Metadata-Version: 2.4
Name: decision-trace-reconstructor
Version: 0.1.2
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://decisiontrace.org/reconstructor/v0.1.0
Project-URL: Changelog, https://decisiontrace.org/reconstructor/v0.1.0/changelog
Project-URL: DOI, https://doi.org/10.5281/zenodo.19851574
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)
- [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>.

## License

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