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

> Install and use the Python SDK for Code-Graph-RAG. Explore repository parsing, knowledge-graph construction, and semantic search with the codebase_rag package and CLI.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: getting-started
- Published: 2026-08-19

---

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

```bash
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml).

**Graph Construction** – The [`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py), while Cypher query utilities and audit tools live in [`codebase_rag/cypher_queries.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cypher_queries.py) and [`codebase_rag/graph_audit.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_audit.py).

**CLI Interface** – A Typer-based command-line interface defined in [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) to parse a codebase into a queryable graph:

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py) to execute natural language queries against the graph:

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py):

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/examples/graph_export_example.py).

## Command-Line Interface

The CLI entry point (`cgr` or `code-graph-rag`) defined in [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) supports common workflows without requiring Python code:

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

```bash
cgr index /path/to/repo

```

**Search the indexed graph semantically**:

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

```

**Export the graph to GraphML** for external visualization tools:

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

```

All commands are registered via the `[project.scripts]` section of [`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml).

## Key Source Files

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

- **[`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml)** – Declares package metadata, tree-sitter dependencies, and CLI entry points.
- **[`codebase_rag/graph_loader.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py)** – Contains the `GraphLoader` class for AST parsing and initial graph construction.
- **[`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_updater.py)** – Implements `GraphUpdater` for incremental graph synchronization.
- **[`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py)** – Houses the `Embedder` class and semantic search implementations.
- **[`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py)** – Defines Typer commands and argument parsing logic.
- **[`codebase_rag/main.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/main.py)** – Core orchestration that wires configuration, loaders, and the CLI.
- **[`examples/graph_export_example.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py)) using natural language queries against code concepts.
- Enable live synchronization with `GraphUpdater` (from [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml).

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

Instantiate `GraphUpdater` from [`codebase_rag/graph_updater.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_loader.py) is language-agnostic and relies on tree-sitter bindings declared as dependencies in [`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml).

### Where is the CLI entry point defined?

The Typer-based CLI is implemented in [`codebase_rag/cli.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cli.py) and exposed through the `[project.scripts]` section of [`pyproject.toml`](https://github.com/vitali87/code-graph-rag/blob/main/pyproject.toml), making the `cgr` and `code-graph-rag` commands available immediately after installation.