62 lines
3.2 KiB
Markdown
62 lines
3.2 KiB
Markdown
# 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`.
|