MathyAgent

MathyAgent is a TypeScript monorepo for a structured math-solving agent. It turns text questions or screenshot inputs into validated math solution objects, then renders the result as readable steps, LaTeX, graphs, and verification output in a quiet academic workbench UI.

The project is built around a strict boundary between AI model calls and product rendering: model providers are hidden behind a ModelAdapter, API responses are validated with shared Zod schemas, and the frontend renders structured fields instead of parsing free-form model text.

Highlights

• Structured math contracts for recognized problems, solution steps, final answers, LaTeX blocks, graph specs, and verification results.
• Provider adapter layer for fake, Yunwu-compatible, and DeepSeek-compatible model flows.
• Node http API with endpoints for solving, history lookup, and health checks.
• React 19 + Vite web app with Chinese-first chat workflow, history sidebar, text input, image URL input, and pasted screenshot support.
• KaTeX-backed LaTeX rendering through a dedicated renderer component.
• SVG graph rendering from explicit GraphSpec data, including 2D and 3D structured graph contracts.
• File-backed local solve history for development without introducing a database dependency.
• Vitest coverage across shared schemas, API behavior, adapters, repositories, and frontend rendering.

Tech Stack

• TypeScript monorepo with npm workspaces
• React 19, Vite, and global CSS
• Node.js http API server
• Zod shared validation schemas
• Vitest and jsdom for testing
• KaTeX for LaTeX rendering

Repository Layout

apps/web/            React frontend
services/api/        HTTP API, solver orchestration, repositories, adapters
packages/shared/     Shared contracts, schemas, and adapter interfaces
docs/                Architecture notes

Architecture

flowchart LR
  User["User input: text or screenshot"] --> Web["apps/web"]
  Web --> Api["services/api"]
  Api --> Solver["SolveOrchestrator"]
  Solver --> Adapter["ModelAdapter"]
  Adapter --> Provider["AI provider"]
  Solver --> Repository["SolveRepository"]
  Api --> Web
  Web --> Latex["LatexBlockView"]
  Web --> Graph["GraphSpecView"]
  Web --> Verify["VerificationPanel"]

Loading

Key design rules:

• AI provider calls go through ModelAdapter.
• Route handlers and frontend code never call providers directly.
• Every solve result includes a VerificationResult.
• LaTeX is represented as LatexBlock with displayMode: true.
• Graphs are represented as GraphSpec; the frontend does not infer graphs from prose.
• Shared Zod schemas validate adapter output before it reaches the UI.

Getting Started

Prerequisites

• Node.js 20 or newer
• npm 10 or newer

Install

npm install

Configure Environment

Create a local .env from the example file:

cp .env.example .env

The default configuration uses the fake provider and does not require an API key:

MODEL_PROVIDER=fake
PORT=3001

For a real provider, set MODEL_PROVIDER, MODEL_NAME, MODEL_BASE_URL, and the matching API key in .env. Do not commit real secrets.

Run

Start the API:

npm run dev:api

Start the web app in another terminal:

npm run dev:web

By default:

• API: http://127.0.0.1:3001
• Web: http://127.0.0.1:5173

Scripts

npm run typecheck
npm test
npm run build

Workspace-specific scripts are also available:

npm run dev -w @mathyagent/api
npm run dev -w @mathyagent/web

API Overview

GET /health

Returns service status.

POST /api/solve

Solves a math problem from recognized text or an image URL.

{
  "uploadId": "upload_123",
  "recognizedText": "解方程：x + 1 = 2",
  "locale": "zh-CN"
}

The response is a validated SolveResult containing:

• problem: recognized and normalized problem fields
• solution: summary, ordered steps, final answer, LaTeX blocks, and graph specs
• verification: verification status, confidence, checks, and issues

GET /api/solve/:id

Returns a previous solve result by ID.

GET /api/history

Returns locally persisted solve history.

Development Notes

• Durable contracts belong in packages/shared.
• Math renderers belong in apps/web/src/components/math.
• Solver workflow belongs in services/api/src/services/solver.
• Provider-specific code belongs in services/api/src/model-adapters.
• Local history is written to .mathyagent/ and is intentionally ignored by Git.

Security

• Never commit .env or provider keys.
• Keep model prompts and adapter responses server-side.
• Do not expose provider keys to frontend code.
• Validate provider responses with shared schemas before returning them to clients.

Project Status

MathyAgent is an MVP-stage structured math-agent workbench. The current implementation prioritizes clean contracts, safe provider boundaries, deterministic rendering, and a runnable local development loop.

License

Released under the MIT License. See LICENSE for details.