Metadata-Version: 2.4
Name: decision-trace-reconstructor
Version: 0.2.0
Summary: Audit agent decisions after the fact by turning raw traces into per-property reconstructability reports that identify evidenced, missing, and opaque decision facts.
Author: Oleg Solozobov
License-Expression: Apache-2.0
Project-URL: Homepage, https://decisiontrace.org/reconstructor
Project-URL: Documentation, https://github.com/governance-evidence/decision-trace-reconstructor/tree/main/docs
Project-URL: Changelog, https://github.com/governance-evidence/decision-trace-reconstructor/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/governance-evidence/decision-trace-reconstructor
Keywords: governance evidence,decision trace reconstruction,agentic AI governance,decision event schema,post-hoc audit
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: <4,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3,>=2.6
Provides-Extra: agentframework
Requires-Dist: autogen-agentchat<2,>=0.4; extra == "agentframework"
Requires-Dist: autogen-core<2,>=0.4; extra == "agentframework"
Provides-Extra: pydantic-ai
Requires-Dist: pydantic-ai<2,>=0.2; extra == "pydantic-ai"
Provides-Extra: parquet
Requires-Dist: pyarrow<25,>=15; extra == "parquet"
Provides-Extra: prov
Requires-Dist: rdflib<8,>=7; extra == "prov"
Provides-Extra: langsmith
Requires-Dist: langsmith<2,>=0.7; extra == "langsmith"
Provides-Extra: anthropic
Requires-Dist: anthropic<2,>=0.50; extra == "anthropic"
Provides-Extra: crewai
Requires-Dist: crewai<2,>=0.40; python_version < "3.14" and extra == "crewai"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.5; extra == "mcp"
Provides-Extra: bedrock
Requires-Dist: boto3<2,>=1.40; extra == "bedrock"
Provides-Extra: openai-agents
Requires-Dist: openai<3,>=2; extra == "openai-agents"
Requires-Dist: openai-agents<1,>=0.14; extra == "openai-agents"
Provides-Extra: otlp
Requires-Dist: opentelemetry-proto<2,>=1.27; extra == "otlp"
Provides-Extra: all
Requires-Dist: autogen-agentchat<2,>=0.4; extra == "all"
Requires-Dist: autogen-core<2,>=0.4; extra == "all"
Requires-Dist: anthropic<2,>=0.50; extra == "all"
Requires-Dist: boto3<2,>=1.40; extra == "all"
Requires-Dist: crewai<2,>=0.40; python_version < "3.14" and extra == "all"
Requires-Dist: langsmith<2,>=0.7; extra == "all"
Requires-Dist: mcp<2,>=1.5; extra == "all"
Requires-Dist: openai<3,>=2; extra == "all"
Requires-Dist: openai-agents<1,>=0.14; extra == "all"
Requires-Dist: opentelemetry-proto<2,>=1.27; extra == "all"
Requires-Dist: pydantic-ai<2,>=0.2; extra == "all"
Requires-Dist: pyarrow<25,>=15; extra == "all"
Requires-Dist: rdflib<8,>=7; extra == "all"
Provides-Extra: dev
Requires-Dist: autogen-agentchat<2,>=0.4; extra == "dev"
Requires-Dist: autogen-core<2,>=0.4; extra == "dev"
Requires-Dist: anthropic<2,>=0.50; extra == "dev"
Requires-Dist: boto3<2,>=1.40; extra == "dev"
Requires-Dist: build<2,>=1.0; extra == "dev"
Requires-Dist: crewai<2,>=0.40; python_version < "3.14" and extra == "dev"
Requires-Dist: langsmith<2,>=0.7; extra == "dev"
Requires-Dist: mcp<2,>=1.5; extra == "dev"
Requires-Dist: mypy<2,>=1.8; extra == "dev"
Requires-Dist: openai<3,>=2; extra == "dev"
Requires-Dist: openai-agents<1,>=0.14; extra == "dev"
Requires-Dist: opentelemetry-proto<2,>=1.27; extra == "dev"
Requires-Dist: pre-commit<5,>=3; extra == "dev"
Requires-Dist: pydantic-ai<2,>=0.2; extra == "dev"
Requires-Dist: pytest<10,>=7; extra == "dev"
Requires-Dist: pytest-cov<8,>=4; extra == "dev"
Requires-Dist: rdflib<8,>=7; extra == "dev"
Requires-Dist: ruff<1,>=0.4; extra == "dev"
Dynamic: license-file

