pytest-grounding 0.0.1__py3-none-any.whl

grounding/__init__.py

@@ -0,0 +1,64 @@
+"""grounding — turn assertions about data into re-runnable, provenance-tracked claims.
+
+A claim is a pytest test. Inside it you ground a statement in sha-pinned evidence:
+
+    from grounding import data, doc, statement, evidence, strength, caveats
+
+    @strength("strong")
+    @caveats("single run; n=3 per dose")
+    def test_knockdown_at_high_dose():
+        df = data("measurements.csv")            # sha-pinned read, recorded as provenance
+        hi = df[df.dose == 300].knockdown.mean()
+        statement(f"Knockdown reached {hi:.0f}% at the 300 nM dose")   # the proposition
+        evidence(knockdown_pct=round(hi, 1))
+        assert hi > 50                           # the grounding/drift check
+
+The pytest plugin (auto-loaded via the ``pytest11`` entry point) wraps each test in a
+capture, records every ``data``/``doc`` read, and emits ``grounding_report.json``. The
+non-binary judgment (``@strength``/``@caveats``/``@kind``/``@reviewed``) is metadata a
+reviewer judges — never a pass/fail input.
+
+Everything here is a pure function of file bytes: no network, no key, no model.
+
+Public API:
+
+    data / load        sha-pinned CSV loader -> DataFrame(.attrs)        [needs the [data] extra]
+    doc -> DocRef      record a document; DocRef.contains() verifies a quote [needs [docs]]
+    statement(text)    the claim's proposition (ideally computed from data)
+    evidence(**kv)     headline numbers for the report
+    uses(claim_id)     compose on a prior claim (transitive provenance + evidence)
+    strength/caveats/kind/reviewed   the judgment markers
+    Capture / current_capture / record / registry / TRACKED_SUFFIXES   the capture core
+    install_guard      install the untracked-read bypass guard (the plugin does this)
+"""
+from __future__ import annotations
+
+from ._capture import (
+    Capture,
+    TRACKED_SUFFIXES,
+    current_capture,
+    record,
+    registry,
+)
+from ._text import match_phrase, sha256
+from .loaders import (
+    DocRef,
+    EmptyExtraction,
+    UnsupportedDocFormat,
+    data,
+    doc,
+    load,
+)
+from .claim import caveats, evidence, kind, reviewed, statement, strength, uses
+from .guard import install_guard
+
+__all__ = [
+    "load", "data", "doc", "DocRef", "UnsupportedDocFormat", "EmptyExtraction",
+    "statement", "evidence", "uses",
+    "strength", "caveats", "kind", "reviewed",
+    "Capture", "current_capture", "record", "registry", "TRACKED_SUFFIXES",
+    "match_phrase", "sha256",
+    "install_guard",
+]
+
+__version__ = "0.0.1"

grounding/_capture.py

@@ -0,0 +1,68 @@
+"""The capture context — the heart of automatic provenance.
+
+While a claim runs, a :class:`Capture` is active in a context variable. Every tracked read
+(``load``/``data``/``doc``, or an untracked read the bypass guard catches) records its
+``{kind, path, sha256}`` into it, and the claim's :func:`grounding.statement` /
+:func:`grounding.evidence` write the proposition + headline numbers. A claim's id + its
+captured inputs + its statement + its evidence form a *computed* record — never
+hand-maintained.
+"""
+from __future__ import annotations
+
+import contextvars
+from dataclasses import dataclass, field
+from typing import Any
+
+# Source-file kinds we consider "tracked": reading one while a capture is active is
+# provenance the claim depends on. The bypass guard watches the same set.
+TRACKED_SUFFIXES = {
+    ".csv", ".tsv", ".xlsx", ".xls", ".pdf", ".docx", ".pptx", ".ppt",
+    ".json", ".yaml", ".yml",
+}
+
+
+@dataclass
+class Capture:
+    """Records every tracked source read + the statement and headline numbers for one
+    claim. The claim's id, captured inputs, statement and evidence are all computed from
+    what actually ran, so they can't drift from reality."""
+
+    claim_id: str | None = None
+    statement: str | None = None                       # the proposition (set by statement())
+    inputs: list[dict] = field(default_factory=list)   # {kind, path, sha256, via}
+    evidence: dict[str, Any] = field(default_factory=dict)
+    bypassed: list[str] = field(default_factory=list)  # untracked reads the guard caught
+    _seen: set = field(default_factory=set)
+
+    def record(self, kind: str, path, sha: str, via: str = "tracked") -> None:
+        key = (kind, str(path))
+        if key in self._seen:
+            return
+        self._seen.add(key)
+        self.inputs.append({"kind": kind, "path": str(path), "sha256": sha, "via": via})
+
+    def merge(self, other: "Capture") -> None:
+        """Pull another capture's inputs in transitively (used by :func:`grounding.uses`)."""
+        for inp in other.inputs:
+            self.record(inp["kind"], inp["path"], inp["sha256"], via="uses")
+
+
+_CURRENT: contextvars.ContextVar[Capture | None] = contextvars.ContextVar(
+    "grounding_capture", default=None)
+
+
+def current_capture() -> Capture | None:
+    return _CURRENT.get()
+
+
+def record(kind: str, path, sha: str, via: str = "tracked") -> None:
+    """Record a (kind, path, sha) into the active capture, if any. Called by the tracked
+    loaders and the bypass guard."""
+    cap = _CURRENT.get()
+    if cap is not None:
+        cap.record(kind, path, sha, via)
+
+
+# A session-wide registry of completed claim records, keyed by node id. Populated by the
+# plugin so :func:`grounding.uses` can pull a prior claim's evidence + inputs.
+registry: dict[str, dict] = {}

grounding/_normalize.py

@@ -0,0 +1,38 @@
+"""The one verbatim-quote text normalizer (pure stdlib).
+
+A single place for the text normalization that quote matching depends on. Keeping it
+in one function means a verbatim quote folds to exactly one canonical form everywhere
+it is compared — so a correct quote is never defeated by a glyph variant, and any future
+identity/caching layer built on top stays consistent with the matcher by construction.
+"""
+from __future__ import annotations
+
+import unicodedata
+
+# Unicode dash/hyphen variants that publishers and PDF extractors use interchangeably
+# with ASCII "-": en/em dashes, the Unicode hyphen, non-breaking hyphen, minus sign, etc.
+# Folding them (plus NFKC, which normalizes ligatures/full-width/compatibility forms) lets
+# a verbatim quote match stored text without the author reproducing the exact glyph — the
+# single most common reason a real, correct quote fails a naive substring check.
+_DASHES = "‐‑‒–—―⁃−﹘﹣－"
+_DASH_MAP = {ord(c): "-" for c in _DASHES}
+
+
+def collapse_ws(s: str) -> str:
+    """Collapse every run of whitespace to a single space (and strip). Quote matching is
+    *verbatim*, but extractors split a sentence across runs/lines/cells (worst in slide
+    decks); normalizing both sides makes a short quote match reliably."""
+    return " ".join(s.split())
+
+
+def fold_match(s: str) -> str:
+    """Normalize text for verbatim-quote matching: NFKC-normalize, fold Unicode dashes to
+    ASCII ``-``, drop Markdown emphasis markers (``*``/``_``), then collapse whitespace.
+    Case is preserved (the quote stays verbatim)."""
+    folded = (
+        unicodedata.normalize("NFKC", s)
+        .translate(_DASH_MAP)
+        .replace("*", "")
+        .replace("_", "")
+    )
+    return collapse_ws(folded)

