receipts-gate 0.1.0__tar.gz

receipts_gate-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,19 @@
+name: tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: python -m pytest -q

receipts_gate-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

receipts_gate-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env
+launch/

receipts_gate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrian Melendez
+
+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.

receipts_gate-0.1.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: receipts-gate
+Version: 0.1.0
+Summary: A hard gate that forces AI agents to back every claim with evidence — or declare it an assumption.
+Project-URL: Homepage, https://github.com/Thepizzapie/receipts
+Project-URL: Repository, https://github.com/Thepizzapie/receipts
+Project-URL: Issues, https://github.com/Thepizzapie/receipts/issues
+Author: Adrian Melendez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,evaluation,grounding,guardrails,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Receipts
+
+**Force AI agents to back every claim with evidence — or declare it an assumption.**
+
+Agents lie about the research they did and quietly base conclusions on guesses,
+because there's no cost to either. Receipts adds the cost. Every claim an agent
+makes must point at a tamper-evident log of what it *actually did*. Claims that
+can't be grounded are illegal — they must be surfaced as explicit assumptions, not
+buried in the answer.
+
+You can't fix this with prompting ("don't assume, don't lie"). Receipts doesn't
+ask the model to be honest — it *measures* honesty against ground truth, with
+deterministic checks the model can't game.
+
+## Install
+
+```bash
+pip install receipts-gate
+```
+
+Zero dependencies. The distribution is `receipts-gate` (the bare name was taken);
+the import and the CLI are plain `receipts`.
+
+## The three rules
+
+Every claim is checked against the `Ledger` (the captured execution log):
+
+| Rule | Kills | How |
+|------|-------|-----|
+| **Binding** | guesses stated as fact | A claim must cite real evidence in the ledger, or be demoted to an assumption. |
+| **Effort honesty** | "I reviewed the entire codebase" | Effort claims must cite evidence of a matching *kind*; words like *all / entire / thoroughly* require machine-checkable `coverage` proof. |
+| **Support** | citing a source that doesn't say it | Cited evidence must actually back the claim (deterministic heuristic by default; pluggable LLM/NLI judge for production). |
+
+## Two modes, one engine
+
+- **Live gate** (`Gate.finalize`) — runs inside the agent loop and *blocks*
+  ungrounded output before the user ever sees it, handing the agent a precise list
+  of what to fix.
+- **Post-hoc auditor** (`audit`) — ingest a finished trace and get a `Verdict`.
+  Same engine, no runtime coupling. Drop it in CI to fail PRs from ungrounded agent runs.
+
+## Quick start
+
+```python
+from receipts import Ledger, Gate, Answer, Claim, Assumption, ClaimKind
+
+# 1. Evidence is captured from real work, not self-reported.
+ledger = Ledger()
+ev = ledger.record("file_read", "config.py", "PORT = 8080")
+
+# 2. The agent emits claims that point at evidence.
+gate = Gate(ledger)  # hard gate by default
+answer = Answer(
+    summary="The service listens on port 8080.",
+    claims=[Claim("The port is 8080", evidence_ids=[ev.id], kind=ClaimKind.FACT)],
+    assumptions=[
+        Assumption("The paid tier is higher", reason="not verified",
+                   impact="capacity planning wrong if false"),
+    ],
+)
+
+# 3. The gate renders the answer, or raises UngroundedAnswerError with a fix list.
+print(gate.finalize(answer))
+```
+
+Capture evidence automatically by wrapping tools:
+
+```python
+from receipts import track
+
+@track(ledger, kind="web_fetch", source=lambda url: url)
+def fetch(url): ...
+```
+
+Or audit an existing run:
+
+```python
+from receipts import ingest_trace, audit
+ingest_trace(ledger, my_logged_events)   # [{"kind","source","content"}, ...]
+verdict = audit(answer, ledger)
+print(verdict.report())
+```
+
+## Semantic support via an LLM
+
+The default support check is token overlap — transparent, but shallow. For real
+grounding (catching a claim that cites evidence which is *related* but doesn't say
+what the claim asserts), swap in the LLM judge. The gate stays deterministic for
+binding and effort; only the support check calls the model, so the thing being
+audited can't game the structural rules.
+
+```python
+from receipts import Gate, AnthropicLLM, LLMSupportVerifier
+
+gate = Gate(ledger, verifier=LLMSupportVerifier(AnthropicLLM()))  # needs receipts-gate[anthropic]
+```
+
+`LLM` is a one-method protocol — drop in any backend (NLI model, embeddings, a
+different vendor) or `FakeLLM` for tests.
+
+## Free-text extraction (no structured claims required)
+
+Agents don't have to emit `Claim` objects by hand. Give Receipts the prose answer
+and the ledger, and it produces a structured `Answer` for the gate to check. The
+extraction is LLM-driven and advisory — every binding it produces is still
+re-verified deterministically, so a hallucinated citation surfaces as a gate
+failure, not a silent pass.
+
+```python
+from receipts import extract_claims, Gate, AnthropicLLM
+
+answer = extract_claims(free_text_answer, ledger, AnthropicLLM())
+print(Gate(ledger).finalize(answer))   # checks the extracted claims
+```
+
+## CLI / CI gate
+
+`receipts audit trace.json` exits non-zero when any claim is ungrounded — a
+drop-in CI gate on agent output. Deterministic by default (no API key); `--llm`
+turns on the semantic judge.
+
+```bash
+receipts audit trace.json          # exit 1 if blocked
+receipts audit trace.json --json   # machine-readable
+```
+
+Trace format and a copy-into-your-repo GitHub Action are in
+[`examples/ci/receipts-example.yml`](examples/ci/receipts-example.yml).
+Claims reference evidence by a local label, list index, or real id — see
+[`trace.py`](src/receipts/trace.py).
+
+## Framework adapters
+
+Capture is framework-agnostic; these map specific ecosystems onto the Ledger.
+
+**OpenAI / Anthropic / Claude Agent SDK traces** — ingest a finished transcript,
+recording each tool result as evidence (pure Python, no SDK needed):
+
+```python
+from receipts.adapters import from_openai_messages, from_anthropic_messages
+
+from_openai_messages(ledger, openai_messages)       # OpenAI chat format
+from_anthropic_messages(ledger, anthropic_messages) # Messages API / Claude Agent SDK
+```
+
+**LangChain / LangGraph** — capture tool results *live* via a callback handler,
+no change to your tool code:
+
+```python
+from receipts.adapters import langchain_handler
+
+handler = langchain_handler(ledger)
+agent.invoke(inputs, config={"callbacks": [handler]})
+```
+
+## Layout
+
+```
+src/receipts/
+  models.py      data model — Evidence, Claim, Assumption, Answer, Verdict
+  ledger.py      append-only, hash-stamped evidence log (the ground truth)
+  instrument.py  capture: @track decorator + ingest_trace()
+  verify.py      pluggable support check — HeuristicVerifier + LLMSupportVerifier
+  llm.py         LLM protocol + AnthropicLLM / FakeLLM backends
+  extract.py     free-text answer -> structured Answer
+  trace.py       load a portable trace file -> (Ledger, Answer)
+  cli.py         `receipts audit` command
+  gate.py        the three rules + Gate + audit()
+  adapters/      OpenAI trace, Anthropic/Claude-Agent-SDK trace, LangChain callback
+examples/        research_agent.py (gate), agent_loop.py (capture->extract->gate)
+tests/           pytest suite
+```
+
+## Develop
+
+```bash
+python -m pytest -q
+python examples/research_agent.py
+```
+
+## Status / roadmap
+
+v0.1 — core engine, hard gate, post-hoc auditor, framework-agnostic capture,
+LLM support verifier, free-text extraction, OpenAI adapter, `receipts audit` CLI
++ CI action.
+
+Adapters: OpenAI trace, Anthropic / Claude Agent SDK trace, LangChain/LangGraph
+callback.
+
+Next candidates:
+- NLI / embeddings `SupportVerifier` backends (no LLM call)
+- Live in-loop gate wrappers for popular agent runtimes
+- Published package on PyPI

