pip install nullspend

from nullspend import NullSpend

# Reads NULLSPEND_API_KEY from environment
ns = NullSpend()

# Or provide explicitly
ns = NullSpend(api_key="ns_live_sk_...")

from openai import OpenAI
from nullspend import NullSpend

ns = NullSpend(
    api_key="ns_live_sk_...",
    cost_reporting={}  # enable batching
)

# Wrap OpenAI — costs are tracked automatically
openai = OpenAI(http_client=ns.openai)

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)
# Cost event is calculated locally and reported in the background

from nullspend import NullSpend, CostEventInput

ns = NullSpend(api_key="ns_live_sk_...")

ns.report_cost(CostEventInput(
    provider="openai",
    model="gpt-4o",
    input_tokens=500,
    output_tokens=150,
    cost_microdollars=4625,
))

# Minimal — reads API key from NULLSPEND_API_KEY env var
ns = NullSpend()

# Explicit keyword arguments
ns = NullSpend(
    api_key="ns_live_sk_...",
    max_retries=3,
    request_timeout_s=60.0,
)

# Using config dataclass
from nullspend import NullSpendConfig

config = NullSpendConfig(
    api_key="ns_live_sk_...",
    max_retries=3,
)
ns = NullSpend(config=config)

with NullSpend(api_key="...") as ns:
    ns.report_cost(...)
# HTTP client is automatically closed, cost reporter is flushed

from openai import OpenAI
from anthropic import Anthropic
from nullspend import NullSpend

ns = NullSpend(
    api_key="ns_live_sk_...",
    cost_reporting={},  # required for tracked clients
)

# Shorthand properties — pre-configured httpx.Client for each provider
openai = OpenAI(http_client=ns.openai)
anthropic = Anthropic(http_client=ns.anthropic)

tracked = ns.create_tracked_client(
    "openai",
    customer="acme-corp",
    session_id="task-042",
    tags={"team": "backend"},
    enforcement=True,
    session_limit_microdollars=5_000_000,  # $5 per session
)

openai = OpenAI(http_client=tracked)

tracked = ns.create_tracked_client("openai", enforcement=True)

openai = OpenAI(http_client=tracked)

try:
    openai.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello"}],
    )
except BudgetExceededError as e:
    print(f"Budget: ${e.remaining_microdollars / 1_000_000:.2f} remaining")
except MandateViolationError as e:
    print(f"Mandate: {e.mandate} blocks {e.requested}")
except SessionLimitExceededError as e:
    print(f"Session: ${e.session_spend_microdollars / 1_000_000:.2f} of ${e.session_limit_microdollars / 1_000_000:.2f}")

final_client = ns.create_tracked_client("openai", finalize=True)

# This request can use the finalization reserve
response = final_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Summarize and save results"}],
)

from nullspend.errors import BudgetExceededError

try:
    response = tracked.chat.completions.create(...)
except BudgetExceededError as e:
    print(e.finalization_reserve_microdollars)   # Reserve amount, or None
    print(e.finalization_remaining_microdollars)  # Remaining after reserve, or None

session = ns.customer("acme-corp")

# Pre-configured httpx.Client for each provider, attributed to the customer
openai = OpenAI(http_client=session.openai)
anthropic = Anthropic(http_client=session.anthropic)

# With enforcement and session limits
session = ns.customer(
    "acme-corp",
    enforcement=True,
    session_id="task-042",
    session_limit_microdollars=5_000_000,
    tags={"team": "backend"},
    on_denied=lambda reason: print(reason),
)

from nullspend import AsyncNullSpend

async with AsyncNullSpend(api_key="ns_live_sk_...") as ns:
    summary = await ns.get_cost_summary("30d")
    print(f"Total: ${summary.totals['totalCostMicrodollars'] / 1_000_000:.2f}")

    action = await ns.create_action(CreateActionInput(
        agent_id="support-agent",
        action_type="send_email",
        payload={"to": "user@example.com"},
    ))

    decision = await ns.wait_for_decision(action.id, timeout_s=300.0)

