backdraft 0.2.0__py3-none-any.whl

backdraft/bind/cli.py

@@ -0,0 +1,133 @@
+"""`backdraft bind` — the CLI surface and the exit-code contract.
+
+```
+backdraft bind <doc.md> [--session S] [--check m1,m2] [--mode frontwalk|backfill]
+```
+
+Exit codes, per SPEC:
+
+* **0** — clean: every citation resolved and nothing was left unmatched.
+* **1** — usage or environment error: no registry, no such document, an unknown
+  `--mode` or `--check` name.
+* **2** — bind completed and something did not resolve. This is the code hooks
+  gate on, so it is about *resolution* only: a `fail` verdict never produces it,
+  because verification is evidence, not a gate.
+
+NOTE: the spec fixes exit 2 as "completed with non-resolved citations". A
+backfill claim bind could not anchor is the same failure without a citation to
+hang it on, so it exits 2 as well — a backfill run that leaves claims
+unattributed is not a clean run.
+
+Registry discovery and session resolution come from `backdraft.cli_context`
+(SPEC Addendum B), imported at module level like every other sub-app's. The
+registry is opened from the *document's* directory rather than the process's
+cwd: `backdraft bind ../notes/memo.md` should find the registry the document
+lives under.
+
+Mounting (Addendum B): `app` is a `typer.Typer()` holding one command named
+`bind` and no callback, and the top level adopts its commands rather than
+nesting the app:
+
+    app.registered_commands.extend(bind_cli.app.registered_commands)
+
+so the command lands as `backdraft bind`, with no group name in between.
+`tests/test_bind_cli.py` pins that.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ..cli_context import (
+    EXIT_UNRESOLVED,
+    EXIT_USAGE,
+    UsageError,
+    guard,
+    open_registry,
+    resolve_session,
+)
+from ..kernel.artifact import bound_path, sidecar_path
+from .binder import bind as run_bind, record_target
+
+__all__ = ["app", "bind", "EXIT_USAGE", "EXIT_UNRESOLVED"]
+
+app = typer.Typer(help="Bind an authored document against the registry.")
+
+
+@app.command("bind")
+def bind(
+    doc: Annotated[Path, typer.Argument(help="The authored markdown document.")],
+    session: Annotated[
+        str | None,
+        typer.Option("--session", help="Session whose ledger `not_shown` is judged against."),
+    ] = None,
+    check: Annotated[
+        str | None,
+        typer.Option(
+            "--check", help="Verification methods to run, comma-separated. Default: none."
+        ),
+    ] = None,
+    mode: Annotated[str, typer.Option("--mode", help="frontwalk | backfill")] = "frontwalk",
+    lean: Annotated[
+        bool,
+        typer.Option("--lean", help="Skip page images in the artifact's evidence."),
+    ] = False,
+    bound: Annotated[
+        bool,
+        typer.Option("--bound", help="Also write the rewritten-markdown projection."),
+    ] = False,
+) -> None:
+    """Resolve every citation, run enabled checks, rewrite, report."""
+    with guard():
+        if mode not in ("frontwalk", "backfill"):
+            raise UsageError(f"unknown mode {mode!r}; expected frontwalk or backfill")
+        if not doc.is_file():
+            raise UsageError(f"no such document: {doc}")
+        checks = [name.strip() for name in (check or "").split(",") if name.strip()]
+        registry = open_registry(doc.resolve().parent)
+        session_id = resolve_session(session, registry)
+        try:
+            report = run_bind(
+                doc, registry, mode=mode, session_id=session_id, checks=checks,
+                lean=lean, bound=bound,
+            )
+        except ValueError as error:  # unknown --check name
+            raise UsageError(str(error)) from error
+        finally:
+            _close(registry)
+    _print_report(report, doc, bound=bound, record=record_target(doc, registry))
+    unmatched = [claim for claim in report.claims if claim.unmatched]
+    if report.unresolved or unmatched:
+        raise typer.Exit(EXIT_UNRESOLVED)
+
+
+def _print_report(report, doc: Path, *, bound: bool = False, record: Path | None = None) -> None:  # noqa: ANN001 - BindReport, kernel-typed
+    """The human-readable report: counts, then every line item."""
+    summary = report.summary
+    typer.echo(
+        f"bound {summary['claims']} claim(s), {summary['citations']} citation(s) "
+        f"[{report.mode}]"
+    )
+    for status, count in sorted(summary["by_status"].items()):
+        typer.echo(f"  {status}: {count}")
+    for method, statuses in sorted(summary["by_method"].items()):
+        detail = ", ".join(f"{key} {value}" for key, value in sorted(statuses.items()))
+        typer.echo(f"  {method}: {detail}")
+    for citation in report.unresolved:
+        reason = f" — {citation.error}" if citation.error else ""
+        typer.echo(f"  ! {citation.status}: {citation.token}{reason}")
+    for claim in report.claims:
+        if claim.unmatched:
+            typer.echo(f"  ! unmatched: {claim.text.strip()[:80]}")
+    if bound:
+        typer.echo(f"wrote {bound_path(doc)}")
+    typer.echo(f"wrote {record or sidecar_path(doc)}")
+
+
+def _close(registry) -> None:  # noqa: ANN001
+    close = getattr(registry, "close", None)
+    if callable(close):
+        close()

backdraft/bind/evidence.py

@@ -0,0 +1,232 @@
+"""Evidence assembly: the context a citation's receipt sits in.
+
+Bind is the one step that holds both the resolved claims and the registry, so
+it is where the artifact's evidence is gathered: the cited pages as images (when
+the registry has snapshots), each cited page's extracted text, a small cell
+window around every cited cell, and the full values of every cited sheet for
+the artifact's sheet view. Bounded by what is cited — never the corpus.
+
+The result is a plain JSON-shaped dict, carried on `BindReport.evidence` and
+described by `LEGEND["evidence"]`. Everything here is optional context: a
+sidecar without evidence is still a complete record, so assembly degrades
+rather than fails — a registry that cannot answer (a test fake, a missing
+snapshot) simply contributes nothing.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+from typing import Any, Iterable
+
+from ..kernel.model import Claim
+
+__all__ = ["assemble", "WINDOW_ROWS", "WINDOW_COLS"]
+
+WINDOW_ROWS = 6
+"""Rows kept above and below a cited cell in its window."""
+
+WINDOW_COLS = 4
+"""Columns kept left and right of a cited cell in its window."""
+
+_CELL_RE = re.compile(r"^(?P<sheet>[^!]+)!(?P<col>[A-Z]{1,3})(?P<row>\d+)$")
+_PAGE_RE = re.compile(r"^p(?P<page>\d+)(?:\.c\d+)?$")
+
+
+def col_num(letters: str) -> int:
+    """A1 column letters -> 1-based number."""
+    n = 0
+    for ch in letters:
+        n = n * 26 + (ord(ch) - 64)
+    return n
+
+
+def col_letters(n: int) -> str:
+    """1-based column number -> A1 letters."""
+    out = ""
+    while n:
+        n, r = divmod(n - 1, 26)
+        out = chr(65 + r) + out
+    return out
+
+
+def assemble(registry, claims: Iterable[Claim], *, lean: bool = False) -> dict[str, Any] | None:  # noqa: ANN001
+    """Evidence for every cited anchor, or None when there is nothing to give.
+
+    `lean` skips page images (the only heavy part); text windows and sheet
+    values are always cheap enough to include.
+    """
+    if not callable(getattr(registry, "document", None)) or not callable(
+        getattr(registry, "page", None)
+    ):
+        return None
+
+    cited_pages: dict[str, set[int]] = {}
+    cited_cells: list[tuple[str, str, str, int]] = []  # slug, sheet, col, row
+    sheet_pages: list[tuple[str, int]] = []
+    slugs: list[str] = []
+
+    documents: dict[str, Any] = {}
+
+    def doc_for(slug: str):  # noqa: ANN202
+        if slug not in documents:
+            documents[slug] = registry.document(slug)
+        return documents[slug]
+
+    for claim in claims:
+        for citation in claim.citations:
+            anchor = citation.anchor
+            if anchor is None:
+                continue
+            document = doc_for(anchor.slug)
+            if document is None:
+                continue
+            if anchor.slug not in slugs:
+                slugs.append(anchor.slug)
+            locator = str(anchor.locator)
+            if m := _CELL_RE.match(locator):
+                cited_cells.append((anchor.slug, m["sheet"], m["col"], int(m["row"])))
+            elif m := _PAGE_RE.match(locator):
+                number = int(m["page"])
+                if document.media_type == "xlsx":
+                    sheet_pages.append((anchor.slug, number))
+                else:
+                    cited_pages.setdefault(anchor.slug, set()).add(number)
+
+    if not slugs:
+        return None
+
+    evidence: dict[str, Any] = {
+        "documents": {
+            slug: {
+                "filename": documents[slug].filename,
+                "media_type": documents[slug].media_type,
+            }
+            for slug in slugs
+        },
+        "pages": {},
+        "pagetexts": {},
+        "windows": {},
+        "sheets": {},
+    }
+
+    # ---- cited PDF pages: text always, image when stored and not lean ------
+    can_image = callable(getattr(registry, "page_image", None))
+    for slug, numbers in cited_pages.items():
+        for number in sorted(numbers):
+            page = registry.page(slug, number)
+            if page is not None:
+                evidence["pagetexts"][f"{slug}:p{number}"] = page.text
+            if lean or not can_image:
+                continue
+            image = registry.page_image(slug, number)
+            if image is not None:
+                evidence["pages"][f"{slug}:p{number}"] = {
+                    "format": image.format,
+                    "width": image.width,
+                    "height": image.height,
+                    "data": base64.b64encode(image.data).decode("ascii"),
+                }
+
+    # ---- sheets: windows around cited cells, full values per cited sheet ---
+    def sheet_page(slug: str, sheet: str):  # noqa: ANN202
+        for page in registry.pages(slug):
+            if page.kind == "sheet" and page.name == sheet:
+                return page
+        return None
+
+    def cells_map(page) -> dict[tuple[int, int], str]:  # noqa: ANN001
+        cells: dict[tuple[int, int], str] = {}
+        for cell in page.cells:
+            if m := re.match(r"^([A-Z]{1,3})(\d+)$", cell.ref):
+                cells[(int(m.group(2)), col_num(m.group(1)))] = cell.value
+        return cells
+
+    def window(cells: dict[tuple[int, int], str], sheet: str,
+               col: str | None, row: int | None) -> dict[str, Any]:
+        if not cells:
+            return {}
+        if col is None:  # whole-sheet citation: top-left populated block
+            r0 = min(r for r, _ in cells)
+            c0 = min(c for _, c in cells)
+            rows_range = range(r0, r0 + 2 * WINDOW_ROWS + 1)
+            cols_range = range(c0, c0 + 2 * WINDOW_COLS + 1)
+            cited = None
+        else:
+            r, c = row, col_num(col)
+            rows_range = range(max(1, r - WINDOW_ROWS), r + WINDOW_ROWS + 1)
+            cols_range = range(max(1, c - WINDOW_COLS), c + WINDOW_COLS + 1)
+            cited = f"{col}{row}"
+        live_rows = [r for r in rows_range if any((r, c) in cells for c in cols_range)]
+        live_cols = [c for c in cols_range if any((r, c) in cells for r in rows_range)]
+        if not live_rows or not live_cols:
+            return {}
+        rows_out = [
+            {
+                "n": r,
+                "cells": {
+                    col_letters(c): cells.get((r, c), "")
+                    for c in range(min(live_cols), max(live_cols) + 1)
+                },
+            }
+            for r in range(min(live_rows), max(live_rows) + 1)
+        ]
+        return {
+            "sheet": sheet,
+            "cited": cited,
+            "cols": [col_letters(c) for c in range(min(live_cols), max(live_cols) + 1)],
+            "rows": rows_out,
+        }
+
+    cited_sheets: dict[tuple[str, str], Any] = {}
+
+    def note_sheet(slug: str, sheet: str):  # noqa: ANN202
+        key = (slug, sheet)
+        if key not in cited_sheets:
+            cited_sheets[key] = sheet_page(slug, sheet)
+        return cited_sheets[key]
+
+    for slug, sheet, col, row in cited_cells:
+        key = f"{slug}:{sheet}!{col}{row}"
+        if key in evidence["windows"]:
+            continue
+        page = note_sheet(slug, sheet)
+        if page is None:
+            continue
+        made = window(cells_map(page), sheet, col, row)
+        if made:
+            evidence["windows"][key] = made
+
+    for slug, number in sheet_pages:
+        page = registry.page(slug, number)
+        if page is None or page.kind != "sheet" or not page.name:
+            continue
+        note_sheet(slug, page.name)
+        key = f"{slug}:p{number}"
+        if key not in evidence["windows"]:
+            made = window(cells_map(page), page.name, None, None)
+            if made:
+                evidence["windows"][key] = made
+
+    for (slug, sheet), page in cited_sheets.items():
+        if page is None:
+            continue
+        cells = cells_map(page)
+        if not cells:
+            continue
+        maxr = max(r for r, _ in cells)
+        maxc = max(c for _, c in cells)
+        evidence["sheets"][f"{slug}:{sheet}"] = {
+            "name": sheet,
+            "nrows": maxr,
+            "ncols": maxc,
+            "rows": [
+                [cells.get((r, c), "") for c in range(1, maxc + 1)]
+                for r in range(1, maxr + 1)
+            ],
+        }
+
+    if not any((evidence["pages"], evidence["pagetexts"],
+                evidence["windows"], evidence["sheets"])):
+        return None
+    return evidence

