Decision Trace Reconstructor

Decision Trace Reconstructor makes agent decisions auditable after the fact: it shows whether the available traces are enough to reconstruct what happened, and names every missing or opaque decision fact.

Instead of generating another narrative, it produces a per-property reconstructability matrix: which decision-event fields are evidenced, partial, structurally absent, or opaque. No synthetic rationale is invented.

Supported Adapters

Full adapter documentation lives in docs/adapters/. Each adapter supports offline file ingest; vendor-backed adapters also support live/network ingest when the optional extra and credentials are available.

Unsupported source systems should use generic-jsonl first. If OpenTelemetry GenAI spans are available, otlp is usually the better long-term integration path.

Quick Start

# 1. Install with the relevant adapter extra
pip install -e '.[langsmith]'   # or [otlp], [bedrock], [openai-agents], ...

# 2. Ingest a trace into a fragments manifest
decision-trace ingest langsmith --from-file traces/agent_run.json \
  --architecture single_agent --stack-tier within_stack \
  --state-mutation-tools "(write|exec|drop|delete|update)" \
  --out fragments.json

# 3. Reconstruct and emit evidence reports
decision-trace reconstruct fragments.json --out report/ --jsonld

Output:

• report/feasibility.json: per-property reconstructability categories, gap descriptions, and completeness percentage
• report/trace.jsonld: W3C PROV-O graph, queryable via SPARQL

Ingest can also be piped directly into reconstruction:

decision-trace ingest langsmith --from-file traces/run.json --out - | \
  decision-trace reconstruct /dev/stdin --out report/ --jsonld

Result Shape

The report is intentionally diagnostic, not narrative:

Documentation

• Installation
• Adapter documentation
• Reports and output artifacts
• Reconstruction architecture
• Development
• Roadmap

Examples

Worked examples live under examples/<adapter>_basic_agent/ and are pinned by integration tests for bit-identical reproduction. The named incident example examples/replit_drop_database/ shows reconstruction from a public-record fragment manifest.

Related Work Status

• Companion papers for the Decision Evidence Maturity Model and related evidence-regime concepts are in preparation. They are intentionally not cited as publications until public identifiers exist.
• Conceptual dependencies: the Decision Event Schema, the upstream Evidence Collector SDK, and the downstream Governance Benchmark Dataset.

Citation

CITATION.cff, codemeta.json, and ro-crate-metadata.json ship with the package. Version v0.1.0 is archived on Zenodo at https://doi.org/10.5281/zenodo.19851574.

License

Apache-2.0. See LICENSE.