Decision Trace

Open Standard for Decision Telemetry.

The project is actively evolving with new SDKs and integrations. Core telemetry concepts and event contracts are considered stable.

Decision Trace is an append-only ledger for recording the reasoning of systems. It captures decisions, evidence, policy checks, and outcomes in a structured, queryable graph.

---

⚡️ 5-Minute Quickstart

Python SDK

pip install decision-trace[collector]
decision-trace dev

decision-trace dev starts a local-only collector on 127.0.0.1:8711 and writes demo data to ./data/events.jsonl.

from decision_trace import decision

with decision("loan.approval", actor={"type": "system", "id": "risk_engine"}) as d:
    d.evidence("credit_score", 720)
    d.policy_check("min_score_700", "pass")
    d.outcome("approved")

Java SDK

Add the Spring Boot starter and point it at a collector. The endpoint below is a local/example placeholder, not a hosted service:

<dependency>
    <groupId>io.decisiontrace</groupId>
    <artifactId>decision-trace-spring-boot-starter</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

decision-trace:
  tenant-id: tenant-a
  environment: prod
  actor-id: auth-service
  collector-endpoint: http://collector:8080/v1/events

@Decision(decisionType = "AUTH_SERVICE_LOGIN", actorId = "auth-service")
AuthResponse login(LoginRequest request) {
    decisionContext.evidence("user_id", request.userId());
    decisionContext.policyCheck("risk_entry_policy", "continue");
    decisionContext.evaluation(Map.of("decision", "ALLOW"));
    return new AuthResponse("ALLOW");
}

---

🧠 What is a Decision?

A Decision is a unit of reasoning. Unlike a log (what happened) or a trace (how long), a Decision captures why. It is a is a semantic unit of business logic.

It captures:

1. Context: Who is acting? (Human, Agent, System)
2. Evidence: What data was used?
3. Logic: What policies were checked?
4. Outcome: What was the result?

Decisions exist in AI agents, but also in traditional APIs, services, risk engines, approval systems, and compliance pipelines.

See Core Concepts for more.

---

🎯 When to Use Decision Trace

Use Decision Trace when you need to answer:

• Why did the system invoke this tool?
• Which policy blocked this user?
• Did a human review this approval?

It is designed for:

• Agent Governance: tracking tool usage and reasoning.
• Human-in-the-Loop: linking AI proposals to human approvals.
• Policy Enforcement: proving compliance with business rules.

---

🏗 Architecture Principles

• Append-Only Ledger: History is immutable.
• Schema-First: All events are validated against a strict schema.
• Failure Isolation: Tracing failures never crash your app.

See Architecture for deep dive.

---

📚 Documentation

• Core Concepts - Logs vs Decisions, The DAG.
• Architecture - Ledger, Collector, Principles.
• Safety & Privacy - Evidence integrity, PII redaction.
• Migration Guide - Integrating with existing logging.
• Java SDK Overview - Spring Boot quickstart and module map.
• Python SDK Overview - Install, examples, and test commands.
• Collector Service - Local ingestion service and storage behavior.
• Java Runtime Architecture - Async runtime and fail-open guarantees.
• Java Golden Flow Walkthrough - Auth/risk/passkey sample flow.
• OTel Mapping Notes - Canonical event to span projection.

Examples

• Refund Workflow: Classify → Approve → Execute DAG.
• Agent Chain: AI Proposal → Human Review.
• Policy Failure: Recording denials.
• Java Golden Flow: Spring Boot auth/risk/passkey DAG.

---

🤝 Contributing, Attribution & License

Attribution

If you build on this framework or create a derivative project, we ask that you credit the original repository. Attribution helps sustain open-source work and signals respect for shared infrastructure.

Contributing

See CONTRIBUTING.md.

Validate Locally

Python:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[collector,test]"
pytest

Java:

cd sdk/java
mvn test
mvn test -pl decision-trace-samples -am

License

Licensed under the Apache License, Version 2.0 (the "License"). You may not use this project except in compliance with the License. See the LICENSE and NOTICE files for the full license text and intellectual property notices.

---

Trademarks

Decision Trace™ is a common law trademark of Shobha Sethuraman / logicoflife.

Initial Development: February 5, 2026

Public Release: February 7, 2026

Whitepaper Publication: February 9, 2026