fuseboxie 0.1.4

Fuseboxie Python SDK for guarding AI calls and tracking token usage from backend applications.

Fuseboxie Python SDK

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

Install

pip install fuseboxie

Package Checks

Run the release check before publishing:

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:

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

Usage

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:

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:

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.

FastAPI Helper

FastAPI apps can attach Fuseboxie once as ASGI middleware, then guard and track from each route with the request object:

from fastapi import FastAPI, HTTPException, Request
from fuseboxie import init
from fuseboxie.fastapi import (
    FuseboxieBlockedError,
    FuseboxieMiddleware,
    guard_ai_request,
    header_value,
    track_openai_response,
)

app = FastAPI()
fuseboxie = init(project_key="pk_live_123", api_url="https://api.fuseboxie.com")

app.add_middleware(
    FuseboxieMiddleware,
    client=fuseboxie,
    user_id_getter=header_value("x-user-id"),
    customer_id_getter=header_value("x-customer-id"),
    role_getter=header_value("x-user-role"),
)

@app.post("/chat", name="chat")
def chat(request: Request):
    try:
        guard_ai_request(request, estimated_tokens=2000, estimated_cost_usd=0.02)
    except FuseboxieBlockedError as error:
        raise HTTPException(status_code=429, detail=str(error)) from error

    response = openai_client.chat.completions.create(...)
    track_openai_response(request, response)
    return {"ok": True}

The FastAPI helper is optional. It does not add FastAPI as a package dependency; it works when imported inside a FastAPI or Starlette app.

Flask Helper

Flask apps can attach Fuseboxie once with init_app, then guard and track from each route without repeating user/customer headers in every SDK call:

from flask import Flask, jsonify
from fuseboxie import init
from fuseboxie.flask import (
    FuseboxieBlockedError,
    guard_ai_request,
    header_value,
    init_app,
    track_anthropic_response,
)

app = Flask(__name__)
fuseboxie = init(project_key="pk_live_123", api_url="https://api.fuseboxie.com")

init_app(
    app,
    client=fuseboxie,
    user_id_getter=header_value("x-user-id"),
    customer_id_getter=header_value("x-customer-id"),
    role_getter=header_value("x-user-role"),
)

@app.post("/chat", endpoint="chat")
def chat():
    try:
        guard_ai_request(estimated_tokens=2000, estimated_cost_usd=0.02)
    except FuseboxieBlockedError as error:
        return jsonify({"error": str(error)}), 429

    response = anthropic_client.messages.create(...)
    track_anthropic_response(response)
    return jsonify({"ok": True})

The Flask helper is optional. It imports Flask only when Flask helpers are used.

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.