# agentcap
`agentcap` is a cost guardrail for LLM agent runs. It calculates safe token limits before execution and enforces strict budget ceilings using real usage data.

---

Github:
https://github.com/OliverIida/agentcap

PyPI:
https://pypi.org/project/agentcap/

---

## Install

```bash
pip install agentcap
```

---

## Example usage
```python
from agentcap import AgentCap

prompt = "Write 2 lines about Tallinn."

cap = AgentCap(
    model="gpt-5",
    budget_usd=0.05,
)

plan = cap.plan(prompt_text=prompt)

# Pass plan.max_output_tokens into your LLM call

actual_cost = cap.finalize(
    prompt_tokens=response_prompt_tokens,
    output_tokens=response_output_tokens,
)

print("Actual cost (USD):", actual_cost)
```

---

## Documentation
https://github.com/OliverIida/agentcap/blob/main/DOCUMENTATION.md

---

## Supported models
https://github.com/OliverIida/agentcap/blob/main/agentcap/models.json
To add more models, open a PR.

Note: Prices may change. Please verify with the provider.

---

## Model pricing sources
OpenAI pricing: https://developers.openai.com/api/docs/pricing?latest-pricing=standard  
Anthropic pricing: https://platform.claude.com/docs/en/about-claude/pricing  
Gemini pricing: https://ai.google.dev/gemini-api/docs/pricing#standard
