feat(api): add hidePaidModels setting to filter paid-only models from /v1/models catalog

[chirag127]

Summary

Adds a global opt-in setting hidePaidModels (default false) that, when enabled, filters paid-only models out of the unified /api/v1/models response. Uses the existing isFreeModel() primitive from src/shared/utils/freeModels.ts — a model qualifies as free when:

1. its id ends with :free (OpenRouter convention), OR
2. both pricing.prompt and pricing.completion are zero, OR
3. its id appears in FREE_MODEL_BUDGETS for that provider.

Providers absent from FREE_MODEL_BUDGETS (e.g. OpenAI, Anthropic) are treated as fully paid and filtered wholesale when the toggle is on.

Motivation

Operators running OmniRoute against a curated free-tier stack currently see the full 4000-model catalog including paid-only providers they can never actually call. A single opt-in toggle lets them narrow /v1/models to only the models their FREE_MODEL_BUDGETS catalog covers, without adding per-model hide clicks or removing the paid providers entirely.

Ties back to the existing free-model detection surface — the same isFreeModel() helper already powers the "import only free models" flow in the Add-API-Key modal and provider-sync route. This PR extends its reach to the catalog output.

Implementation

Two loops in src/app/api/v1/models/catalog.ts gain a paid-filter guard:

• PROVIDER_MODELS (chat) loop — skip when shouldHidePaid(canonicalProviderId, model.id, model.pricing) returns true.
• OpenRouter loop — reuses the already-computed isFree flag; when hidePaid && !isFree, skip the push.

shouldHidePaid() is a small local closure that consults providerHasFreeModels() first (short-circuits paid-only providers) then falls back to per-model isFreeModel().

Exempted surfaces (documented, intentional)

• Embedding / image / rerank / audio / moderation / video / music registries — represent local capabilities without pricing metadata.
• Combos / auto/* builtins / synced-available / custom / alias-backed models — extending scope to these would require per-entry pricing lookups not available today. Recommended follow-up.

Storage

Setting stored via the existing key_value namespace settings — no migration, no schema change. Default is false so existing deployments see no behavioral change.

Test

New unit test tests/unit/models-catalog-hide-paid.test.ts (Rule #18 regression guard):

1. Confirms the default is false.
2. Seeds an OpenAI connection, sets hidePaidModels=false, asserts paid OpenAI chat aliases appear.
3. Flips to hidePaidModels=true, re-fetches, asserts no paid OpenAI chat alias remains.

$ node --import tsx/esm --test tests/unit/models-catalog-hide-paid.test.ts
✔ hidePaidModels default is false + toggles the catalog filter (723ms)
ℹ tests 1
ℹ pass 1
ℹ fail 0

Typecheck (tsc -p tsconfig.typecheck-core.json) clean.

Diff

 src/app/api/v1/models/catalog.ts            | 16 +++++++
 src/lib/db/settings.ts                      |  5 +++
 tests/unit/models-catalog-hide-paid.test.ts | 66 +++++++++++++++++++++++++++++
 3 files changed, 87 insertions(+)

No new dependencies. Setting name matches the existing camelCase settings convention (hideEndpointNgrokTunnel, hideEndpointCloudflaredTunnel, mcpEnabled, etc.).

Follow-ups (not in this PR)

• Wire a checkbox into the general settings tab — API-only in v1 keeps the diff minimal; UI can land later behind the same setting key.
• Extend filter to /api/models/alias so combo composition UI honors the toggle when picking targets.
• Consider filtering combos whose all targets are paid.

Thanks for the great work on OmniRoute.

[gemini-code-assist]

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[diegosouzapw]

Merged into release/v3.8.46 — thank you, @chirag127! Synced onto the release tip, added the CHANGELOG entry, and verified tests green. 🙌