Description
The Runtime Embedding Provider Registry is the developer seam for adding another embedding implementation beside Dots' frozen built-in catalog. A composition root registers catalog metadata and may attach a constructed EmbeddingProvider instance. Overlay-aware lookup and listing functions then expose the combined built-in and runtime population, while legacy built-in-only functions remain stable.
Runtime names can live outside the closed built-in ProviderName union, which lets an integrator introduce a genuinely new provider family. Registration validates non-empty names and rejects collisions with either a built-in or an earlier runtime entry. Status-aware list helpers keep shipped, adapter-seam, deferred, and no-op populations honest rather than implying every catalog item is callable.
Selling Points
- Integrators can add a provider without editing the frozen catalog or the adapter package's core maps.
- Optional instance registration couples discoverable metadata to a live implementation when the composition needs both.
- Built-in-only callers retain deterministic behavior, reducing compatibility risk as runtime providers are added.
- Collision errors prevent one integration from silently replacing a known provider or another runtime registration.
- Status-aware queries let surfaces distinguish usable providers from deferred or non-production entries.
User Story
An enterprise composition has an approved internal embedding gateway. At boot it constructs an EmbeddingProvider implementation, registers its metadata and instance under a new name, and resolves it through the overlay when assembling indexing or search. Existing callers that intentionally list only built-ins see no change.
Extension Surface
Pluggable is the defining rung. packages/embedding-providers/src/internal/provider-registry.ts exposes registerEmbeddingProvider, getRuntimeEmbeddingProvider, findProviderInfo, and overlay-aware list functions, while packages/embedding-providers/src/internal/types.ts defines the implementation contract. A new provider can be added at composition without changing core package files.
Capabilities & Limits
- Registers a new provider name, status metadata, model details, and an optional constructed instance.
- Lists runtime-only or built-in-plus-runtime populations with status narrowing.
- Resolves catalog information and live instances independently.
- Limits: registration is process-local and operator-scoped; no tenant-facing production route lets a workspace add providers dynamically.
- Limits: the registry does not manage credentials, persistence, health checks, or provider-specific UI.
Implementation Map
packages/embedding-providers/src/internal/provider-registry.tspackages/embedding-providers/src/internal/types.tsEmbeddingProviderpackages/embedding-providers/src/public/index.tspackages/embedding-providers/src/internal/provider-registry-runtime.test.tspackages/embedding-providers/src/internal/resolve-text-model.ts