whatfirst-small: offline Gradio + llama.cpp task prioritizer

HF Build Small hackathon entry (Backyard AI). A small local VLM
(Qwen2.5-VL-3B via llama.cpp) turns a brain-dump or a photo of a to-do
list into structured tasks; a clean-room Python port of the what-first.com
scoring engine ranks them transparently.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.dockerignore

@@ -0,0 +1,8 @@
+.git
+__pycache__/
+*.pyc
+*.gguf
+models/
+.gradio/
+.venv/
+plan/

.gitattributes

@@ -0,0 +1 @@
+*.ttf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.gguf
+models/
+.gradio/
+.venv/
+.DS_Store

Dockerfile

@@ -0,0 +1,36 @@
+# whatfirst-small — Gradio app + a local llama.cpp server, one container.
+# Builds llama-server (multimodal) from source, then runs the Gradio UI in front
+# of it. No cloud APIs at runtime.
+
+FROM python:3.11-slim
+
+# --- build llama.cpp (llama-server includes multimodal / mtmd support) -------
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential cmake git libgomp1 ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN git clone --depth 1 https://github.com/ggml-org/llama.cpp /opt/llama.cpp \
+    && cmake -S /opt/llama.cpp -B /opt/llama.cpp/build \
+        -DGGML_NATIVE=OFF -DLLAMA_CURL=OFF -DLLAMA_BUILD_TESTS=OFF \
+    && cmake --build /opt/llama.cpp/build --config Release -j --target llama-server \
+    && rm -rf /opt/llama.cpp/.git
+
+# --- non-root user (Hugging Face Spaces convention) --------------------------
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    HF_HOME=/home/user/.cache/huggingface \
+    MODEL_DIR=/home/user/models \
+    MODEL_REPO=ggml-org/Qwen2.5-VL-3B-Instruct-GGUF \
+    MODEL_FILE=Qwen2.5-VL-3B-Instruct-Q4_K_M.gguf \
+    MMPROJ_FILE=mmproj-Qwen2.5-VL-3B-Instruct-f16.gguf \
+    PORT=7860
+
+WORKDIR /home/user/app
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+COPY --chown=user . .
+
+EXPOSE 7860
+CMD ["bash", "start.sh"]

README.md

