feat(models)!: default configured provider models mode to allowlist

Merged
SA
1d ago
+438-190

Breaking change. A configured provider model list (providers.<name>.models, <PROVIDER>_MODELS, or the dashboard's Models field) is now the provider's whole inventory by default: CONFIGURED_PROVIDER_MODELS_MODE defaults to allowlist instead of fallback, and upstream /models is skipped for providers with a list.

Why: under fallback, a list was silently ignored whenever /models succeeded (e.g. one configured OpenRouter model still exposed ~600). That was also how the OpenAI-compatible and Oracle adapters behaved before #268 introduced the global mode. A missing model under allowlist fails loudly (404) instead of an ignored list going unnoticed.

To keep the old behavior: CONFIGURED_PROVIDER_MODELS_MODE=fallback (or merge to add listed models to discovery), globally or per provider via models_mode. Providers without a configured list are unaffected.

Also:

  • Docs: new Models modes comparison table (docs/advanced/config-yaml#models-modes) plus an upgrade note; every mention of the default updated in en/de/pl/zh, .env.template, and config.example.yaml. Bailian docs now recommend merge to keep discovered chat models alongside configured embedding models.
  • Dashboard: a "?" next to Models mode links to the table; field hints reflect the new default.
  • Tests that exercise fallback now set it explicitly; a new test pins the allowlist default.

Summary by CodeRabbit

  • Behavior Changes
    • Configured provider model lists now default to allowlist mode: only configured models are available, and upstream model discovery is skipped. Choose fallback to use configured models when discovery fails or returns no results, or merge to combine configured and discovered models.
  • Dashboard
    • Added links to relevant documentation beside provider settings when available.
  • Documentation
    • Updated configuration guidance and examples to reflect the new default and explain the available modes.