app.py

"""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.

The language radio switches the whole page and the model's answer language.
Ukrainian-first for my parents; English exists so judges can evaluate output.

Build Small Hackathon 2026 · Backyard AI track.
"""

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". Нічого не вигадуй."""

EN_SUFFIX = """

OUTPUT LANGUAGE OVERRIDE: Write the values of "summary", "actions", "what" and "pattern" in ENGLISH (translate the allowed pattern names). Keep dates, amounts and phone numbers exactly as written in the letter. Keep "evidence" quotes verbatim in their original language — they are citations."""

UK = "Українська"
EN = "English"

T = {
    "uk": {
        # result rendering
        "stamp_danger": "Схоже на шахрайство",
        "stamp_ok": "Виглядає як справжній лист",
        "h_summary": "Про що цей лист",
        "h_flags": "Чому це підозріло",
        "h_actions": "Що робити",
        "h_deadlines": "Дати та суми",
        "col_when": "Коли",
        "col_what": "Що",
        "col_amount": "Сума",
        "meta": "Оброблено локально, без інтернет-сервісів",
        "status_read": "Читаю лист…",
        "status_read_d": "Перший запит після запуску може тривати довше.",
        "status_work": "Розшифровую…",
        "status_chars": "символів за",
        "err_empty": "Спочатку додайте лист: сфотографуйте його або вставте текст у поле зліва.",
        "err_conn": "Помилка зв'язку з моделлю:",
        "err_json": "Модель повернула некоректну відповідь. Спробуйте ще раз.",
        # page UI
        "wordmark": 'Розшифровувач <span class="accent">паперів</span>',
        "tagline": (
            "Сфотографуйте офіційний лист — отримаєте просте пояснення, "
            "список дій, усі дати й суми та перевірку на шахрайство. "
            "Працює повністю на цьому сервері, лист нікуди не надсилається."
        ),
        "lbl_image": "Фото листа",
        "lbl_letter": "Текст листа",
        "ph_letter": "…або вставте текст листа сюди",
        "btn_decode": "Розшифрувати лист",
        "btn_clear": "Очистити",
        "lbl_examples": "Приклади",
        "placeholder_result": "Тут з'явиться розшифровка листа.",
    },
    "en": {
        "stamp_danger": "Looks like a scam",
        "stamp_ok": "Looks like a genuine letter",
        "h_summary": "What this letter says",
        "h_flags": "Why it is suspicious",
        "h_actions": "What to do",
        "h_deadlines": "Dates and amounts",
        "col_when": "When",
        "col_what": "What",
        "col_amount": "Amount",
        "meta": "Processed locally, no internet services",
        "status_read": "Reading the letter…",
        "status_read_d": "The first request after startup can take longer.",
        "status_work": "Decoding…",
        "status_chars": "characters in",
        "err_empty": "Add a letter first: photograph it or paste the text on the left.",
        "err_conn": "Model connection error:",
        "err_json": "The model returned a malformed answer. Try again.",
        "wordmark": 'Paper <span class="accent">Decoder</span>',
        "tagline": (
            "Photograph an official Ukrainian letter — get a plain-language "
            "explanation, an action list, every date and amount, and a scam "
            "check. Runs entirely on this server; the letter is sent nowhere."
        ),
        "lbl_image": "Photo of the letter",
        "lbl_letter": "Letter text",
        "ph_letter": "…or paste the letter text here",
        "btn_decode": "Decode the letter",
        "btn_clear": "Clear",
        "lbl_examples": "Examples",
        "placeholder_result": "The decoded letter will appear here.",
    },
}


def lang_code(choice: str) -> str:
    return "en" if choice == EN else "uk"


def header_html(lang: str) -> str:
    t = T[lang]
    return (
        '<div class="pd-header">'
        f'<div class="pd-wordmark">{t["wordmark"]}</div>'
        f'<div class="pd-tagline">{html.escape(t["tagline"])}</div></div>'
    )