receipts_gate-0.1.0/README.md

@@ -0,0 +1,193 @@
+# Receipts
+
+**Force AI agents to back every claim with evidence — or declare it an assumption.**
+
+Agents lie about the research they did and quietly base conclusions on guesses,
+because there's no cost to either. Receipts adds the cost. Every claim an agent
+makes must point at a tamper-evident log of what it *actually did*. Claims that
+can't be grounded are illegal — they must be surfaced as explicit assumptions, not
+buried in the answer.
+
+You can't fix this with prompting ("don't assume, don't lie"). Receipts doesn't
+ask the model to be honest — it *measures* honesty against ground truth, with
+deterministic checks the model can't game.
+
+## Install
+
+```bash
+pip install receipts-gate
+```
+
+Zero dependencies. The distribution is `receipts-gate` (the bare name was taken);
+the import and the CLI are plain `receipts`.
+
+## The three rules
+
+Every claim is checked against the `Ledger` (the captured execution log):
+
+| Rule | Kills | How |
+|------|-------|-----|
+| **Binding** | guesses stated as fact | A claim must cite real evidence in the ledger, or be demoted to an assumption. |
+| **Effort honesty** | "I reviewed the entire codebase" | Effort claims must cite evidence of a matching *kind*; words like *all / entire / thoroughly* require machine-checkable `coverage` proof. |
+| **Support** | citing a source that doesn't say it | Cited evidence must actually back the claim (deterministic heuristic by default; pluggable LLM/NLI judge for production). |
+
+## Two modes, one engine
+
+- **Live gate** (`Gate.finalize`) — runs inside the agent loop and *blocks*
+  ungrounded output before the user ever sees it, handing the agent a precise list
+  of what to fix.
+- **Post-hoc auditor** (`audit`) — ingest a finished trace and get a `Verdict`.
+  Same engine, no runtime coupling. Drop it in CI to fail PRs from ungrounded agent runs.
+
+## Quick start
+
+```python
+from receipts import Ledger, Gate, Answer, Claim, Assumption, ClaimKind
+
+# 1. Evidence is captured from real work, not self-reported.
+ledger = Ledger()
+ev = ledger.record("file_read", "config.py", "PORT = 8080")
+
+# 2. The agent emits claims that point at evidence.
+gate = Gate(ledger)  # hard gate by default
+answer = Answer(
+    summary="The service listens on port 8080.",
+    claims=[Claim("The port is 8080", evidence_ids=[ev.id], kind=ClaimKind.FACT)],
+    assumptions=[
+        Assumption("The paid tier is higher", reason="not verified",
+                   impact="capacity planning wrong if false"),
+    ],
+)
+
+# 3. The gate renders the answer, or raises UngroundedAnswerError with a fix list.
+print(gate.finalize(answer))
+```
+
+Capture evidence automatically by wrapping tools:
+
+```python
+from receipts import track
+
+@track(ledger, kind="web_fetch", source=lambda url: url)
+def fetch(url): ...
+```
+
+Or audit an existing run:
+
+```python
+from receipts import ingest_trace, audit
+ingest_trace(ledger, my_logged_events)   # [{"kind","source","content"}, ...]
+verdict = audit(answer, ledger)
+print(verdict.report())
+```
+
+## Semantic support via an LLM
+
+The default support check is token overlap — transparent, but shallow. For real
+grounding (catching a claim that cites evidence which is *related* but doesn't say
+what the claim asserts), swap in the LLM judge. The gate stays deterministic for
+binding and effort; only the support check calls the model, so the thing being
+audited can't game the structural rules.
+
+```python
+from receipts import Gate, AnthropicLLM, LLMSupportVerifier
+
+gate = Gate(ledger, verifier=LLMSupportVerifier(AnthropicLLM()))  # needs receipts-gate[anthropic]
+```
+
+`LLM` is a one-method protocol — drop in any backend (NLI model, embeddings, a
+different vendor) or `FakeLLM` for tests.
+
+## Free-text extraction (no structured claims required)
+
+Agents don't have to emit `Claim` objects by hand. Give Receipts the prose answer
+and the ledger, and it produces a structured `Answer` for the gate to check. The
+extraction is LLM-driven and advisory — every binding it produces is still
+re-verified deterministically, so a hallucinated citation surfaces as a gate
+failure, not a silent pass.
+
+```python
+from receipts import extract_claims, Gate, AnthropicLLM
+
+answer = extract_claims(free_text_answer, ledger, AnthropicLLM())
+print(Gate(ledger).finalize(answer))   # checks the extracted claims
+```
+
+## CLI / CI gate
+
+`receipts audit trace.json` exits non-zero when any claim is ungrounded — a
+drop-in CI gate on agent output. Deterministic by default (no API key); `--llm`
+turns on the semantic judge.
+
+```bash
+receipts audit trace.json          # exit 1 if blocked
+receipts audit trace.json --json   # machine-readable
+```
+
+Trace format and a copy-into-your-repo GitHub Action are in
+[`examples/ci/receipts-example.yml`](examples/ci/receipts-example.yml).
+Claims reference evidence by a local label, list index, or real id — see
+[`trace.py`](src/receipts/trace.py).
+
+## Framework adapters
+
+Capture is framework-agnostic; these map specific ecosystems onto the Ledger.
+
+**OpenAI / Anthropic / Claude Agent SDK traces** — ingest a finished transcript,
+recording each tool result as evidence (pure Python, no SDK needed):
+
+```python
+from receipts.adapters import from_openai_messages, from_anthropic_messages
+
+from_openai_messages(ledger, openai_messages)       # OpenAI chat format
+from_anthropic_messages(ledger, anthropic_messages) # Messages API / Claude Agent SDK
+```
+
+**LangChain / LangGraph** — capture tool results *live* via a callback handler,
+no change to your tool code:
+
+```python
+from receipts.adapters import langchain_handler
+
+handler = langchain_handler(ledger)
+agent.invoke(inputs, config={"callbacks": [handler]})
+```
+
+## Layout
+
+```
+src/receipts/
+  models.py      data model — Evidence, Claim, Assumption, Answer, Verdict
+  ledger.py      append-only, hash-stamped evidence log (the ground truth)
+  instrument.py  capture: @track decorator + ingest_trace()
+  verify.py      pluggable support check — HeuristicVerifier + LLMSupportVerifier
+  llm.py         LLM protocol + AnthropicLLM / FakeLLM backends
+  extract.py     free-text answer -> structured Answer
+  trace.py       load a portable trace file -> (Ledger, Answer)
+  cli.py         `receipts audit` command
+  gate.py        the three rules + Gate + audit()
+  adapters/      OpenAI trace, Anthropic/Claude-Agent-SDK trace, LangChain callback
+examples/        research_agent.py (gate), agent_loop.py (capture->extract->gate)
+tests/           pytest suite
+```
+
+## Develop
+
+```bash
+python -m pytest -q
+python examples/research_agent.py
+```
+
+## Status / roadmap
+
+v0.1 — core engine, hard gate, post-hoc auditor, framework-agnostic capture,
+LLM support verifier, free-text extraction, OpenAI adapter, `receipts audit` CLI
++ CI action.
+
+Adapters: OpenAI trace, Anthropic / Claude Agent SDK trace, LangChain/LangGraph
+callback.
+
+Next candidates:
+- NLI / embeddings `SupportVerifier` backends (no LLM call)
+- Live in-loop gate wrappers for popular agent runtimes
+- Published package on PyPI

