| # Session Handoff — Kasualdad LFED Build |
|
|
| > **Last updated:** 2026-06-06 (Session 2 — Phases 1-8 complete) |
| > **Deadline:** 2026-06-15 (HF Build Small Hackathon — "Backyard AI" chapter) |
| > **Project root:** `/Users/flucido/projects/build-small-hackathon/Kasualdad_LFED` |
| > **Original reference project:** `/Users/flucido/projects/Kasualdad_LFED` (untouched snapshot) |
| > **Reference project:** `/Users/flucido/projects/local-data-stack` (education data stack patterns) |
|
|
| --- |
|
|
| ## TL;DR — How to Resume in 30 Seconds |
|
|
| ```bash |
| cd /Users/flucido/projects/build-small-hackathon/Kasualdad_LFED |
| source .venv/bin/activate |
| python -c "import gradio, duckdb, llama_cpp, huggingface_hub; print('env OK')" |
| |
| # Run the app |
| python app.py |
| |
| # Run tests |
| pytest tests/ -v |
| |
| # Kick off Modal fine-tuning (after setting HF_TOKEN secret) |
| modal run modal_train/modal_app.py |
| ``` |
|
|
| Full plan is in [`docs/PLAN.md`](./PLAN.md). |
|
|
| --- |
|
|
| ## Project Summary |
|
|
| **Kasualdad LFED** = a Hugging Face Space that turns natural-language questions from school district admins (principals, superintendents, department heads) into safe DuckDB SQL via a small local LLM (llama.cpp, GGUF format). Targets HF "Build Small" Hackathon badges: |
|
|
| - **Off the Grid** — all inference local, no API calls |
| - **Well-Tuned** — Modal fine-tune of a small text-to-SQL model pushed to Hub |
| - **Llama Champion** — llama.cpp as inference backend |
| - **Off-Brand** — custom CSS targeting cognitive-load reduction (added in second iteration) |
|
|
| User's success criteria: **win the hackathon** + have a **demoable slice for clients/employers**. |
|
|
| --- |
|
|
| ## Decisions Locked (do not re-litigate) |
|
|
| | Decision | Value | Source | |
| |---|---|---| |
| | Project location | `~/projects/build-small-hackathon/Kasualdad_LFED` | User: "this is where the hackathon is happening" | |
| | Source of truth | Copy of `~/projects/Kasualdad_LFED` | User choice (Recommended) | |
| | Python version | 3.12 (local + Space) | User: "ok to recreate" | |
| | Base model | `Qwen2.5-Coder-7B-Instruct` Q4_K_M | Plan, **7/7 sanity check passed** | |
| | Alt model (fallback) | `Llama-3.1-8B-Instruct` Q4_K_M | Plan (only if Qwen fails sanity) | |
| | Quantization | Q4_K_M (~4.4 GB) | Plan: speed/accuracy tradeoff for free Space | |
| | Code layout | Modular: `app.py` / `data_engine.py` / `model_inference.py` / `prompts.py` | User choice (Recommended) | |
| | Data source | Seed tables only for hackathon | User choice (Recommended) | |
| | Aesthetic | Linear / Vercel style, minimal monochrome + teal accent | User choice (Recommended) | |
| | Accent color | `#14b8a6` (teal) | User choice (Recommended) | |
| | Modal timing | Start fine-tune ASAP, end-to-end | User choice (Recommended) | |
| | Modal account | `flucido` | User | |
| | Modal credits | Hackathon-provided, confirmed | User | |
| | Custom CSS | **Yes** (reinstated after user feedback) | User: "i wnat the design to llook good" | |
|
|
| --- |
|
|
| ## Current State (as of session 2 — Phases 1-8 complete) |
|
|
| ### ✅ Completed |
| - **Phase 0: Bootstrap** — venv, pinned deps, packages.txt |
| - **Phase 1: Model sanity check** — Qwen2.5-Coder-7B Q4_K_M: **7/7 prompts passed**, model locked |
| - **Phase 2: Refactor** — modular codebase (`app.py`, `data_engine.py`, `model_inference.py`, `prompts.py`) |
| - **Phase 3: Robustness** — JSON envelope parsing, schema-aware column validation (EXPLAIN), threading timeout via `conn.interrupt()`, per-request DB connections, streaming SQL generation |
| - **Phase 4: Seed data** — `data/generate_seed.py`: 5 schools × 4 years × 13 grades, 2,900 students, 15% chronic rate |
| - **Phase 5: UI polish** — Off-Brand CSS (Inter + JetBrains Mono, teal accent, WCAG AA, prefers-reduced-motion, focus rings), README design docs |
| - **Phase 6: Tests** — **81 tests, 0 failures** (execution guard, data engine, model inference with mocked LLM) |
| - **Phase 7: Modal pipeline** — `modal_train/`: synthetic data generator (1,289 pairs, 32 templates), Unsloth QLoRA train.py, GGUF export, Modal orchestration |
| - **Phase 8: README** — expanded with badges, Mermaid architecture diagram, schema docs, run guide, project structure |
|
|
| ### 🟡 In Progress |
| - Nothing in progress |
|
|
| ### ⏳ Pending |
| - Phase 7b: Actually run Modal training (user needs to create HF_TOKEN secret and `modal run`) |
| - Phase 7c: Swap `REPO_ID` in `model_inference.py` after GGUF is pushed |
| - Phase 9: Deploy to HF Space + smoke test |
| - Phase 10–11: Buffer + polish + submit |
| |
| --- |
| |
| ## File Tree (Current — post Phase 8) |
| |
| ``` |
| ~/projects/build-small-hackathon/Kasualdad_LFED/ |
| ├── .venv/ # Python 3.12.8 |
| ├── app.py # Gradio UI + Off-Brand CSS (354 lines) |
| ├── data_engine.py # DuckDB lifecycle, execution guard, timeout (310 lines) |
| ├── model_inference.py # llama.cpp wrapper, streaming (211 lines) |
| ├── prompts.py # System prompt, schema docs, few-shot (131 lines) |
| ├── data/ |
| │ └── generate_seed.py # 5 schools × 4 years seed generator |
| ├── tests/ |
| │ ├── conftest.py # Shared fixtures |
| │ ├── test_execution_guard.py # 24 tests — SQL injection, validation |
| │ ├── test_data_engine.py # 23 tests — schema, isolation, integrity |
| │ └── test_model_inference.py # 24 tests — prompt assembly, mock LLM |
| ├── modal_train/ |
| │ ├── generate_synthetic.py # 1,289 NL→SQL training pairs |
| │ ├── train.py # Unsloth QLoRA recipe |
| │ ├── export_gguf.py # Merge → GGUF → HF Hub |
| │ ├── modal_app.py # Modal orchestration |
| │ └── train.jsonl # Training data (1,289 pairs) |
| ├── docs/ |
| │ ├── HANDOFF.md # this file |
| │ └── PLAN.md # full plan |
| ├── requirements.txt # PINNED (4 deps) |
| ├── packages.txt # System deps for HF Space |
| └── README.md # Expanded (badges, mermaid, schema, run guide) |
| |
| # External artifacts: |
| /tmp/lfed-models/qwen/Qwen2.5-Coder-7B-Instruct.Q4_K_M.gguf # 4.4 GB, ready |
| ``` |
| |
| --- |
| |
| ## Quick-Reference: Commands to Know |
| |
| ### Activate environment |
| ```bash |
| cd /Users/flucido/projects/build-small-hackathon/Kasualdad_LFED |
| source .venv/bin/activate |
| ``` |
| |
| ### Test all imports |
| ```bash |
| python -c "import gradio, duckdb, llama_cpp, huggingface_hub; print('env OK')" |
| ``` |
| |
| ### Run the app locally |
| ```bash |
| python app.py |
| # → http://localhost:7860 |
| ``` |
| |
| ### Run pytest (Phase 6+) |
| ```bash |
| pytest tests/ -v |
| ``` |
| |
| ### Modal CLI (Phase 7+) |
| ```bash |
| modal --version # verify install |
| modal secret list # list secrets |
| modal run modal_train/modal_app.py # kick off training |
| ``` |
| |
| --- |
| |
| ## Outstanding Dependencies |
| |
| | When | Dependency | Status | |
| |---|---|---| |
| | Now | `modal secret create huggingface HF_TOKEN=<token>` | ⏳ User action | |
| | After training | Swap `REPO_ID` in `model_inference.py` to the fine-tuned GGUF repo | ⏳ After Phase 7c | |
| |
| --- |
| |
| ## 9-Day Schedule (Updated) |
| |
| | Day | Date | Phases | Status | |
| |---|---|---|---| |
| | 1 | Jun 6 | 0 · 1 · 2 · 3 · 4 · 5 · 6 · 7 · 8 | ✅ **Done** (all 8 phases in one session) | |
| | 3 | Jun 8 | 7b: Modal training (3-6 hrs overnight on A10G) | ⏳ User action needed | |
| | 4 | Jun 9 | 7c: merge → GGUF → push → swap REPO_ID | ⏳ After training | |
| | 5–6 | Jun 10–11 | 9: Deploy to HF Space + smoke test | ⏳ | |
| | 7–8 | Jun 12–13 | Buffer: polish, re-iterate | ⏳ | |
| | 9 | Jun 14 | Final verify + submit | **Submit** | |
| |
| **Next action**: User creates Modal HF_TOKEN secret, then `modal run modal_train/modal_app.py`. |
| |
| --- |
| |
| ## Reference |
| |
| - Full plan: [`docs/PLAN.md`](./PLAN.md) |
| - HF Build Small Hackathon (track: Backyard AI): submission deadline 2026-06-15 |
| - Modal: https://modal.com/apps/flucido/main (credits: hackathon-provided) |
| - HF Hub: fine-tuned GGUF repo (TBD — see Modal export script) |
| |
