feat: create structure for the project and first problem

AGENTS.md

@@ -0,0 +1,62 @@
+# 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.
+
+## Naming Conventions
+
+- Endpoint paths use the existing style: `/math/1_grade/<problem_name>`.
+- Python package names should use valid identifiers like `grade_1`, not `1_grade`.
+- 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`.