feed-protocol 0.2.0__py3-none-any.whl

feed/parser.py

@@ -0,0 +1,196 @@
+"""Parse a FEED markdown document back into a FeedDocument.
+
+Robust to extra prose between blocks: we scan for FEED markers and ignore
+everything else (including the visible notice blockquote and headings).
+"""
+
+from __future__ import annotations
+
+from .constants import (
+    CLOSE_MARKER_RE,
+    DEFAULT_GROUNDING,
+    OPEN_MARKER_RE,
+    parse_attrs,
+)
+from .document import FeedDocument
+
+
+def parse(text: str) -> FeedDocument:
+    blocks = _scan_blocks(text)
+
+    # Document-level header.
+    doc_attrs: dict[str, str] = {}
+    meta: dict[str, str] = {}
+    for kind, attrs, body in blocks:
+        if kind == "DOC":
+            doc_attrs = attrs
+        elif kind == "META":
+            meta = _parse_kv(body)
+
+    grounding = doc_attrs.get("grounding") or meta.get("grounding") or DEFAULT_GROUNDING
+    title = meta.get("title") or _first_heading(text) or "Untitled"
+
+    doc = FeedDocument(
+        title=title,
+        author=meta.get("author"),
+        grounding=grounding,
+        created=meta.get("created"),
+        summary=meta.get("summary"),
+        version=doc_attrs.get("version", "0.2"),
+    )
+
+    # Evidence must be added before claims that reference it, so do two passes.
+    for kind, attrs, body in blocks:
+        if kind == "EVIDENCE":
+            eid = attrs.get("id")
+            if not eid:
+                continue
+            fields = _parse_kv(body, drop_keys={"note"}, drop_id_marker=eid)
+            note = _parse_kv(body).get("note")
+            doc.add_evidence(
+                eid,
+                type=attrs.get("type", "data"),
+                confidence=attrs.get("confidence", "medium"),
+                note=note,
+                **fields,
+            )
+
+    for kind, attrs, body in blocks:
+        if kind == "CLAIM":
+            cid = attrs.get("id")
+            if not cid:
+                continue
+            evidence = [
+                e.strip()
+                for e in (attrs.get("evidence", "").split(","))
+                if e.strip()
+            ]
+            text_body = _claim_text(body)
+            doc.add_claim(
+                cid,
+                text=text_body,
+                evidence=evidence,
+                decision=attrs.get("decision") or _claim_decision(body),
+            )
+
+    # Findings: the markdown under a "## Findings" heading that is not inside a
+    # FEED block. Captured separately so round-tripping preserves narrative.
+    for para in _findings_paragraphs(text):
+        doc.add_finding(para)
+
+    return doc
+
+
+# --- low-level scanning ---------------------------------------------------
+def _scan_blocks(text: str):
+    """Yield (kind, attrs_dict, body_text) for every FEED block in order.
+
+    DOC has no body. META/CLAIM/EVIDENCE run until their matching close marker.
+    """
+    results = []
+    pos = 0
+    while True:
+        m = OPEN_MARKER_RE.search(text, pos)
+        if not m:
+            break
+        kind = m.group("kind")
+        attrs = parse_attrs(m.group("attrs"))
+        if kind in ("DOC", "END"):
+            results.append((kind, attrs, ""))
+            pos = m.end()
+            continue
+        close = CLOSE_MARKER_RE.search(text, m.end())
+        if close and close.group("kind") == kind:
+            body = text[m.end() : close.start()]
+            results.append((kind, attrs, body))
+            pos = close.end()
+        else:
+            # Unterminated block — record what we have and move on.
+            results.append((kind, attrs, text[m.end() :]))
+            pos = m.end()
+    return results
+
+
+def _parse_kv(
+    body: str, drop_keys: set[str] | None = None, drop_id_marker: str | None = None
+) -> dict[str, str]:
+    drop_keys = drop_keys or set()
+    out: dict[str, str] = {}
+    for raw in body.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        if drop_id_marker and line in (f"**[{drop_id_marker}]**", f"[{drop_id_marker}]"):
+            continue
+        if ":" not in line:
+            continue
+        key, _, value = line.partition(":")
+        key = key.strip()
+        if not key or " " in key:
+            continue  # not a key/value line (probably prose)
+        if key in drop_keys:
+            continue
+        out[key] = value.strip()
+    return out
+
+
+def _claim_text(body: str) -> str:
+    for raw in body.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("- **Decision:**"):
+            continue
+        # strip trailing [E001][E002] citations from the stored text
+        return _strip_citations(line)
+    return ""
+
+
+def _strip_citations(line: str) -> str:
+    import re
+
+    return re.sub(r"\s*(\[E\d{1,4}\])+\s*$", "", line).strip()
+
+
+def _claim_decision(body: str) -> str | None:
+    for raw in body.splitlines():
+        line = raw.strip()
+        if line.startswith("- **Decision:**"):
+            return line.split("**Decision:**", 1)[1].strip()
+    return None
+
+
+def _first_heading(text: str) -> str | None:
+    for raw in text.splitlines():
+        line = raw.strip()
+        if line.startswith("# "):
+            return line[2:].strip()
+    return None
+
+
+def _findings_paragraphs(text: str) -> list[str]:
+    """Pull paragraphs under '## Findings' up to the next heading, skipping any
+    FEED comment markers."""
+    lines = text.splitlines()
+    out: list[str] = []
+    in_section = False
+    buf: list[str] = []
+    for raw in lines:
+        line = raw.rstrip()
+        stripped = line.strip()
+        if stripped.startswith("## "):
+            if in_section:  # leaving the section
+                break
+            in_section = stripped[3:].strip().lower().startswith("finding")
+            continue
+        if not in_section:
+            continue
+        if stripped.startswith("<!--") or stripped.startswith("# "):
+            continue
+        if not stripped:
+            if buf:
+                out.append(" ".join(buf).strip())
+                buf = []
+            continue
+        buf.append(stripped)
+    if buf:
+        out.append(" ".join(buf).strip())
+    return [p for p in out if p]

