Briefcase AI SDK

License: Apache-2.0

Open-source decision tracking for AI.

Install

pip install briefcase-ai

Quick Example

import briefcase

briefcase.observe("console")          # send records to stderr (or "memory" / "runs.jsonl")

@briefcase.capture(decision_type="classify_text")
def classify(text: str) -> str:
    return text.upper()

classify("hello world")               # a decision record is emitted

capture works immediately — no briefcase.init() required. Call init() only when you use the native runtime features (storage backends, snapshots). Without a call to briefcase.observe(...) (or briefcase.setup(exporter=...)), @capture records decisions but has nowhere to send them.

Exporters. briefcase.observe(...) accepts "console", "memory" (records collected on exporter.records), a "*.jsonl" path, or any briefcase.exporters.BaseExporter instance — subclass BaseExporter to ship records to your own backend.

Evaluations and RL

Two bridges emit decision records from work that is not a single function call. Both use the exporter you already configured.

from briefcase.integrations.evals import EvalRun, from_inspect_log, replay

with EvalRun("gsm8k", model="claude-opus-5") as run:   # one eval.case per case,
    run.log_case("q1", inputs=q, outputs=a, passed=a == target)   # one eval.run
print(run.summary()["pass_rate"])

replay(from_inspect_log("logs/2026-08-12_gsm8k.eval"))  # inspect-ai .json/.eval

The parsers are stdlib only and never import the eval framework, so a log can be replayed on a machine that has neither installed. See examples/eval_runs/.

from briefcase.integrations.gym import GuardrailGymEnv, capture_episodes

env = GuardrailGymEnv(guardrail, tasks, injections)  # a guardrail as a gym.Env
env = capture_episodes(env)                          # rl.step / rl.episode records

Needs pip install briefcase-ai[gym]. See examples/rl_gym/.

capture_episodes exports on a background thread by default, since step capture is on the hot path. A script that exits right after close() can lose its records; pass capture_episodes(env, async_capture=False) in short runs. EvalRun already defaults to async_capture=False for that reason.

Logging

The library is silent by default (it installs only a NullHandler). Turn on visible logs explicitly:

import briefcase
briefcase.enable_logging("DEBUG")     # or set BRIEFCASE_LOG_LEVEL=DEBUG

Using with AI tools (Cursor, Claude Code, Codex, …)

This repo ships machine-readable usage guidance: llms.txt / llms-full.txt, an AGENTS.md, and copy-paste editor rules under docs/llm/. An MCP server is available via pip install briefcase-ai[mcp] then briefcase-mcp.

Extras

Extra Description
replay Deterministic replay engine for recorded decisions
drift Drift scoring and cost calculation for model outputs
sanitize Built-in PII redaction utilities
otel OpenTelemetry helpers
storage Rust-backed SQLite storage engine
validate Prompt validation engine
guardrails Guardrail framework, wrappers, and registries
rag Versioned embedding pipeline and instrumented retrieval
correlation Workflow and trace correlation helpers
external External data snapshot tracking
events Structured event type and emitter interface
routing Router protocol, agent router, versioned policy registry
lakefs lakeFS versioned storage client
vcs VCS client base protocol
gym Gymnasium bridge: guardrail env adapter and RL episode capture
evals Eval-harness bridge: EvalRun logger, inspect-ai / lm-eval parsers (adds zstandard for .eval archives on Python < 3.14)
bitemporal Bitemporal evidence store, as-of views, append-only corrections
bitemporal-iceberg pyiceberg-backed bitemporal store (any supported catalog)
compliance Examiner bundles joining decision, evidence, and policy version
mcp MCP server (briefcase-mcp) exposing the SDK to AI agents
dev Dev tooling: pytest, mypy, flake8
all Installs every optional extra listed above

Most features are native- or pure-Python-backed and ship with the base package — their extras (replay, drift, sanitize, storage, routing, bitemporal, compliance, …) are convenience groupings that pull in no additional dependencies. Only otel, lakefs, bitemporal-iceberg, gym, evals, and mcp install third-party packages.

Enterprise features

The OSS SDK ships everything needed to run the end-to-end walkthrough, persist evidence to SQLite or Iceberg, and pass an internal audit. The following features require the commercial briefcase-ai-sdk-enterprise package:

