Architecture

Overview

Briefcase AI is a layered system. The Python package you install (briefcase-ai) is the SDK surface — the @capture decorator, configuration, and pure-Python feature modules. Underneath, a PyO3 binding crate exposes a native extension module (briefcase._native) backed by a fast Rust core (~11K lines, the briefcase-core crate) that provides high-performance decision tracking, replay, drift, cost, sanitization, and SQLite storage.

graph TD
    A[Python package: briefcase-ai] --> B[PyO3 bindings: briefcase._native]
    B --> C[Rust core: briefcase-core]
    C --> D[SQLite storage backend]

Diagram description

A top-down stack of four layers. The Python package briefcase-ai calls the PyO3 bindings briefcase._native, which call the Rust core briefcase-core, which in turn reads and writes the SQLite storage backend.

Rust Core (briefcase-core)

The core crate lives in crates/briefcase-core and exposes feature-gated modules:

• models - DecisionSnapshot, Input, Output, ModelParameters, and related types
• storage - the SQLite storage backend (SqliteBackend)
• replay - the deterministic replay engine
• drift - drift and consistency calculation
• cost - token-cost estimation and budget checks
• sanitization - PII detection and redaction

Feature flags (recording, async, storage, replay, drift, sanitize, otel, tokens, and others) control which modules compile. The Python extension is built with the full feature set.

PyO3 Bindings (briefcase._native)

The bindings/python crate (briefcase-python, library name briefcase_native) uses PyO3 and maturin to compile the Rust core into the briefcase._native extension module. The native-backed Python modules (briefcase.cost, briefcase.drift, briefcase.sanitize, briefcase.storage, briefcase.replay) import their classes from this extension.

Python Package (briefcase-ai)

The Python layer adds:

• the @capture decorator, which records a lightweight decision dict and ships it through an exporter
• configuration via setup(), init(), and BriefcaseConfig
• pure-Python feature modules: validation, guardrails, RAG versioning, correlation, events, external-data tracking, routing, bitemporal primitives, and audit bundles
• an optional lakeFS integration (briefcase.integrations.lakefs) — one bundled versioned-data source; others plug in through the generic VCS protocol

Capture and Replay Flow

The @capture decorator and the native runtime layer are separate paths. @capture records a dict and hands it to an exporter; persistence and replay use the native DecisionSnapshot objects directly.

sequenceDiagram
    participant App
    participant Capture as capture decorator
    participant Exporter

    App->>Capture: call function
    Capture->>App: function result
    Capture->>Exporter: export decision dict

Diagram description

A sequence across App, the capture decorator, and the Exporter. The App calls the wrapped function through the capture decorator, which returns the result to the App and then exports the recorded decision dict to the Exporter.

sequenceDiagram
    participant App
    participant Storage as SqliteBackend
    participant Replay as ReplayEngine

    App->>Storage: save_decision(snapshot)
    Storage-->>App: decision_id
    App->>Replay: replay(decision_id, mode)
    Replay->>Storage: load snapshot
    Replay-->>App: ReplayResult

Diagram description

A sequence across App, the SqliteBackend, and the ReplayEngine. The App saves a snapshot to storage and receives a decision_id, then asks the ReplayEngine to replay that id; the engine loads the snapshot from storage and returns a ReplayResult to the App.

Next steps

Core Concepts How snapshots, capture, and replay fit together in practice.

Decision Recording Record structured decisions that flow through these layers.