unitcause 0.1.0

Python SDK for UnitCause — real-time cost governance for AI agents

UnitCause Python SDK

Real-time cost governance for AI agents. Set budgets. Stop loops. Ship confidently.

Installation

pip install unitcause

With framework integrations:

pip install unitcause[langchain]
pip install unitcause[crewai]
pip install unitcause[autogen]
pip install unitcause[all]

Quick Start

import os
from unitcause import UnitCause

# Set your API key
os.environ["UNITCAUSE_API_KEY"] = "uc_live_..."

uc = UnitCause()

# Wrap your agent run in a session
with uc.session(agent_name="data-analyst", budget=5.00) as session:
    # Run your agent — UnitCause tracks every LLM call
    result = agent.run("Analyze Q4 revenue trends")
    
    print(f"Total cost: ${session.total_cost:.4f}")
    print(f"Tokens used: {session.total_tokens:,}")
    print(f"LLM calls: {session.call_count}")

Async Support

import asyncio
from unitcause import UnitCause

uc = UnitCause()

async def run_agent():
    async with uc.session(agent_name="researcher", budget=2.00) as session:
        result = await agent.arun("Find top ML papers from 2025")
        print(f"Cost: ${session.total_cost:.4f}")

asyncio.run(run_agent())

Manual Step Tracking

If you're not using auto-instrumentation, you can manually report each LLM call:

with uc.session(agent_name="my-agent", budget=1.00) as session:
    # After each LLM call, report it
    response = session.report_step(
        action="llm_call",
        model="gpt-4o",
        tokens_in=500,
        tokens_out=200,
        cost_usd=0.0035,
    )
    
    # The response tells you whether to continue
    if response.action == "kill":
        print(f"Session killed: {response.reason}")
        break

Budget Callbacks

def on_warning(session, utilization):
    print(f"⚠️ Budget {utilization:.0%} used")

def on_exceeded(session, cost):
    print(f"🛑 Budget exceeded: ${cost:.4f}")
    return False  # Return True to allow continuing

with uc.session(
    agent_name="analyst",
    budget=5.00,
    on_budget_warning=on_warning,
    on_budget_exceeded=on_exceeded,
) as session:
    result = agent.run("...")

Health Check

status = uc.health_check()
print(status)
# {'status': 'connected', 'latency_ms': 42, 'version': '0.1.0'}

Configuration

Environment Variables

Variable	Default	Description
UNITCAUSE_API_KEY	—	Your API key
UNITCAUSE_BASE_URL	https://api.unitcause.com	API endpoint
UNITCAUSE_ENVIRONMENT	production	Environment label
UNITCAUSE_DISABLED	false	Disable all tracking
UNITCAUSE_LOG_LEVEL	WARNING	Logging level
UNITCAUSE_DEFAULT_BUDGET	—	Default session budget (USD)

Programmatic Configuration

from unitcause import UnitCause, Config

uc = UnitCause(
    api_key="uc_live_...",
    base_url="https://api.unitcause.com",
    environment="staging",
    disabled=False,
    log_level="DEBUG",
    retry_config={
        "max_retries": 3,
        "backoff_factor": 0.5,
    },
)

Exception Handling

from unitcause.exceptions import (
    BudgetExceededError,
    LoopDetectedError,
    AuthenticationError,
)

try:
    with uc.session(agent_name="agent", budget=1.00) as session:
        agent.run("...")
except BudgetExceededError as e:
    print(f"Budget exceeded: ${e.actual_cost:.4f} / ${e.budget_limit:.4f}")
except LoopDetectedError as e:
    print(f"Loop detected: {e.iteration_count} iterations")

Documentation

Full documentation at unitcause.com/docs

License

MIT — see LICENSE