Metadata-Version: 2.4
Name: agenticstack-costs
Version: 0.1.0
Summary: Token and cost tracking harness for AgenticStack: per-agent usage, USD estimates, and budgets
Author: The AgenticStack Authors
License: Apache-2.0
Requires-Python: >=3.11
Requires-Dist: agenticstack>=0.2.0
Description-Content-Type: text/markdown

# agenticstack-costs

Token and cost tracking harness for [AgenticStack](https://github.com/AiConglomerate/AgentStack).

Accumulates prompt/completion/total tokens, call counts, and estimated
USD spend per agent (and overall) by watching every LLM call through
`MONITOR`-priority hooks — the same interception surface every
marketplace plugin uses. Nothing is transformed; it only counts.

## Install

```bash
pip install agenticstack-costs
```

## Use

```python
from agenticstack_costs import CostTracker

tracker = CostTracker(budget_usd=5.00).install()

# ... run any agents ...

print(tracker.report())
# {
#   "per_agent": {"Helper": {"calls": 3, "prompt_tokens": 2100,
#                            "completion_tokens": 640, "total_tokens": 2740,
#                            "cost_usd": 0.0021}},
#   "total": {..., "runs": 3},
#   "unpriced_calls": 0,
#   "over_budget": False,
# }

tracker.reset()      # zero the counters
tracker.uninstall()  # detach cleanly
```

Or as a plugin (`CostsPlugin`), activated by the plugin runtime; pass
`budget_usd` through plugin config.

## Pricing table

`PRICES` maps model-name prefixes to `(input, output)` USD per 1M tokens
for `gpt-4o`, `gpt-4o-mini`, `claude-3-5-sonnet`, `claude-3-5-haiku`,
`gemini-1.5`, and `llama`. The longest matching prefix wins
(`gpt-4o-mini-2024...` prices as `gpt-4o-mini`, not `gpt-4o`). The
numbers are **estimates** of public list prices — verify against your
provider before relying on them. Models with no matching prefix cost
`0.0` and increment the `unpriced_calls` counter.

## Budgets are soft

`budget_usd` is tracking only: when the estimated total exceeds it, the
tracker logs a warning and sets `over_budget = True`. **It never blocks
or stops anything** — pair it with a guard plugin if you need hard
enforcement.

## Permissions

None — pure in-memory accounting.
