Skip to content

README.md

Latest commit

 

History

History
86 lines (67 loc) · 3.65 KB

README.md

File metadata and controls

86 lines (67 loc) · 3.65 KB
Raw

CodeGraph 🕸️

CodeGraph is an open-source, AI-powered tool that transforms any public GitHub repository into an interactive, 2D force-directed knowledge graph in seconds.

By analyzing the Abstract Syntax Trees (AST) of the repository's source code and leveraging state-of-the-art Large Language Models, CodeGraph enables developers to instantly visualize, explore, and converse with complex codebases.

🚀 Features

  • Interactive Dependency Visualization: Explore codebases as a graph where nodes represent Files, Classes, and Functions, and edges represent relationships (calls, defines, imports, contains).
  • AI Code Summarization: Automatically generates plain-English summaries for every function and class using Groq (llama-3.3-70b) and Mistral AI.
  • PageRank Centrality: Automatically calculates node centrality using NetworkX to visually highlight the most important core functions (entry points and heavily utilized utilities).
  • Deep Syntax Parsing: Uses tree-sitter for precise, multi-language structural code parsing (Python currently optimized).
  • "Ask me anything" AI Chatbot: Interact with a context-aware AI assistant that answers questions grounded strictly in your repository's structure, streaming live tokens and guiding you directly to relevant nodes.
  • Code Inspector: View raw source code with syntax highlighting side-by-side with your graph. Features clickable inline node citations.
  • File Tree Navigation: Traverse the repository with a familiar VSCode-style sidebar that tightly syncs with the graph.
  • Shareable Links: Send your analyzed graph URL to your team for instant collaboration.

🛠️ Tech Stack

Backend

  • Framework: FastAPI (Python)
  • Code Parsing: tree-sitter
  • Graph Processing: NetworkX
  • AI Providers: Groq API, Mistral API
  • Streaming: Server-Sent Events (SSE) for both pipeline progress and LLM chatbot responses.

Frontend

  • Framework: React + Vite
  • Styling: TailwindCSS
  • Graph Renderer: react-force-graph-2d

⚙️ Getting Started

1. Prerequisites

  • Node.js (v18+)
  • Python (3.11+)
  • GitHub Personal Access Token
  • Groq API Key
  • Mistral API Key

2. Backend Setup

cd backend
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

Create a .env file in the backend/ directory:

GITHUB_TOKEN=your_github_token
GROQ_API_KEY=your_groq_api_key
MISTRAL_API_KEY=your_mistral_api_key
MAX_FILES=60
CACHE_DIR=./cache

Start the backend server:

uvicorn main:app --reload --port 8000

3. Frontend Setup

cd frontend
npm install

Start the development server:

npm run dev

Navigate to http://localhost:5173/ in your browser. Paste a GitHub repository URL and click Analyze Repo.

🧠 How it Works

  1. Ingestion: Downloads the target repository structure from the GitHub API.
  2. Parsing: Extracts functions, classes, docstrings, parameters, and dependencies using tree-sitter.
  3. Graph Building: Constructs a directed graph of the entire repository ecosystem using NetworkX, identifying isolated entry points and calculating mathematical centrality for UI scaling.
  4. AI Enrichment: Processes the abstract syntax data through Groq/Mistral to produce high-level human-readable summaries.
  5. Rendering & Chat: Sends the heavily optimized payload via SSE (Server-Sent Events) to the React frontend. Users can interact with the d3 layout in an HTML5 Canvas, view source files, or chat with the AI using context generated on-the-fly from the graph.

📝 License

This project is open-source and free to use.