# ---------------------------------------------------------------- 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, lang: str):
    """Yield (accumulated_text, completion_tokens, elapsed_s) while streaming."""
    system = SYSTEM_PROMPT + (EN_SUFFIX if lang == "en" else "")
    payload = {
        "model": "paper-decoder",
        "temperature": 0.2,
        "seed": 42,
        "max_tokens": 900,
        "cache_prompt": True,
        "response_format": {"type": "json_object"},
        "stream": True,
        "stream_options": {"include_usage": True},
        "messages": [
            {"role": "system", "content": system},
            {"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()
    try:
        obj = json.loads(candidate)
        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, t: dict) -> str:
    flags = data.get("scam_flags") or []
    is_scam = len(flags) > 0

    if is_scam:
        stamp = f'<div class="pd-stamp pd-stamp-danger">{esc(t["stamp_danger"])}</div>'
    else:
        stamp = f'<div class="pd-stamp pd-stamp-ok">{esc(t["stamp_ok"])}</div>'

    parts = [f'<div class="pd-stamp-row">{stamp}</div>']

    summary = data.get("summary")
    if summary:
        parts.append(
            f'<section class="pd-card"><h3>{esc(t["h_summary"])}</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(
            f'<section class="pd-card pd-card-danger"><h3>{esc(t["h_flags"])}</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(
            f'<section class="pd-card"><h3>{esc(t["h_actions"])}</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(
            f'<section class="pd-card"><h3>{esc(t["h_deadlines"])}</h3>'
            '<table class="pd-deadlines"><thead><tr>'
            f'<th>{esc(t["col_when"])}</th><th>{esc(t["col_what"])}</th><th>{esc(t["col_amount"])}</th>'
            "</tr></thead>"
            f"<tbody>{rows}</tbody></table></section>"
        )

    speed = f" · {tok_s:.1f} tok/s" if tok_s else ""
    parts.append(f'<div class="pd-meta">{esc(t["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, lang_choice: str):
    lang = lang_code(lang_choice)
    t = T[lang]

    letter_text = (letter_text or "").strip()
    if not letter_text or letter_text.startswith("(Не вдалося"):
        yield render_error(t["err_empty"])
        return
    letter_text = letter_text[:MAX_LETTER_CHARS]

    yield render_status(t["status_read"], t["status_read_d"])

    acc, completion_tokens, elapsed = "", 0, 0.0
    try:
        last_yield = 0.0
        for acc, completion_tokens, elapsed in stream_completion(letter_text, lang):
            if elapsed - last_yield >= 1.0:
                last_yield = elapsed
                yield render_status(
                    t["status_work"],
                    f"{len(acc)} {t['status_chars']} {elapsed:.0f} s",
                )
    except requests.RequestException as e:
        yield render_error(f"{t['err_conn']} {e}")
        return

    data = parse_model_json(acc)
    if data is None:
        yield (
            render_error(t["err_json"])
            + 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, t)


def switch_ui(lang_choice: str):
    """Swap every static UI string when the language radio changes."""
    t = T[lang_code(lang_choice)]
    return (
        header_html(lang_code(lang_choice)),
        gr.update(label=t["lbl_image"]),
        gr.update(label=t["lbl_letter"], placeholder=t["ph_letter"]),
        gr.update(value=t["btn_decode"]),
        gr.update(value=t["btn_clear"]),
    )


# --------------------------------------------------------------------- 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:
    header = gr.HTML(header_html("uk"))
    with gr.Row():
        with gr.Column(scale=5):
            image = gr.Image(
                type="filepath",
                sources=["upload"],
                label=T["uk"]["lbl_image"],
                height=260,
            )
            letter = gr.Textbox(
                label=T["uk"]["lbl_letter"],
                placeholder=T["uk"]["ph_letter"],
                lines=10,
            )
            lang = gr.Radio(
                choices=[UK, EN],
                value=UK,
                label="Мова / Language",
            )
            with gr.Row():
                decode_btn = gr.Button(
                    T["uk"]["btn_decode"], variant="primary", size="lg"
                )
                clear_btn = gr.ClearButton([image, letter], value=T["uk"]["btn_clear"])
            gr.Examples(
                examples=[[EXAMPLE_LEGIT], [EXAMPLE_SCAM]],
                inputs=[letter],
                label="Приклади / Examples",
            )
        with gr.Column(scale=6):
            result = gr.HTML(
                '<div class="pd-meta">Тут з\'явиться розшифровка листа. '
                "/ The decoded letter will appear here.</div>"
            )

    image.upload(do_ocr, inputs=[image], outputs=[letter])
    decode_btn.click(decode, inputs=[letter, lang], outputs=[result])
    letter.submit(decode, inputs=[letter, lang], outputs=[result])
    lang.change(
        switch_ui,
        inputs=[lang],
        outputs=[header, image, letter, decode_btn, clear_btn],
    )

if __name__ == "__main__":
    demo.launch(css=CSS)