Feature OSS Enterprise
In-memory, SQLite, pyiceberg backends ✓
kdb+ backend (pykx client) stub only ✓
Managed-catalog connectors (Glue, Snowflake Horizon, Databricks Unity, Confluent Tableflow) ✓
Licensed market data ingest (Bloomberg BPIPE, Refinitiv, ICE) ✓
Signed content-hash envelopes (AWS KMS, GCP KMS, YubiHSM) ✓
WORM retention integration (S3 Object Lock, Azure Blob immutable, MinIO) ✓
Multi-tenant PolicyRegistry with RBAC and approvals ✓
Cross-region evidence replication, DR runbooks ✓
Regulator-format bundle exporters (SEC SDR, FCA, OCC, FINRA) ✓
SOC 2 Type II / FedRAMP attestations, 24/7 SLA support ✓

Contact sales@briefcasebrain.com for enterprise access.

Telemetry

The SDK can report anonymous usage metrics (SDK version, OS, architecture, backend type) to help prioritize development. No personal data or decision content is ever collected. Telemetry is only transmitted when a collection endpoint is configured via BRIEFCASE_API_URL (it defaults to localhost, i.e. a no-op), and you can disable it entirely at any time:

export BRIEFCASE_TELEMETRY=0   # also accepts: false, no, off (case-insensitive)

Links

Project links

Data verified by PyPI on Aug 12, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (4.1.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for aanshshah from gravatar.com aanshshah

Credits

Author: Briefcase AI

GitHub Statistics

Data verified by PyPI on Aug 12, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

Apache-2.0
View SPDX License List

Requires

Python >=3.9

Provides Extra

all bitemporal bitemporal-iceberg compliance correlation dev drift evals events external guardrails gym lakefs mcp otel rag replay routing run sanitize storage validate vcs

Tags

ai observability decision-tracking replay drift

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

briefcase_ai-4.0.0.tar.gz (238.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

briefcase_ai-4.0.0-cp39-abi3-win_amd64.whl (7.5 MB view details)

Uploaded CPython 3.9+Windows x86-64

briefcase_ai-4.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.1 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

briefcase_ai-4.0.0-cp39-abi3-macosx_11_0_arm64.whl (7.7 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

briefcase_ai-4.0.0-cp39-abi3-macosx_10_12_x86_64.whl (7.8 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file briefcase_ai-4.0.0.tar.gz.

File metadata

  • Download URL: briefcase_ai-4.0.0.tar.gz
  • Upload date:
  • Size: 238.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for briefcase_ai-4.0.0.tar.gz
Algorithm Hash digest
SHA256 029c7ced998aa1e64ce5ffc84214bf58208fcad9ea5f8445a8888518c6aae9f4
MD5 e2b8a95258b7adcf5c195e7efb4faa6f
BLAKE2b-256 d8b6e2443d89d0ac15b41c218be3a172ae0f00ccb851115f1b650801076f9420

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.0.0.tar.gz:

Publisher: publish.yml on briefcasebrain/briefcase-ai-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file briefcase_ai-4.0.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: briefcase_ai-4.0.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 7.5 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for briefcase_ai-4.0.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 7d6534bc392690f0b20660e9c072c649968c91574ca9013a16d97b8eaa23a7b0
MD5 fda92a78013c3d5e03a9a7f36d82b6b1
BLAKE2b-256 e016f20cf570e7a31851d49e064a597088735c43f7517bb28b9d53edfece40cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.0.0-cp39-abi3-win_amd64.whl:

Publisher: publish.yml on briefcasebrain/briefcase-ai-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file briefcase_ai-4.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f36639dc4e89f32290f10220e0306501bb5f628c813da0521c88ca9141435ae2
MD5 615c6f34fbca28ffc998727d461a50ba
BLAKE2b-256 788d72e680d28d15adfebee5fbd5b7a0e217e2df067b077c5e2ffae893177c2a

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.0.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on briefcasebrain/briefcase-ai-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file briefcase_ai-4.0.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.0.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c8d6dd55b9b9667a4db8007e93e4d7b77926f1ae731d6cdd2a25ca700c9a082e
MD5 fa2eb92722e0e9a7e66bfdaf3d539903
BLAKE2b-256 2972664fb588fef3272a3af611b2d98e96c590df7a24aecf673dddf26c66bef0

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.0.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on briefcasebrain/briefcase-ai-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file briefcase_ai-4.0.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.0.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 911762b7db74843e244766deb975eee7146c5a6e5ef4e9478c921a6569617812
MD5 60a5439044a5c432a3d4cbe510b72e20
BLAKE2b-256 12ccb208791263f6139a43f5cb1c3d701e724c3b1780288b4c9d29ab0c331cee

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.0.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on briefcasebrain/briefcase-ai-sdk

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page