ADR 018 · Accepted
Multi-Provider Model Discovery
Context
Different LLM providers expose different model listing APIs. OpenAI offers GET /v1/models, Ollama uses GET /api/tags, Anthropic lists models through GET /v1/models, and Gemini uses a different URL structure. The setup wizard needs a unified way to discover available models regardless of provider.
Problem statement
Heterogeneous APIs: No standard protocol for model listing.
Authentication variance: Bearer tokens, API key headers, URL parameters.
Response format divergence: Each provider returns different JSON structures.
Unavailable discovery: API failures, empty listings or custom endpoints can require a fallback catalogue; that does not imply no listing API exists.
Endpoint normalization: Users enter URLs with/without trailing slashes, versions, schemes.
Decision
Abstract model discovery behind ModelDiscoveryInterface with two operations:
The ModelDiscovery implementation routes per adapter type to one discoverer class per provider (extracted from the original single-class implementation in 2026-08; behaviour unchanged):
Each provider's listing, filtering, enrichment and fallback catalog live in Classes/Service/SetupWizard/Discovery/ as a *ModelDiscoverer extends AbstractModelDiscoverer; whether a result is live API data or a canned catalog travels on the returned DiscoveryResult rather than on shared service state.
Key design elements:
API-driven discovery for providers with listing endpoints (OpenAI, Ollama, Mistral, Groq, OpenRouter, Gemini and Anthropic).
Fallback catalogues for failed/empty discovery or endpoints without a usable listing. AnthropicModelDiscoverer calls the Models API; its static entries are a fallback, not the primary discovery mechanism. See the Anthropic Models API (checked 2026-11-07).
Provider detection via ProviderDetector using URL pattern matching with confidence scores (1.0 for exact match, 0.3 for unknown).
Normalized DTOs: DiscoveredModel unifies model metadata across providers (modelId, name, capabilities, contextLength, costs, recommended flag).
Authentication dispatch: Per-provider header format (Authorization: Bearer, x-api-key, x-goog-api-key, none for Ollama).
Provider detection patterns
ProviderDetector matches endpoint URLs against known patterns:
Pattern |
Adapter Type |
Confidence |
|---|---|---|
api.openai.com |
openai |
1.0 |
api.anthropic.com |
anthropic |
1.0 |
generativelanguage.googleapis.com |
gemini |
1.0 |
\*.openai.azure.com |
azure_openai |
1.0 |
localhost:11434 |
ollama |
1.0 |
\*/v1/chat/completions (path match) |
openai |
0.6 |
Unknown endpoint |
openai (fallback) |
0.3 |
Consequences
Positive:
●● Unified model discovery across seven provider types.
● Static catalogs ensure discovery works even without API access.
● Confidence scoring lets the UI warn about uncertain detections.
◐ PSR HTTP interfaces allow testing with mock HTTP clients.
◐ Endpoint normalization handles common user input variations.
Negative:
◑ Static catalogs require periodic updates as providers release new models.
◑ API-based discovery may expose all models, including deprecated ones.
✕ Rate limiting on model listing endpoints not handled.
Net Score: +5.0 (Strong positive)
Files changed
Added:
Classes/Service/SetupWizard/ModelDiscoveryInterface.php
Classes/Service/SetupWizard/ModelDiscovery.php (since 2026-08 a facade over Classes/Service/SetupWizard/Discovery/, one discoverer class per provider)
Classes/Service/SetupWizard/ProviderDetector.php
Classes/Service/SetupWizard/DTO/DetectedProvider.php
Classes/Service/SetupWizard/DTO/DiscoveredModel.php