Python client

The wire contract is plain HTTP JSON, so any language works. The bundled client adds three conveniences: a passthrough whitelist for per-call routing fields, the economics envelopes surfaced on every result, and typed budget refusals.

from costhelm.client import CosthelmClient, BudgetExceeded

async with CosthelmClient() as gw:                       # COSTHELM_BASE_URL or localhost:8111
    await gw.set_budget("session:run-42", 0.05, period="day")
    try:
        r = await gw.chat(
            "Summarise this in one line: ...",
            system="You are terse.",
            request={"session": "run-42", "auto_route": "worker", "max_tokens": 200},
        )
        print(r["text"])
        print(r["cost"]["total_usd"], r["router_decision"]["tier"])
    except BudgetExceeded as e:
        print("refused:", e.envelope["shortfall_usd"])

Design notes

• The client holds no provider credential. That boundary is the point: an agent runtime built on this client cannot leak a key it never had.
• request= is whitelisted. Only routing/economics fields pass through (provider, model, max_tokens, temperature, reasoning, auto_route, response_format, tools, tool_choice, escalate, cost_quality_tradeoff, semantic_cache, cache_system, and the five principal dimensions). Anything else is dropped before the wire — a caller’s config file cannot smuggle arbitrary fields.
• 402 is a typed exception. BudgetExceeded.envelope carries the numbers, so “over budget” is distinguishable from “broken” without parsing status codes.
• Auth: pass api_key= or set COSTHELM_API_KEY; sent as a bearer token.

Convenience reads

await gw.budget()                    # all armed ceilings
await gw.budget("session:run-42")    # one principal's view
await gw.cost_by_principal()         # spend grouped by dimension
await gw.cache_stats()               # semantic cache hit/save totals
await gw.health()

Source: costhelm/client.py (~170 lines, httpx only).