auditable 0.1.1__tar.gz → 0.2.0__tar.gz

auditable-0.1.1/README.md → auditable-0.2.0/PKG-INFO

@@ -1,8 +1,55 @@
+Metadata-Version: 2.4
+Name: auditable
+Version: 0.2.0
+Summary: An open-source system of record for AI-agent decisions: it captures what each decision relied on, replays it against live state, and rolls back the committed action when it no longer holds.
+Project-URL: Homepage, https://github.com/yzhao062/auditable
+Project-URL: Repository, https://github.com/yzhao062/auditable
+Project-URL: Issues, https://github.com/yzhao062/auditable/issues
+Author-email: Yue Zhao <yzhao010@usc.edu>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent,agent-reliability,ai-agents,ai-risk,ai-safety,anomaly-detection,audit,auditing,compliance,langchain,langgraph,llm,mcp,model-context-protocol,observability,replay,trustworthy-ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Provides-Extra: anomaly
+Requires-Dist: pyod>=1.1.0; extra == 'anomaly'
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pyod>=1.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: networkx>=3.0; extra == 'graph'
+Provides-Extra: langchain
+Requires-Dist: langchain-core<2,>=0.3.0; extra == 'langchain'
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=1.0; (python_version >= '3.10') and extra == 'langgraph'
+Requires-Dist: networkx>=3.0; extra == 'langgraph'
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == 'llm'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.28.1; (python_version >= '3.10') and extra == 'mcp'
+Provides-Extra: report
+Requires-Dist: fpdf2>=2.7; extra == 'report'
+Requires-Dist: matplotlib>=3.5; extra == 'report'
+Requires-Dist: networkx>=3.0; extra == 'report'
+Description-Content-Type: text/markdown
+
 <div align="center">
 
 # auditable
 
-**Audit any agent decision across its past, present, and future, on one typed graph.**
+**`auditable` is an open-source system of record for AI-agent decisions: it captures what each decision relied on, replays it against live state, and rolls back the committed action when it no longer holds.**
 
 *Your logs show what the agent did. `auditable` shows what it relied on, replays it under live state, and rolls it back when it no longer holds.*
 
@@ -82,9 +129,11 @@ pip install "auditable[langgraph]"
 python examples/example_langgraph_capture.py     # a real LangGraph run -> observed=100%, keystone named
 ```
 
+The same wrapped builder also yields **replayable** records, so the LIVE pillar runs on the captured run, not a hand-built dict. `builder.to_records(decisions={"approve": "vendor_payment"})` lowers a marked decision node into a `DecisionRecord` carrying the state it relied on, and `replay(record, live_state=...)` re-decides it under state that is live now and routes a rollback. See [`example_langgraph_live_replay.py`](examples/example_langgraph_live_replay.py): one real LangGraph run, captured, ranked (POST), then replayed and reversed under a drifted budget (LIVE).
+
 Want a real model in the loop? [`example_langgraph_llm_agent.py`](examples/example_langgraph_llm_agent.py) runs the same capture with live LLM nodes against any OpenAI-compatible endpoint (a plain OpenAI key, a gateway, or a local vLLM or Ollama server). The captured edges are identical, because the capture sees the state channels a node read and wrote, not the model call inside it.
 
-Not on LangGraph? The framework-agnostic `TouchRecorder` captures the same observed edges from any loop (a raw OpenAI or Anthropic agent, your own scheduler) by declaring each step's `reads()` and `writes()`. See [`examples/example_touch_capture.py`](examples/example_touch_capture.py). **Roadmap:** LangChain, CrewAI, MCP, and OpenTelemetry.
+Not on LangGraph? A one-line callback captures any LangChain runnable (`auditable.integrations.langchain`), an in-place `instrument` records every tool call at an MCP server boundary (`auditable.integrations.mcp`), and the framework-agnostic `TouchRecorder` captures the same observed edges from any loop (a raw OpenAI or Anthropic agent, your own scheduler) by declaring each step's `reads()` and `writes()`. See [`examples/example_touch_capture.py`](examples/example_touch_capture.py). **Roadmap:** CrewAI and OpenTelemetry.
 
 ## Examples and Integrations
 
@@ -94,13 +143,17 @@ Point `auditable` at a scenario and it builds the same typed graph. Each row lin
 |---|---|---|---|
 | Capture a real LangGraph agent | LIVE → POST | a live `StateGraph` run (`instrument`) | [`example_langgraph_capture.py`](examples/example_langgraph_capture.py) |
 | Capture a real LLM agent (live model) | LIVE → POST | a model-driven `StateGraph` run (`instrument` + OpenAI-compatible) | [`example_langgraph_llm_agent.py`](examples/example_langgraph_llm_agent.py) |
+| Capture a real LangChain runnable | LIVE → POST | a callback on any runnable (`LangChainCallbackHandler`) | [`example_langchain_capture.py`](examples/example_langchain_capture.py) |
 | Capture any tool loop by hand | LIVE → POST | declared resource touches (`TouchRecorder`) | [`example_touch_capture.py`](examples/example_touch_capture.py) |
+| Capture MCP tool traffic at the server boundary | LIVE → POST | an instrumented FastMCP server (`instrument`) | [`example_mcp_capture.py`](examples/example_mcp_capture.py) |
+| Capture a LangGraph agent, then replay and reverse it | LIVE → POST | a live `StateGraph` run lowered to replayable records (`instrument` + `to_records`) | [`example_langgraph_live_replay.py`](examples/example_langgraph_live_replay.py) |
 | Lint a declared plan before deploy | PRE | a framework-agnostic plan dict (`declared_plan_v1`) | [`example_pre_lint_plan.py`](examples/example_pre_lint_plan.py) |
 | Recover a payment as the budget drifts | LIVE | a decision captured live (`audit` + `replay`) | [`example_live_replay.py`](examples/example_live_replay.py) |
+| Monitor a run as it streams, name the keystone live | LIVE | a run scored prefix by prefix (`LiveSession`) | [`example_live_monitor.py`](examples/example_live_monitor.py) |
 | Rank a tau-bench run, name the keystone | POST | a tau-bench trajectory (`tau_bench_prior_db_reads_v1`) | [`example_post_rank_run.py`](examples/example_post_rank_run.py) |
 | Walk one payment through every pillar | PRE, LIVE, POST | the full lifecycle (`own_record_v1` for POST) | [`example_end_to_end.py`](examples/example_end_to_end.py) |
 
-The first three rows capture a real run; see [Plug In Your Agent](#plug-in-your-agent) for the two-line setup. **Roadmap:** LangChain, CrewAI, MCP, and OpenTelemetry.
+The first six rows capture a real run; see [Plug In Your Agent](#plug-in-your-agent) for the two-line setup. **Roadmap:** CrewAI and OpenTelemetry.
 
 ## The Lifecycle
 
@@ -122,9 +175,11 @@ The core is dependency-free and torch-free. Structural-graph analysis (`analyze_
 
 ```bash
 pip install "auditable[graph]"
+pip install "auditable[anomaly]"
 ```
 