ns = NullSpend(
    api_key="ns_live_sk_...",
    cost_reporting=CostReportingConfig(
        batch_size=10,           # flush every 10 events
        flush_interval_ms=5000,  # or every 5 seconds
        max_queue_size=1000,     # drop events if queue is full
    ),
)

# Queue events — sent in batches automatically
ns.queue_cost(CostEventInput(
    provider="openai", model="gpt-4o",
    input_tokens=500, output_tokens=150, cost_microdollars=4625,
))

# Explicit flush and shutdown
ns.flush()     # drain queue immediately
ns.shutdown()  # flush + stop background thread

from nullspend import CostEventInput

result = ns.report_cost(CostEventInput(
    provider="anthropic",
    model="claude-sonnet-4-6",
    input_tokens=1000,
    output_tokens=500,
    cost_microdollars=6750,
    # Optional fields:
    cached_input_tokens=200,
    reasoning_tokens=0,
    duration_ms=1200,
    session_id="session-123",
    trace_id="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
    event_type="llm",        # "llm" | "tool" | "custom"
    tool_name="search",
    tool_server="rag-server",
    tags={"team": "backend"},
    customer="acme-corp",
))

result = ns.report_cost_batch([
    CostEventInput(provider="openai", model="gpt-4o", input_tokens=500, output_tokens=150, cost_microdollars=4625),
    CostEventInput(provider="openai", model="gpt-4o-mini", input_tokens=1000, output_tokens=300, cost_microdollars=225),
])

from nullspend import calculate_openai_cost_event, calculate_anthropic_cost_event

# From an OpenAI response
event = calculate_openai_cost_event(
    model="gpt-4o",
    usage={"prompt_tokens": 500, "completion_tokens": 150},
    duration_ms=1200,
)

# From an Anthropic response (with cache details)
event = calculate_anthropic_cost_event(
    model="claude-sonnet-4-6",
    usage={"input_tokens": 1000, "output_tokens": 500},
    cache_creation_detail={"cache_creation_tokens": 200},
    duration_ms=800,
)

# Check if a model is known
from nullspend import is_known_model, get_model_pricing
is_known_model("openai", "gpt-4o")  # True
get_model_pricing("openai", "gpt-4o")  # {"inputPerMTok": 2.5, "outputPerMTok": 10.0, ...}

from nullspend import CreateActionInput

response = ns.create_action(CreateActionInput(
    agent_id="support-agent",
    action_type="send_email",
    payload={"to": "user@example.com", "subject": "Refund"},
    metadata={"ticket_id": "T-1234"},
    expires_in_seconds=1800,
))
print(response.id, response.status)  # "ns_act_..." "pending"

action = ns.get_action("ns_act_550e8400-...")
print(action.status)  # "pending" | "approved" | "rejected" | ...

from nullspend import MarkResultInput

# Start executing
ns.mark_result(action_id, MarkResultInput(status="executing"))

# Report success
ns.mark_result(action_id, MarkResultInput(
    status="executed",
    result={"rows_deleted": 42},
))

# Or report failure
ns.mark_result(action_id, MarkResultInput(
    status="failed",
    error_message="Connection timeout",
))

decision = ns.wait_for_decision(
    action_id,
    poll_interval_s=2.0,   # default: 2.0
    timeout_s=300.0,        # default: 300.0 (5 min)
    on_poll=lambda action: print(action.status),
)

from nullspend import ProposeAndWaitOptions

def execute(context):
    # Runs only after human approval.
    # context["action_id"] can be sent as X-NullSpend-Action-Id to correlate costs.
    return delete_old_logs()

result = ns.propose_and_wait(ProposeAndWaitOptions(
    agent_id="data-agent",
    action_type="db_write",
    payload={"query": "DELETE FROM logs WHERE age > 90"},
    execute=execute,
    expires_in_seconds=3600,
    poll_interval_s=2.0,
    timeout_s=300.0,
))

from nullspend import RequestBudgetIncreaseOptions

