# Briefcase AI Python SDK

Python SDK for AI observability, replay, and decision tracking.
`briefcase-ai` provides Rust-powered performance with a Python-native API.

[![Crates.io](https://img.shields.io/crates/v/briefcase-python.svg)](https://crates.io/crates/briefcase-python)
[![PyPI](https://img.shields.io/pypi/v/briefcase-ai.svg)](https://pypi.org/project/briefcase-ai/)

## Overview

Briefcase AI helps you:

- Capture AI decision inputs/outputs as structured snapshots
- Track estimated model costs and monitor drift signals
- Sanitize sensitive values before storage or transport
- Store, query, and replay decisions with SQLite or lakeFS backends

The package is built from the `briefcase-core` Rust runtime and exposed through PyO3 bindings.

## Installation

```bash
pip install briefcase-ai
```

For live lakeFS integrations:

```bash
pip install "briefcase-ai[lakefs]"
```

Requirements:

- Python `>=3.10`
- Rust toolchain only if building from source

Artifact note:

- Releases can include native wheels and a source distribution (sdist).
- If a wheel is unavailable for your environment, `pip` can install from sdist.

## Canonical Import Surface

Use `briefcase_ai` for all new code.
Compatibility aliases exposed in `briefcase_ai` include:

- `versioned`
- `lakefs_versioned`
- `versioned_context`
- `lakefs_context`
- `briefcase_workflow`

The legacy `briefcase` namespace remains available in `2.1.30` as a compatibility alias
and emits `DeprecationWarning`. Alias removal is planned for `2.1.31`.

## Quick Start

```python
import briefcase_ai

briefcase_ai.init()

decision = briefcase_ai.DecisionSnapshot("chat_completion")
decision.add_input(briefcase_ai.Input("prompt", "Summarize this text", "string"))
decision.add_input(briefcase_ai.Input("model", "gpt-4o-mini", "string"))
decision.add_output(
    briefcase_ai.Output("response", "Summary output", "string").with_confidence(0.94)
)
decision.with_execution_time(42.5)
decision.add_tag("environment", "prod")

storage = briefcase_ai.SqliteBackend.in_memory()
decision_id = storage.save_decision(decision)

loaded = storage.load_decision(decision_id)
print(loaded.function_name)
```

## Core Capabilities

### 1) Decision Snapshot Modeling

- `DecisionSnapshot`, `Input`, `Output`, `ModelParameters`, `ExecutionContext`
- Build reproducible records for AI decisions and annotate with tags/metadata

### 2) Storage and Query

- `SqliteBackend` for local/in-memory usage
- `LakeFSBackend` for versioned storage workflows
- Save/load/query snapshots and decision records

### 3) Drift Monitoring

```python
calculator = briefcase_ai.DriftCalculator()
metrics = calculator.calculate_drift(["answer A", "answer A", "answer B"])
print(metrics.consistency_score, metrics.drift_score)
```

### 4) Cost Estimation

```python
cost = briefcase_ai.CostCalculator()
estimate = cost.estimate_cost("gpt-4", 1200, 300)
print(estimate.total_cost, estimate.currency)
```

### 5) PII Sanitization

```python
sanitizer = briefcase_ai.Sanitizer()
result = sanitizer.sanitize("Email me at user@example.com")
print(result.sanitized)
```

### 6) Replay

- `ReplayEngine` can replay persisted snapshots/decisions from a configured backend
- Useful for debugging determinism and policy validation workflows

### 7) Feature Modules via `briefcase_ai`

The distribution exposes feature modules through `briefcase_ai.*`, including:

- `briefcase_ai.integrations` (lakeFS, framework handlers, VCS adapters)
- `briefcase_ai.correlation`
- `briefcase_ai.compliance`
- `briefcase_ai.rag`
- `briefcase_ai.external_data`
- `briefcase_ai.validation`

Optional provider libraries (for example Pinecone/Weaviate/Chroma or framework-specific SDKs)
may still be required at runtime depending on the integration you use.

## Documentation Links

- Product docs: <https://docs.briefcasebrain.com>
- Getting started: <https://docs.briefcasebrain.com/docs/getting-started/installation>
- Quick start: <https://docs.briefcasebrain.com/docs/getting-started/quickstart>

## License

This project is licensed under **GNU General Public License v3.0 (GPL-3.0-or-later)**.
See the [LICENSE](https://github.com/briefcasebrain/briefcase-ai-core/blob/main/LICENSE) file.
