chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,42 @@
+---
+summary: "models.dev pricing metadata pipeline, cache, lookup rules, and token-cost units."
+read_when:
+  - Updating models.dev pricing metadata support
+  - Debugging model-pricing cache refresh or lookup behavior
+  - Routing provider cost calculations through shared pricing metadata
+---
+
+# Model pricing metadata
+
+CodexBar has an additive models.dev pricing pipeline for future cost lookup work. Existing hardcoded pricing remains unchanged for now.
+
+## Source and cache
+
+- Source API: `https://models.dev/api.json`
+- No API key is required.
+- Local cache: `~/Library/Caches/CodexBar/model-pricing/models-dev-v1.json`
+- TTL: 24 hours
+
+The pipeline lets future scanner code read the last valid cache synchronously with `ModelsDevPricingPipeline.lookup` and refresh stale metadata separately with `ModelsDevPricingPipeline.refreshIfNeeded`. If a refresh fails, the last valid cache remains usable.
+
+## Lookup rules
+
+Pricing is scoped by provider id and model id. This prevents two providers with the same model id or display name from sharing pricing accidentally.
+
+Planned local source mapping:
+
+- Codex/OpenAI logs: models.dev provider id `openai`
+- Claude logs: models.dev provider id `anthropic`
+- Vertex AI Claude logs: models.dev provider id `google-vertex-anthropic`
+
+The first integration PR only adds the parser, client, cache, provider-scoped lookup, and tests. It does not route live cost calculations through models.dev yet.
+
+## Units
+
+models.dev publishes costs as USD per 1M tokens. CodexBar converts those to USD per token in the metadata layer:
+
+```text
+perToken = modelsDevCost / 1_000_000
+```
+
+When models.dev includes `cost.context_over_200k`, CodexBar parses those values as the above-200k-token pricing lane and converts them with the same per-1M-token rule.