receipts-gate 0.1.0__py3-none-any.whl

receipts/__init__.py

@@ -0,0 +1,70 @@
+"""Receipts — force AI agents to back every claim with evidence, or declare it.
+
+Quick start:
+
+    from receipts import Ledger, Gate, Answer, Claim, Assumption, ClaimKind
+
+    ledger = Ledger()
+    # ... evidence gets recorded as the agent actually does work ...
+    ledger.record("file_read", "config.py", "PORT = 8080")
+
+    gate = Gate(ledger)  # hard gate by default
+    answer = Answer(
+        summary="The service listens on port 8080.",
+        claims=[Claim("The port is 8080", evidence_ids=[...], kind=ClaimKind.FACT)],
+    )
+    print(gate.finalize(answer))  # raises UngroundedAnswerError if not grounded
+"""
+
+from .errors import ReceiptsError, UngroundedAnswerError
+from .extract import extract_claims
+from .gate import Gate, audit, render
+from .instrument import ingest_trace, track
+from .ledger import Ledger
+from .llm import AnthropicLLM, FakeLLM
+from .models import (
+    Answer,
+    Assumption,
+    Claim,
+    ClaimKind,
+    ClaimResult,
+    Evidence,
+    EvidenceKind,
+    Verdict,
+)
+from .trace import load_trace
+from .verify import (
+    HeuristicVerifier,
+    LLMSupportVerifier,
+    NullVerifier,
+    SupportVerifier,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Ledger",
+    "Gate",
+    "audit",
+    "render",
+    "track",
+    "ingest_trace",
+    "load_trace",
+    "extract_claims",
+    "AnthropicLLM",
+    "FakeLLM",
+    "Answer",
+    "Assumption",
+    "Claim",
+    "ClaimKind",
+    "ClaimResult",
+    "Evidence",
+    "EvidenceKind",
+    "Verdict",
+    "HeuristicVerifier",
+    "LLMSupportVerifier",
+    "NullVerifier",
+    "SupportVerifier",
+    "ReceiptsError",
+    "UngroundedAnswerError",
+]

receipts/adapters/__init__.py

@@ -0,0 +1,17 @@
+"""Framework adapters that feed real tool-call traces into a Ledger.
+
+Capture is framework-agnostic at the core (`@track`, `ingest_trace`); these
+adapters map specific ecosystems' trace formats onto the Ledger so you don't have
+to hand-translate. Each is import-light and optional.
+"""
+
+from .anthropic_trace import from_anthropic_messages
+from .langchain import langchain_handler, record_tool_end
+from .openai_trace import from_openai_messages
+
+__all__ = [
+    "from_openai_messages",
+    "from_anthropic_messages",
+    "langchain_handler",
+    "record_tool_end",
+]

receipts/adapters/anthropic_trace.py

@@ -0,0 +1,84 @@
+"""Ingest an Anthropic / Claude Agent SDK conversation into a Ledger.
+
+Works with the Anthropic Messages API conversation shape and the Claude Agent
+SDK's message stream — both express tool use as content blocks: an assistant
+`tool_use` block names the tool, and a later user `tool_result` block carries what
+the tool returned (the observation Receipts treats as evidence).
+
+Blocks may be plain dicts (raw API / JSON transcripts) or SDK objects (attribute
+access); this adapter handles both. Pure Python, no SDK required to run.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..ledger import Ledger
+from .openai_trace import _infer_kind
+
+
+def _get(obj, key, default=None):
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+
+def _content_blocks(message) -> list:
+    content = _get(message, "content", [])
+    if isinstance(content, str):
+        return []  # plain-text turn, no tool blocks
+    return list(content or [])
+
+
+def _result_text(content) -> str:
+    """tool_result content is a string or a list of {type: text, text: ...} blocks."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for b in content:
+            if _get(b, "type") == "text" or _get(b, "text") is not None:
+                parts.append(str(_get(b, "text", "")))
+            else:
+                parts.append(str(b))
+        return "\n".join(p for p in parts if p)
+    return "" if content is None else str(content)
+
+
+def from_anthropic_messages(
+    ledger: Ledger,
+    messages: Iterable,
+    *,
+    name_to_kind=None,
+) -> Ledger:
+    """Record every `tool_result` block in an Anthropic-style conversation.
+
+    `messages` is the list of message dicts/objects (Messages API format, or the
+    Claude Agent SDK message stream). Returns the same ledger for chaining.
+    """
+    messages = list(messages)
+
+    # First pass: map tool_use ids to their tool names (from assistant turns).
+    id_to_name: dict[str, str] = {}
+    for m in messages:
+        for block in _content_blocks(m):
+            if _get(block, "type") == "tool_use":
+                bid = _get(block, "id")
+                name = _get(block, "name")
+                if bid and name:
+                    id_to_name[bid] = name
+
+    # Second pass: record tool_result blocks as evidence.
+    for m in messages:
+        for block in _content_blocks(m):
+            if _get(block, "type") != "tool_result":
+                continue
+            name = id_to_name.get(_get(block, "tool_use_id", ""), "tool")
+            kind = None
+            if name_to_kind is not None:
+                kind = name_to_kind(name)
+            kind = kind or _infer_kind(name)
+            text = _result_text(_get(block, "content", ""))
+            err = bool(_get(block, "is_error", False))
+            ledger.record(kind, name, text, is_error=err)
+    return ledger

