Spaces:
Sleeping
Sleeping
| title: BreadBuddy | |
| emoji: 🍞 | |
| colorFrom: yellow | |
| colorTo: gray | |
| sdk: gradio | |
| sdk_version: 6.18.0 | |
| python_version: '3.11' | |
| app_file: app.py | |
| pinned: false | |
| tags: | |
| - track:backyard | |
| - sponsor:openbmb | |
| - sponsor:modal | |
| - achievement:offbrand | |
| - achievement:llama | |
| - achievement:fieldnotes | |
| # BreadBuddy 🍞 | |
| AI-powered bread baking assistant — diagnose what went wrong, get fixes, and learn to bake better. | |
| Built over 10 days for the Hugging Face × Gradio Build Small Hackathon. All models ≤ 32B, self-hosted, no proprietary APIs. | |
| ## Features | |
| | Feature | Description | Model Pipeline | | |
| |------|------|------| | |
| | 🍞 Photo + Text Diagnosis | Upload a bread photo with description → structured 3-part diagnosis (causes / fixes / recipes) | MiniCPM-V 4.6 → Gemma-4-12B | | |
| | 💬 Follow-up Chat | Drill deeper on diagnosis results — multi-turn conversation with context memory | Gemma-4-12B | | |
| | 🌙 Dark Mode | Full dark bakery theme with custom CSS/JS | Gradio 5.50.0 | | |
| All responses streamed in real-time via SSE (Server-Sent Events). Reasoning content visible in a collapsible panel. | |
| ## Architecture | |
| ``` | |
| User (Photo + Text) | |
| │ | |
| ▼ | |
| ┌─ Gradio Frontend (deploy/app.py) ──────────────────────────────────┐ | |
| │ Single-tab clinic UI · Dark bakery theme · Custom CSS/JS │ | |
| │ Streams SSE: reasoning_content + content dual channels │ | |
| └──────────────────────────┬──────────────────────────────────────────┘ | |
| │ POST /v1/chat/completions (OpenAI-compatible) | |
| ▼ | |
| ┌─ Modal Gateway (CPU, gateway.py) ──────────────────────────────────┐ | |
| │ Unified routing: has_image? → call_vision() : call_agent() │ | |
| │ ReAct loop (OpenAI function calling) · SSE streaming │ | |
| └──────────┬───────────────────────────────────┬─────────────────────┘ | |
| │ │ | |
| has_image? no image | |
| │ │ | |
| ▼ │ | |
| ┌──────────────────────┐ │ | |
| │ MiniCPM-V 4.6 │ │ | |
| │ Modal L4 GPU │ │ | |
| │ Vision analysis │ │ | |
| └──────────┬───────────┘ │ | |
| │ vision context │ | |
| ▼ ▼ | |
| ┌─────────────────────────────────────────────────────────────────────┐ | |
| │ Gemma 4 12B (GGUF Q4_K_M) · llama.cpp · Modal A10G │ | |
| │ 8K context · 8 concurrent slots · OpenAI-compatible API · -n 4096 │ | |
| └─────────────────────────────────────────────────────────────────────┘ | |
| ``` | |
| ## Key Engineering Decisions | |
| - **Unified Gateway Pattern** — single endpoint, stateless routing. Gateway on CPU (<2s cold start), models on GPU (independent scaling). Eliminates cross-service contract drift. | |
| - **ReAct Agent (Gateway-embedded)** — OpenAI function calling directly in gateway, no LangGraph dependency. Reduced 3 fragile cross-service contracts to 1. | |
| - **llama.cpp with `-n 4096`** — discovered and fixed a server-side 1000-token hard limit that silently truncated output. Root cause debugging took 3 repair cycles across server/client/parser layers. | |
| - **content + reasoning merge rendering** — tolerant of non-deterministic LLM output. Reasoning often contains complete diagnosis even when content is truncated. | |
| - **Custom Gradio UI** — deep CSS/JS override beyond default theme. Dark mode with localStorage persistence. | |
| ## By the Numbers | |
| | | | | |
| |------|------| | |
| | **Development** | 10 days (June 5–15, 2026) | | |
| | **Code** | ~2,000 lines Python (deploy + modal) | | |
| | **Tests** | 54 tests (41 unit + 13 E2E with Playwright) | | |
| | **Commits** | 40+ | | |
| | **Deployments** | 15+ modal deploy | | |
| | **Design docs** | 25+ (architecture decisions, retrospectives, checklists) | | |
| | **Architecture decisions** | 6 (2 revised from scratch) | | |
| <img src="https://pbs.twimg.com/media/HK16HJfaEAME9Ok?format=jpg&name=4096x4096" width="600" alt="BreadBuddy screenshot" /> | |
| ## Challenges Solved | |
| The most interesting bug: **E2E tests passed locally but the recipe section never rendered in production.** After 3 repair cycles across 4 agents, the root cause was traced to **llama.cpp's default `-n 1000` token limit** — Gemma-4's reasoning consumed ~70% of the budget, starving the visible content. The fix chain: `/no_think` hack → server-side `-n 4096` → content+reasoning merge rendering. Full retrospective: [technical-retrospective.md](https://github.com/iweb3insight/ceo-worktree/blob/master/1-Run/instructions/2026-06-15-BreadBuddy-%E9%A1%B9%E7%9B%AE%E5%A4%8D%E7%9B%98.md) | |
| **Gateway code rot** — three independently-deployed services (Gateway / MiniCPM / Gemma) drifted apart: mismatched routes, wrong response keys, dead code path. Fixed by reducing interface contracts from 3 to 1. | |
| ## Methodology | |
| This project was built with two AI-assisted development frameworks: | |
| - **Harness** (AGENTS.md + TDD + Skills + Memory) — project constitution, red-green-refactor, mandatory verification before success claims. AGENTS.md as a living document, 50+ cross-session memory entries. | |
| - **Architecture Loop** (Judge/Builder separation) — frozen acceptance gates before implementation, "nobody grades their own work," mandatory builder disagreements. Evaluated and documented applicability boundaries (best for incremental changes, not greenfield prototypes). | |
| Key lesson: **Verify the premise before building.** 30 minutes of Gemma function-calling compatibility tests saved 2 days of potential rework. | |
| ## Tech Stack | |
| | Layer | Technology | | |
| |----|------| | |
| | Frontend | Gradio 5.50.0, custom CSS/JS, dark mode | | |
| | Text Model | Gemma 4 12B (GGUF Q4_K_M) via llama.cpp b9518 | | |
| | Vision Model | MiniCPM-V 4.6 via Transformers | | |
| | Gateway | FastAPI + Python 3.11, CPU-only, SSE streaming | | |
| | GPU Cloud | Modal.com (A10G + L4, $250 credits) | | |
| | Agent | ReAct loop, OpenAI function calling | | |
| | Testing | pytest (41 unit) + Playwright (13 E2E), all against live API | | |
| | Deployment | Hugging Face Spaces (Gradio) + Modal serverless | | |
| ## Links | |
| - 🎬 Demo video: https://www.youtube.com/watch?v=QN4ZL1Q_kNA | |
| - 🐦 Social post: https://x.com/rockhighdev/status/2066432837075841399 | |
| ## License | |
| MIT |