Implement-LLM-WP-0005-cost-model-estimators

contracts/functional/costs.md

@@ -0,0 +1,25 @@
+# Cost Estimates
+
+`llm_connect.costs` converts token estimates or observed token counts into
+USD estimates using `ModelRateRegistry`.
+
+## Contract
+
+```python
+from llm_connect import estimate_cost
+
+estimate = estimate_cost("openai/gpt-4o-mini", 28_000, 7_500)
+```
+
+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>`.
+
+Unknown models return `CostEstimate(cost_usd=None, cost_source="unknown")`.
+Missing rates are never silently treated as zero cost.
+
+The module also exposes `CostModel(registry=...)` for callers that prefer to
+carry a registry object and call `model.estimate_cost(...)`.