Provider Registry
Relevant source files
The following files were used as context for generating this wiki page:
The Provider Registry serves as the central orchestration layer for managing Large Language Model (LLM) providers and their associated metadata. It defines the communication protocols, authentication requirements, and model capabilities (such as vision and reasoning) for all supported services, including Anthropic, OpenAI, and local deployments like Ollama.
The system bifurcates provider management into static definitions (built-in providers) and dynamic state (user-provided API keys and persistent settings). It ensures that the application can seamlessly transition between different models based on context—such as using a high-latency reasoning model for complex tasks or a low-latency model for live voice interactions.
Core Architecture and Data Models
The registry relies on a set of canonical types that standardize how the application interacts with various AI backends. This abstraction allows the core engine to remain "wire-format-agnostic," with specific adapters handling the translation to provider-specific payloads.
Provider and Model Definitions
The system distinguishes between ProviderInfo (the configuration of a service) and ModelInfo (the specific capabilities of a model instance).
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the provider (e.g., "anthropic", "openai"). |
protocol | Protocol | Determines the adapter used: openai, openai-chat, or anthropic. |
keyless | boolean | If true, indicates a local provider (e.g., Ollama) that does not require an API key. |
vision | boolean | Indicates if a model supports image input modalities. |
reasoning | boolean | Indicates if the model exposes a dedicated reasoning/thinking channel. |
Sources: packages/harness/src/types.ts:63-108, apps/web/src/components/settings/ModelsSettings.tsx:21-25
Protocol Adapters
The registry supports three primary wire protocols, which drive the selection of the underlying harness adapter:
- anthropic: Targets the
/messagesendpoint for Claude models and compatible services like MiniMax. - openai: Targets the
/responsesAPI, typically used by OpenAI and recent versions of Ollama (v0.13.3+). - openai-chat: The "universal dialect" used for
/chat/completionsacross Groq, Together, DeepSeek, and others.
Sources: packages/harness/src/types.ts:54-61
Model Discovery and Cataloging
The system manages model availability through a hybrid approach of offline snapshots and live catalog fetching.
Catalog Resolution Flow
The catalog.ts module attempts to load model metadata from models.dev. If the network is unavailable or the cache (TTL of 24 hours) is valid, it provides enriched metadata including context windows and cost information.
The diagram shows the tiered fallback logic for model discovery, prioritizing fresh remote metadata while ensuring offline reliability.
Sources: packages/harness/src/catalog.ts:11-54
Provider Resolution Logic
The providers.ts service determines which provider and model should be active based on user settings, environment variables, and hardware capabilities (e.g., local Ollama vs. Cloud).
Live Voice Selection
For live voice mode, the system follows a specific hierarchy to ensure the best possible latency and capability match:
- Explicit Setting: Checks
liveProviderIdin the database. - Env Fallback: Looks for pre-configured environment keys for Anthropic, OpenAI, or MiniMax.
- Local Fallback: Defaults to
ollamaif no cloud keys are present.
Vision Model Routing
If the primary "live" model lacks vision capabilities, the registry can route image frames to a dedicated visionProviderId. This allows the tutor to "see" via one model while "speaking" through another.
Sources: services/agent/src/providers.ts:55-103, apps/web/src/components/settings/ModelsSettings.tsx:84-114
Data Persistence and Security
Provider data is persisted in providers.json via a JSON-file store. Security is maintained by encrypting sensitive API keys before they are written to disk.
Security Implementation
- Encryption: API keys are stored as
apiKeyCiphertextusingencryptSecret. - Masking: The UI only receives
keyLast4, ensuring full keys are never exposed to the frontend. - Environment Integration: Upon startup,
ensureSeedProviderssynchronizes environment variables (e.g.,ANTHROPIC_API_KEY) into the database if not already present.
This sequence illustrates the secure write path for API keys, where the plaintext key is encrypted immediately and only a masked version is returned to the UI.
Sources: packages/db/src/queries.ts:24-64, apps/web/src/app/api/providers/route.ts:15-25
Reasoning Effort Management
The registry controls the "Reasoning Effort" parameter, which balances answer depth against initial response latency.
- Allowed Efforts: Determined by the provider protocol. OpenAI's
reasoning_efforttypically acceptslow,medium, orhigh. - Auto Mode: For voice calls, "Auto" (the lowest supported effort) is preferred to minimize "dead air" before the model starts speaking.
Sources: packages/harness/src/types.ts:11-23, apps/web/src/components/settings/ModelsSettings.tsx:166-176
The Provider Registry represents the critical bridge between the user's local configuration and the global ecosystem of AI models. By abstracting provider-specific quirks and managing secure storage, it enables the project to maintain a high-performance, multi-modal tutoring environment.