Uncooked

Study platform for Cambridge International A Level Mathematics (syllabus 9709). Past papers get sliced into per-question images, Google Gemini tags each question with a syllabus topic, difficulty band, and a worked explanation, and a Vite + React frontend at uncooked.works serves them up for revision.

What's in the repo

• main.py FastAPI job that walks a folder of question papers (9709_<session><year>_qp_<component><paper>.pdf), renders each page to PNG with PyMuPDF, uploads the images to a Supabase Storage bucket, and inserts a row per question into the alevel_math_questions table.
• mark_sc.py sibling job for mark scheme PDFs (9709_<session><year>_ms_<component><paper>.pdf). Each mark-scheme page is matched back to its question number and pushed into that row's answer_img array.
• ai.py batch worker that pulls rows without an ai_explanation, groups them by syllabus component (Pure 1, Pure 3, Mechanics, Stats 1, Stats 2), and streams the images through a single Gemini 1.5 Flash chat session per component so the tutor persona stays consistent. Fills in topic, difficulty, and ai_explanation, and deletes rows the model flags as "extra page" filler. Prints a running cost estimate as it goes.
• frontend/ Vite + React + shadcn/ui app deployed at uncooked.works. Uses Supabase for data and Auth0 for authentication.
• papers/ local drop folder for the source PDFs.

Setup

Backend jobs (Python 3.11+):

python -m venv .venv
source .venv/bin/activate
pip install fastapi uvicorn pymupdf requests python-dotenv google-generativeai

Backend .env:

SUPABASE_URL=...
SUPABASE_KEY=...                 # service role key
BUCKET_NAME=...                  # question-image bucket
MARK_SCHEME_BUCKET_NAME=...      # mark-scheme bucket
GEMINI_API_KEY=...

Frontend:

cd frontend
npm install
npm run dev

Running the pipeline

1. Drop question papers into papers/ using the Cambridge naming scheme.
2. Start the FastAPI host: uvicorn main:app --reload.
3. Hit GET /upload-all to slice, upload, and index every PDF into Supabase.
4. Drop mark schemes into the answers folder and hit /upload-mark-scheme (or run mark_sc.py) to attach answer images to the matching rows.
5. Run python ai.py to fill in AI explanations for any un-tagged rows.

Data model

Each question ends up as one row in alevel_math_questions with: question_number, paper_code, paper_year, session, component, question_img[], answer_img[], topic, difficulty, ai_explanation.