104 lines
2.8 KiB
Markdown
104 lines
2.8 KiB
Markdown
# math-problems-structure
|
|
|
|
This repository provides a Python library for generating structured math problems, ranging from graphical exercises to text-based ones.
|
|
|
|
The importable Python package is `math_problems_structure`. The project name uses hyphens (`math-problems-structure`), but Python imports use underscores.
|
|
|
|
## Installation
|
|
|
|
This project uses `uv` for dependency management. To set up the environment, run the following command in your terminal:
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
## Usage
|
|
|
|
Import and call the problem generator functions directly:
|
|
|
|
```python
|
|
from math_problems_structure.grade_1 import join_pictures_with_quantity
|
|
|
|
problem = join_pictures_with_quantity(
|
|
available_pictures=[
|
|
{"id": f"picture-{index}", "name": f"Picture {index}", "image_path": f"/images/{index}.png"}
|
|
for index in range(10)
|
|
],
|
|
seed=1,
|
|
)
|
|
```
|
|
|
|
The public grade-level imports are thin wrappers around the core library code in `math_problems_structure/core/`.
|
|
|
|
You can also run the included example script:
|
|
|
|
```bash
|
|
uv run python test-lib.py
|
|
```
|
|
|
|
## Server
|
|
|
|
The repository also includes a small FastAPI server for testing the core library over HTTP.
|
|
|
|
Start the server:
|
|
|
|
```bash
|
|
uv run math-problems-server
|
|
```
|
|
|
|
Open the API docs:
|
|
|
|
```text
|
|
http://localhost:8000/docs
|
|
```
|
|
|
|
Check health:
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
```
|
|
|
|
Example request:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8000/grade-1/join-pictures-with-quantity \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"available_pictures": [
|
|
{"id": "picture-0", "name": "Picture 0", "image_path": "/images/0.png"},
|
|
{"id": "picture-1", "name": "Picture 1", "image_path": "/images/1.png"},
|
|
{"id": "picture-2", "name": "Picture 2", "image_path": "/images/2.png"},
|
|
{"id": "picture-3", "name": "Picture 3", "image_path": "/images/3.png"},
|
|
{"id": "picture-4", "name": "Picture 4", "image_path": "/images/4.png"},
|
|
{"id": "picture-5", "name": "Picture 5", "image_path": "/images/5.png"},
|
|
{"id": "picture-6", "name": "Picture 6", "image_path": "/images/6.png"},
|
|
{"id": "picture-7", "name": "Picture 7", "image_path": "/images/7.png"},
|
|
{"id": "picture-8", "name": "Picture 8", "image_path": "/images/8.png"},
|
|
{"id": "picture-9", "name": "Picture 9", "image_path": "/images/9.png"}
|
|
],
|
|
"seed": 1
|
|
}'
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
- `math_problems_structure/core/problems/` contains reusable problem generation logic.
|
|
- `math_problems_structure/core/schemas/` contains Pydantic request and response models.
|
|
- `math_problems_structure/grade_1/` exposes the public grade 1 library functions.
|
|
- `math_problems_structure/server/` contains the FastAPI server adapter.
|
|
- `tests/` contains function and server tests.
|
|
|
|
## Test
|
|
|
|
To run the tests, use the following command:
|
|
|
|
```bash
|
|
uv run python -m unittest
|
|
```
|
|
|
|
To compile changed Python files:
|
|
|
|
```bash
|
|
uv run python -m py_compile <files>
|
|
```
|