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

> Learn how to implement semantic search with vector embeddings in code-review-graph using embed_graph and semantic_search_nodes. Get smarter code analysis today.

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

---

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

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

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

```bash
crg embed_graph_tool

```

Using the Python API:

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

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

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

```

Using the Python API:

```python
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`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py), lines 99-107) calls `hybrid_search` from [`code_review_graph/search.py`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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`](https://github.com/tirth8205/code-review-graph/blob/main/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.