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

> Learn to configure semantic search with vector embeddings in code-review-graph. Install dependencies, set up your provider, and embed your graph for powerful code analysis.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-07

---

**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:

```bash
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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:

```bash

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/docs.py):

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py) (lines 10-18) merges embedding information into the output.

Run the stats tool:

```bash
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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py)) calls the core `hybrid_search` function in [`code_review_graph/search.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/search.py) (lines 19-36), which combines full-text and vector search results.

### CLI Search

```bash
crg semantic_search_nodes_tool query="user authentication flow"

```

### Python API Search

```python
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.

```bash

# 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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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").