# 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`.