Metadata-Version: 2.4
Name: llm-cost-guard-py
Version: 0.1.0
Summary: Estimate LLM request cost and enforce per-request or per-session budgets. Python port of @mukundakatta/llm-cost-guard.
Project-URL: Homepage, https://github.com/MukundaKatta/llm-cost-guard-py
Project-URL: Issues, https://github.com/MukundaKatta/llm-cost-guard-py/issues
Project-URL: Source, https://github.com/MukundaKatta/llm-cost-guard-py
Project-URL: JS sibling, https://github.com/MukundaKatta/llm-cost-guard
Author-email: Mukunda Katta <mukunda.vjcs6@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,budget,claude,cost,gemini,llm,openai,tokens
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# llm-cost-guard

[![PyPI](https://img.shields.io/pypi/v/llm-cost-guard-py.svg)](https://pypi.org/project/llm-cost-guard-py/)
[![Python](https://img.shields.io/pypi/pyversions/llm-cost-guard.svg)](https://pypi.org/project/llm-cost-guard-py/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**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](https://github.com/MukundaKatta/llm-cost-guard).

## Install

```bash
pip install llm-cost-guard-py
```

## Usage

```python
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:

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

## Override or extend the price table

```python
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](https://github.com/MukundaKatta/llm-cost-guard) for the broader design notes.
