Paper Decoder v1: base model end-to-end (G1)

Dockerfile

@@ -0,0 +1,46 @@
+# Paper Decoder — HF Space (Docker SDK)
+# llama.cpp server (official image binaries) + Tesseract OCR (ukr/rus) + Gradio 6
+
+# Stage 1: take llama-server + shared libs from the official CPU server image.
+# Layout verified 2026-06-10 against .devops/cpu.Dockerfile: binary and all
+# *.so* live flat in /app; runtime needs libgomp1 and curl.
+FROM ghcr.io/ggml-org/llama.cpp:server AS llama
+
+FROM python:3.11-slim-bookworm
+
+# System deps: OCR (Ukrainian + Russian traineddata), llama.cpp runtime libs
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        tesseract-ocr \
+        tesseract-ocr-ukr \
+        tesseract-ocr-rus \
+        libgomp1 \
+        curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=llama /app /opt/llama
+ENV LD_LIBRARY_PATH=/opt/llama
+
+# Bake the model into the image at build time: faster Space restarts,
+# no runtime download. Exact file pin recorded after first build.
+RUN pip install --no-cache-dir "huggingface_hub[cli]>=0.26,<2.0" && \
+    huggingface-cli download unsloth/Qwen3-4B-Instruct-2507-GGUF \
+        --include "*Q4_K_M*.gguf" --local-dir /opt/models && \
+    find /opt/models -name "*.gguf" -exec ls -lh {} \;
+
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir -r /tmp/requirements.txt
+
+# HF Spaces convention: run as non-root user with UID 1000
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    GRADIO_SERVER_NAME=0.0.0.0 \
+    GRADIO_SERVER_PORT=7860
+
+WORKDIR /home/user/app
+COPY --chown=user app.py start.sh ./
+RUN chmod +x start.sh
+
+EXPOSE 7860
+CMD ["./start.sh"]

README.md

@@ -1,12 +1,56 @@
 ---
-title: Paper Decoder
-emoji: 📉
-colorFrom: blue
+title: Paper Decoder — Розшифровувач паперів
+emoji: 📄
+colorFrom: yellow
 colorTo: gray
 sdk: docker
+app_port: 7860
 pinned: false
 license: apache-2.0
