# Cost Estimates

`llm_connect.costs` converts token estimates or observed token counts into
USD estimates using `ModelRateRegistry`, and optionally into EUR via
`llm_connect.fx`.

## Contract

```python
from llm_connect import estimate_cost

estimate = estimate_cost("openai/gpt-4o-mini", 28_000, 7_500)
estimate = estimate_cost("moonshotai/kimi-k3", 1_000, 500, fx=0.92)
```

For known models the result is:

- `cost_usd`: prompt plus completion estimate.
- `prompt_cost_usd`: prompt-token component.
- `completion_cost_usd`: completion-token component.
- `cost_source`: `rate_table:<model_id>`.
- `cost_eur` / `prompt_cost_eur` / `completion_cost_eur`: EUR display amounts
  when FX is available (default: bundled snapshot, override with `fx=` or
  env `LLM_CONNECT_EUR_PER_USD` as euros-per-USD).
- `fx_source`: how EUR was derived (`explicit`, `env:…`, `snapshot:…`).

Unknown models return `CostEstimate(cost_usd=None, cost_source="unknown")`
with EUR fields also `None`. Missing rates or FX are never silently treated
as zero cost.

Pass `apply_fx=False` to skip EUR conversion.

The module also exposes `CostModel(registry=..., fx=...)` for callers that
prefer to carry a registry object and call `model.estimate_cost(...)`.