Decision Recording

Decision recording captures the complete context behind every decision your AI system makes, so it can be replayed, audited, and verified later.

base install For: governance & audit

When you’d reach for this

A customer disputes how your triage agent routed their ticket three weeks ago. Without a record, you can only guess what the model saw and why. With decision recording, every classify_ticket call already kept its exact inputs, the label it returned, the model used, and a content fingerprint — so you can pull up that one decision and explain it.

Why persist a decision

A decision that vanishes the moment it runs can’t be replayed, audited, or proven. Recording it turns a fleeting model call into a durable, verifiable record:

• Replay — re-run the exact inputs later to check whether behavior changed.
• Audit — answer “what did the agent decide, and on what basis?” months later.
• Prove — the fingerprint() content hash makes tampering detectable.

There are two ways to record. The lightweight @capture decorator records a dict per call and hands it to an exporter. The native DecisionSnapshot builds a structured record you can persist and replay.

How recording flows

1. Capture — @capture wraps classify_ticket and records its inputs, outputs, timing, and type for each call.

2. Export — the recorded dict is handed to an exporter (console, a .jsonl file, or your own).

3. Persist — for storage and replay, build a native DecisionSnapshot and save it to a backend.

4. Replay & verify — later, load the snapshot, re-run it, and compare its fingerprint().

flowchart LR
  A["classify_ticket()"] -->|"@capture"| B["recorded dict"]
  B --> C[Exporter]
  A -->|"native API"| D[DecisionSnapshot]
  D --> E[Backend]
  E --> F["Replay & Verify"]

Diagram description

A classify_ticket call can be recorded two ways. The @capture decorator produces a lightweight dict that flows to an exporter for streaming and inspection. The native DecisionSnapshot is a structured record that is saved to a storage backend, which is what a later replay-and-verify step loads from.

Record a decision with @capture

The simplest way to record a decision is the @capture decorator. Pass an exporter to send each record somewhere:

from briefcase import capture
from briefcase.exporters import BaseExporter


class CollectingExporter(BaseExporter):
    def __init__(self):
        self.records = []

    async def export(self, decision):
        self.records.append(decision)
        return True

    async def flush(self):
        ...

    async def close(self):
        ...


exporter = CollectingExporter()


@capture(decision_type="classification", context_version="v1",
         exporter=exporter, async_capture=False)
def classify_ticket(text: str) -> str:
    # call your model here
    return "account_access"


classify_ticket("Reset my password")
print(exporter.records[0])

The decorator wraps the call, records a dict (decision id, inputs, outputs, timing, decision_type, context_version), and exports it through the exporter you pass. It does not persist a native DecisionSnapshot on its own; use the native objects below when you need storage or replay.

@capture parameters

Parameter	Default	Description
decision_type	None	Label for the kind of decision recorded
context_version	None	Version tag for the surrounding context or prompt
max_input_chars	1000	Truncate recorded inputs to this length
max_output_chars	1000	Truncate recorded outputs to this length
exporter	None	Exporter that receives each recorded dict
async_capture	True	Export off the calling thread

@capture works with or without arguments:

from briefcase import capture


@capture
def classify(text: str) -> str:
    # call your model here
    return "billing"

Emit records

@capture records a decision but has nowhere to send it until you configure an exporter. briefcase.observe() wires one up in a single line and returns it.

import briefcase

mem = briefcase.observe("memory")  # or "console", or a "*.jsonl" path


@briefcase.capture(decision_type="classification", async_capture=False)
def classify_ticket(text: str) -> str:
    # call your model here
    return "account_access"


classify_ticket("Reset my password")
print(mem.records[0])

Tip

@capture exports in a background thread by default. Pass async_capture=False when you want the record available synchronously — for example, to read MemoryExporter.records right after the call.

The per-call exporter= argument shown above overrides the global one set by observe(). See Exporters for the stock exporters and how to write a custom one.

Build a native DecisionSnapshot

When you need storage or replay, build a structured DecisionSnapshot:

from briefcase import DecisionSnapshot, Input, Output, ModelParameters

decision = DecisionSnapshot("classify_ticket")
decision.add_input(Input("text", "Reset my password", "string"))

params = ModelParameters("your-model")
params.with_provider("your-provider")
params.with_parameter("temperature", 0.0)
decision.with_model_parameters(params)

output = Output("category", "account_access", "string")
output.with_confidence(0.92)
decision.add_output(output)

decision.with_execution_time(12.5)
decision.with_module("triage_service")
decision.add_tag("environment", "production")

print(decision.function_name)
print(decision.fingerprint())

Fingerprints make a record verifiable

fingerprint() returns a stable hash over inputs, outputs, and model parameters. Store it alongside the record; recompute it later to detect when the same decision produces a different result — this is what makes a decision tamper-evident and replay-checkable.

digest = decision.fingerprint()        # stable content hash
# later, on a loaded snapshot:
assert loaded.fingerprint() == digest  # unchanged

Key classes

• @capture — decorator that records a dict and exports it
• DecisionSnapshot — structured record you can persist and replay; exposes fingerprint()
• Input / Output — typed wrappers; Output.with_confidence(score) attaches a confidence value
• ModelParameters — model name, provider, and per-call parameters
• Snapshot — groups multiple decisions; add_decision(decision) appends to it

Field	Description	Why it matters
function_name	The recorded function	Identifies which decision this is
inputs	Typed inputs	The exact inputs a replay re-runs against
outputs	Typed outputs	What the agent actually decided
tags	Arbitrary key/value tags	Carries your own context (e.g. environment, queue)
execution_time_ms	How long the call took	Anchors performance over time
fingerprint()	Content hash	Makes the record tamper-evident and verifiable

@capture vs DecisionSnapshot vs persisted storage

Three layers, each for a different need — pick by what you’re trying to do.

Use this	When you want to…	Lifetime
@capture decorator	Instrument a real function (like classify_ticket) with zero boilerplate and stream a lightweight record to an exporter	Per call
DecisionSnapshot	Build a structured record by hand — to persist, replay, or fingerprint it	In-memory object
Persisted backend (SqliteBackend)	Keep decisions durably so you can query, replay, and audit them weeks later	Durable

Note

@capture records a dict and exports it — it does not persist a native DecisionSnapshot on its own. For anything you’ll need to query or replay later, build a DecisionSnapshot and save it to a backend.

Persist a decision

Save a DecisionSnapshot to a storage backend so it can be queried or replayed later. This is the bridge from Capture into the Store & Query act.

import briefcase
from briefcase import DecisionSnapshot, Input, Output
from briefcase.storage import SqliteBackend

briefcase.init()

decision = DecisionSnapshot("classify_ticket")
decision.add_input(Input("text", "Reset my password", "string"))
decision.add_output(Output("category", "account_access", "string"))
decision.with_execution_time(12.5)

backend = SqliteBackend.in_memory()        # or SqliteBackend("decisions.db")
decision_id = backend.save_decision(decision)

restored = backend.load_decision(decision_id)
print(restored.function_name)

Where this fits

Next · Capture: Exporters Send each recorded decision to the console, a file, or your own backend.

Then · Store & Query: Storage Adapters Persist snapshots durably so you can query and replay them later.