Python SDK

pip install briefcase-ai For: engineers building governed agents

This is the narrative guide

This page walks through the SDK by example. For exhaustive class, method, and parameter signatures, see the Python API reference.

Install

pip install briefcase-ai

Import Paths

from briefcase import (
    capture,
    observe,
    setup,
    init,
    init_with_config,
    is_initialized,
    enable_logging,
    set_log_level,
    disable_logging,
    get_logger,
    BriefcaseConfig,
    DecisionSnapshot,
    Snapshot,
    SnapshotQuery,
    Input,
    Output,
    ModelParameters,
    ExecutionContext,
    HardwareMetadata,
)
from briefcase.cost import CostCalculator, CostEstimate, BudgetStatus
from briefcase.drift import DriftCalculator, DriftMetrics
from briefcase.sanitize import Sanitizer
from briefcase.storage import SqliteBackend, BufferedBackend
from briefcase.replay import ReplayEngine, ReplayPolicy, ReplayResult, ReplayStats
from briefcase.validation import PromptValidationEngine, ValidationReport
from briefcase.external import ExternalDataTracker, SnapshotPolicy, SnapshotFrequency
from briefcase.routing import AgentRouter, PolicyRegistry, PolicyVersion, PolicyRule
from briefcase.events import BriefcaseEvent, emit
from briefcase.bitemporal import BitemporalRecord, InMemoryBitemporalStore, AsOfView
from briefcase.compliance import ExaminerBundle
from briefcase.exporters import BaseExporter

The @capture Decorator

from briefcase import capture

@capture(decision_type="ticket-classification")
def classify_ticket(text: str) -> str:
    return "billing"

@capture records a lightweight dict for every call — inputs, outputs, and timing — and hands it to an exporter. It does not persist a DecisionSnapshot; to store and replay structured decisions, build a DecisionSnapshot and use SqliteBackend (see Core Concepts).

Configuration

setup() wires up exporters, routing, events, storage, and other components and returns a BriefcaseConfig. There is no configure() function.

from briefcase import setup

config = setup(
    exporter=None,
    router=None,
    webhook_url=None,
    storage=None,
)

Start the native runtime once with init(), or use init_with_config() instead to set worker threads. BriefcaseConfig.get() returns the active configuration.

from briefcase import init, is_initialized, BriefcaseConfig

init()  # start the runtime (use init_with_config(worker_threads=4) instead to size the pool)

print(is_initialized())
config = BriefcaseConfig.get()

Logging

Silent by default

The top-level briefcase logger has only a NullHandler attached, so importing the package emits nothing. Opt in when you want to see what the SDK is doing. These functions are in the base package — no extra required.

import briefcase

# Opt in to briefcase logs on stderr (default level "INFO").
briefcase.enable_logging("DEBUG")

# Change the level later without re-adding a handler.
briefcase.set_log_level("WARNING")

# Use the same logger tree in your own modules.
log = briefcase.get_logger(__name__)
log.warning("classification fell back to default category")

# Turn briefcase logging back off and restore silence.
briefcase.disable_logging()

enable_logging(level="INFO", *, stream=None, fmt=None, datefmt=None) returns the briefcase logger and adds a single StreamHandler (idempotent). Pass stream=, fmt=, or datefmt= to control where and how records are formatted. set_log_level(level) adjusts the level in place. disable_logging() removes the handler. get_logger(__name__) returns a child of the briefcase logger so your own modules inherit the same configuration.

Set BRIEFCASE_LOG_LEVEL to enable logging automatically at import — useful for turning on diagnostics without touching code:

BRIEFCASE_LOG_LEVEL=DEBUG python app.py

Extras

Install only what you need. See Installation for the full extras table.

Lazy Imports

Optional submodules import only when their backing code is available. Pure-Python extras (replay, validate, correlation, external) report a missing extra:

ImportError: briefcase.replay requires the 'replay' extra.
Install it with: pip install briefcase-ai[replay]

Native-backed modules (cost, drift, sanitize, storage) instead ask you to reinstall or rebuild the native extension:

ImportError: briefcase.storage could not load the native extension. Reinstall the package (pip install --force-reinstall briefcase-ai) or rebuild from source with 'maturin develop'.

Next steps

Python API Reference Full signatures for every public symbol, grouped by module.

Exporters Wire captured decisions to console, file, or a custom backend.