-short_description: Ukrainian official-letter decoder for my parents.
+short_description: Ukrainian official-letter decoder for my parents. Local-only.
+tags:
+  - backyard-ai
+  - off-the-grid
+  - llama-cpp
+  - tiny-titan
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Paper Decoder — Розшифровувач паперів
+
+My parents in Uzhhorod receive official Ukrainian letters — utility debt
+notices, bank letters, tax demands — and "official-looking" scam messages.
+They can read every word and still not know what the letter wants from them,
+or whether it's real.
+
+Paper Decoder takes a phone photo or pasted text of a letter and returns:
+
+1. a plain-Ukrainian summary (3–4 sentences, no bureaucratese),
+2. a "what you must do" action list,
+3. every date, deadline and amount, extracted,
+4. scam-pattern flags with the matched evidence quoted.
+
+## Why a small local model
+
+These letters contain names, addresses, account numbers, debts. Sending them
+to a cloud API is exactly what I'd tell my parents never to do. Everything
+runs on this CPU Space: Tesseract OCR (ukr+rus) for the photo path,
+Qwen3-4B-Instruct-2507 at Q4_K_M served by llama.cpp. No external calls at
+inference time.
+
+## Model selection was gated, not assumed
+
+Before building, three candidate models ran a 10-prompt Ukrainian spot-check
+on real letter types (scored 0–2 per prompt, blind rubric):
+
+| Model | Score | Verdict |
+|---|---|---|
+| MiniCPM5-1B (Q4_K_M) | 0/20 | Russian bleed, script corruption, empty outputs |
+| Qwen3-1.7B (Q4_K_M) | 11/20 | Fluent Ukrainian, zero scam awareness |
+| Qwen3-4B-Instruct-2507 (Q4_K_M) | 14/20 | Pass — shipped |
+
+A fine-tuned LoRA targeting the remaining failure modes (protective actions
+on scam letters, date fidelity in summaries) is in progress; the before/after
+eval will be published with the model.
+
+Built solo by [aleks-gotsa](https://huggingface.co/aleks-gotsa) for the
+Build Small Hackathon 2026, Backyard AI track.

app.py

@@ -0,0 +1,399 @@
+"""Paper Decoder — Розшифровувач паперів.
+
+Ukrainian official-letter decoder. Photo or pasted text in; plain-language
+summary, required actions, deadlines, and scam flags out. Fully local:
+Tesseract OCR + Qwen3-4B-Instruct-2507 (Q4_K_M) via llama.cpp. No cloud calls.
+
+Build Small Hackathon 2026 · Backyard AI track · built for my parents.
+"""
+
+import html
+import json
+import os
+import time
+
+import pytesseract
+import requests
+from PIL import Image, ImageOps
+
+import gradio as gr
+
+LLAMA_URL = os.environ.get("LLAMA_URL", "http://127.0.0.1:8081")
+MAX_LETTER_CHARS = 6000  # ~1.5-2k tokens; keeps prefill sane on CPU
+
+SYSTEM_PROMPT = """Ти — «Розшифровувач паперів», помічник для літніх людей в Україні. Тобі дають текст офіційного листа (іноді розпізнаний з фотографії, з помилками розпізнавання).
+
+Відповідай ЛИШЕ валідним JSON без жодного іншого тексту, з полями:
+- "summary": 3–4 короткі речення простою українською, без канцеляризмів. Пояснюй так, ніби говориш із власною бабусею.
+- "actions": список конкретних дій, які має зробити людина, у порядку виконання.
+- "deadlines": список об'єктів {"date": "...", "what": "...", "amount": "..."}; якщо суми немає — null.
+- "scam_flags": список об'єктів {"pattern": "...", "evidence": "точна цитата з листа"}; якщо ознак немає — порожній список [].
+
+У полі "pattern" ДОЗВОЛЕНІ ЛИШЕ ці значення, нічого іншого:
+1. "несправжнє посилання" — домен лише схожий на офіційний (зайві слова, дефіси, інша зона).
+2. "оплата на картку фізособи" — вимога переказати гроші на 16-значний номер картки.
+3. "вимога ПІН-коду, CVV або кодів з SMS".
+4. "знижка за швидку оплату" — менша сума, якщо заплатити за години.
+5. "строк у годинах" — вимога зробити щось за 12/24/48 годин. Справжні установи дають конкретні дати або дні, не години.
+
+Якщо жодна з цих п'яти ознак не присутня ДОСЛІВНО в тексті — "scam_flags" має бути []. Попередження про відключення послуг, пеню, суд або стягнення у листах від комунальних підприємств, банків, податкової чи виконавчої служби — звичайна законна практика, це НЕ шахрайство і НЕ потрапляє у "scam_flags".
+
+ПРАВИЛО БЕЗПЕКИ: якщо "scam_flags" непорожній, у "actions" ЗАБОРОНЕНО радити переходити за посиланням, платити, телефонувати за номерами з листа або вводити дані. Натомість дії мають бути захисними: не переходити за посиланням і не платити; зателефонувати до банку чи установи за офіційним номером (з банківської картки або офіційного сайту); показати лист рідним.
+
+ПРАВИЛА ДАТ І СУМ: використовуй лише дати та суми, які є в листі, і копіюй їх точно. Відносні строки («протягом 10 календарних днів») залишай відносними — не перетворюй їх на конкретні дати. Дати у "summary" мають дослівно збігатися з датами у "deadlines". Нічого не вигадуй."""
+
+# ---------------------------------------------------------------- OCR path
+
+
+def ocr_image(filepath: str | None) -> str:
+    if not filepath:
+        return ""
+    img = Image.open(filepath)
+    img = ImageOps.exif_transpose(img)  # phone photos carry rotation in EXIF
+    img = ImageOps.grayscale(img)
+    img = ImageOps.autocontrast(img)
+    if img.width < 1400:  # Tesseract wants ~300dpi-ish input
+        scale = 1400 / img.width
+        img = img.resize((1400, int(img.height * scale)), Image.LANCZOS)
+    text = pytesseract.image_to_string(img, lang="ukr+rus")
+    return text.strip()
+
+
+# ------------------------------------------------------------- model call
+
+
+def stream_completion(letter_text: str):
+    """Yield (accumulated_text, completion_tokens, elapsed_s) while streaming."""
+    payload = {
+        "model": "paper-decoder",
+        "temperature": 0.2,
+        "seed": 42,
+        "max_tokens": 900,
+        "cache_prompt": True,  # system prompt is cached across requests
+        "response_format": {"type": "json_object"},
+        "stream": True,
+        "stream_options": {"include_usage": True},
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": letter_text},
+        ],
+    }
+    acc, completion_tokens = "", 0
+    t0 = time.monotonic()
+    with requests.post(
+        f"{LLAMA_URL}/v1/chat/completions", json=payload, stream=True, timeout=600
+    ) as r:
+        r.raise_for_status()
+        r.encoding = "utf-8"
+        for raw in r.iter_lines(decode_unicode=True):
+            if not raw or not raw.startswith("data: "):
+                continue
+            data = raw[len("data: "):]
+            if data.strip() == "[DONE]":
+                break
+            try:
+                chunk = json.loads(data)
+            except json.JSONDecodeError:
+                continue
+            usage = chunk.get("usage")
+            if usage:
+                completion_tokens = usage.get("completion_tokens", completion_tokens)
+            choices = chunk.get("choices") or []
+            if choices:
+                delta = choices[0].get("delta") or {}
+                acc += delta.get("content") or ""
+            yield acc, completion_tokens, time.monotonic() - t0
+
+
+def parse_model_json(text: str) -> dict | None:
+    candidate = text.strip()
+    if candidate.startswith("```"):
+        candidate = candidate.strip("`")
+        if candidate.startswith("json"):
+            candidate = candidate[4:]
+        candidate = candidate.strip()
+    for attempt in (candidate,):
+        try:
+            obj = json.loads(attempt)
+            if isinstance(obj, dict):
+                return obj
+        except (json.JSONDecodeError, ValueError):
+            pass
+    start, end = candidate.find("{"), candidate.rfind("}")
+    if start != -1 and end > start:
+        try:
+            obj = json.loads(candidate[start : end + 1])
+            if isinstance(obj, dict):
+                return obj
+        except (json.JSONDecodeError, ValueError):
+            pass
+    return None
+
+
+# -------------------------------------------------------------- rendering
+
+
+def esc(x) -> str:
+    return html.escape(str(x)) if x is not None else ""
+
+
+def render_status(message: str, detail: str = "") -> str:
+    d = f'<div class="pd-status-detail">{esc(detail)}</div>' if detail else ""
+    return (
+        '<div class="pd-status"><span class="pd-pulse"></span>'
+        f"<div><div>{esc(message)}</div>{d}</div></div>"
+    )
+
+
+def render_error(message: str) -> str:
+    return f'<div class="pd-error">{esc(message)}</div>'
+
+
+def render_result(data: dict, tok_s: float | None) -> str:
+    flags = data.get("scam_flags") or []
+    is_scam = len(flags) > 0
+
+    if is_scam:
+        stamp = '<div class="pd-stamp pd-stamp-danger">Схоже на шахрайство</div>'
+    else:
+        stamp = '<div class="pd-stamp pd-stamp-ok">Виглядає як справжній лист</div>'
+
+    parts = [f'<div class="pd-stamp-row">{stamp}</div>']
+
+    summary = data.get("summary")
+    if summary:
+        parts.append(
+            '<section class="pd-card"><h3>Про що цей лист</h3>'
+            f'<p class="pd-summary">{esc(summary)}</p></section>'
+        )
+
+    if is_scam:
+        rows = "".join(
+            '<li><span class="pd-flag-pattern">' + esc(f.get("pattern", "")) + "</span>"
+            '<span class="pd-flag-evidence">«' + esc(f.get("evidence", "")) + "»</span></li>"
+            for f in flags
+            if isinstance(f, dict)
+        )
+        parts.append(
+            '<section class="pd-card pd-card-danger"><h3>Чому це підозріло</h3>'
+            f'<ul class="pd-flags">{rows}</ul></section>'
+        )
+
+    actions = data.get("actions") or []
+    if actions:
+        rows = "".join(f"<li>{esc(a)}</li>" for a in actions)
+        parts.append(
+            '<section class="pd-card"><h3>Що робити</h3>'
+            f'<ol class="pd-actions">{rows}</ol></section>'
+        )
+
+    deadlines = data.get("deadlines") or []
+    if deadlines:
+        rows = ""
+        for d in deadlines:
+            if not isinstance(d, dict):
+                continue
+            amount = d.get("amount")
+            amount_html = f'<td class="pd-mono pd-amount">{esc(amount)}</td>' if amount else "<td>—</td>"
+            rows += (
+                f'<tr><td class="pd-mono pd-date">{esc(d.get("date", ""))}</td>'
+                f'<td>{esc(d.get("what", ""))}</td>{amount_html}</tr>'
+            )
+        parts.append(
+            '<section class="pd-card"><h3>Дати та суми</h3>'
+            '<table class="pd-deadlines"><thead><tr>'
+            "<th>Коли</th><th>Що</th><th>Сума</th></tr></thead>"
+            f"<tbody>{rows}</tbody></table></section>"
+        )
+
+    speed = f" · {tok_s:.1f} ток/с" if tok_s else ""
+    parts.append(
+        f'<div class="pd-meta">Оброблено локально, без інтернет-сервісів{speed}</div>'
+    )
+    return '<div class="pd-result">' + "".join(parts) + "</div>"
+
+
+# ------------------------------------------------------------------ logic
+
+
+def do_ocr(image_path):
+    if not image_path:
+        return gr.update()
+    text = ocr_image(image_path)
+    if not text:
+        return "(Не вдалося розпізнати текст. Спробуйте чіткіше фото або вставте текст вручну.)"
+    return text
+
+
+def decode(letter_text: str):
+    letter_text = (letter_text or "").strip()
+    if not letter_text or letter_text.startswith("(Не вдалося"):
+        yield render_error(
+            "Спочатку додайте лист: сфотографуйте його або вставте текст у поле зліва."
+        )
+        return
+    letter_text = letter_text[:MAX_LETTER_CHARS]
+
+    yield render_status("Читаю лист…", "Перший запит після запуску може тривати довше.")
+
+    acc, completion_tokens, elapsed = "", 0, 0.0
+    try:
+        last_yield = 0.0
+        for acc, completion_tokens, elapsed in stream_completion(letter_text):
+            if elapsed - last_yield >= 1.0:
+                last_yield = elapsed
+                yield render_status(
+                    "Розшифровую…", f"{len(acc)} символів за {elapsed:.0f} с"
+                )
+    except requests.RequestException as e:
+        yield render_error(f"Помилка зв'язку з моделлю: {e}")
+        return
+
+    data = parse_model_json(acc)
+    if data is None:
+        yield (
+            render_error("Модель повернула некоректну відповідь. Спробуйте ще раз.")
+            + f'<pre class="pd-raw">{esc(acc[:2000])}</pre>'
+        )
+        return
+
+    tok_s = (completion_tokens / elapsed) if completion_tokens and elapsed > 0 else None
+    yield render_result(data, tok_s)
+
+
+# --------------------------------------------------------------------- UI
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Unbounded:wght@500;700&family=IBM+Plex+Sans:wght@400;500;600&family=IBM+Plex+Mono:wght@500;600&display=swap');
+
+:root, .dark {
+  --pd-bg: #14120F; --pd-panel: #1D1A15; --pd-panel2: #232017;
+  --pd-ink: #F2EDE3; --pd-dim: #A89F8D; --pd-line: #322E26;
+  --pd-amber: #E8B33A; --pd-red: #D4543F; --pd-green: #7CA86A;
+  --body-background-fill: var(--pd-bg);
+  --background-fill-primary: var(--pd-panel);
+  --background-fill-secondary: var(--pd-panel2);
+  --block-background-fill: var(--pd-panel);
+  --border-color-primary: var(--pd-line);
+  --body-text-color: var(--pd-ink);
+  --block-label-text-color: var(--pd-dim);
+  --input-background-fill: var(--pd-panel2);
+}
+body, gradio-app { background: var(--pd-bg) !important; }
+* { font-family: 'IBM Plex Sans', sans-serif; }
+
+.pd-header { padding: 8px 0 2px; }
+.pd-wordmark {
+  font-family: 'Unbounded', sans-serif; font-weight: 700;
+  font-size: 1.7rem; color: var(--pd-ink); letter-spacing: -0.01em;
+}
+.pd-wordmark .accent { color: var(--pd-amber); }
+.pd-tagline { color: var(--pd-dim); font-size: 1.02rem; margin-top: 4px; }
+
+.pd-status { display:flex; gap:12px; align-items:center; padding:18px;
+  background:var(--pd-panel); border:1px solid var(--pd-line); border-radius:10px;
+  font-size:1.1rem; color:var(--pd-ink); }
+.pd-status-detail { color: var(--pd-dim); font-size:0.92rem; margin-top:2px; }
+.pd-pulse { width:12px; height:12px; border-radius:50%; background:var(--pd-amber);
+  animation:pdpulse 1.1s ease-in-out infinite; flex:none; }
+@keyframes pdpulse { 0%,100%{opacity:.35} 50%{opacity:1} }
+@media (prefers-reduced-motion: reduce) { .pd-pulse { animation:none; } }
+
+.pd-error { padding:16px 18px; border:1px solid var(--pd-red); border-radius:10px;
+  color:var(--pd-ink); background:rgba(212,84,63,.08); font-size:1.05rem; }
+.pd-raw { color:var(--pd-dim); font-size:.8rem; white-space:pre-wrap; margin-top:10px; }
+
+.pd-stamp-row { padding: 6px 0 14px; }
+.pd-stamp {
+  display:inline-block; transform:rotate(-2deg);
+  font-family:'IBM Plex Mono', monospace; font-weight:600;
+  font-size:1.12rem; letter-spacing:.08em; text-transform:uppercase;
+  padding:10px 18px; border:3px double currentColor; border-radius:6px;
+}
+.pd-stamp-danger { color: var(--pd-red); }
+.pd-stamp-ok { color: var(--pd-green); }
+
+.pd-card { background:var(--pd-panel); border:1px solid var(--pd-line);
+  border-radius:12px; padding:18px 20px; margin-bottom:14px; }
+.pd-card-danger { border-color: var(--pd-red); }
+.pd-card h3 { margin:0 0 10px; color:var(--pd-amber); font-size:.85rem;
+  font-weight:600; letter-spacing:.12em; text-transform:uppercase; }
+.pd-card-danger h3 { color: var(--pd-red); }
+
+.pd-summary { font-size:1.22rem; line-height:1.65; margin:0; color:var(--pd-ink); }
+
+.pd-actions { margin:0; padding-left:1.4em; font-size:1.14rem; line-height:1.6; }
+.pd-actions li { margin-bottom:10px; }
+.pd-actions li::marker { color:var(--pd-amber); font-weight:600; }
+
+.pd-flags { margin:0; padding-left:1.2em; font-size:1.05rem; line-height:1.55; }
+.pd-flags li { margin-bottom:10px; }
+.pd-flag-pattern { display:block; font-weight:600; color:var(--pd-ink); }
+.pd-flag-evidence { display:block; color:var(--pd-dim); font-style:italic; }
+
+.pd-deadlines { width:100%; border-collapse:collapse; font-size:1.08rem; }
+.pd-deadlines th { text-align:left; color:var(--pd-dim); font-weight:500;
+  font-size:.85rem; padding:4px 12px 8px 0; }
+.pd-deadlines td { padding:9px 12px 9px 0; border-top:1px solid var(--pd-line);
+  vertical-align:top; }
+.pd-mono { font-family:'IBM Plex Mono', monospace; font-weight:600; }
+.pd-date { color:var(--pd-amber); white-space:nowrap; }
+.pd-amount { white-space:nowrap; }
+
+.pd-meta { color:var(--pd-dim); font-size:.88rem; padding:4px 2px 0; }
+footer { display:none !important; }
+"""
+
+EXAMPLE_LEGIT = """ПрАТ «Закарпаттяобленерго»
+Вих. № 1123/05 від 03.06.2026
+
+Шановний споживачу!
+За особовим рахунком № 4471102 станом на 01.06.2026 обліковується заборгованість за спожиту електричну енергію в сумі 1847,50 грн. Просимо погасити заборгованість у повному обсязі до 25.06.2026. У разі непогашення заборгованості у зазначений термін постачання електричної енергії може бути припинено відповідно до п. 7 Правил роздрібного ринку електричної енергії.
+Довідки за телефоном: 0800-50-60-22."""
+
+EXAMPLE_SCAM = """UA-BANK ПОВІДОМЛЕННЯ
+
+Шановний клієнт! Ваша банківська картка ЗАБЛОКОВАНА у зв'язку з підозрілою операцією. Для розблокування картки терміново перейдіть за посиланням та підтвердіть свої дані протягом 12 годин: http://privat24-secure.com-ua-card.info/unlock
+У разі непідтвердження даних кошти на рахунку будуть утримані.
+Служба безпеки банку."""
+
+with gr.Blocks(title="Paper Decoder — Розшифровувач паперів") as demo:
+    gr.HTML(
+        '<div class="pd-header">'
+        '<div class="pd-wordmark">Розшифровувач <span class="accent">паперів</span></div>'
+        '<div class="pd-tagline">Сфотографуйте офіційний лист — отримаєте просте пояснення, '
+        "список дій, усі дати й суми та перевірку на шахрайство. "
+        "Працює повністю на цьому сервері, лист нікуди не надсилається.</div></div>"
+    )
+    with gr.Row():
+        with gr.Column(scale=5):
+            image = gr.Image(
+                type="filepath",
+                sources=["upload"],
+                label="Фото листа / Photo of the letter",
+                height=260,
+            )
+            letter = gr.Textbox(
+                label="Текст листа / Letter text",
+                placeholder="…або вставте текст листа сюди",
+                lines=10,
+            )
+            with gr.Row():
+                decode_btn = gr.Button("Розшифрувати лист", variant="primary", size="lg")
+                clear_btn = gr.ClearButton([image, letter], value="Очистити")
+            gr.Examples(
+                examples=[[EXAMPLE_LEGIT], [EXAMPLE_SCAM]],
+                inputs=[letter],
+                label="Приклади / Examples",
+            )
+        with gr.Column(scale=6):
+            result = gr.HTML(
+                '<div class="pd-meta">Тут з\'явиться розшифровка листа.</div>'
+            )
+
+    image.upload(do_ocr, inputs=[image], outputs=[letter])
+    decode_btn.click(decode, inputs=[letter], outputs=[result])
+    letter.submit(decode, inputs=[letter], outputs=[result])
+
+if __name__ == "__main__":
+    demo.launch(css=CSS)

requirements.txt

@@ -0,0 +1,4 @@
+gradio==6.17.3
+pytesseract==0.3.13
+pillow==12.2.0
+requests==2.34.2

start.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MODEL="$(find /opt/models -name '*.gguf' | head -n1)"
+if [ -z "$MODEL" ]; then
+  echo "FATAL: no .gguf found in /opt/models" >&2
+  exit 1
+fi
+echo ">> starting llama-server with $MODEL"
+
+/opt/llama/llama-server \
+  -m "$MODEL" \
+  --host 127.0.0.1 \
+  --port 8081 \
+  -c 4096 \
+  -t "$(nproc)" \
+  --jinja &
+
+echo ">> waiting for llama-server health ..."
+until curl -sf http://127.0.0.1:8081/health > /dev/null; do
+  sleep 2
+done
+echo ">> llama-server is up, starting Gradio"
+
+exec python3 app.py