Embedding Providers and Models Used for Semantic Search in Code‑Review‑Graph

Code‑Review‑Graph supports four distinct embedding providers—Local (sentence‑transformers), Google Gemini, MiniMax, and OpenAI‑compatible endpoints—allowing developers to choose between offline privacy and cloud‑based performance for semantic code search.

The Code‑Review‑Graph (CRG) repository implements a pluggable embedding architecture in code_review_graph/embeddings.py that enables hybrid semantic search. This system combines traditional full‑text search with dense vector retrieval to locate relevant code patterns across your repository.

The Four Embedding Providers

The embedding subsystem defines four concrete implementations of the abstract EmbeddingProvider base class. Each provider targets different operational requirements regarding latency, privacy, and model capability.

Local Provider (Offline)

The LocalEmbeddingProvider uses the sentence‑transformers library to generate embeddings entirely offline. It defaults to the all‑MiniLM‑L6‑v2 model, a 384‑dimensional sentence encoder optimized for speed and memory efficiency.

In code_review_graph/embeddings.py (lines 4‑8), the provider initializes the model with optional trust_remote_code protection controlled by the CRG_ALLOW_REMOTE_CODE environment variable. This provider requires no network connectivity and incurs zero API costs, making it ideal for private environments or CI/CD pipelines.

Google Gemini Provider

The GoogleEmbeddingProvider interfaces with Google's Gemini embedding API, defaulting to the gemini‑embedding‑001 model. This provider requires a valid GOOGLE_API_KEY environment variable.

As implemented in lines 81‑89 of code_review_graph/embeddings.py, this cloud‑based option offloads computation to Google's infrastructure, trading network latency for potentially higher‑quality multilingual embeddings.

MiniMax Provider

The MiniMaxEmbeddingProvider connects to the MiniMax cloud API to generate 1536‑dimensional vectors using the embo‑01 model. Configuration requires a MINIMAX_API_KEY environment variable.

The implementation (lines 70‑78) handles MiniMax‑specific authentication and batching constraints, providing a middle ground between local inference and large‑provider redundancy.

OpenAI‑Compatible Provider

The OpenAIEmbeddingProvider supports any /v1/embeddings‑compatible endpoint, including OpenAI, Azure OpenAI, Ollama, LiteLLM, and vLLM. The model selection is controlled via the CRG_OPENAI_MODEL environment variable.

Found in lines 84‑93 of code_review_graph/embeddings.py, this provider offers maximum flexibility for organizations running self‑hosted embedding gateways or requiring specific model versions like text‑embedding‑3‑small.

The EmbeddingProvider Interface

All providers implement the abstract base class EmbeddingProvider defined in lines 46‑58 of code_review_graph/embeddings.py. This contract ensures interchangeable behavior across the search pipeline:

class EmbeddingProvider(ABC):
    def embed(self, texts: list[str]) -> list[list[float]]: ...
    def embed_query(self, text: str) -> list[float]: ...
    @property
    def dimension(self) -> int: ...
    @property
    def name(self) -> str: ...

• embed(): Batch encodes multiple documents for indexing.
• embed_query(): Encodes a single search query, potentially using task‑specific optimizations.
• dimension: Returns the vector size (384 for MiniLM, 1536 for MiniMax, etc.).

Hybrid Search Architecture

The semantic search implementation lives in code_review_graph/search.py and operates as a dual‑pipeline system that merges lexical and semantic relevance signals.

FTS5 BM25 vs Vector Similarity

When hybrid_search() is invoked, CRG executes two parallel retrieval strategies:

1. FTS5 BM25: A SQLite full‑text index rebuilt via rebuild_fts_index() (lines 25‑68) that performs keyword‑based matching on code tokens.
2. Embedding Search: Vector similarity lookup against the embeddings table populated by the active provider, implemented in _embedding_search.

Reciprocal Rank Fusion

Results from both pipelines are merged using Reciprocal Rank Fusion (rrf_merge, lines 50‑74). This algorithm combines rankings from disparate sources without requiring score normalization, producing a unified relevance score that balances exact keyword matches with semantic similarity.

from code_review_graph.search import hybrid_search
from code_review_graph.graph import GraphStore

store = GraphStore("/tmp/crg.db")
results = hybrid_search(
    store,
    query="extract all public API endpoints from a SpringBoot project",
    limit=20,
)

Configuration and Environment Variables

Provider selection and behavior are controlled through environment variables read at initialization:

• CRG_EMBEDDING_MODEL: Overrides the default model for the Local provider (e.g., all-mpnet-base-v2).
• CRG_OPENAI_MODEL: Selects the specific OpenAI model (e.g., text-embedding-3-small).
• CRG_ALLOW_REMOTE_CODE: Enables trust_remote_code for sentence‑transformers loading (security‑sensitive).

These variables are parsed in embeddings.py during provider instantiation (lines 97‑104).

Implementation Examples

Initializing Specific Providers

from code_review_graph.embeddings import (
    LocalEmbeddingProvider,
    OpenAIEmbeddingProvider,
)

# Offline local inference

local = LocalEmbeddingProvider()
vectors = local.embed(["def foo(): pass", "class Bar: ..."])

# OpenAI-compatible endpoint

openai = OpenAIEmbeddingProvider(
    api_key="sk-...",
    model="text-embedding-3-small",
    base_url="https://api.openai.com/v1"
)
query_vec = openai.embed_query("How to iterate over a Python list?")

Pre‑warming Local Models

On Windows and certain environments, sentence‑transformers must be loaded in the main thread before forking:

from code_review_graph.embeddings import prewarm_local_embeddings

prewarm_local_embeddings()  # Loads model once to prevent thread-safety issues

Summary

• Four provider options cover offline (sentence‑transformers), Google Gemini, MiniMax, and any OpenAI‑compatible endpoint.
• Abstract interface (EmbeddingProvider) standardizes embed(), embed_query(), and dimension across all implementations.
• Hybrid retrieval combines SQLite FTS5 BM25 with vector similarity using Reciprocal Rank Fusion in code_review_graph/search.py.
• Environment variables CRG_EMBEDDING_MODEL, CRG_OPENAI_MODEL, and CRG_ALLOW_REMOTE_CODE control runtime configuration without code changes.
• Local provider defaults to all‑MiniLM‑L6‑v2 (384‑dim) and supports trust_remote_code security controls.

Frequently Asked Questions

What is the default embedding model for offline usage?

The LocalEmbeddingProvider defaults to all‑MiniLM‑L6‑v2, a lightweight 384‑dimensional model from the sentence‑transformers library. You can override this via the CRG_EMBEDDING_MODEL environment variable, for example to use all-mpnet-base-v2 for potentially higher accuracy at the cost of inference speed.

How does Code‑Review‑Graph combine keyword and semantic search?

CRG implements Reciprocal Rank Fusion (rrf_merge in code_review_graph/search.py lines 50‑74) to merge results from SQLite FTS5 BM25 (lexical search) and cosine similarity on vector embeddings (semantic search). This hybrid approach ensures exact keyword matches remain highly ranked while semantically related but syntactically different code is also surfaced.

Can I use a self‑hosted embedding model with Code‑Review‑Graph?

Yes. The OpenAIEmbeddingProvider accepts any /v1/embeddings‑compatible endpoint via the base_url parameter. This supports self‑hosted solutions like Ollama, vLLM, or LiteLLM gateways, allowing you to run text‑embedding‑3‑small or custom models entirely within your infrastructure without external API calls.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}