feat(pricing): add models.dev fallback source

[IvGolovach]

Summary

• Add models.dev as a third upstream pricing dataset alongside LiteLLM and OpenRouter.
• Cache the parsed models.dev dataset in the existing pricing cache layer and reuse stale cached data when live fetches are unavailable.
• Use models.dev only as a provider-aware fallback so custom overrides, LiteLLM, OpenRouter, and existing Cursor overrides keep their current precedence.
• Expose models.dev through tokscale pricing --provider models.dev for direct pricing inspection.

Why

Tokscale can miss cost estimates when a newer model appears in models.dev before it is represented in LiteLLM or OpenRouter. That creates avoidable zero-cost or unknown-cost reports even when a usable public pricing source already exists. This change expands coverage while keeping the existing source ordering intact: the new dataset fills gaps, but it does not shadow custom overrides or the established primary sources.

Diff scope

• crates/tokscale-core/src/pricing/models_dev.rs: adds the fetch, cache, retry, parser, and per-million-to-per-token conversion for the models.dev API.
• crates/tokscale-core/src/pricing/mod.rs: loads models.dev in parallel with the existing pricing sources, includes stale-cache recovery, and adds fixture-backed coverage for fallback cost calculation.
• crates/tokscale-core/src/pricing/lookup.rs: wires models.dev into exact, normalized, provider-aware, and prefix lookup paths after the existing primary sources.
• crates/tokscale-cli/src/main.rs: allows pricing --provider models.dev and renders the source label consistently.
• crates/tokscale-core/tests/fixtures/models_dev_pricing.json: adds a focused fixture for parser and precedence tests.

Branch integrity

• Base branch: main
• Validated base SHA: a86e688d620939d2c973c6d5625baa815ea223d7
• Ahead/behind against fetched origin/main: 0 behind / 1 ahead
• Merge base: a86e688d620939d2c973c6d5625baa815ea223d7
• Diff proof was computed against the fetched base.

Commit integrity

• Introduced commit: b7226c82827c7b8532803c3fdeb30467510f39d0 feat(pricing): add models.dev fallback source
• Final PR diff contains only the intended pricing-source integration, CLI provider option, and regression fixture changes.
• Ledger: not applicable - not required for selected validation mode/change family.
• Version: not applicable - not required for selected validation mode/change family.

Diff hygiene

• git diff --name-status origin/main...HEAD: M crates/tokscale-cli/src/main.rs, M crates/tokscale-core/src/pricing/lookup.rs, M crates/tokscale-core/src/pricing/mod.rs, A crates/tokscale-core/src/pricing/models_dev.rs, A crates/tokscale-core/tests/fixtures/models_dev_pricing.json
• git diff --check origin/main...HEAD: PASS, no output

Validation mode and proof

• Validation mode: Mode 3 - shared pricing behavior and user-visible cost calculation fallback.
• cargo test -p tokscale-core pricing::: PASS, 212 tests
• cargo check -p tokscale-cli: PASS
• cargo fmt --check: PASS
• curl -fsSL -A 'tokscale-pr-validation/1.0' https://models.dev/api.json | python3 -c '...': PASS, provider map with model objects and optional cost fields
• Full workspace test suite not run locally because the targeted pricing suite plus CLI compile check cover this diff, and remote PR CI should provide final full-gate status after the PR is opened.

CI context confirmation

• Pending - required GitHub Actions checks will run after the PR is created.
• CI workflow context names unchanged.

Runtime safety

• Reviewed changed runtime paths: pricing service fetch path, pricing cache fallback path, lookup precedence, and CLI pricing provider validation.
• The new live fetch runs in the existing async pricing fetch phase and degrades to an empty dataset when models.dev fails, preserving LiteLLM/OpenRouter behavior.
• Existing custom overrides and primary pricing sources retain precedence over models.dev.
• No new blocking locks, unbounded queues, database writes, or auth-sensitive paths were introduced.
• No invariant regression introduced.

Migration notes

Not applicable - no DB migration changed.

Documentation integrity

Not applicable - no docs or runbooks changed. The CLI help text for tokscale pricing --provider was updated with the new valid source.

Rollback plan

Rollback: revert this PR.
DB downgrade: not applicable.
Data repair: not applicable.
Operational caveats: reverting restores the previous LiteLLM/OpenRouter/custom-only pricing source set.

Known residual risks

• Remote CI has not run yet because the PR has not been opened.
• models.dev is an external best-effort data source; the implementation treats fetch or parse failures as non-fatal so existing pricing behavior remains available.

---

Summary by cubic

Add models.dev as a provider-aware fallback pricing source to fill gaps when LiteLLM or OpenRouter don’t have a model. Also adds CLI support to query it with tokscale pricing --provider models.dev.

• New Features

  • Integrates models.dev after custom overrides, LiteLLM, and OpenRouter (exact/normalized/prefix, provider-aware) without changing precedence.
  • Fetches with retry/backoff, parses per‑million to per‑token, caches results, and reuses stale cache on failures.
  • CLI: tokscale pricing --provider models.dev and updated provider validation/help.

• Bug Fixes

  • Corrected retry handling for models.dev to back off on 429/5xx and fail after max retries; still falls back to cached data when available.

^{Written for commit 37b5a06. Summary will update on new commits.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
tokscale	Ignored	Preview	Jun 1, 2026 10:35pm

[cubic-dev-ai]

1 issue found across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>