receipts/adapters/langchain.py

@@ -0,0 +1,54 @@
+"""LangChain / LangGraph capture: record tool outputs to the Ledger live.
+
+A LangChain callback handler that writes each tool result into the Ledger as it
+happens, so an existing LangChain agent gains evidence capture without changing
+its tool code. `langchain_handler(ledger)` returns a ready handler — pass it in
+`config={"callbacks": [...]}` (or to the agent executor).
+
+The recording logic lives in the plain `record_tool_end` function so it's
+testable without langchain installed; the handler is a thin wrapper around it and
+lazy-imports `langchain_core` only when you actually build one.
+"""
+
+from __future__ import annotations
+
+from ..ledger import Ledger
+from .openai_trace import _infer_kind, _stringify
+
+
+def record_tool_end(ledger: Ledger, name: str, output, *, name_to_kind=None):
+    """Record one finished tool call as evidence. Returns the Evidence record."""
+    kind = None
+    if name_to_kind is not None:
+        kind = name_to_kind(name)
+    kind = kind or _infer_kind(name or "")
+    return ledger.record(kind, name or "tool", _stringify(output))
+
+
+def langchain_handler(ledger: Ledger, *, name_to_kind=None):
+    """Build a LangChain `BaseCallbackHandler` that captures tool results.
+
+    Usage:
+        handler = langchain_handler(ledger)
+        agent.invoke(inputs, config={"callbacks": [handler]})
+    """
+    try:
+        from langchain_core.callbacks import BaseCallbackHandler
+    except ImportError as e:  # pragma: no cover - env-dependent
+        raise ImportError(
+            "langchain_handler needs langchain-core: pip install langchain-core"
+        ) from e
+
+    class ReceiptsCallbackHandler(BaseCallbackHandler):
+        def __init__(self) -> None:
+            super().__init__()
+            self._names: dict = {}
+
+        def on_tool_start(self, serialized, input_str, *, run_id=None, **kwargs):
+            self._names[run_id] = (serialized or {}).get("name")
+
+        def on_tool_end(self, output, *, run_id=None, **kwargs):
+            name = self._names.pop(run_id, None) or kwargs.get("name") or "tool"
+            record_tool_end(ledger, name, output, name_to_kind=name_to_kind)
+
+    return ReceiptsCallbackHandler()

receipts/adapters/openai_trace.py

