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

contracts/functional/rates.md

@@ -0,0 +1,30 @@
+# Model Rate Registry
+
+`llm_connect.rates` owns static model list prices used for planning and
+post-hoc estimates.
+
+## Contract
+
+- `ModelRate` records `model_id`, prompt and completion rates in USD per
+  1,000 tokens, `currency`, `source_url`, and `captured_at`.
+- `ModelRateRegistry.default()` returns the bundled OpenRouter snapshot
+  captured on `2026-05-17`.
+- `ModelRateRegistry.from_yaml(path)` accepts the package/consumer override
+  shape:
+
+```yaml
+schema_version: 1
+currency: USD
+source_url: https://openrouter.ai/models
+captured_at: "2026-05-17"
+rates:
+  openai/gpt-4o-mini:
+    prompt_per_1k: 0.00015
+    completion_per_1k: 0.00060
+```
+
+- `merged_with(override)` returns a new registry where matching override
+  entries replace default entries by `model_id`.
+
+Rates are a static snapshot. Consumers decide whether `captured_at` is fresh
+enough for their workflow.