receipts_gate-0.1.0/examples/agent_loop.py

@@ -0,0 +1,103 @@
+"""End-to-end: a tracked tool loop -> free-text answer -> extract -> gate.
+
+Runs fully offline (FakeLLM stands in for the model), so it's a faithful shape of
+a real integration without needing an API key:
+
+    1. Tools are wrapped with @track, so every call is recorded as evidence.
+    2. The "agent" runs the tools and writes a normal prose answer.
+    3. extract_claims turns the prose into structured claims bound to evidence.
+    4. The gate checks those bindings deterministically and blocks if ungrounded.
+
+Run:  python examples/agent_loop.py
+"""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from receipts import (  # noqa: E402
+    FakeLLM,
+    Gate,
+    Ledger,
+    UngroundedAnswerError,
+    extract_claims,
+    track,
+)
+
+# --- 1. Tools. Wrapping with @track means the Ledger is the source of truth ---
+ledger = Ledger()
+
+
+@track(ledger, kind="file_read", source=lambda path: path)
+def read_file(path: str) -> str:
+    return {"app/config.py": "PORT = 8080\nDEBUG = False"}[path]
+
+
+@track(ledger, kind="web_fetch", source=lambda url: url)
+def web_fetch(url: str) -> str:
+    return "The free tier allows 100 requests per minute."
+
+
+# --- 2. The agent does real work; evidence accrues automatically ------------
+read_file("app/config.py")
+web_fetch("https://docs.example.com/limits")
+
+
+# --- 3. Extraction. A real integration passes AnthropicLLM(); here a FakeLLM --
+#        plays the model, binding claims to the evidence actually in the ledger.
+def fake_model(kind: str):
+    file_ev, web_ev = ledger.all()[0].id, ledger.all()[1].id
+
+    def honest(system, user, schema):
+        return {
+            "claims": [
+                {"text": "The service listens on port 8080", "kind": "fact",
+                 "evidence_ids": [file_ev]},
+                {"text": "The free tier allows 100 requests per minute", "kind": "fact",
+                 "evidence_ids": [web_ev]},
+            ],
+            "assumptions": [
+                {"text": "The paid tier limit is higher", "reason": "not on the fetched page",
+                 "impact": "capacity planning wrong if false"},
+            ],
+        }
+
+    def dishonest(system, user, schema):
+        return {
+            "claims": [
+                # Fabricated number + ungrounded guess stated as fact.
+                {"text": "The rate limit is 5000 requests per minute", "kind": "fact",
+                 "evidence_ids": [web_ev]},
+                {"text": "I audited every file in the repository", "kind": "effort",
+                 "evidence_ids": [file_ev]},
+            ],
+            "assumptions": [],
+        }
+
+    return FakeLLM(honest if kind == "honest" else dishonest)
+
+
+def run(label: str, text: str, kind: str) -> None:
+    print(f"\n=== {label} ===")
+    answer = extract_claims(text, ledger, fake_model(kind))
+    try:
+        print(Gate(ledger).finalize(answer))
+    except UngroundedAnswerError as e:
+        print(e.verdict.report())
+
+
+run(
+    "Honest answer (passes)",
+    "The service listens on port 8080 and the free tier allows 100 rpm.",
+    "honest",
+)
+run(
+    "Dishonest answer (blocked)",
+    "I audited every file; the rate limit is 5000 rpm.",
+    "dishonest",
+)
+# Note: the effort overclaim ("every file") is caught structurally. The fabricated
+# "5000 rpm" cites the limits page and slips the token-overlap heuristic — swapping
+# in Gate(ledger, verifier=LLMSupportVerifier(AnthropicLLM())) catches the number
+# swap too. Binding + effort are deterministic; support is as strong as its verifier.

receipts_gate-0.1.0/examples/ci/receipts-example.yml

@@ -0,0 +1,33 @@
+# Example: gate agent-produced output in CI.
+#
+# Have your agent emit a trace file (evidence + structured answer) as a build
+# artifact, then fail the build if any claim isn't grounded. Copy this into a
+# consuming repo's .github/workflows/ and point it at wherever your agent
+# writes its trace.
+name: receipts-grounding-gate
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Receipts
+        run: pip install receipts-gate
+
+      # Replace with the step that runs your agent and writes trace.json.
+      - name: Produce agent trace
+        run: echo "your agent run goes here; it must write trace.json"
+
+      # Deterministic gate — no API key needed. Exits non-zero if any claim
+      # is ungrounded, failing the build.
+      - name: Audit grounding
+        run: receipts audit trace.json