Post Audit MVP — Gradio Space (hybrid rules + Gemma 4 E4B on Modal)

README.md

@@ -1,13 +1,22 @@
 ---
 title: Post Audit
-emoji: 🦀
-colorFrom: green
-colorTo: pink
+emoji: 📋
+colorFrom: blue
+colorTo: green
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: "5.12.0"
 app_file: app.py
 pinned: false
+license: apache-2.0
+short_description: Audit posts against goal & audience (Gemma 4 + rules)
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Post Audit
+
+Brief-aware social post audit for the [build-small-hackathon](https://huggingface.co/build-small-hackathon) Backyard AI track.
+
+**Model:** Gemma 4 E4B (4.5B effective parameters, ≤32B hackathon limit)  
+**Inference:** Modal GPU endpoint  
+**Host:** Rule linters + deterministic score recomputation
+
+Set Space secret `MODAL_AUDIT_URL` to your deployed Modal web endpoint base URL (without trailing `/audit`).

app.py

@@ -0,0 +1,94 @@
+"""Post Audit — Gradio Space entrypoint."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from audit_client import backend_label, call_modal_audit
+from examples import EXAMPLE_CHAT_DUMP, EXAMPLE_WEBINAR
+from merge import merge_audit, viewer_payload
+from render import render_report_html
+from rules import run_rules
+
+
+def run_audit(platform: str, goal: str, audience: str, post: str):
+    if not post.strip():
+        return "<p>Enter a post to audit.</p>", {}
+
+    rule_warnings = run_rules(platform, goal, audience, post)
+    try:
+        llm_payload = call_modal_audit(platform, goal, audience, post)
+    except Exception as exc:
+        err = f"<p style='color:#b3261e'>Audit failed: {exc}</p>"
+        return err, {}
+
+    merged = merge_audit(llm_payload, rule_warnings)
+    view = viewer_payload(merged)
+    report_html = render_report_html(view)
+
+    status = (
+        f"<p><strong>Done.</strong> Inference: {backend_label()}. "
+        f"Rule warnings: {len(rule_warnings)}.</p>"
+    )
+
+    return status + report_html, merged
+
+
+def load_example(example: dict):
+    return example["platform"], example["goal"], example["audience"], example["post"]
+
+
+with gr.Blocks(title="Post Audit", theme=gr.themes.Soft()) as demo:
+    gr.Markdown(
+        """
+# Post Audit
+Audit a social post against your **goal** and **audience** before you publish.
+
+Hybrid pipeline: deterministic rule linters + **Gemma 4 E4B** (4.5B effective) on Modal.
+First run may take ~30s while the GPU container starts.
+"""
+    )
+
+    with gr.Row():
+        platform = gr.Dropdown(
+            choices=["Telegram", "LinkedIn", "X/Twitter", "Other"],
+            value="Telegram",
+            label="Platform",
+        )
+    goal = gr.Textbox(label="Goal", placeholder="Register attendees for Thursday 7pm webinar")
+    audience = gr.Textbox(
+        label="Audience",
+        placeholder="Product managers who own product metrics",
+    )
+    post = gr.Textbox(
+        label="Post draft",
+        lines=10,
+        placeholder="Paste your post here…",
+    )
+
+    with gr.Row():
+        audit_btn = gr.Button("Run audit", variant="primary")
+        ex_webinar = gr.Button("Load example: weak webinar CTA")
+        ex_chat = gr.Button("Load example: chat dump")
+
+    status_report = gr.HTML()
+
+    with gr.Accordion("Raw JSON", open=False):
+        raw_json = gr.JSON(label="Pipeline output")
+
+    audit_btn.click(
+        fn=run_audit,
+        inputs=[platform, goal, audience, post],
+        outputs=[status_report, raw_json],
+    )
+    ex_webinar.click(
+        fn=lambda: load_example(EXAMPLE_WEBINAR),
+        outputs=[platform, goal, audience, post],
+    )
+    ex_chat.click(
+        fn=lambda: load_example(EXAMPLE_CHAT_DUMP),
+        outputs=[platform, goal, audience, post],
+    )
+
+if __name__ == "__main__":
+    demo.launch()

audit_client.py

@@ -0,0 +1,205 @@
+"""HTTP client for Modal audit endpoint with mock fallback."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Any
+
+from merge import parse_llm_json
+from prompts import FEW_SHOT_ASSISTANT, build_messages
+
+
+def get_modal_url() -> str | None:
+    return os.environ.get("MODAL_AUDIT_URL") or os.environ.get("MODAL_AUDIT_ENDPOINT")
+
+
+def get_modal_timeout() -> float:
+    # Warm latency is ~50s, but a cold container must download + load the ~16 GB
+    # model first, which pushes the first request past 2 min. Generous default.
+    return float(os.environ.get("MODAL_AUDIT_TIMEOUT", "300"))
+
+
+def get_ollama_model() -> str | None:
+    """Local Ollama model tag (e.g. 'gemma3:4b'); enables the local-LLM path."""
+    return os.environ.get("OLLAMA_MODEL")
+
+
+def get_ollama_url() -> str:
+    return os.environ.get("OLLAMA_URL", "http://localhost:11434")
+
+
+def get_ollama_timeout() -> float:
+    # Local CPU/Metal inference is slow: a full audit is ~2.5 min on an M1 with
+    # gemma3:4b, and the first (cold) call adds model-load time. Generous default.
+    return float(os.environ.get("OLLAMA_TIMEOUT", "300"))
+
+
+def backend_label() -> str:
+    """Human-readable description of the inference backend run() will use."""
+    if get_modal_url():
+        return "live Gemma 4 E4B on Modal"
+    model = get_ollama_model()
+    if model:
+        return f"local Ollama ({model})"
+    return "mock LLM (set MODAL_AUDIT_URL or OLLAMA_MODEL)"
+
+
+def call_modal_audit(
+    platform: str,
+    goal: str,
+    audience: str,
+    post: str,
+    *,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Dispatch to a backend: Modal endpoint, local Ollama, or deterministic mock."""
+    if timeout is None:
+        timeout = get_modal_timeout()
+    url = get_modal_url()
+    if not url:
+        if get_ollama_model():
+            return _call_ollama(platform, goal, audience, post)
+        return _mock_llm_response(platform, goal, audience, post)
+
+    payload = json.dumps(
+        {
+            "platform": platform,
+            "goal": goal,
+            "audience": audience,
+            "post": post,
+        }
+    ).encode("utf-8")
+    # Modal serves a single fastapi_endpoint at the root of its URL — no path suffix.
+    headers = {"Content-Type": "application/json"}
+    token = os.environ.get("MODAL_AUDIT_TOKEN")
+    if token:
+        headers["X-Audit-Token"] = token
+    req = urllib.request.Request(
+        url.rstrip("/"),
+        data=payload,
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Modal HTTP {exc.code}: {body}") from exc
+
+    if "raw" in data:
+        return parse_llm_json(data["raw"])
+    return data
+
+
+def _ollama_chat(model: str, messages: list[dict[str, str]], timeout: float) -> str:
+    """POST messages to Ollama's /api/chat with JSON-constrained output; return content."""
+    body = json.dumps(
+        {
+            "model": model,
+            "messages": messages,
+            "stream": False,
+            "format": "json",  # constrain output to valid JSON
+            "options": {"temperature": 0, "num_predict": 2048},
+        }
+    ).encode("utf-8")
+    req = urllib.request.Request(
+        get_ollama_url().rstrip("/") + "/api/chat",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
+        raise RuntimeError(f"Ollama HTTP {exc.code}: {detail}") from exc
+    except urllib.error.URLError as exc:
+        raise RuntimeError(
+            f"Cannot reach Ollama at {get_ollama_url()} — is it running? ({exc.reason})"
+        ) from exc
+    return data.get("message", {}).get("content", "")
+
+
+def _call_ollama(
+    platform: str,
+    goal: str,
+    audience: str,
+    post: str,
+    *,
+    timeout: float | None = None,
+) -> dict[str, Any]:
+    """Run the audit against a local Ollama model. First call may be slow (model load)."""
+    if timeout is None:
+        timeout = get_ollama_timeout()
+    model = get_ollama_model()
+    messages = build_messages(platform, goal, audience, post)
+    raw = _ollama_chat(model, messages, timeout)
+    try:
+        return parse_llm_json(raw)
+    except (json.JSONDecodeError, ValueError):
+        # One retry with an explicit instruction, mirroring the Modal path.
+        retry = messages + [
+            {"role": "user", "content": "Return ONLY valid JSON matching the schema. No other text."}
+        ]
+        return parse_llm_json(_ollama_chat(model, retry, timeout))
+
+
+def _mock_llm_response(
+    platform: str,
+    goal: str,
+    audience: str,
+    post: str,
+) -> dict[str, Any]:
+    """Deterministic mock when Modal URL is unset — uses few-shot shape for webinar-like posts."""
+    del platform, goal, audience
+    lower = post.lower()
+    if "link in bio" in lower or "webinar" in lower:
+        return json.loads(FEW_SHOT_ASSISTANT)
+    return {
+        "briefCheck": {
+            "status": "ok",
+            "inferred": {
+                "goal": "Unclear from post — needs editor review",
+                "audience": "In-context colleagues",
+            },
+            "gaps": [],
+        },
+        "auditReport": {
+            "goalAlignment": {
+                "overall": 40,
+                "cappedBy": [],
+                "dimensions": [
+                    {"key": "hook", "score": 2, "rationale": "Opening lacks a clear stake or benefit."},
+                    {"key": "clarity", "score": 2, "rationale": "Multiple topics mixed in one dump."},
+                    {"key": "audienceFit", "score": 3, "rationale": "Jargon may fit insiders but structure is rough."},
+                    {"key": "goalService", "score": 2, "rationale": "Does not clearly drive the stated goal actions."},
+                    {"key": "cta", "score": 2, "rationale": "Call to action is logistics-only or missing deadline."},
+                ],
+                "summary": "Mock audit (set MODAL_AUDIT_URL for live Gemma 4 E4B). Post needs structure and a clearer CTA.",
+            },
+            "warnings": [
+                {
+                    "code": "MIXED_MESSAGES",
+                    "severity": "warning",
+                    "source": "llm",
+                    "message": "Artifact, task, and logistics appear mixed.",
+                },
+                {
+                    "code": "NO_CLEAR_CTA",
+                    "severity": "warning",
+                    "source": "llm",
+                    "message": "No explicit personal action with a deadline.",
+                },
+            ],
+            "rewriteHints": [
+                "Lead with why the reader should act now.",
+                "Separate artifact, task, and logistics into sections.",
+                "Add one explicit CTA with a deadline.",
+            ],
+        },
+    }

examples.py

@@ -0,0 +1,30 @@
+"""Demo inputs for the Gradio Space."""
+
+EXAMPLE_WEBINAR = {
+    "platform": "Telegram",
+    "goal": "Register attendees for Thursday 7pm webinar",
+    "audience": "Product managers who own product metrics",
+    "post": (
+        "Webinar on product metrics 🚀🚀 Link in bio!!! "
+        "#product #metrics #growth #pm #webinar #training #analytics"
+    ),
+}
+
+EXAMPLE_CHAT_DUMP = {
+    "platform": "Telegram",
+    "goal": (
+        "Activate participants on 3 actions: read materials, write their own "
+        "conduit version, refine the schema"
+    ),
+    "audience": "Working group on decision methodology — colleagues in context",
+    "post": """Handbook (https://example.com/handbook) with checklists
+
+[6/5/26 5:10 PM] Pavel Trubin:
+Conduit zero-version:
+- fragment one with typos and missing context
+- another fragment referencing ontology without link
+
+Please improve this conduit and turn it into a schema. Substantive thoughts go on the miro board.
+
+Any and all important decisions will be made one way or another — complexity sits on both sides of the moment.""",
+}

merge.py

@@ -0,0 +1,104 @@
+"""Merge LLM output with rule warnings and recompute scores."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+DIMENSION_KEYS = ("hook", "clarity", "audienceFit", "goalService", "cta")
+
+
+def parse_llm_json(raw: str) -> dict[str, Any]:
+    text = raw.strip()
+    if text.startswith("```"):
+        text = text.split("\n", 1)[-1]
+        if text.endswith("```"):
+            text = text[:-3]
+        text = text.strip()
+    start = text.find("{")
+    end = text.rfind("}")
+    if start == -1 or end == -1:
+        raise ValueError("No JSON object found in model output")
+    return json.loads(text[start : end + 1])
+
+
+def recompute_overall(dimensions: list[dict[str, Any]], capped_by: list[str]) -> int:
+    scores = [int(d.get("score", 0)) for d in dimensions if d.get("key") in DIMENSION_KEYS]
+    if not scores:
+        return 0
+    overall = round(sum(scores) / len(scores) / 5 * 100)
+    if capped_by:
+        overall = min(overall, 39)
+    return overall
+
+
+def merge_warnings(
+    llm_warnings: list[dict[str, Any]],
+    rule_warnings: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    by_code: dict[str, dict[str, Any]] = {}
+    for w in llm_warnings:
+        code = w.get("code")
+        if code:
+            by_code[code] = w
+    for w in rule_warnings:
+        code = w.get("code")
+        if code:
+            by_code[code] = w  # rule wins on conflict
+    return list(by_code.values())
+
+
+def capped_by_from_warnings(warnings: list[dict[str, Any]]) -> list[str]:
+    return sorted({w["code"] for w in warnings if w.get("severity") == "critical" and w.get("code")})
+
+
+def merge_audit(
+    llm_payload: dict[str, Any],
+    rule_warnings: list[dict[str, Any]],
+) -> dict[str, Any]:
+    brief = llm_payload.get("briefCheck") or {}
+    status = brief.get("status", "ok")
+
+    if status == "needs_clarification":
+        return {"briefCheck": brief, "auditReport": None}
+
+    audit = llm_payload.get("auditReport")
+    if not audit:
+        return {"briefCheck": brief, "auditReport": None}
+
+    ga = audit.get("goalAlignment") or {}
+    dimensions = ga.get("dimensions") or []
+    llm_warnings = audit.get("warnings") or audit.get("warnings_llm") or []
+    rewrite_hints = audit.get("rewriteHints") or []
+
+    warnings = merge_warnings(llm_warnings, rule_warnings)
+    capped = capped_by_from_warnings(warnings)
+    overall = recompute_overall(dimensions, capped)
+
+    goal_alignment = {
+        "overall": overall,
+        "cappedBy": capped,
+        "dimensions": dimensions,
+        "summary": ga.get("summary") or "",
+    }
+
+    return {
+        "briefCheck": brief,
+        "auditReport": {
+            "goalAlignment": goal_alignment,
+            "warnings": warnings,
+            "rewriteHints": rewrite_hints,
+        },
+    }
+
+
+def viewer_payload(merged: dict[str, Any]) -> dict[str, Any]:
+    """Flatten merged output for post-audit-viewer (audit section only)."""
+    brief = merged.get("briefCheck")
+    audit = merged.get("auditReport")
+    if audit is None and brief:
+        return brief
+    if audit:
+        return audit
+    return merged

platform_config.py

@@ -0,0 +1,51 @@
+"""Platform-specific thresholds for rule linters."""
+
+HASHTAG_LIMITS = {
+    "telegram": 3,
+    "linkedin": 5,
+    "x": 3,
+    "twitter": 3,
+    "other": 5,
+}
+
+ACTIVATING_GOAL_KEYWORDS = (
+    "register",
+    "sign up",
+    "signup",
+    "rsvp",
+    "join",
+    "attend",
+    "apply",
+    "submit",
+    "deadline",
+    "webinar",
+    "event",
+    "book",
+    "buy",
+    "donate",
+    "vote",
+    "enroll",
+)
+
+TIME_PATTERNS = (
+    r"\b\d{1,2}[/:]\d{2}\b",
+    r"\b\d{1,2}\s*(am|pm)\b",
+    r"\b(monday|tuesday|wednesday|thursday|friday|saturday|sunday)\b",
+    r"\b(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\w*\b",
+    r"\b\d{1,2}\s+(jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)\w*\b",
+    r"\bby\s+(tomorrow|tonight|eod|end of day)\b",
+    r"\b\d{4}-\d{2}-\d{2}\b",
+)
+
+
+def normalize_platform(platform: str) -> str:
+    p = (platform or "other").strip().lower()
+    if p in ("x/twitter", "x / twitter"):
+        return "x"
+    if p.startswith("twitter"):
+        return "twitter"
+    return p if p in HASHTAG_LIMITS else "other"
+
+
+def hashtag_limit(platform: str) -> int:
+    return HASHTAG_LIMITS.get(normalize_platform(platform), HASHTAG_LIMITS["other"])

prompts.py

@@ -0,0 +1,128 @@
+"""LLM prompts for post audit (LLM-judgment codes only)."""
+
+from __future__ import annotations
+
+from platform_config import hashtag_limit, normalize_platform
+
+SYSTEM_PROMPT = """You are a social media editor. Audit the post against the stated goal and audience. Return STRICTLY valid JSON matching the schema below.
+No text outside JSON: no preamble, no markdown fences, no comments. Response starts with { and ends with }.
+
+INPUT (in the user message): platform, goal, audience, post.
+
+STEP 0 — brief check (briefCheck).
+- Goal is verifiable if there is an observable outcome and direction (not vague "engagement" but a concrete action or result).
+- Audience is verifiable if role/level/context is clear (not "everyone" or "professionals").
+- Always output inferred.goal and inferred.audience from the post text — your interpretation even if the brief is fine.
+- If a brief field is vague, add a gaps object: field ("goal"|"audience"), reason, candidates (2–4 concrete options).
+- status="ok" if audit is possible (including on inferred). status="needs_clarification" only if goal is completely unverifiable; then auditReport=null.
+
+STEP 1 — goal dimensions (5 items, integer scores 1–5). Anchors:
+[hook]        1=first line repels/empty; 3=neutral, not compelling; 5=stakes/benefit/hook clear from line one.
+[clarity]     1=unclear what this is and why; 3=readable but scattered/multi-topic; 5=one clear core, easy to retell.
+[audienceFit] 1=jargon/level wrong for audience; 3=mostly ok, some misses; 5=language, level, examples fit audience.
+[goalService] 1=does not advance goal; 3=partial, gaps remain; 5=directly triggers actions stated in goal.
+[cta]         1=no call to action; 3=present but vague or no deadline; 5=one clear CTA: action + deadline.
+In rationale — one short phrase in the post's language explaining the score.
+
+STEP 2 — warnings (warnings). Use ONLY codes from the catalog below (LLM judgment only — rule checks run separately on the host).
+For each triggered warning: code, severity, source="llm", message (post language), evidence (verbatim excerpt from post ≤12 words; omit if not tied to a fragment).
+severity ∈ {info, warning, critical}. Use critical only when the defect blocks the goal; GOAL_ACTION_MISMATCH is always critical.
+
+CATALOG (code — default severity — when to fire):
+GOAL_ACTION_MISMATCH   — critical — post does not ask for the action stated in the goal.
+BURIED_LEDE            — warning  — main value/motive buried at the end; critical if goal is activating.
+GOAL_DRIFT             — warning  — ask is broader/different from declared goal.
+WEAK_DELIVERABLE_NAMING— info     — vague ask ("insights", "think about") instead of concrete deliverable.
+NO_CLEAR_CTA           — warning  — no explicit CTA or CTA is logistics-only; critical if action is mandatory and absent.
+DIFFUSE_ASKS           — warning  — ≥3 different asks in one post, focus blurred.
+MIXED_MESSAGES         — warning  — artifact + task + logistics + philosophy mixed together.
+EFFORT_ASYMMETRY       — warning  — sloppy/raw post while asking for careful work.
+CLICKBAIT              — warning  — promise not backed by content; critical if strongly misleading.
+TONE_MISMATCH          — warning  — tone/jargon level mismatches audience.
+COGNITIVE_LOAD         — warning  — dense jargon + cross-references, hard to hold in mind.
+AI_TELL                — info     — clichés like "in today's fast-changing world".
+
+STEP 3 — goalAlignment assembly (host will recompute overall and cappedBy — still fill them for completeness).
+- summary = 1–2 phrases in post language: what works and what pulls down.
+- rewriteHints = 3–6 concrete edits in post language.
+
+LANGUAGE: human-readable fields (rationale, message, summary, reason, candidates, rewriteHints, inferred.*) in the post's language. Keys and enums (code, severity, source, key, status, field) in Latin as in schema.
+
+OUTPUT SCHEMA (return exactly one object):
+{
+  "briefCheck": {
+    "status": "ok" | "needs_clarification",
+    "inferred": { "goal": string, "audience": string },
+    "gaps": [ { "field": "goal"|"audience", "reason": string, "candidates": [string, ...] } ]
+  },
+  "auditReport": {
+    "goalAlignment": {
+      "overall": integer,
+      "cappedBy": [string, ...],
+      "dimensions": [ { "key": "hook"|"clarity"|"audienceFit"|"goalService"|"cta", "score": 1..5, "rationale": string } ],
+      "summary": string
+    },
+    "warnings": [ { "code": string, "severity": "info"|"warning"|"critical", "source": "llm", "message": string, "evidence": string (optional) } ],
+    "rewriteHints": [string, ...]
+  } | null
+}
+
+HARD RULES: JSON only; scores integers 1–5; codes only from catalog; evidence verbatim from post; no extra fields; auditReport=null when status="needs_clarification"."""
+
+FEW_SHOT_USER = """platform: telegram
+goal: Register attendees for Thursday 7pm webinar
+audience: Product managers who own product metrics
+post:
+Webinar on product metrics 🚀🚀 Link in bio!!! #product #metrics #growth #pm #webinar #training #analytics"""
+
+FEW_SHOT_ASSISTANT = """{
+  "briefCheck": {
+    "status": "ok",
+    "inferred": { "goal": "Register for product metrics webinar (Thu 7pm)", "audience": "Product managers working with metrics" },
+    "gaps": []
+  },
+  "auditReport": {
+    "goalAlignment": {
+      "overall": 39,
+      "cappedBy": ["GOAL_ACTION_MISMATCH"],
+      "dimensions": [
+        { "key": "hook", "score": 2, "rationale": "Opens with generic 'webinar on metrics' — no benefit or hook." },
+        { "key": "clarity", "score": 3, "rationale": "Topic is clear but when/where/how to register is missing." },
+        { "key": "audienceFit", "score": 3, "rationale": "Topic fits PMs but tone is ad-like." },
+        { "key": "goalService", "score": 2, "rationale": "Cannot register: no link in post, no date/time." },
+        { "key": "cta", "score": 2, "rationale": "'Link in bio' is not an action; no registration form." }
+      ],
+      "summary": "Topic is clear but the post does not drive registration: no direct link, date, or clear CTA."
+    },
+    "warnings": [
+      { "code": "NO_CLEAR_CTA", "severity": "warning", "source": "llm", "message": "CTA is logistics ('link in bio'), not registration.", "evidence": "Link in bio" },
+      { "code": "GOAL_ACTION_MISMATCH", "severity": "critical", "source": "llm", "message": "Goal is registration but post does not enable signing up.", "evidence": "Link in bio" }
+    ],
+    "rewriteHints": [
+      "Put a direct registration link in the post, not 'in bio'.",
+      "State date and time (Thursday 7pm) in the text.",
+      "Replace ad tone with concrete takeaway: what attendees leave with.",
+      "Cut hashtags to 2–3 relevant ones."
+    ]
+  }
+}"""
+
+
+def build_user_message(platform: str, goal: str, audience: str, post: str) -> str:
+    plat = normalize_platform(platform)
+    limit = hashtag_limit(platform)
+    return f"""platform: {plat}
+hashtag_limit: {limit}
+goal: {goal}
+audience: {audience}
+post:
+{post}"""
+
+
+def build_messages(platform: str, goal: str, audience: str, post: str) -> list[dict[str, str]]:
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": FEW_SHOT_USER},
+        {"role": "assistant", "content": FEW_SHOT_ASSISTANT},
+        {"role": "user", "content": build_user_message(platform, goal, audience, post)},
+    ]

render.py

@@ -0,0 +1,260 @@
+"""Render audit JSON as HTML for Gradio (ported from post-audit-viewer.html)."""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any
+
+DIM_LABELS = {
+    "hook": "Hook",
+    "clarity": "Clarity",
+    "audienceFit": "Audience fit",
+    "goalService": "Goal service",
+    "cta": "Call to action",
+}
+
+SEV_ORDER = {"critical": 0, "warning": 1, "info": 2}
+SEV_CLASS = {"critical": "crit", "warning": "warn", "info": "info"}
+
+
+def _esc(s: Any) -> str:
+    return html.escape(str(s if s is not None else ""))
+
+
+def _band_color(pct: int) -> str:
+    if pct < 40:
+        return "var(--crit)"
+    if pct < 70:
+        return "var(--warn)"
+    return "var(--ok)"
+
+
+def _dim_color(score: int) -> str:
+    if score <= 2:
+        return "var(--crit)"
+    if score == 3:
+        return "var(--warn)"
+    return "var(--ok)"
+
+
+def _gauge(pct: int) -> str:
+    r = 60
+    c = 2 * 3.14159265 * r
+    off = c * (1 - max(0, min(100, pct)) / 100)
+    col = _band_color(pct)
+    return f"""<div class="gauge">
+      <svg width="138" height="138" viewBox="0 0 138 138">
+        <circle cx="69" cy="69" r="{r}" fill="none" stroke="#ece6d8" stroke-width="9"/>
+        <circle cx="69" cy="69" r="{r}" fill="none" stroke="{col}" stroke-width="9" stroke-linecap="round"
+          stroke-dasharray="{c:.1f}" stroke-dashoffset="{off:.1f}" transform="rotate(-90 69 69)"/>
+      </svg>
+      <div class="num"><b style="color:{col}">{pct}</b><span>of 100</span></div>
+    </div>"""
+
+
+def _render_audit(data: dict[str, Any]) -> str:
+    ga = data.get("goalAlignment") or {}
+    dims = ga.get("dimensions") or []
+    warns = sorted(
+        data.get("warnings") or [],
+        key=lambda w: SEV_ORDER.get(w.get("severity", "info"), 9),
+    )
+    counts: dict[str, int] = {}
+    for w in warns:
+        sev = w.get("severity", "info")
+        counts[sev] = counts.get(sev, 0) + 1
+    count_str = " · ".join(f"{counts[s]} {s}" for s in ("critical", "warning", "info") if counts.get(s))
+
+    parts = [
+        f"""<section class="sec"><div class="head">
+      {_gauge(int(ga.get("overall") or 0))}
+      <div class="lead">
+        <p class="verdict">{_esc(ga.get("summary") or "")}</p>"""
+    ]
+    capped = ga.get("cappedBy") or []
+    if capped:
+        tags = "".join(f'<span class="tag crit mono">{_esc(c)}</span>' for c in capped)
+        parts.append(f'<div class="capped"><span class="lbl">capped by:</span>{tags}</div>')
+    parts.append("</div></div></section>")
+
+    if dims:
+        parts.append(
+            '<section class="sec"><div class="sec-h"><span>Goal dimensions</span>'
+            '<span class="wcount">score / 5</span></div>'
+        )
+        for dm in dims:
+            s = int(dm.get("score") or 0)
+            pct = (s / 5) * 100
+            col = _dim_color(s)
+            key = dm.get("key", "")
+            parts.append(
+                f"""<div class="dim">
+          <div class="name">{_esc(DIM_LABELS.get(key, key))}<span class="k">{_esc(key)}</span></div>
+          <div class="body">
+            <div class="bar"><div class="track"><div class="fill" style="width:{pct}%;background:{col}"></div></div>
+            <div class="sc">{s}/5</div></div>
+            <div class="rat">{_esc(dm.get("rationale") or "")}</div>
+          </div></div>"""
+            )
+        parts.append("</section>")
+
+    if warns:
+        parts.append(
+            f'<section class="sec"><div class="sec-h"><span>Warnings</span>'
+            f'<span class="wcount">{_esc(count_str)}</span></div>'
+        )
+        for i, w in enumerate(warns):
+            cl = SEV_CLASS.get(w.get("severity", "info"), "info")
+            src = f'<span class="src">{_esc(w.get("source"))}</span>' if w.get("source") else ""
+            ev = (
+                f'<div class="ev">{_esc(w.get("evidence"))}</div>'
+                if w.get("evidence")
+                else ""
+            )
+            parts.append(
+                f"""<div class="w {cl}" style="--i:{i}">
+          <div class="row">
+            <span class="sev {cl}">{_esc(w.get("severity"))}</span>
+            <span class="code">{_esc(w.get("code"))}</span>
+            {src}
+          </div>
+          <div class="msg">{_esc(w.get("message"))}</div>
+          {ev}
+        </div>"""
+            )
+        parts.append("</section>")
+
+    hints = data.get("rewriteHints") or []
+    if hints:
+        items = "".join(f"<li>{_esc(h)}</li>" for h in hints)
+        parts.append(
+            f'<section class="sec"><div class="sec-h"><span>Rewrite hints</span></div>'
+            f'<ol class="hints">{items}</ol></section>'
+        )
+
+    return "".join(parts)
+
+
+def _render_brief(data: dict[str, Any]) -> str:
+    ok = data.get("status") == "ok"
+    status_cls = "ok" if ok else "clar"
+    status_txt = (
+        "Brief accepted — audit uses inferred fields"
+        if ok
+        else "Needs clarification"
+    )
+    inferred = data.get("inferred") or {}
+    parts = [
+        f"""<section class="sec">
+      <span class="status {status_cls}"><span class="dot"></span>{status_txt}</span>
+      <div class="cards2" style="margin-top:16px">
+        <div class="infcard"><div class="t">Goal (inferred)</div><div class="v">{_esc(inferred.get("goal") or "—")}</div></div>
+        <div class="infcard"><div class="t">Audience (inferred)</div><div class="v">{_esc(inferred.get("audience") or "—")}</div></div>
+      </div></section>"""
+    ]
+    for g in data.get("gaps") or []:
+        chips = "".join(f'<span class="chip">{_esc(c)}</span>' for c in g.get("candidates") or [])
+        parts.append(
+            f"""<section class="sec"><div class="sec-h"><span>Gaps</span></div>
+        <div class="gap">
+        <span class="fld">{_esc(g.get("field"))}</span>
+        <div class="reason">{_esc(g.get("reason") or "")}</div>
+        <div class="chips">{chips}</div>
+      </div></section>"""
+        )
+    return "".join(parts)
+
+
+REPORT_CSS = """
+  :root{
+    --paper:#f5f1e8; --card:#fffdf8; --ink:#211f1b; --soft:#5c574d; --faint:#928c7e;
+    --rule:#e2dccd; --rule-2:#d3ccb8;
+    --crit:#b3261e; --crit-bg:#fbe9e6; --warn:#956000; --warn-bg:#faf0d6; --info:#2b5f8a; --info-bg:#e6eef6;
+    --ok:#2f6b34; --ok-bg:#e8f1e3;
+  }
+  .post-audit-report *{box-sizing:border-box}
+  .post-audit-report{
+    background:var(--paper); color:var(--ink);
+    font-family:"Golos Text",system-ui,sans-serif; font-size:16px; line-height:1.6;
+    border:1px solid var(--rule); border-radius:14px; padding:24px 20px;
+  }
+  .post-audit-report .mono{font-family:"JetBrains Mono",monospace}
+  .post-audit-report header.top{border-bottom:2px solid var(--ink);padding-bottom:14px;margin-bottom:20px}
+  .post-audit-report header.top .kicker{font-family:"JetBrains Mono",monospace;font-size:11px;letter-spacing:.22em;text-transform:uppercase;color:var(--faint)}
+  .post-audit-report header.top h1{font-family:Georgia,serif;font-weight:700;font-size:28px;line-height:1.1;margin:6px 0 0}
+  .post-audit-report .sec{margin-top:28px}
+  .post-audit-report .sec-h{font-family:"JetBrains Mono",monospace;font-size:11px;letter-spacing:.2em;text-transform:uppercase;color:var(--faint);
+    border-bottom:1px solid var(--rule);padding-bottom:8px;margin-bottom:18px;display:flex;justify-content:space-between;align-items:baseline}
+  .post-audit-report .head{display:flex;gap:26px;align-items:center;flex-wrap:wrap}
+  .post-audit-report .gauge{flex:0 0 auto;position:relative;width:138px;height:138px}
+  .post-audit-report .gauge .num{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center}
+  .post-audit-report .gauge .num b{font-family:Georgia,serif;font-size:42px;font-weight:700;line-height:1}
+  .post-audit-report .gauge .num span{font-size:11px;color:var(--faint);font-family:"JetBrains Mono",monospace;margin-top:2px}
+  .post-audit-report .head .lead{flex:1 1 280px;min-width:220px}
+  .post-audit-report .head .lead .verdict{font-family:Georgia,serif;font-size:20px;line-height:1.32;font-weight:500;margin:0 0 12px}
+  .post-audit-report .capped{display:flex;flex-wrap:wrap;gap:6px}
+  .post-audit-report .capped .lbl{font-size:11px;color:var(--faint);font-family:"JetBrains Mono",monospace;align-self:center;margin-right:2px}
+  .post-audit-report .tag{font-family:"JetBrains Mono",monospace;font-size:11px;padding:3px 8px;border-radius:6px;border:1px solid;letter-spacing:.02em}
+  .post-audit-report .tag.crit{color:var(--crit);background:var(--crit-bg);border-color:#eecfca}
+  .post-audit-report .dim{display:grid;grid-template-columns:150px 1fr;gap:14px 18px;align-items:start;padding:14px 0;border-bottom:1px solid var(--rule)}
+  .post-audit-report .dim:last-child{border-bottom:none}
+  .post-audit-report .dim .name{font-weight:600;font-size:15px}
+  .post-audit-report .dim .name .k{display:block;font-family:"JetBrains Mono",monospace;font-size:10.5px;color:var(--faint);font-weight:400;margin-top:2px}
+  .post-audit-report .dim .body .bar{display:flex;align-items:center;gap:10px;margin-bottom:7px}
+  .post-audit-report .track{flex:1;height:7px;border-radius:4px;background:#ece6d8;overflow:hidden}
+  .post-audit-report .fill{height:100%;border-radius:4px}
+  .post-audit-report .dim .sc{font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--soft);min-width:30px;text-align:right}
+  .post-audit-report .dim .rat{font-size:14px;color:var(--soft);line-height:1.5}
+  .post-audit-report .wcount{font-family:"JetBrains Mono",monospace;font-size:11px;color:var(--faint);letter-spacing:.04em}
+  .post-audit-report .w{position:relative;background:var(--card);border:1px solid var(--rule);border-left-width:4px;border-radius:10px;padding:13px 16px 15px;margin-bottom:11px}
+  .post-audit-report .w.crit{border-left-color:var(--crit)} .post-audit-report .w.warn{border-left-color:var(--warn)} .post-audit-report .w.info{border-left-color:var(--info)}
+  .post-audit-report .w .row{display:flex;align-items:center;gap:9px;flex-wrap:wrap;margin-bottom:7px}
+  .post-audit-report .sev{font-family:"JetBrains Mono",monospace;font-size:10px;letter-spacing:.12em;text-transform:uppercase;padding:3px 7px;border-radius:5px;font-weight:500}
+  .post-audit-report .sev.crit{color:var(--crit);background:var(--crit-bg)} .post-audit-report .sev.warn{color:var(--warn);background:var(--warn-bg)} .post-audit-report .sev.info{color:var(--info);background:var(--info-bg)}
+  .post-audit-report .code{font-family:"JetBrains Mono",monospace;font-size:12.5px;font-weight:500}
+  .post-audit-report .src{margin-left:auto;font-family:"JetBrains Mono",monospace;font-size:10px;color:var(--faint);border:1px solid var(--rule-2);border-radius:20px;padding:2px 9px}
+  .post-audit-report .w .msg{font-size:14.5px;line-height:1.5}
+  .post-audit-report .ev{margin-top:10px;font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--soft);background:#f3eee2;border-radius:7px;padding:8px 11px;border-left:2px solid var(--rule-2);white-space:pre-wrap;word-break:break-word}
+  .post-audit-report .ev::before{content:"evidence";display:block;font-size:9px;letter-spacing:.16em;text-transform:uppercase;color:var(--faint);margin-bottom:4px}
+  .post-audit-report ol.hints{list-style:none;counter-reset:h;margin:0;padding:0}
+  .post-audit-report ol.hints li{counter-increment:h;position:relative;padding:11px 0 11px 42px;border-bottom:1px solid var(--rule);font-size:15px;line-height:1.5;color:var(--ink)}
+  .post-audit-report ol.hints li:last-child{border-bottom:none}
+  .post-audit-report ol.hints li::before{content:counter(h,decimal-leading-zero);position:absolute;left:0;top:11px;font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--faint);font-weight:500}
+  .post-audit-report .cards2{display:grid;grid-template-columns:1fr 1fr;gap:14px}
+  @media(max-width:620px){.post-audit-report .cards2{grid-template-columns:1fr}.post-audit-report .dim{grid-template-columns:1fr}}
+  .post-audit-report .infcard{background:var(--card);border:1px solid var(--rule);border-radius:11px;padding:15px 17px}
+  .post-audit-report .infcard .t{font-family:"JetBrains Mono",monospace;font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);margin-bottom:7px}
+  .post-audit-report .infcard .v{font-size:15px;line-height:1.5}
+  .post-audit-report .gap{background:var(--card);border:1px solid var(--rule);border-radius:11px;padding:15px 17px;margin-top:13px}
+  .post-audit-report .gap .fld{display:inline-block;font-family:"JetBrains Mono",monospace;font-size:11px;background:var(--warn-bg);color:var(--warn);padding:3px 8px;border-radius:5px;margin-bottom:8px}
+  .post-audit-report .gap .reason{font-size:14.5px;color:var(--soft);margin-bottom:11px}
+  .post-audit-report .chips{display:flex;flex-wrap:wrap;gap:7px}
+  .post-audit-report .chip{font-size:13px;border:1px solid var(--rule-2);border-radius:20px;padding:5px 13px;background:#fcfaf4}
+  .post-audit-report .status{display:inline-flex;align-items:center;gap:8px;font-family:"JetBrains Mono",monospace;font-size:12px;padding:6px 13px;border-radius:8px;font-weight:500}
+  .post-audit-report .status.ok{color:var(--ok);background:var(--ok-bg)} .post-audit-report .status.clar{color:var(--warn);background:var(--warn-bg)}
+  .post-audit-report .dot{width:7px;height:7px;border-radius:50%;background:currentColor}
+"""
+
+
+def render_report_html(payload: dict[str, Any]) -> str:
+    """Build full HTML fragment for gr.HTML from merged or viewer payload."""
+    if payload.get("goalAlignment"):
+        body = _render_audit(payload)
+        subtitle = "Structured audit against your stated goal and audience."
+    elif payload.get("status") or payload.get("inferred"):
+        body = _render_brief(payload)
+        subtitle = "Brief check — clarify gaps before a full audit."
+    else:
+        body = f'<p class="rat">Unexpected payload: {_esc(json.dumps(payload)[:200])}</p>'
+        subtitle = "Report"
+
+    return f"""<div class="post-audit-report">
+<style>{REPORT_CSS}</style>
+<header class="top">
+  <div class="kicker">post audit · pipeline output</div>
+  <h1>Post audit report</h1>
+  <p>{_esc(subtitle)}</p>
+</header>
+{body}
+</div>"""

requirements.txt

@@ -0,0 +1,6 @@
+# Pinned to match the HF Space SDK version in README.md frontmatter (sdk_version).
+# Keep these two in sync so local dev runs the same Gradio as the deployed Space.
+gradio==5.12.0
+# gradio 5.12.0 imports `requests` from its CLI on `import gradio` but does not
+# declare it; the HF base image ships requests, a bare local venv does not.
+requests>=2.31.0

rules.py

@@ -0,0 +1,282 @@
+"""Deterministic rule-based warnings for social post audit."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from platform_config import ACTIVATING_GOAL_KEYWORDS, TIME_PATTERNS, hashtag_limit, normalize_platform
+
+URL_RE = re.compile(r"https?://\S+", re.I)
+HASHTAG_RE = re.compile(r"#\w+", re.UNICODE)
+CHAT_TIMESTAMP_RE = re.compile(
+    r"\[\d{1,2}/\d{1,2}/\d{2,4}\s+\d{1,2}:\d{2}\s*(?:AM|PM)?\]",
+    re.I,
+)
+CHAT_NAME_RE = re.compile(r"^\[[^\]]+\]\s+\w[\w\s.-]{0,40}:", re.M)
+ENGAGEMENT_BAIT_RE = re.compile(
+    r"\b(tag a friend|comment below|double tap|like and share|drop a .? below|"
+    r"share this post|repost if you agree)\b",
+    re.I,
+)
+STRUCTURE_MARKERS_RE = re.compile(
+    r"(^[\s]*[-*•]\s|\n[\s]*[-*•]\s|^\d+\.\s|\n\d+\.\s|^#{1,3}\s|\*\*[^*]+\*\*)",
+    re.M,
+)
+
+
+def detect_post_language(post: str) -> str:
+    if not post.strip():
+        return "en"
+    cyrillic = sum(1 for c in post if "\u0400" <= c <= "\u04FF")
+    return "ru" if cyrillic > len(post) * 0.15 else "en"
+
+
+def _msg(lang: str, en: str, ru: str) -> str:
+    return ru if lang == "ru" else en
+
+
+def _warning(
+    code: str,
+    severity: str,
+    message: str,
+    evidence: str | None = None,
+) -> dict[str, Any]:
+    w: dict[str, Any] = {
+        "code": code,
+        "severity": severity,
+        "source": "rule",
+        "message": message,
+    }
+    if evidence:
+        w["evidence"] = evidence[:120]
+    return w
+
+
+def _first_line(post: str) -> str:
+    lines = [ln.strip() for ln in post.strip().splitlines() if ln.strip()]
+    return lines[0] if lines else ""
+
+
+def _evidence_snippet(text: str, max_words: int = 12) -> str:
+    words = text.split()
+    return " ".join(words[:max_words])
+
+
+def _goal_is_activating(goal: str) -> bool:
+    g = goal.lower()
+    return any(kw in g for kw in ACTIVATING_GOAL_KEYWORDS)
+
+
+def _post_has_deadline(post: str) -> bool:
+    for pat in TIME_PATTERNS:
+        if re.search(pat, post, re.I):
+            return True
+    return False
+
+
+def _check_hashtag_stuffing(post: str, platform: str, lang: str) -> dict[str, Any] | None:
+    tags = HASHTAG_RE.findall(post)
+    limit = hashtag_limit(platform)
+    if len(tags) <= limit:
+        return None
+    return _warning(
+        "HASHTAG_STUFFING",
+        "warning",
+        _msg(
+            lang,
+            f"{len(tags)} hashtags exceed the {normalize_platform(platform)} limit ({limit}).",
+            f"{len(tags)} хэштегов — больше порога для {normalize_platform(platform)} ({limit}).",
+        ),
+        _evidence_snippet(" ".join(tags[:6])),
+    )
+
+
+def _check_chat_dump(post: str, lang: str) -> dict[str, Any] | None:
+    m = CHAT_TIMESTAMP_RE.search(post) or CHAT_NAME_RE.search(post)
+    if not m:
+        return None
+    return _warning(
+        "CHAT_DUMP_FORMAT",
+        "warning",
+        _msg(
+            lang,
+            "Timestamps or chat-style name prefixes look like a pasted conversation, not a composed post.",
+            "Таймстемпы и подписи «Имя:» — похоже на копипаст чата, а не собранный пост.",
+        ),
+        _evidence_snippet(m.group(0)),
+    )
+
+
+def _check_weak_opening(post: str, lang: str) -> dict[str, Any] | None:
+    first = _first_line(post)
+    if not first:
+        return None
+    if URL_RE.fullmatch(first.strip()) or (
+        URL_RE.search(first) and len(first.split()) <= 4
+    ):
+        return _warning(
+            "WEAK_OPENING",
+            "warning",
+            _msg(
+                lang,
+                "First line is a bare link or too thin to hook the reader.",
+                "Первая строка — голая ссылка или слабая зацепка.",
+            ),
+            _evidence_snippet(first),
+        )
+    return None
+
+
+def _check_wall_of_text(post: str, lang: str) -> dict[str, Any] | None:
+    for para in post.split("\n\n"):
+        p = para.strip()
+        if len(p) > 400 and "\n" not in p:
+            return _warning(
+                "WALL_OF_TEXT",
+                "warning",
+                _msg(
+                    lang,
+                    "Long paragraph without line breaks is hard to scan.",
+                    "Длинный абзац без переносов — тяжело читать.",
+                ),
+                _evidence_snippet(p),
+            )
+    return None
+
+
+def _check_no_structure(post: str, lang: str) -> dict[str, Any] | None:
+    if len(post) < 280:
+        return None
+    if STRUCTURE_MARKERS_RE.search(post):
+        return None
+    if post.count("\n") >= 4:
+        return None
+    return _warning(
+        "NO_STRUCTURE",
+        "warning",
+        _msg(
+            lang,
+            "Long post lacks bullets, numbers, or headings — reads as a flat dump.",
+            "Длинный пост без списков и иерархии — плоский дамп.",
+        ),
+        _evidence_snippet(_first_line(post) or post[:80]),
+    )
+
+
+def _check_engagement_bait(post: str, lang: str) -> dict[str, Any] | None:
+    m = ENGAGEMENT_BAIT_RE.search(post)
+    if not m:
+        return None
+    return _warning(
+        "ENGAGEMENT_BAIT",
+        "warning",
+        _msg(
+            lang,
+            "Engagement-bait phrasing detected.",
+            "Обнаружена «приманка» для вовлечения.",
+        ),
+        _evidence_snippet(m.group(0)),
+    )
+
+
+def _check_bare_link(post: str, lang: str) -> dict[str, Any] | None:
+    urls = URL_RE.findall(post)
+    if not urls:
+        return None
+    for url in urls:
+        idx = post.find(url)
+        before = post[max(0, idx - 80) : idx].strip()
+        after = post[idx + len(url) : idx + len(url) + 80].strip()
+        context = (before + " " + after).strip()
+        if len(context.split()) < 6:
+            return _warning(
+                "BARE_LINK",
+                "info",
+                _msg(
+                    lang,
+                    "Link appears without framing — say what's inside and why to open it.",
+                    "Ссылка без рамки — неясно, что внутри и зачем открывать.",
+                ),
+                _evidence_snippet(url),
+            )
+    return None
+
+
+def _check_dense_parenthetical(post: str, lang: str) -> dict[str, Any] | None:
+    for m in re.finditer(r"\([^)]{80,}\)", post):
+        return _warning(
+            "DENSE_PARENTHETICAL",
+            "info",
+            _msg(
+                lang,
+                "Long parenthetical breaks reading flow.",
+                "Длинная вставка в скобках тормозит чтение.",
+            ),
+            _evidence_snippet(m.group(0)),
+        )
+    return None
+
+
+def _check_no_deadline(post: str, goal: str, lang: str) -> dict[str, Any] | None:
+    if not _goal_is_activating(goal):
+        return None
+    if _post_has_deadline(post):
+        return None
+    return _warning(
+        "NO_DEADLINE",
+        "warning",
+        _msg(
+            lang,
+            "Goal implies a time-bound action, but the post has no date or deadline.",
+            "Цель требует действия ко времени, но в посте нет срока.",
+        ),
+        _evidence_snippet(_first_line(post) or post[:60]),
+    )
+
+
+def _check_unresolved_reference(post: str, lang: str) -> dict[str, Any] | None:
+    refs = re.search(
+        r"\b(link in bio|link in profile|see profile|check my profile|"
+        r"registration link|sign up link)\b",
+        post,
+        re.I,
+    )
+    if not refs:
+        return None
+    if URL_RE.search(post):
+        return None
+    return _warning(
+        "UNRESOLVED_REFERENCE",
+        "info",
+        _msg(
+            lang,
+            "Registration or resource is referenced but no URL is in the post.",
+            "Регистрация упомянута, но ссылки в тексте нет.",
+        ),
+        _evidence_snippet(refs.group(0)),
+    )
+
+
+def run_rules(
+    platform: str,
+    goal: str,
+    audience: str,
+    post: str,
+) -> list[dict[str, Any]]:
+    """Run all rule linters and return warning objects."""
+    del audience  # reserved for future rule checks
+    lang = detect_post_language(post)
+    checks = [
+        _check_hashtag_stuffing(post, platform, lang),
+        _check_chat_dump(post, lang),
+        _check_weak_opening(post, lang),
+        _check_wall_of_text(post, lang),
+        _check_no_structure(post, lang),
+        _check_engagement_bait(post, lang),
+        _check_bare_link(post, lang),
+        _check_dense_parenthetical(post, lang),
+        _check_no_deadline(post, goal, lang),
+        _check_unresolved_reference(post, lang),
+    ]
+    return [w for w in checks if w is not None]

static/viewer.html

@@ -0,0 +1,321 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Post Audit — Report Viewer</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Lora:ital,wght@0,500;0,600;0,700;1,500&family=Golos+Text:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+<style>
+  :root{
+    --paper:#f5f1e8; --card:#fffdf8; --ink:#211f1b; --soft:#5c574d; --faint:#928c7e;
+    --rule:#e2dccd; --rule-2:#d3ccb8;
+    --crit:#b3261e; --crit-bg:#fbe9e6; --warn:#956000; --warn-bg:#faf0d6; --info:#2b5f8a; --info-bg:#e6eef6;
+    --ok:#2f6b34; --ok-bg:#e8f1e3;
+  }
+  *{box-sizing:border-box}
+  html,body{margin:0}
+  body{
+    background:var(--paper); color:var(--ink);
+    font-family:"Golos Text",sans-serif; font-size:16px; line-height:1.6;
+    -webkit-font-smoothing:antialiased;
+    background-image:radial-gradient(circle at 18% -10%,#fbf8f0 0,transparent 46%);
+  }
+  .wrap{max-width:900px;margin:0 auto;padding:38px 26px 90px}
+  a{color:var(--info)}
+  .mono{font-family:"JetBrains Mono",monospace}
+
+  /* masthead */
+  header.top{border-bottom:2px solid var(--ink);padding-bottom:14px;margin-bottom:26px}
+  header.top .kicker{font-family:"JetBrains Mono",monospace;font-size:11px;letter-spacing:.22em;text-transform:uppercase;color:var(--faint)}
+  header.top h1{font-family:"Lora",serif;font-weight:700;font-size:34px;line-height:1.04;margin:6px 0 0;letter-spacing:-.01em}
+  header.top p{margin:7px 0 0;color:var(--soft);font-size:14.5px;max-width:60ch}
+
+  /* input */
+  .io{background:var(--card);border:1px solid var(--rule);border-radius:14px;padding:16px;margin-bottom:30px}
+  .io summary{cursor:pointer;font-weight:600;font-size:14px;list-style:none;display:flex;align-items:center;gap:8px}
+  .io summary::-webkit-details-marker{display:none}
+  .io summary .chev{transition:transform .2s;color:var(--faint)}
+  details[open] .io-body{margin-top:14px}
+  textarea{width:100%;min-height:150px;resize:vertical;border:1px solid var(--rule-2);border-radius:9px;
+    padding:12px 13px;font-family:"JetBrains Mono",monospace;font-size:12.5px;line-height:1.55;background:#fcfaf4;color:var(--ink)}
+  textarea:focus{outline:none;border-color:var(--ink)}
+  .btns{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px}
+  button{font-family:inherit;font-size:13px;font-weight:500;cursor:pointer;border-radius:8px;padding:8px 14px;border:1px solid var(--rule-2);background:#fcfaf4;color:var(--ink);transition:.15s}
+  button:hover{border-color:var(--ink)}
+  button.primary{background:var(--ink);color:var(--paper);border-color:var(--ink)}
+  button.primary:hover{opacity:.88}
+  .err{color:var(--crit);font-size:13px;margin-top:10px;font-family:"JetBrains Mono",monospace;display:none}
+
+  /* sections */
+  .sec{margin-top:34px}
+  .sec-h{font-family:"JetBrains Mono",monospace;font-size:11px;letter-spacing:.2em;text-transform:uppercase;color:var(--faint);
+    border-bottom:1px solid var(--rule);padding-bottom:8px;margin-bottom:18px;display:flex;justify-content:space-between;align-items:baseline}
+
+  /* score head */
+  .head{display:flex;gap:26px;align-items:center;flex-wrap:wrap}
+  .gauge{flex:0 0 auto;position:relative;width:138px;height:138px}
+  .gauge .num{position:absolute;inset:0;display:flex;flex-direction:column;align-items:center;justify-content:center}
+  .gauge .num b{font-family:"Lora",serif;font-size:42px;font-weight:700;line-height:1}
+  .gauge .num span{font-size:11px;color:var(--faint);font-family:"JetBrains Mono",monospace;margin-top:2px}
+  .head .lead{flex:1 1 280px;min-width:260px}
+  .head .lead .verdict{font-family:"Lora",serif;font-size:21px;line-height:1.32;font-weight:500;margin:0 0 12px}
+  .capped{display:flex;flex-wrap:wrap;gap:6px}
+  .capped .lbl{font-size:11px;color:var(--faint);font-family:"JetBrains Mono",monospace;align-self:center;margin-right:2px}
+  .tag{font-family:"JetBrains Mono",monospace;font-size:11px;padding:3px 8px;border-radius:6px;border:1px solid;letter-spacing:.02em}
+  .tag.crit{color:var(--crit);background:var(--crit-bg);border-color:#eecfca}
+
+  /* dimensions */
+  .dim{display:grid;grid-template-columns:150px 1fr;gap:14px 18px;align-items:start;padding:14px 0;border-bottom:1px solid var(--rule)}
+  .dim:last-child{border-bottom:none}
+  .dim .name{font-weight:600;font-size:15px}
+  .dim .name .k{display:block;font-family:"JetBrains Mono",monospace;font-size:10.5px;color:var(--faint);font-weight:400;margin-top:2px}
+  .dim .body .bar{display:flex;align-items:center;gap:10px;margin-bottom:7px}
+  .track{flex:1;height:7px;border-radius:4px;background:#ece6d8;overflow:hidden}
+  .fill{height:100%;border-radius:4px;transform-origin:left;animation:grow .7s cubic-bezier(.22,1,.36,1) both}
+  @keyframes grow{from{transform:scaleX(0)}}
+  .dim .sc{font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--soft);min-width:30px;text-align:right}
+  .dim .rat{font-size:14px;color:var(--soft);line-height:1.5}
+
+  /* warnings */
+  .wcount{font-family:"JetBrains Mono",monospace;font-size:11px;color:var(--faint);letter-spacing:.04em}
+  .w{position:relative;background:var(--card);border:1px solid var(--rule);border-left-width:4px;border-radius:10px;
+    padding:13px 16px 15px;margin-bottom:11px;animation:rise .5s cubic-bezier(.22,1,.36,1) both;animation-delay:calc(var(--i,0)*55ms)}
+  @keyframes rise{from{opacity:0;transform:translateY(8px)}}
+  .w.crit{border-left-color:var(--crit)} .w.warn{border-left-color:var(--warn)} .w.info{border-left-color:var(--info)}
+  .w .row{display:flex;align-items:center;gap:9px;flex-wrap:wrap;margin-bottom:7px}
+  .sev{font-family:"JetBrains Mono",monospace;font-size:10px;letter-spacing:.12em;text-transform:uppercase;padding:3px 7px;border-radius:5px;font-weight:500}
+  .sev.crit{color:var(--crit);background:var(--crit-bg)} .sev.warn{color:var(--warn);background:var(--warn-bg)} .sev.info{color:var(--info);background:var(--info-bg)}
+  .code{font-family:"JetBrains Mono",monospace;font-size:12.5px;font-weight:500}
+  .src{margin-left:auto;font-family:"JetBrains Mono",monospace;font-size:10px;color:var(--faint);border:1px solid var(--rule-2);border-radius:20px;padding:2px 9px}
+  .w .msg{font-size:14.5px;line-height:1.5}
+  .ev{margin-top:10px;font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--soft);background:#f3eee2;border-radius:7px;padding:8px 11px;border-left:2px solid var(--rule-2);white-space:pre-wrap;word-break:break-word}
+  .ev::before{content:"evidence";display:block;font-size:9px;letter-spacing:.16em;text-transform:uppercase;color:var(--faint);margin-bottom:4px}
+
+  /* hints */
+  ol.hints{list-style:none;counter-reset:h;margin:0;padding:0}
+  ol.hints li{counter-increment:h;position:relative;padding:11px 0 11px 42px;border-bottom:1px solid var(--rule);font-size:15px;line-height:1.5;color:var(--ink)}
+  ol.hints li:last-child{border-bottom:none}
+  ol.hints li::before{content:counter(h,decimal-leading-zero);position:absolute;left:0;top:11px;font-family:"JetBrains Mono",monospace;font-size:12px;color:var(--faint);font-weight:500}
+
+  /* brief view */
+  .cards2{display:grid;grid-template-columns:1fr 1fr;gap:14px}
+  @media(max-width:620px){.cards2{grid-template-columns:1fr}.dim{grid-template-columns:1fr}}
+  .infcard{background:var(--card);border:1px solid var(--rule);border-radius:11px;padding:15px 17px}
+  .infcard .t{font-family:"JetBrains Mono",monospace;font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:var(--faint);margin-bottom:7px}
+  .infcard .v{font-size:15px;line-height:1.5}
+  .gap{background:var(--card);border:1px solid var(--rule);border-radius:11px;padding:15px 17px;margin-top:13px}
+  .gap .fld{display:inline-block;font-family:"JetBrains Mono",monospace;font-size:11px;background:var(--warn-bg);color:var(--warn);padding:3px 8px;border-radius:5px;margin-bottom:8px}
+  .gap .reason{font-size:14.5px;color:var(--soft);margin-bottom:11px}
+  .chips{display:flex;flex-wrap:wrap;gap:7px}
+  .chip{font-size:13px;border:1px solid var(--rule-2);border-radius:20px;padding:5px 13px;background:#fcfaf4}
+  .status{display:inline-flex;align-items:center;gap:8px;font-family:"JetBrains Mono",monospace;font-size:12px;padding:6px 13px;border-radius:8px;font-weight:500}
+  .status.ok{color:var(--ok);background:var(--ok-bg)} .status.clar{color:var(--warn);background:var(--warn-bg)}
+  .dot{width:7px;height:7px;border-radius:50%;background:currentColor}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header class="top">
+    <div class="kicker">post audit · pipeline output</div>
+    <h1>Post audit report</h1>
+    <p>Paste pipeline JSON — <span class="mono">AuditReport</span> or <span class="mono">BriefCheck</span>. View is detected automatically.</p>
+  </header>
+
+  <details class="io" open>
+    <summary><span class="chev">▾</span> Input JSON</summary>
+    <div class="io-body">
+      <textarea id="src" spellcheck="false"></textarea>
+      <div class="btns">
+        <button class="primary" id="render">Render</button>
+        <button data-sample="audit">Sample: audit</button>
+        <button data-sample="brief">Sample: brief</button>
+        <button id="clear">Clear</button>
+      </div>
+      <div class="err" id="err"></div>
+    </div>
+  </details>
+
+  <div id="out"></div>
+</div>
+
+<script type="application/json" id="sample-audit">
+{
+  "goalAlignment": {
+    "overall": 34,
+    "cappedBy": ["BURIED_LEDE", "GOAL_ACTION_MISMATCH"],
+    "dimensions": [
+      { "key": "hook",        "score": 2, "rationale": "Открывается голой ссылкой и «Кондуит zero-version:». Ни ставки, ни «зачем мне это»." },
+      { "key": "clarity",     "score": 2, "rationale": "Артефакт + задача + логистика + философия смешаны в одном дампе из нескольких сообщений." },
+      { "key": "audienceFit", "score": 3, "rationale": "Жаргон уместен для группы в контексте, но сырость и отсутствие структуры не уважают внимание." },
+      { "key": "goalService", "score": 2, "rationale": "Материалы и черновик для реакции даны (плюс), но три заявленных действия пост напрямую не запускает." },
+      { "key": "cta",         "score": 2, "rationale": "Призыв = логистика (куда писать), без дедлайна и персонального действия." }
+    ],
+    "summary": "Пост даёт материал для работы, но как мотиватор не собран: причина действовать спрятана в конце, а просьба не совпадает с целью."
+  },
+  "warnings": [
+    { "code": "BURIED_LEDE", "severity": "critical", "source": "llm", "message": "Мотивирующая рамка — самый сильный аргумент действовать — стоит в самом конце.", "evidence": "Любые и все важные решения так или иначе будут приняты" },
+    { "code": "GOAL_ACTION_MISMATCH", "severity": "critical", "source": "llm", "message": "Цель требует «написать свою версию кондуита», но пост этого не просит — ставит общую задачу «улучшить и превратить в схему».", "evidence": "вот этот наш кондуит улучшить и ... превратить в схему" },
+    { "code": "NO_CLEAR_CTA", "severity": "warning", "source": "llm", "message": "Призыв описывает, куда писать, но не что именно сделать каждому и к какому сроку.", "evidence": "Содержательные мысли лучше добавлять на miro-доску" },
+    { "code": "EFFORT_ASYMMETRY", "severity": "warning", "source": "llm", "message": "Сырой дамп при просьбе о вдумчивой работе демотивирует: «автор не вложился — почему должен я»." },
+    { "code": "WEAK_OPENING", "severity": "warning", "source": "rule", "message": "Первая строка — голая ссылка; на обрезке «…ещё» зацепки нет.", "evidence": "Справочник (https://agsagds.github.io/...) с чеклистами" },
+    { "code": "CHAT_DUMP_FORMAT", "severity": "warning", "source": "rule", "message": "Вставлены таймстемпы и подписи — выглядит как копипаст истории чата, а не собранный пост.", "evidence": "[6/5/26 5:10 PM] Pavel Trubin:" },
+    { "code": "TYPOS", "severity": "warning", "source": "rule", "message": "Опечатки бьют по доверию в посте, который просит о тщательной работе.", "evidence": "учестом · принтяия · принтяием · данны" },
+    { "code": "NO_STRUCTURE", "severity": "warning", "source": "rule", "message": "«Кондуит zero-version» — плоский список фрагментов без иерархии; тяжело реагировать построчно." }
+  ],
+  "rewriteHints": [
+    "Поднять рамку в начало: решения принимаются всегда, сложности по обе стороны от момента — это и есть зацепка.",
+    "Явный персональный CTA под цель: «прочитай справочник → напиши свою версию кондуита (3–5 строк) → предложи одну правку схемы», с дедлайном.",
+    "Развести артефакт / задачу / логистику; кондуит структурировать в список с иерархией.",
+    "Дать ссылке рамку: что внутри и зачем открыть до того, как писать свою версию.",
+    "Вычитать опечатки — особенно когда просишь о вдумчивой работе."
+  ]
+}
+</script>
+
+<script type="application/json" id="sample-brief">
+{
+  "status": "ok",
+  "inferred": {
+    "goal": "Активировать участников на 3 действия: прочитать материалы, написать свою версию кондуита, доработать схему",
+    "audience": "Рабочая группа по методологии принятия решений — коллеги в контексте, знают термины ЛПР / онтология / кондуит"
+  },
+  "gaps": [
+    { "field": "audience", "reason": "Задана как «участники» без уровня/контекста; выведена из текста, но не подтверждена", "candidates": ["Коллеги глубоко в ко��тексте", "Новые участники, нужен ввод в тему", "Смешанная группа"] }
+  ]
+}
+</script>
+
+<script>
+  const DIM_LABELS = { hook:"Hook", clarity:"Clarity", audienceFit:"Audience fit", goalService:"Goal service", cta:"Call to action" };
+  const SEV_ORDER = { critical:0, warning:1, info:2 };
+  const SEV_CLASS = { critical:"crit", warning:"warn", info:"info" };
+  const SEV_RU    = { critical:"critical", warning:"warning", info:"info" };
+
+  const $ = s => document.querySelector(s);
+  const esc = s => String(s ?? "").replace(/[&<>"]/g, c => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;"}[c]));
+
+  const bandColor = pct => pct < 40 ? "var(--crit)" : pct < 70 ? "var(--warn)" : "var(--ok)";
+  const dimColor  = s   => s <= 2 ? "var(--crit)" : s === 3 ? "var(--warn)" : "var(--ok)";
+
+  function gauge(pct){
+    const r = 60, c = 2 * Math.PI * r, off = c * (1 - Math.max(0, Math.min(100, pct)) / 100);
+    const col = bandColor(pct);
+    return `<div class="gauge">
+      <svg width="138" height="138" viewBox="0 0 138 138">
+        <circle cx="69" cy="69" r="${r}" fill="none" stroke="#ece6d8" stroke-width="9"/>
+        <circle cx="69" cy="69" r="${r}" fill="none" stroke="${col}" stroke-width="9" stroke-linecap="round"
+          stroke-dasharray="${c.toFixed(1)}" stroke-dashoffset="${c.toFixed(1)}" transform="rotate(-90 69 69)"
+          style="animation:dash 1s cubic-bezier(.22,1,.36,1) forwards"/>
+        <style>@keyframes dash{to{stroke-dashoffset:${off.toFixed(1)}}}</style>
+      </svg>
+      <div class="num"><b style="color:${col}">${pct}</b><span>of 100</span></div>
+    </div>`;
+  }
+
+  function renderAudit(d){
+    const ga = d.goalAlignment || {};
+    const dims = ga.dimensions || [];
+    const warns = (d.warnings || []).slice().sort((a,b)=>(SEV_ORDER[a.severity]??9)-(SEV_ORDER[b.severity]??9));
+    const counts = warns.reduce((m,w)=>(m[w.severity]=(m[w.severity]||0)+1,m),{});
+    const countStr = ["critical","warning","info"].filter(s=>counts[s]).map(s=>`${counts[s]} ${s}`).join(" · ");
+
+    let html = `<section class="sec"><div class="head">
+      ${gauge(Number(ga.overall)||0)}
+      <div class="lead">
+        <p class="verdict">${esc(ga.summary || "")}</p>
+        ${(ga.cappedBy||[]).length ? `<div class="capped"><span class="lbl">capped by:</span>${ga.cappedBy.map(c=>`<span class="tag crit mono">${esc(c)}</span>`).join("")}</div>`:""}
+      </div></div></section>`;
+
+    if (dims.length){
+      html += `<section class="sec"><div class="sec-h"><span>Goal dimensions</span><span class="wcount">score / 5</span></div>`;
+      html += dims.map(dm=>{
+        const s = Number(dm.score)||0, pct = (s/5)*100, col = dimColor(s);
+        return `<div class="dim">
+          <div class="name">${esc(DIM_LABELS[dm.key]||dm.key)}<span class="k">${esc(dm.key)}</span></div>
+          <div class="body">
+            <div class="bar"><div class="track"><div class="fill" style="width:${pct}%;background:${col}"></div></div><div class="sc">${s}/5</div></div>
+            <div class="rat">${esc(dm.rationale||"")}</div>
+          </div></div>`;
+      }).join("");
+      html += `</section>`;
+    }
+
+    if (warns.length){
+      html += `<section class="sec"><div class="sec-h"><span>Warnings</span><span class="wcount">${esc(countStr)}</span></div>`;
+      html += warns.map((w,i)=>{
+        const cl = SEV_CLASS[w.severity]||"info";
+        return `<div class="w ${cl}" style="--i:${i}">
+          <div class="row">
+            <span class="sev ${cl}">${esc(SEV_RU[w.severity]||w.severity)}</span>
+            <span class="code">${esc(w.code||"")}</span>
+            ${w.source?`<span class="src">${esc(w.source)}</span>`:""}
+          </div>
+          <div class="msg">${esc(w.message||"")}</div>
+          ${w.evidence?`<div class="ev">${esc(w.evidence)}</div>`:""}
+        </div>`;
+      }).join("");
+      html += `</section>`;
+    }
+
+    if ((d.rewriteHints||[]).length){
+      html += `<section class="sec"><div class="sec-h"><span>Rewrite hints</span></div>
+        <ol class="hints">${d.rewriteHints.map(h=>`<li>${esc(h)}</li>`).join("")}</ol></section>`;
+    }
+    return html;
+  }
+
+  function renderBrief(d){
+    const ok = d.status === "ok";
+    let html = `<section class="sec">
+      <span class="status ${ok?"ok":"clar"}"><span class="dot"></span>${ok?"Brief accepted — audit uses inferred fields":"Needs clarification"}</span>
+      <div class="cards2" style="margin-top:16px">
+        <div class="infcard"><div class="t">Goal (inferred)</div><div class="v">${esc(d.inferred?.goal||"—")}</div></div>
+        <div class="infcard"><div class="t">Audience (inferred)</div><div class="v">${esc(d.inferred?.audience||"—")}</div></div>
+      </div></section>`;
+    if ((d.gaps||[]).length){
+      html += `<section class="sec"><div class="sec-h"><span>Gaps</span></div>`;
+      html += d.gaps.map(g=>`<div class="gap">
+        <span class="fld">${esc(g.field)}</span>
+        <div class="reason">${esc(g.reason||"")}</div>
+        <div class="chips">${(g.candidates||[]).map(c=>`<span class="chip">${esc(c)}</span>`).join("")}</div>
+      </div>`).join("");
+      html += `</section>`;
+    }
+    return html;
+  }
+
+  function render(){
+    const err = $("#err"); err.style.display = "none";
+    let data;
+    try { data = JSON.parse($("#src").value); }
+    catch(e){ err.textContent = "Invalid JSON: " + e.message; err.style.display = "block"; $("#out").innerHTML=""; return; }
+    const out = $("#out");
+    if (data && data.goalAlignment) out.innerHTML = renderAudit(data);
+    else if (data && (data.status || data.gaps || data.inferred)) out.innerHTML = renderBrief(data);
+    else { err.textContent = "Not AuditReport or BriefCheck (missing goalAlignment / status)."; err.style.display="block"; out.innerHTML=""; }
+  }
+
+  function loadSample(which){
+    $("#src").value = $("#sample-"+which).textContent.trim();
+    render();
+  }
+
+  window.renderAuditPayload = function(data) {
+    $("#src").value = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+    render();
+  };
+
+  $("#render").addEventListener("click", render);
+  $("#clear").addEventListener("click", ()=>{ $("#src").value=""; $("#out").innerHTML=""; $("#err").style.display="none"; });
+  document.querySelectorAll("[data-sample]").forEach(b=>b.addEventListener("click",()=>loadSample(b.dataset.sample)));
+
+  if (new URLSearchParams(location.search).get("embed") === "1") {
+    document.querySelector(".io").style.display = "none";
+  } else {
+    loadSample("audit");
+  }
+</script>
+</body>
+</html>