backdraft/bind/verify/__init__.py

@@ -0,0 +1,30 @@
+"""Verification methods: independent switches, recorded as evidence, never gates.
+
+Importing this package registers every method in `VERIFIERS`; `selected(names)`
+turns `--check value-trace,overlap` into the list bind runs. All switches are
+off by default — a bind with no `--check` writes no verdict rows at all, and the
+report's shape is unchanged either way.
+"""
+
+from __future__ import annotations
+
+from .base import VERIFIERS, Verifier, register, selected
+from .entail import Entail, entail
+from .overlap import Overlap, overlap
+from .recompute import Recompute, recompute
+from .value_trace import ValueTrace, value_trace
+
+__all__ = [
+    "VERIFIERS",
+    "Verifier",
+    "register",
+    "selected",
+    "ValueTrace",
+    "value_trace",
+    "Overlap",
+    "overlap",
+    "Recompute",
+    "recompute",
+    "Entail",
+    "entail",
+]

backdraft/bind/verify/base.py

@@ -0,0 +1,70 @@
+"""The Verifier protocol and the registry of verification methods.
+
+A verifier answers one question about one (claim, citation) pair and records a
+`Verdict`. Verdicts are evidence, never gates: bind's exit code keys off
+citation *resolution*, never off a verdict. All methods are off by default;
+`--check value-trace,overlap` opts in.
+
+`applies` is the method's own claim-class filter — value-trace applies only to
+claims carrying a value, `recompute` applies to nothing until `bd:calc` lands.
+An enabled verifier that does not apply writes no verdict row, so a report never
+implies a method looked at a claim it never read.
+
+Optional capability, not part of the protocol: a verifier may define
+``prepare(pairs)`` taking the full list of ``(claim, citation, anchor)`` triples
+bind is about to verify. Bind calls it once, before any `verify`, when it is
+present — this is how `entail` batches its judge calls. Verifiers without it are
+unaffected.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Protocol, runtime_checkable
+
+from ...kernel.model import Anchor, Citation, Claim, Verdict
+
+__all__ = ["Verifier", "VERIFIERS", "register", "selected"]
+
+
+@runtime_checkable
+class Verifier(Protocol):
+    """One verification method."""
+
+    method: str
+    """`value-trace` | `overlap` | `recompute` | `entail`."""
+
+    def applies(self, claim: Claim, citation: Citation) -> bool:
+        """True when this method has something to say about this pair."""
+        ...
+
+    def verify(self, claim: Claim, citation: Citation, anchor: Anchor) -> Verdict:
+        """The method's finding, as a `Verdict` carrying `self.method`."""
+        ...
+
+
+VERIFIERS: dict[str, Verifier] = {}
+"""Every registered method, by name. Registration happens on import."""
+
+
+def register(verifier: Verifier) -> Verifier:
+    """Register `verifier` under its `method` name and return it."""
+    VERIFIERS[verifier.method] = verifier
+    return verifier
+
+
+def selected(names: Sequence[str]) -> list[Verifier]:
+    """The verifiers named by `--check`, in the order given.
+
+    Raises `ValueError` for an unknown method name — a usage error, which the
+    CLI reports as exit 1 rather than running a bind with a silent typo.
+    """
+    chosen: list[Verifier] = []
+    for name in names:
+        if name not in VERIFIERS:
+            known = ", ".join(sorted(VERIFIERS))
+            raise ValueError(f"unknown verification method {name!r}; known methods: {known}")
+        verifier = VERIFIERS[name]
+        if verifier not in chosen:
+            chosen.append(verifier)
+    return chosen

