From a trace
to a clear account.

Make the evidence visible.

This example performs no delivery or payment. It reads synthetic artifact-store fixtures using the public package APIs.

python -m pip install consequa-x==2.1.2
consequa-x --version

python report_quickstart.py --output my-first-capture

consequa-x report my-first-capture/verified.json --output another-report.html

State and origin stay separate.

A timeout describes a tool response. It cannot by itself determine the requested outcome.

The example hashes the bytes read from its fixture independently of the requested digest. Its application-owned ArtifactVerifier evaluates the contract and records which revisions match the target, so explain can judge the agent’s report without any artifact-specific logic.

Inspect an offline report.

A report is self-contained HTML: no JavaScript, external fonts, remote assets or network requests. It shows structural contract bounds, the timeline, responses, the reported assessment, readbacks, recorded state and origin, and an evidence graph.

Successive observations retain separate witnesses. Order, dependency, observation and origin links carry distinct labels; a graph edge does not establish counterfactual necessity.

To start with the package’s bundled refund fixtures instead:

consequa-x demo --output sample-run
consequa-x report sample-run/traces/episode_00.json --output sample-report.html

Input traces are validated before the output is created. The CLI preserves the source and refuses an existing output file, including the input itself.

Share a smaller surface.

Default reports use local aliases and omit arbitrary captured values: payloads, rationales, source names, raw identifiers, paths, digests, predicates and error messages. Omitted fields are absent from the HTML, including attributes, comments and embedded data.

Timing, counts, enum statuses and relationships remain visible. Review these before sharing. This is deliberate field omission, not universal anonymization or personal-data detection.

consequa-x report my-first-capture/verified.json --output detailed-report.html --include-details

Retain the original trace and source evidence separately. A reduced presentation is not a substitute for the verification record. For a public bug report, provide a synthetic reproduction.

Render without a service.

render_report returns HTML and writes no files. It accepts a validated Trace and an optional boolean include_details argument, which defaults to False.

from pathlib import Path
from consequa_x import Trace, render_report

trace = Trace.from_json(Path("trace.json").read_text(encoding="utf-8"))
document = render_report(trace)  # Minimal disclosure by default.
with Path("report.html").open("x", encoding="utf-8") as destination:
    destination.write(document)

The portable schema is 1.0: several actions per trace, a declared time base, and read-only records. Package version and wire-schema version are separate. Convert traces saved by 1.x with consequa-x migrate.

Connect your application.

1. Declare the contract before the action. Define matching state, deadline, persistence horizon and required count; TraceRecorder.register returns that action’s ActionCapture.
2. Capture the action as it runs. Wrap each tool call in capture.attempt(), capture_tool or acall, and record the agent’s assessment exactly as it was stated. A run can register several actions.
3. Obtain independent readback. Query your system of record through a separate read-only path, with source, scope, completeness, watermark and effect-origin metadata; poll_readback re-reads a lagging source.
4. Verify it. Use the built-in RecordVerifier for rows, orders or tickets, or implement the explicit Verifier interface for another domain. The receipt records which effects match the target, and any domain findings. An outcome with several required effects is one all_of or any_of contract, checked part by part by CompositeVerifier with one readback per source.
5. Explain and act. explain(trace) judges each action from its receipts; retry_advice says whether a retry would duplicate an effect.
6. Or let your framework report its tool calls. Optional extras record calls from the OpenAI Agents SDK (consequential_tool), LangChain (ConsequaCallbackHandler) and the Claude Agent SDK (consequa_hooks) for the calls you mark as consequential. consequa-x otel-export writes a trace as OpenTelemetry spans.

The downloadable SQLite agent loop runs a scripted support agent against a real local database, captures it with TraceRecorder and checks the refund with RecordVerifier. Its other modes are other_actor and stale_readback. No money moves; the refund is a row in a local file.

python agent_loop_sqlite.py --mode timeout_after_commit --output agent-run

The artifact-delivery adapter implements a verifier by hand. In your application, read back through an independently authenticated adapter; do not copy the requested state into the readback.

Keep uncertainty intact.

Schema validation checks structure and identity linkage. Your application establishes source authentication, provider guarantees and the truth of supplied metadata. A report cannot supply those guarantees.

unknown, other_actor and unassessable conclusions remain distinct. Missing readback is not a successful verification. Research replay interfaces carry their own assumptions; the package does not claim baseline superiority or improved live-model accuracy.

Platform validation is recorded for environments actually checked. A pure-Python wheel alone does not establish compatibility with every platform.