Final Submission

.gitignore

@@ -42,6 +42,12 @@ tmp/
 .venv/
 venv/
 
+# Remotion video project
+video/node_modules/
+video/out/
+
 # Local diagnostic logs
 samples/diag_*_out*.txt
 *.png
+*.mp4
+video/

README.md

@@ -34,7 +34,10 @@ tags:
 
 *Find where money is being lost — in under 60 seconds*
 
-[![HF Space](https://img.shields.io/badge/🤗%20Space-Kirana%20Detective-blue)](https://huggingface.co/spaces/build-small-hackathon/kirana-detective)
+[![Try It Live](https://img.shields.io/badge/🤗%20Try%20It-Live%20Demo-blue)](https://huggingface.co/spaces/build-small-hackathon/kirana-detective)
+[![Watch Demo](https://img.shields.io/badge/▶%20Watch-Demo-red)](https://youtu.be/8TVZP4sfesI)
+[![Blog Post](https://img.shields.io/badge/📝%20Blog-How%20I%20Built%20It-orange)](https://huggingface.co/blog/build-small-hackathon/kirana-detective)
+[![X Post](https://img.shields.io/badge/𝕏-View%20Post-black)](https://x.com/naazimhussain02/status/2065966381657633161)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Python 3.11](https://img.shields.io/badge/Python-3.11-blue.svg)](https://python.org)
 [![Training: Modal](https://img.shields.io/badge/Training-Modal%20A10G-orange)](https://modal.com)
@@ -113,7 +116,7 @@ Agent 6 — MiniCPM5-1B generates rupee savings report + action items
 └──────────────────────────────────┘
 ```
 
-Every agent run is traced and logged for the **Sharing is Caring** badge.
+Every agent run is stored locally in SQLite for audit history.
 
 ---
 
@@ -225,27 +228,18 @@ Comfortably within the **Tiny Titan** ≤4B threshold. Zero cloud API calls —
 | 🔌 Off the Grid | 100% local inference — MiniCPM-V (transformers) + MiniCPM5-1B (GGUF) + YOLO26n (ONNX) |
 | 🦙 Llama Champion | MiniCPM5-1B served via llama-cpp-python (GGUF Q4_K_M) |
 | 🎨 Off-Brand | Custom Gradio UI — rupee savings cards, colour-coded anomaly flags |
-| 📡 Sharing is Caring | Two public trace datasets: runtime audit traces per run + full Claude Code build sessions |
+| 📡 Sharing is Caring | Claude Code build sessions (11 JSONL sessions) published as a public trace dataset |
 | 📓 Field Notes | *"How I built an AI auditor for India's 12 million kirana stores"* |
 | 🏋️ Tiny Titan | ~2.38B total parameters — OCR + normalization + counting + report |
 
 ---
 
-## Sharing is Caring — Trace Datasets
-
-Two public datasets document everything that happened in this project:
-
-### 1. Runtime Audit Traces — `build-small-hackathon/kirana-detective-traces`
-
-Published automatically after every invoice audit run by [`tracer.py`](tracer.py). Each file records one complete pipeline execution — all six agents, inputs, outputs, and timings.
-
-### 2. Claude Code Build Sessions — `build-small-hackathon/kirana-detective-build-traces`
+## Sharing is Caring — Build Trace Dataset
 
 The 11 raw Claude Code (Sonnet 4.6) JSONL sessions used to design, code, debug, and document this entire project — from blank repo to hackathon submission. Viewable in HF Data Studio's native agent trace viewer.
 
 | Dataset | Contents | Format |
 |---|---|---|
-| [`build-small-hackathon/kirana-detective-traces`](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-traces) | Per-audit runtime traces (6 agents per run) | JSONL, auto-published by app |
 | [`build-small-hackathon/kirana-detective-build-traces`](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-build-traces) | 11 Claude Code build sessions · ~8.9 MB | Native JSONL trace viewer |
 
 To upload build traces:
@@ -297,9 +291,7 @@ kirana-detective/
 - **Product normalizer**: [build-small-hackathon/minicpm5-1b-indian-fmcg-normalizer](https://huggingface.co/build-small-hackathon/minicpm5-1b-indian-fmcg-normalizer)
 - **Product detector**: [build-small-hackathon/yolo26n-indian-fmcg-detection](https://huggingface.co/build-small-hackathon/yolo26n-indian-fmcg-detection)
 - **Full model card**: [MODEL_CARD.md](MODEL_CARD.md)
-- **Runtime audit traces**: [build-small-hackathon/kirana-detective-traces](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-traces)
 - **Build sessions (Claude Code)**: [build-small-hackathon/kirana-detective-build-traces](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-build-traces)
-- **PRD**: [docs/kirana-detective-prd.md](docs/kirana-detective-prd.md)
 
 ---
 

SUBMISSION.md

@@ -0,0 +1,171 @@
+# Kirana Detective — Hackathon Submission
+
+**HuggingFace Build Small Hackathon 2026**
+
+| | |
+|---|---|
+| **Space** | [build-small-hackathon/kirana-detective](https://huggingface.co/spaces/build-small-hackathon/kirana-detective) |
+| **Demo Video** | [YouTube](https://youtu.be/8TVZP4sfesI) |
+| **Blog Post** | [How I Built an AI Auditor for India's 12 Million Kirana Stores](https://huggingface.co/blog/build-small-hackathon/kirana-detective) |
+| **Social Post** | [X / Twitter](https://x.com/naazimhussain02/status/2065966381657633161) |
+| **Track** | Track 1: Backyard AI |
+| **Total Parameters** | ~2.38B (Tiny Titan ✅) |
+
+---
+
+## Track: Backyard AI
+
+**Problem**: India's 12 million kirana store owners receive 3–5 distributor invoices per week via WhatsApp, printed bills, or Tally exports. Manual verification is impossible. Distributors overcharge, deliver short quantities, and apply wrong GST rates. A single store loses ₹3,000–₹8,000 per month silently.
+
+**Solution**: Upload an invoice + delivery photos → receive a ₹ leakage report in under 60 seconds. Every finding (overcharge, shortage, GST error, duplicate) maps to a rupee amount and an action step.
+
+**Real user**: Tested against real invoice formats from kirana distributors in India (HUL, ITC, Nestlé, Britannia).
+
+**Model constraint fit**: Entire pipeline runs on CPU — no GPU required at inference. Designed for Tier 2/3 city deployment where GPU hardware is absent and internet is patchy.
+
+---
+
+## Merit Badges
+
+### ✅ Off the Grid
+Zero cloud API calls. All inference runs locally:
+- MiniCPM-V 4.6 via `transformers` (merged bfloat16 weights)
+- MiniCPM5-1B via `llama-cpp-python` (GGUF Q4_K_M)
+- YOLO26n via ONNX Runtime
+
+Invoice data never leaves the device. Suitable for privacy-sensitive business data.
+
+### ✅ Well-Tuned
+Three custom models fine-tuned from scratch and published on HF Hub:
+
+| Model | Repo | Task |
+|---|---|---|
+| MiniCPM-V 4.6 | [`build-small-hackathon/minicpm-v-4-6-indian-invoice-extraction-merged`](https://huggingface.co/build-small-hackathon/minicpm-v-4-6-indian-invoice-extraction-merged) | Invoice OCR → structured JSON |
+| MiniCPM5-1B | [`build-small-hackathon/minicpm5-1b-indian-fmcg-normalizer`](https://huggingface.co/build-small-hackathon/minicpm5-1b-indian-fmcg-normalizer) | Product name normalisation + savings report |
+| YOLO26n | [`build-small-hackathon/yolo26n-indian-fmcg-detection`](https://huggingface.co/build-small-hackathon/yolo26n-indian-fmcg-detection) | Product counting from delivery photos |
+
+Training dataset: [`build-small-hackathon/kirana-invoice-train-data`](https://huggingface.co/datasets/build-small-hackathon/kirana-invoice-train-data) — 500 synthetic Indian invoices (printed GST, Tally PDF, handwritten, WhatsApp).
+
+### ✅ Off-Brand
+Custom Gradio UI — not default Gradio. Features:
+- Rupee savings cards with colour-coded anomaly type (overcharge = red, shortage = amber, duplicate = purple, GST = orange)
+- Agent progress stream with per-agent timing
+- Collapsible raw JSON view per agent
+- Dark/warm colour scheme themed around the kirana store context
+
+### ✅ Llama Champion
+MiniCPM5-1B is served entirely via `llama-cpp-python` using a GGUF Q4_K_M quantised model. Used for both Agent 2 (product normalisation) and Agent 6 (savings report generation). No transformers at runtime for these two agents — pure llama.cpp.
+
+### ✅ Sharing is Caring
+11 raw Claude Code (Sonnet 4.6) JSONL build sessions published as a public trace dataset, viewable in HF Data Studio's native agent trace viewer:
+
+[`build-small-hackathon/kirana-detective-build-traces`](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-build-traces) — complete design, coding, debugging, and documentation sessions from blank repo to submission.
+
+### ✅ Field Notes
+Full blog post: [How I Built an AI Auditor for India's 12 Million Kirana Stores](https://huggingface.co/blog/build-small-hackathon/kirana-detective)
+
+Covers: the problem, the 6-agent pipeline design, all three fine-tuned models with training details, the local-inference rationale, the hardest bug, and the full stack.
+
+---
+
+## Prize Categories Targeted
+
+### Special Awards
+
+**🏋️ Tiny Titan** — ~2.38B total parameters across all three models combined.
+
+| Component | Parameters |
+|---|---|
+| MiniCPM-V 4.6 (merged bfloat16) | ~1.3B |
+| MiniCPM5-1B (GGUF Q4_K_M) | ~1.08B |
+| YOLO26n (ONNX) | ~2.4M |
+| **Total** | **~2.38B** |
+
+Well within the ≤4B Tiny Titan threshold.
+
+**🤖 Best Agent** — Fully modular 6-agent pipeline. Each agent has a single responsibility, a defined input/output contract, and produces an `AgentTraceEntry` with timing. Generator-based streaming shows live agent progress in the UI.
+
+**🎨 Off-Brand** — Custom Gradio UI with rupee savings cards, colour-coded anomaly flags, and agent-by-agent progress stream. Distinctly different from the default Gradio look.
+
+**📊 Best Demo** — End-to-end demo covering: invoice upload → extraction → normalisation → price check → delivery photo counting → shortage reconciliation → ₹ savings report with action items.
+
+**🎖️ Bonus Quest Champion** — All 6 merit badges claimed on a single submission:
+
+| # | Badge | Evidence |
+|---|---|---|
+| 1 | Off the Grid | Zero cloud API calls — MiniCPM-V (transformers) + MiniCPM5-1B (llama.cpp) + YOLO26n (ONNX), all CPU |
+| 2 | Well-Tuned | 3 custom fine-tuned models published on HF Hub (MiniCPM-V 4.6, MiniCPM5-1B, YOLO26n) |
+| 3 | Off-Brand | Custom Gradio UI — rupee savings cards, colour-coded anomaly flags, per-agent streaming progress |
+| 4 | Llama Champion | MiniCPM5-1B served via llama-cpp-python (GGUF Q4_K_M) for both Agent 2 and Agent 6 |
+| 5 | Sharing is Caring | 11 Claude Code build sessions published at [`build-small-hackathon/kirana-detective-build-traces`](https://huggingface.co/datasets/build-small-hackathon/kirana-detective-build-traces) |
+| 6 | Field Notes | Blog post at [huggingface.co/blog/build-small-hackathon/kirana-detective](https://huggingface.co/blog/build-small-hackathon/kirana-detective) |
+
+Full sash. All badges earned independently, each with verifiable evidence.
+
+**🗳️ Community Choice** — Kirana Detective is built around a problem that 12 million Indian shopkeepers face every week. It is demonstrable to anyone who has ever received a bill they couldn't verify — which is most of the world. The live Space requires no setup, no account, and produces a tangible rupee number in under a minute. The blog post and X post are live for community sharing. Encouraging votes from the community.
+
+### Sponsor Awards
+
+**OpenBMB ($10,000 pool)**
+
+Both language models are from OpenBMB's MiniCPM family:
+- MiniCPM-V 4.6 (`openbmb/MiniCPM-V-4.6`) — fine-tuned for Indian invoice extraction
+- MiniCPM5-1B (`openbmb/MiniCPM5-1B`) — fine-tuned for FMCG product normalisation and report generation
+
+Both are fine-tuned, pushed to HF Hub, and used in production in the Space. MiniCPM5-1B runs as GGUF via llama.cpp (cross-qualifying for Llama Champion badge).
+
+**Modal ($20,000 in credits)**
+
+All three models were trained on Modal A10G GPUs using Modal's `@app.function` decorator with GPU provisioning. Total compute: ~4.5 hours of A10G time, ~$5.80 total cost.
+
+Training scripts in `finetune/`:
+- `finetune/train_minicpm_v.py` — MiniCPM-V 4.6 fine-tuning (51 min, A10G)
+- `finetune/train_minicpm5_1b.py` — MiniCPM5-1B fine-tuning (~1 hr, A10G)
+- `finetune/train_yolo26n.py` — YOLO26n fine-tuning (~2 hrs, A10G)
+- `finetune/generate_invoices.py` — synthetic invoice generation (Modal function)
+- `finetune/export_minicpm_v_gguf.py` — LoRA merge + GGUF export (Modal function)
+
+**NVIDIA**
+
+YOLO26n is exported to ONNX and can leverage NVIDIA GPU acceleration via ONNX Runtime when available (falls back to CPU). The A10G GPU used for all training is NVIDIA hardware. ONNX Runtime GPU execution provider supports CUDA/TensorRT for deployment on NVIDIA hardware.
+
+---
+
+## Six-Agent Pipeline Summary
+
+```
+Agent 1 — Invoice Extractor     MiniCPM-V 4.6 (OpenBMB, fine-tuned)  →  Structured JSON
+Agent 2 — Product Matcher       MiniCPM5-1B (OpenBMB, GGUF, llama.cpp) →  Canonical SKU names
+Agent 3 — Pricing Agent         Rule-based (SQLite history)             →  Price / GST flags
+Agent 4 — Visual Counter        YOLO26n (ONNX Runtime)                  →  Product counts
+Agent 5 — Reconciliation Agent  Rule-based                              →  Shortage flags + ₹ loss
+Agent 6 — Savings Agent         MiniCPM5-1B (OpenBMB, GGUF, llama.cpp) →  ₹ report + actions
+```
+
+---
+
+## Constraints Met
+
+| Constraint | Status |
+|---|---|
+| Models ≤ 32B parameters | ✅ ~2.38B total |
+| Gradio UI | ✅ Custom Gradio 6.16 |
+| Hosted as HF Space | ✅ [build-small-hackathon/kirana-detective](https://huggingface.co/spaces/build-small-hackathon/kirana-detective) |
+| Demo video | ✅ [YouTube](https://youtu.be/8TVZP4sfesI) |
+| Social media post | ✅ [X post](https://x.com/naazimhussain02/status/2065966381657633161) |
+
+---
+
+## Links
+
+| Resource | URL |
+|---|---|
+| Space | https://huggingface.co/spaces/build-small-hackathon/kirana-detective |
+| Blog | https://huggingface.co/blog/build-small-hackathon/kirana-detective |
+| X Post | https://x.com/naazimhussain02/status/2065966381657633161 |
+| Invoice Extractor | https://huggingface.co/build-small-hackathon/minicpm-v-4-6-indian-invoice-extraction-merged |
+| Product Normalizer | https://huggingface.co/build-small-hackathon/minicpm5-1b-indian-fmcg-normalizer |
+| Product Detector | https://huggingface.co/build-small-hackathon/yolo26n-indian-fmcg-detection |
+| Training Dataset | https://huggingface.co/datasets/build-small-hackathon/kirana-invoice-train-data |
+| Build Traces | https://huggingface.co/datasets/build-small-hackathon/kirana-detective-build-traces |
+| GitHub | https://github.com/naazimsnh02/kirana-detective |

tracer.py

@@ -114,22 +114,8 @@ class AgentTracer:
         # Persist to local SQLite first (fast, synchronous)
         storage.save_audit_run(audit_run_id, trace_json)
 
-        # Then push to HF Hub with retries
-        for attempt in range(MAX_RETRIES):
-            try:
-                self._publish_to_hf_hub(audit_run_id, entries)
-                storage.mark_trace_published(audit_run_id)
-                logger.info("Trace %s published to HF Hub", audit_run_id)
-                return
-            except Exception as e:
-                wait = BACKOFF_BASE_SECONDS ** (attempt + 1)
-                logger.warning(
-                    "Trace publish attempt %d/%d failed: %s — retrying in %ds",
-                    attempt + 1, MAX_RETRIES, e, wait,
-                )
-                time.sleep(wait)
-
-        logger.error("Trace %s: all %d publish attempts failed; stored locally only", audit_run_id, MAX_RETRIES)
+        # HF Hub publishing disabled — runtime trace dataset was not completed
+        logger.info("Trace %s stored locally (HF Hub publishing disabled)", audit_run_id)
 
     def _publish_to_hf_hub(self, audit_run_id: str, entries: List[AgentTraceEntry]) -> None:
         from huggingface_hub import HfApi, CommitOperationAdd