result = ns.request_budget_increase(RequestBudgetIncreaseOptions(
    agent_id="data-agent",
    amount_microdollars=10_000_000,  # request $10 increase
    reason="Need more budget for batch processing",
    entity_type="user",
    entity_id="user-123",
    poll_interval_s=2.0,
    timeout_s=600.0,
))
print(result.action_id, result.requested_amount_microdollars)

status = ns.check_budget()

for entity in status.entities:
    print(
        f"{entity.entity_type}/{entity.entity_id}: "
        f"${entity.spend_microdollars / 1_000_000:.2f} / ${entity.limit_microdollars / 1_000_000:.2f}"
    )

result = ns.list_budgets()

for budget in result.data:
    spent = budget.spend_microdollars / 1_000_000
    limit = budget.max_budget_microdollars / 1_000_000
    print(f"{budget.entity_type}/{budget.entity_id}: ${spent:.2f} / ${limit:.2f}")

summary = ns.get_cost_summary("30d")  # "7d" | "30d" | "90d"

print(f"Total spend: ${summary.totals['totalCostMicrodollars'] / 1_000_000:.2f}")
print(f"Total requests: {summary.totals['totalRequests']}")

from nullspend import ListCostEventsOptions

# Get the last 10 cost events
result = ns.list_cost_events(ListCostEventsOptions(limit=10))

for event in result.data:
    print(f"{event.model}: {event.input_tokens} in / {event.output_tokens} out — ${event.cost_microdollars / 1_000_000:.4f}")

# Paginate with cursor — pass it straight back, no json.dumps needed
if result.cursor:
    next_page = ns.list_cost_events(ListCostEventsOptions(limit=10, cursor=result.cursor))

from nullspend import NullSpendError

try:
    ns.create_action(...)
except NullSpendError as err:
    print(err.status_code)  # 409
    print(err.code)          # "invalid_action_transition"

from nullspend import (
    BudgetExceededError,
    MandateViolationError,
    LoopDetectedError,
    PlanLimitExceededError,
)

try:
    openai.chat.completions.create(model="gpt-4o", messages=[...])
except BudgetExceededError as err:
    print(f"${err.remaining_microdollars / 1_000_000:.2f} remaining")
    if err.upgrade_url:
        print(f"Upgrade at: {err.upgrade_url}")
except MandateViolationError as err:
    print(f"{err.mandate}: {err.requested} not in {err.allowed}")
except LoopDetectedError as err:
    print(f"Loop blocked: {err.call_count}/{err.max_calls} calls in {err.window_seconds}s")
except PlanLimitExceededError as err:
    print(f"Plan cap hit ({err.count}/{err.block_at}). Upgrade: {err.upgrade_url}")

from nullspend import (
    # Clients
    NullSpend,
    AsyncNullSpend,
    CostReporter,

    # Configuration
    NullSpendConfig,
    CostReportingConfig,

    # Actions
    CreateActionInput,
    CreateActionResponse,
    ActionRecord,
    MarkResultInput,
    MutateActionResponse,
    ProposeAndWaitOptions,
    RequestBudgetIncreaseOptions,
    BudgetIncreaseResult,

    # Cost reporting
    CostEventInput,
    CostEventRecord,
    CostBreakdown,

    # Cost calculation
    calculate_openai_cost_event,
    calculate_anthropic_cost_event,
    get_model_pricing,
    is_known_model,

    # Tracked clients
    create_tracked_client,
    CustomerSession,
    validate_customer_id,

    # Budgets
    BudgetStatus,
    BudgetEntity,
    BudgetRecord,
    ListBudgetsResponse,

    # Cost awareness (read)
    ListCostEventsResponse,
    ListCostEventsOptions,
    CostSummaryResponse,

    # Errors
    NullSpendError,
    PollTimeoutError,
    RejectedError,
    BudgetExceededError,
    MandateViolationError,
    SessionLimitExceededError,
    VelocityExceededError,
    TagBudgetExceededError,
)