Python SDK for Code-Graph-RAG: Installation and Usage Guide

The Python SDK for Code-Graph-RAG is the code-graph-rag package on PyPI that exposes repository parsing, knowledge-graph construction, and semantic search through the codebase_rag namespace and a Typer-based CLI.

The vitali87/code-graph-rag repository provides a first-party Python SDK designed for programmatic code intelligence. It bridges language-agnostic AST parsing with graph-based retrieval, allowing you to build searchable knowledge graphs from any codebase and query them using natural language or structured traversals.

Installation

Install the SDK from PyPI to access both the library and command-line tools:

pip install code-graph-rag

This command installs the codebase_rag package and registers the cgr (or code-graph-rag) CLI entry point declared in the repository's pyproject.toml.

Architecture Overview

The SDK organizes functionality into distinct layers that mirror the repository's source structure:

Parsing & AST Analysis – Uses tree-sitter grammars for language-agnostic source parsing. Dependencies for specific languages (e.g., tree-sitter-python, tree-sitter-c) are declared in pyproject.toml.

Graph Construction – The codebase_rag/graph_loader.py module walks ASTs, resolves imports, and builds a knowledge graph containing definitions, function calls, and inheritance relationships.

Graph Updating – Incremental synchronization is handled by codebase_rag/graph_updater.py, which provides filesystem watching to update the graph as files change without full re-indexing.

Query & Retrieval – Semantic embeddings and search logic reside in codebase_rag/embedder.py, while Cypher query utilities and audit tools live in codebase_rag/cypher_queries.py and codebase_rag/graph_audit.py.

CLI Interface – A Typer-based command-line interface defined in codebase_rag/cli.py exposes these capabilities for shell scripts and CI pipelines.

Programmatic Usage

Loading a Repository and Building the Graph

Import the GraphLoader class from codebase_rag/graph_loader.py to parse a codebase into a queryable graph:

from codebase_rag.graph_loader import GraphLoader

# Initialize loader pointing at repository root

loader = GraphLoader(
    repo_path="path/to/your/repo",      # Absolute or relative path

    language="python",                 # Supports "python", "java", "go", etc.

)

# Build the full graph (parses all files and resolves imports)

graph = loader.load()

# Inspect basic statistics

print(f"Nodes: {len(graph.nodes)}")
print(f"Relationships: {len(graph.relationships)}")

Performing Semantic Search

Use the Embedder class from codebase_rag/embedder.py to execute natural language queries against the graph:

from codebase_rag.embedder import Embedder

embedder = Embedder(model_name="sentence-transformers/all-MiniLM-L6-v2")
results = embedder.semantic_search(
    query="How does the `UserService` create a new user?",
    graph=graph,
    top_k=5,
)

for r in results:
    print(r.node_id, r.score, r.snippet)

Keeping the Graph Synchronized

For live updates while editing files, instantiate GraphUpdater from codebase_rag/graph_updater.py:

from codebase_rag.graph_updater import GraphUpdater

updater = GraphUpdater(loader)  # Watches the repo_path

updater.start()                 # Runs in background

# ... edit files ...

updater.stop()                  # Cleanup when done

This pattern mirrors the reference implementation provided in examples/graph_export_example.py.

Command-Line Interface

The CLI entry point (cgr or code-graph-rag) defined in codebase_rag/cli.py supports common workflows without requiring Python code:

Index a repository (creates a .cgr directory with the graph):

cgr index /path/to/repo

Search the indexed graph semantically:

cgr semantic-search "find all functions that write to a log file"

Export the graph to GraphML for external visualization tools:

cgr export-graph --format graphml /path/to/repo > graph.graphml

All commands are registered via the [project.scripts] section of pyproject.toml.

Key Source Files

Understanding the repository structure helps when extending the SDK or debugging:

• pyproject.toml – Declares package metadata, tree-sitter dependencies, and CLI entry points.
• codebase_rag/graph_loader.py – Contains the GraphLoader class for AST parsing and initial graph construction.
• codebase_rag/graph_updater.py – Implements GraphUpdater for incremental graph synchronization.
• codebase_rag/embedder.py – Houses the Embedder class and semantic search implementations.
• codebase_rag/cli.py – Defines Typer commands and argument parsing logic.
• codebase_rag/main.py – Core orchestration that wires configuration, loaders, and the CLI.
• examples/graph_export_example.py – End-to-end usage demonstrations.

Summary

• Install the Python SDK for Code-Graph-RAG via pip install code-graph-rag to access the codebase_rag namespace and cgr CLI.
• Use GraphLoader (from codebase_rag/graph_loader.py) to parse repositories and build knowledge graphs from ASTs with resolved imports.
• Perform semantic searches with Embedder (from codebase_rag/embedder.py) using natural language queries against code concepts.
• Enable live synchronization with GraphUpdater (from codebase_rag/graph_updater.py) to watch filesystem changes without re-indexing the entire repository.
• Execute common indexing and querying workflows through the cgr CLI for automation and CI integration.

Frequently Asked Questions

What package name do I use to install the Python SDK for Code-Graph-RAG?

Install using pip install code-graph-rag. This distributes the codebase_rag Python package and registers the cgr command-line entry point specified in the repository's pyproject.toml.

How do I incrementally update the knowledge graph when source files change?

Instantiate GraphUpdater from codebase_rag/graph_updater.py, passing it an existing GraphLoader instance. Call updater.start() to begin filesystem watching in a background thread, then invoke updater.stop() when you finish editing to release resources.

Can I use the SDK with languages other than Python?

Yes. The GraphLoader class accepts a language parameter (e.g., "java", "go", "c") that selects the appropriate tree-sitter grammar. The parsing layer in codebase_rag/graph_loader.py is language-agnostic and relies on tree-sitter bindings declared as dependencies in pyproject.toml.

Where is the CLI entry point defined?

The Typer-based CLI is implemented in codebase_rag/cli.py and exposed through the [project.scripts] section of pyproject.toml, making the cgr and code-graph-rag commands available immediately after installation.

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