# Briefcase AI Python SDK

Python SDK for AI observability, replay, and decision tracking. This package provides high-performance Rust-powered tools for monitoring and debugging AI applications in Python.

[![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

This Python SDK provides a complete toolkit for AI observability, decision tracking, and replay functionality. Built on a high-performance Rust core with Python bindings via [PyO3](https://pyo3.rs/), it offers the speed of Rust with the convenience of Python.

## Features

- **High Performance** - Rust core with minimal Python overhead
- **Memory Efficient** - Zero-copy operations where possible
- **Type Safe** - Full Python type hints and error handling
- **Async Support** - Async/await compatible operations

## Installation

Install the Python SDK using pip:

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

## Quick Start

```python
import briefcase_ai
import openai

# Initialize the SDK
briefcase_ai.init()

# Track an OpenAI API call
def track_openai_call(user_message: str) -> str:
    # Create decision snapshot
    decision = briefcase_ai.DecisionSnapshot("openai_chat")

    # Add input
    decision.add_input(briefcase_ai.Input("user_message", user_message, "string"))
    decision.add_input(briefcase_ai.Input("model", "gpt-3.5-turbo", "string"))

    # Make API call (your existing code)
    response = openai.ChatCompletion.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": user_message}]
    )

    ai_response = response.choices[0].message.content

    # Add output with confidence
    decision.add_output(
        briefcase_ai.Output("ai_response", ai_response, "string")
        .with_confidence(0.95)
    )
    decision.with_execution_time(response.usage.total_tokens * 0.1)  # Estimate

    # Save for analysis
    storage = briefcase_ai.SqliteBackend.file("ai_decisions.db")
    decision_id = storage.save_decision(decision)

    return ai_response

# Use it
result = track_openai_call("Explain quantum computing")
print(f"AI Response: {result}")
```

## Advanced Usage Examples

### 1. Model Performance Monitoring

```python
import briefcase_ai
from datetime import datetime

def monitor_model_performance():
    storage = briefcase_ai.SqliteBackend.file("model_performance.db")

    # Track multiple model variants
    models = ["gpt-3.5-turbo", "gpt-4", "claude-3"]

    for model in models:
        decision = briefcase_ai.DecisionSnapshot(f"comparison_test")
        decision.add_input(briefcase_ai.Input("prompt", "Write a poem", "string"))
        decision.add_input(briefcase_ai.Input("model", model, "string"))
        decision.add_tag("experiment", "model_comparison")
        decision.add_tag("timestamp", str(datetime.now()))

        # Your model call here...
        # decision.add_output(...)

        storage.save_decision(decision)
```

### 2. Cost Tracking for AI Operations

```python
import briefcase_ai

def track_ai_costs():
    # Initialize cost calculator
    cost_calc = briefcase_ai.CostCalculator()

    # Track costs for different models
    models_usage = [
        ("gpt-4", 1500, 800),  # model, input_tokens, output_tokens
        ("gpt-3.5-turbo", 2000, 1200),
        ("claude-3", 1800, 900)
    ]

    total_cost = 0
    for model, input_tokens, output_tokens in models_usage:
        cost_estimate = cost_calc.estimate_cost(model, input_tokens, output_tokens)
        total_cost += cost_estimate.total_cost

        print(f"{model}: ${cost_estimate.total_cost:.4f}")

    print(f"Total estimated cost: ${total_cost:.4f}")
```

### 3. Drift Detection

```python
import briefcase_ai

def detect_model_drift():
    # Monitor for changes in model outputs
    drift_calc = briefcase_ai.DriftCalculator()

    # Sample outputs from the same prompt over time
    outputs = [
        "The sky is blue because of light scattering",
        "The sky appears blue due to Rayleigh scattering",
        "Blue sky results from atmospheric light scattering",
        "The sky looks green"  # Anomaly!
    ]

    metrics = drift_calc.calculate_drift(outputs)
    print(f"Consistency score: {metrics.consistency_score:.2f}")

    if metrics.consistency_score < 0.8:
        print("⚠️ Potential model drift detected!")
```

### 4. Data Sanitization

```python
import briefcase_ai

def sanitize_sensitive_data():
    # Remove sensitive information before logging
    sanitizer = briefcase_ai.Sanitizer()

    user_input = "My email is john@example.com and SSN is 123-45-6789"

    # Sanitize the input
    result = sanitizer.sanitize(user_input)
    print(f"Original: {user_input}")
    print(f"Sanitized: {result.sanitized}")
    print(f"Patterns found: {result.patterns_found}")

    # Use sanitized version in your AI tracking
    decision = briefcase_ai.DecisionSnapshot("user_query")
    decision.add_input(briefcase_ai.Input("query", result.sanitized, "string"))
```

### 5. Replay and Debugging

```python
import briefcase_ai

def replay_ai_decision():
    storage = briefcase_ai.SqliteBackend.file("ai_decisions.db")

    # Load a previous decision
    decision_id = "decision-123"
    original_decision = storage.load_decision(decision_id)

    if original_decision:
        # Create replay engine
        replay_engine = briefcase_ai.ReplayEngine()

        # Replay the decision with same inputs
        replay_result = replay_engine.replay_decision(original_decision)

        if replay_result.is_deterministic:
            print("✅ Decision is reproducible")
        else:
            print("❌ Non-deterministic behavior detected")
            print(f"Differences: {replay_result.differences}")
```

## For Rust Developers

This crate is primarily used for building the Python extension. To use Briefcase AI in Rust, use the core library directly:

```toml
[dependencies]
briefcase-core = "2.0.4"
```

## Building

This crate requires:
- Rust 1.70+
- Python 3.10+
- PyO3 dependencies

Build the Python extension:

```bash
cd crates/python
maturin build --release
```

## Development

For development with maturin:

```bash
cd crates/python
maturin develop
```

Then test in Python:

```python
import briefcase_ai
print(briefcase_ai.__version__)
```

## Dependencies

- [`briefcase-core`](https://crates.io/crates/briefcase-core) - Core Rust library
- [`pyo3`](https://crates.io/crates/pyo3) - Python FFI bindings
- [`tokio`](https://crates.io/crates/tokio) - Async runtime

## License

MIT License - see [LICENSE](https://github.com/briefcasebrain/briefcase-ai-core/blob/main/LICENSE) file for details.

## Related Packages

- [`briefcase-ai`](https://pypi.org/project/briefcase-ai/) - Python package (end users)
- [`briefcase-core`](https://crates.io/crates/briefcase-core) - Core Rust library
- [`briefcase-wasm`](https://www.npmjs.com/package/briefcase-wasm) - WebAssembly bindings