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

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

• app/__init__.py exposes the public library functions.
• 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 direct function tests.

Design Rules

• Keep generation logic in app/problems/.
• Keep all Pydantic models in app/schemas/.
• 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. Export the function from app/problems/grade_1/__init__.py and app/__init__.py if it is public.
4. Add direct function 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. Export public functions from the relevant package __init__.py files.
3. 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.