grounding/_text.py

@@ -0,0 +1,52 @@
+"""Shared text / identifier helpers (leaf module).
+
+Small, dependency-light helpers: the sha256 hasher, the single phrase matcher
+``DocRef.contains`` delegates to, and the identifier-column preservation used by
+:func:`grounding.load`. Imports only :mod:`grounding._normalize` (pure stdlib) and,
+lazily, pandas inside :func:`preserve_identifier`; nothing here imports back up into the
+package, so it is safe to import from anywhere.
+"""
+from __future__ import annotations
+
+import hashlib
+import re as _re
+
+from ._normalize import fold_match
+
+
+def sha256(b: bytes) -> str:
+    return hashlib.sha256(b).hexdigest()
+
+
+def match_phrase(phrase: str, text: str, *, normalize_ws: bool = True) -> bool:
+    """Substring-check ``phrase`` against ``text`` for verbatim-quote matching. With
+    ``normalize_ws`` (default) fold both sides first (NFKC + Unicode-dash fold + Markdown
+    emphasis strip + whitespace-collapse) so a correct quote isn't defeated by an en-dash,
+    a ligature, stored Markdown, or an extractor that split it across runs/lines/cells.
+    Case is preserved."""
+    if normalize_ws:
+        return fold_match(phrase) in fold_match(text)
+    return phrase in text
+
+
+_INT_LIKE = _re.compile(r"^-?\d+$")
+
+
+def preserve_identifier(col, str_col):
+    """Keep a column as faithful strings when pandas' numeric inference would corrupt
+    identifiers. Fires only when every non-blank value is a plain integer string AND
+    inference would alter it — a leading zero (``"01"`` -> ``1``) or a column floated by
+    blank cells (``"73"`` -> ``73.0``). Real measurement columns (decimals, sign-less
+    floats, clean blank-free integers) are left numeric and untouched."""
+    import pandas as pd
+
+    if not (pd.api.types.is_integer_dtype(col.dtype) or pd.api.types.is_float_dtype(col.dtype)):
+        return col  # already object/string
+    nonblank = str_col[str_col != ""]
+    if not len(nonblank) or not nonblank.map(lambda v: bool(_INT_LIKE.match(v))).all():
+        return col  # has decimals / non-integer text -> a real measurement column
+    has_leading_zero = nonblank.map(lambda v: len(v) > 1 and v.lstrip("-").startswith("0")).any()
+    has_blanks = (str_col == "").any()
+    if has_leading_zero or has_blanks:
+        return str_col  # identifier-like; keep the exact text
+    return col          # clean blank-free integers (counts, indices) stay numeric

grounding/claim.py

@@ -0,0 +1,101 @@
+"""The claim surface: the proposition, the evidence, composition, and the judgment markers.
+
+A claim is a pytest test. Inside it:
+
+    statement(...)              the proposition — what is asserted (ideally computed from data)
+    evidence(**kv)              headline numbers, kept OUT of the assert
+    uses(claim_id)              compose on a prior claim (transitive provenance + its evidence)
+
+and on it, the non-binary judgment (metadata, never a pass/fail input):
+
+    @strength(...) @caveats(...) @kind(...) @reviewed(...)
+"""
+from __future__ import annotations
+
+from ._capture import current_capture, registry
+
+
+def statement(text: str) -> None:
+    """Record the claim's proposition — the human-readable statement a reviewer judges and
+    a citation renders. Prefer a value computed from the data, e.g.
+    ``statement(f"knockdown reached {hi:.0f}% at the high dose")``, so the claim literally
+    cannot state a number its evidence doesn't produce. One statement per claim."""
+    cap = current_capture()
+    if cap is not None:
+        cap.statement = str(text)
+
+
+def evidence(**kv) -> None:
+    """Record headline numbers for the report (e.g. ``evidence(knockdown_pct=53)``). Kept
+    *out* of the assert so the assertion stays a pure grounding/drift check."""
+    cap = current_capture()
+    if cap is not None:
+        cap.evidence.update(kv)
+
+
+def uses(claim_id: str) -> dict:
+    """Compose on another claim: merge its recorded inputs into this capture (transitive
+    provenance) and return its evidence dict. The referenced claim must have run earlier in
+    the session (collection order).
+
+    ``claim_id`` may be a full node id or a bare function name. A bare name that is ambiguous
+    across files prefers a candidate in the *calling claim's own file*; for a genuine
+    cross-file reference, pass a qualified id (``"<file>::test_x"``)."""
+    cap = current_capture()
+    rec = registry.get(claim_id)
+    if rec is None:
+        cand = [k for k in registry
+                if k == claim_id or k.endswith("::" + claim_id) or k.split("::")[-1] == claim_id]
+        if len(cand) > 1 and cap is not None and cap.claim_id:
+            my_file = cap.claim_id.split("::")[0]
+            same = [k for k in cand if k.split("::")[0] == my_file]
+            if same:
+                cand = same
+        if len(cand) == 1:
+            rec = registry.get(cand[0])
+        elif len(cand) > 1:
+            raise LookupError(
+                f"uses({claim_id!r}) is ambiguous — qualify it as "
+                f"'<file>::{claim_id.split('::')[-1]}'. Candidates: {sorted(cand)}")
+    if rec is None:
+        raise LookupError(
+            f"uses({claim_id!r}): no completed claim with that id has run yet "
+            f"(known: {sorted(registry)})")
+    if cap is not None:
+        for inp in rec["inputs"]:
+            cap.record(inp["kind"], inp["path"], inp["sha256"], via="uses")
+    return dict(rec.get("evidence", {}))
+
+
+# --------------------------------------------------------------------------- #
+# Markers — the non-binary judgment, kept out of the assert.
+# --------------------------------------------------------------------------- #
+def _marker(name):
+    import pytest
+    return getattr(pytest.mark, name)
+
+
+def strength(level: str):
+    """``@strength("strong|moderate|weak|...")`` — how strongly the evidence supports the
+    statement. Metadata, not a pass/fail input; edits across commits are the
+    belief-change ledger."""
+    return _marker("strength")(level)
+
+
+def caveats(text: str):
+    """``@caveats("...")`` — scope/limits a reader must keep in mind."""
+    return _marker("caveats")(text)
+
+
+def kind(category: str):
+    """``@kind("result|design|external|interpretive|...")`` — what sort of assertion this is."""
+    return _marker("kind")(category)
+
+
+def reviewed(**verdict):
+    """``@reviewed(by=..., support=True, date=..., note=...)`` — a reviewer's (human or
+    fresh-context agent) one-time judgment that the evidence actually supports the
+    statement as worded. The mechanical check is the assert; this records the reading
+    judgment that the assert can't make. ``support=False`` flags a claim the reviewer
+    judged unsupported."""
+    return _marker("reviewed")(**verdict)

