pytest-grounding 0.0.1__tar.gz

pytest_grounding-0.0.1/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,184 @@
+# 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/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"

pytest_grounding-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] = {}

pytest_grounding-0.0.1/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)

pytest_grounding-0.0.1/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