📋 DecisionTrace — Append-Only Flight Data Recorder for AI Decisions

DecisionTrace is an append-only audit log and flight data recorder for multi-step AI systems and autonomous agents. It creates an immutable, tamper-evident cryptographic hash chain of every decision made by an AI model, enabling post-incident forensics, compliance verification, and step-by-step decision replay.

---

📌 Why DecisionTrace?

As autonomous agents execute financial trades, generate code, contact customers, and manipulate databases, organizations face a critical accountability dilemma: how do you prove why an AI model took a specific action?

DecisionTrace records:

• The exact model & parameters used (temperature, checkpoint).
• The exact prompt & context sources ingested.
• The model's output, confidence score, and internal risk flags.
• A SHA-256 cryptographic hash chain where every decision cryptographically binds to the previous record. Any tampering with past records breaks the hash verification chain.

---

🔒 Cryptographic Hash Chain Architecture

Record #1 (Genesis)
[ timestamp, model, prompt, output, risk_flags ]
Hash: a1b2c3...
       |
       v (prev_hash)
Record #2
[ timestamp, prev_hash: a1b2c3..., model, prompt, output ]
Hash: d4e5f6...
       |
       v (prev_hash)
Record #3
[ timestamp, prev_hash: d4e5f6..., model, prompt, output ]
Hash: 789abc...

If an attacker or corrupted process alters even a single character in Record #1, Record #2's recorded prev_hash will fail verification, exposing the tampering immediately.

---

📁 Repository Structure

DecisionTrace/
├── src/decisiontrace/
│   ├── __init__.py         # Package version & metadata
│   ├── cli.py              # Click command-line interface
│   ├── logger.py           # Thread-safe append-only JSONL logger
│   ├── hasher.py           # SHA-256 cryptographic chaining engine
│   ├── replay.py           # Step-by-step decision replay module
│   └── schema.py           # Strict decision telemetry schema definition
├── logs/
│   └── decision_log.jsonl  # Append-only immutable log store
├── pyproject.toml          # Build configuration & package metadata
├── requirements.txt        # Runtime dependencies
├── LICENSE                 # MIT License
└── README.md

---

🚀 Getting Started

1. Installation

Clone the repository and install DecisionTrace in editable mode:

git clone https://github.com/Tarunjit45/DecisionTrace.git
cd DecisionTrace

pip install -e .

2. Log an AI Decision

Prepare a JSON payload (decision.json):

{
  "model": "gpt-4o",
  "config": { "temperature": 0.2 },
  "prompt": "Evaluate loan eligibility for applicant ID 9821",
  "context_sources": ["credit_score_db", "income_verification_api"],
  "output": "Loan Approved with 6.5% APR",
  "confidence": 0.94,
  "risk_flags": []
}

Log the decision via CLI:

decisiontrace log decision.json

3. Verify Integrity

Audit the log file to mathematically verify that no past decisions have been modified or deleted:

decisiontrace verify

4. Replay Decision Chains

Replay historical decisions for debugging and compliance audits:

decisiontrace replay --limit 10

---

📄 License

This project is licensed under the MIT License.