feed/render.py

@@ -0,0 +1,209 @@
+"""Render a FeedDocument to Markdown (canonical) or styled HTML.
+
+Document order encodes priority — tier 0 (claims/decisions) first, tier 1
+(findings) next, tier 2 (full evidence) last — so a small-context model that
+truncates the tail still keeps the core.
+"""
+
+from __future__ import annotations
+
+import html as _html
+
+from .constants import ingestion_notice
+from .document import Evidence, FeedDocument
+
+
+def to_markdown(doc: FeedDocument) -> str:
+    out: list[str] = []
+    out.append(f'<!-- FEED:DOC version="{doc.version}" grounding="{doc.grounding}" -->')
+    out.append("")
+    out.append(ingestion_notice(doc.grounding))
+    out.append("")
+    out.append(f"# {doc.title}")
+    out.append("")
+
+    # --- META (machine header) ---
+    out.append("<!-- FEED:META -->")
+    out.append(f"title: {doc.title}")
+    if doc.author:
+        out.append(f"author: {doc.author}")
+    if doc.created:
+        out.append(f"created: {doc.created}")
+    out.append(f"grounding: {doc.grounding}")
+    if doc.summary:
+        out.append(f"summary: {doc.summary}")
+    out.append("<!-- /FEED:META -->")
+    out.append("")
+
+    # --- TIER 0: claims & decisions, front-loaded ---
+    if doc.summary:
+        out.append(f"**TL;DR.** {doc.summary}")
+        out.append("")
+    if doc.claims:
+        out.append("## Claims & Decisions")
+        out.append("")
+        for c in doc.claims:
+            ev = ",".join(c.evidence)
+            attrs = f' id="{c.id}"'
+            if ev:
+                attrs += f' evidence="{ev}"'
+            if c.decision:
+                attrs += f' decision="{_attr(c.decision)}"'
+            out.append(f"<!-- FEED:CLAIM{attrs} -->")
+            line = c.text.strip()
+            if c.evidence:
+                line += " " + "".join(f"[{e}]" for e in c.evidence)
+            out.append(line)
+            if c.decision:
+                out.append(f"- **Decision:** {c.decision}")
+            out.append("<!-- /FEED:CLAIM -->")
+            out.append("")
+
+    # --- TIER 1: findings narrative ---
+    if doc.findings:
+        out.append("## Findings")
+        out.append("")
+        for para in doc.findings:
+            out.append(para.strip())
+            out.append("")
+
+    # --- TIER 2: full evidence appendix ---
+    if doc.evidence:
+        out.append("## Evidence")
+        out.append("")
+        for ev in doc.evidence:
+            out.append(_evidence_md(ev))
+            out.append("")
+
+    out.append("<!-- FEED:END -->")
+    out.append("")
+    return "\n".join(out)
+
+
+def _evidence_md(ev: Evidence) -> str:
+    lines = [
+        f'<!-- FEED:EVIDENCE id="{ev.id}" type="{ev.type}" confidence="{ev.confidence}" -->'
+    ]
+    lines.append(f"**[{ev.id}]**")
+    for k, v in ev.fields.items():
+        lines.append(f"{k}: {v}")
+    if ev.note:
+        lines.append(f"note: {ev.note}")
+    lines.append("<!-- /FEED:EVIDENCE -->")
+    return "\n".join(lines)
+
+
+def _attr(value: str) -> str:
+    return value.replace('"', "'")
+
+
+# --- HTML ----------------------------------------------------------------
+def to_html(doc: FeedDocument) -> str:
+    """Styled, self-contained HTML. FEED markers live in HTML comments so they
+    are invisible on screen but present in the raw source for any AI."""
+    e = _html.escape
+    parts: list[str] = []
+    parts.append("<!doctype html>")
+    parts.append('<html lang="en"><head><meta charset="utf-8">')
+    parts.append(f"<title>{e(doc.title)}</title>")
+    parts.append(f"<!-- FEED:DOC version=\"{doc.version}\" grounding=\"{doc.grounding}\" -->")
+    parts.append(_STYLE)
+    parts.append("</head><body><main>")
+
+    # Visible notice (rendered from the same markdown blockquote text).
+    notice = ingestion_notice(doc.grounding).replace("> ", "").replace(">", "")
+    parts.append(f'<aside class="feed-notice">{_md_inline(notice)}</aside>')
+
+    parts.append(f"<h1>{e(doc.title)}</h1>")
+    meta_bits = []
+    if doc.author:
+        meta_bits.append(e(doc.author))
+    if doc.created:
+        meta_bits.append(e(doc.created))
+    meta_bits.append(f"grounding: {e(doc.grounding)}")
+    parts.append(f'<p class="feed-meta">{" · ".join(meta_bits)}</p>')
+    # Machine META mirror, hidden from view but in the source.
+    parts.append("<!-- FEED:META -->")
+    parts.append(f"<!-- title: {doc.title} -->")
+    if doc.author:
+        parts.append(f"<!-- author: {doc.author} -->")
+    parts.append(f"<!-- grounding: {doc.grounding} -->")
+    parts.append("<!-- /FEED:META -->")
+
+    if doc.summary:
+        parts.append(f'<p class="feed-tldr"><strong>TL;DR.</strong> {e(doc.summary)}</p>')
+
+    if doc.claims:
+        parts.append("<h2>Claims &amp; Decisions</h2>")
+        for c in doc.claims:
+            ev = ",".join(c.evidence)
+            attrs = f' id="{c.id}"'
+            if ev:
+                attrs += f' evidence="{ev}"'
+            parts.append(f"<!-- FEED:CLAIM{attrs} -->")
+            cites = " ".join(f'<span class="cite">[{e(x)}]</span>' for x in c.evidence)
+            parts.append(f'<div class="claim"><p>{e(c.text)} {cites}</p>')
+            if c.decision:
+                parts.append(f'<p class="decision"><strong>Decision:</strong> {e(c.decision)}</p>')
+            parts.append("</div>")
+            parts.append("<!-- /FEED:CLAIM -->")
+
+    if doc.findings:
+        parts.append("<h2>Findings</h2>")
+        for para in doc.findings:
+            parts.append(f"<p>{_md_inline(e(para))}</p>")
+
+    if doc.evidence:
+        parts.append("<h2>Evidence</h2>")
+        for ev in doc.evidence:
+            parts.append(
+                f'<!-- FEED:EVIDENCE id="{ev.id}" type="{ev.type}" confidence="{ev.confidence}" -->'
+            )
+            parts.append('<table class="evidence">')
+            parts.append(
+                f'<caption><span class="eid">[{e(ev.id)}]</span> '
+                f'<span class="etype">{e(ev.type)} · {e(ev.confidence)} confidence</span></caption>'
+            )
+            for k, v in ev.fields.items():
+                parts.append(f"<tr><th>{e(k)}</th><td>{e(v)}</td></tr>")
+            if ev.note:
+                parts.append(f'<tr><th>note</th><td>{e(ev.note)}</td></tr>')
+            parts.append("</table>")
+            parts.append("<!-- /FEED:EVIDENCE -->")
+
+    parts.append("<!-- FEED:END -->")
+    parts.append("</main></body></html>")
+    return "\n".join(parts)
+
+
+def _md_inline(text: str) -> str:
+    """Tiny inline markdown: **bold** and `code`. Enough for the notice."""
+    import re
+
+    text = re.sub(r"\*\*([^*]+)\*\*", r"<strong>\1</strong>", text)
+    text = re.sub(r"`([^`]+)`", r"<code>\1</code>", text)
+    return text.replace("\n", "<br>")
+
+
+_STYLE = """<style>
+:root { --ink:#1c1b18; --muted:#6b6357; --line:#e4ddd0; --accent:#b1542f; --bg:#f7f4ee; }
+body { background:var(--bg); color:var(--ink); font:16px/1.6 Georgia, 'Times New Roman', serif;
+       margin:0; padding:2.5rem 1rem; }
+main { max-width:46rem; margin:0 auto; }
+h1 { font-size:2rem; margin:.2em 0 0; }
+h2 { font-size:1.25rem; margin:2rem 0 .6rem; border-bottom:1px solid var(--line); padding-bottom:.3rem; }
+.feed-meta { color:var(--muted); font-style:italic; margin:.2rem 0 1.4rem; }
+.feed-notice { background:#fff; border:1px solid var(--line); border-left:4px solid var(--accent);
+       padding:.9rem 1.1rem; font-size:.86rem; color:var(--muted); border-radius:4px; margin-bottom:1.6rem; }
+.feed-tldr { background:#fff; border:1px solid var(--line); padding:.8rem 1rem; border-radius:4px; }
+.claim { border-left:3px solid var(--accent); padding:.1rem 0 .1rem 1rem; margin:.8rem 0; }
+.decision { color:var(--accent); margin:.2rem 0 0; }
+.cite, .eid { font-family:ui-monospace, Menlo, monospace; font-size:.82em; color:var(--accent); }
+table.evidence { width:100%; border-collapse:collapse; background:#fff; margin:.8rem 0;
+       border:1px solid var(--line); font-size:.92rem; }
+table.evidence caption { text-align:left; padding:.5rem .7rem; background:#faf7f1; border-bottom:1px solid var(--line); }
+.etype { color:var(--muted); font-style:italic; font-family:Georgia,serif; margin-left:.5rem; }
+table.evidence th { text-align:left; width:34%; vertical-align:top; color:var(--muted); font-weight:normal;
+       padding:.35rem .7rem; border-top:1px solid var(--line); font-family:ui-monospace,Menlo,monospace; font-size:.85rem; }
+table.evidence td { padding:.35rem .7rem; border-top:1px solid var(--line); }
+</style>"""

