Metadata-Version: 2.4
Name: fuseboxie
Version: 0.1.1
Summary: Fuseboxie Python SDK for guarding AI calls and tracking token usage from backend applications.
Project-URL: Homepage, https://fuseboxie.com
Author: Fuseboxie
License-Expression: MIT
Keywords: ai,analytics,cost-control,fuseboxie,guardrails,tokens,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Fuseboxie Python SDK

Backend SDK for tracking AI usage and blocking AI calls when a Fuseboxie guard rule says no.

## Install

```bash
pip install fuseboxie
```

## Package Checks

Run the release check before publishing:

```bash
npm run check
```

That command runs unit tests, compiles the SDK/examples, removes old package artifacts, and builds both the wheel and source distribution in `dist/`.

After publishing, verify the public package and send one smoke event:

```bash
pip install --upgrade fuseboxie
set FUSEBOXIE_PROJECT_KEY=fbxi_live_your_project_key
python scripts/smoke_pypi_usage.py
```

## Usage

```python
from fuseboxie import init

fuseboxie = init(
    project_key="pk_live_123",
    api_url="https://api.fuseboxie.com",
    guard_failure_mode="throw",
    request_timeout=3,
)

result = fuseboxie.can_use_ai(
    user_id="user_123",
    customer_id="customer_123",
    role="trial",
    estimated_tokens=2000,
    estimated_cost_usd=0.02,
    operation="chat.completion",
)

if not result["allowed"]:
    raise RuntimeError(result.get("reason") or "AI usage is blocked.")

response = openai_client.chat.completions.create(...)

fuseboxie.track_openai(
    response,
    user_id="user_123",
    customer_id="customer_123",
    role="trial",
    operation="chat.completion",
)
```

When `api_url` is configured, `init()` automatically sends a lightweight setup check to Fuseboxie. This lets the Fuseboxie dashboard mark the project as connected as soon as your backend starts.

If you want to wait for that setup check during a smoke test, call:

```python
fuseboxie.wait_for_setup_check(timeout=10)
```

`guard_failure_mode` controls what happens if Fuseboxie cannot be reached before an AI call:

- `throw` fails the current request with an SDK error. This is the default.
- `allow` lets the AI call continue when the guard service is unavailable.
- `block` blocks the AI call when the guard service is unavailable.

## Provider Helpers

- `track_openai(response, **context)` maps `usage.prompt_tokens`, `usage.completion_tokens`, `usage.total_tokens`, and the newer `usage.input_tokens` / `usage.output_tokens` shape.
- `track_anthropic(response, **context)` maps `usage.input_tokens` and `usage.output_tokens`.
- `track_gemini(response, **context)` maps `usageMetadata.promptTokenCount`, `usageMetadata.candidatesTokenCount`, and `usageMetadata.totalTokenCount`.

You can still call `track_usage()` manually when you already have normalized token counts:

```python
fuseboxie.track_usage(
    provider="openai",
    model="gpt-4.1-mini",
    input_tokens=1200,
    output_tokens=420,
    user_id="user_123",
    customer_id="customer_123",
    role="trial",
    operation="chat.completion",
)
```

Role is stored as safe metadata so role-based reports and limits can work.

## Framework Examples

The package includes examples for common Python backends:

- `examples/fastapi.py`
- `examples/flask.py`
- `examples/django_view.py`

The SDK validates and normalizes usage events. It can send guard checks and usage events to the Fuseboxie API with `api_url`, and transports are injectable for custom testing or forwarding.
