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:

uv sync

Usage

Import and call the problem generator functions directly:

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:

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:

uv run math-problems-server

Open the API docs:

http://localhost:8000/docs

Check health:

curl http://localhost:8000/health

Example request:

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:

uv run python -m unittest

To compile changed Python files:

uv run python -m py_compile <files>