feed/tagger.py

@@ -0,0 +1,58 @@
+"""Optional convenience: auto-tag a plain document into FEED by calling Claude.
+
+THIS IS NOT THE PRIMARY PATH. FEED is AI-to-AI — normally the AI already in your
+loop emits FEED natively using `feed.authoring.AUTHORING_PROMPT` +
+`FEED_JSON_SCHEMA`, and you render it with `feed.authoring.build()` (no API key).
+
+This module exists only for the case where you have a plain document and *no* AI
+already in the loop, and want a one-shot CLI. It needs the `anthropic` package and
+an ANTHROPIC_API_KEY (`pip install feed-protocol[tagger]`). Defaults to Opus 4.8.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .authoring import AUTHORING_PROMPT, FEED_JSON_SCHEMA, build
+from .document import FeedDocument
+
+DEFAULT_MODEL = "claude-opus-4-8"
+
+
+def auto_tag(
+    text: str,
+    title: str | None = None,
+    author: str | None = None,
+    grounding: str = "strict",
+    created: str | None = None,
+    model: str = DEFAULT_MODEL,
+) -> FeedDocument:
+    """Read a plain document and return a FeedDocument, using Claude to extract the
+    structure. Raises if `anthropic` is missing or no API key is configured.
+
+    Note this reuses the exact same portable prompt and schema any other AI would
+    use — the API call is just one way to drive it."""
+    try:
+        import anthropic
+    except ImportError as exc:  # pragma: no cover - environment dependent
+        raise RuntimeError(
+            "The auto-tagger needs the anthropic package. Install with: "
+            "pip install feed-protocol[tagger]. (Or skip it: have the AI already "
+            "in your pipeline emit FEED JSON using feed.authoring, then feed.build.)"
+        ) from exc
+
+    client = anthropic.Anthropic()
+    instruction = "Convert the following document into FEED structure."
+    if title:
+        instruction += f' Use the title "{title}".'
+
+    response = client.messages.create(
+        model=model,
+        max_tokens=16000,
+        system=AUTHORING_PROMPT,
+        output_config={"format": {"type": "json_schema", "schema": FEED_JSON_SCHEMA}},
+        messages=[{"role": "user", "content": f"{instruction}\n\n---\n\n{text}"}],
+    )
+    raw = next(b.text for b in response.content if b.type == "text")
+    data = json.loads(raw)
+    return build(data, title=title, author=author, grounding=grounding, created=created)

feed/validate.py

@@ -0,0 +1,99 @@
+"""Structural validation for FEED documents.
+
+Errors block compliance; warnings flag quality/robustness issues. The intent is
+that a CI step can run `feed validate` and fail the build on errors.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .constants import (
+    CONFIDENCE_LEVELS,
+    EVIDENCE_ID_RE,
+    EVIDENCE_TYPES,
+    GROUNDING_MODES,
+    CLAIM_ID_RE,
+)
+from .document import FeedDocument
+
+
+@dataclass
+class ValidationReport:
+    errors: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        lines = []
+        for e in self.errors:
+            lines.append(f"  ERROR   {e}")
+        for w in self.warnings:
+            lines.append(f"  WARN    {w}")
+        if not lines:
+            lines.append("  OK — valid FEED document")
+        return "\n".join(lines)
+
+
+def validate(doc: FeedDocument) -> ValidationReport:
+    r = ValidationReport()
+
+    if doc.grounding not in GROUNDING_MODES:
+        r.errors.append(f"grounding {doc.grounding!r} is not one of {GROUNDING_MODES}")
+
+    if not doc.title or not doc.title.strip():
+        r.errors.append("document has no title")
+
+    # Evidence checks.
+    seen: set[str] = set()
+    for ev in doc.evidence:
+        if not EVIDENCE_ID_RE.match(ev.id):
+            r.errors.append(f"evidence id {ev.id!r} is malformed (expected E001)")
+        if ev.id in seen:
+            r.errors.append(f"duplicate evidence id {ev.id!r}")
+        seen.add(ev.id)
+        if not ev.fields:
+            r.errors.append(f"evidence {ev.id!r} has no key/value fields")
+        if ev.type not in EVIDENCE_TYPES:
+            r.warnings.append(f"evidence {ev.id!r} has unusual type {ev.type!r}")
+        if ev.confidence not in CONFIDENCE_LEVELS:
+            r.warnings.append(
+                f"evidence {ev.id!r} has unusual confidence {ev.confidence!r}"
+            )
+
+    # Claim checks.
+    claim_ids: set[str] = set()
+    for c in doc.claims:
+        if not CLAIM_ID_RE.match(c.id):
+            r.errors.append(f"claim id {c.id!r} is malformed (expected C1)")
+        if c.id in claim_ids:
+            r.errors.append(f"duplicate claim id {c.id!r}")
+        claim_ids.add(c.id)
+        for e in c.evidence:
+            if e not in seen:
+                r.errors.append(f"claim {c.id!r} cites missing evidence {e!r}")
+        if doc.grounding == "strict" and not c.evidence:
+            r.warnings.append(
+                f"claim {c.id!r} has no evidence, but grounding is strict"
+            )
+
+    # Whole-document sanity.
+    if not doc.evidence:
+        r.warnings.append("document has no evidence blocks — nothing to ground answers in")
+    if not doc.claims and not doc.findings:
+        r.warnings.append("document has no claims or findings — nothing for a reader to act on")
+
+    # Cheap density check: flag evidence written as prose rather than key/value.
+    for ev in doc.evidence:
+        for k, v in ev.fields.items():
+            if len(v) > 240:
+                r.warnings.append(
+                    f"evidence {ev.id!r} field {k!r} is very long — "
+                    "prefer compact key/value facts over prose"
+                )
+                break
+
+    return r