@@ -0,0 +1,79 @@
+---
+title: whatfirst small
+emoji: 🗂️
+colorFrom: indigo
+colorTo: blue
+sdk: docker
+app_port: 7860
+pinned: false
+license: apache-2.0
+---
+
+# whatfirst · small
+
+**Dump everything on your mind — get back what to do *first*, with the math shown.**
+
+A small **local** vision-language model (Qwen2.5-VL-3B, ~2 GB, running on
+llama.cpp) reads a messy brain-dump or a photo of a to-do list and turns each
+line into a structured task — impact, readiness, effort, deadline. A
+**deterministic, transparent scoring engine** then ranks them and tells you the
+one thing to start now, showing every number behind the call. No cloud, no API
+keys, runs on a laptop.
+
+Built for the [Hugging Face Build Small hackathon](https://huggingface.co/build-small-hackathon)
+(Backyard AI track).
+
+## Why this exists
+
+Deciding *what to do first* is a real, daily problem — and most "AI to-do" apps
+answer it with a black box. This one keeps the AI where it earns its keep (turning
+vague human language into structured fields) and makes the prioritization itself
+**legible**: two competing scores (do-it-now vs. de-risk-first), an urgency curve
+that explodes as a deadline nears, a quick-win boost for short ready tasks, and
+deadlines treated as a hard constraint rather than a number folded into a blob.
+
+The problem, and the scoring model, come from
+**[what-first.com](https://what-first.com)** — a full web app the same team built
+in June 2026, where the scoring runs server-side against Claude. This entry is a
+fresh, **offline, small-model** take built for the hackathon: can a 3B model on a
+laptop do the load-bearing language work that a frontier cloud model does in the
+product? The ranking engine here is a clean-room reimplementation in Python with
+its own tests — no dependency on the original.
+
+## How it works
+
+```
+brain-dump / photo  ──▶  Qwen2.5-VL-3B (llama.cpp, localhost)  ──▶  structured tasks
+                                                                          │
+                                                              score.py (deterministic)
+                                                                          │
+                                                          ranked list + "do this first"
+```
+
+- `score.py` — the scoring + deadline-ranking engine (pure standard-library math).
+- `llm.py` — client for the local llama.cpp server (brain-dump parse, image
+  extract, single-task re-score). Every model output is re-clamped before scoring.
+- `prompts.py` — the system prompts that pin the model to strict JSON.
+- `app.py` — the Gradio UI: capture, ranked table, and sliders to correct any
+  score and re-rank live.
+
+## Run it locally
+
+```bash
+docker build -t whatfirst-small .
+docker run -p 7860:7860 whatfirst-small   # first boot downloads ~2.3 GB of weights
+```
+
+Then open http://localhost:7860. On a CPU-only box, expect a few seconds per task
+— that's the cost of staying fully on the grid-less side. Tests:
+
+```bash
+python -m pytest test_score.py    # or: python test_score.py
+```
+
+## Notes
+
+- **Model:** [`ggml-org/Qwen2.5-VL-3B-Instruct-GGUF`](https://huggingface.co/ggml-org/Qwen2.5-VL-3B-Instruct-GGUF)
+  (Q4_K_M + f16 mmproj), ≤ 32B and laptop-runnable.
+- **Off the grid:** all inference is local llama.cpp over localhost; nothing
+  leaves the box at runtime.

app.py

@@ -0,0 +1,172 @@
+"""whatfirst-small — a Gradio app that turns a messy brain-dump (or a photo of a
+to-do list) into a transparently-ranked "do this first" list, using a small
+local model for the messy-language part and a deterministic, legible engine for
+the ranking.
+
+Capture -> AI structures each task (impact / readiness / effort / due) -> the
+scoring engine ranks -> you can correct any score and it re-ranks live.
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+
+import gradio as gr
+
+import llm
+import score
+
+SAMPLE_DUMP = """email the landlord about the lease renewal, kind of important and due Friday
+finish the Q3 board deck — big deal, maybe 4 hours of work, needs to be done by next Wednesday
+5 min: cancel the unused gym membership
+look into switching the team to the new CI, no rush, not sure where to start
+book the dentist, due tomorrow
+reply to Sam's thread, quick one
+draft the hiring plan — important but I'm blocked until we agree on budget"""
+
+FORMULA_BLURB = """
+Two scores compete and the higher one shows:
+
+- **do = (Impact · Urgency · Readiness_eff · QuickWin) / 10** — the case for doing it now.
+- **prep = (Impact · Urgency · (10 − Readiness)) / 10 · 0.7 · QuickWin** — the case for de-risking it first (wins only when a task is valuable but not ready).
+
+**Urgency** climbs as a deadline nears and *explodes* once it's within a day, so a looming deadline can't be buried by a shiny far-off task. **QuickWin** rewards short, ready tasks. Deadlines act as a *constraint*, not just a term: anything overdue, or that genuinely won't finish in time given everything ahead of it, is lifted above the value pack. Every number is shown — nothing is a black box.
+"""
+
+DF_HEADERS = ["#", "Task", "Score", "Due", "Flag", "Why", "I", "R", "Eff·h"]
+DF_DATATYPES = ["number", "str", "str", "str", "str", "str", "number", "number", "number"]
+
+
+def _label(t: dict) -> str:
+    return f"{t['id']} · {t['title']}"
+
+
+def render(tasks: list[dict]):
+    """tasks -> (header_md, dataframe_rows, dropdown_choices)."""
+    if not tasks:
+        return "### Add a brain-dump or a photo, then hit **Prioritize**.", [], []
+    now = datetime.now()
+    ranked = score.rank_active(tasks, now)
+    risk = score.deadline_risk_map(ranked, now)
+    rows = []
+    for i, t in enumerate(ranked):
+        c = score.score_components(t)
+        flag = score.deadline_status(t, now) or risk.get(t["id"], "")
+        rows.append([
+            i + 1,
+            t["title"],
+            score.format_score(c["display"]),
+            score.due_label(t.get("due_date"), now) if t.get("due_date") else "—",
+            flag,
+            t.get("reason", "") or "",
+            round(c["I"]),
+            round(c["R"]),
+            round(t["effort_hours"], 2),
+        ])
+    top = ranked[0]
+    header = f"### ▶ Do this first: **{top['title']}**  ·  score {score.format_score(score.priority(top))}"
+    return header, rows, [_label(t) for t in ranked]
+
+
+def prioritize(text, image, tasks):
+    if not llm.is_ready():
+        return tasks, "### ⏳ The local model is still loading — give it a moment and try again.", [], gr.update()
+    collected = []
+    if text and text.strip():
+        collected += llm.parse_braindump(text)
+    if image is not None:
+        collected += llm.extract_from_image(image)
+    for i, t in enumerate(collected):
+        t["id"] = f"t{i}"
+    if not collected:
+        return collected, "### Nothing actionable found — try a different dump or photo.", [], gr.update(choices=[], value=None)
+    header, rows, choices = render(collected)
+    return collected, header, rows, gr.update(choices=choices, value=(choices[0] if choices else None))
+
+
+def load_task(sel, tasks):
+    t = _find(sel, tasks)
+    if not t:
+        return 5, 8, 1.0
+    return t["impact"], t["readiness"], t["effort_hours"]
+
+
+def apply_edit(sel, impact, readiness, effort, tasks):
+    t = _find(sel, tasks)
+    if t:
+        t["impact"] = int(impact)
+        t["readiness"] = int(readiness)
+        t["effort_hours"] = float(effort)
+        t["reason"] = (t.get("reason") or "").split(" · edited")[0] + " · edited"
+    header, rows, choices = render(tasks)
+    keep = sel if sel in choices else (choices[0] if choices else None)
+    return tasks, header, rows, gr.update(choices=choices, value=keep)
+
+
+def resuggest(sel, tasks):
+    t = _find(sel, tasks)
+    if not t or not llm.is_ready():
+        return gr.update(), gr.update(), gr.update()
+    s = llm.score_task(t["title"], t.get("notes") or "", t.get("category") or "")
+    if not s:
+        return t["impact"], t["readiness"], t["effort_hours"]
+    return s["impact"], s["readiness"], s["effort_hours"]
+
+
+def _find(sel, tasks):
+    if not sel:
+        return None
+    tid = sel.split(" · ", 1)[0]
+    return next((x for x in tasks if x["id"] == tid), None)
+
+
+with gr.Blocks(title="whatfirst-small", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        "# whatfirst · small\n"
+        "Dump everything on your mind — or snap a photo of your to-do list — and a "
+        "**small local model** turns it into structured tasks. A **transparent scoring "
+        "engine** then tells you what to do *first*, and shows its work. No cloud, no API keys."
+    )
+    tasks_state = gr.State([])
+
+    with gr.Row():
+        with gr.Column(scale=2):
+            dump = gr.Textbox(
+                label="Brain-dump", lines=8,
+                placeholder="email the landlord by Friday, finish the deck (4h, big deal), 5-min: cancel the gym…",
+            )
+            image = gr.Image(label="…or a photo of a list", type="pil", height=180)
+            with gr.Row():
+                go = gr.Button("Prioritize", variant="primary")
+                sample = gr.Button("Try a sample")
+        with gr.Column(scale=3):
+            header = gr.Markdown("### Add a brain-dump or a photo, then hit **Prioritize**.")
+            table = gr.Dataframe(
+                headers=DF_HEADERS, datatype=DF_DATATYPES, interactive=False,
+                wrap=True, label="Ranked",
+            )
+
+    with gr.Accordion("Correct a score (the model proposes — you decide)", open=False):
+        picker = gr.Dropdown(label="Task", choices=[], interactive=True)
+        with gr.Row():
+            impact = gr.Slider(1, 10, value=5, step=1, label="Impact")
+            readiness = gr.Slider(1, 10, value=8, step=1, label="Readiness")
+            effort = gr.Slider(0.05, 8, value=1.0, step=0.05, label="Effort (hours)")
+        with gr.Row():
+            apply_btn = gr.Button("Apply & re-rank", variant="primary")
+            resuggest_btn = gr.Button("Re-suggest with AI")
+
+    with gr.Accordion("How the score works", open=False):
+        gr.Markdown(FORMULA_BLURB)
+
+    go.click(prioritize, [dump, image, tasks_state], [tasks_state, header, table, picker])
+    sample.click(lambda: SAMPLE_DUMP, None, dump)
+    picker.change(load_task, [picker, tasks_state], [impact, readiness, effort])
+    apply_btn.click(apply_edit, [picker, impact, readiness, effort, tasks_state],
+                    [tasks_state, header, table, picker])
+    resuggest_btn.click(resuggest, [picker, tasks_state], [impact, readiness, effort])
+
+
+if __name__ == "__main__":
+    demo.launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", "7860")))

download_model.py

@@ -0,0 +1,27 @@
+"""Fetch the GGUF weights + vision projector from the Hub into MODEL_DIR.
+
+Run once at container start (idempotent — hf_hub_download skips files already
+present). Kept tiny and dependency-light so the container can pull the model
+before the server boots.
+"""
+
+import os
+
+from huggingface_hub import hf_hub_download
+
+REPO = os.environ.get("MODEL_REPO", "ggml-org/Qwen2.5-VL-3B-Instruct-GGUF")
+MODEL_FILE = os.environ.get("MODEL_FILE", "Qwen2.5-VL-3B-Instruct-Q4_K_M.gguf")
+MMPROJ_FILE = os.environ.get("MMPROJ_FILE", "mmproj-Qwen2.5-VL-3B-Instruct-f16.gguf")
+MODEL_DIR = os.environ.get("MODEL_DIR", "/models")
+
+
+def main():
+    os.makedirs(MODEL_DIR, exist_ok=True)
+    for fname in (MODEL_FILE, MMPROJ_FILE):
+        print(f"[download] {REPO}/{fname} -> {MODEL_DIR}", flush=True)
+        hf_hub_download(repo_id=REPO, filename=fname, local_dir=MODEL_DIR)
+    print("[download] done", flush=True)
+
+
+if __name__ == "__main__":
+    main()

llm.py

@@ -0,0 +1,238 @@
+"""Local model client.
+
+Talks to a llama.cpp `llama-server` running on localhost (OpenAI-compatible
+`/v1/chat/completions`, with multimodal support for the Qwen2.5-VL GGUF). One
+model serves all three flows. No network leaves the box — this is the
+"off the grid" path.
+
+Every model response is treated as untrusted: parsed tolerantly, then every
+field is re-clamped to its domain before it reaches score.py.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+import json
+import os
+from datetime import datetime
+
+import requests
+
+LLAMA_BASE_URL = os.environ.get("LLAMA_BASE_URL", "http://127.0.0.1:8080").rstrip("/")
+CHAT_URL = f"{LLAMA_BASE_URL}/v1/chat/completions"
+REQUEST_TIMEOUT = int(os.environ.get("LLM_TIMEOUT", "240"))  # CPU inference is slow
+
+from prompts import (
+    PARSE_SYSTEM_PROMPT, build_parse_user,
+    EXTRACT_SYSTEM_PROMPT, EXTRACT_USER_PROMPT,
+    SCORE_SYSTEM_PROMPT, build_score_user,
+)
+
+
+# -- server plumbing ----------------------------------------------------------
+
+def is_ready() -> bool:
+    """Has the model server come up and loaded weights?"""
+    try:
+        r = requests.get(f"{LLAMA_BASE_URL}/health", timeout=5)
+        return r.status_code == 200
+    except requests.RequestException:
+        return False
+
+
+def _chat(system: str, user_content, max_tokens: int) -> str:
+    """One chat completion with a JSON prefill. `user_content` is a string or an
+    OpenAI content-parts list (for images). Returns the raw assistant text with
+    the prefilled '{' restored."""
+    messages = [
+        {"role": "system", "content": system},
+        {"role": "user", "content": user_content},
+        {"role": "assistant", "content": "{"},  # prefill: coerce a JSON object
+    ]
+    payload = {
+        "messages": messages,
+        "max_tokens": max_tokens,
+        "temperature": 0.2,
+        "top_p": 0.9,
+        "stream": False,
+    }
+    r = requests.post(CHAT_URL, json=payload, timeout=REQUEST_TIMEOUT)
+    r.raise_for_status()
+    text = r.json()["choices"][0]["message"]["content"]
+    return "{" + text
+
+
+def _extract_json(text: str) -> dict:
+    """Tolerantly pull the first balanced JSON object out of a model response,
+    ignoring markdown fences and any trailing prose."""
+    text = text.strip()
+    if text.startswith("```"):
+        text = text.split("```", 2)[1] if "```" in text[3:] else text
+        text = text.lstrip("json").lstrip()
+    start = text.find("{")
+    if start == -1:
+        return {}
+    depth, in_str, esc = 0, False, False
+    for i in range(start, len(text)):
+        ch = text[i]
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+            continue
+        if ch == '"':
+            in_str = True
+        elif ch == "{":
+            depth += 1
+        elif ch == "}":
+            depth -= 1
+            if depth == 0:
+                try:
+                    return json.loads(text[start:i + 1])
+                except json.JSONDecodeError:
+                    return {}
+    return {}
+
+
+# -- validation ---------------------------------------------------------------
+
+def _clamp_int(v, lo, hi):
+    try:
+        n = round(float(v))
+    except (TypeError, ValueError):
+        return None
+    return max(lo, min(hi, n))
+
+
+def _clamp_num(v, lo, hi):
+    try:
+        n = float(v)
+    except (TypeError, ValueError):
+        return None
+    if n <= 0:
+        return None
+    return max(lo, min(hi, n))
+
+
+def _str_or_none(v, n):
+    if not isinstance(v, str):
+        return None
+    s = v.strip()[:n]
+    return s or None
+
+
+def _due_iso(date_v, time_v):
+    """Combine a model-proposed YYYY-MM-DD (+ optional HH:MM) into the ISO form
+    score.py expects, or None. Garbage shapes are dropped, not guessed."""
+    import re
+    if not isinstance(date_v, str) or not re.match(r"^\d{4}-\d{2}-\d{2}$", date_v.strip()):
+        return None
+    date = date_v.strip()
+    if isinstance(time_v, str) and re.match(r"^([01]\d|2[0-3]):[0-5]\d$", time_v.strip()):
+        return f"{date}T{time_v.strip()}:00"
+    return date  # score.py normalizes a bare date to 17:00
+
+
+def _sanitize_scored(raw: dict, idx: int) -> dict | None:
+    """A fully-scored item from PARSE: title + scores + optional due."""
+    title = _str_or_none(raw.get("title"), 90)
+    if not title:
+        return None
+    impact = _clamp_int(raw.get("impact"), 1, 10)
+    readiness = _clamp_int(raw.get("readiness"), 1, 10)
+    effort = _clamp_num(raw.get("effort_hours"), 0.05, 200)
+    return {
+        "id": f"t{idx}",
+        "title": title,
+        "category": _str_or_none(raw.get("category"), 80),
+        "notes": _str_or_none(raw.get("notes"), 400),
+        "due_date": _due_iso(raw.get("due_date"), raw.get("due_time")),
+        "impact": impact if impact is not None else 5,
+        "readiness": readiness if readiness is not None else 8,
+        "effort_hours": effort if effort is not None else 1.0,
+        "reason": _str_or_none(raw.get("reason"), 200) or "",
+        "completed": False,
+    }
+
+
+def _sanitize_titleonly(raw: dict) -> dict | None:
+    """An unscored item from EXTRACT: title + context only."""
+    title = _str_or_none(raw.get("title"), 90)
+    if not title:
+        return None
+    return {
+        "title": title,
+        "category": _str_or_none(raw.get("category"), 80),
+        "notes": _str_or_none(raw.get("notes"), 400),
+    }
+
+
+# -- flows --------------------------------------------------------------------
+
+def parse_braindump(text: str) -> list[dict]:
+    """Free-text brain-dump -> fully scored, ready-to-rank task dicts."""
+    if not text or not text.strip():
+        return []
+    now = datetime.now()
+    today = now.strftime("%Y-%m-%d")
+    weekday = now.strftime("%A")
+    out = _chat(PARSE_SYSTEM_PROMPT, build_parse_user(text, today, weekday), max_tokens=1800)
+    items = _extract_json(out).get("items", [])
+    if not isinstance(items, list):
+        return []
+    scored = [_sanitize_scored(it, i) for i, it in enumerate(items[:25])]
+    return [s for s in scored if s]
+
+
+def score_task(title: str, notes: str = "", category: str = "") -> dict | None:
+    """Re-score a single task (used by the slider 'suggest' button)."""
+    out = _chat(SCORE_SYSTEM_PROMPT, build_score_user(title, notes, category), max_tokens=200)
+    raw = _extract_json(out)
+    impact = _clamp_int(raw.get("impact"), 1, 10)
+    readiness = _clamp_int(raw.get("readiness"), 1, 10)
+    effort = _clamp_num(raw.get("effort_hours"), 0.05, 200)
+    if impact is None or readiness is None or effort is None:
+        return None
+    return {
+        "impact": impact,
+        "readiness": readiness,
+        "effort_hours": effort,
+        "reason": _str_or_none(raw.get("reason"), 200) or "",
+    }
+
+
+def extract_from_image(image) -> list[dict]:
+    """Photo of a list -> scored task dicts. Two calls: a vision pass pulls the
+    titles, then the text scorer scores them in one batch (keeps it to one
+    model, and the scorer is more reliable on text than the VLM head is)."""
+    if image is None:
+        return []
+    b64 = _png_b64(image)
+    content = [
+        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{b64}"}},
+        {"type": "text", "text": EXTRACT_USER_PROMPT},
+    ]
+    out = _chat(EXTRACT_SYSTEM_PROMPT, content, max_tokens=1024)
+    raw_items = _extract_json(out).get("items", [])
+    if not isinstance(raw_items, list):
+        return []
+    titles = [_sanitize_titleonly(it) for it in raw_items[:20]]
+    titles = [t for t in titles if t]
+    if not titles:
+        return []
+    # Score the extracted titles in one pass by feeding them as a brain-dump.
+    dump = "\n".join(
+        f"{t['title']}" + (f" — {t['notes']}" if t.get("notes") else "")
+        for t in titles
+    )
+    return parse_braindump(dump)
+
+
+def _png_b64(image) -> str:
+    buf = io.BytesIO()
+    image.convert("RGB").save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode("ascii")

prompts.py

@@ -0,0 +1,87 @@
+"""System prompts + user-message builders for the local model.
+
+Adapted from whatfirst's production prompts (the score / extract / voice system
+prompts), reshaped for a single small model running locally:
+
+  - PARSE   : free-text brain-dump  -> fully scored task items (one call)
+  - EXTRACT : a photo of a list     -> task items (titles only; scored after)
+  - SCORE   : one task              -> impact / readiness / effort (slider re-suggest)
+
+Every call uses the JSON-prefill trick (prefill the assistant turn with "{") so
+a small model continues the object instead of wrapping it in prose. All model
+output is untrusted and re-clamped in llm.py before it reaches the scorer.
+"""
+
+# Shared definitions of the three scoring axes, kept identical across prompts so
+# the model scores consistently whether it sees text or an image.
+SCALE_GUIDE = """impact: how much the task moves this person's life or work forward. 1 = trivial, 5 = meaningful, 10 = transformative.
+readiness: how clear the immediate next physical step is. 1 = blocked or ambiguous, 5 = partial, 10 = obvious next action.
+effort_hours: realistic focused time. 0.25 = 15 minutes, 1 = an hour, 8 = a day."""
+
+
+# -- PARSE: brain-dump text -> scored items -----------------------------------
+
+PARSE_SYSTEM_PROMPT = f"""You turn a messy brain-dump into a prioritized task list for a personal productivity app. The text is one person listing things they need to do; it may ramble, run several tasks together, or include filler.
+
+Output a JSON object: {{ "items": [ {{ "title": string, "category": string | null, "notes": string | null, "due_date": string | null, "due_time": string | null, "impact": integer, "readiness": integer, "effort_hours": number, "reason": string }} ] }}
+
+{SCALE_GUIDE}
+
+Rules:
+- title is a short imperative phrase, sentence case, no trailing period, under 90 characters. Prefer the person's own words.
+- category is a 1-2 word project name if obvious (e.g. "Work", "Home", "Errands"); otherwise null.
+- notes is a clarifying detail that won't fit in the title; otherwise null.
+- due_date: if a day, date, or deadline is named ("Friday", "tomorrow", "by the 5th", "end of week"), resolve it to YYYY-MM-DD relative to the current date given below. Otherwise null.
+- due_time: if a clock time is named ("at 11pm", "by 9am", "noon"), resolve it to 24-hour HH:MM. If a day but no clock time, null. Never invent a time.
+- impact, readiness, effort_hours: always score every task using the scale above. If importance is stated ("really important", "no rush"), let it guide impact.
+- reason: one short lowercase sentence, no exclamations, under 14 words, explaining the scores.
+- Split distinct tasks into separate items. Skip greetings, filler, and self-talk that isn't a task.
+- Return at most 25 items. Drop near-duplicates.
+- If there are no actionable tasks, return {{ "items": [] }}.
+
+Output only the JSON object. No prose, no markdown fences."""
+
+
+def build_parse_user(text: str, today: str, weekday: str) -> str:
+    return f"Current date: {today} ({weekday}).\n\nBrain-dump:\n{text.strip()}"
+
+
+# -- EXTRACT: image -> items (titles only) ------------------------------------
+
+EXTRACT_SYSTEM_PROMPT = """You read a screenshot or photo and extract tasks for a personal productivity app. The image may show a handwritten list, a typed list, an email, a chat, a whiteboard, or meeting notes. Identify every discrete actionable task visible.
+
+Output a JSON object: { "items": [ { "title": string, "category": string | null, "notes": string | null } ] }
+
+Rules:
+- title is a short imperative phrase, sentence case, no trailing period, under 90 characters. Prefer the writer's own words when legible.
+- category is a 1-2 word project name if the image makes one obvious; otherwise null.
+- notes is null unless the image contains a clarifying detail that won't fit in the title.
+- Skip headers, dates, names, decorative text, and items already crossed out or checked off.
+- If the image contains no actionable tasks, return { "items": [] }.
+- Return at most 20 items. Drop near-duplicates.
+
+Output only the JSON object. No prose, no markdown fences."""
+
+EXTRACT_USER_PROMPT = "Extract every actionable task from this image."
+
+
+# -- SCORE: one task -> impact / readiness / effort ---------------------------
+
+SCORE_SYSTEM_PROMPT = f"""You score one task for a productivity app. Given a title and optional context, output JSON with impact, readiness, effort_hours, and a short reason.
+
+{SCALE_GUIDE}
+
+A short title can hide real work. If notes describe several steps, treat them as the scope: more open work usually means more effort_hours and lower readiness.
+
+reason is one short lowercase sentence, no exclamations, under 14 words.
+
+Output only the JSON object. No prose, no markdown fences."""
+
+
+def build_score_user(title: str, notes: str = "", category: str = "") -> str:
+    lines = [f"Title: {title}"]
+    if category:
+        lines.append(f"Project: {category}")
+    if notes:
+        lines.append(f"Notes: {notes}")
+    return "\n".join(lines)

requirements.txt

@@ -0,0 +1,4 @@
+gradio==5.9.1
+huggingface_hub>=0.25
+pillow>=10.0
+requests>=2.31

sample_data/sample_braindump.txt

@@ -0,0 +1,8 @@
+email the landlord about the lease renewal, kind of important and due Friday
+finish the Q3 board deck — big deal, maybe 4 hours of work, needs to be done by next Wednesday
+5 min: cancel the unused gym membership
+look into switching the team to the new CI, no rush, not sure where to start
+book the dentist, due tomorrow
+reply to Sam's thread, quick one
+draft the hiring plan — important but I'm blocked until we agree on budget
+pick up dry cleaning sometime this week

score.py

@@ -0,0 +1,333 @@
+"""Priority scoring + deadline ranking — the deterministic core.
+
+Clean-room Python port of whatfirst's scoring engine, re-implemented from the
+formula's documented behaviour. It depends on nothing but the standard library
+(math, datetime) and imports nothing from the original app. Two parallel scores
+compete; the higher one is what the user sees.
+
+    do_score   = (I * U * R_eff * QW) / 10
+    prep_score = (I * U * (10 - R)) / 10 * 0.7 * QW
+
+where:
+    U       = max(calendar_urgency, completion_urgency)
+    QW      = 1 + 0.6 * (I/10) * exp(-E/1.5)        quick-win boost
+    R_floor = clamp((U - 6) / 4 * 10, 0, 10)        urgency's target readiness
+    R_eff   = R + max(0, R_floor - R) * READY_LIFT  urgency lifts an unready task
+    defer   = U_comp >= 9 and slack < 0.5 and I < 7 flag, not a number
+
+READY_LIFT (< 1) keeps the readiness control live: R_eff stays strictly
+increasing in R, so readiness always moves the do-score while urgency can still
+drag an unready-but-urgent task up to where it competes. All inputs are coerced
+to finite numbers and clamped to their domains (I,R in [1,10], E >= 0.05) so the
+displayed score can never be NaN/Infinity.
+
+Urgency is unbounded near zero: a rational decay holds for d > 2 days, then an
+inverse-distance term takes over and grows past 10 as the deadline approaches
+(saturating at 30 the instant before due). Crossing the deadline hands off
+continuously: the overdue branch picks up at 30 and ramps to 40 over five days,
+so a task never loses urgency merely by going late.
+
+If task["execute_anyway"] is true, R_eff is forced to max(R, 9), prep_score is
+zeroed, and the defer flag is suppressed (the user opted in to risk-on mode).
+"""
+
+from __future__ import annotations
+
+import math
+from datetime import datetime
+
+# -- Tunable scoring knobs ----------------------------------------------------
+# READY_LIFT and PREP_BIAS are both 0.7 by coincidence; they are unrelated and
+# may drift apart, so they are named separately rather than sharing a literal.
+
+# How far urgency may close the gap between a task's readiness and the
+# urgency-driven target R_floor. Strictly < 1 so a fully unready task is never
+# lifted all the way to "ready".
+READY_LIFT = 0.7
+
+# Action bias on the prep branch: < 1 so a tie in raw value tilts to "do".
+PREP_BIAS = 0.7
+
+# Upper guard on the two score branches. Sits above the formula's natural
+# maximum on purpose, so it never clips a real task — only a backstop.
+SCORE_CAP = 1000
+
+# Closeness band for the value tier, realized as a transitive log-bucket.
+TIE_BAND = 0.10
+
+# Quick-win lens thresholds (a short, ready-to-start task for a spare moment).
+QUICK_WIN_MAX_EFFORT_HOURS = 0.25  # 15 minutes
+QUICK_WIN_MIN_READINESS = 7
+
+
+def clamp(x: float, lo: float, hi: float) -> float:
+    return max(lo, min(hi, x))
+
+
+def finite(x, fallback: float) -> float:
+    """Coerce anything non-numeric or non-finite to a known default before it
+    enters the formula — one bad field must yield a sane number, never NaN."""
+    try:
+        xf = float(x)
+    except (TypeError, ValueError):
+        return fallback
+    return xf if math.isfinite(xf) else fallback
+
+
+def readiness_of(t: dict) -> float:
+    """Default readiness is 8 (a task is presumed mostly-ready)."""
+    return finite(t.get("readiness"), 8)
+
+
+# -- Urgency curves -----------------------------------------------------------
+
+def cal_urgency(d: float) -> float:
+    if d <= 0:
+        return min(40, 30 + (-d) * 2)
+    base = 1 + 9 / (1 + (d / 7) ** 1.5)
+    T, k, eps = 2, 8, 0.25
+    accel = max(0, k / (d + eps) - k / (T + eps)) if d < T else 0
+    return min(30, base + accel)
+
+
+def comp_urgency(d: float, e_hours: float) -> float:
+    if d <= 0:
+        return min(40, 30 + (-d) * 2)
+    e_days = max(e_hours, 0.05) / 4
+    slack = d / e_days
+    base = 1 + 9 / (1 + slack / 2)
+    T, k, eps = 1, 4, 0.1
+    accel = max(0, k / (slack + eps) - k / (T + eps)) if slack < T else 0
+    return min(30, base + accel)
+
+
+def urgency(due_date, effort_hours) -> float:
+    if not due_date:
+        return 2
+    d = days_to_due_raw(due_date)
+    return max(cal_urgency(d), comp_urgency(d, effort_hours or 0.05))
+
+
+# -- Core score ---------------------------------------------------------------
+
+def score_components(t: dict) -> dict:
+    I = clamp(finite(t.get("impact"), 5), 1, 10)
+    R = clamp(readiness_of(t), 1, 10)
+    E = max(finite(t.get("effort_hours"), 0.05), 0.05)
+    d = days_to_due_raw(t.get("due_date"))
+    has_due = bool(t.get("due_date")) and math.isfinite(d)
+    U_cal = cal_urgency(d) if has_due else 1.5
+    U_comp = comp_urgency(d, E) if has_due else 1.5
+    U = max(U_cal, U_comp)
+    if has_due and d > 0:
+        slack = d / (E / 4)
+    elif d <= 0:
+        slack = 0.0
+    else:
+        slack = math.inf
+    QW = 1 + 0.6 * (I / 10) * math.exp(-E / 1.5)
+    risk_on = bool(t.get("execute_anyway"))
+    R_floor = clamp((U - 6) / 4 * 10, 0, 10)
+    # Partial lift toward R_floor (not max(R, R_floor)): urgency pulls an unready
+    # task up so it still competes, but readiness keeps moving the score.
+    R_eff = max(R, 9) if risk_on else R + max(0, R_floor - R) * READY_LIFT
+    do_score = clamp((I * U * R_eff * QW) / 10, 0.1, SCORE_CAP)
+    prep_score = 0.0 if risk_on else clamp((I * U * (10 - R)) / 10 * PREP_BIAS * QW, 0, SCORE_CAP)
+    defer = (not risk_on) and has_due and U_comp >= 9 and slack < 0.5 and I < 7
+    display = max(do_score, prep_score)
+    prep_wins = prep_score > do_score and R <= 5 and not risk_on
+    return {
+        "I": I, "R": R, "E": E, "d": d, "U": U, "U_cal": U_cal, "U_comp": U_comp,
+        "slack": slack, "qw": QW, "R_floor": R_floor, "R_eff": R_eff,
+        "do_score": do_score, "prep_score": prep_score, "defer": defer,
+        "display": display, "prep_wins": prep_wins,
+    }
+
+
+def priority(t: dict) -> float:
+    return score_components(t)["display"]
+
+
+def value_bucket(v: float) -> int:
+    return math.floor(math.log(max(v, 0.1)) / math.log(1 + TIE_BAND))
+
+
+# -- Assignment (collapses to "always mine" with no teams) --------------------
+
+def assignee_ids(task: dict) -> list:
+    ids = task.get("assignee_user_ids")
+    if isinstance(ids, list):
+        return ids
+    if task.get("assignee_user_id") is not None:
+        return [task["assignee_user_id"]]
+    return []
+
+
+def mine_to_do(task: dict, current_user_id=None) -> bool:
+    if current_user_id is None:
+        return True
+    ids = assignee_ids(task)
+    return len(ids) == 0 or current_user_id in ids
+
+
+# -- Dates --------------------------------------------------------------------
+
+def normalize_iso(due_date):
+    """A bare date ('YYYY-MM-DD') names a day; treat it as 5pm local so a
+    date-only deadline isn't read as midnight. A full datetime passes through."""
+    if not isinstance(due_date, str):
+        return due_date
+    return f"{due_date}T17:00:00" if len(due_date) == 10 else due_date
+
+
+def _parse(due_date):
+    try:
+        return datetime.fromisoformat(normalize_iso(due_date))
+    except (TypeError, ValueError):
+        return None
+
+
+def days_to_due_raw(due_date, now: datetime | None = None) -> float:
+    if not due_date:
+        return math.inf
+    due = _parse(due_date)
+    if due is None:
+        return math.inf
+    now = now or datetime.now()
+    return (due - now).total_seconds() / 86400
+
+
+def deadline_status(task: dict, now: datetime | None = None):
+    """Deadline pressure as a discrete tier, orthogonal to the priority score.
+    Returns 'overdue' | 'today' | 'tomorrow' | None."""
+    if not task or task.get("completed") or not task.get("due_date"):
+        return None
+    due = _parse(task["due_date"])
+    if due is None:
+        return None
+    now = now or datetime.now()
+    if due < now:
+        return "overdue"
+    start = lambda d: datetime(d.year, d.month, d.day)
+    day_diff = round((start(due) - start(now)).total_seconds() / 86400)
+    if day_diff == 0:
+        return "today"
+    if day_diff == 1:
+        return "tomorrow"
+    return None
+
+
+# -- Ranking ------------------------------------------------------------------
+
+def deadline_risk_map(sorted_active: list, now: datetime | None = None, current_user_id=None) -> dict:
+    """Cumulative deadline-risk tiers across the ranked active queue.
+
+    Walk the queue in priority order, accumulate effort, and project a
+    continuous wall-clock finish for each task. A task whose projected finish
+    lands past its own deadline is at risk even if it would have fit alone — the
+    work ahead of it ate the runway. Returns {id: 'at-risk' | 'tight'}.
+    """
+    out = {}
+    now = now or datetime.now()
+    acc = 0.0  # cumulative effort-hours of the queue so far, inclusive
+    for t in sorted_active:
+        if not t or t.get("completed"):
+            continue
+        if not mine_to_do(t, current_user_id):
+            continue
+        E = max(t.get("effort_hours") or 0, 0)
+        acc += E
+        if not t.get("due_date"):
+            continue
+        due = _parse(t["due_date"])
+        if due is None:
+            continue
+        hours_to_due = (due - now).total_seconds() / 3600
+        if not (hours_to_due > 0):
+            continue  # overdue — skip; deadline_status owns that signal
+        slack = hours_to_due - acc
+        if slack <= 0:
+            out[t["id"]] = "at-risk"
+        elif slack < 0.5 * E:
+            out[t["id"]] = "tight"
+    return out
+
+
+def rank_active(tasks: list, now: datetime | None = None, current_user_id=None) -> list:
+    """Rank the active queue with deadlines as a constraint, not a term folded
+    into the value score. Three tiers: 0 overdue (EDF), 1 binding/at-risk (EDF,
+    lifted above the value pack), 2 value pack (value bucket, sooner due breaks
+    near-ties)."""
+    now = now or datetime.now()
+    active = [t for t in tasks if not t.get("completed")]
+    V = {t["id"]: priority(t) for t in active}
+    D = {t["id"]: days_to_due_raw(t.get("due_date"), now) for t in active}
+    by_value = sorted(active, key=lambda t: V[t["id"]], reverse=True)
+    risk = deadline_risk_map(by_value, now, current_user_id)
+
+    def tier_of(t):
+        if not mine_to_do(t, current_user_id):
+            return 2
+        if t.get("due_date") and D[t["id"]] <= 0:
+            return 0
+        return 1 if risk.get(t["id"]) == "at-risk" else 2
+
+    def sort_key(t):
+        tid = t["id"]
+        tr = tier_of(t)
+        if tr < 2:
+            return (tr, D[tid], 0.0)  # overdue/binding: earliest-deadline-first
+        # value pack: higher bucket first, then sooner due breaks near-ties
+        return (tr, -value_bucket(V[tid]), D[tid])
+
+    # Python's sort is stable, so equal keys keep by_value (value-desc) order.
+    return sorted(by_value, key=sort_key)
+
+
+# -- Quick-win lens -----------------------------------------------------------
+
+def is_quick_win(task: dict) -> bool:
+    """Short enough and ready enough to knock out in a spare moment?"""
+    if not task or task.get("completed"):
+        return False
+    e = task.get("effort_hours")
+    if not isinstance(e, (int, float)) or not math.isfinite(e) or e <= 0 or e > QUICK_WIN_MAX_EFFORT_HOURS:
+        return False
+    return readiness_of(task) >= QUICK_WIN_MIN_READINESS or bool(task.get("execute_anyway"))
+
+
+def quick_wins(tasks: list) -> list:
+    """Quick wins ordered for the spare-moment view: shortest first, ties by
+    priority desc."""
+    return sorted(
+        (t for t in tasks if is_quick_win(t)),
+        key=lambda t: (t["effort_hours"], -priority(t)),
+    )
+
+
+# -- Display helpers ----------------------------------------------------------
+
+def format_score(n: float) -> str:
+    rounded = round(n * 10) / 10
+    return str(int(rounded)) if rounded == int(rounded) else f"{rounded:.1f}"
+
+
+def due_label(due_date, now: datetime | None = None) -> str:
+    """Compact relative deadline label ('now', '3h', 'tomorrow', '2d', '5d late')."""
+    if not due_date:
+        return "-"
+    due = _parse(due_date)
+    if due is None:
+        return "-"
+    now = now or datetime.now()
+    raw = (due - now).total_seconds() / 86400
+    if raw < 0:
+        ab = -raw
+        return f"{max(1, round(ab * 24))}h late" if ab < 1 else f"{round(ab)}d late"
+    start = lambda d: datetime(d.year, d.month, d.day)
+    day_diff = round((start(due) - start(now)).total_seconds() / 86400)
+    if day_diff == 0:
+        return "now" if raw < 1 / 24 else f"{round(raw * 24)}h"
+    if day_diff == 1:
+        return "tomorrow"
+    return f"{day_diff}d"

start.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MODEL_DIR="${MODEL_DIR:-/models}"
+MODEL_FILE="${MODEL_FILE:-Qwen2.5-VL-3B-Instruct-Q4_K_M.gguf}"
+MMPROJ_FILE="${MMPROJ_FILE:-mmproj-Qwen2.5-VL-3B-Instruct-f16.gguf}"
+
+# 1. Pull weights (idempotent).
+python download_model.py
+
+# 2. Launch the llama.cpp server (multimodal) on localhost in the background.
+echo "[start] launching llama-server"
+/opt/llama.cpp/build/bin/llama-server \
+  --model "${MODEL_DIR}/${MODEL_FILE}" \
+  --mmproj "${MODEL_DIR}/${MMPROJ_FILE}" \
+  --host 127.0.0.1 --port 8080 \
+  --ctx-size 8192 \
+  --threads "$(nproc)" &
+
+# 3. Start the Gradio app (foreground). is_ready() polls the server's /health,
+#    so the UI comes up immediately and the button waits for the model.
+echo "[start] launching gradio"
+exec python app.py

test_score.py

@@ -0,0 +1,158 @@
+"""Self-contained tests for the scoring engine.
+
+Numeric anchors are derived by hand from the formula (worked through on paper),
+not copied from score.py's own output, so they actually constrain the port. The
+rest assert structural invariants (monotonicity, tier order, quick-win
+direction) that catch regressions a single magic number would miss.
+"""
+
+from datetime import datetime
+
+import score as s
+
+
+def approx(a, b, tol=1e-3):
+    assert abs(a - b) <= tol, f"expected {b}, got {a}"
+
+
+# -- Hand-computed urgency anchors --------------------------------------------
+
+def test_cal_urgency_week_out():
+    # d=7: base = 1 + 9/(1+(7/7)**1.5) = 1 + 9/2 = 5.5; d>=T so no accel.
+    approx(s.cal_urgency(7), 5.5)
+
+
+def test_cal_urgency_overdue_saturates():
+    # d=0 -> 30; d=-5 -> 30 + 5*2 = 40 (capped at 40).
+    approx(s.cal_urgency(0), 30.0)
+    approx(s.cal_urgency(-5), 40.0)
+    approx(s.cal_urgency(-100), 40.0)  # hard cap
+
+
+def test_comp_urgency_comfortable_slack():
+    # d=7, e=4h -> e_days=1, slack=7, base = 1 + 9/(1+3.5) = 3; no accel.
+    approx(s.comp_urgency(7, 4), 3.0)
+
+
+def test_comp_urgency_explodes_near_zero_slack():
+    # Tiny slack drives the inverse-distance term up hard.
+    assert s.comp_urgency(0.1, 4) > 20
+
+
+# -- Hand-computed full-score anchor ------------------------------------------
+
+def test_priority_default_no_due():
+    # I=5, R=8, E=0.05, no due -> U=1.5, R_eff=8,
+    # QW = 1 + 0.3*exp(-1/30) = 1.2901648,
+    # do = (5*1.5*8*QW)/10 = 7.740989; prep loses.
+    t = {"id": "x", "impact": 5, "readiness": 8, "effort_hours": 0.05}
+    approx(s.priority(t), 7.7410)
+
+
+# -- Structural invariants ----------------------------------------------------
+
+def test_readiness_moves_the_score():
+    # The whole point of READY_LIFT: readiness stays live. Higher R -> higher do.
+    base = {"id": "x", "impact": 6, "effort_hours": 1}
+    assert s.priority({**base, "readiness": 10}) > s.priority({**base, "readiness": 8})
+
+
+def test_quick_win_boost_rewards_short_effort():
+    # Lower effort -> larger QW -> higher displayed score, all else equal.
+    base = {"id": "x", "impact": 6, "readiness": 8}
+    assert s.priority({**base, "effort_hours": 0.05}) > s.priority({**base, "effort_hours": 4})
+
+
+def test_prep_wins_for_unready_high_impact():
+    # R=2, I=8, no due: prep (6.72*QW) beats do (2.4*QW) and R<=5.
+    c = s.score_components({"id": "x", "impact": 8, "readiness": 2})
+    assert c["prep_wins"] is True
+    assert c["prep_score"] > c["do_score"]
+
+
+def test_risk_on_zeroes_prep_and_lifts_readiness():
+    c = s.score_components({"id": "x", "impact": 8, "readiness": 2, "execute_anyway": True})
+    assert c["prep_score"] == 0.0
+    assert c["R_eff"] >= 9
+    assert c["prep_wins"] is False
+
+
+def test_value_bucket_monotone():
+    assert s.value_bucket(100) > s.value_bucket(10) > s.value_bucket(1)
+
+
+def test_bad_fields_never_nan():
+    # A garbage field must fall back, not poison the score.
+    c = s.score_components({"id": "x", "impact": None, "readiness": float("nan"), "effort_hours": "oops"})
+    assert c["display"] == c["display"]  # not NaN
+    assert 0.1 <= c["display"] <= s.SCORE_CAP
+
+
+# -- Ranking ------------------------------------------------------------------
+
+NOW = datetime(2026, 6, 7, 12, 0, 0)
+
+
+def test_overdue_ranks_first():
+    tasks = [
+        {"id": "B", "impact": 10, "readiness": 10, "effort_hours": 0.1},          # high value, no due
+        {"id": "A", "impact": 2, "readiness": 8, "effort_hours": 1, "due_date": "2026-06-01"},  # overdue
+        {"id": "C", "impact": 7, "readiness": 8, "effort_hours": 1, "due_date": "2026-06-20"},  # future
+    ]
+    order = [t["id"] for t in s.rank_active(tasks, NOW)]
+    assert order[0] == "A", order  # overdue lifted above the value pack
+
+
+def test_binding_deadline_lifts_above_value():
+    # A low-value task that genuinely won't finish in time must beat a juicy
+    # future task it would otherwise sit below.
+    tasks = [
+        {"id": "big", "impact": 10, "readiness": 9, "effort_hours": 2, "due_date": "2026-06-30"},
+        {"id": "tight", "impact": 3, "readiness": 9, "effort_hours": 10, "due_date": "2026-06-07T18:00:00"},
+    ]
+    order = [t["id"] for t in s.rank_active(tasks, NOW)]
+    assert order[0] == "tight", order
+
+
+def test_completed_tasks_excluded():
+    tasks = [
+        {"id": "done", "impact": 10, "completed": True},
+        {"id": "live", "impact": 4},
+    ]
+    order = [t["id"] for t in s.rank_active(tasks, NOW)]
+    assert order == ["live"]
+
+
+# -- Quick wins ---------------------------------------------------------------
+
+def test_quick_win_filter_and_order():
+    tasks = [
+        {"id": "a", "impact": 5, "readiness": 9, "effort_hours": 0.1},   # qualifies
+        {"id": "b", "impact": 9, "readiness": 9, "effort_hours": 0.05},  # qualifies, shorter
+        {"id": "c", "impact": 5, "readiness": 3, "effort_hours": 0.1},   # too unready
+        {"id": "d", "impact": 5, "readiness": 9, "effort_hours": 2},     # too long
+    ]
+    order = [t["id"] for t in s.quick_wins(tasks)]
+    assert order == ["b", "a"], order  # shortest first
+
+
+def test_due_label():
+    assert s.due_label("2026-06-08T12:00:00", NOW) == "tomorrow"
+    assert s.due_label("2026-06-12T12:00:00", NOW) == "5d"
+    assert s.due_label("2026-06-05T12:00:00", NOW) == "2d late"
+
+
+if __name__ == "__main__":
+    import sys
+
+    fns = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
+    failed = 0
+    for fn in fns:
+        try:
+            fn()
+            print(f"  ok   {fn.__name__}")
+        except AssertionError as e:
+            failed += 1
+            print(f"  FAIL {fn.__name__}: {e}")
+    print(f"\n{len(fns) - failed}/{len(fns)} passed")
+    sys.exit(1 if failed else 0)