Metadata-Version: 2.1
Name: tracedeck
Version: 0.1.0
Summary: Structured agent decision logs: replay, decision-point diff, golden regression checks, failure-to-test extraction
License: MIT
Keywords: ai,agents,observability,debugging,eval,llm
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# tracedeck — structured decision logs for AI agents

The debugging fix for "the 200 status code that is completely wrong". Agents
don't crash — they confidently execute the wrong plan. The only artifact is a
100k-token context window no human can audit. tracedeck replaces it with a
git-like decision log: every decision point is a structured record written to
a known directory by convention, replayable, diffable, and convertible into
regression tests.

## Why

- **Traces alone are unreadable.** A single turn is 3-15 LLM calls; a failed
  run at turn 40 is 80k+ tokens. Structured decision records — decision,
  rationale, sources, confidence, cost — turn debugging into "check the
  decision log", not "read the context window".
- **Decision-point diffing barely exists.** When you change a prompt or swap
  a model, you need to know *which* decision points changed and in what
  direction — the agent equivalent of a code diff.
- **The eval-debugging loop is the discipline that scales.** Every resolved
  failure becomes a test case; every test case that fails triggers an
  investigation. `failures` closes that loop automatically.

## Record schema

One JSON object per line, `runs/<run_id>.jsonl`:

```json
{"run_id": "r1", "step": 3, "decision": "use_get_pipeline_logs",
 "rationale": "deploy failure is in the pipeline, not the image",
 "sources": ["ops/run-4821.log"], "confidence": 0.91, "cost": 0.012,
 "tool_calls": [{"tool": "get_pipeline_run_logs"}], "status": "done",
 "model": "claude-sonnet", "timestamp": "2026-08-15T12:00:00+00:00"}
```

Required: `run_id`, `step`, `decision`. Optional: everything else.

## Usage

```bash
./tracedeck init ~/traces

# agents append records (flags or --stdin for JSON)
./tracedeck record ~/traces --run-id r1 --step 1 --decision use_lookup \
    --rationale "well index docs exist" --sources '["pvt/black-oil.md"]' \
    --confidence 0.9 --cost 0.001
echo '{"run_id":"r1","step":2,"decision":"escalate","status":"failed"}' \
    | ./tracedeck record ~/traces --stdin

./tracedeck replay ~/traces r1          # git-log-style rendering
./tracedeck diff ~/traces r1 r2         # decision-point diff (exit 1 if differs)
./tracedeck golden ~/traces r1          # mark known-good run
./tracedeck check ~/traces r2           # regression detection vs golden
./tracedeck failures ~/traces r1        # extract failed steps -> eval test cases
./tracedeck runs ~/traces               # list runs + decision-point counts
```

`diff`/`check` exit non-zero on divergence, so CI can gate on agent regressions.
