Decision Trace V1.1 — Adoption Polish Release
Status: Implementation-ready
Scope: Developer experience, examples, and integration accelerators
Compatibility: Fully backward-compatible with V1 schema and architecture
0. Purpose
V1.1 is an adoption-focused release.
It introduces no architectural changes to Decision Trace.
The schema, append-only model, and core tracer semantics remain unchanged.
The goal is to:
- deliver a 5-minute “dopamine demo”
- provide flagship examples that teach the mental model
- reduce friction for agent builders via integration adapters
V1.1 optimizes first contact with Decision Trace.
1. Non-goals
V1.1 explicitly does NOT introduce:
- schema changes
- mutation semantics
- distributed storage
- SaaS features
- dashboards
- breaking API changes
All V1 invariants remain locked.
2. CLI: 5-minute dopamine demo
2.1 decision-trace dev
Starts a local collector in dev mode.
Behavior:
- launches FastAPI collector on localhost
- writes to local JSONL ledger
- initializes SQLite index if available
- prints:
Must start in <1 second.
No config required.
2.2 decision-trace inspect <trace_id>
Default mode prints compact decision tree:
- parent hierarchy
- decision_type
- terminal outcome/error
- event counts
Example:
2.3 decision-trace inspect –verbose
Verbose mode adds:
- timestamps
- actor info
- evidence keys + values
- policy results
- approvals
- actions
- causal links
- conformance warnings
Example structure:
Verbose mode is the primary demo surface.
2.4 decision-trace inspect –last
Resolves most recent trace_id and prints it.
No arguments required.
3. Flagship examples
All examples must run with:
No manual setup required.
3.1 Example A — Refund workflow (polished)
Path:
Graph:
classify → approve → execute
Must include:
- evidence
- policy check
- action
- outcome
- at least one causal link
Purpose:
Teach parent decision graph + semantic events.
3.2 Example B — Agent approval chain
Path:
Graph:
AI proposal → human approval → system execution
Decisions:
- agent.proposal.generate.v1
- human.approval.review.v1
- system.execution.apply.v1
Features demonstrated:
- decision.approval event
- human actor
- action event
- branching approval outcome
Human step is simulated:
Purpose:
Show governance + human-in-the-loop pattern.
3.3 Example C — Policy failure + evaluation later
Path:
Script 1:
- emits denied decision due to policy failure
Script 2:
- emits decision.evaluation referencing prior decision
Shared state stored in:
Purpose:
Demonstrate:
- audit trail
- policy denial
- post-hoc learning loop
4. Integration adapters
Adapters reduce friction for agent builders.
All adapters must preserve:
- append-only semantics
- schema conformance
- non-blocking behavior
- zero behavior modification
Tracing must never change execution semantics.
4.1 Generic decorator
File:
API:
@decision_traced(decision_type="x.y.z.v1")
def fn(...):
...
Behavior:
- wraps function in decision context
- captures optional args as evidence
- success → outcome
- exception → error
Purpose:
Zero-friction instrumentation for Python code.
4.2 OpenAI tool wrapper
File:
API:
@openai_tool_decision_traced(...)
def tool(...):
...
Adds:
- tool metadata evidence
- action event for tool call
Purpose:
Agent builders can instrument tools automatically.
4.3 LangChain callback handler
File:
Drop-in handler mapping:
- chain start → decision.start
- tool call → decision.action
- chain end → outcome
- error → decision.error
Purpose:
LangChain compatibility with minimal code.
4.4 LangGraph node wrapper
File:
API:
node = decision_traced_node(fn)
Wraps graph node execution in decision context.
Purpose:
Graph-native agent tracing.
5. README requirements
README front page must include:
- 5-minute quickstart
- decision-trace dev instructions
- inspect demo output
- example links
- integration overview
- builder prompt template
Keep README short and executable.
6. Builder prompt template
Include verbatim:
Install Decision Trace and instrument major agent decisions.
Wrap decision points in a decision() context or decorator.
Record evidence, policy checks, actions, approvals, and outcomes.
Do not change behavior — only add tracing.
Ensure events remain append-only and schema compliant.
This enables viral distribution via coding agents.
7. Release checklist
Before publishing V1.1:
- dev collector runs reliably
- inspect works in verbose mode
- 3 examples run end-to-end
- README quickstart verified
- LICENSE included
- CONTRIBUTING.md included
- version bumped
- no failing tests
Optional follow-ups allowed post-release.
8. Success criteria
A developer can:
- install SDK
- run example
- inspect decision graph
- understand structure
- imagine use in their own agent
in under 5 minutes.
If this happens, V1.1 succeeds.
End of V1.1 spec.