@@ -0,0 +1,87 @@
+"""Ingest an OpenAI-style chat message trace into a Ledger.
+
+The OpenAI chat-completions message format (`role`/`content`/`tool_calls`/
+`tool_call_id`) is a de-facto standard many agent frameworks emit or can export.
+This adapter walks such a transcript and records each *tool result* as evidence —
+those are the observations the agent actually made, the ground truth Receipts
+checks claims against. Pure-python; no SDK required.
+
+A tool result is a message with `role == "tool"`. We map its tool name to an
+evidence kind via `name_to_kind` (extend as needed); unknown names fall back to
+the generic TOOL_CALL kind.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..ledger import Ledger
+from ..models import EvidenceKind
+
+# Map common tool-name substrings to evidence kinds. First match wins.
+_DEFAULT_KIND_MAP: list[tuple[str, EvidenceKind]] = [
+    ("search", EvidenceKind.WEB_SEARCH),
+    ("fetch", EvidenceKind.WEB_FETCH),
+    ("browse", EvidenceKind.WEB_FETCH),
+    ("read", EvidenceKind.FILE_READ),
+    ("file", EvidenceKind.FILE_READ),
+    ("cat", EvidenceKind.FILE_READ),
+    ("test", EvidenceKind.TEST_RUN),
+    ("pytest", EvidenceKind.TEST_RUN),
+    ("bash", EvidenceKind.COMMAND),
+    ("shell", EvidenceKind.COMMAND),
+    ("exec", EvidenceKind.COMMAND),
+    ("run", EvidenceKind.COMMAND),
+]
+
+
+def _infer_kind(name: str) -> EvidenceKind:
+    low = (name or "").lower()
+    for needle, kind in _DEFAULT_KIND_MAP:
+        if needle in low:
+            return kind
+    return EvidenceKind.TOOL_CALL
+
+
+def from_openai_messages(
+    ledger: Ledger,
+    messages: Iterable[dict],
+    *,
+    name_to_kind=None,
+) -> Ledger:
+    """Record every tool-result message in an OpenAI-style trace as evidence.
+
+    `name_to_kind` optionally overrides the inferred kind: a callable taking the
+    tool name and returning an `EvidenceKind` (or None to fall back to inference).
+    Returns the same ledger for chaining.
+    """
+    # Resolve tool names: a tool message carries tool_call_id; the name lives on
+    # the assistant message's tool_calls. Build that lookup first.
+    id_to_name: dict[str, str] = {}
+    for m in messages if isinstance(messages, list) else (messages := list(messages)):
+        for call in m.get("tool_calls") or []:
+            cid = call.get("id")
+            fn = (call.get("function") or {}).get("name") or call.get("name")
+            if cid and fn:
+                id_to_name[cid] = fn
+
+    for m in messages:
+        if m.get("role") != "tool":
+            continue
+        name = m.get("name") or id_to_name.get(m.get("tool_call_id", ""), "tool")
+        kind = None
+        if name_to_kind is not None:
+            kind = name_to_kind(name)
+        kind = kind or _infer_kind(name)
+        ledger.record(kind, name, _stringify(m.get("content", "")))
+    return ledger
+
+
+def _stringify(value) -> str:
+    if isinstance(value, str):
+        return value
+    if isinstance(value, list):
+        # OpenAI content parts: join any text parts.
+        parts = [p.get("text", "") if isinstance(p, dict) else str(p) for p in value]
+        return "\n".join(p for p in parts if p)
+    return repr(value)

receipts/cli.py

@@ -0,0 +1,100 @@
+"""Command-line auditor: `receipts audit trace.json`.
+
+Exits non-zero when the answer fails the grounding gate, so it drops straight
+into CI as a gate on agent-produced output. Deterministic by default (no network);
+pass --llm to use the LLM support verifier.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .gate import audit
+from .models import ClaimKind, EvidenceKind
+from .trace import load_trace
+from .verify import HeuristicVerifier
+
+_KINDS_HELP = (
+    f"valid evidence kinds: {', '.join(k.value for k in EvidenceKind)}; "
+    f"valid claim kinds: {', '.join(k.value for k in ClaimKind)}"
+)
+
+
+def _fail(args, message: str) -> int:
+    """Uniform CLI error: a JSON object under --json, plain text on stderr otherwise."""
+    if getattr(args, "json", False):
+        print(json.dumps({"ok": False, "error": message}, indent=2))
+    else:
+        print(f"error: {message}", file=sys.stderr)
+    return 2
+
+
+def _cmd_audit(args) -> int:
+    try:
+        with open(args.trace, encoding="utf-8") as f:
+            data = json.load(f)
+    except OSError as e:
+        return _fail(args, f"cannot read trace file: {e}")
+    except json.JSONDecodeError as e:
+        return _fail(args, f"{args.trace} is not valid JSON: {e}")
+
+    if not isinstance(data, dict):
+        return _fail(args, "trace root must be a JSON object with 'evidence' and 'answer'")
+
+    try:
+        ledger, answer = load_trace(data)
+    except (KeyError, TypeError, ValueError) as e:
+        return _fail(args, f"malformed trace: {e} ({_KINDS_HELP})")
+
+    verifier = HeuristicVerifier()
+    if args.llm:
+        from .llm import AnthropicLLM
+        from .verify import LLMSupportVerifier
+
+        verifier = LLMSupportVerifier(AnthropicLLM())
+
+    verdict = audit(answer, ledger, verifier=verifier)
+
+    if args.json:
+        out = {
+            "ok": verdict.ok,
+            "claimed_effort": verdict.claimed_effort,
+            "logged_evidence": verdict.logged_evidence,
+            "failures": [
+                {"claim": r.claim.text, "reasons": r.failures}
+                for r in verdict.failures
+            ],
+            "assumptions": [a.text for a in verdict.assumptions],
+        }
+        print(json.dumps(out, indent=2))
+    else:
+        print(verdict.report())
+
+    return 0 if verdict.ok else 1
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="receipts",
+        description="Force AI agents to back every claim with evidence.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_audit = sub.add_parser("audit", help="Audit a trace file; exit 1 if blocked.")
+    p_audit.add_argument("trace", help="Path to a trace JSON file.")
+    p_audit.add_argument("--json", action="store_true", help="Emit JSON instead of a report.")
+    p_audit.add_argument(
+        "--llm",
+        action="store_true",
+        help="Use the LLM support verifier (needs anthropic + ANTHROPIC_API_KEY).",
+    )
+    p_audit.set_defaults(func=_cmd_audit)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