-The LIVE example runs on the core install alone.
+The graph extra adds NetworkX. The anomaly extra adds the fitted `DataAuditor` path
+through PyOD; freshness fallback and the LIVE example run on the core install alone.
 
 Docs: https://auditable-ai.readthedocs.io/
 
@@ -250,7 +305,12 @@ These standalone auditors are inputs to the record, not the headline. The compos
 
 **What ships today.** The full signed chain, replay under live state, executed recovery through a rail-neutral gate, two sinks (in-memory and append-only JSONL), the POST `analyze_run` ranking, the PRE `analyze_plan` lints plus preflight coverage report, and real-run capture into observed dependency edges (LangGraph via `instrument`, any loop via `TouchRecorder`).
 
-The release does **not** yet claim a learned data-anomaly method, a calibrated model-trust score, calibrated cross-layer risk, or live incremental scoring. The POST structural score is an uncalibrated ranking; the compound report is a transparent, explicitly uncalibrated debug bundle. Everything beyond this list is on the [roadmap](#roadmap).
+The fitted data-anomaly path ships as an unpromoted module API, and `LiveSession`
+prefix scoring ships. The release does **not** yet claim benchmark-grade detector
+evidence, a calibrated model-trust score, or calibrated cross-layer risk. The POST
+structural score is an uncalibrated ranking; the compound report is a transparent,
+explicitly uncalibrated debug bundle. Calibrated compound scoring remains on the
+[roadmap](#roadmap).
 
 </details>
 
@@ -261,17 +321,22 @@ The release does **not** yet claim a learned data-anomaly method, a calibrated m
 
 <br>
 
-Shipping today: the full capture, replay, and recover chain; PRE plan lints; POST run ranking; signed, hash-chained records; two sinks. Next:
+Shipping today: the full capture, replay, and recover chain; PRE plan lints; POST run ranking; `LiveSession` prefix scoring; signed, hash-chained records; two sinks. The fitted PyOD detector over dependency snapshots also ships as an unpromoted module API, with freshness as the fallback; promotion waits for benchmark-grade evidence. Next:
 
-- **Smarter drift detection.** Learn what healthy dependency state looks like and flag anomalies, not just staleness (PyOD backend, with freshness as the fallback).
-- **One calibrated risk score.** Combine the data, model, and action signals into a single calibrated score, with the model treated as a first-class node in the graph.
-- **Live scoring.** Score decisions on the prefix graph as the agent runs, not only after the run completes. (Capturing what each step read and wrote already ships for LangGraph and the `TouchRecorder`.)
+- **One calibrated compound score.** Combine the data, model, and action signals into a single calibrated score, with the model treated as a first-class node in the graph.
 - **Automatic fixes.** Refresh stale data, quarantine bad inputs, fall back to a safer model, or require human sign-off.
 - **Built-in CI checks.** A table-stakes OWASP-Agentic and CWE rule floor for continuous integration.
-- **Integrations (1.0).** LangGraph capture ships now (`instrument`); next are one-line hooks for LangChain and CrewAI, an MCP server, export to OpenTelemetry and LangSmith, downloadable evidence bundles, and a stable public API.
+- **Integrations (1.0).** LangGraph capture (`instrument`), the LangChain callback, and MCP tool-boundary capture ship now; next are a CrewAI hook, export to OpenTelemetry and LangSmith, downloadable evidence bundles, and a stable public API.
 
 </details>
 
+## Related Projects
+
+`auditable` is part of a small family of open agent-reliability projects:
+
+- **[awesome-auditable-ai](https://github.com/yzhao062/awesome-auditable-ai)** — a curated reading list on AI agent reliability and auditing.
+- **[GRADE](https://arxiv.org/abs/2606.22741)** — the research behind the typed two-layer graph this library is built on (also in [References](#references)).
+
 ## References
 
 <details>

auditable-0.1.1/PKG-INFO → auditable-0.2.0/README.md

@@ -1,51 +1,8 @@
-Metadata-Version: 2.4
-Name: auditable
-Version: 0.1.1
-Summary: Audit any agent decision across its past, present, and future, on one typed graph.
-Project-URL: Homepage, https://github.com/yzhao062/auditable
-Project-URL: Repository, https://github.com/yzhao062/auditable
-Project-URL: Issues, https://github.com/yzhao062/auditable/issues
-Author-email: Yue Zhao <yzhao010@usc.edu>
-License-Expression: Apache-2.0
-License-File: LICENSE
-Keywords: agent,agent-reliability,ai-agents,ai-risk,ai-safety,anomaly-detection,audit,auditing,compliance,llm,observability,replay,trustworthy-ai
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-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 :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Python: >=3.9
-Provides-Extra: dev
-Requires-Dist: build>=1.0; extra == 'dev'
-Requires-Dist: pyod>=1.1.0; extra == 'dev'
-Requires-Dist: pytest>=7.0; extra == 'dev'
-Requires-Dist: twine>=5.0; extra == 'dev'
-Provides-Extra: graph
-Requires-Dist: networkx>=3.0; extra == 'graph'
-Provides-Extra: langchain
-Requires-Dist: langchain-core>=0.3.0; extra == 'langchain'
-Provides-Extra: langgraph
-Requires-Dist: langgraph>=1.0; (python_version >= '3.10') and extra == 'langgraph'
-Requires-Dist: networkx>=3.0; extra == 'langgraph'
-Provides-Extra: llm
-Requires-Dist: openai>=1.0; extra == 'llm'
-Provides-Extra: report
-Requires-Dist: fpdf2>=2.7; extra == 'report'
-Requires-Dist: matplotlib>=3.5; extra == 'report'
-Requires-Dist: networkx>=3.0; extra == 'report'
-Description-Content-Type: text/markdown
-
 <div align="center">
 
 # auditable
 
-**Audit any agent decision across its past, present, and future, on one typed graph.**
+**`auditable` is an open-source system of record for AI-agent decisions: it captures what each decision relied on, replays it against live state, and rolls back the committed action when it no longer holds.**
 
 *Your logs show what the agent did. `auditable` shows what it relied on, replays it under live state, and rolls it back when it no longer holds.*
 
@@ -125,9 +82,11 @@ pip install "auditable[langgraph]"
 python examples/example_langgraph_capture.py     # a real LangGraph run -> observed=100%, keystone named
 ```
 
+The same wrapped builder also yields **replayable** records, so the LIVE pillar runs on the captured run, not a hand-built dict. `builder.to_records(decisions={"approve": "vendor_payment"})` lowers a marked decision node into a `DecisionRecord` carrying the state it relied on, and `replay(record, live_state=...)` re-decides it under state that is live now and routes a rollback. See [`example_langgraph_live_replay.py`](examples/example_langgraph_live_replay.py): one real LangGraph run, captured, ranked (POST), then replayed and reversed under a drifted budget (LIVE).
+
 Want a real model in the loop? [`example_langgraph_llm_agent.py`](examples/example_langgraph_llm_agent.py) runs the same capture with live LLM nodes against any OpenAI-compatible endpoint (a plain OpenAI key, a gateway, or a local vLLM or Ollama server). The captured edges are identical, because the capture sees the state channels a node read and wrote, not the model call inside it.
 
-Not on LangGraph? The framework-agnostic `TouchRecorder` captures the same observed edges from any loop (a raw OpenAI or Anthropic agent, your own scheduler) by declaring each step's `reads()` and `writes()`. See [`examples/example_touch_capture.py`](examples/example_touch_capture.py). **Roadmap:** LangChain, CrewAI, MCP, and OpenTelemetry.
+Not on LangGraph? A one-line callback captures any LangChain runnable (`auditable.integrations.langchain`), an in-place `instrument` records every tool call at an MCP server boundary (`auditable.integrations.mcp`), and the framework-agnostic `TouchRecorder` captures the same observed edges from any loop (a raw OpenAI or Anthropic agent, your own scheduler) by declaring each step's `reads()` and `writes()`. See [`examples/example_touch_capture.py`](examples/example_touch_capture.py). **Roadmap:** CrewAI and OpenTelemetry.
 
 ## Examples and Integrations
 
@@ -137,13 +96,17 @@ Point `auditable` at a scenario and it builds the same typed graph. Each row lin
 |---|---|---|---|
 | Capture a real LangGraph agent | LIVE → POST | a live `StateGraph` run (`instrument`) | [`example_langgraph_capture.py`](examples/example_langgraph_capture.py) |
 | Capture a real LLM agent (live model) | LIVE → POST | a model-driven `StateGraph` run (`instrument` + OpenAI-compatible) | [`example_langgraph_llm_agent.py`](examples/example_langgraph_llm_agent.py) |
+| Capture a real LangChain runnable | LIVE → POST | a callback on any runnable (`LangChainCallbackHandler`) | [`example_langchain_capture.py`](examples/example_langchain_capture.py) |
 | Capture any tool loop by hand | LIVE → POST | declared resource touches (`TouchRecorder`) | [`example_touch_capture.py`](examples/example_touch_capture.py) |
+| Capture MCP tool traffic at the server boundary | LIVE → POST | an instrumented FastMCP server (`instrument`) | [`example_mcp_capture.py`](examples/example_mcp_capture.py) |
+| Capture a LangGraph agent, then replay and reverse it | LIVE → POST | a live `StateGraph` run lowered to replayable records (`instrument` + `to_records`) | [`example_langgraph_live_replay.py`](examples/example_langgraph_live_replay.py) |
 | Lint a declared plan before deploy | PRE | a framework-agnostic plan dict (`declared_plan_v1`) | [`example_pre_lint_plan.py`](examples/example_pre_lint_plan.py) |
 | Recover a payment as the budget drifts | LIVE | a decision captured live (`audit` + `replay`) | [`example_live_replay.py`](examples/example_live_replay.py) |
+| Monitor a run as it streams, name the keystone live | LIVE | a run scored prefix by prefix (`LiveSession`) | [`example_live_monitor.py`](examples/example_live_monitor.py) |
 | Rank a tau-bench run, name the keystone | POST | a tau-bench trajectory (`tau_bench_prior_db_reads_v1`) | [`example_post_rank_run.py`](examples/example_post_rank_run.py) |
 | Walk one payment through every pillar | PRE, LIVE, POST | the full lifecycle (`own_record_v1` for POST) | [`example_end_to_end.py`](examples/example_end_to_end.py) |
 
-The first three rows capture a real run; see [Plug In Your Agent](#plug-in-your-agent) for the two-line setup. **Roadmap:** LangChain, CrewAI, MCP, and OpenTelemetry.
+The first six rows capture a real run; see [Plug In Your Agent](#plug-in-your-agent) for the two-line setup. **Roadmap:** CrewAI and OpenTelemetry.
 
 ## The Lifecycle
 
@@ -165,9 +128,11 @@ The core is dependency-free and torch-free. Structural-graph analysis (`analyze_
 
 ```bash
 pip install "auditable[graph]"
+pip install "auditable[anomaly]"
 ```
 
-The LIVE example runs on the core install alone.
+The graph extra adds NetworkX. The anomaly extra adds the fitted `DataAuditor` path
+through PyOD; freshness fallback and the LIVE example run on the core install alone.
 
 Docs: https://auditable-ai.readthedocs.io/
 
@@ -293,7 +258,12 @@ These standalone auditors are inputs to the record, not the headline. The compos
 
 **What ships today.** The full signed chain, replay under live state, executed recovery through a rail-neutral gate, two sinks (in-memory and append-only JSONL), the POST `analyze_run` ranking, the PRE `analyze_plan` lints plus preflight coverage report, and real-run capture into observed dependency edges (LangGraph via `instrument`, any loop via `TouchRecorder`).
 
-The release does **not** yet claim a learned data-anomaly method, a calibrated model-trust score, calibrated cross-layer risk, or live incremental scoring. The POST structural score is an uncalibrated ranking; the compound report is a transparent, explicitly uncalibrated debug bundle. Everything beyond this list is on the [roadmap](#roadmap).
+The fitted data-anomaly path ships as an unpromoted module API, and `LiveSession`
+prefix scoring ships. The release does **not** yet claim benchmark-grade detector
+evidence, a calibrated model-trust score, or calibrated cross-layer risk. The POST
+structural score is an uncalibrated ranking; the compound report is a transparent,
+explicitly uncalibrated debug bundle. Calibrated compound scoring remains on the
+[roadmap](#roadmap).
 
 </details>
 
@@ -304,17 +274,22 @@ The release does **not** yet claim a learned data-anomaly method, a calibrated m
 
 <br>
 
-Shipping today: the full capture, replay, and recover chain; PRE plan lints; POST run ranking; signed, hash-chained records; two sinks. Next:
+Shipping today: the full capture, replay, and recover chain; PRE plan lints; POST run ranking; `LiveSession` prefix scoring; signed, hash-chained records; two sinks. The fitted PyOD detector over dependency snapshots also ships as an unpromoted module API, with freshness as the fallback; promotion waits for benchmark-grade evidence. Next:
 
-- **Smarter drift detection.** Learn what healthy dependency state looks like and flag anomalies, not just staleness (PyOD backend, with freshness as the fallback).
-- **One calibrated risk score.** Combine the data, model, and action signals into a single calibrated score, with the model treated as a first-class node in the graph.
-- **Live scoring.** Score decisions on the prefix graph as the agent runs, not only after the run completes. (Capturing what each step read and wrote already ships for LangGraph and the `TouchRecorder`.)
+- **One calibrated compound score.** Combine the data, model, and action signals into a single calibrated score, with the model treated as a first-class node in the graph.
 - **Automatic fixes.** Refresh stale data, quarantine bad inputs, fall back to a safer model, or require human sign-off.
 - **Built-in CI checks.** A table-stakes OWASP-Agentic and CWE rule floor for continuous integration.
-- **Integrations (1.0).** LangGraph capture ships now (`instrument`); next are one-line hooks for LangChain and CrewAI, an MCP server, export to OpenTelemetry and LangSmith, downloadable evidence bundles, and a stable public API.
+- **Integrations (1.0).** LangGraph capture (`instrument`), the LangChain callback, and MCP tool-boundary capture ship now; next are a CrewAI hook, export to OpenTelemetry and LangSmith, downloadable evidence bundles, and a stable public API.
 
 </details>
 
+## Related Projects
+
+`auditable` is part of a small family of open agent-reliability projects:
+
+- **[awesome-auditable-ai](https://github.com/yzhao062/awesome-auditable-ai)** — a curated reading list on AI agent reliability and auditing.
+- **[GRADE](https://arxiv.org/abs/2606.22741)** — the research behind the typed two-layer graph this library is built on (also in [References](#references)).
+
 ## References
 
 <details>

{auditable-0.1.1 → auditable-0.2.0}/examples/README.md

@@ -21,16 +21,23 @@ the langgraph extra):
 pip install "auditable[graph]"
 pip install "auditable[langgraph]"       # for example_langgraph_capture.py
 pip install "auditable[langgraph,llm]"   # for example_langgraph_llm_agent.py (a real model; needs an OpenAI-compatible key)
+pip install "auditable[graph,langchain]" # for example_langchain_capture.py
+pip install "auditable[graph,mcp]"       # for example_mcp_capture.py (Python >= 3.10)
 ```
 
 | Pillar | Example | When it runs | Benchmark number |
 |--------|---------|--------------|------------------|
 | PRE | `example_pre_lint_plan.py` | Design time, before any step executes | None (capability demo) |
 | LIVE | `example_live_replay.py` | At decision time, on a committed action | None (capability demo) |
+| LIVE | `example_live_monitor.py` | While a run streams, before it finishes | None (capability demo) |
 | POST | `example_post_rank_run.py` | After a run finishes | GRADE corpus results (see below) |
 | Capture | `example_langgraph_capture.py` | Capture a real LangGraph run, then rank it | None (capability demo) |
 | Capture | `example_langgraph_llm_agent.py` | Capture a real LLM-driven LangGraph run, then rank it | None (capability demo) |
+| Capture | `example_langchain_capture.py` | Capture a real LangChain runnable, then rank it | None (capability demo) |
+| Capture + LIVE | `example_langgraph_live_replay.py` | Capture a real LangGraph run, then replay and reverse its decision under drift | None (capability demo) |
+| Capture + Data | `example_state_anomaly.py` | Capture clean state history, fit from it, then score synthetic faults | None (concept demo) |
 | Capture | `example_touch_capture.py` | Capture any tool loop by hand, then rank it | None (capability demo) |
+| Capture | `example_mcp_capture.py` | Capture MCP tool traffic at the server boundary (ops-side mount) into an honest zero-coverage report | None (capability demo) |
 
 ## PRE: Lint a Declared Plan Before Deploy
 
@@ -81,6 +88,29 @@ Run it:
 python examples/example_live_replay.py
 ```
 
+## LIVE: Monitor a Run as It Streams
+
+`example_live_monitor.py` is the other LIVE capability: a running structural score while
+the run is still going. Where `example_live_replay.py` re-decides one committed action,
+`LiveSession` watches the whole run grow. Feed each step as it happens
+(`live.observe(step)`) and the running report names the keystone and its blast share over
+the run seen so far, marked `completeness=prefix`, so a caller can flag, gate, or
+checkpoint a high-blast step before the run ends. It is the same structural kernel as
+POST, run on a growing graph.
+
+The example replays the retail trajectory one step at a time so the score change is
+visible: the first read carries no blast when it happens, becomes the keystone once the
+first write lands on it, and its blast share then moves as later steps arrive. That
+movement is the honest part. A prefix score is a live triage and gating signal, not a
+validated early-warning probability; the blast structure can resolve late, so the keystone
+may shift. This is a capability demo with NO benchmark percentage.
+
+Run it:
+
+```
+python examples/example_live_monitor.py
+```
+
 ## POST: Rank a Finished Run and Name the Keystone
 
 `example_post_rank_run.py` reads a run after it completes, builds one typed
@@ -144,10 +174,35 @@ a pure function or a frontier model, which is the point the example makes. It re
 plain OpenAI key or any compatible gateway or local server, and prints a notice and
 exits cleanly when no key is set. It needs `pip install "auditable[langgraph,llm]"`.
 
+`example_langgraph_live_replay.py` carries one real LangGraph run through both
+pillars. The same wrapped builder that yields the POST ranking also lowers the
+marked decision node into a replayable `DecisionRecord`. `to_records` takes the
+budget the approval relied on into the snapshot, and `action_args` / `action_costs`
+lift the recipient and the real payment cost onto the action itself, so the lowered
+record is the executable payment rather than a state-only stub:
+
+```python
+record = builder.to_records(
+    decisions={"approve": "vendor_payment"},
+    action_args={"approve": {"recipient": "recipient"}},
+    action_costs={"approve": "amount"},
+)[0]
+```
+
+After capture, the example lowers the live budget below the approved amount (fault
+injection, a controlled post-capture change, not drift the corpus supplied) and
+`replay` re-decides on the live state with a cost-based policy: the action's cost
+exceeds the budget that is live now, so it routes a `ROLLBACK` that the `ActionGate`
+executes through a reference ledger. It needs `pip install "auditable[langgraph]"`.
+It is a capability demo on one run, not the comparative replay-versus-baseline
+experiment.
+
 `example_touch_capture.py` does the same for a plain tool loop with no framework,
 using the generic `TouchRecorder`: each step declares its `reads()` and `writes()`
-and the same matcher produces the observed edges. This is the framework-agnostic
-path for a raw OpenAI or Anthropic loop, or any scheduler.
+and the same matcher produces the observed edges. The recorder also carries the
+relied-on values (`reads(..., value=...)`) and a `decides(...)` action, so
+`rec.to_records()` lowers a consequential step into the same replayable record. This
+is the framework-agnostic path for a raw OpenAI or Anthropic loop, or any scheduler.
 
 Both are capability demos: the keystone ranking is a triage signal, not a
 calibrated probability, and the OBSERVED grade is an observed touch match, not a

auditable-0.2.0/examples/example_langchain_capture.py

@@ -0,0 +1,100 @@
+"""Plug in a real LangChain runnable: capture its run into the typed decision graph.
+
+What this shows, in plain terms: you attach one `auditable` callback handler to
+an actual LangChain runnable you already built, run it as usual, and get back the
+typed two-layer decision graph for that run. Chain/runnable and model callbacks
+become decision steps, tool callbacks become tool-call steps, and `analyze_run`
+ranks the run and names the keystone, exactly as the POST pillar does for corpus
+traces.
+
+This is a real-agent capture path: no hand-written plan dict, no corpus fixture,
+no network, and no API key. The only change to your runnable call is the callback,
+followed by one analysis line:
+
+    handler = LangChainCallbackHandler()                         # 1) make once
+    chain.invoke(request, config={"callbacks": [handler]})       # 2) attach
+    report = analyze_run(handler, adapter=handler)               # 3) analyze
+
+The scenario is a small payment approver. `fetch_budget` prepares the amount and
+budget, the `approve_payment` tool decides whether the payment fits, and
+`record_ledger` records the result. LangChain's RunnableSequence callback tags
+declare both handoffs, and the adjacent output/input payload digests match, so
+those two State-A value-flow edges are graded OBSERVED.
+
+Honesty holds in the output. Callbacks expose State A -- runnable/model reasoning
+and tool flow -- but not State B, the live version or contents of the external
+systems behind a tool. This example therefore makes no observed claim about an
+account database; its OBSERVED edges mean exact callback-level value handoffs,
+not external-state reads or precise causality. The score is a triage ranking, not
+a calibrated probability. The corpus-scale GRADE numbers (arXiv:2606.22741) are
+not produced here; this is a capability demo on one offline run.
+
+Needs the graph + langchain extras:  pip install "auditable[graph,langchain]"
+Run:  python examples/example_langchain_capture.py
+"""
+try:
+    from langchain_core.runnables import RunnableLambda
+    from langchain_core.tools import tool
+except ImportError:
+    print(
+        'example skipped: install langchain-core with pip install "auditable[graph,langchain]"'
+    )
+    raise SystemExit(0)
+
+from auditable import analyze_run
+from auditable.integrations.langchain import LangChainCallbackHandler
+
+
+def fetch_budget(request):
+    """Prepare the payment and the illustrative budget it will be checked against."""
+    return {"amount": request["amount"], "budget": 5_000}
+
+
+@tool
+def approve_payment(amount: int, budget: int) -> bool:
+    """Approve a payment only when it fits within the supplied budget."""
+    return amount <= budget
+
+
+def record_ledger(approved):
+    """Record the tool's approval result."""
+    return {"approved": approved, "paid": approved}
+
+
+def main():
+    chain = (
+        RunnableLambda(fetch_budget, name="fetch_budget")
+        | approve_payment
+        | RunnableLambda(record_ledger, name="record_ledger")
+    ).with_config(run_name="payment_chain")
+
+    handler = LangChainCallbackHandler()
+    final = chain.invoke({"amount": 4_200}, config={"callbacks": [handler]})
+    print(f"agent result: approved={final['approved']}, paid={final['paid']}\n")
+
+    # One public call: the callback handler is its own source and adapter.
+    report = analyze_run(handler, adapter=handler)
+    print(report)
+
+    print("\nDependency edges captured from the live run:")
+    steps = {step.idx: step for step in handler.steps()}
+    for step in steps.values():
+        for edge in step.deps:
+            source = steps[edge.src_idx]
+            print(
+                f"  {step.agent} -> {source.agent} "
+                f"({edge.grade.value}, {edge.evidence['relation']})"
+            )
+
+    keystone = report.keystone
+    if keystone is not None:
+        print(
+            f"\nKeystone: step {keystone.idx} "
+            f"({keystone.node_attrs.get('runnable') or keystone.label}) -- "
+            "the approval and ledger result both rest on this captured handoff, "
+            "so it is the first step to review."
+        )
+
+
+if __name__ == "__main__":
+    main()

auditable-0.2.0/examples/example_langgraph_live_replay.py

@@ -0,0 +1,154 @@
+"""Capture a real LangGraph agent, then replay and reverse its decision under drift.
+
+This joins the two halves auditable shipped separately. ``example_langgraph_capture.py``
+captures a real LangGraph run for POST analysis (observed dependency edges). This
+example does that AND lowers the captured decision into a replayable record, so the
+LIVE pillar (``replay`` + routed recovery) runs on a real captured agent rather than
+a hand-built dict. Wrap once, get both:
+
+    builder = instrument(StateGraph(State))   # 1) wrap; build / compile / invoke normally
+    report = analyze_run(builder, adapter=builder)        # POST: rank the run, name the keystone
+    records = builder.to_records(                          # LIVE: replayable records
+        decisions={"approve": "vendor_payment"},
+        action_args={"approve": {"recipient": "recipient"}},  # action payload from captured fields
+        action_costs={"approve": "amount"},                   # action cost from the captured amount
+    )
+
+The scenario is a payment approver: ``fetch_budget`` reads the account budget,
+``approve`` decides a vendor payment against it, and ``record_ledger`` rests on the
+approval. The agent is real (a LangGraph ``StateGraph`` of plain function nodes); the
+relied-on budget and the decision are captured from the run, not hand-written.
+
+The drift is fault injection, stated plainly: after the run is captured, we lower the
+live budget below the approved amount and ``replay`` re-decides on that live state.
+This is a controlled post-capture change, not a fault the corpus supplied (real agent
+corpora carry no intra-run state drift). It is a capability demo on one run, not the
+comparative replay-versus-baseline experiment, which is not shown here. No API key, no
+network.
+
+Needs:  pip install "auditable[langgraph]"
+Run:    python examples/example_langgraph_live_replay.py
+"""
+from typing import TypedDict
+
+from auditable import Action, ActionGate, ReferenceLedger, analyze_run, replay
+from auditable.integrations.langgraph import instrument
+
+try:
+    from langgraph.graph import END, START, StateGraph
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise SystemExit('This example needs langgraph: pip install "auditable[langgraph]"') from exc
+
+
+class PaymentState(TypedDict):
+    invoice: str
+    recipient: str
+    amount: int
+    budget: int
+    allow_list: list
+    approved: bool
+    recorded: bool
+
+
+def budget_policy(state, action):
+    """Re-decide the payment: the action's recipient must be allow-listed, and the action's
+    cost must fit the budget that is live now. The recipient and cost ride on the captured
+    action (``to_records(action_args=..., action_costs=...)``); the allow-list and budget come
+    from the dependency state. A cost-based check like this is why the lowered action must
+    carry the real cost, not ``0``."""
+    recipient = action.arguments.get("recipient")
+    allow_list = state.get("allow_list", [])
+    budget = state.get("budget", 0)
+    if recipient not in allow_list:
+        return False, f"recipient {recipient!r} not allow-listed"
+    if action.cost > budget:
+        return False, f"payment ${action.cost:,.0f} exceeds budget ${budget:,.0f}"
+    return True, f"payment ${action.cost:,.0f} within budget ${budget:,.0f}"
+
+
+def build_agent():
+    """A real LangGraph payment approver of plain function nodes, instrumented once."""
+    builder = instrument(StateGraph(PaymentState))
+
+    def fetch_budget(state):
+        """Read the account budget the approval will rest on (the keystone source).
+        The allow-list is static config (read free in the initial state), so the budget
+        is the single fetched dependency the approval rests on."""
+        return {"budget": 10000}
+
+    def approve(state):
+        """Decide the payment against the budget and allow-list this node read."""
+        ok = state["recipient"] in state["allow_list"] and state["amount"] <= state["budget"]
+        return {"approved": ok}
+
+    def record_ledger(state):
+        """Rest on the approval the approve node wrote."""
+        return {"recorded": state["approved"]}
+
+    builder.add_node("fetch_budget", fetch_budget)
+    builder.add_node("approve", approve)
+    builder.add_node("record_ledger", record_ledger)
+    builder.add_edge(START, "fetch_budget")
+    builder.add_edge("fetch_budget", "approve")
+    builder.add_edge("approve", "record_ledger")
+    builder.add_edge("record_ledger", END)
+    return builder
+
+
+def main():
+    builder = build_agent()
+    graph = builder.compile()
+    final = graph.invoke(
+        {
+            "invoice": "INV-4471",
+            "recipient": "acme-supplies",
+            "amount": 4200,
+            "budget": 0,
+            "allow_list": ["acme-supplies"],
+            "approved": False,
+            "recorded": False,
+        }
+    )
+    print(f"agent run: approved={final['approved']}\n")
+
+    # POST: the same captured run, ranked. fetch_budget is the structural keystone.
+    report = analyze_run(builder, adapter=builder)
+    print(report)
+    k = report.keystone
+    if k is not None:
+        print(f"\nPOST keystone: step {k.idx} ({k.node_attrs.get('langgraph_node')})\n")
+
+    # LIVE: lower the captured approval into a replayable record. The relied-on budget,
+    # amount, recipient, and allow-list become its DependencySnapshot; action_args and
+    # action_costs lift the recipient and the real cost onto the action itself, so the
+    # lowered record is the executable payment, not a state-only stub.
+    record = builder.to_records(
+        decisions={"approve": "vendor_payment"},
+        action_args={"approve": {"recipient": "recipient"}},
+        action_costs={"approve": "amount"},
+    )[0]
+    snap = record.data.snapshot.state
+    print("captured decision record:")
+    print(f"  action:   {record.harness.action_type} -> {record.harness.arguments}")
+    print(f"  cost:     ${record.harness.cost:,.0f} (the captured amount)")
+    print(f"  relied-on budget: ${snap['budget']:,}; amount: ${snap['amount']:,}\n")
+
+    # Commit the captured payment through a reference ledger (a demo rail, not a production
+    # rail). The action committed is the one the record carries, not a hand-rebuilt one.
+    ledger = ReferenceLedger(balance=10000)
+    gate = ActionGate(ledger)
+    pay = Action(record.harness.action_type, dict(record.harness.arguments), cost=record.harness.cost)
+    receipt = gate.commit(pay)
+    print(f"committed ${pay.cost:,.0f}; ledger balance now ${ledger.balance:,.0f}")
+
+    # Fault injection: after capture, the live budget drops below the approved amount.
+    # replay re-decides on the live state and routes a rollback; the gate executes it.
+    live_state = {**snap, "budget": 3000}
+    verdict = replay(record, live_state=live_state, policy=budget_policy)
+    gate.enforce_post_commit(verdict, receipt=receipt)
+    print(f"replay under live budget $3,000: {verdict.action.value.upper()} -- {verdict.reason}")
+    print(f"recovery executed; ledger balance restored to ${ledger.balance:,.0f}")
+
+
+if __name__ == "__main__":
+    main()