feed/verify.py

@@ -0,0 +1,116 @@
+"""Verify that an AI's answer is actually grounded in a FEED document.
+
+This is FEED's defensible edge over plain "AI-friendly" formats: because every
+evidence block has a stable plain-text ID and answers must cite by ID, you can
+mechanically check an answer:
+
+  - every [E###] it cites exists in the document         (no invented citations)
+  - in strict mode, the answer cites at least one block   (it didn't free-wheel)
+  - optionally, cited figures actually appear in the answer (loose corroboration)
+
+It is deliberately simple and dependency-free — a 20-line idea with teeth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .constants import CITATION_RE
+from .document import FeedDocument
+
+
+@dataclass
+class VerificationReport:
+    cited: list[str] = field(default_factory=list)        # all IDs cited, in order
+    valid: list[str] = field(default_factory=list)        # cited and exist
+    invalid: list[str] = field(default_factory=list)      # cited but do not exist
+    uncited_evidence: list[str] = field(default_factory=list)  # exist but never cited
+    corroborated: list[str] = field(default_factory=list)      # cited & a value appears in answer
+    grounding: str = "strict"
+    passed: bool = False
+    reasons: list[str] = field(default_factory=list)
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        status = "PASS" if self.passed else "FAIL"
+        lines = [f"  grounding: {self.grounding}    result: {status}"]
+        lines.append(f"  cited: {', '.join(self.cited) or '(none)'}")
+        if self.invalid:
+            lines.append(f"  INVALID citations (no such evidence): {', '.join(self.invalid)}")
+        if self.corroborated:
+            lines.append(f"  corroborated (a value appears in the answer): {', '.join(self.corroborated)}")
+        if self.uncited_evidence:
+            lines.append(f"  unused evidence: {', '.join(self.uncited_evidence)}")
+        for reason in self.reasons:
+            lines.append(f"  - {reason}")
+        return "\n".join(lines)
+
+
+def verify(answer: str, doc: FeedDocument) -> VerificationReport:
+    evidence_by_id = {ev.id: ev for ev in doc.evidence}
+
+    cited: list[str] = []
+    for match in CITATION_RE.finditer(answer):
+        for part in match.group(1).split(","):
+            cited.append(part.strip())
+
+    # Preserve order, dedupe for set operations.
+    seen: list[str] = []
+    for c in cited:
+        if c not in seen:
+            seen.append(c)
+
+    valid = [c for c in seen if c in evidence_by_id]
+    invalid = [c for c in seen if c not in evidence_by_id]
+    uncited = [eid for eid in evidence_by_id if eid not in seen]
+
+    lower_answer = answer.lower()
+    corroborated: list[str] = []
+    for cid in valid:
+        ev = evidence_by_id[cid]
+        for value in ev.fields.values():
+            token = _significant_token(value)
+            if token and token.lower() in lower_answer:
+                corroborated.append(cid)
+                break
+
+    report = VerificationReport(
+        cited=cited,
+        valid=valid,
+        invalid=invalid,
+        uncited_evidence=uncited,
+        corroborated=corroborated,
+        grounding=doc.grounding,
+    )
+
+    # Decide pass/fail.
+    passed = True
+    if invalid:
+        passed = False
+        report.reasons.append(
+            f"answer cites {len(invalid)} evidence ID(s) that do not exist in the document"
+        )
+    if doc.grounding == "strict" and not cited:
+        passed = False
+        report.reasons.append(
+            "grounding is strict but the answer contains no [E###] citations"
+        )
+    if doc.grounding == "open" and not cited:
+        report.reasons.append("no citations found (allowed in open mode)")
+    report.passed = passed
+    if passed and not report.reasons:
+        report.reasons.append("all citations resolve to real evidence")
+    return report
+
+
+def _significant_token(value: str) -> str | None:
+    """Pull a distinctive token (e.g. a number) from an evidence value to look
+    for in the answer. Returns None if nothing distinctive enough."""
+    import re
+
+    m = re.search(r"\d[\d,.]*", value)
+    if m and len(m.group(0)) >= 2:
+        return m.group(0)
+    # else fall back to the longest word if it is reasonably specific
+    words = [w for w in re.findall(r"[A-Za-z0-9_\-]{4,}", value)]
+    words.sort(key=len, reverse=True)
+    return words[0] if words else None