VibeGraph

Turn any Python project into an interactive, AI-powered learning experience.

Upload your code → explore the call graph → ask AI anything about it.

---

What is VibeGraph?

VibeGraph parses any Python codebase with AST analysis, renders it as an interactive graph, and lets you click any function or class to get an AI explanation, ask follow-up questions, or watch a "Ghost Runner" animate the execution flow in real time.

Built for people who learn by exploring — vibe coders, junior devs, or anyone dropped into an unfamiliar repo.

---

Screenshots

Interactive call graph — file sidebar, node type filtering	AI explanation panel — click any node, get Technical or Analogy view
AI chat — multi-turn conversation with full code context	Dependency map — imports and relationships per file

---

Features

	Feature	Description
🧬	Interactive Call Graph	Functions, classes, and relationships as a zoomable, pannable graph
👻	Ghost Runner	Watch an AI "ghost" traverse execution paths in real time (Slow / Normal / Fast)
🔍	Node Search	Fuzzy search across all nodes with Ctrl+K — instantly zooms and highlights
💬	AI Chat	Multi-turn conversation about any node — AI holds the full source as context
🎓	Learning Path	AI-suggested study order: start here, then go here, for any file
📝	Code Panel	Source code with line numbers for every selected node
💡	AI Explanations	Beginner / Intermediate / Advanced levels, Technical or Analogy mode
📤	Upload Any Project	Drop .py files or a .zip of your whole project — graph appears instantly

---

Quick Start

Prerequisites

• Python 3.10+
• Node.js 18+
• Groq API key — free tier at console.groq.com (no credit card required)

1. Clone

git clone https://github.com/madara88645/VibeGraph.git
cd VibeGraph

2. Install dependencies

# Python backend
pip install -r requirements.txt

# React frontend
cd explorer && npm install && cd ..

3. Configure

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key_here

4. Run

Development mode (hot reload on both sides):

# Terminal 1 — backend
python serve.py

# Terminal 2 — frontend
cd explorer && npm run dev

Open http://localhost:5173

---

Production mode (single port, no Node needed after build):

cd explorer && npm run build && cd ..
python serve.py

Open http://localhost:8000

---

5. Use it

Upload your project — click Upload Project in the top bar, select .py files or a .zip archive. The graph appears automatically.

Analyze via CLI (optional, for local files):

python main.py analyze path/to/your_project/

---

Project Structure

VibeGraph/
├── analyst/
│   ├── analyzer.py        # AST parser → NetworkX graph (nodes + edges)
│   └── exporter.py        # NetworkX → React Flow JSON
├── teacher/
│   └── groq_agent.py      # Groq LLM: explain / chat / learning path
├── explorer/              # React 19 + Vite frontend
│   └── src/components/    # GraphViewer, ChatDrawer, CodePanel, ...
├── tests/                 # 24 pytest tests
├── serve.py               # FastAPI backend (all API routes)
├── main.py                # CLI entry point
└── requirements.txt

---

API

Method	Endpoint	Description
GET	/api/health	Health check
POST	/api/upload-project	Upload .py/.zip, returns graph JSON
POST	/api/snippet	Extract source code for a node
POST	/api/explain	AI explanation for a node
POST	/api/chat	Multi-turn AI conversation
POST	/api/learning-path	AI-suggested learning order

---

Tech Stack

Layer	Technology
Backend	Python, FastAPI, NetworkX, ast stdlib
AI	Groq API — Llama 3 (free tier)
Frontend	React 19, React Flow, Vite
Styling	Custom CSS — dark theme, glassmorphism
Tests	pytest, 24 tests

---

Tests

pytest tests/ -v

---

License

GPLv3