llm-cost-guard

Estimate LLM call cost and enforce per-request or per-session budgets. Built-in price table for the major frontier models, override or extend at runtime. Zero runtime dependencies.

Python port of @mukundakatta/llm-cost-guard.

Install

pip install llm-cost-guard-py

Usage

from llm_cost_guard import Budget, BudgetExceeded, estimate

# 1. Estimate the cost of a call you're about to make.
cost = estimate(model="gpt-5", input_tokens=1200, output_tokens=400)
print(cost.usd)            # Decimal('0.0120')
print(cost.input_cost)     # Decimal('0.0060')
print(cost.total_tokens)   # 1600

# 2. Per-request and per-session budgets.
budget = Budget(
    max_usd_per_request="0.10",
    max_usd_per_session="5.00",
    mode="throw",          # "check" returns Decision instead of raising
)

try:
    decision = budget.check(cost)
    if decision.allowed:
        # ... call your model here ...
        budget.record(cost)
except BudgetExceeded as err:
    print("blocked:", err.decision.reason)

Don't have token counts yet? Pass raw text and a heuristic estimator runs:

estimate(model="claude-sonnet-4-5", input="long prompt here", output="model response")

Override or extend the price table

from llm_cost_guard import PRICES, register_model

register_model("my-self-hosted-llama", input_per_1k="0.0001", output_per_1k="0.0002")
PRICES["gpt-5"]["input"] = "0.004"   # bulk-discount tier

All amounts are decimal.Decimal for exact arithmetic; cast with float() when serializing.

API differences from the JS sibling

• estimate() takes Python keyword args (model=, input_tokens=, ...) and returns a Cost dataclass.
• enforce_budget() is preserved and accepts both Cost and the JS dict shape.
• Budget adds session-level tracking and a mode='throw' path -- not present in the JS package.

See the JS sibling's README for the broader design notes.