# TutorDesk AI — Implementation Plan

Build plan for the Build Small Hackathon (deadline **June 15, 2026**). Track progress in
`progress.md`; product rationale in `PRD.md`.

## Guiding principles

- **Demo-first:** every phase should move the end-to-end demo forward.
- **Reuse over build:** NCERT_Dataset + pretrained models do most of the work.
- **Narrow scope:** Classes 6–10, Math + Science, CBSE/NCERT, English (+ Hindi slice).
- **Badges are cheap multipliers** — bake them into the architecture, don't bolt on later.

---

## Architecture (decided 2026-06-11)

Laptop can't hold the models → **all models self-hosted on Modal** as scale-to-zero GPU
functions (`serving/modal_app.py`). The **HF Space = thin Gradio UI** calling Modal by name.
No external APIs. Models: MiniCPM-V 4.5 (8B), fine-tuned Qwen3-4B, **Tiny Aya
`CohereLabs/tiny-aya-fire` (3.35B)**, FLUX.1-schnell — total ≈27B.

## Phase 0 — Project setup

- Repo scaffolding per CLAUDE.md structure; `requirements.txt`; `.env.example`.
- HF account + empty **Space**; **Modal account + CLI auth** (`modal token set`).
- `serving/modal_app.py` skeleton: one scale-to-zero function per model.

**Exit:** `app.py` shows a "hello" Gradio app live on the Space; `modal deploy` succeeds.

---

## Phase 1 — Core text generation (no fine-tune yet)

Get the product working with the **base** Qwen3-4B so UI/pipelines aren't blocked on training.

- `serving/modal_app.py::Qwen` — load base Qwen3-4B on Modal; `models/qwen.py` calls it.
- `agents/` — implement the 5 agents (curriculum, question_gen, difficulty, answer, report)
  as prompt-driven functions over Qwen.
- `pipelines/weekly_pack.py` — orchestrate the 5 agents → worksheet+homework+quiz+key+note.
- `utils/pdf.py` — print-ready PDF export.

**Exit:** **Feature 2 (Weekly Teaching Pack)** works end-to-end from text inputs → PDF.

---

## Phase 2 — Vision (Feature 1)

- `serving/modal_app.py::MiniCPM` — load MiniCPM-V 4.5 on Modal (4.6 fallback flag).
- `pipelines/worksheet_from_textbook.py` — image/PDF → extracted topic/concepts → feed
  Phase 1 pipeline.
- `utils/image.py` — PDF page rasterization, basic preprocessing.

**Exit:** **Feature 1** works — photograph a chapter → worksheet+quiz+key.

---

## Phase 3 — Dataset + fine-tune on Modal (Well-Tuned / Tiny Titan / Modal)

- `data/prep_generation.py` — NCERT_Dataset → ChatML JSONL (objective ① generation).
- `data/prep_difficulty.py` — NCERT `Difficulty` column → ChatML (objective ② classify).
- `data/prep_grading.py` — synthesize marking-scheme + simulated-student-answer + marks
  triples (objective ③ grading); ~1–2k rows.
- `finetune/train_modal.py` — LoRA SFT of Qwen3-4B on Modal; merge + export GGUF.
- **Publish the fine-tuned model to the HF Hub** (claims Well-Tuned).

**Exit:** Fine-tuned Qwen3-4B published; swapped into the pipelines; ~6–8k training examples.

---

## Phase 4 — Photo Auto-Grading (Feature 5)

- `pipelines/auto_grade.py` — MiniCPM-V reads answer sheet → fine-tuned Qwen3-4B grades
  against marking scheme → marks + per-step breakdown + auto-drafted parent note.

**Exit:** **Feature 5** works on neat/printed answer sheets.

---

## Phase 5 — Multilingual (Cohere) + Diagrams (FLUX)

- `serving/modal_app.py::TinyAya` — host `CohereLabs/tiny-aya-fire`; language selector on
  every output (Feature 3).
- `serving/modal_app.py::Flux` — host FLUX.1-schnell; diagrams embedded in worksheet PDFs
  (Feature 4).
- Graceful fallback when offline (English-only / no images).

**Exit:** **Features 3 & 4** work; sponsor claims for Cohere + BFL satisfied.

---

## Phase 6 — Badge layer & polish

- **Off the Grid / Llama Champion:** local mode — MiniCPM-V + Qwen3-4B via llama.cpp, toggle
  to disable all cloud calls.
- **Sharing is Caring:** `traces/` — capture agent traces → publish HF dataset.
- **Off-Brand:** custom `gr.Server` frontend, mobile-first polish.
- **Field Notes:** build/report blog post.

**Exit:** all badges claimable; app polished.

---

## Phase 7 — Submission

- Record **demo video** (90-min → 10-min teacher story).
- **Social post.** Final Space deploy + README with sponsor/badge checklist.
- Submit before **June 15, 2026**.

---

## Sponsor / award coverage (target)

| Claim | Phase |
|---|---|
| OpenBMB ($10k) — MiniCPM-V | 2, 4 |
| Modal ($20k credits) — training job | 3 |
| Cohere ($5k) — Aya | 5 |
| Black Forest Labs ($3k) — FLUX | 5 |
| Best Agent ($1k) — 5-agent pipeline | 1 |
| Well-Tuned + Tiny Titan ($1.5k) — published 4B fine-tune | 3 |
| Sharing is Caring — agent traces dataset | 6 |
| Off the Grid + Llama Champion — local mode | 6 |
| Off-Brand ($1.5k) — gr.Server | 6 |
| Best Demo ($1k) + Field Notes | 6, 7 |

## Risks / watch-items

- **Handwriting OCR** unreliable → demo with printed answers; roadmap item.
- **Laptop memory** for 8B + 4B → use GGUF/quantized; lazy-load models.
- **NCERT subject coverage** may skew → verify collection, supplement if thin.
- **Time:** if behind, Phases 1–4 are the must-win core; 5–6 are sponsor add-ons.