Embedding Providers

Relevant source files

The following files were used as context for generating this wiki page:

• crates/mcb-providers/src/embedding/openai.rs
• crates/mcb-providers/src/embedding/ollama.rs
• crates/mcb-providers/src/embedding/anthropic.rs
• crates/mcb-providers/src/embedding/gemini.rs
• crates/mcb-providers/src/embedding/mod.rs
• crates/mcb-providers/src/macros/embedding.rs
• crates/mcb-providers/src/utils/embedding.rs
• README.md

Embedding Providers in the MCB project are specialized adapters that convert natural language text into dense numerical vectors (embeddings). These embeddings enable the system's core Semantic Code Search and Persistent Memory features by allowing mathematical comparison of query strings against indexed codebases and stored observations.

The system follows a multi-provider architecture, supporting both local inference (via Ollama or FastEmbed) and cloud-based services (OpenAI, Gemini, VoyageAI, Anthropic). Each provider implements the EmbeddingProvider port defined in the domain layer, ensuring the rest of the application remains decoupled from specific API implementations.

Sources: README.md:12-14, crates/mcb-providers/src/embedding/mod.rs:1-8

Provider Architecture

The architecture utilizes a modular design where each provider is registered via a distributed slice mechanism (linkme). This allows for zero-runtime-overhead provider selection and easy extensibility.

Core Components

• EmbeddingProvider Trait: The domain-level interface that all implementations must satisfy. It defines methods for batch embedding and metadata retrieval.
• HttpEmbeddingClient: A shared utility struct that encapsulates common HTTP concerns like API keys, base URLs, timeouts, and the underlying reqwest client.
• Provider Macros: A set of Rust macros used to boilerplate standard HTTP provider implementations, including struct definitions and registration logic.

Sources: crates/mcb-providers/src/macros/embedding.rs:11-137, crates/mcb-providers/src/utils/embedding.rs:16-29

Provider Registration Flow

The following diagram illustrates how a provider is initialized and registered into the system using factory functions and the linkme crate.

A flowchart showing the configuration-driven initialization and registration of embedding providers.
Sources: crates/mcb-providers/src/macros/embedding.rs:89-113, crates/mcb-providers/src/embedding/gemini.rs:114-123

Supported Providers

The project categorizes providers based on their deployment model and specific optimization.

Provider	Type	Primary Use Case	Default Model
OpenAI	Cloud	General purpose, high accuracy	text-embedding-3-small
Ollama	Local	Privacy-first, offline development	nomic-embed-text
Gemini	Cloud	Google ecosystem, large context	text-embedding-004
Anthropic	Cloud	Optimized for code (via Voyage)	voyage-3
FastEmbed	Local	Zero-dependency testing	N/A

Sources: crates/mcb-providers/src/embedding/mod.rs:10-26, crates/mcb-providers/src/embedding/gemini.rs:114-123, crates/mcb-providers/src/embedding/anthropic.rs:108-117

Implementation Details

Standard HTTP Flow

Most providers use a standard request/response pattern. The define_standard_embedding_provider! macro generates the logic for sending JSON payloads to /v1/embeddings and parsing the returned vectors.

A sequence diagram depicting the interaction between a provider implementation, shared utilities, and the external API.
Sources: crates/mcb-providers/src/macros/embedding.rs:139-216, crates/mcb-providers/src/utils/embedding.rs:103-138

Provider-Specific Logic

• Gemini: Unlike others, the Gemini provider processes batch requests sequentially because its embedContent API does not natively support batch arrays in the standard format. It also requires a specific x-goog-api-key header instead of the standard Bearer token.
• Anthropic: This provider acts as a wrapper for Voyage AI models accessed through Anthropic's endpoints, specifically supporting voyage-code-3 for code-heavy tasks.
• Ollama: Specifically targets local LLM servers, allowing users to leverage local hardware for embedding generation.

Sources: crates/mcb-providers/src/embedding/gemini.rs:56-102, crates/mcb-providers/src/embedding/anthropic.rs:13-33, crates/mcb-providers/src/embedding/mod.rs:21-22

Data Structures

The providers primarily interact with the Embedding value object and HttpEmbeddingClient configuration.

// Shared internal client configuration
pub(crate) struct HttpEmbeddingClient {
    pub(crate) api_key: String,
    pub(crate) base_url: String,
    pub(crate) model: String,
    pub(crate) timeout: Duration,
    pub(crate) client: Client,
}

Sources: crates/mcb-providers/src/utils/embedding.rs:16-24

Error Handling and Retries

The providers utilize a centralized retry mechanism defined in JsonRequestParams. Standard retry configurations use PROVIDER_RETRY_COUNT and PROVIDER_RETRY_BACKOFF_MS constants to handle transient network failures or rate limits from cloud providers.

Sources: crates/mcb-providers/src/embedding/gemini.rs:74-77, crates/mcb-providers/src/embedding/anthropic.rs:73-76

Summary

Embedding Providers form the bridge between raw code/text and the vector-space representations required for semantic understanding. By abstracting different API formats (OpenAI, Gemini, Ollama) through a unified macro-driven infrastructure, MCB maintains a flexible architecture that supports both high-performance cloud inference and secure local processing.