grounding/cli.py

@@ -0,0 +1,39 @@
+"""``grounding`` CLI — currently one verb, ``trace``.
+
+    grounding trace <grounding_report.json | dir>      re-verify claims' inputs vs shas
+    grounding trace <dir> --json                        machine-readable
+
+Exit 0 if every claim is still grounded, 1 if any input changed/went missing.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(prog="grounding", description="grounded-claims tooling")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    t = sub.add_parser("trace", help="re-verify each claim's inputs still match recorded shas")
+    t.add_argument("path", help="grounding_report.json, or a directory containing it")
+    t.add_argument("--json", action="store_true", help="machine-readable output")
+
+    args = ap.parse_args(argv)
+
+    if args.cmd == "trace":
+        from . import trace as T
+
+        result = T.trace(args.path)
+        if args.json:
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+        else:
+            print(T.render(result))
+        return 0 if result["status"] == "GROUNDED" else 1
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

grounding/guard.py

@@ -0,0 +1,105 @@
+"""Bypass guard — make untracked source reads visible.
+
+While a capture is active we wrap ``pandas.read_csv`` and ``builtins.open`` so a *direct*
+read of a tracked source file (one not routed through :func:`grounding.load` / :func:`doc`)
+is still captured and flagged. This guarantees the captured input set is complete: a claim
+can't quietly read a CSV behind the harness's back. We capture-and-flag rather than
+hard-fail, so the grounding report still renders and the flag surfaces in the claim record.
+
+Only reads of tracked-suffix files *under the grounding root* are considered — the root is
+``GROUNDING_ROOT`` (env) or whatever the plugin sets to the pytest rootdir — so the guard
+never interferes with the test runner reading its own internals or temp files.
+"""
+from __future__ import annotations
+
+import builtins
+import os
+from pathlib import Path
+
+from ._capture import TRACKED_SUFFIXES, current_capture
+from ._text import sha256
+
+_guard_installed = False
+_orig_open = builtins.open
+_orig_read_csv = None
+_ROOT: Path | None = None
+
+
+def set_root(path) -> None:
+    """Set the directory under which untracked reads are flagged (the plugin calls this with
+    ``GROUNDING_ROOT`` or the pytest rootdir). ``None`` disables flagging."""
+    global _ROOT
+    _ROOT = Path(path).resolve() if path else None
+
+
+def _data_root() -> Path | None:
+    if _ROOT is not None:
+        return _ROOT
+    r = os.environ.get("GROUNDING_ROOT")
+    return Path(r).resolve() if r else None
+
+
+def _under_root(p: Path) -> bool:
+    root = _data_root()
+    if root is None:
+        return False
+    try:
+        p.resolve().relative_to(root)
+        return True
+    except (ValueError, OSError):
+        return False
+
+
+def _maybe_flag(path, via: str) -> None:
+    cap = current_capture()
+    if cap is None:
+        return
+    try:
+        p = Path(path)
+    except TypeError:
+        return
+    if p.suffix.lower() not in TRACKED_SUFFIXES or not _under_root(p):
+        return
+    if not p.is_file():
+        return
+    # If a tracked loader already recorded this exact path, nothing to flag.
+    if any(inp["path"] == str(p) for inp in cap.inputs):
+        return
+    sha = sha256(p.read_bytes())
+    cap.record("bypass", p, sha, via=f"bypass:{via}")
+    cap.bypassed.append(f"{via}: {p}")
+
+
+def install_guard() -> None:
+    """Patch ``builtins.open`` (always) and ``pandas.read_csv`` (if pandas is installed) to
+    flag untracked tracked-file reads. Idempotent; a no-op when no capture is active, so it
+    is safe to leave installed for the whole session."""
+    global _guard_installed, _orig_read_csv
+    if _guard_installed:
+        return
+
+    def guarded_open(file, mode="r", *a, **k):
+        if "r" in mode and isinstance(file, (str, os.PathLike)):
+            _maybe_flag(file, "open")
+        return _orig_open(file, mode, *a, **k)
+
+    builtins.open = guarded_open
+
+    try:
+        import pandas as pd
+    except ImportError:
+        pd = None
+    if pd is not None:
+        orig_read_csv = pd.read_csv
+        _orig_read_csv = orig_read_csv
+
+        def guarded_read_csv(*a, **k):
+            # Only path-like first args are real file reads; BytesIO (our load()) is skipped.
+            target = a[0] if a else k.get("filepath_or_buffer")
+            if isinstance(target, (str, os.PathLike)):
+                _maybe_flag(target, "pandas.read_csv")
+            return orig_read_csv(*a, **k)
+
+        pd.read_csv = guarded_read_csv
+
+    _guard_installed = True

grounding/loaders.py

@@ -0,0 +1,186 @@
+"""Tracked loaders: sha-pinned data + document handles.
+
+``load``/``data`` read a CSV into a DataFrame and record it as provenance; ``doc`` records
+a non-table source (PDF/Word/PowerPoint) and returns a :class:`DocRef` whose
+:meth:`~DocRef.contains` verifies a verbatim quote against the document's text. All reads
+are sha-pinned: the recorded hash is of exactly the bytes that were parsed.
+
+The per-format text readers are offline, deterministic, pure functions of the bytes — no
+network, no key, no model. There is **no OCR**: a scanned/image-only document has no text
+layer, so rather than let a quote silently "not match", :meth:`DocRef.text` raises
+:class:`EmptyExtraction`.
+"""
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ._capture import record
+from ._text import match_phrase, preserve_identifier, sha256
+
+
+class UnsupportedDocFormat(ValueError):
+    """Raised by :meth:`DocRef.text` for a suffix no built-in reader handles."""
+
+
+class EmptyExtraction(RuntimeError):
+    """Raised when a document yields no extractable text (e.g. a scanned PDF with no text
+    layer). A claim must never quietly pass or fail because its source was unreadable."""
+
+
+# --------------------------------------------------------------------------- #
+# CSV — the tracked data loader
+# --------------------------------------------------------------------------- #
+def load(path, kind: str = "data"):
+    """Read a CSV into a DataFrame, sha-pin it, and record it as provenance.
+
+    The DataFrame carries ``.attrs["source"]`` and ``.attrs["sha256"]``. The sha is of the
+    file bytes (exactly what was parsed); the parse goes through ``BytesIO`` so the bypass
+    guard never double-counts it. Identifier columns whose values only look numeric (``"01"``,
+    ``"08"``) are kept as faithful strings (see :func:`grounding._text.preserve_identifier`).
+    Needs the ``[data]`` extra (pandas)."""
+    import pandas as pd
+
+    p = Path(path)
+    raw = p.read_bytes()
+    sha = sha256(raw)
+    record(kind, p, sha)
+    df = pd.read_csv(io.BytesIO(raw))
+    str_df = pd.read_csv(io.BytesIO(raw), dtype=str, keep_default_na=False)
+    for col in df.columns:
+        df[col] = preserve_identifier(df[col], str_df[col])
+    df.attrs["source"] = str(p)
+    df.attrs["sha256"] = sha
+    return df
+
+
+data = load  # spelled both ways
+
+
+# --------------------------------------------------------------------------- #
+# Document text readers (the [docs] extra) — offline, deterministic, verbatim
+# --------------------------------------------------------------------------- #
+def read_pdf_text(path) -> str:
+    """All page text of a PDF, newline-joined (pdfplumber). Pure function of the bytes.
+    Deliberately not a hosted/Markdown extractor: quote-matching needs raw text that is
+    deterministic and verbatim."""
+    import pdfplumber
+
+    with pdfplumber.open(str(path)) as pdf:
+        return "\n".join((page.extract_text() or "") for page in pdf.pages)
+
+
+def read_docx_text(path) -> str:
+    """All paragraph + table-cell text of a .docx, newline-joined (python-docx)."""
+    import docx
+
+    d = docx.Document(str(path))
+    parts = [p.text for p in d.paragraphs]
+    for table in d.tables:
+        for row in table.rows:
+            parts.extend(cell.text for cell in row.cells)
+    return "\n".join(parts)
+
+
+def read_pptx_text(path) -> str:
+    """All deck prose, newline-joined (python-pptx): title/body text frames, table cells,
+    *grouped* shapes, and speaker notes — so a quote in any of them is matchable."""
+    from pptx import Presentation
+    from pptx.enum.shapes import MSO_SHAPE_TYPE
+
+    def walk(shapes):
+        for shape in shapes:
+            if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+                yield from walk(shape.shapes)
+            else:
+                yield shape
+
+    prs = Presentation(str(path))
+    parts: list[str] = []
+    for slide in prs.slides:
+        for shape in walk(slide.shapes):
+            if shape.has_text_frame:
+                parts.append(shape.text_frame.text)
+            if shape.has_table:
+                for row in shape.table.rows:
+                    parts.extend(cell.text for cell in row.cells)
+        if slide.has_notes_slide:
+            notes = slide.notes_slide.notes_text_frame
+            if notes is not None:
+                parts.append(notes.text)
+    return "\n".join(parts)
+
+
+# suffix -> reader. Pure-Python formats only; legacy .doc/.ppt (which would need
+# LibreOffice) are intentionally absent and raise UnsupportedDocFormat.
+_TEXT_READERS = {
+    ".pdf": read_pdf_text,
+    ".docx": read_docx_text,
+    ".pptx": read_pptx_text,
+}
+
+_PRESENTATION_SUFFIXES = {".pptx", ".ppt", ".odp"}
+
+
+@dataclass
+class DocRef:
+    """A handle to a non-table source (a PDF/Word report, or a slide deck) recorded as
+    evidence. Returned by :func:`doc` so a claim can quote it and keep the citation
+    traceable. :meth:`text`/:meth:`contains` extract and match its prose."""
+
+    path: Path
+    sha256: str
+    _text: str | None = field(default=None, init=False, repr=False, compare=False)
+
+    def __str__(self) -> str:
+        return f"{self.path.name}@{self.sha256[:12]}"
+
+    @property
+    def is_presentation(self) -> bool:
+        """True for slide decks (.pptx/.ppt/.odp) — weaker evidence than a signed report
+        (summary text, rounded numbers, scattered across shapes)."""
+        return self.path.suffix.lower() in _PRESENTATION_SUFFIXES
+
+    def text(self) -> str:
+        """Extract the document's plain text, dispatching on suffix (``.pdf``/``.docx``/
+        ``.pptx``; needs the ``[docs]`` extra). Cached on the instance. Raises
+        :class:`UnsupportedDocFormat` for any other suffix, and :class:`EmptyExtraction`
+        when the document yields no text (scanned/image-only — OCR is not supported)."""
+        if self._text is None:
+            reader = _TEXT_READERS.get(self.path.suffix.lower())
+            if reader is None:
+                raise UnsupportedDocFormat(
+                    f"doc().text() can't extract {self.path.suffix!r} ({self.path.name}): "
+                    f"supported formats are {', '.join(sorted(_TEXT_READERS))} "
+                    f"(install the [docs] extra). Legacy .doc/.ppt are not supported.")
+            try:
+                txt = reader(self.path)
+            except ImportError as exc:
+                name = getattr(exc, "name", None) or "a reader"
+                raise ImportError(
+                    f"{name} is required to read {self.path.suffix} — install the [docs] "
+                    f"extra: pip install 'grounding[docs]'") from exc
+            if not txt.strip():
+                raise EmptyExtraction(
+                    f"no extractable text in {self.path.name} — a scanned/image-only "
+                    f"document? OCR is not supported. A quote can't be verified against "
+                    f"an unreadable source.")
+            self._text = txt
+        return self._text
+
+    def contains(self, phrase: str, *, normalize_ws: bool = True) -> bool:
+        """Substring-check ``phrase`` against the extracted :meth:`text`. With
+        ``normalize_ws`` (default), fold whitespace/dashes/Markdown on both sides first —
+        the robust way to match a verbatim quote an extractor split across lines/cells."""
+        return match_phrase(phrase, self.text(), normalize_ws=normalize_ws)
+
+
+def doc(path, kind: str = "doc"):
+    """Record a non-table source (a PDF/Word report, or a slide deck) as a provenance input
+    and return a :class:`DocRef`. The quote a claim makes is grounded in the bytes of the
+    cited document, sha-pinned like any table. Call :meth:`DocRef.contains` to verify it."""
+    p = Path(path)
+    sha = sha256(p.read_bytes())
+    record(kind, p, sha)
+    return DocRef(p, sha)

grounding/plugin.py

@@ -0,0 +1,236 @@
+"""pytest plugin — capture provenance, collect claims, emit the grounding report.
+
+A *claim* is a pytest test: its :func:`grounding.statement` call is the proposition, its
+node id is the stable id, its body is the justification (reads sha-pinned via ``load``/
+``doc``), and its assert is the grounding/drift check. Markers carry the non-binary
+judgment (``strength``/``caveats``/``kind``/``reviewed``); lifecycle rides pytest states
+(``xfail`` = contradicted/retracted, ``skip`` = unverifiable).
+
+This plugin:
+  * registers the markers (no "unknown mark" warnings),
+  * wraps each test in a :class:`grounding.Capture` (autouse fixture) so every ``load``/
+    ``doc`` read is recorded, and installs the bypass guard,
+  * collects ``{id, statement, outcome, evidence, inputs+shas, strength, caveats, kind,
+    reviewed, notes}`` per claim and writes ``grounding_report.{json,md}``.
+
+Auto-loaded via the ``pytest11`` entry point, so a bare ``pytest`` collects grounded claims
+once the package is installed.
+"""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+import pytest
+
+from . import guard
+from ._capture import Capture, _CURRENT, registry
+
+_MARKERS = {
+    "strength": "strength(level): how strongly the evidence supports the statement",
+    "caveats": "caveats(text): scope/limits to keep in mind",
+    "kind": "kind(category): result|design|external|interpretive|...",
+    "reviewed": "reviewed(**verdict): a reviewer's support judgment of the claim",
+}
+
+
+def pytest_addoption(parser):
+    g = parser.getgroup("grounding")
+    g.addoption("--grounding-out", action="store", default=None,
+                help="directory for grounding_report.{json,md} (default: rootdir)")
+    g.addoption("--grounding-fresh", "--no-merge", action="store_true", default=False,
+                dest="grounding_fresh",
+                help="ignore any existing grounding_report.json and write ONLY this run's "
+                     "records (clean slate). Default MERGES this run's claims into the "
+                     "existing report at test-file granularity, so a partial run updates "
+                     "just its own files and leaves other modules' claims intact.")
+
+
+def pytest_configure(config):
+    for name, help_ in _MARKERS.items():
+        config.addinivalue_line("markers", help_)
+    # Flag untracked reads under the grounding root: GROUNDING_ROOT, else the rootdir.
+    guard.set_root(os.environ.get("GROUNDING_ROOT") or str(config.rootpath))
+    guard.install_guard()
+    config._grounding_records = []
+
+
+# --------------------------------------------------------------------------- #
+# Per-claim capture
+# --------------------------------------------------------------------------- #
+@pytest.fixture(autouse=True)
+def _grounding_capture(request):
+    """Set a fresh capture for each claim and attach it to the item so the report hook can
+    read it."""
+    cap = Capture(claim_id=request.node.nodeid)
+    token = _CURRENT.set(cap)
+    request.node._grounding_cap = cap
+    try:
+        yield cap
+    finally:
+        _CURRENT.reset(token)
+
+
+def _marker_val(item, name, default=None):
+    m = item.get_closest_marker(name)
+    if m is None:
+        return default
+    return m.args[0] if m.args else default
+
+
+def _marker_kwargs(item, name):
+    m = item.get_closest_marker(name)
+    return dict(m.kwargs) if m is not None else None
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    out = yield
+    rep = out.get_result()
+    if rep.when != "call":
+        return
+    cap = getattr(item, "_grounding_cap", None)
+
+    outcome = rep.outcome
+    if hasattr(rep, "wasxfail"):
+        outcome = "xpass" if rep.passed else "xfail"
+    elif rep.skipped and call.excinfo and call.excinfo.errisinstance(pytest.xfail.Exception):
+        outcome = "xfail"
+
+    notes = (item.function.__doc__ or "").strip() if hasattr(item, "function") else ""
+    statement = cap.statement if cap and cap.statement else None
+    evidence = dict(cap.evidence) if cap else {}
+    inputs = list(cap.inputs) if cap else []
+
+    advisories: list[str] = []
+    if statement is None and outcome not in ("skipped",):
+        advisories.append("no statement() — the proposition isn't recorded")
+    if cap and cap.bypassed:
+        advisories.append(f"{len(cap.bypassed)} untracked read(s) caught by the bypass guard")
+
+    rec = {
+        "id": item.nodeid,
+        "statement": statement,
+        "notes": notes or None,
+        "outcome": outcome,
+        "kind": _marker_val(item, "kind", "unspecified"),
+        "strength": _marker_val(item, "strength", "unspecified"),
+        "caveats": _marker_val(item, "caveats"),
+        "reviewed": _marker_kwargs(item, "reviewed"),
+        "evidence": evidence,
+        "inputs": inputs,
+        "bypassed": list(cap.bypassed) if cap else [],
+        "advisories": advisories,
+        "longrepr": str(rep.longrepr) if rep.failed and not getattr(rep, "wasxfail", None) else None,
+    }
+    item.config._grounding_records.append(rec)
+    registry[item.nodeid] = rec  # enables uses(claim_id) for later claims
+
+
+# --------------------------------------------------------------------------- #
+# Report emission
+# --------------------------------------------------------------------------- #
+def _json_default(o):
+    if hasattr(o, "item"):           # numpy scalar -> python scalar
+        try:
+            return o.item()
+        except (ValueError, TypeError):
+            pass
+    if hasattr(o, "tolist"):         # numpy array / pandas Index/Series -> list
+        return o.tolist()
+    return str(o)
+
+
+_OUTCOME_LABEL = {
+    "passed": "✅ grounded", "failed": "❌ DRIFT", "xfail": "⊘ contradicted",
+    "xpass": "⚠️ unexpectedly grounded", "skipped": "… unverifiable",
+}
+
+
+def _test_file_of(record: dict) -> str:
+    cid = record.get("id") or ""
+    head = cid.split("::", 1)[0]
+    return Path(head).name or cid
+
+
+def _merge_records(prior: list[dict], current: list[dict]) -> list[dict]:
+    """Union prior and current records at test-file granularity, sorted by id: drop prior
+    records from files this run produced, keep the rest, add this run's records. A
+    whole-suite run replaces everything; a one-file run updates just that file."""
+    current_files = {_test_file_of(r) for r in current}
+    kept = [r for r in prior if _test_file_of(r) not in current_files]
+    return sorted(kept + list(current), key=lambda r: r.get("id") or "")
+
+
+def _load_prior_records(path: Path) -> list[dict]:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return [c for c in data.get("claims", []) if isinstance(c, dict)]
+    except (OSError, ValueError, AttributeError, TypeError):
+        return []
+
+
+def pytest_sessionfinish(session):
+    config = session.config
+    records = getattr(config, "_grounding_records", [])
+    if not records:
+        return
+    out_dir = Path(config.getoption("--grounding-out") or config.rootpath)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    json_path = out_dir / "grounding_report.json"
+
+    if config.getoption("grounding_fresh", default=False):
+        merged = sorted(records, key=lambda r: r.get("id") or "")
+    else:
+        merged = _merge_records(_load_prior_records(json_path), records)
+
+    json_path.write_text(
+        json.dumps({"claims": merged}, indent=2, ensure_ascii=False, default=_json_default),
+        encoding="utf-8")
+    (out_dir / "grounding_report.md").write_text(_render_md(merged), encoding="utf-8")
+    config._grounding_report_path = out_dir / "grounding_report.md"
+
+
+def pytest_terminal_summary(terminalreporter, exitstatus, config):
+    p = getattr(config, "_grounding_report_path", None)
+    if p is not None:
+        terminalreporter.write_sep("-", "grounding report")
+        terminalreporter.write_line(f"  {p}")
+
+
+def _render_md(records: list[dict]) -> str:
+    from collections import Counter
+
+    tally = Counter(r["outcome"] for r in records)
+    lines = ["# Grounding report", "", "| outcome | n |", "|---|---|"]
+    for k, v in tally.items():
+        lines.append(f"| {_OUTCOME_LABEL.get(k, k)} | {v} |")
+    lines.append("")
+    by_kind: dict[str, list[dict]] = {}
+    for r in records:
+        by_kind.setdefault(r["kind"], []).append(r)
+    for kind in sorted(by_kind):
+        lines += [f"## kind: {kind}", ""]
+        for r in by_kind[kind]:
+            lines.append(f"### {_OUTCOME_LABEL.get(r['outcome'], r['outcome'])} — `{r['id'].split('::')[-1]}`")
+            if r.get("statement"):
+                lines.append(f"> {r['statement']}")
+            meta = f"**strength:** {r['strength']}"
+            if r.get("caveats"):
+                meta += f" · **caveats:** {r['caveats']}"
+            lines += ["", meta]
+            if r.get("evidence"):
+                ev = ", ".join(f"`{k}={v}`" for k, v in r["evidence"].items())
+                lines.append(f"\n**evidence:** {ev}")
+            if r.get("inputs"):
+                lines.append("\n**inputs:**")
+                for i in r["inputs"]:
+                    via = "" if i["via"] == "tracked" else f" _({i['via']})_"
+                    lines.append(f"- `{i['kind']}` {Path(i['path']).name} — `{i['sha256'][:12]}`{via}")
+            if r.get("advisories"):
+                lines.append("\n**advisories:** " + "; ".join(r["advisories"]))
+            if r.get("longrepr"):
+                lines.append(f"\n```\n{r['longrepr'][:800]}\n```")
+            lines.append("")
+    return "\n".join(lines) + "\n"

grounding/report_io.py

@@ -0,0 +1,40 @@
+"""Locate + load the grounding report — the wire format between producer and consumers.
+
+``grounding_report.json`` is the contract the pytest plugin emits and every consumer reads.
+It is a *regenerable projection* of running the claims — never the source of truth (that is
+the tests + the source bytes). Delete it and rebuild by re-running pytest.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+GROUNDING_REPORT_NAME = "grounding_report.json"
+
+
+def load_report(path) -> dict:
+    """Parse a grounding_report.json into its dict form (``{"claims": [...]}``)."""
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def claims_of(data: dict) -> list[dict]:
+    """The claim records from a loaded report (defensive against a malformed file)."""
+    return [c for c in data.get("claims", []) if isinstance(c, dict)]
+
+
+def find_report(start) -> Path | None:
+    """Resolve ``start`` to a grounding_report.json: an existing file is used as-is; a
+    directory resolves to ``<dir>/grounding_report.json`` (searching upward a few levels).
+    Returns ``None`` if none is found."""
+    p = Path(start)
+    if p.is_file():
+        return p
+    if p.is_dir():
+        cand = p / GROUNDING_REPORT_NAME
+        if cand.is_file():
+            return cand
+        for parent in list(p.resolve().parents)[:4]:
+            cand = parent / GROUNDING_REPORT_NAME
+            if cand.is_file():
+                return cand
+    return None

