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

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, 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) 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:

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:

# 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 (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 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 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.

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