math-problems-structure/AGENTS.md

AGENTS.md

This project is a FastAPI backend for generating structured math problems. The intended design should scale to grades 1 through 6 and multiple problem types per grade.

Run And Test

• Start the API with uv run uvicorn main:app --reload.
• Open API docs at http://127.0.0.1:8000/docs.
• Run tests with uv run python -m unittest.
• Compile changed Python files with uv run python -m py_compile <files>.

Endpoint example

• POST /math/grade_1/join_pictures_with_quantity
• The caller sends image metadata and optional generation settings.
• The endpoint returns a JSON-ready math problem where students count images and match groups to numbers.

Responsibilities

• main.py is only the uvicorn entry point. Keep it thin.
• app/main.py defines create_app() and includes the top-level API router.
• app/routers/math.py owns the /math router and includes grade routers.
• app/routers/grade_1.py registers all grade 1 HTTP endpoints.
• app/problems/grade_1/ contains reusable generation logic for grade 1 problems.
• app/schemas/grade_1/ contains Pydantic request/response models for grade 1 problems.
• tests/ contains endpoint tests using fastapi.testclient.TestClient.

Design Rules

• Keep HTTP code in app/routers/.
• Keep generation logic in app/problems/.
• Keep all Pydantic models in app/schemas/.
• Do not put generation logic in routers.
• Do not put FastAPI router code in problem generator modules.
• Prefer one router file per grade, not one router file per problem.
• Prefer one schema file per problem type.
• Prefer one generator file per problem type.

Adding A New Problem Type

For a new grade 1 problem named example_problem:

1. Add schemas in app/schemas/grade_1/example_problem.py.
2. Add generator logic in app/problems/grade_1/example_problem.py.
3. Register the endpoint in app/routers/grade_1.py.
4. Add endpoint tests in tests/.
5. Run uv run python -m unittest.

For a new grade, follow the same pattern:

1. Add app/schemas/grade_2/ and app/problems/grade_2/.
2. Add app/routers/grade_2.py.
3. Include the new grade router from app/routers/math.py.
4. Add tests.

Every time you add a new problem, also add an endpoint curl example on the ENDPOINTS-EXAMPLE.md file.

Naming Conventions

• Endpoint paths use the existing style: /math/grade_1/<problem_name>.
• Python package names should use valid identifiers like grade_1.
• Problem files should use snake case, for example join_pictures_with_quantity.py.
• Request schema names should end in Request.
• Response schema names should describe the generated problem, for example JoinPicturesWithQuantityProblem.