math-problems-structure/AGENTS.md

AGENTS.md

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

Run And Test

• Run tests with uv run python -m unittest.
• Compile changed Python files with uv run python -m py_compile <files>.
• Run the usage example with uv run python test-lib.py.
• Run the HTTP server with uv run math-problems-server.
• Open the server docs at http://localhost:8000/docs after starting the server.

Usage example

• from math_problems_structure.grade_1 import join_pictures_with_quantity
• The caller passes image metadata and optional generation settings.
• The function returns a JSON-ready math problem where students count images and match groups to numbers.

Responsibilities

• math_problems_structure/__init__.py and math_problems_structure/grade_1/ expose public library functions.
• math_problems_structure/core/problems/grade_1/ contains reusable generation logic for grade 1 problems.
• math_problems_structure/core/schemas/grade_1/ contains Pydantic request/response models for grade 1 problems.
• math_problems_structure/server/ contains the FastAPI app, CLI, and routes used to test the core library over HTTP.
• tests/ contains direct function tests and server adapter tests.

Design Rules

• Keep generation logic in math_problems_structure/core/problems/.
• Keep all Pydantic models in math_problems_structure/core/schemas/.
• Keep HTTP/server code in math_problems_structure/server/; server routes should call core generators rather than duplicating generation logic.
• Keep public import wrappers in math_problems_structure/grade_*/ small and explicit.
• 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 math_problems_structure/core/schemas/grade_1/example_problem.py.
2. Add generator logic in math_problems_structure/core/problems/grade_1/example_problem.py.
3. Export the function from math_problems_structure/core/problems/grade_1/__init__.py.
4. Export the public function from math_problems_structure/grade_1/__init__.py and math_problems_structure/__init__.py if callers should import it directly.
5. Add a server route in math_problems_structure/server/routes/grade_1.py if the problem should be testable over HTTP.
6. Add direct function tests in tests/ and server route tests when applicable.
7. Run uv run python -m unittest.

For a new grade, follow the same pattern:

1. Add math_problems_structure/core/schemas/grade_2/ and math_problems_structure/core/problems/grade_2/.
2. Add a public wrapper package such as math_problems_structure/grade_2/.
3. Add server routes under math_problems_structure/server/routes/ if HTTP access is needed.
4. Export public functions from the relevant package __init__.py files.
5. Add tests.

Naming Conventions

• 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.