CodeGraph AI

CodeGraph AI is a CLI tool that analyzes your Python codebase and visualizes it as an interactive knowledge graph.

It helps developers understand:

• Code structure
• Function call relationships
• File dependencies
• Overall architecture

---

Features

• AST-based parsing of Python code
• Function call graph generation
• Dependency graph (imports)
• Interactive visualization in browser
• Graph-aware RAG — ask questions about your codebase using AI
• Multi-modal asset parsing (CSV, JSON, PDF, images, databases)
• Focus on specific files
• Hide external libraries (stdlib & third-party)
• Fast CLI-based workflow

---

Installation

pip install codegraph-ai

---

Quick Start

codegraph index
codegraph plot

---

Commands

1. Index your codebase

Scan and build the graph:

codegraph index

Index a specific folder:

codegraph index path/to/your/project

Options

Flag	Default	Description
--embedder	sentence-transformers	Embedding provider: sentence-transformers, openai, anthropic, google
--embedder-model	provider default	Override the default embedding model
--skip-embed	false	Build the graph only, skip FAISS embedding

codegraph index --embedder openai
codegraph index --embedder anthropic --embedder-model claude-3-haiku-20240307
codegraph index --skip-embed

---

2. Visualize the graph

codegraph plot

This opens an interactive graph in your browser.

Options

Flag	Default	Description
--hide-external	false	Hide external/stdlib nodes
--level	all	Show only: file, function, class, method
--focus	none	Focus on a specific file (e.g. cli.py)
--edge-type	all	Filter edges: calls, imports, contains, all

---

3. Ask questions about your codebase

Use graph-aware RAG to query your codebase in natural language:

codegraph ask "How does the authentication flow work?"

Options

Flag	Default	Description
--llm	anthropic	LLM provider: anthropic, openai, google
--llm-model	provider default	Override the default LLM model
--top-k	5	Number of graph nodes to retrieve as context

codegraph ask "What does the GraphBuilder class do?" --llm openai
codegraph ask "Which functions call the embedder?" --llm anthropic --top-k 10

Note: Requires a FAISS index. Run codegraph index without --skip-embed first.

---

4. Save an API key

Permanently store an API key so you are never prompted again:

codegraph set-key anthropic  sk-ant-...
codegraph set-key openai     sk-...
codegraph set-key google     AIza...

Keys are saved locally and reused automatically by the index and ask commands.

---

5. Explain a file (coming soon)

codegraph explain path/to/file.py

Options

Flag	Default	Description
--llm	anthropic	LLM provider: anthropic, openai, google

---

6. Audit your codebase (coming soon)

Detect missing docs, unused code, and hidden dependencies:

codegraph audit

---

Advanced Usage

Hide external libraries

Removes standard library and third-party dependencies from the graph:

codegraph plot --hide-external

---

Focus on a specific file

Shows only a file and its direct relationships:

codegraph plot --focus cli.py

---

Filter by node type

Show only certain types of nodes:

codegraph plot --level file
codegraph plot --level function
codegraph plot --level class

---

Filter by edge type

Show only specific relationships:

codegraph plot --edge-type calls
codegraph plot --edge-type imports
codegraph plot --edge-type contains
codegraph plot --edge-type all

---

Combine filters

codegraph plot --focus cli.py --hide-external --edge-type calls

---

How It Works

1. Parses Python files using AST
2. Parses assets (CSV, JSON, PDF, images, SQLite databases)
3. Extracts:
   • Functions, classes, imports, and function calls
   • Asset metadata: columns, tables, keys, page counts, OCR text
4. Builds a directed knowledge graph
5. Embeds all nodes into a FAISS vector index
6. Renders an interactive visualization, or answers questions via RAG

---

Graph Semantics

Node Types

Type	Description
File	Python source file
Function	Function or method
Class	Class definition
Module	External dependency
Dataset	CSV or tabular data file
Database	SQLite database
Document	PDF document
Image	Image file (PNG, JPG, JPEG)

---

Edge Types

Relation	Meaning
contains	File or class contains a node
calls	Function calls another function
imports	File imports a module
defined_in	Function belongs to a file
uses	Code references an asset
references	Node references another node

---

Output Files

After indexing:

.codegraph/
  graph.json       # Knowledge graph
  faiss.index      # Vector index for semantic search

After visualization:

graph.html

---

Example Workflow

# Index and embed
codegraph index --embedder sentence-transformers

# Explore visually
codegraph plot --hide-external

# Ask questions
codegraph ask "What are the main entry points of this project?"

---

Use Cases

• Understand large codebases quickly
• Visualize architecture
• Debug dependencies
• Explore function interactions
• Ask natural language questions about your code
• Prepare for refactoring

---

Author

Aditya Jogdand

---

License

MIT License