| # 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. |
|
|
