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

code-review-graph supports semantic search by creating vector embeddings for every graph node via the embed_graph tool, then querying them through semantic_search_nodes which automatically falls back to full-text search when embeddings are unavailable.

The code-review-graph open-source project enables AI-powered code reviews by maintaining a knowledge graph of your repository. By leveraging semantic search with vector embeddings, you can query this graph using natural language rather than exact keyword matches, significantly improving discovery of related code concepts.

Prerequisites: Installing Embedding Dependencies

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

Run the following command to install the required packages:

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

Without this extra, calling embed_graph will return a structured error indicating that sentence-transformers is missing. This is enforced in code_review_graph/tools/docs.py within the embed_graph implementation.

Configuring the Embedding Provider

The embedding pipeline supports multiple providers. Your choice determines where vectors are generated and which environment variables you must configure.

Local Provider (Default)

The local provider uses the installed transformer model to compute embeddings on your machine. This is the default mode when no remote API keys are detected.

To use the local provider explicitly:

from code_review_graph.tools.docs import embed_graph

result = embed_graph(repo_root=".", provider="local")

Remote Providers (OpenAI, Google, Voyage, Minimax)

For higher-quality embeddings or reduced local compute, configure a remote provider by setting the appropriate 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 via the provider-specific variables as implemented in code_review_graph/tools/docs.py

You can override the default model for any provider using the optional CRG_EMBEDDING_MODEL environment variable. The embed_graph routine reads these variables during initialization (lines 60-66 of code_review_graph/tools/docs.py) and returns structured error messages if required variables are missing.

Generating Vector Embeddings

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

Using the CLI:

crg embed_graph_tool

Using the Python API:

from code_review_graph.tools.docs import embed_graph

result = embed_graph(
    repo_root=".",
    provider="openai",  # or "local", "google", "voyage"

    model="text-embedding-3-small"  # optional override

)
print(result["summary"])

The embed_graph function populates the EmbeddingStore class (referenced in code_review_graph/embeddings.py) with vectors for each node. If you switch models or providers, simply re-run the command; the store automatically re-embeds all nodes with the new settings.

Verifying Embeddings Are Active

Confirm that embeddings were successfully created using the stats tool:

crg list_graph_stats_tool

Look for the line indicating "Embeddings: X nodes embedded". This output is generated by the list_graph_stats function in code_review_graph/tools/query.py (lines 10-18), which merges embedding information into the statistics display. 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 that understand conceptual similarity rather than exact text matches.

Using the CLI:

crg semantic_search_nodes_tool query="user authentication flow"

Using the Python API:

from code_review_graph.tools.query import semantic_search_nodes

search = semantic_search_nodes(
    query="login",
    provider="local",
    model="all-MiniLM-L6-v2"
)
print(search["search_mode"])  # "hybrid", "semantic", "fts", or "keyword"

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

The semantic_search_nodes wrapper (defined in code_review_graph/tools/query.py, lines 99-107) calls hybrid_search from code_review_graph/search.py (lines 19-36). This core logic first attempts a combined full-text search (FTS) and vector search. If embeddings are present, the result's "search_mode" field will be "hybrid" or "semantic"; otherwise, it gracefully falls back to "fts" or "keyword" mode.

Troubleshooting Common Issues

When embeddings fail to generate or search, the tools return structured error dictionaries rather than raising exceptions, making programmatic detection straightforward.

Missing sentence-transformers: If you encounter an error instructing you to install the extra dependencies, run pip install "code-review-graph[embeddings]" again.

Remote provider unavailable: Errors will specify which environment variables are missing (e.g., CRG_OPENAI_API_KEY). Check the error message returned by embed_graph (lines 67-82 of code_review_graph/tools/docs.py) to identify the exact missing configuration.

Zero embeddings found: If list_graph_stats_tool shows zero embedded nodes, ensure you have run embed_graph_tool successfully and that your repository contains indexed graph nodes.

Summary

• Install embedding support via pip install "code-review-graph[embeddings]" to enable local vector computation with sentence-transformers.
• Configure your provider (local, OpenAI, Google, Voyage, or Minimax) using environment variables read by embed_graph in code_review_graph/tools/docs.py.
• Generate embeddings using crg embed_graph_tool or the Python embed_graph function, which populates the EmbeddingStore.
• Verify successful embedding creation via crg list_graph_stats_tool before attempting semantic queries.
• Execute semantic searches with semantic_search_nodes, which utilizes hybrid_search from code_review_graph/search.py and automatically falls back to full-text search when vectors are unavailable.

Frequently Asked Questions

What is the difference between semantic search and full-text search in code-review-graph?

Full-text search matches exact keywords and substrings within node content, while semantic search uses vector embeddings to find conceptually related code even when terminology differs. According to the implementation in code_review_graph/search.py, the hybrid_search function combines both approaches, returning results ranked by vector similarity when embeddings exist, or falling back to FTS when they do not.

Can I use multiple embedding providers simultaneously?

No, you must select a single provider per embedding generation run. However, you can re-embed the graph with a different provider by calling embed_graph with a new provider argument. The EmbeddingStore automatically replaces existing vectors with newly generated ones from the selected provider and model.

How do I know if my semantic search is actually using vector embeddings?

Check the "search_mode" field in the search results dictionary. As implemented in code_review_graph/tools/query.py, the semantic_search_nodes wrapper exposes the mode selected by hybrid_search. If embeddings are present and used, the mode will be "hybrid" or "semantic"; if unavailable, it will show "fts" or "keyword" instead.

What happens if I search before generating embeddings?

The search will still execute, but it will fall back to keyword-based or full-text search modes. The hybrid_search logic in code_review_graph/search.py gracefully handles missing embeddings by detecting the absence of vectors in the EmbeddingStore and routing the query to the FTS5 index instead, ensuring you always receive results even without vector setup.

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