Metadata-Version: 2.4
Name: codegraph-cli-ai
Version: 0.2.2
Summary: CLI tool to analyze Python codebases, visualize knowledge graphs, and query code using AI
Author: Aditya Jogdand
License: MIT
Project-URL: Homepage, https://github.com/AdityaJogdand/codegraph-ai
Project-URL: Repository, https://github.com/AdityaJogdand/codegraph-ai
Project-URL: Bug Tracker, https://github.com/AdityaJogdand/codegraph-ai/issues
Keywords: code-analysis,ast,graph,cli,developer-tools,rag,knowledge-graph,embeddings,faiss,llm
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.9.0
Requires-Dist: networkx>=3.0
Requires-Dist: pyvis>=0.3.2
Requires-Dist: sentence-transformers>=2.2.0
Requires-Dist: faiss-cpu>=1.7.4
Requires-Dist: pypdf>=3.0.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: pytesseract>=0.3.10
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.20.0; extra == "anthropic"
Provides-Extra: google
Requires-Dist: google-genai>=1.0.0; extra == "google"
Provides-Extra: all-llms
Requires-Dist: openai>=1.0.0; extra == "all-llms"
Requires-Dist: anthropic>=0.20.0; extra == "all-llms"
Requires-Dist: google-genai>=1.0.0; extra == "all-llms"
Provides-Extra: all
Requires-Dist: openai>=1.0.0; extra == "all"
Requires-Dist: anthropic>=0.20.0; extra == "all"
Requires-Dist: google-genai>=1.0.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# 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

```bash
pip install codegraph-ai
```

---

## Quick Start

```bash
codegraph index
codegraph plot
```

---

## Commands

### 1. Index your codebase

Scan and build the graph:

```bash
codegraph index
```

Index a specific folder:

```bash
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 |

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

---

### 2. Visualize the graph

```bash
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:

```bash
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 |

```bash
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:

```bash
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)*

```bash
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:

```bash
codegraph audit
```

---

## Advanced Usage

### Hide external libraries

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

```bash
codegraph plot --hide-external
```

---

### Focus on a specific file

Shows only a file and its direct relationships:

```bash
codegraph plot --focus cli.py
```

---

### Filter by node type

Show only certain types of nodes:

```bash
codegraph plot --level file
codegraph plot --level function
codegraph plot --level class
```

---

### Filter by edge type

Show only specific relationships:

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

---

### Combine filters

```bash
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

```bash
# 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
