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==1.1.0
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; its ArtifactTargetMatcher can qualify matching through the separate explanation API.

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 remains 0.1. Package version and wire-schema version are separate; the version-1 core remains compatible.

Connect your application.

1. Declare the contract before the action. Define matching state, deadline, persistence horizon and required count.
2. Capture the action history. Retain dispatches, responses and the agent’s reported assessment.
3. Obtain independent readback. Capture source, scope, completeness, watermark and effect-origin metadata from a read-only adapter.
4. Implement your verifier. Interpret that domain’s evidence through the explicit Verifier interface.
5. Qualify alignment when appropriate. Supply an application TargetMatcher to explain(trace, target_matcher=...).

The downloadable artifact-delivery adapter demonstrates both interfaces using only public APIs. Replace its fixture with an independently authenticated read 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.