backdraft/bind/verify/entail.py

@@ -0,0 +1,156 @@
+"""entail: does the snippet support the claim? A model judge, behind `[entail]`.
+
+The qualitative claim class — the one no deterministic check reaches. The
+question asked is deliberately tiny and closed: given a claim and the verbatim
+snippet it cites, answer `yes`, `partial`, or `no`. Nothing is asked about
+truth in the world; only about whether *this* snippet supports *this* claim.
+
+The module imports without the extra installed: `anthropic` is import-guarded, so
+`--check entail` is always a valid request. There is no pre-check — without the
+extra, or without `BACKDRAFT_ENTAIL_API_KEY`, every pair verifies as `skip` carrying the
+reason, and the bind still completes. That is the "failures are data" reading:
+a report saying the judge could not run is more use than a refusal to bind, and
+`skip` never touches the exit code, which keys off resolution alone.
+
+Batching lives in `prepare`, an optional capability bind calls once with every
+(claim, citation, anchor) triple before any `verify` — see `base.py`. One
+request carries `BATCH_SIZE` numbered pairs and comes back as numbered lines,
+which is what makes a judge affordable over a long document. A pair whose
+answer does not come back — API error, short reply, unparseable line — verifies
+as `skip` with the reason, never as `fail`: a verifier that cannot reach a
+finding has not found anything.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from ...credentials import setting
+from ...kernel.hashing import normalize
+from ...kernel.model import Anchor, Citation, Claim, Verdict, VerdictStatus
+from .base import register
+
+try:  # pragma: no cover - exercised only by the extra's presence
+    import anthropic
+except ImportError:  # pragma: no cover - the guarded path
+    anthropic = None  # type: ignore[assignment]
+
+__all__ = ["Entail", "entail", "MODEL", "BATCH_SIZE"]
+
+MODEL = "claude-opus-5"
+"""Judge model. Override with `BACKDRAFT_ENTAIL_MODEL`."""
+
+BATCH_SIZE = 20
+"""Pairs per request."""
+
+MAX_SNIPPET = 2000
+"""Snippet characters sent per pair. Longer receipts are truncated, marked."""
+
+_SYSTEM = (
+    "You judge whether a source snippet supports a claim. "
+    "For each numbered pair, answer with exactly one word: "
+    "yes (the snippet states or directly implies the claim), "
+    "partial (it supports part of the claim, or supports it with qualification), "
+    "no (it does not support the claim). "
+    "Reply with one line per pair, formatted '<number>: <answer>', and nothing else."
+)
+
+_ANSWER = re.compile(r"^\s*(?P<number>\d+)\s*[:.)]\s*(?P<answer>yes|partial|no)\b", re.IGNORECASE)
+
+_STATUS = {
+    "yes": VerdictStatus.PASS,
+    "partial": VerdictStatus.PARTIAL,
+    "no": VerdictStatus.FAIL,
+}
+
+
+class Entail:
+    """Model judge over (claim, snippet) pairs. Batched, cached per run."""
+
+    method = "entail"
+
+    def __init__(self) -> None:
+        self._answers: dict[tuple[str, str], tuple[VerdictStatus, str]] = {}
+
+    def applies(self, claim: Claim, citation: Citation) -> bool:
+        """True for any claim with text — every claim is a qualitative claim."""
+        return bool(claim.text.strip())
+
+    def prepare(self, pairs: Sequence[tuple[Claim, Citation, Anchor]]) -> None:
+        """Judge every pair up front, in batches. Optional capability."""
+        questions: list[tuple[str, str]] = []
+        for claim, _citation, anchor in pairs:
+            key = self._key(claim, anchor)
+            if key not in self._answers and key not in questions:
+                questions.append(key)
+        for start in range(0, len(questions), BATCH_SIZE):
+            self._ask(questions[start : start + BATCH_SIZE])
+
+    def verify(self, claim: Claim, citation: Citation, anchor: Anchor) -> Verdict:
+        """The judge's answer, or `skip` with the reason it has none."""
+        key = self._key(claim, anchor)
+        if key not in self._answers:
+            self._ask([key])
+        status, detail = self._answers.get(
+            key, (VerdictStatus.SKIP, "no answer returned for this pair")
+        )
+        return Verdict(method=self.method, status=status, detail=detail)
+
+    def _key(self, claim: Claim, anchor: Anchor) -> tuple[str, str]:
+        snippet = normalize(anchor.receipt.snippet)
+        if len(snippet) > MAX_SNIPPET:
+            snippet = snippet[:MAX_SNIPPET] + " […truncated]"
+        return (normalize(claim.text), snippet)
+
+    def _ask(self, batch: Sequence[tuple[str, str]]) -> None:
+        """One request for one batch; record an answer for every pair in it."""
+        if not batch:
+            return
+        if anthropic is None:
+            self._record_all(batch, "the [entail] extra is not installed")
+            return
+        api_key = setting("BACKDRAFT_ENTAIL_API_KEY")
+        if not api_key:
+            self._record_all(
+                batch,
+                "BACKDRAFT_ENTAIL_API_KEY is not set (env or .backdraft/env); "
+                "ambient ANTHROPIC_API_KEY is deliberately not read",
+            )
+            return
+        prompt = "\n\n".join(
+            f"{index}.\nCLAIM: {claim}\nSNIPPET: {snippet}"
+            for index, (claim, snippet) in enumerate(batch, start=1)
+        )
+        try:
+            response = anthropic.Anthropic(api_key=api_key).messages.create(
+                model=setting("BACKDRAFT_ENTAIL_MODEL") or MODEL,
+                max_tokens=4096,
+                system=_SYSTEM,
+                output_config={"effort": "low"},
+                messages=[{"role": "user", "content": prompt}],
+            )
+        except Exception as error:  # noqa: BLE001 - any failure is a `skip`, never a `fail`
+            self._record_all(batch, f"judge call failed: {error}")
+            return
+        text = "\n".join(block.text for block in response.content if block.type == "text")
+        answers: dict[int, str] = {}
+        for line in text.splitlines():
+            if match := _ANSWER.match(line):
+                answers[int(match["number"])] = match["answer"].lower()
+        for index, key in enumerate(batch, start=1):
+            answer = answers.get(index)
+            if answer is None:
+                self._answers[key] = (
+                    VerdictStatus.SKIP,
+                    "judge returned no answer for this pair",
+                )
+            else:
+                self._answers[key] = (_STATUS[answer], f"judge: {answer}")
+
+    def _record_all(self, batch: Sequence[tuple[str, str]], reason: str) -> None:
+        for key in batch:
+            self._answers[key] = (VerdictStatus.SKIP, reason)
+
+
+entail = register(Entail())