# Decision Trace Reconstructor

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19851574.svg)](https://doi.org/10.5281/zenodo.19851574)

**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/`](docs/adapters/README.md). Each adapter supports offline file ingest; vendor-backed adapters also support live/network ingest when the optional extra and credentials are available.

| # | Adapter | Extra | Covers |
|---|---|---|---|
| 01 | [`langsmith`](docs/adapters/langsmith.md) | `[langsmith]` | LangChain / LangGraph ecosystem |
| 02 | [`otlp`](docs/adapters/otlp.md) | `[otlp]` | OpenTelemetry GenAI — one adapter, many backends |
| 03 | [`bedrock`](docs/adapters/bedrock.md) | `[bedrock]` | AWS Bedrock AgentCore |
| 04 | [`openai-agents`](docs/adapters/openai-agents.md) | `[openai-agents]` | OpenAI Agents SDK + Traces dashboard exports |
| 05 | [`anthropic`](docs/adapters/anthropic.md) | `[anthropic]` | Anthropic Messages API + Computer Use |
| 06 | [`mcp`](docs/adapters/mcp.md) | `[mcp]` | Model Context Protocol transcripts |
| 07 | [`crewai`](docs/adapters/crewai.md) | `[crewai]` | CrewAI multi-agent telemetry |
| 08 | [`agentframework`](docs/adapters/agentframework.md) | `[agentframework]` | Microsoft Agent Framework / AutoGen v0.4 |
| 09 | [`pydantic-ai`](docs/adapters/pydantic-ai.md) | `[pydantic-ai]` | Pydantic AI run records |
| 10 | [`generic-jsonl`](docs/adapters/generic-jsonl.md) | none | Custom JSONL logs via mapping config |

Unsupported source systems should use [`generic-jsonl`](docs/adapters/generic-jsonl.md) first. If OpenTelemetry GenAI spans are available, [`otlp`](docs/adapters/otlp.md) is usually the better long-term integration path.

## Quick Start

```bash
# 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:

```bash
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:

| Property | Category | Gap |
|---|---|---|
| `inputs` | `fully_fillable` | none |
| `policy_basis` | `structurally_unfillable` | active policy was not recorded |
| `reasoning_trace` | `opaque` | model reasoning is not externally observable |

## Documentation

- [Installation](docs/installation.md)
- [Adapter documentation](docs/adapters/README.md)
- [Reports and output artifacts](docs/reports.md)
- [Reconstruction architecture](docs/architecture.md)
- [v0.2.0 release notes and migration](docs/releases/0.2.0.md)
- [Development](docs/development.md)
- [Roadmap](docs/roadmap.md)

## 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>. That deposit identifies the original fixture evaluation, including the retained `results/` files. Version `0.2.0` is prepared for release; its version DOI will be recorded after archival publication. The later live-model study requires a separate replication deposit and must not be cited as part of v0.1.0.

## License

Apache-2.0. See [`LICENSE`](LICENSE).

## Evidence assessment contracts

The mapper separates topology from evidence visibility and record producers from action issuers. Existing manifests report structural coverage (`fragment-coverage-v2`). The opt-in `decision-evidence-v1` contract checks structured scope, request/receipt binding and independent state observations; it is not a general semantic or authentication verifier. See [the contract and examples](docs/evidence-contract.md). Historical v0.1.0 results and frozen V5 assessments remain tied to their preserved instruments.

## Replication study

See [the replication guide](docs/replication-study.md) for the immutable run inventory, portable offline reproduction command and local package preparation. Study data are delivered separately from the runtime wheel. The source distribution includes the experiment tools, but cannot recreate frozen model responses unless the replication data are supplied.
