# How to Integrate OpenAI Embeddings with code-review-graph for Semantic Search

> Integrate OpenAI embeddings with code-review-graph for semantic code search. Set environment variables, instantiate EmbeddingStore, and call embed_nodes() and search() to power your repository's semantic search.

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

---

**Set the `CRG_OPENAI_API_KEY`, `CRG_OPENAI_BASE_URL`, and `CRG_OPENAI_MODEL` environment variables, instantiate `EmbeddingStore`, and call `embed_nodes()` followed by `search()` to enable OpenAI-powered semantic code search across your repository.**

The `code-review-graph` library ships with a flexible embedding layer that supports multiple AI providers including OpenAI. By configuring specific environment variables, you can leverage OpenAI's embedding models to enable semantic search capabilities across your codebase's graph structure without modifying any source code.

## How the Embedding Provider System Works

The library uses a provider pattern to abstract embedding generation. In [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py), the `get_provider()` function (lines 722-751) automatically detects which backend to instantiate based on environment variables. When `CRG_OPENAI_API_KEY` is present and no explicit provider is requested, the function returns an `OpenAIEmbeddingProvider` instance configured for the OpenAI API or any compatible endpoint.

This design allows the `EmbeddingStore` class to remain agnostic about the underlying embedding service while providing a consistent interface for vector storage and retrieval.

## Configuring OpenAI Environment Variables

To integrate OpenAI embeddings with code-review-graph, export three specific environment variables before running your application:

- **`CRG_OPENAI_API_KEY`** – Your OpenAI API key (or compatible service key).
- **`CRG_OPENAI_BASE_URL`** – The base URL for the OpenAI API endpoint, typically `https://api.openai.com/v1` for official OpenAI services.
- **`CRG_OPENAI_MODEL`** – The embedding model identifier, such as `text-embedding-3-small`, `text-embedding-3-large`, or `text-embedding-ada-002`.

When these variables are present in the environment, `get_provider()` automatically selects the OpenAI implementation without requiring explicit provider arguments in your code.

## Storing and Searching Embeddings

The `EmbeddingStore` class (defined at lines 1157-1165 in [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py)) handles SQLite persistence for vector storage. Its constructor accepts `db_path`, optional `provider`, and `model` arguments, forwarding these to `get_provider()` to initialize the appropriate backend.

To populate the store with embeddings:

1. Load your code graph using `GraphStore`.
2. Instantiate `EmbeddingStore` pointing to the same SQLite database path.
3. Call `embed_nodes()` with the list of graph nodes to generate and cache embeddings in batches.

For querying, the `search(query, limit)` method (lines 1247-1272) computes query embeddings via the provider's `embed_query()` method, then performs cosine similarity scoring against stored vectors, returning the top-ranked qualified names with their similarity scores.

## Complete Integration Example

The following Python implementation demonstrates the full workflow from configuration to semantic search:

```python
import os
from pathlib import Path
from code_review_graph.graph import GraphStore
from code_review_graph.embeddings import EmbeddingStore

# 1️⃣  Configure OpenAI credentials (do NOT hard‑code them!)

os.environ["CRG_OPENAI_API_KEY"] = "<your‑openai‑api‑key>"
os.environ["CRG_OPENAI_BASE_URL"] = "https://api.openai.com/v1"
os.environ["CRG_OPENAI_MODEL"] = "text-embedding-3-small"

# 2️⃣  Load a code graph (e.g. from a repository)

graph_path = Path("/tmp/myrepo.graph.db")
graph = GraphStore(str(graph_path))

# 3️⃣  Initialise the embedding store – it will pick the OpenAI provider automatically

emb_store = EmbeddingStore(db_path=graph_path, provider="openai")

# 4️⃣  Populate embeddings for every node (once per database)

#    This will call the OpenAI `/v1/embeddings` endpoint in batches.

num_embedded = emb_store.embed_nodes(list(graph.nodes()))
print(f"Embedded {num_embedded} nodes using OpenAI")

# 5️⃣  Perform a semantic lookup

results = emb_store.search("how does the request get routed in Flask", limit=5)
for qualified_name, score in results:
    print(f"{qualified_name}: {score:.4f}")

```

You can also execute this workflow via the command-line interface after setting the environment variables:

```bash

# Export the required variables (sh/bash syntax)

export CRG_OPENAI_API_KEY=YOUR_KEY
export CRG_OPENAI_BASE_URL=https://api.openai.com/v1
export CRG_OPENAI_MODEL=text-embedding-3-small

# Build the graph for a project (example)

code-review-graph build /path/to/project --db /tmp/project.db

# Generate embeddings (OpenAI will be used automatically)

code-review-graph embed --db /tmp/project.db

# Search semantically

code-review-graph search "parse JSON payload" --db /tmp/project.db --limit 10

```

## Security Considerations and Privacy Warnings

When integrating with cloud-based embedding services, `code-review-graph` includes a safety mechanism to prevent accidental data exfiltration. In [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) (lines 443-452), the library checks whether the configured base URL points to `localhost`. If the endpoint is external and the environment variable `CRG_ACCEPT_CLOUD_EMBEDDINGS` is not set to `1`, the library prints a one-time warning to stderr about cloud egress before proceeding.

To suppress this warning for production deployments using external APIs, set `CRG_ACCEPT_CLOUD_EMBEDDINGS=1` in your environment.

## Summary

- **`get_provider()`** automatically instantiates `OpenAIEmbeddingProvider` when `CRG_OPENAI_API_KEY` and related variables are present.
- **`EmbeddingStore`** persists vectors in SQLite and manages (re)embedding when providers or source text change.
- **`embed_nodes()`** batches graph node processing to minimize API calls to the OpenAI `/v1/embeddings` endpoint.
- **`search()`** uses cosine similarity on cached vectors to return semantically relevant code symbols.
- The **CLI commands** `build`, `embed`, and `search` provide a complete workflow without requiring Python scripting.

## Frequently Asked Questions

### What environment variables are required to integrate OpenAI embeddings with code-review-graph?

You must set `CRG_OPENAI_API_KEY` for authentication, `CRG_OPENAI_BASE_URL` for the API endpoint (typically `https://api.openai.com/v1`), and `CRG_OPENAI_MODEL` to specify the embedding model such as `text-embedding-3-small`. These variables are read by `get_provider()` in [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) to configure the OpenAI provider automatically.

### How does code-review-graph handle embedding storage and updates?

The `EmbeddingStore` class manages SQLite persistence for vector embeddings. It stores vectors alongside their metadata and automatically handles re-embedding when the underlying provider changes or when source text is modified. The constructor at lines 1157-1165 of [`embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/embeddings.py) initializes the database connection and validates the provider configuration.

### Can I use a local OpenAI-compatible API instead of the official OpenAI service?

Yes, any API implementing the OpenAI embeddings specification is supported. Set `CRG_OPENAI_BASE_URL` to your local endpoint (e.g., `http://localhost:8000/v1`). When the base URL contains `localhost`, the library suppresses the cloud-egress warning that normally appears for external API calls.

### What is the recommended workflow for semantic search after initial setup?

First, build your code graph using `GraphStore`. Then create an `EmbeddingStore` instance pointing to the same database path and call `embed_nodes()` to generate embeddings for all graph nodes—this is typically done once per repository. Afterward, use the `search()` method or the `code-review-graph search` CLI command to perform semantic lookups using natural language queries.