Upload folder using huggingface_hub

app.py

@@ -11,7 +11,7 @@ from fastapi import BackgroundTasks, FastAPI, Header, HTTPException, Request
 from fastapi.responses import HTMLResponse, JSONResponse, RedirectResponse
 from pydantic import BaseModel
 
-from server import dedup, events, health, threads
+from server import dedup, events, threads
 from server.pipeline import AgentRequest, AgentResponse, run_pipeline
 from ui.blocks import CAROUSEL_JS, CSS, THEME, build_demo
 
@@ -134,10 +134,8 @@ def ingest(batch: IngestBatch, background_tasks: BackgroundTasks,
 
 
 @app.get("/health")
-def health_route():
-    # Liveness + hardware-adequacy (device/model/degraded/reason). The on-page
-    # status banner and the maintenance monitor both read this.
-    return health.health_status()
+def health():
+    return {"ok": True}
 
 
 # --- Per-user Google Calendar OAuth (web flow) ----------------------------- #
@@ -254,19 +252,6 @@ if SERVE == "uvicorn":
     from starlette.responses import Response as _Response
 
     _CAROUSEL_INLINE = f'<script id="cz-inline-js">({CAROUSEL_JS})();</script>'
-    # Status banner: fetch /health on load and reveal #status-banner if degraded
-    # (e.g. real model on CPU-only hardware). Same inline-script pattern as the
-    # carousel, since js= is unreliable on a mounted app; it polls for the element
-    # because Gradio renders it client-side after </body>.
-    _BANNER_JS = (
-        "(function(){fetch('/health').then(function(r){return r.json();})"
-        ".then(function(h){if(!h||!h.degraded){return;}(function s(){"
-        "var b=document.getElementById('status-banner');"
-        "if(!b){return setTimeout(s,400);}"
-        "b.textContent='\\u26a0\\ufe0f '+(h.reason||'This Space needs a GPU.')+' \\u26a0\\ufe0f';"
-        "b.style.display='block';})();}).catch(function(){});})();"
-    )
-    _BANNER_INLINE = f'<script id="cz-banner-js">{_BANNER_JS}</script>'
 
     @app.middleware("http")
     async def _inject_carousel_js(request, call_next):  # noqa: ANN001
@@ -276,7 +261,7 @@ if SERVE == "uvicorn":
         body = b"".join([chunk async for chunk in resp.body_iterator])
         html = body.decode("utf-8", "ignore")
         if "cz-inline-js" not in html and "</body>" in html:
-            html = html.replace("</body>", _CAROUSEL_INLINE + _BANNER_INLINE + "</body>", 1)
+            html = html.replace("</body>", _CAROUSEL_INLINE + "</body>", 1)
         headers = dict(resp.headers)
         headers.pop("content-length", None)  # body length changed; let Starlette recompute
         return _Response(content=html, status_code=resp.status_code,

docs/OffGridSchedula — In-Depth Technical Talk Track.md

@@ -0,0 +1,119 @@
+# OffGridSchedula — In-Depth Technical Talk Track
+*Audience: CS graduate students. Framing: a small, locally-served fine-tuned model wrapped in deliberate systems engineering.*
+
+> 📸 **Screenshot suggestion (hero):** the landing/Home hero with the tagline and the badge row (🔒 100% local · 🦙 llama.cpp · 🎯 Fine-tuned · 🪶 ≤ 32B), establishing the "small, local, fine-tuned" thesis up front.
+
+## [Opener — ~20s]
+OffGridSchedula reads a messy group chat and produces calendar events — entirely on a ~4-billion-parameter model running locally, with no cloud AI in the loop. What I want to show you isn't just *what* each page does, but the engineering decisions that make a small model behave reliably. The recurring theme: **use the LLM only for the fuzzy natural-language-to-structure step, and make everything that can be deterministic, deterministic.**
+
+## [The model-type decision — why decoders, not encoders — ~1:15]
+> 📸 **Screenshot suggestion:** a simple two-box slide — *encoder (BERT): classify · tag · embed* on the left, *decoder (GPT-style): generate · reason · orchestrate* on the right — with the app's `ActionPlan` JSON landing under the decoder side. If you have the architecture inset (the two local llama-servers, gemma-cal + MiniCPM), show it here to preview the two-decoder design.
+
+**The framing.** Before *which* model — before size, fine-tuning, or quantization — there's a more fundamental fork most teams skip past: *encoder or decoder?* We made that call twice, once for extraction and once for orchestration, and both times the answer was a decoder. It's worth making the reasoning explicit, because it's the decision the rest of the system is built on top of.
+
+**The decisions behind it:**
+
+- **Why a decoder, not BERT — the deliverable decides.** Per thread the extractor emits one constrained object: `events[]` (title, ISO-8601 start/end, location, reminders), a `reply_draft`, and a `needs_clarification` question when the thread is ambiguous. That isn't classification and it isn't span-tagging — it's *generation* plus reasoning, resolving "next Tuesday" against a reference date and shifting a start when someone says "arrive 15 min early." Encoder-only models (BERT / RoBERTa / DeBERTa) are *discriminative*: they understand — classify, tag, embed — but they don't *write*. To force this onto BERT you'd stitch together an intent classifier + an NER tagger + a datetime normalizer, and you still couldn't draft the reply. A decoder wasn't the better option here; it was the only candidate.
+
+- **Why orchestration is *also* a decoder job.** Planning is generative reasoning too — you can't classify your way to "call `extract_events`, observe the result, then finalize." So the Agent tab's planner is a *second* decoder, **OpenBMB's MiniCPM**, deliberately separate from the extractor: MiniCPM decides *which tools to call*, the fine-tuned E4B does the extraction, each model doing the one thing it's good at. (The MiniCPM-over-MCP design gets its own walkthrough on the Agent page — the point here is simply that *both* roles an encoder fundamentally can't fill, generating structure and planning tool calls, are decoder territory.)
+
+- **The tradeoff we accepted, stated honestly.** Decoders cost you. Generation is autoregressive, so latency scales with output length where a BERT tagger would answer in <100 ms; you need a GPU (~5 GB VRAM at 4-bit) where an encoder runs on CPU for cents; and it's heavier to deploy — GGUFs through llama.cpp versus a single CPU model. We took all of it, because the work is generative and there's no honest way around that.
+
+- **Why we could give up BERT's safety and still be safe.** An encoder has one quiet superpower: it *can't* hallucinate a label set it was never given. A decoder gives that guarantee up — so we rebuilt it in the systems layer instead of the model. Generation is grammar-constrained to a JSON Schema derived from our Pydantic `ActionPlan` (correct by construction); everything that must be exact stays in deterministic Python; and an eval gate (schema-validity, precision, recall, F1) has *rejected* several of our own fine-tunes before they could ship. That's the recurring theme applied to model *choice*: pick the model that can do the fuzzy job, then wrap it so the exact parts are guaranteed in code.
+
+- **When the encoder still earns its place.** Choosing a decoder for the core doesn't retire BERT — it relocates it to the *edges*. The efficient extension is a cheap encoder front-door: a tiny CPU classifier ("is this even a scheduling message?") that gates the expensive GPU decode, plus sentence-embeddings for the Memory tab's recall. Encoders to *decide and retrieve*; decoders to *generate and orchestrate*; route cheap → expensive.
+
+**One-line bridge:** type settled — a decoder, in fact two — the next questions are *how small* and *how specialized*, which is exactly where the Schedule page picks up.
+
+## [Home — the Schedule page — ~2:00]
+> 📸 **Screenshot suggestion:** the Schedule tab mid-run — a pasted appointment thread on the left, the streamed results on the right showing an extracted event (e.g. 10:15–11:00 with the joined address), a ⚠️ conflict badge, and the drafted reply. A second shot of the live "thinking" trace streaming is a nice optional inset.
+
+**Feature.** You paste a chat thread or drop a screenshot; the app streams back extracted events, a conflict check against your calendar, a ready-to-send reply, and one-tap export to `.ics` or Google/Outlook/Apple.
+
+**The decisions behind it:**
+
+- **Why a fine-tuned *small* model, not a frontier API.** The hard constraint was local-first — no cloud AI calls. So the model has to be edge-sized: *gemma-cal*, a QLoRA fine-tune of Gemma E4B, ~5 GB at 4-bit, served as a GGUF through llama.cpp. The decision to *fine-tune* rather than prompt a generic model wasn't about raw capability — it was about **reliability of structure**. The fine-tune holds 100% schema validity even with no system prompt, won't invent an event from "thanks!", and learns *this product's* date conventions (what "next Tuesday" resolves to). You trade general intelligence for a model that's bulletproof at one job.
+
+- **Why grammar-constrained decoding.** The single most important reliability decision. Generation is constrained to a JSON Schema derived directly from our Pydantic model (`json_schema=ActionPlan.model_json_schema()`). The decoder can only emit tokens that keep the output a valid `ActionPlan`. Compare the alternative — generate free text and parse-and-repair — which is exactly where small models fall over. By constraining at the grammar level, we delete an entire class of failures: no malformed JSON, no missing fields, no hallucinated structure. The contract is enforced at decode time, not hoped for afterward.
+
+- **Why one `ActionPlan` object.** The model emits a single structured plan — `reasoning`, `events[]`, `conflicts[]`, `proposed_times[]`, `reply_draft`, `needs_clarification` — in one pass. Two design choices live here: first, everything downstream is *typed* (Pydantic), so the UI and exporters never touch raw model text. Second, `needs_clarification` is a first-class field — when a thread is ambiguous ("sometime next week"), the model is trained to *ask* instead of fabricating a datetime. That's a deliberate choice to fail safe rather than fail confident.
+
+- **Why conflict detection is NOT the model.** Interval overlap is exact, cheap, and verifiable — so we don't spend LLM tokens or risk hallucination on it. `calendar_out/freebusy.py` does deterministic free/busy math against intervals parsed from your `.ics`, and classifies each clash as overlap, adjacent, or tight. The principle: **the LLM converts language to structure; Python does the temporal logic.** Same reasoning drove the deterministic post-processing for arrival-aware start times and type-based reminders — logistics that *must* hold get guaranteed in code, with the model's output as the starting point.
+
+- **Why streaming, and why a browser-held OAuth token.** A local model is slower than an API, so we stream the reasoning trace to make the wait legible. And the Google token lives in *your browser's* localStorage, never on the server — the server never holds your calendar credentials. That's a privacy decision that also keeps the "off-grid" claim honest: the only outbound call is the user's own optional calendar push.
+
+## [Agent page — the MiniCPM-over-MCP design — ~2:00]
+> 📸 **Screenshot suggestion:** the Agent tab's live step trace — "MiniCPM planner engaged → tool_call: extract_events → observation → Planner finished" — so the audience sees a model genuinely planning and calling a tool. Pair it with a tiny inset of the architecture (two local llama-servers: gemma-cal + MiniCPM) if you have a diagram.
+
+**Feature.** The Agent tab runs the *same* extraction workflow, but agentically: a separate planner model reads the thread, calls the app's tools itself, and you watch every step — plan, tool call, observation, result — before it lands on the same events/conflicts/reply surface as Home.
+
+**The decisions behind it:**
+
+- **Why expose the app's own functions as MCP tools — and have the agent eat its own dog food.** `extract_events`, `check_conflicts`, and `make_ics` are published as **Model Context Protocol tools** via Gradio's `mcp_server=True`, served over an SSE endpoint. The deliberate choice is that the planner consumes them through that *public* MCP contract — the same interface an external client like Claude Desktop or Cursor would use — not via private Python imports. So the agentic path is a genuine proof that the Space is a real MCP server, not a demo wrapper. The agent talks to the application exactly the way a third party would.
+
+- **Why a second, separate model just for planning.** The fine-tuned E4B is a *specialist* — natural-language-to-`ActionPlan`. Orchestration is a different skill, so it's a different model: **OpenBMB's MiniCPM (1B), on its own local llama-server**. That's a clean separation of concerns — the planner decides *which tools to call*; the extractor does the extraction — and both stay local, both under the size cap, still zero cloud AI. It's a two-model architecture where each model does the thing it's good at.
+
+- **Why a framework + a standard, not a bespoke loop.** Rather than hand-roll an agent, we use smolagents' `ToolCallingAgent` pointed at MiniCPM (an OpenAI-compatible server model) over an `MCPClient` connected to the localhost SSE endpoint. Standing on the agent framework plus the MCP standard means the interesting engineering is in the *integration*, not in reinventing tool-call parsing.
+
+- **Why the planner is now a *single* tool call — the central lesson.** This is the part worth dwelling on, because we got here empirically. The first design was a multi-step planner: extract → check conflicts → render `.ics`. The problem is structural to agent loops: **every step re-sends the accumulated context** — the task, the thread, and each prior tool's full observation. On long, multi-event threads that did two bad things: it blew past the planner's context window (a hard `request exceeds context` failure), and it ballooned latency to ~3.5 minutes. The insight that fixed it: conflict math and `.ics` rendering are *already deterministic* — the planner never needed to drive them. So we collapsed the planner to **exactly one tool call (`extract_events`)**, then let the deterministic path finalize the rest. The agentic value — a model genuinely planning and invoking a tool through MCP — is fully preserved, but the unbounded-accumulation pathology is gone. Latency dropped from ~207s to ~75s, and context overflow became *structurally impossible*, because a single call has nothing to accumulate.
+
+- **Why a deterministic scripted fallback wraps the whole thing.** If the planner is unavailable — model down, an error mid-run, or CI/stub mode with no model — `run_orchestrator` degrades to a scripted sequence that runs the same tools deterministically and emits *identical* step events. The decision: the tab must always return a correct result, so the LLM planner is the showcase, never a single point of failure. As a bonus, that deterministic path is exactly what the test suite exercises — CI never needs a GPU.
+
+- **The unglamorous interop decisions that actually made small-model tool use work.** Three of them, because they're the reality of this space. First, Gradio exposes *every* UI callback as an MCP tool — ~64 of them — so we **filter the planner's toolset down to the calendar tools**; handing a 1B model 64 tools degrades planning and, worse, pulls in file-input schemas with unresolvable `$ref`s that crash prompt rendering. Second, we had to register `make_ics`/`check_conflicts` through `gr.api()` rather than hidden components, because Gradio otherwise emitted an *untyped* JSON schema (`"type": {}`) that the small planner filled with a malformed argument. Third, the extraction tool is text-only over MCP for the same typing reason. None of this is glamorous, but it's the difference between "the agent works in the slides" and "the agent works."
+
+- **Why the planner's answer isn't the product.** The planner's free-text output is treated as *evidence* — the visible trace that proves the agent reasoned and acted. The canonical `ActionPlan` is still re-derived through the deterministic pipeline (and an extraction cache means the planner's call and the finalization share a single E4B inference). It's a trust-but-verify architecture: the agent shows its work for transparency, the deterministic core guarantees the result.
+
+**One-line bridge back to the theme:** even the *agentic* page obeys the project's core rule — the model plans and calls a tool, but the exact, must-be-correct work stays in deterministic code.
+
+## [Activity page — ~1:30]
+> 📸 **Screenshot suggestion:** the Activity dashboard — the colored stepper, the metric tiles (events, conflicts, latency), the stage histogram (BarPlot), and the "this week" impact panel — all on screen at once. An optional second shot: the one-click "publish redacted trace" confirmation linking to the public HF dataset.
+
+**Feature.** A live operations dashboard: a real-time stepper, latency/throughput tiles, an event timeline, a stage histogram, recent per-run traces, and a durable "this week" impact panel — refreshed every two seconds.
+
+**The decisions behind it:**
+
+- **Why an in-process event bus.** Instrumentation is decoupled from logic via `server/events.py`: the pipeline calls `bus.emit(stage, message, …)` and the UI subscribes. The decision to keep it an **ephemeral ring buffer** rather than a database is deliberate — live telemetry doesn't need durability, and a Space shouldn't carry a DB dependency for a dashboard.
+
+- **Why a second, *durable* tier.** The weekly impact (events captured, conflicts caught, minutes saved) *does* need to survive restarts, so it's a separate persistent log (`server/impact.py`). Two-tier telemetry: ephemeral for "what's happening now," durable for "what value accrued." And `minutes_saved` is explicitly a *configurable estimate*, not a measurement — an honesty decision, surfaced as such.
+
+- **Why contextvars for run scoping.** Correlating emitted events to a single run is hard when Gradio streams across async contexts. We use a `run_scope` contextvar to tag events, and — this is the gotcha — wrap its reset in try/except because Gradio resets contexts underneath us. That's the kind of framework-reality decision you only make after it breaks once.
+
+- **Why publishable, redacted traces.** Any run's trace can be pushed to a public Hugging Face dataset in one click — for reproducibility and community learning. The critical decision: traces are **structural by design** — stage names, counts, latencies, *never* the chat text — and redaction is forced for anything public. Privacy-by-construction: the thing you can share literally cannot contain the thing you must protect.
+
+## [Memory page — ~1:15]
+> 📸 **Screenshot suggestion:** the Memory tab dataframe showing a few sample facts (people/roles/preferences with their weights) and the "load sample memories" button — and, if you can, a before/after of an extraction that resolves "Coach" to the right person once a fact is present.
+
+**Feature.** Device-owned facts — people, roles, preferences, locations — that personalize extraction so the model resolves "Coach" or "the dentist" to the right person, and learns your recurring contacts.
+
+**The decisions behind it:**
+
+- **Why localStorage, not a server database.** Personalization data is the most sensitive data in the system, so it never touches the server. Facts live in the browser; on each request the UI passes a compact `memory_block` to the extractor. Two payoffs: there's no PII at rest on a shared Space, and it's inherently multi-user-safe because there's no shared server state to collide. The decision treats memory as *the user's*, not the app's.
+
+- **Why prompt-injection instead of per-user fine-tuning.** `facts_to_recall()` renders the facts into a compact "what I know about you" block prepended to the extraction prompt. Per-user fine-tuning would be the heavyweight answer and is infeasible at this scale; prompt-time personalization is instant, cheap, and reversible — essentially a tiny, hand-curated RAG. You get personalization without touching the weights.
+
+- **Why weighted facts and auto-observation.** Each fact carries a weight that's bumped on reinforcement — a lightweight recency/relevance signal so repeated facts win, with no model involved. And `observe_plan()` quietly learns recurring attendees from accepted plans, so the system "grows with you" without demanding explicit input. There's also a deliberate split: the UI path uses client memory, while a separate server-side recall exists for the autonomous path — kept apart so per-user data never pollutes the shared store.
+
+## [Feed page — ~1:00]
+> 📸 **Screenshot suggestion:** the privacy-sealed Feed on the public build — i.e. the `{"feed": "private", …}` notice — to make the privacy-by-default point visually. Optionally, a paired shot of the populated JSON view on a trusted local deployment to show what the Mac collector ingests.
+
+**Feature.** A JSON view of raw iMessages ingested from an optional Mac collector — for the hands-off, autonomous mode.
+
+**The decisions behind it:**
+
+- **Why a collector at all — a platform-forced decision.** iOS exposes no API for iMessage content. There's no clean way to read messages on the phone. So the architecture works *around* the constraint: a small collector on a Mac (where iMessages sync) reads `~/Library/Messages/chat.db` with Full Disk Access and POSTs new messages to a FastAPI `/ingest` endpoint. This is a case study in letting a hard platform limit dictate the system boundary — the primary path stays "paste from your phone browser, no install," and the collector is an optional power-user add-on.
+
+- **Why `/ingest` is token-authenticated.** The endpoint accepts message *content*, so it's bearer-token gated (`INGEST_TOKEN`) — an unauthenticated write path for personal messages would be indefensible.
+
+- **Why the Feed is privacy-gated by default.** Raw message text is the most sensitive thing the app ever sees, so the Feed only renders it when `EXPOSE_FEED=1` — on public builds it returns a privacy notice instead. The default is sealed; you opt *in* to visibility on a trusted local deployment, never *out* on a public one. Privacy-by-default, again, as a hard switch rather than a guideline.
+
+## [Submission page — ~50s]
+> 📸 **Screenshot suggestion:** the Submission tab's green-checked scorecard — hard rules (≤ 32B, Gradio on HF, public repo) and the bonus quests — with the evidence links visible, to drive home the "self-verifying compliance" point.
+
+**Feature.** A live compliance scorecard for the hackathon — green checks against the rules, with evidence links to the model, training scripts, and source.
+
+**The decisions behind it:**
+
+- **Why generate it from the running environment, not hardcode it.** `_compliance_facts()` reads the *live* config — `MODEL_REPO`, `MODEL_FILE`, `INFERENCE_BASE_URL` — and derives the claims from what's actually loaded. If you swap the model or point inference at a remote server, the scorecard changes with it. The decision was to make compliance **self-verifying and tamper-evident**: the page can't claim "under 32B, local llama.cpp, published fine-tune" unless that's the truth of the process serving the page. For a CS audience, it's reproducibility applied to a submission — the artifact attests to its own provenance.
+
+## [Close — ~20s]
+Step back and the pattern is consistent: a **fine-tune for structural reliability**, **grammar-constrained decoding** so output is correct by construction, **deterministic code for everything exact**, **privacy-by-default** at every data boundary, and **self-attesting compliance**. The headline is "a small model runs your scheduling" — but the engineering story is everything built *around* that model to make it trustworthy.

docs/blog-eval-gated-finetuning.md

@@ -0,0 +1,187 @@
+# What Six Failed Fine-Tunes Taught Us About Evals, Templates, and Knowing When to Stop
+
+*A post-mortem on fine-tuning Gemma-4 for structured calendar extraction — fifteen GPU runs,
+one destroyed model, one exonerated quantizer, a chat-template landmine, and the eval harness
+that caught every bad model before it shipped.*
+
+---
+
+## The setup
+
+[OffGridSchedula](https://huggingface.co/spaces/ParetoOptimal/OffGridSchedula) is a local-first
+scheduling agent: paste a group chat (or a flyer screenshot) and get back a constrained
+**ActionPlan** JSON — events with exact ISO datetimes, a conflict check, a drafted reply, and a
+`needs_clarification` question when the thread is too vague to schedule. Inference is
+llama.cpp serving Gemma-4 GGUFs; no cloud AI APIs.
+
+The project carried a hard requirement: ship a **fine-tuned model** that outperforms its base.
+This is the story of trying to satisfy that requirement honestly — and what "honestly" ended up
+costing and teaching. Everything below ran on Modal serverless A100s; total GPU spend for the
+entire investigation was well under $100.
+
+## Act I: The fine-tune that lost to its own base
+
+The first QLoRA fine-tune of `google/gemma-4-31B-it` (Unsloth, r=16, 69 synthetic examples,
+2 epochs) looked fine in a smoke test. So we built a real eval before trusting it: 28 held-out
+examples scored on **start-exact recall** (did you produce the exact ISO start datetime),
+event F1 with greedy datetime matching, schema validity, no-event accuracy (does chitchat
+hallucinate events), and clarification recall (do you *ask* instead of inventing when a plan is
+"TBD"). Temperature 0, the same `response_format: json_schema` call the production server uses.
+
+First scores: fine-tune **F1 0.81**, base **0.977**. The fine-tune *lost to its own base*. The
+mismatch dump showed why — three of its five misses were the same corruption: `"206-10-06"`
+instead of `"2026-10-06"`. A dropped year digit.
+
+Two suspects: quantization (classic low-bit digit corruption) or the training itself.
+
+## Act II: Scaling data made it worse. Much worse.
+
+The intuitive fix — more data — backfired in the most instructive way possible:
+
+| training examples | schema validity | event F1 |
+|---|---|---|
+| 69 | 1.00 | 0.81 |
+| 87 | 0.75 | 0.465 |
+| 122 | 0.46 | 0.214 |
+| 2,122 (incl. real SMCalFlow data) | 0.107 | 0.000 |
+
+**Monotonic decay with training steps.** By the 2,122-example run the model emitted unparseable
+output on ~90% of inputs. A raw-output probe (serve the staging GGUF, generate *without* the
+JSON grammar) settled what "broken" meant: the model free-generated `Huddle — — — — — —…` to the
+token limit. Not a formatting problem. Destroyed weights.
+
+Two cheap experiments isolated the cause:
+
+**Quantization was exonerated** by sweeping the *same* merged weights through f16 / Q8_0 /
+Q4_K_M (one A100 lease, the fp16 was already on a Modal volume). At full fp16 the fine-tune
+still scored validity 0.64 / F1 0.57 — nowhere near base. Precision bought ~+0.1 F1. The damage
+preceded the quantizer.
+
+**The chat template was half the story.** Gemma-4 ships a brand-new template —
+`<|turn>user\n…<turn|>`, with a dedicated `<|turn>system` block. There is no
+`<start_of_turn>` anywhere in it. Our training code used Unsloth's legacy `"gemma"` template,
+which is built entirely on `<start_of_turn>`. Every gradient step optimized a turn syntax that
+`llama-server --jinja` (which reads the template *embedded in the GGUF*) never renders. We
+verified the fix end-to-end by reading `tokenizer.chat_template` out of our exported GGUF's
+metadata with `gguf.GGUFReader` — trust the artifact, not the code — and added a hard
+`assert "<|turn>" in rendered` to the training script so the mismatch can never silently
+recur.
+
+And yet: with templates verifiably aligned, response-only loss masking, and LR dropped to 5e-5,
+the 31B *still* collapsed to validity 0.0. With dataset, template, LR, and masking all varied,
+the one remaining common factor was the training stack itself: Unsloth's QLoRA path for the
+brand-new Gemma-4-31B architecture (its own logs warn it can't handle `Gemma4AudioModel`
+internals). The same recipe on Gemma-4 **E4B** trained cleanly every single time. New
+architectures make the training framework a first-class suspect.
+
+## Act III: The benchmark nobody wants — prompt engineering hits 1.0
+
+While the fine-tune investigation ran, error analysis kept improving the *system*:
+
+- **State the weekday in the prompt.** `Current datetime: Monday, 2026-09-14T09:00:00` turns
+  day-of-week resolution from memorized calendar knowledge into deterministic arithmetic — for
+  every model.
+- **Two surgical system-prompt lines** targeting the base's only two eval misses (multi-event
+  splitting; asking on "TBD") took **stock Gemma-4-31B to 1.0 on every metric**.
+
+That's the uncomfortable benchmark for any SFT project: against a near-ceiling base, prompt
+engineering had ~100× better ROI than fine-tuning. The requirement, however, was a fine-tune
+that beats *its* base — so we re-aimed at the tier where headroom actually existed.
+
+## Act IV: The E4B campaign — six gated runs to a tie
+
+A ~5 GB Gemma-4 E4B that runs on modest hardware is the model this local-first project actually
+wants at the edge, and stock E4B had real room: F1 0.93. Every retrain ran through an
+**eval-gate**: train → upload to a *staging* filename → eval → promote to production **only if
+it beats the bar**, else delete staging. The gate rejected eight models across this project
+without production ever serving one of them.
+
+Each iteration fixed a diagnosed failure, not a hunch:
+
+| run | change | F1 (eval) |
+|---|---|---|
+| 1 | fixed recipe, 2,122 examples | 0.884 (n=28) |
+| 2 | weekday-in-prompt, data regenerated to match | 0.955 |
+| 3 | dropped 74 SMCalFlow rows teaching a conflicting "next DOW" convention; 4× hand-data upsample | **1.000** |
+| 4 | + TBD-clarify seeds, 8× upsample | 0.93 (clarify → 1.0) |
+| 5 | clarify seeds at 4× | 0.93 |
+| — | **eval expanded 28 → 60 examples** | — |
+| 6 | + targeted seeds for the two shapes stock fails | 0.97 |
+
+Three findings here deserve their own bullets:
+
+- **Label conventions are silent killers.** SMCalFlow annotates "next Tuesday" (said on a
+  Monday) as *tomorrow*; our app's convention is *Tuesday of next week*. 74 imported rows
+  trained the bug in. Filtering them fixed it — until other data shifts brought it back.
+  When you convert someone else's dataset, you inherit someone else's semantics.
+- **Small evals lie.** At n=28 (22 gold events), one event = 4.5 recall points, and we watched
+  **4 added training rows flip 3 eval cases**. Run-to-run SFT jitter swamped the signal — runs
+  3–5 were a seesaw, not progress. Expanding to 60 examples / 50 events made the gate mean
+  something again.
+- **Some priors resist data.** The "next Tuesday = tomorrow" prior survived *seven* explicit
+  counter-examples. Stock makes the same error. Genuinely ambiguous English stays ambiguous.
+
+Run 6 vs stock E4B (with the same engineered prompt): **identical confusion counts** —
+48/50 events, tp/fp/fn 48/1/2, F1 0.97 = 0.97. A dead statistical tie.
+
+## Act V: The bare-prompt tiebreaker
+
+The classic argument for SFT at parity is internalization: the fine-tune shouldn't *need* the
+prompt. So we measured it — same 60 examples, system prompt deleted for both models, identical
+minimal user content, same JSON-schema constraint:
+
+| bare, n=60 | stock E4B | fine-tuned E4B |
+|---|---|---|
+| schema validity | 0.967 | **1.0** |
+| no-event accuracy | 0.70 | **0.80** |
+| clarification recall | 0.50 | **0.625** |
+| event F1 | **0.682** | 0.644 |
+
+The fine-tune is more *disciplined* bare (never breaks schema, hallucinates less, asks more);
+stock edges bare extraction. No decisive gap. **Final verdict: at this data scale (139
+hand-authored + 2,000 converted examples, QLoRA, 1 epoch), the fine-tune reaches parity with
+its base — not superiority.** It shipped as the project's edge model with exactly that claim on
+the model card, by explicit owner decision; the strict-dominance auto-gate, correctly, never
+promoted it.
+
+## What we'd tell you to do differently
+
+1. **Build the eval before the fine-tune, and gate every publish on it.** Ours rejected eight
+   bad models, caught a regression that had already overwritten a good artifact (server-side
+   `CommitOperationCopy` restored it for free), and converted every failure into a diagnosis.
+   The eval harness was the single highest-value artifact of the project.
+2. **Train format must equal serve format — and verify it in the artifact.** Read the chat
+   template out of the exported GGUF's metadata. Assert it in the training script. A template
+   mismatch doesn't error; it just quietly ruins everything at a rate proportional to your
+   training steps.
+3. **Suspect the training stack on new architectures.** The same recipe destroyed Gemma-4-31B
+   and trained Gemma-4-E4B flawlessly, six times in a row. Framework warnings about unhandled
+   submodules (`Gemma4AudioModel`) are not noise.
+4. **Exonerate quantization cheaply before blaming it.** Sweep the same weights across
+   f16/Q8/Q4 in one GPU lease. Ours cost a few dollars and killed the most plausible-sounding
+   hypothesis of the whole project.
+5. **Put deterministic facts in the prompt instead of hoping the model memorized them.**
+   Weekday-in-the-prompt improved every model, including the ones we didn't train.
+6. **Match your eval's resolution to your iteration size.** If one flipped case moves a gated
+   metric by 4+ points, your gate is a coin flip.
+7. **Diff label conventions when importing datasets.** Resolution semantics ("next DOW"),
+   reference-time handling, and reply style all transfer — whether you want them to or not.
+8. **Respect the parity outcome.** Against a strong instruction-tuned base on a narrow,
+   well-prompted task, SFT parity is a common honest result. The defensible claims left are
+   discipline-under-no-prompt, token savings, and convention control — claim those, not wins
+   you didn't measure.
+
+### What might still beat the base
+10–100× more *real* (non-template) data; full fine-tuning rather than QLoRA once the stack
+supports the architecture; preference optimization (DPO) specifically on the
+clarify-vs-extract boundary; and a harder eval where the ceiling isn't 0.97. The gate is
+already in place to referee all of it.
+
+---
+
+*Artifacts: model repo
+[`ParetoOptimal/gemma-4-cal-gguf`](https://huggingface.co/ParetoOptimal/gemma-4-cal-gguf)
+(31B v1 + E4B edge + mmproj), eval harness `training/eval.py` + `training/data/eval.jsonl`,
+gate `training/gated_retrain.py`, importer `training/import_smcalflow.py` (SMCalFlow,
+CC BY-SA 4.0 — Semantic Machines et al., TACL 2020), full run-by-run log in
+`docs/eval-roadmap.md`.*

docs/blog-offgridschedula.md

@@ -0,0 +1,211 @@
+# Off the Grid, On Schedule
+
+*A solo Build Small project — one person, two small local models, and a calendar problem worth solving.*
+
+## TL;DR
+
+- **OffGridSchedula** turns a pasted group chat — or a screenshot of a flyer or invite — into calendar events, with conflicts caught and a reply drafted, then a local `.ics` you own.
+- It runs a **fine-tuned Gemma 4** through **llama.cpp**, **in the Space**. No cloud AI APIs, no account, no app to install.
+- A full **QLoRA → GGUF** fine-tuning pipeline, built solo, ships behind an **eval gate** that refuses to publish a model that doesn't clear the bar — and it produced an own edge model at parity with the base.
+- **Run the agents** runs a **two-model team**, both local and both ≤ 32B: **OpenBMB MiniCPM5-1B** plans the steps and the fine-tuned **gemma-cal E4B** does the extraction.
+- It's also an **MCP server**: any MCP-aware agent can call `extract_events` / `make_ics` / `check_conflicts` as tools.
+
+**👉 Try it:** [build-small-hackathon/OffGridSchedula](https://huggingface.co/spaces/build-small-hackathon/OffGridSchedula) · **Model:** [gemma-4-cal-gguf](https://huggingface.co/build-small-hackathon/gemma-4-cal-gguf) · **Planner:** [MiniCPM5-1B](https://huggingface.co/openbmb/MiniCPM5-1B-GGUF) · **Traces:** [offgridschedula-traces](https://huggingface.co/datasets/ParetoOptimal/offgridschedula-traces)
+
+## Contents
+- [The problem](#the-problem)
+- [What it does](#what-it-does)
+- [Architecture](#architecture)
+- [Fine-tuning Gemma 4 for calendars](#fine-tuning-gemma-4-for-calendars)
+- [Off the grid: llama.cpp in a Space](#off-the-grid-llamacpp-in-a-space)
+- [From app to agent: MCP, memory, and shared traces](#from-app-to-agent-mcp-memory-and-shared-traces)
+- [Built small, by the rules: constraints & badges](#built-small-by-the-rules-constraints--badges)
+- [Lessons learned](#lessons-learned)
+- [What's next](#whats-next)
+- [Get started](#get-started)
+- [Acknowledgements & citation](#acknowledgements--citation)
+
+## The problem
+
+Every parent knows this chat. The class group thread scrolls past: *"Picture day is Thursday at 9am, wear the green shirt."* *"Practice moves to Tuesday 5pm this week."* *"RSVP by Friday for the party."* You read it once, mean to add it later, and miss it.
+
+That's the person this was built for — not "users" in the abstract, but one busy parent whose kid's school and activity events are buried in noise. It's an honest fit for a small, local model: the input is a handful of recent messages or a screenshot, the output is a few calendar events, and the whole thing should work from a phone browser with nothing to install.
+
+![The dark hero of the OffGridSchedula landing page: "Schedule your invite before it slips away."](assets/offgridschedula/hero.png)
+*The landing page. Paste a chat or a screenshot; get events back.*
+
+## What it does
+
+Paste the chat (or attach a screenshot of a flyer/invite). The agent returns:
+
+1. **The events** — title, start/end, location, a sensible default reminder.
+2. **A conflict check** against a calendar you upload (`.ics`), with clashes flagged.
+3. **A ready-to-send reply** ("Got it — adding both, thanks!").
+
+Everything is **surfaced for review before anything is saved**. The output is a local `.ics` file you can import into any calendar, with an optional one-click Google Calendar push. No inbox access, no auto-reading — it reads only what you choose to paste.
+
+## Architecture
+
+The app is a single **Gradio 6** Blocks UI mounted alongside a **FastAPI** app on one port, so the same Space serves the UI, a `/agent` endpoint, and an MCP server.
+
+**Two small models, two jobs.** Extraction is the fine-tuned **`gemma-cal` E4B** (~4B effective params): it reads the thread — with **vision**, for screenshots — and emits the single constrained `ActionPlan` below. A second model plans the run: **OpenBMB [MiniCPM5-1B](https://huggingface.co/openbmb/MiniCPM5-1B-GGUF)** as the *planner*, which sequences the steps via the Space's own MCP tools when you click **Run the agents**. Both run locally through llama.cpp (the planner as a second `llama-server`); neither is over 32B, and nothing leaves the box.
+
+The model never decides *whether two events clash* — it decides **what** the events are; deterministic interval math decides **when they conflict**. The model emits a single constrained JSON object (a pydantic `ActionPlan`), grammar-constrained so it's always valid:
+
+```python
+class Event(BaseModel):
+    title: str
+    start: str            # ISO 8601
+    end: str | None = None
+    location: str | None = None
+    reminder_minutes: int | None = 30
+
+class ActionPlan(BaseModel):
+    reasoning: str
+    events: list[Event] = []
+    conflicts: list[Conflict] = []
+    proposed_times: list[str] = []
+    reply_draft: str = ""
+    needs_clarification: bool = False
+```
+
+Inference sits behind one seam — an `INFERENCE_BASE_URL` env var. Unset, the Space loads a GGUF and runs it in-process via llama.cpp. Set, it points at any OpenAI-compatible `llama-server` (e.g. one running on your own machine). Same app, two deployment shapes.
+
+A nice consequence: a **stub extractor** (`USE_STUB_EXTRACTOR=1`, a tiny regex heuristic) lets the entire app, the test suite, and the demo run with **no GPU at all**. The expensive dependency is optional from day one — which means the cheap path doubles as the CI harness and the free-tier preview.
+
+## Fine-tuning Gemma 4 for calendars
+
+The fun part. **Gemma 4** was fine-tuned to read messy chats into the `ActionPlan` schema — and, just as importantly, paired with the **machinery to know whether a fine-tune is actually any good**.
+
+**The pipeline.** QLoRA via Unsloth (4-bit, r=16) → merge → `convert_hf_to_gguf.py` → `llama-quantize Q4_K_M` → published as [`build-small-hackathon/gemma-4-cal-gguf`](https://huggingface.co/build-small-hackathon/gemma-4-cal-gguf). Training data is hand-authored examples plus a **SMCalFlow** importer (Microsoft Semantic Machines, CC BY-SA 4.0) that resolves LISP "dataflow" calendar programs into concrete, self-consistent datetimes — directly training the relative-date skill ("next Thursday", "the 14th") against a spread of 2026 reference dates.
+
+**The real win: an eval gate.** Generic benchmarks (MMLU, etc.) don't apply to a narrow extraction task, so a task-specific scorer (`training/eval.py`) over a held-out set became the **publishing process** (`training/gated_retrain.py`):
+
+> Retrain → upload to a **staging** filename → score on the held-out eval → **gate**
+> (`schema_validity ≥ 0.95`, `event_f1 ≥ 0.81`, `start-exact recall ≥ 0.773`) →
+> **PASS** promotes staging to production (a free server-side copy); **FAIL** deletes staging, production untouched.
+
+No retrain reaches users unless it beats the current best. That gate has already earned its keep — it caught regressions on bigger retrains and refused to ship them, so production was never degraded by an experiment.
+
+Here's the fine-tune's scorecard (Q4_K_M, n=28), with the base model as context:
+
+| Metric | Fine-tune `gemma-4-cal` | Base Gemma 4 (context) |
+| --- | --- | --- |
+| schema validity | 1.00 | 1.00 |
+| no-event accuracy | 1.00 | 1.00 |
+| **clarification recall** | **1.00** | 0.75 |
+| end-time exact | 1.00 | 1.00 |
+| event precision | 0.85 | 1.00 |
+| start-exact recall | 0.77 | 0.955 |
+| event F1 | 0.81 | 0.977 |
+
+The standout is **clarification discipline** — the fine-tune reliably asks when a thread is "date TBD" instead of guessing, where the base model sometimes plows ahead. The base model is genuinely strong on this narrow task, so rather than argue about it, **the eval decides what production serves** — and the published fine-tune stands as the Well-Tuned artifact.
+
+**Where fine-tuning shines: the edge model.** The effort re-aimed at a **Gemma 4 E4B (~4B)** model that runs on the **free CPU tier** — no paid GPU. Six gated runs, each fixing a diagnosed miss, with schema validity holding at **1.0 the entire time**. On an expanded 60-example eval, the fine-tuned E4B landed at **F1 0.97 / recall 0.96 / clarification 1.0** — an exact statistical tie with stock E4B (identical 48/1/2 true/false/missed), at **zero quality cost** and on a model small enough to run on a laptop. An own, local, parity fine-tune is exactly the "small + well-tuned" sweet spot the constraint rewards.
+
+Two honest notes the eval forced onto the page:
+- **Quantization was exonerated.** The same weights, scored at f16 / Q8 / Q4 — precision wasn't the bottleneck. Good to know before chasing a fix that wouldn't have helped.
+- **Both the base and the fine-tune are ≤ 32B** (31B and ~4B), satisfying the size constraint, and the "no cloud AI" rule applies to the *running app* — dataset prep can use any offline tooling.
+
+## Off the grid: llama.cpp in a Space
+
+"Local-first" meant: inference runs **in the Space**, not via a hosted LLM API. The build started on ZeroGPU but pivoted to a **Docker Space** built on the official `ggml-org/llama.cpp` image — `llama-server` is always warm, and (crucially) there's no multi-minute build cost compiling llama.cpp from source on the free builders. The big 31B GGUF wants a GPU; the **E4B variant runs on the free CPU tier**, which is the honest "runs on a laptop" story. Running the agents spins up a **second** local `llama-server` for the MiniCPM5-1B planner — still entirely on-box.
+
+The whole point: your messages never touch a third-party AI service. The default output is a file you own.
+
+## From app to agent: MCP, memory, and shared traces
+
+**It's an MCP server.** Gradio's `mcp_server=True` turns typed functions into tools any MCP-aware client (Claude Desktop, Cursor, …) can call — so a larger agent can use scheduling as an **off-grid skill**:
+
+```python
+def extract_events(thread: str, images: list[str] | None = None) -> dict:
+    """Extract calendar events from a chat thread (and optional screenshots).
+
+    Args:
+        thread: the conversation text to scan for events.
+        images: optional base64 data-URIs of screenshots.
+    Returns: an ActionPlan (events, conflicts, proposed_times, reply_draft).
+    """
+```
+
+…plus `make_ics(events)` and `check_conflicts(events, ics_base64)`. The MCP schema is generated straight from the type hints and docstrings.
+
+**…and it consumes its own tools.** Click **Run the agents** and the loop closes: a local **OpenBMB MiniCPM5-1B** planner drives those same MCP tools as a multi-step agent — `extract_events` → `check_conflicts` → `make_ics` — with every step streamed to the UI. So the Space is *both sides* of MCP at once: it **exposes** scheduling as tools, and it **uses** them, planned by a second small model. Still no cloud AI — the planner is a second local `llama-server`, and if it isn't configured the orchestrator falls back to a deterministic scripted plan, so it works either way.
+
+**Memory that grows with you, on *your* device.** Facts like *"Dana is the soccer coach"* or *"you decline Mondays"* personalize every extraction. They live in your browser's **localStorage** — per-user by default, never on a server — and are injected into the prompt at run time. You can seed them with a 10-second onboarding, or import contacts (`.vcf`/CSV) and a calendar (`.ics`), parsed locally.
+
+**Sharing is Caring.** One click publishes a **redacted** run trace to a public dataset, [`offgridschedula-traces`](https://huggingface.co/datasets/ParetoOptimal/offgridschedula-traces), for others to learn from. The trace is structural by design — counts and stage names, never your chat text — and redaction is forced for anything public.
+
+## Built small, by the rules: constraints & badges
+
+Build Small comes with hard rules and a sash of collectable badges. Here's the honest scorecard.
+
+**The hard constraints.**
+- **Every model ≤ 32B.** Two models, both far under the cap: extraction is **`gemma-cal` E4B** (~4B effective params, ~5 GB at Q4) and planning is **OpenBMB MiniCPM5-1B** (1B). No frontier API anywhere in the loop.
+- **A Gradio app on a Hugging Face Space.** A Gradio 6 Blocks UI mounted on a **Docker SDK** Space running llama.cpp.
+- **A demo video and a social post, linked from the README.** [▶ Demo video](https://youtu.be/m-o0u9X3tI4) · social posts on [X (1)](https://x.com/nate_mauer/status/2064920352845709419) and [X (2)](https://x.com/nate_mauer/status/2065661878441750916).
+- **README frontmatter tags + a short write-up.** Namespaced `track:*` / `sponsor:*` / `achievement:*` tags and the idea-and-tech write-up live at the top of the README.
+- **No ZeroGPU sprawl.** Runs on a single dedicated T4 — and, in stub mode, the **free CPU tier** — so there's no ZeroGPU dependency to cap.
+
+**The track and the sponsors.**
+- 🏡 **Backyard AI** — built for one specific real person (the busy parent), not "users" in the abstract. Short pasted chats and screenshots are exactly a small local model's wheelhouse — an honest fit, not a stretch.
+- 🟢 **Modal** — the whole fine-tune lifecycle ran on Modal serverless GPUs: dataset → QLoRA train → GGUF export → the 60-example eval → the gate that rejected eight regressed models before this one shipped.
+- 🌱 **OpenBMB MiniCPM** — the planner behind **Run the agents**, driving the Space's own MCP tools as a visible multi-step agent.
+
+**The six badges — all claimed.**
+- 🔌 **Off the Grid** — all inference is local llama.cpp; no cloud AI APIs. The only optional outbound call is *your* Google Calendar push.
+- 🎯 **Well-Tuned** — [`gemma-cal` E4B](https://huggingface.co/build-small-hackathon/gemma-4-cal-gguf), the published QLoRA fine-tune, is the model production serves — shipped through the eval gate with the scorecard public.
+- 🎨 **Off-Brand** — a bespoke landing page, hero + carousel, grouped nav, and custom results/Activity surfaces, far past the stock Gradio look.
+- 🦙 **Llama Champion** — the official `ggml-org/llama.cpp` server image runs the GGUF + vision mmproj.
+- 📡 **Sharing is Caring** — one click publishes a **redacted** run trace to the public [`offgridschedula-traces`](https://huggingface.co/datasets/ParetoOptimal/offgridschedula-traces) dataset.
+- 📓 **Field Notes** — [this post](https://huggingface.co/blog/build-small-hackathon/offgridschedula), plus `FIELD_NOTES.md` (the build retrospective) and the eval-gated fine-tuning post-mortem.
+
+Two honest footnotes the rules deserve: E4B is a MatFormer **"effective-4B"** (judges' call on whether that's *tiny* enough for the Tiny Titan nod), and the "no cloud AI" rule applies to the **running app** — the offline dataset prep and training on Modal are fair game.
+
+## Lessons learned
+
+A field-notes dump of things that cost time here so they don't cost yours:
+
+> **Gradio 6 ignores `css=`/`js=` set on `gr.Blocks` when it's mounted under FastAPI.** Custom styling silently doesn't apply. The fix that stuck: inject the CSS at mount time and the JS as a real inline `<script>` before `</body>` via middleware, so it always executes:
+> ```python
+> html = html.replace("</body>", f"<script>({CAROUSEL_JS})()</script></body>")
+> ```
+
+> **`display:none` ≠ "responsive."** Gradio's tab strip needed explicit CSS to hide on narrow screens; the nav buttons click the *real* hidden Gradio tabs underneath. A `MutationObserver` re-wires everything after each Gradio swap so dynamic updates don't break it.
+
+> **Make the expensive dependency optional on day one.** The stub extractor + lazy imports meant the same codebase is the test harness, the offline demo, and the free tier — all at once.
+
+> **The HF MCP badge is Gradio-SDK only.** A pure FastAPI app or a bare `llama-server` won't advertise MCP; you need Gradio's `mcp_server=True` and typed, docstringed tool functions.
+
+> **Traces are redacted by construction, not after the fact.** The activity bus only ever emits counts and short status strings; the one free-text field (a chat name) is stripped. An allowlist beats a denylist when the cost of a leak is someone's private calendar.
+
+> **Be honest about "off the grid."** A 31B GGUF (~18–20 GB) wants a GPU — and "your own cloud GPU" is easy to conflate with "a cloud AI API." The headline model stayed honest, and the E4B edge variant shipped as the truly-local path.
+
+And the meta-lesson: **an eval that gates publishing changes how you work.** Once "does it beat the bar?" is automated, you stop arguing about vibes and start shipping only what's measurably better — or, as happened here, a strong prompt on a capable base turns out to be the right answer sometimes, and the fine-tune is kept for where it actually wins.
+
+## What's next
+
+- Polish the optional Mac collector (reading `~/Library/Messages/chat.db`, including the `attributedBody` blobs modern Messages uses).
+- Grow the on-device memory beyond contacts and preferences.
+- Push the E4B edge model further so the fully-local path matches the 31B headline on the hardest relative-date cases.
+
+## Get started
+
+- **Try it (30 seconds, no install):** open the [Space](https://huggingface.co/spaces/build-small-hackathon/OffGridSchedula), tap **Try a sample**, and watch a chat become events + a conflict check + a reply.
+- **The model:** [`build-small-hackathon/gemma-4-cal-gguf`](https://huggingface.co/build-small-hackathon/gemma-4-cal-gguf) (QLoRA fine-tune of Gemma 4, GGUF for llama.cpp).
+- **The planner:** [`openbmb/MiniCPM5-1B-GGUF`](https://huggingface.co/openbmb/MiniCPM5-1B-GGUF) — drives the multi-step orchestration behind **Run the agents**, locally via llama.cpp.
+- **The traces dataset:** [`ParetoOptimal/offgridschedula-traces`](https://huggingface.co/datasets/ParetoOptimal/offgridschedula-traces).
+- **Use it as a tool:** add the Space as an MCP server and call `extract_events` from your own agent.
+
+## Acknowledgements & citation
+
+Built on the shoulders of [Gemma 4](https://huggingface.co/google), [OpenBMB MiniCPM](https://huggingface.co/openbmb), [llama.cpp / ggml](https://github.com/ggml-org/llama.cpp), [Gradio](https://www.gradio.app/), and [Unsloth](https://github.com/unslothai/unsloth). Training data uses **SMCalFlow** (Semantic Machines et al., *"Task-Oriented Dialogue as Dataflow Synthesis,"* TACL 2020; CC BY-SA 4.0).
+
+```bibtex
+@misc{offgridschedula2026,
+  title  = {OffGridSchedula: a local-first, fine-tuned scheduling agent},
+  author = {ParetoOptimal},
+  year   = {2026},
+  howpublished = {\url{https://huggingface.co/blog/build-small-hackathon/offgridschedula}}
+}
+```

docs/demo-script.md

@@ -0,0 +1,34 @@
+# OffGridSchedula — 95-second demo video script & storyboard
+
+**Goal:** show a real busy parent turn a messy group chat into calendar events — locally, on a small
+model — and name every claimed bonus quest out loud at its evidence moment. "Show, tell the judges."
+
+> Recording it? The full operator's runbook — environment prep, demo-calendar
+> setup, the talk track and the reasoning behind each line —
+> is in **[demo-walkthrough.md](./demo-walkthrough.md)**.
+
+**Model:** `ParetoOptimal/gemma-4-cal-gguf` — our fine-tune of **Gemma E4B** (~4B effective
+params, far under the 32B cap), run via llama.cpp. (The 31B gguf in the repo is a legacy
+artifact; the platform serves the E4B.)
+
+**Bonus quests called out on camera** (field-guide names, verbatim): **Off the Grid** ·
+**Well-Tuned** · **Llama Champion** · **Sharing is Caring** · **Off-Brand**. The sixth claimed
+quest, **Field Notes**, lives on the end card + README (it's a write-up, not a screen).
+
+| # | Time | Shot (visual) | Voiceover / on-screen text |
+|---|------|---------------|----------------------------|
+| 1 | 0:00–0:08 | Phone screen: a noisy class group chat scrolling ("Picture day Thursday 9am", "practice moved to Tuesday", "RSVP by Friday"). | "Every parent knows this chat. The dates are in here — and they're easy to miss." |
+| 2 | 0:08–0:20 | Open the Space in a phone browser. Hero: *Catch every invite before it slips away.* Zoom the 🔒 badge. | "OffGridSchedula. No app, no account — a small model runs right in the Space. No cloud APIs anywhere: that's the **Off the Grid** quest — the whole thing runs on the model in front of you." |
+| 3 | 0:20–0:34 | Paste the chat → tap **Find the events**. The "thinking" panel streams; flash the HF model card. | "Paste the chat. The model reading it is **Well-Tuned** — our own fine-tune of Gemma, published on Hugging Face with its eval scorecard — running through the llama.cpp runtime: **Llama Champion**." |
+| 4 | 0:34–0:48 | Results: event cards (Picture Day · Thu 9:00, Practice · Tue 5:00), a ⚠️ conflict badge, free-time chips. | "It pulls out the events, checks them against your calendar, and catches the clash — before anything is saved." |
+| 5 | 0:48–0:58 | Screenshot/flyer upload → an event appears from the image. | "A flyer or screenshot works too — the same local model reads the date, time and place from the picture." |
+| 6 | 0:58–1:10 | Copy the ready-to-send reply; tap **Download .ics**; event drops into the calendar. | "It even drafts the reply. Then the events drop into your calendar — Google, Apple, anything that takes a .ics." |
+| 7 | 1:10–1:22 | Activity tab: live pipeline → click **share trace** → the public Hub dataset page. | "Every agent run is observable — and one click publishes a redacted trace to a public dataset for anyone to learn from. **Sharing is Caring**: the open-trace quest." |
+| 8 | 1:22–1:35 | Slow pan over the custom landing page → **🏆 Submission** tab scorecard (all six quests green) → end card with Space URL. | "And everything you've watched is a custom frontend pushed far past the default Gradio look — **Off-Brand**. Local-first, fine-tuned, llama.cpp, open traces, custom UI — built small, by the rules. Try it free — link below." |
+
+**B-roll / cutaways:** the rotating use-case cards (carpool, appointments, parties); the Activity tab's
+"time saved this week" tiles.
+
+**Capture tips:** record the phone browser at 1080×1920; keep the cursor visible on desktop shots; show
+the network panel offline once to prove no cloud calls; pre-load the traces dataset page in a tab
+for shot 7.

docs/demo-walkthrough.md

@@ -0,0 +1,127 @@
+# Demo video — recording walkthrough & talk track
+
+The end-to-end runbook for recording the public demo video: environment prep,
+the shot-by-shot walkthrough with the exact talk track, and *why each line is
+worded the way it is*. The compact storyboard lives in
+[demo-script.md](./demo-script.md); this document is the operator's guide for
+actually producing it for a general-public audience (the hackathon
+Submission-tab finale is replaced with a public closer).
+
+## Decisions baked into this walkthrough
+
+- **Backend: the live GPU Space.** Record against the real model — streaming
+  output, real extraction, working vision. Never record stub mode
+  (`USE_STUB_EXTRACTOR=1` output is visibly fake and vision is disabled).
+- **Calendar: a brand-new demo Google account** (e.g. `offgridschedula.demo@`),
+  not a personal calendar. Zero PII can appear on camera — no real events, no
+  real email in the OAuth chrome — and the calendar is seeded with exactly the
+  event that produces the on-screen conflict.
+- **The on-camera "event lands in the calendar" moment uses .ics import**, not
+  a server-side OAuth push. `credentials.json`/`token.json` must never live on
+  the public Space; importing the downloaded .ics into the demo account's
+  Google Calendar shows the same payoff with zero server credentials. (An
+  optional locally-recorded one-click-push splice is described at the end.)
+
+## Part A — Prep (before recording day)
+
+### A1. Demo Google account
+1. Create the account; set a neutral profile name ("OffGrid Demo").
+2. In its Google Calendar (local timezone), seed **one clashing event**:
+   `Dentist — Tuesday 5:00 PM`. It collides with "practice moved to Tuesday
+   5pm" in the UI's built-in sample thread, which is what makes the ⚠️ conflict
+   badge fire on camera. Add 1–2 filler events so the calendar looks lived-in.
+3. Export the calendar (Settings → Import & export → Export) and save the
+   unzipped file as `demo-existing-calendar.ics` — this gets uploaded in the UI.
+
+### A2. Assets
+- **Flyer image** for the vision shot: a simple school-event flyer (title,
+  date, time, place) as PNG/JPEG — *not HEIC* (the vision pipeline can't decode
+  it), under 4 MB.
+- **Staged iMessage chat** for the opening phone shot: stage a group chat with
+  demo contacts containing the storyboard lines ("Picture day Thursday 9am",
+  "practice moved to Tuesday 5", "RSVP by Friday") and screen-record it
+  scrolling. Never show a real chat.
+
+### A3. Space
+1. Put the Docker Space on a GPU tier (T4 is enough for E4B) and **restart
+   it** — restarting also clears `/tmp`, so no previously-ingested feed data is
+   visible anywhere in the UI.
+2. Confirm `USE_STUB_EXTRACTOR` is unset and `MMPROJ_FILE` is set (vision).
+3. Dry-run after llama-server health is green: sample thread → real streamed
+   output; upload `demo-existing-calendar.ics` → conflict badge; flyer → event
+   from image.
+4. Relative dates resolve from the **server clock (UTC)** — check the dry-run
+   dates land on the expected weekdays and adjust the seeded Dentist event if
+   needed.
+
+### A4. Recording
+- 1080p+ screen capture (QuickTime / OBS) in a **clean browser profile** logged
+  into the demo Google account only.
+- Record the voiceover separately after screen capture — cleaner than
+  narrating live, and the talk track below is written to be read.
+
+## Part B — Shot list with talk track
+
+| # | Time | Screen | Action | Talk track |
+|---|------|--------|--------|------------|
+| 1 | 0:00–0:08 | iPhone clip | Staged class group chat scrolls past | "Every parent knows this chat. The dates are in here — and they're easy to miss." |
+| 2 | 0:08–0:20 | Browser | Open the Space; hero + badges visible; zoom the 🔒 badge | "OffGridSchedula. No app, no account — a small model runs right in the Space. No cloud APIs anywhere: that's the **Off the Grid** quest — local-first, the whole thing runs on the model in front of you." |
+| 3 | 0:20–0:34 | Schedule flow | Upload `demo-existing-calendar.ics` first, then tap **Try a sample**; thinking panel streams; flash the model card link | "Paste the chat. The model reading it is **Well-Tuned** — our own fine-tune of Gemma, published on Hugging Face with its eval scorecard — and it runs through the llama.cpp runtime: **Llama Champion**." |
+| 4 | 0:34–0:48 | Results | Event cards appear; ⚠️ conflict vs Dentist; free-slot chips | "It pulls out the events, checks your calendar, and catches the clash — before anything is saved." |
+| 5 | 0:48–0:58 | Vision | Start over → drop in the flyer PNG → event extracted from the image | "A flyer or screenshot works too — the same local model reads the date, time and place right off the picture." |
+| 6 | 0:58–1:10 | Export | Copy the drafted reply; **Download .ics**; switch tabs and import it into the demo Google Calendar — events appear on the grid | "It drafts the reply, and the events drop straight into your calendar — Google, Apple, anything that takes a .ics." |
+| 7 | 1:10–1:22 | Activity | Activity tab's live pipeline; click **share trace**; the public dataset page flashes | "Every agent run is observable — and one click publishes a redacted trace to a public Hub dataset for anyone to learn from. That's **Sharing is Caring**: the open trace quest." |
+| 8 | 1:22–1:35 | Closer | Slow pan over the custom landing page → end card with the Space URL | "And everything you've watched — the hero, the cards, that dashboard — is a custom frontend pushed far past the default Gradio look: **Off-Brand**. Open source, runs locally, your messages never leave the machine. Try it free — link below." |
+
+Tip for shot 6: pre-open the demo calendar's import dialog in a second tab so
+the on-camera import is two clicks. Tip for shot 7: have the
+`ParetoOptimal/offgridschedula-traces` dataset page pre-loaded in a tab so the
+"published" beat is one cut, not a page load.
+
+## Why the talk track is worded this way
+
+- **Shot 1 names the pain before the product.** "Every parent knows this chat"
+  earns the next 60 seconds from a general audience that has never heard of
+  local LLMs — the hook is the missed pickup, not the model.
+- **The bonus quests are named out loud, verbatim, at their evidence moments.**
+  This track serves two audiences at once: the public hook stays in shots 1
+  and 4–6, while the field guide's quest names — **Off the Grid** (local-first,
+  no cloud APIs), **Well-Tuned** (published fine-tune), **Llama Champion**
+  (llama.cpp runtime), **Sharing is Caring** (open trace on the Hub), and
+  **Off-Brand** (custom UI past stock Gradio) — are each spoken exactly when
+  the screen shows the proof. Judges score the video against those names;
+  making them explicit means no claimed quest can be missed on a single watch.
+  (The sixth claimed quest, **Field Notes**, is print, not screen — it lives on
+  the end card and in the README, not the voiceover.)
+- **Shot 2 still kills the two adoption objections immediately** ("no app, no
+  account") before the first quest callout — the badge language is framed as a
+  plain-English promise ("the whole thing runs on the model in front of you"),
+  so the callout lands for laypeople too.
+- **Shot 4's "before anything is saved"** is the trust beat — the agent
+  proposes, the human disposes. This line pre-empts the "AI touched my
+  calendar" fear that kills scheduling tools.
+- **Shot 6 generalizes the payoff** ("Google, Apple, anything that takes a
+  .ics") so the demo doesn't read as Google-only — and the on-screen action
+  matches the off-grid story: a local file the user chooses to import.
+- **Shot 8 closes on the three-word value stack** — open source, local,
+  private — and a single call to action, with the Off-Brand callout folded
+  into the visual it describes. People remember one URL and one feeling.
+
+## Part C — Edit & publish
+
+- Assemble: phone clip → screen capture → end card. Speed-ramp model wait time
+  but keep ~2 s of genuine streaming so it reads as live.
+- Burn in captions (most social viewers watch muted). Export 1920×1080;
+  optionally a 1080×1920 vertical crop of shots 3–6 for Shorts/Reels.
+- Pair with the draft copy in [social-post.md](./social-post.md); link the
+  video from the README (Build Small hard rule #3).
+- **Pause or downgrade the GPU Space after recording** unless the closer is
+  meant to drive live traffic.
+
+## Optional: one-click Google Calendar push splice
+
+To show the actual **Add to Google Calendar** button instead of the .ics
+import: run the app locally, complete the one-time OAuth flow as the *demo*
+account to mint a local `token.json`, enable the toggle, and record just that
+click — the UI is pixel-identical and splices cleanly. Never upload
+`credentials.json`/`token.json` to the public Space.

server/orchestrator.py

@@ -169,13 +169,17 @@ def _smol_steps(thread: str, ics_b64: Optional[str],
 def run_orchestrator(thread: str, ics_b64: Optional[str] = None,
                      memory_block: Optional[str] = None,
                      max_steps: int = 6,
-                     images: Optional[list[str]] = None) -> Iterator[dict]:
+                     images: Optional[list[str]] = None,
+                     use_planner: bool = True) -> Iterator[dict]:
     """Yield orchestration steps for a thread (+ optional screenshot data URIs);
     always ends with a 'final' step (or an 'error' followed by the scripted
-    fallback's steps)."""
+    fallback's steps).
+
+    Pass use_planner=False to skip the MiniCPM planner entirely and run the
+    deterministic scripted path directly (e.g. homepage fast path)."""
     with bus.run_scope("agent"):
         bus.emit("decision", "agent orchestrator run started")
-        if _use_llm_planner():
+        if use_planner and _use_llm_planner():
             try:
                 yield from _smol_steps(thread, ics_b64, memory_block, max_steps, images)
                 bus.emit("decision", "agent orchestrator run finished (MiniCPM planner)")

static/app.css

@@ -946,18 +946,3 @@ a.footer-cta:hover { transform: translateY(-2px); filter: brightness(1.07); }
 /* Footer: keep "on Hugging Face" (its own <a> in .footer-meta) on one line
    instead of breaking as "on Hugging" / "Face". */
 .footer-meta a { white-space: nowrap; }
-
-/* Hardware-degraded banner — revealed by app.py's /health probe (inline JS).
-   Hidden by default; the script sets display:block when the model is on weak
-   hardware (e.g. real model on a CPU-only Space). */
-#status-banner-host { padding: 0; margin: 0; }
-.status-banner {
-  display: none;
-  padding: 10px 16px;
-  text-align: center;
-  font-weight: 600;
-  font-size: 0.95rem;
-  line-height: 1.4;
-  background: var(--accent);
-  color: #fff;
-}

ui/blocks.py

@@ -807,7 +807,8 @@ def _on_analyze(conversation: str, cal_path, image_paths, mem_json: str = ""):
     steps: list[dict] = []
     final = None
     for step in run_orchestrator(conversation or "", ics_b64=ics_b64,
-                                 memory_block=memory_block, images=images or None):
+                                 memory_block=memory_block, images=images or None,
+                                 use_planner=False):
         steps.append(step)
         if step.get("kind") == "final":
             final = step
@@ -1887,11 +1888,6 @@ def build_demo() -> gr.Blocks:
     # Theme/css set on the Blocks so the Off-Brand look applies no matter who
     # launches it (our uvicorn locally, or HF's gradio runtime on a Spaces deploy).
     with gr.Blocks(theme=THEME, css=CSS, title="OffGridSchedula") as demo:
-        # Hardware-degraded banner — hidden by default. app.py injects a tiny
-        # script that calls /health on load and reveals this when the model is on
-        # inadequate hardware (e.g. real model on a CPU-only Space).
-        gr.HTML('<div id="status-banner" class="status-banner" role="alert"></div>',
-                elem_id="status-banner-host")
         gr.HTML(_nav_html())
 
         # Per-user memory lives in the visitor's browser (localStorage); this hidden