Docs

Capture a run. Open the break. Replay the path.

These docs describe the public TraceBreak surface: capture the run, inspect the event lineage, and replay the path that changed.

Quickstart

Run the loop locally

Point the runtime at memory, choose an OpenAI-compatible LLM endpoint, and execute a skill. Every step writes linked events that can be inspected later.

shell

export TRACEBREAK_MEMORY_URL=http://127.0.0.1:7777
export TRACEBREAK_MEMORY_KEY=<tenant-key>
export TRACEBREAK_LLM_URL=http://127.0.0.1:11434/v1
export TRACEBREAK_LLM_MODEL=qwen2.5-coder:7b

tracebreak run \
  --skill ./samples/triage.json \
  --tenant <tenant-id> \
  --goal "summarise the last hour of events"

API surface

Memory endpoints

The memory API stores typed events, searches embeddings, and traverses source links. Admin endpoints mint tenants and API keys for operators.

http

GET    /health
GET    /metrics
GET    /v1/whoami
POST   /v1/memory/event
POST   /v1/memory/search
POST   /v1/memory/cypher

POST   /v1/admin/tenants
POST   /v1/admin/keys
GET    /v1/admin/audit

Lineage

Source events are the spine

Every derived event should include `source_event_ids`. A replay can then walk backward from a final output to the exact evidence chain that shaped it.

json

{
  "kind": "observation",
  "embedding": [0.12, 0.41, 0.08, 0.67],
  "properties": {
    "text": "The deployment created a spike in failed tool calls.",
    "source_event_ids": [
      "1ff9917e-7d60-40bc-a811-ecf9f20a8d56",
      "a52e8a45-7584-4728-9dd6-ad80673a2368"
    ]
  }
}

Replay

Compare a counterfactual

Replay keeps the lineage constant and changes one variable: model, prompt, temperature, or state snapshot. The diff shows where behavior first changed.

shell

tracebreak inspect --event-id <event-id> --json > captured.json
tracebreak replay \
  --event-id <event-id> \
  --against-model gpt-4.1 \
  --diff captured.json

Event format

Keep events plain and linked

Events should be easy to audit: a kind, optional embedding, properties, and source links. The richer the source links, the better the replay.