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 14, 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:
Latest release

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 14, 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.1.0.tar.gz (248.5 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.1.0-cp39-abi3-win_amd64.whl (7.5 MB view details)

Uploaded CPython 3.9+Windows x86-64

briefcase_ai-4.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (8.2 MB view details)

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

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

Uploaded CPython 3.9+macOS 11.0+ ARM64

briefcase_ai-4.1.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.1.0.tar.gz.

File metadata

  • Download URL: briefcase_ai-4.1.0.tar.gz
  • Upload date:
  • Size: 248.5 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.1.0.tar.gz
Algorithm Hash digest
SHA256 d9f47862f023ac251b14af6d6374b5c541eca22ce6cc1007f900eb85dd0ac8fe
MD5 94a1749eeba0317c46b714a9131047c9
BLAKE2b-256 eef556f694d223785edb1932fad2f57a86552a8acfa22bfb2da7a8b181504b1b

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.1.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.1.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: briefcase_ai-4.1.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.1.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ca6380fd3d3a9eb3364a0be6b2e3e1731a11744ea1a19b848bd8b01db76d6ff6
MD5 75834d61f67919a08d0d4ee286cc35c2
BLAKE2b-256 13522de15905720b5671b9513ddd29856d74c6ea78f56af74fb4865a57e62caa

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.1.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.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.1.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 d4738fc48e06f9d64505ccd94114cdae0d97598b9e1cd7a5a4b48ccb21a07b3b
MD5 aefde94ab76e503153f8bedba65d59e1
BLAKE2b-256 33d024ccce277661f489b9c2510e77c7c50b6d9233ddd1ce8f4aa4296a6716cf

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.1.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.1.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.1.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9df772d9656190b141a33efcb557cecc60c5b8bf6b9e14f58a0fbccce5899437
MD5 86869bd7d6c380d8c5d360fb1c7ecf5a
BLAKE2b-256 7f290400307f0b2d83489fade5c21b343ad5fbb52f6d3183b0b229ccc18df855

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.1.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.1.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for briefcase_ai-4.1.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6ebf3fbcef5ea858ea2c07c3c5f4fd0cf43e03d8c59fdef1df9637e9ecf81f5b
MD5 a05eb7c9a427fbb4e63403abb3485f16
BLAKE2b-256 58b0d4d8694590c6319b8d7ef1714af264abb635f36d3c0b019473da9c23ff73

See more details on using hashes here.

Provenance

The following attestation bundles were made for briefcase_ai-4.1.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