consequa-x 1.2.0__tar.gz → 2.1.0__tar.gz

consequa_x-2.1.0/CHANGELOG.md

@@ -0,0 +1,353 @@
+# Changes
+
+## 2.1.0 - 19 October 2026
+
+Additive: the roadmap features left out of 2.0.0 (verifier composition,
+framework integrations and OpenTelemetry). Schema `1.0` and the 2.0 API are
+unchanged, and the core still has no required runtime dependency. Checked
+before publication; see the
+[release record](output/release-2.1.0-2026-10-19/README.md).
+
+- Verifier composition. `all_of(contract_id, *parts)` and `any_of(...)` build
+  one outcome contract from part contracts, each with its own predicate,
+  expected values and timing; `contract_parts` decodes and checks them.
+  `CompositeVerifier({part_id: verifier}, sources={part_id: source})` checks
+  each part against the readback from its source and combines the receipts
+  with three-valued logic: `all_of` is violated when any part is violated and
+  satisfied when all are; `any_of` is satisfied when any part is and violated
+  when all are; otherwise the outcome stays `unknown`. A part without readback
+  is `unknown`. The receipt keeps each part's evidence (tagged with its part
+  ID, status, origin and reason), the union of the parts' effects and
+  findings, and adds `PART_VIOLATED`, `PART_UNKNOWN` and `PART_OTHER_ACTOR`.
+  Target matching is conservative, so an agent's report is judged only when
+  the deciding parts did target matching. Parts can nest.
+- Several readbacks per verification: `verify`, `averify`,
+  `ActionCapture.verify`/`averify` and `poll_readback` (whose `read` may return
+  one observation per source) accept a sequence of observations for a verifier
+  that provides `verify_readbacks`. Receipts are still checked against every
+  supplied observation.
+- Reports describe an `all_of`/`any_of` contract's structure (part count,
+  each part's deadline and horizon) and list each recorded part result, without
+  showing part payloads.
+- `consequa-x verify` takes `--readback` once per source, plus
+  `--part-source PART=SOURCE` and `--scope-field PART=FIELD` for composite
+  contracts.
+- OpenTelemetry (`consequa_x.otel`): `to_otlp` writes an OTLP/JSON document
+  with a span per action, an `execute_tool` span per attempt named as the GenAI
+  semantic conventions describe, and a span per verification, with
+  `consequa_x.*` attributes for state, origin, alignment and diagnosis codes.
+  Payloads are opt-in (`include_payloads=True`, which also embeds the complete
+  trace for `from_otlp`). `emit` creates the spans through `opentelemetry-api`
+  (extra `otel`). `record_tool_spans` turns `execute_tool` spans from any
+  GenAI instrumentation into recorded actions for the contracts the
+  application supplies. New commands: `otel-export` and `otel-import`.
+- Framework integrations (`consequa_x.integrations`): `ToolCallCapture` and
+  `ToolCall` record framework tool calls for the calls `contract_for` makes
+  consequential, grouping retries through `action_id_for`. Optional extras:
+  `openai-agents` (`consequential_tool`, in place of `function_tool`),
+  `langchain` (`ConsequaCallbackHandler`) and `claude-agent-sdk`
+  (`consequa_hooks` for `PreToolUse`, `PostToolUse` and
+  `PostToolUseFailure`). Tested offline with openai-agents 0.24.0,
+  langchain-core 1.6.12, claude-agent-sdk 0.2.168 and opentelemetry 1.45.1; no
+  live model was called.
+
+## 2.0.0 - 19 October 2026 (breaking)
+
+See [the 2.0 design](docs/design-2.0.md) and the
+[migration guide](docs/migrating-to-2.0.md). Deferred to 2.1: verifier
+composition, optional framework integrations and OpenTelemetry export.
+Published to PyPI with registry hashes verified; see the
+[release record](output/release-2.0.0-2026-10-19/README.md). Installed checks
+passed on Windows Python 3.11.9 and 3.12.10, on one Alpine Linux 3.24.2 QEMU guest
+with Python 3.14.8 and from a fresh PyPI install. macOS has never been tested.
+
+- Typed exceptions: every intentional error derives from `ConsequaError` and
+  still from `ValueError` or `TypeError`. `ValidationError` (invalid records,
+  traces and settings; malformed JSON is now one too), `SchemaVersionError`,
+  `ConsequaTypeError`, `ContractError` (a verifier cannot evaluate the
+  contract), `ReceiptError` (a verifier or matcher result crosses its identity
+  boundary, or recorded evidence cannot support the interpretation) and
+  `RecorderError`. `InsufficientEvidenceError` and `PolicyError` join the
+  hierarchy.
+- Captured payloads are deeply read-only. Event data, arguments, contract
+  expectations, results, readback records, scopes and evidence details are
+  `FrozenDict` and `FrozenList` values: they compare equal to and serialize
+  like ordinary dicts and lists, but any change raises `ConsequaTypeError`.
+  `copy.deepcopy` returns the same read-only value; `thaw()` returns an
+  editable copy, and `to_dict()` still exports ordinary dicts and lists.
+- Trace schema `1.0`. A trace holds one or more `actions`, each with its own
+  contract; `responses`, `assessments` (zero or more per action) and
+  `verifications` each name their `action_id`. A required `time_base`
+  (`unix_ms` or `relative_ms`) says what the integer millisecond times count
+  from. `trace_id` is no longer repeated on actions and events. All records
+  are keyword-only. Schema `0.1` input is refused with a `SchemaVersionError`
+  that names the migration route; the packaged schema is `trace-v1.0.json`.
+  New helpers: `Trace.get_action`, `single_action`, `responses_for`,
+  `assessments_for`, `verifications_for`, `latest_assessment`,
+  `latest_verification`.
+- `TraceRecorder.register` can be called for several actions and returns an
+  `ActionCapture` whose `attempt`, `call`, `dispatch`, `response`,
+  `assessment` and `verify` record for that action. The recorder-level methods
+  still work while exactly one action is registered. Assessments are optional
+  and may be repeated. The default clock is wall-clock `unix_ms`; a custom
+  clock records `relative_ms` unless told otherwise. `capture_tool` and
+  `call_mcp_tool` accept an `ActionCapture`.
+- `explain()` returns a `TraceExplanation` with one `ActionExplanation` per
+  action (`for_action`, `single_action`). An action without verification is
+  reported as `NO_VERIFICATION` instead of raising. The evidence graph has a
+  contract node per action, and offline reports show every action, with an
+  Action column for responses and verifications and the time base in the
+  footer.
+- Verifiers own domain interpretation. `VerificationResult` gains
+  `target_effect_ids` (`None` when the verifier did no target matching,
+  otherwise this action's effects that match the full target) and `findings`
+  (`Finding(code, effect_ids, detail)`). `RefundVerifier` records refund
+  matches and the `EXCESS_EFFECTS`, `DUPLICATE_EFFECT`, `PARAMETER_MISMATCH`,
+  `PARTIAL_EFFECT` and `REVERSED_EFFECT` findings; `RecordVerifier` records
+  record matches and `EXCESS_EFFECTS`, `DUPLICATE_EFFECT`,
+  `PARAMETER_MISMATCH` and `REMOVED_EFFECT`. `TargetMatcher`,
+  `RecordTargetMatcher`, `RecordVerifier.target_matcher()` and
+  `explain(..., target_matcher=...)` are removed; a custom verifier sets
+  `target_effect_ids` instead.
+- `explain()` is domain-independent: it reads receipts, responses and
+  assessments and never reinterprets evidence details. Diagnoses are
+  structured `Diagnosis(code, evidence, message)` records; `codes` gives the
+  codes and `diagnosis` a display label. `UNASSESSABLE_ASSESSMENT` now applies
+  to every predicate whenever the outcome is known but alignment cannot be
+  judged (1.x omitted it for refunds). `CORE_DIAGNOSES` lists the codes
+  `explain()` produces.
+- Offline reports show each action's assessment alignment and diagnosis
+  codes, computed from the recorded receipts. Codes from custom verifiers are
+  counted rather than printed.
+- Migration: `migrate_trace()` and `consequa-x migrate OLD --output NEW`
+  convert schema `0.1` traces. Target matches and findings are added only when
+  the 2.0 verifier (the refund verifier by default; pass others with
+  `verifiers=`) reproduces the recorded receipt exactly; no recorded conclusion
+  is changed. `consequa-x validate` checks trace files. Migrated traces of the
+  1.x demo reproduce their 1.x explanations; fixtures written by the released
+  1.2.0 package are in `tests/fixtures/v0.1`.
+- `summarize(traces)` and `consequa-x summarize PATH... [--format text|markdown|json]`
+  count verified state, origin, alignment, tool responses and diagnoses over
+  every action, with stated denominators; `unknown` and `unverified` stay
+  separate from failures, and actions with divergences or violations are
+  listed. Folders (non-trace JSON is skipped and counted) and `.jsonl` stores
+  are accepted; invalid inputs are listed by path and error type only and make
+  the command exit 2.
+- `poll_readback(capture, read, until_ms=, interval_ms=)` waits until the
+  contract horizon, then reads back and verifies repeatedly (every observation
+  and receipt is recorded) until the outcome is `satisfied` or `violated` or the
+  time limit passes; an unresolved `unknown` is returned as is.
+- Async agents: `capture_tool` wraps `async def` tools, `ActionCapture.acall`
+  (and `TraceRecorder.acall`) awaits a tool as one recorded attempt,
+  `averify`/`ActionCapture.averify` accept verifiers whose `verify` is a
+  coroutine (receipts are checked exactly as `verify` checks them), and
+  `apoll_readback` polls with awaited reads and `asyncio.sleep`.
+- `retry_advice(receipt or trace)` turns verified evidence into
+  `DO_NOT_RETRY` (the outcome already holds, whoever produced it), `WAIT`
+  (missing or unknown readback), `ESCALATE` (relevant effects that do not
+  satisfy the contract) or `RETRY_PERMITTED` (a complete readback shows no
+  relevant effect; retry with an idempotency key, since an in-flight attempt can
+  still commit), each with a reason.
+- `compare(left, right)` and `consequa-x compare A B [--fail-on-difference]`
+  compare two traces action by action: contract, tool responses, latest
+  assessment, verified state and origin, alignment and diagnosis codes, plus
+  actions present in only one trace.
+- `consequa-x verify TRACE --readback OBS.json [--scope-field F] --output NEW`
+  verifies a captured readback file with the built-in refund or record
+  verifier and saves the trace with the new receipt, without Python code.
+- `render_report(..., include_details=True, redact=("card_number", ...))` and
+  `consequa-x report --include-details --redact KEY` replace the values of the
+  named JSON keys everywhere in the included trace. Values under other keys are
+  kept; this is omission by name, not anonymization.
+- `TraceStore(path)`: an append-only JSON Lines file of validated traces with
+  unique trace IDs; reading reports the line number of an invalid entry.
+- Research interfaces (`EffectEstimate`, `Intervention`, `leave_one_out`,
+  `recency_attribution`, the policy types) are imported from
+  `consequa_x.research` instead of the top-level namespace.
+- Research code (benchmark, replay, policies, studies and their audit
+  scripts) produces and reads schema `1.0` traces. Retained 1.x study outputs
+  under `output/` are unchanged.
+
+## 1.2.0 - 19 October 2026
+
+Additive only: the 1.x API and trace schema `0.1` are unchanged.
+
+- Added `TraceRecorder` (`consequa_x.capture`), which records one action as it
+  happens (context, decision, registration with its outcome contract,
+  dispatches, tool responses, the agent's assessment, readbacks and
+  verification) and returns an ordinary validated `Trace`. Events are linked
+  as in the package fixtures, so graphs, reports and `explain()` work unchanged.
+- Added tool-call capture: `TraceRecorder.attempt()` (context manager),
+  `TraceRecorder.call()` and the `capture_tool` decorator record the dispatch
+  and the response (success, `timeout` for `TimeoutError`, or `error`) around
+  a synchronous tool, keep JSON results, keep only exception type names, and
+  re-raise. A recorded timeout says nothing about whether the effect happened.
+- Added `RecordVerifier` and `RecordTargetMatcher` for a generic `record_present`
+  predicate: records with given field values, an exact or minimum count,
+  a commit deadline and a persistence window, with configurable field names.
+  Unavailable, out-of-scope, incomplete, stale or malformed readback stays
+  `unknown`, and origin stays a separate conclusion, as for refunds.
+- Added `examples/agent_loop_sqlite.py`: a stdlib-only, offline tool-calling
+  loop that writes to a real SQLite database, is captured with `TraceRecorder`,
+  and is verified through a separate read-only connection with `RecordVerifier`.
+  Modes: `timeout_after_commit`, `other_actor` and `stale_readback`.
+  It is also in the website's quickstart download.
+- README section on capturing a real agent's tool call.
+- Added `TraceRecorder.now()`, the recorder clock for readback times.
+- Added `consequa_x.mcp_capture.call_mcp_tool`, which records an awaited MCP
+  tool call from any session exposing `call_tool(name, arguments)` without an
+  MCP dependency. Tool content is not copied into the trace.
+- Added a framework integration guide (`docs/framework-integration.md`).
+- The website's workflow cards, documentation and quickstart show the capture
+  API. `scripts/check_installed_release.py` now also exercises the recorder,
+  tool capture and record verifier from the installed wheel.
+- Published to PyPI with registry hashes verified; see the
+  [release record](output/release-1.2.0-2026-10-19/README.md). Installed checks
+  passed on Windows Python 3.11.9 and 3.12.10, on one Alpine Linux 3.24.2 QEMU
+  guest with Python 3.14.8 and from a fresh PyPI install. macOS has never been
+  tested.
+
+## 1.1.1 - 18 October 2026
+
+- Documentation and metadata release. Runtime code and schema `0.1` are
+  identical to 1.1.0 apart from the version number.
+- Rewrote the package description for PyPI with absolute links that work outside
+  the repository. Project URLs now point to the public source repository and to
+  <https://consequa-x.onrender.com>.
+- The source repository is public. Its issue forms and security policy replace
+  the separate community repository, whose quickstart and release notes moved to
+  `docs/quickstart.md` and `docs/release-notes.md`.
+- The website inspector and live demo replay recorded output from real package
+  runs, generated by `scripts/build_site_demo.py` and pinned by
+  `tests/test_site_demo.py`. The site deploys from this repository.
+- The snapshot-integrity test now verifies every committed manifest format and
+  ignores uncommitted study outputs.
+- Published to PyPI with registry hashes verified; see the
+  [release record](output/release-1.1.1-2026-10-18/README.md). Installed checks
+  passed on Windows Python 3.11.9 and 3.12.10 and from a fresh PyPI install.
+  Linux and macOS were not rerun for 1.1.1; macOS has never been tested.
+
+## 1.1.0 - 17 October 2026
+
+- Added `render_report(trace, include_details=False)` and
+  `consequa-x report trace.json --output report.html`, with a self-contained
+  chronology, contract, responses, assessment, readback, verification/origin and
+  SVG evidence graph plus complete accessible graph tables.
+- Default reports omit arbitrary captured values throughout the file. Explicit
+  details mode includes the full trace as escaped inert JSON. No report executes
+  actions, verifiers, target matchers or replay; alignment remains unassessable
+  in the report. The original trace remains separate evidence.
+- Preserved source and existing output files with exclusive creation. Invalid
+  schema data is refused before an output directory is created, with captured
+  values omitted from report-command decoding errors.
+- Added a synthetic artifact-delivery visual quickstart and public documentation,
+  support and security routes, while retaining the private research repository.
+- Added installed-package release checks and browser/report security gates.
+  Release receipts bind the final artifact, actual platform checks and
+  publication state; public release notes report the tested environments.
+- Preserved the dependency-free version-1 core and portable wire schema `0.1`.
+  GitHub Actions stays disabled.
+
+## Post-release research update - 16 October 2026
+
+The predeclared physical-interaction study finished collection on 15 October
+2026 at frozen runtime source `0bd744df4fc8784e4cf1a1e2eb62f892c6f3c8c9`.
+It retained all 2,048 trials and 655,360 planned branch slots, with 628,535 actual
+scripted policy calls, no model calls and no additional comparison calls.
+The [protocol](output/interaction-sampling-2026-10-15/protocol.json),
+[complete summary](output/interaction-sampling-2026-10-15/summary.json) and
+[execution receipt](output/interaction-sampling-2026-10-15-execution.json) retain
+the collection identity separately from the public stable release. The
+[independent audit](output/interaction-sampling-audits-2026-10-15/independent.json)
+passed 44,698,925 assertions, covering every planned trial/branch and 4,210
+preselected complete traces. The
+[derived findings](output/interaction-sampling-findings-2026-10-15/FINDINGS.md)
+retain coverage, width, detection and refusal denominators. The defined
+framework and protocol/software paper scope is complete on 16 October 2026:
+the [illustrated eight-page IEEE PDF](output/pdf/Consequa-X_IEEE_Paper.pdf) compiled and all
+rendered pages passed visual review. The [QA receipt](output/pdf/qa.json) binds
+it to the frozen [editable source](paper/consequa-x-ieee.tex) and four vector
+figures. Actual venue selection, final human
+review, reviewer access and submission remain maintainer steps. These results
+do not establish held-out model performance, a new estimator or baseline
+superiority.
+
+## 1.0.0 - 15 October 2026
+
+Runtime source is frozen at `0bd744df4fc8784e4cf1a1e2eb62f892c6f3c8c9`.
+The [stable release is public on PyPI](https://pypi.org/project/consequa-x/1.0.0/),
+built from `85ce6c316838c995782aadc8c10770acc708339b` with all 36 runtime files
+matching that freeze. Both downloads were independently hash/size checked;
+[publication](output/release-1.0.0-2026-10-15/publication.json) and
+[fresh registry-install](output/release-1.0.0-2026-10-15/registry-install.json)
+receipts record the achieved release. PR #8 merged as `708d064`; GitHub remains
+private. Published artifacts retain their original reviewed bytes and dated
+build-time documentation.
+
+- Defined the version 1 stable evidence-core API while retaining wire schema
+  `0.1`. Benchmark procedures, exact policy prompts and study commands remain
+  explicitly scoped research interfaces.
+- Added explicit application verifiers to `verify(..., verifier=...)`, with
+  receipt checks for contract, observation identity, source, watermark and
+  capture time. Adapter semantics and source authentication remain application
+  responsibilities.
+- Added `TargetMatcher` and `explain(..., target_matcher=...)`. Non-refund
+  predicates remain domain-neutral and unassessable without declared target
+  semantics; unknown receipts never execute the matcher. Invalid adapter methods
+  and inputs have controlled type errors, and invalid target returns or known
+  refund details have controlled value errors.
+- Exported `Evidence`, `ToolResponse`, `ResponseStatus` and `TargetMatcher` from
+  the package root. Added the standalone artifact-delivery application example
+  and source-archive integration documentation.
+- Preserved successive and duplicate effect records as separate graph witnesses,
+  with identity edges and observation-specific verification/origin links.
+  Conflicting later payloads or provenance cannot overwrite an earlier witness.
+  Source-owned reserved fields remain available verbatim; attribution candidates
+  must identify captured events.
+- Made demonstration, fixture-experiment and explanation output paths preserve
+  existing evidence. Run directories must be new or empty; explanation output
+  must be a new file distinct from the input trace.
+- Added `calibrate-interactions`, reproducible repeated physical refund sampling,
+  same-draw uncertainty comparisons, bounded parallel execution, complete
+  refusal/cost records and an independently implemented audit. The retained
+  2,048-trial collection completed after the distribution-build checkpoint;
+  its later research status is recorded above without changing released bytes.
+
+The full frozen-source suite passed 1,480 tests and 240 subtests. Twenty
+additional stable-publisher tests passed; final installed-wheel Windows Python
+3.11.9 conformance passed 200 tests and 165 subtests. Independent Windows Python
+3.12.14 wheel, source-archive and registry installations each passed 12 trace
+round-trips and four artifact-adapter checks. All eight local release gates,
+public artifact hash/size verification and the fresh registry installation are
+complete. No GitHub Actions were used. These software checks do not establish
+held-out model performance or attribution superiority.
+
+## 0.1.0a2 — 14 October 2026
+
+- Default decision-contrastive uncertainty now uses exact binomial intervals.
+  Signed Shapley pair means use Hoeffding bounds; independent endpoint
+  differences use two exact binomial marginals with a split failure allowance.
+  Original bootstrap/normal modes remain explicit comparators.
+- Added `compare-intervals`, with a pre-call protocol, complete same-draw
+  retention, exact finite distribution calculations, width/power metrics and
+  independent numerical/artifact audits. Original calibration data is preserved.
+- Added an explicit on-reach positional game for normally terminated later
+  decisions. The strict game remains the default, and incompatible operations,
+  unknown evidence, provider failures and budget refusals remain explicit.
+- Added `refund-interactions` to enumerate physical selection/retry interactions,
+  idempotency and evidence/budget controls through actual payment readback.
+- Interval rescoring now reconstructs Shapley pair vectors from replay evidence
+  and validates stored coverage, points and endpoint diagnostics.
+- Cached static record annotations while retaining validation of every value;
+  added a working paper, reproducible evidence links and release preparation.
+
+This is an engineering alpha. Sampling assumptions, individual-interval scope
+and intervention games remain explicit. Synthetic validation does not establish
+live-model calibration, cross-task generalization or attribution superiority.
+GitHub Actions remains disabled; checks and builds run locally.
+
+## 0.1.0a1
+
+Initial Python alpha with portable evidence records, independent refund
+verification, evidence graphs, local policy adapters and bounded replay
+experiments. No registry publication is implied by the source version.

{consequa_x-1.2.0 → consequa_x-2.1.0}/MANIFEST.in

@@ -5,3 +5,5 @@ recursive-include docs/studies *.json
 recursive-include tests *.py
 recursive-include examples *.py
 recursive-include scripts *.py
+recursive-include tests/fixtures *.json
+recursive-include tests/fixtures *.md

consequa_x-2.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: consequa-x
+Version: 2.1.0
+Summary: Evidence-aware explanation of consequential agent actions
+Author: Devrajsinh Jhala
+License-Expression: MIT
+Project-URL: Homepage, https://consequa-x.onrender.com
+Project-URL: Documentation, https://consequa-x.onrender.com/docs.html
+Project-URL: Changelog, https://consequa-x.onrender.com/changelog.html
+Project-URL: Repository, https://github.com/Devrajsinh-Jhala/consequa-x
+Project-URL: Issues, https://github.com/Devrajsinh-Jhala/consequa-x/issues
+Project-URL: Security, https://github.com/Devrajsinh-Jhala/consequa-x/security/policy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.2.168; extra == "claude-agent-sdk"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: jsonschema>=4.23; extra == "dev"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.6; extra == "langchain"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.24; extra == "openai-agents"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.45; extra == "otel"
+Dynamic: license-file
+
+# Consequa-X
+
+**Evidence-aware explanation of consequential agent actions.**
+
+When an agent calls a tool that changes something (a refund, a delivery, a
+database write), the tool's response is only part of the story. A timeout can
+hide a refund that went through. A "success" can hide one that never landed.
+Another actor can produce the very outcome the agent was asked for.
+
+Consequa-X keeps four things apart: the **tool response**, what the **agent
+reported**, the outcome established by an **independent read-only readback**, and
+**who produced the effect**. Missing, stale or incomplete evidence stays
+`unknown` instead of being guessed.
+
+- Website, live inspector and docs: <https://consequa-x.onrender.com>
+- Package: <https://pypi.org/project/consequa-x/>
+- Source and issues: <https://github.com/Devrajsinh-Jhala/consequa-x>
+
+Python 3.11+ · MIT licensed · no required runtime dependencies · no model, API
+key or network access needed for the core or the offline examples.
+
+## Install
+
+```sh
+python -m pip install consequa-x
+consequa-x --version
+```
+
+Use `python -m consequa_x` wherever a command below uses `consequa-x`. Optional
+extras add framework integrations and OpenTelemetry: `consequa-x[openai-agents]`,
+`consequa-x[langchain]`, `consequa-x[claude-agent-sdk]` and `consequa-x[otel]`.
+
+## See it in a minute
+
+```sh
+consequa-x demo --output my-demo
+consequa-x report my-demo/traces/episode_01.json --output my-report.html
+```
+
+`demo` writes twelve synthetic refund scenarios with simulated money: timeouts
+before and after commit, false success, partial and duplicate effects, delayed
+readback, retries, another actor and missing provenance. Episode 1 is a timeout
+after commit: the tool timed out and the agent reported failure, but readback
+shows the refund committed and linked to the agent's action. Open
+`my-report.html` in any browser. It is one self-contained file with no scripts
+or network requests.
+
+Each run needs a new output directory, and a report never overwrites an existing
+file. The demo's `evaluator_truth/` folder is simulator ground truth for
+evaluation only; never pass it to an explainer.
+
+## Use it in Python
+
+Register each consequential action with its intended outcome before running it,
+let the recorder capture what happens, read the outcome back from a trusted
+read-only source, then verify and explain:
+
+```python
+from consequa_x import (
+    Observation, OutcomeContract, RecordVerifier, TraceRecorder, explain, render_report,
+)
+
+verifier = RecordVerifier(scope_fields=("order_id",))
+rec = TraceRecorder("run-17", actor="support-agent", time_base="relative_ms")
+refund = rec.register(
+    "refund-o-17", "issue_refund", {"order_id": "o-17"}, at_ms=0,
+    contract=OutcomeContract(contract_id="refund-o-17", predicate="record_present",
+                             expected={"order_id": "o-17", "amount_minor": 5000},
+                             deadline_ms=200, stability_ms=50))
+
+try:
+    with refund.attempt(at_ms=5) as attempt:      # your tool call goes here
+        attempt.at_ms = 30
+        raise TimeoutError                        # ...and it timed out
+except TimeoutError:
+    refund.assessment("failure", at_ms=31)        # what the agent reported
+
+# Captured independently, after the horizon, from a read-only replica of the orders table.
+readback = Observation(
+    observation_id="read-1", source="orders-replica", observed_at_ms=300, as_of_ms=300,
+    scope={"order_id": "o-17"},
+    records=({"effect_id": "rf-1", "order_id": "o-17", "amount_minor": 5000,
+              "committed_at_ms": 20, "action_id": "refund-o-17",
+              "attempt_id": "refund-o-17:attempt-1", "actor": "support-agent"},))
+receipt = refund.verify(readback, verifier=verifier)
+
+result = explain(rec.trace()).for_action("refund-o-17")
+assert receipt.status.value == "satisfied"         # the refund really happened
+assert receipt.origin.value == "confirmed"         # and this action produced it
+assert result.assessment_alignment == "contradicted"   # the agent said failure
+print(result.codes)  # ('ASSESSMENT_DIVERGENCE', 'ACKNOWLEDGEMENT_EFFECT_DIVERGENCE')
+html = render_report(rec.trace())                  # offline, minimal disclosure
+```
+
+A run can register several actions; each `register` returns that action's
+`ActionCapture`, and its attempts, assessments and verifications stay separate.
+`capture_tool` decorates a tool (synchronous or `async def`) so every call is
+recorded. `poll_readback` re-reads a lagging source until the outcome is known,
+and `retry_advice` turns the receipt into a retry decision.
+
+The built-in verifiers are `RecordVerifier` (rows, orders, tickets, files:
+`record_present`) and `RefundVerifier` (`refund_processed`). Both check values,
+count, commit deadline and persistence; unavailable, incomplete, wrongly scoped or
+stale readback produces `unknown`. Effect origin is a separate conclusion:
+`confirmed`, `other_actor` or `unknown`. Verifiers also record which effects match
+the target and domain findings (excess, duplicate, mismatched, reversed or
+removed effects); `explain` reads those receipts without any domain logic of its
+own.
+
+The [agent-loop example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/agent_loop_sqlite.py)
+runs this end to end against a real SQLite database, offline, in three modes: a
+timeout after the refund committed, a refund made by someone else, and a readback
+too stale to decide. The
+[framework guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/framework-integration.md)
+shows where the calls go in OpenAI Agents SDK, LangChain, Claude Agent SDK and MCP
+tool loops.
+
+Traces round-trip through a portable, versioned JSON schema (`1.0`):
+`Trace.from_json(trace.to_json())` rejects unknown fields, broken identity links
+and dependency cycles, and every captured payload is read-only.
+
+## Bring your own domain
+
+Write a read-only `Verifier` for your predicate. It returns a
+`VerificationResult` with the state, origin and the effects it saw; to let the
+agent's report be judged, it also records `target_effect_ids` (this action's
+effects that match the full target):
+
+```python
+receipt = verify(action, observation, verifier=MyVerifier())
+```
+
+Your application owns source trust, scope, completeness, timing and provenance;
+Consequa-X checks that receipts bind to the supplied action, contract and
+observation, and keeps the evidence structured. The
+[artifact-delivery example](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/examples/artifact_delivery.py)
+implements a verifier with public APIs only, and the
+[integration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/application-integration.md)
+describes the boundary in detail. The
+[stable API](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/stable-api.md)
+page lists what version 2 guarantees.
+
+An outcome with several required effects (a refund *and* a closed ticket, or a
+refund *or* store credit) is one contract: `all_of(...)` or `any_of(...)` over
+part contracts, checked by `CompositeVerifier` with one readback per source.
+Unknown parts keep the whole outcome unknown unless another part already
+settles it.
+
+## Agent frameworks and OpenTelemetry
+
+Optional integrations record an agent framework's tool calls through the same
+recorder. Your `contract_for(call)` decides which calls are consequential:
+
+```python
+from consequa_x.integrations import ToolCallCapture
+calls = ToolCallCapture(rec, contract_for=contract_for)
+
+# OpenAI Agents SDK: use in place of @function_tool
+from consequa_x.integrations.openai_agents import consequential_tool
+# LangChain: config={"callbacks": [ConsequaCallbackHandler(calls)]}
+from consequa_x.integrations.langchain import ConsequaCallbackHandler
+# Claude Agent SDK: ClaudeAgentOptions(hooks=consequa_hooks(calls))
+from consequa_x.integrations.claude_agent_sdk import consequa_hooks
+```
+
+`consequa_x.otel` writes traces as OTLP/JSON with `execute_tool` spans named as
+the OpenTelemetry GenAI conventions describe, emits them through
+`opentelemetry-api`, and turns tool spans from other instrumentation into
+recorded actions. See the
+[framework guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/framework-integration.md)
+and the
+[OpenTelemetry guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/opentelemetry.md).
+
+## Upgrading from 1.x
+
+Version 2.0 changes the trace schema to `1.0` (several actions per trace, a
+declared time base, keyword-only and read-only records) and moves domain
+interpretation into verifiers. Convert saved 1.x traces with
+`consequa-x migrate OLD.json --output NEW.json` or `migrate_trace()`. The
+[migration guide](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/migrating-to-2.0.md)
+lists every change and its replacement.
+
+## Command line
+
+| Command | What it does |
+| --- | --- |
+| `consequa-x demo --output DIR` | Write the twelve synthetic refund scenarios: traces, explanations, schema and manifest |
+| `consequa-x explain TRACE [--output FILE]` | Explain an existing trace without replay; prints JSON or writes a new file |
+| `consequa-x report TRACE --output FILE` | Render a self-contained HTML report; `--include-details` embeds the full capture, `--redact KEY` blanks named keys in it |
+| `consequa-x summarize PATH... [--format markdown]` | Count outcomes, alignment and divergences across trace files, folders and `.jsonl` stores |
+| `consequa-x compare A B` | Compare two traces action by action |
+| `consequa-x verify TRACE --readback OBS --output NEW` | Verify captured readback with built-in verifiers; repeat `--readback` for an `all_of`/`any_of` contract |
+| `consequa-x otel-export TRACE --output FILE` / `consequa-x otel-import FILE --output-dir DIR` | Write a trace as OpenTelemetry OTLP/JSON spans; restore traces exported with `--include-payloads` |
+| `consequa-x validate TRACE...` / `consequa-x migrate OLD --output NEW` | Check traces; convert schema `0.1` traces |
+| `consequa-x experiment …` and research commands | Paired replay, decision attribution and calibration studies (see Research) |
+
+## What it does not do
+
+- It does not watch or control a live agent; your application captures the records.
+  `retry_advice` is advice derived from captured evidence, not a guarantee.
+- It does not authenticate a readback source or prove that provider metadata is true.
+- An evidence-graph link records provenance, not causal necessity.
+- Default reports omit captured strings and identifiers, but keep times, counts
+  and relationships. That is field omission, not anonymization.
+- No accuracy advantage over other methods is claimed.
+
+## Research
+
+The repository also contains declared research interfaces, imported from
+`consequa_x.research`: isolated replay, contrastive and Shapley-style decision attribution,
+calibration studies, an optional local Ollama adapter, and the retained evidence
+for each study. Results so far are synthetic or exploratory local-model studies
+and are reported with their denominators and limits. Start with the
+[research roadmap](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/docs/research-roadmap.md)
+and the [paper notes](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/paper/README.md).
+
+## Platforms
+
+The package is pure Python. Released wheels have been install-tested on Windows
+with Python 3.11 and 3.12 and on one Alpine Linux virtual machine with Python
+3.14. macOS has not been tested yet. See the
+[release notes](https://consequa-x.onrender.com/changelog.html) for exact
+environments.
+
+## Contributing and support
+
+- Questions and bugs: [GitHub issues](https://github.com/Devrajsinh-Jhala/consequa-x/issues/new/choose).
+  Use synthetic data only; never post real traces, customer data or credentials.
+- Security: report vulnerabilities privately as described in
+  [SECURITY.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/SECURITY.md).
+- Development: see [CONTRIBUTING.md](https://github.com/Devrajsinh-Jhala/consequa-x/blob/main/CONTRIBUTING.md).
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check src tests scripts
+```
+
+## License
+
+MIT, copyright Devrajsinh Jhala. The website's self-hosted fonts keep their SIL
+Open Font License.