How to Configure Semantic Search with Vector Embeddings in code-review-graph

To enable semantic search in code-review-graph, install the optional embeddings dependencies, configure your provider (local or remote), and run the embed_graph tool to populate the vector store before using semantic_search_nodes.

The code-review-graph repository provides vector-based semantic search capabilities that allow you to query your knowledge graph using natural language. This feature works by generating embeddings for every node in the graph and storing them in an EmbeddingStore, enabling the semantic_search_nodes tool to perform similarity searches that automatically fall back to full-text search when embeddings are unavailable.

Prerequisites and Installation

Before generating embeddings, you must install the optional dependencies required for vector computation. The local provider relies on sentence-transformers to compute vectors locally.

Install the embeddings extra using pip:

pip install "code-review-graph[embeddings]"

Without this package, calling embed_graph will return a structured error directing you to install the missing dependency.

Configuring the Embedding Provider

The embed_graph function in code_review_graph/tools/docs.py supports multiple providers for generating embeddings. Your choice determines which environment variables you must set and where the computation occurs.

Local Provider (Default)

The local provider uses the installed sentence-transformers model to compute vectors on your machine. This is the default when no remote API credentials are configured. Set the optional CRG_EMBEDDING_MODEL environment variable to override the default model selection.

Remote Providers

For cloud-based embedding generation, configure one of the following providers by setting the required environment variables:

• OpenAI: Set CRG_OPENAI_BASE_URL, CRG_OPENAI_API_KEY, and CRG_OPENAI_MODEL
• Google: Set CRG_GOOGLE_API_KEY and CRG_GOOGLE_MODEL
• Voyage: Set VOYAGE_API_KEY and CRG_VOYAGE_MODEL
• Minimax: Configure according to provider documentation

The embed_graph implementation (lines 60-66 in code_review_graph/tools/docs.py) validates these variables and returns a structured error if any required credentials are missing.

Generating Vector Embeddings

Once dependencies are installed and environment variables are set, populate the vector store by running the embedding pipeline. This process creates a vector for every graph node that does not already have an up-to-date embedding.

Using the CLI

Run the embedding tool from your repository root:

# Generate embeddings using the configured provider

crg embed_graph_tool

# Override model or provider via CLI arguments

crg embed_graph_tool model="all-MiniLM-L6-v2" provider="local"

Using the Python API

Import and call embed_graph directly from code_review_graph/tools/docs.py:

from code_review_graph.tools.docs import embed_graph

# Local provider with default model

result = embed_graph(repo_root=".", provider="local")
print(result["summary"])

# Remote provider with specific model

result = embed_graph(
    repo_root=".",
    provider="openai",
    model="text-embedding-3-small"
)

The function returns a dictionary with a status key. Errors are returned as structured data (lines 67-82 in code_review_graph/tools/docs.py) rather than exceptions, making programmatic error detection straightforward.

Verifying Embedding Creation

Confirm that embeddings were successfully generated by checking the graph statistics. The list_graph_stats function in code_review_graph/tools/query.py (lines 10-18) merges embedding information into the output.

Run the stats tool:

crg list_graph_stats_tool

Look for the line indicating "Embeddings: X nodes embedded". If you see a warning about missing sentence-transformers, the local provider is not properly installed.

Performing Semantic Searches

With embeddings in place, execute semantic queries using the semantic_search_nodes tool. This wrapper (lines 99-107 in code_review_graph/tools/query.py) calls the core hybrid_search function in code_review_graph/search.py (lines 19-36), which combines full-text and vector search results.

CLI Search

crg semantic_search_nodes_tool query="user authentication flow"

Python API Search

from code_review_graph.tools.query import semantic_search_nodes

search = semantic_search_nodes(
    query="login",
    provider="local",          # or "openai", "google", etc.

    model="all-MiniLM-L6-v2", # optional override

)

print(search["search_mode"])  # "hybrid", "semantic", "fts", or "keyword"

print(search["results"][:5])  # top 5 results

The search_mode field in the response indicates which search path was active. When embeddings are available, the system uses hybrid mode (combining FTS5 and vector results) or pure semantic mode. If embeddings are missing, it automatically falls back to fts or keyword search.

Updating and Retuning Embeddings

To switch to a different embedding model or provider, simply re-run the embedding command with new parameters. The EmbeddingStore automatically re-embeds all nodes when it detects configuration changes.

# Switch to a larger model for better accuracy

crg embed_graph_tool model="multi-qa-mpnet-base-dot-v1" provider="local"

Different models affect both similarity quality and computational cost, particularly when using remote APIs that charge per token.

Summary

• Install the optional [embeddings] extra to enable local vector computation with sentence-transformers
• Configure provider-specific environment variables in code_review_graph/tools/docs.py for OpenAI, Google, or Voyage APIs
• Execute embed_graph via crg embed_graph_tool or the Python API to populate the EmbeddingStore
• Verify embedding count using crg list_graph_stats_tool before searching
• Query using semantic_search_nodes, which automatically selects hybrid, semantic, or fallback search modes based on availability

Frequently Asked Questions

What happens if I try to search without generating embeddings first?

The semantic_search_nodes tool automatically falls back to full-text search (FTS) or keyword search when no embeddings are detected. The response will include "search_mode": "fts" or "search_mode": "keyword" instead of "hybrid" or "semantic", ensuring the query still returns results even without vector data.

Can I use a custom embedding model not listed in the defaults?

Yes. While the local provider defaults to standard sentence-transformers models, you can specify any compatible model name using the model parameter in embed_graph or the CRG_EMBEDDING_MODEL environment variable. For remote providers, ensure the model name is valid for that API endpoint.

Why does my embedding command return an error about missing environment variables?

The embed_graph function validates required credentials before attempting API calls. If using OpenAI, Google, or Voyage providers, ensure you have exported the specific variables listed in code_review_graph/tools/docs.py (lines 60-66). The error message will explicitly state which variables are missing.

How do I know which search mode was actually used for my query?

Check the search_mode key in the response dictionary from semantic_search_nodes. This field is set by the hybrid_search logic in code_review_graph/search.py and indicates whether the results came from vector similarity ("semantic"), combined FTS and vector ("hybrid"), or traditional text matching ("fts"/"keyword").

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