receipts/errors.py

@@ -0,0 +1,18 @@
+"""Exceptions raised by the hard gate."""
+
+from __future__ import annotations
+
+
+class ReceiptsError(Exception):
+    """Base class."""
+
+
+class UngroundedAnswerError(ReceiptsError):
+    """Raised by Gate.finalize() when an Answer fails verification.
+
+    Carries the full Verdict so callers can show the agent exactly what to fix.
+    """
+
+    def __init__(self, verdict) -> None:  # verdict: Verdict
+        self.verdict = verdict
+        super().__init__(verdict.report())

receipts/extract.py

@@ -0,0 +1,100 @@
+"""Free-text claim extraction.
+
+The adoption unlock: an agent writes a normal prose answer, and Receipts turns it
+into a structured `Answer` (atomic claims, each bound to evidence ids, plus
+declared assumptions) which the gate can then check. The agent doesn't have to
+emit structured claims by hand.
+
+Extraction is LLM-driven and therefore advisory — the *checking* of the extracted
+claims stays deterministic in the gate, so a sloppy extraction surfaces as gate
+failures rather than silently passing. The extractor is told the evidence ids and
+their content so it can bind claims; the gate independently re-verifies every
+binding it produces.
+"""
+
+from __future__ import annotations
+
+from .ledger import Ledger
+from .models import Answer, Assumption, Claim, ClaimKind
+
+_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "claims": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "text": {"type": "string"},
+                    "kind": {"type": "string", "enum": ["fact", "effort", "conclusion"]},
+                    "evidence_ids": {"type": "array", "items": {"type": "string"}},
+                },
+                "required": ["text", "kind", "evidence_ids"],
+                "additionalProperties": False,
+            },
+        },
+        "assumptions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "text": {"type": "string"},
+                    "reason": {"type": "string"},
+                    "impact": {"type": "string"},
+                },
+                "required": ["text", "reason", "impact"],
+                "additionalProperties": False,
+            },
+        },
+    },
+    "required": ["claims", "assumptions"],
+    "additionalProperties": False,
+}
+
+_SYSTEM = (
+    "You convert an AI agent's free-text answer into structured, checkable claims.\n"
+    "Rules:\n"
+    "1. Break the answer into atomic claims — one verifiable assertion each.\n"
+    "2. Classify each: 'fact' (a stated fact), 'effort' (a claim about work the "
+    "agent did, e.g. 'I searched the docs'), or 'conclusion' (an inference).\n"
+    "3. For each claim, cite the evidence ids (from the EVIDENCE list) that back "
+    "it. If nothing in the evidence supports a claim, cite NOTHING for it — do "
+    "not invent ids.\n"
+    "4. If the answer relies on something not backed by evidence, record it as an "
+    "assumption with a reason and the impact if it's wrong, instead of forcing it "
+    "into a claim.\n"
+    "Only use evidence ids that appear in the EVIDENCE list verbatim."
+)
+
+
+def extract_claims(text: str, ledger: Ledger, llm) -> Answer:
+    """Turn a free-text answer into a structured `Answer` ready for the gate.
+
+    `llm` is a `receipts.llm.LLM`. The returned Answer keeps `text` as its summary;
+    run it through `Gate.finalize()` / `audit()` to actually check the bindings.
+    """
+    ev_list = "\n".join(
+        f"- {e.id} | {e.kind.value} | {e.source}\n    {_snippet(e.content)}"
+        for e in ledger.all()
+    )
+    user = f"EVIDENCE:\n{ev_list or '(none)'}\n\nANSWER:\n{text}"
+    result = llm.complete_json(_SYSTEM, user, _SCHEMA)
+
+    claims = [
+        Claim(
+            text=c["text"],
+            kind=ClaimKind(c.get("kind", "fact")),
+            evidence_ids=list(c.get("evidence_ids", [])),
+        )
+        for c in result.get("claims", [])
+    ]
+    assumptions = [
+        Assumption(text=a["text"], reason=a.get("reason", ""), impact=a.get("impact", ""))
+        for a in result.get("assumptions", [])
+    ]
+    return Answer(claims=claims, assumptions=assumptions, summary=text)
+
+
+def _snippet(content: str, limit: int = 300) -> str:
+    content = " ".join(content.split())
+    return content if len(content) <= limit else content[:limit] + "..."