Embedding Providers
Relevant source files
The following files were used as context for generating this wiki page:
Embedding Providers are a core component of the MCB (Memory Context Browser) architecture, responsible for transforming natural language text into high-dimensional vector embeddings. These embeddings enable semantic features such as natural language code search and persistent memory retrieval by allowing the system to perform vector similarity comparisons rather than simple keyword matching.
The system utilizes a multi-provider strategy, supporting both local (e.g., Ollama, FastEmbed) and cloud-based (e.g., OpenAI, Gemini, VoyageAI) services. Each provider implements the EmbeddingProvider port defined in the domain layer, ensuring that the rest of the application remains decoupled from specific API implementations.
Sources: README.md:14-17, crates/mcb-providers/src/lib.rs:11-18, AGENTS.md:144-148
Provider Architecture
The embedding system is built on Clean Architecture principles. Providers reside in the mcb-providers crate and implement traits defined in mcb-domain. This decoupling allows for compile-time registration of providers using the linkme crate, which facilitates zero-overhead provider discovery.
Component Hierarchy
The following diagram illustrates the relationship between the domain ports, the provider implementations, and the shared utility layers.
The EmbeddingProvider trait acts as the interface, while specific implementations like GeminiEmbeddingProvider use shared utilities and macros to handle HTTP communication and response parsing.
Sources: crates/mcb-providers/src/lib.rs:1-25, crates/mcb-providers/src/utils/embedding.rs:14-25, crates/mcb-providers/src/macros/embedding.rs:163-175
Core Components and Logic
EmbeddingProvider Trait
The fundamental contract for all embedding implementations. It requires three primary capabilities:
embed_batch: Generates a vector for a slice of input strings.dimensions: Returns the size of the vector produced by the specific model.provider_name: Returns a unique slug (e.g., "openai") for registry identification.
Sources: crates/mcb-providers/src/macros/embedding.rs:83-102, crates/mcb-providers/src/embedding/gemini.rs:109-127
Standard HTTP Client Utility
The HttpEmbeddingClient is a shared internal structure that standardizes how providers manage API keys, base URLs, model identifiers, and timeouts.
| Field | Type | Description |
|---|---|---|
api_key | String | Authentication token for the service |
base_url | String | The endpoint URL for the API |
model | String | The specific embedding model identifier |
timeout | Duration | Max time allowed for a request |
client | reqwest::Client | Shared HTTP client instance |
Sources: crates/mcb-providers/src/utils/embedding.rs:14-25
Batch Processing Logic
Most providers process texts in batches to improve efficiency. The process_batch utility manages the lifecycle of a batch request, including error checking for count mismatches between input texts and returned vectors.
Implementation Macros
MCB uses a sophisticated macro system to reduce boilerplate when adding new HTTP-based embedding providers.
define_standard_embedding_provider!
This macro generates the entire provider implementation for services following the standard /v1/embeddings pattern (like OpenAI or VoyageAI). It handles:
- Struct Definition: Creates the provider struct wrapping
HttpEmbeddingClient. - Trait Implementation: Implements
EmbeddingProviderwith standard batching and parsing logic. - Registration: Registers the provider into the global registry via
linkme.
Sources: crates/mcb-providers/src/macros/embedding.rs:163-230
register_http_provider!
Used to generate the factory function required by the Dependency Injection (DI) system. It maps configuration fields (like model and api_key) to the provider's constructor.
Sources: crates/mcb-providers/src/macros/embedding.rs:113-140
Specific Provider Details
Google Gemini
Unlike OpenAI, the Gemini provider does not natively support batch embedding in a single request. Its implementation iterates through the provided texts and performs sequential requests.
- API Endpoint:
/v1beta/models/{model}:embedContent - Authentication: Custom header
x-goog-api-key - Default Model:
text-embedding-004 - Max Tokens: Configured via
GEMINI_MAX_TOKENSconstant.
Sources: crates/mcb-providers/src/embedding/gemini.rs:56-105
Supported Providers
Based on the registry and source files, the following providers are available:
| Slug | Description | Source |
|---|---|---|
openai | OpenAI (text-embedding-3-small/large) | README.md |
gemini | Google Gemini (text-embedding-004) | gemini.rs |
ollama | Local embeddings via Ollama | lib.rs |
fastembed | Local high-performance embeddings | README.md |
voyageai | VoyageAI specialized code embeddings | lib.rs |
anthropic | Anthropic embedding services | lib.rs |
Sources: README.md:16-17, crates/mcb-providers/src/lib.rs:11-18, crates/mcb-providers/src/embedding/gemini.rs:136-144
Summary
Embedding Providers in MCB bridge the gap between raw text and semantic vector space. By utilizing a unified architecture driven by traits, macros, and shared HTTP utilities, the system maintains a high degree of extensibility while ensuring robust error handling and standardized configuration across multiple local and cloud-based backends.