grounding/trace.py

@@ -0,0 +1,65 @@
+"""Trace — re-verify a report's claims still rest on the bytes they recorded.
+
+For each claim in a grounding_report.json, re-hash every recorded input and compare to the
+stored sha256. A claim is GROUNDED if every input still exists and matches; a changed or
+missing input is a break. This is the static, git-free check that answers "is this
+conclusion still grounded?" without re-running the suite. (Re-running the suite is the
+*executable* complement — it recomputes the claim against the current bytes.)
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from ._text import sha256
+from .report_io import claims_of, find_report, load_report
+
+
+def trace(report_path) -> dict:
+    """Walk every claim's recorded inputs and re-verify their shas. Returns
+    ``{status, report, claims:[{id, statement, outcome, breaks:[...]}]}`` where ``status``
+    is ``GROUNDED`` iff no claim has a break."""
+    rp = find_report(report_path)
+    if rp is None:
+        return {"status": "NO_REPORT", "report": str(report_path), "claims": []}
+
+    claims = claims_of(load_report(rp))
+    base = rp.parent
+    out = []
+    status = "GROUNDED"
+    for c in claims:
+        breaks: list[str] = []
+        for inp in c.get("inputs", []):
+            p = Path(inp["path"])
+            if not p.is_absolute():
+                p = base / p
+            if not p.is_file():
+                breaks.append(f"missing: {inp['path']}")
+                continue
+            if sha256(p.read_bytes()) != inp.get("sha256"):
+                breaks.append(f"changed: {inp['path']}")
+        # A claim that recorded no inputs at all can't be grounded in anything.
+        if not c.get("inputs"):
+            breaks.append("no recorded inputs")
+        if breaks:
+            status = "BROKEN"
+        out.append({
+            "id": c.get("id"),
+            "statement": c.get("statement"),
+            "outcome": c.get("outcome"),
+            "breaks": breaks,
+        })
+    return {"status": status, "report": str(rp), "claims": out}
+
+
+def render(result: dict) -> str:
+    """Human-readable trace summary."""
+    lines = [f"trace: {result['status']}  ({result['report']})"]
+    for c in result["claims"]:
+        mark = "✅" if not c["breaks"] else "❌"
+        name = (c["id"] or "").split("::")[-1]
+        lines.append(f"  {mark} {name}")
+        if c.get("statement"):
+            lines.append(f"       {c['statement']}")
+        for b in c["breaks"]:
+            lines.append(f"       ! {b}")
+    return "\n".join(lines)

pytest_grounding-0.0.1.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: pytest-grounding
+Version: 0.0.1
+Summary: Turn assertions about data into re-runnable, provenance-tracked claims — written and reviewed by agents.
+Author-email: Sam Quigley <quigley@emerose.com>
+License: MIT
+Project-URL: Homepage, https://github.com/emerose/pytest-grounding
+Project-URL: Repository, https://github.com/emerose/pytest-grounding
+Project-URL: Issues, https://github.com/emerose/pytest-grounding/issues
+Keywords: pytest,provenance,grounding,claims,reproducibility,data,audit
+Classifier: Framework :: Pytest
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pytest>=7.0
+Provides-Extra: data
+Requires-Dist: pandas>=2.0; extra == "data"
+Provides-Extra: docs
+Requires-Dist: pdfplumber>=0.11; extra == "docs"
+Requires-Dist: python-docx>=1.1; extra == "docs"
+Requires-Dist: python-pptx>=1.0; extra == "docs"
+Dynamic: license-file
+
+# grounding
+
+**Turn assertions about data into re-runnable, provenance-tracked claims — written and reviewed by agents.**
+
+`grounding` is a small runtime on top of pytest. A test stops being a pass/fail check on your *code* and becomes a **grounded claim**: a statement about data, automatically pinned to the exact bytes it depends on, re-checked whenever those bytes change, carrying a non-binary judgment (how strong, with what caveats) that lives in version control.
+
+It's built for a workflow where **an agent writes the claims and a second, fresh-context agent reviews them.**
+
+```bash
+pip install grounding            # core (statement-only / quote-only)
+pip install 'grounding[data]'    # + CSV grounding via data()/load()
+pip install 'grounding[docs]'    # + document quote verification via doc()
+```
+
+No network, no API keys, no model inside. Everything is a pure function of file bytes.
+
+## Why agents, specifically
+
+When an agent asserts *"knockdown reached 53% at the high dose,"* you have two questions: **is it mechanically true** against the data, and **does the evidence actually support the claim** as worded? `grounding` splits those, and each half lands with the right reviewer:
+
+- **The mechanical half is the test.** Re-run it; it passes or fails against sha-pinned bytes. No reviewer judgment needed — CI does it.
+- **The judgment half is metadata** (`statement`, `@strength`, `@caveats`, the cited quote). A fresh-context reviewer agent reads *exactly* the bytes the author grounded — same shas, no drift — and decides whether the framing is honest.
+
+`grounding_report.json` is the machine-readable handoff: the author agent emits it, the reviewer agent consumes it.
+
+## A claim is a pytest test
+
+```python
+from grounding import data, evidence, statement, strength, caveats, kind
+from scipy import stats
+
+@kind("result")
+@strength("moderate")
+@caveats("n=8 per arm, single cohort; not corrected for multiple endpoints")
+def test_treatment_lowers_biomarker_vs_vehicle():
+    """Serum biomarker at day 28: 10 mg/kg arm vs vehicle, cohort B.
+
+    Reviewer notes: groups are the prespecified arms; Welch's t-test because the
+    vehicle arm's spread is larger; two treated animals were excluded upstream for
+    dosing errors (already applied in the tidy table).
+    """
+    df = data("biomarker_day28.csv")
+    treated = df[df.arm == "10mpk"].biomarker
+    vehicle = df[df.arm == "vehicle"].biomarker
+
+    drop = 1 - treated.mean() / vehicle.mean()
+    t, p = stats.ttest_ind(treated, vehicle, equal_var=False)
+
+    statement(f"At day 28, the 10 mg/kg arm showed a {drop:.0%} lower serum biomarker "
+              f"than vehicle (Welch t = {t:.1f}, p = {p:.3f}).")
+    evidence(pct_drop=round(drop * 100, 1), p_value=round(p, 4))
+
+    assert p < 0.05 and drop > 0    # the qualitative claim: a real, downward effect
+```
+
+The three layers don't repeat each other:
+
+- **`statement()`** is the proposition, with numbers interpolated from the data — it *can't* claim a drop the table doesn't produce.
+- the **docstring** is the *why and how* — context that lets a later reviewer judge the claim without re-deriving it.
+- the **`assert`** guards only the qualitative shape (significant, downward); the quantity lives in the computed statement.
+
+Run it:
+
+```bash
+pytest --grounding-out ./out
+```
+
+→ `out/grounding_report.json`:
+
+```json
+{
+  "claims": [{
+    "id": "test_efficacy.py::test_treatment_lowers_biomarker_vs_vehicle",
+    "statement": "At day 28, the 10 mg/kg arm showed a 41% lower serum biomarker than vehicle (Welch t = 3.2, p = 0.006).",
+    "kind": "result",
+    "strength": "moderate",
+    "caveats": "n=8 per arm, single cohort; not corrected for multiple endpoints",
+    "inputs": [{"kind": "data", "path": "biomarker_day28.csv", "sha256": "a17b…", "via": "tracked"}],
+    "evidence": {"pct_drop": 41.2, "p_value": 0.0061}
+  }]
+}
+```
+
+Nobody hand-wrote that provenance. `data()` recorded the read; the capture context attached it to the claim.
+
+## Grounding a quote in a document
+
+```python
+from grounding import doc, statement
+
+def test_summary_states_endpoint_met():
+    """Quote is from the signed CSR §10.1, not the synopsis."""
+    csr = doc("clinical_summary.pdf")          # sha-pinned like any input
+    statement("The clinical study report states the primary endpoint was met.")
+    assert csr.contains("the primary endpoint was met")
+```
+
+`DocRef.contains()` extracts with pinned pure-Python readers (pdf/docx/pptx) and matches whitespace/dash/Markdown-robustly, so a quote split across lines or cells still matches. The match is a pure function of the bytes. There is **no OCR**: a scanned/image-only document raises `EmptyExtraction` rather than silently reporting "not found".
+
+## Composing claims
+
+`uses()` lets one claim build on earlier ones: it merges their sha-pinned inputs into this
+claim's provenance (transitively) and hands back their `evidence`. The composed claim can read
+no source of its own, yet `grounding trace` still walks it all the way down — change an upstream
+dataset and the roll-up breaks too. Provenance is a computed DAG, never hand-maintained.
+
+**Roll up independent results.** A program-level conclusion that rests on several per-dataset
+claims — defined in different test files, over different data:
+
+```python
+from grounding import uses, statement, strength
+
+@strength("moderate")
+def test_effect_replicates_across_cohorts():
+    """The biomarker drop holds in two independently-run cohorts."""
+    b = uses("test_treatment_lowers_biomarker_vs_vehicle")   # cohort B
+    c = uses("test_treatment_lowers_biomarker_cohort_c")     # cohort C, a different test file
+    statement(f"the effect replicates: {b['pct_drop']:.0f}% (cohort B) "
+              f"and {c['pct_drop']:.0f}% (cohort C)")
+    assert b["pct_drop"] > 0 and c["pct_drop"] > 0
+```
+
+This claim touches no CSV directly, but its recorded inputs now include *both* cohorts' files,
+each sha-pinned. Change either cohort's data and this roll-up — not just the two underlying
+claims — shows up as drifted.
+
+**Cross-check data against a document.** Compose a numeric claim with a quote check to assert an
+external report and your own data agree — the classic transcription-drift catcher:
+
+```python
+from grounding import doc, uses, statement, strength, kind
+
+@kind("external")
+@strength("strong")
+def test_report_headline_matches_our_data():
+    """The CSR's stated drop matches what our tidy data produces — no transcription drift."""
+    ours = uses("test_treatment_lowers_biomarker_vs_vehicle")["pct_drop"]
+    csr = doc("clinical_summary.pdf")
+    statement(f"the CSR's reported reduction matches our computed {ours:.0f}% drop")
+    assert csr.contains(f"{ours:.0f}% reduction")
+```
+
+This grounds the *agreement* itself: the PDF is pinned by `doc()`, the number is pinned
+transitively through `uses()`, and the single assert fails if the report and the data ever
+diverge. Each claim stays small and independently reviewable; higher-level claims inherit — never
+re-derive — their evidence and provenance.
+
+## Tracing
+
+```bash
+grounding trace ./out          # re-verify every claim's inputs still match recorded shas
+```
+
+One command answers *"is this conclusion still grounded?"* — the question a reviewer otherwise spends an afternoon on. Exit 0 if grounded, 1 if any input changed or went missing.
+
+## What's in the box
+
+| Piece | What it does |
+|---|---|
+| **Capture context** | records every tracked read (kind, path, sha256) while a claim runs |
+| **Tracked loaders** | `data()`/`load()` (CSV→DataFrame, sha-pinned), `doc()` (any document) |
+| **`statement()`** | the claim's proposition — ideally computed from the data so it can't drift |
+| **Quote verification** | `DocRef.contains()` — offline, deterministic; raises on unreadable sources |
+| **pytest plugin** | wraps every test in a capture, emits `grounding_report.json` |
+| **Judgment markers** | `@strength`, `@caveats`, `@kind`, `@reviewed` — the reviewer's surface |
+| **`uses()`** | transitive claim composition |
+| **Bypass guard** | flags a claim that reads data through an untracked path |
+| **`grounding trace`** | walks the provenance DAG; tells you if a conclusion is still grounded |
+
+## Design principles
+
+- **Deterministic & offline.** Pure function of bytes. No network, keys, or model — runs in CI and in massively parallel agent fan-out with nothing to configure.
+- **Sha-pinned.** The recorded hash is of exactly the bytes parsed.
+- **The test is the spec.** A claim is an ordinary pytest test; your runner, fixtures, and CI just work. Git history of `statement`/`@strength`/`@caveats` is a belief-change ledger.
+- **Computed, not curated.** Provenance, composition, and (ideally) the statement itself derive from what ran, so they can't drift from reality.
+- **Author/critic separation by construction.** Mechanical truth → the assert; honest framing → metadata a fresh-context reviewer judges against the same pinned evidence.
+
+## What it is *not*
+
+- **Not data versioning** (DVC/lakeFS) — it pins shas of files you already have, wherever they live.
+- **Not a workflow engine** — it observes reads during a test; it doesn't orchestrate them.
+- **Not rendering** — turning grounded claims into a cited report (PDF/HTML) is a separate layer built *on top* of `grounding_report.json`.
+- **Not storage/indexing** — the report is the wire format; building a searchable index over it is a consumer's concern.
+- **Not an LLM judge** — it runs no model; judgments are recorded by the agents that use it.

pytest_grounding-0.0.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+grounding/__init__.py,sha256=trgaeeLarPVl6sZp-7xYsITSXr8bChD_NWiSK_mHulc,2486
+grounding/_capture.py,sha256=IUSy-T5Lwa6q36Epl8Ni4zjbnYq1guC01T1O1jS35pE,2783
+grounding/_normalize.py,sha256=Ec_5yCPnFq8ywoKcNj9CYLyIi62hLDHzezdOXBC52Zs,1752
+grounding/_text.py,sha256=BX8YrI4WCJzbw2RFxn2UEIaJuUptIj8eqxczVEKbdMo,2373
+grounding/claim.py,sha256=m8Uc_58ARKzrUjlBTxuaZFViDQczRbty1cZzLGWLkzU,4244
+grounding/cli.py,sha256=cASvd8lRXejxkLRttF7F3vazQFAwjQolKZqyeYLvE_g,1210
+grounding/guard.py,sha256=WvPfC6mPe91NuYQ7VpBXSUFUBqCxpuyNyfHjgKHupbU,3467
+grounding/loaders.py,sha256=cx8AuB9WBh3hcB8Fyb_8gCeKCy0PWI4DR4IfdR4ihks,7829
+grounding/plugin.py,sha256=FTNn8NGc17hLNVCPQWKZzcGuxqisqw25ehh1d6ZYElI,9476
+grounding/report_io.py,sha256=B-CNv_Gyaxpv6O4yTDPUjWRqRmmEfbng5MqIPa26aNY,1464
+grounding/trace.py,sha256=NxrWhZJdT-XvdvjUsOlYL0eENKafJP53iUZn9knsD0w,2513
+pytest_grounding-0.0.1.dist-info/licenses/LICENSE,sha256=7zWYAdBL9zruGyPR4pIEkWOMm-LjlvOoaJBamd5Uays,1068
+pytest_grounding-0.0.1.dist-info/METADATA,sha256=PZlqh0uXzn4fnrovmhpUbyzVSVLPq9tZ3KnjJ5OuAU4,10822
+pytest_grounding-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pytest_grounding-0.0.1.dist-info/entry_points.txt,sha256=e3hjM8FuEEuTRgqgW6L-haXT62tBiADjOtMb-N6Hm_Q,90
+pytest_grounding-0.0.1.dist-info/top_level.txt,sha256=G9oeBZ6MVFGVkzOWhMqAu6DaZ62iKeVTviROIDeD7t0,10
+pytest_grounding-0.0.1.dist-info/RECORD,,

pytest_grounding-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pytest_grounding-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+grounding = grounding.cli:main
+
+[pytest11]
+grounding = grounding.plugin

pytest_grounding-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sam Quigley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pytest_grounding-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+grounding