refactor: implement core and server dir to split the library and endpoints for testing

README.md

@@ -2,6 +2,8 @@
 
 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:
@@ -26,13 +28,65 @@ problem = join_pictures_with_quantity(
 )
 ```
 
+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.py
+uv run python test-lib.py
 ```
 
-Each grade has its `images_for_reference` folder, which contains the images that were used to create the structure of the problems.
+## 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
 
@@ -41,3 +95,9 @@ 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>
+```