How to Enable Semantic Search in Code-Graph-RAG: A Complete Setup Guide

Enable semantic search in Code-Graph-RAG by installing the semantic extra (pip install "code-graph-rag[semantic]"), starting a Qdrant vector store, and running the indexer to embed functions into a dense vector space.

Code-Graph-RAG (cgr) provides dense vector search capabilities that allow you to retrieve functions using natural language queries rather than exact string matching. According to the vitali87/code-graph-rag source code, this feature embeds source code fragments into a high-dimensional space and performs approximate nearest-neighbor (ANN) searches against a Qdrant vector store.

Understanding the Semantic Search Architecture

Embedding Layer

The embedding layer converts function source text into dense vectors using transformer models. In codebase_rag/embedder.py, the functions embed_code and embed_code_batch handle the vectorization, utilizing models from the semantic extra (specifically torch, transformers, and sentence-transformers).

Vector Store

Vectors are persisted in Qdrant via the thin wrapper implemented in codebase_rag/vector_store.py. This module provides search_embeddings for querying and upsert_embeddings for storing vectors.

Search Tool Interface

The LangChain-compatible tool is exposed through codebase_rag/tools/semantic_search.py. The semantic_code_search function (lines 44-46) embeds queries, while lines 46-48 handle the ANN search against Qdrant.

Step-by-Step: Enable Semantic Search in Code-Graph-RAG

1. Install the Semantic Extra

The heavy ML dependencies are optional. Install them using pip:

pip install "code-graph-rag[semantic]"

The pyproject.toml defines this extra under [project.optional-dependencies], pulling in torch, transformers, and sentence-transformers.

2. Configure the Vector Store

Start a Qdrant instance or point to an existing deployment using the VECTOR_STORE_URL environment variable. The default Docker Compose configuration includes a Qdrant service, but you can customize endpoints via cgr.yaml or environment variables.

3. Index Your Codebase

Run the graph updater to create embeddings for every function and method:

python -m codebase_rag.graph_updater --project my_project

This process calls embed_code_batch from embedder.py and stores results via vector_store.upsert_embeddings.

4. Verify Dependencies

The runtime guard in codebase_rag/utils/dependencies.py checks for the presence of ML libraries. If the check passes, the search tool activates automatically; otherwise, it degrades gracefully with a warning logged via ex.SEMANTIC_EXTRA (see lines 36-38 in semantic_search.py).

Querying Code with Natural Language

Programmatic Usage

Use the factory function create_semantic_search_tool to instantiate the search capability:

from codebase_rag.tools.semantic_search import create_semantic_search_tool

# ingestor implements QueryProtocol (e.g., Neo4j driver wrapper)

semantic_tool = create_semantic_search_tool(ingestor)

# Search for relevant functions

result = await semantic_tool.run(
    query="find the function that parses JSON", 
    top_k=5
)
print(result)  # Returns qualified names and similarity scores

Behind the scenes, the tool embeds your query using embed_code, searches Qdrant via search_embeddings, and resolves node IDs to metadata using Cypher queries (build_nodes_by_ids_query).

Retrieving Source Code

To fetch the actual source lines for a returned node ID, use the companion tool:

from codebase_rag.tools.semantic_search import create_get_function_source_tool

source_tool = create_get_function_source_tool(ingestor)
source_code = await source_tool.run(node_id="function_123")

The underlying get_function_source_code function (lines 11-51 in semantic_search.py) handles path validation and project-root security checks.

Summary

• Install the semantic extra: Run pip install "code-graph-rag[semantic]" to get PyTorch and transformer dependencies.
• Start Qdrant: Configure via cgr.yaml or VECTOR_STORE_URL environment variable.
• Index with graph_updater: Execute python -m codebase_rag.graph_updater --project my_project to vectorize functions.
• Use semantic tools: Import create_semantic_search_tool and create_get_function_source_tool from codebase_rag/tools/semantic_search.py.
• Graceful degradation: The dependency guard in utils/dependencies.py ensures the system warns rather than crashes if ML libraries are missing.

Frequently Asked Questions

What happens if I don't install the semantic extra?

If the ML stack is absent, the dependency guard in codebase_rag/utils/dependencies.py detects the missing imports. The semantic_code_search tool short-circuits early (lines 36-38) and logs a warning via ex.SEMANTIC_EXTRA, allowing the rest of Code-Graph-RAG to function without semantic capabilities.

Which embedding model does Code-Graph-RAG use?

The specific transformer model is configurable via cgr.yaml or environment variables. The embedder.py module uses sentence-transformers by default to encode both source code and natural language queries into the same dense vector space.

Can I use a different vector store instead of Qdrant?

While Qdrant is the default and ships with the Docker Compose configuration, the vector_store.py wrapper abstracts the client interface. You could extend it to support other ANN-compatible stores, though you would need to implement search_embeddings and upsert_embeddings methods for your chosen backend.

How do I verify that semantic search is active?

Check the runtime dependency guard by importing from codebase_rag.utils.dependencies. If it returns True for the semantic extra check, the search tool will be active. Additionally, successful execution of create_semantic_search_tool without ImportError exceptions confirms the embedding layer is functional.

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