⚡ GitExplain: Multi-Agent AI GitHub Research Assistant

GitExplain is a production-ready, modular multi-agent system designed to ingest, index, analyze, and explain GitHub repositories. Built with Python 3.11+, LangGraph, FastAPI, ChromaDB, Sentence Transformers, and Streamlit, it coordinates 13 specialized AI agents to deliver complete codebase understanding.

---

🏛️ System Architecture

                                  +-----------------------+
                                  |   Streamlit / Client  |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |   FastAPI REST API    |
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |  Director / Router    |
                                  |    (Qwen 2B / HF)     |
                                  +-----------+-----------+
                                              |
                        +---------------------+---------------------+
                        |                     |                     |
                        v                     v                     v
              +-------------------+ +-------------------+ +-------------------+
              |   GitHub Agent    | | Code Indexer Agt  | | Code Analysis Agt |
              | (Git MCP / GitPy) | | (AST/Tree-sitter) | | (Ruff/Bandit/Rad) |
              +---------+---------+ +---------+---------+ +---------+---------+
                        |                     |                     |
                        +---------------------+---------------------+
                                              |
                                              v
                                  +-----------------------+
                                  |  Embedding & Vector   |
                                  | (ChromaDB + BGE-large)|
                                  +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |    Retrieval Agent    |
                                  +-----------+-----------+
                                              |
                        +---------------------+---------------------+
                        |                     |                     |
                        v                     v                     v
              +-------------------+ +-------------------+ +-------------------+
              |  Reasoning Agent  | | Documentation Agt | |   Diagram Agent   |
              | (Gemma 31B Cloud) | |  (Docs / Guides)  | | (Mermaid Visuals) |
              +-------------------+ +-------------------+ +-------------------+
                                              |
                                              v
                                  +-----------------------+
                                  | SQLite Memory Agent   |
                                  +-----------------------+

---

🤖 The 13 Specialized AI Agents

#	Agent	Model / Tool	Primary Responsibility
1	Director / Router Agent	Qwen 2B Instruct / HF	Classifies user intent, breaks down requests into subtasks, returns execution plan.
2	Reasoning Agent	Gemma 31B Cloud API	Deep architectural analysis, cross-file reasoning, refactoring advice, and complex Q&A.
3	GitHub Agent	Git MCP / GitPython	Clones repos, inspects file trees, fetches commit history, branches, PRs, and issues.
4	Code Indexing Agent	AST / Tree-sitter	Parses source code, builds import dependency graphs, extracts symbols, detects frameworks.
5	Documentation Agent	Gemma 31B	Auto-generates README.md, Developer Onboarding Guide, and API Reference docs.
6	Embedding Agent	BAAI/bge-large / ChromaDB	Chunks code, docstrings, and markdown; embeds vectors into ChromaDB collections.
7	Retrieval Agent	Hybrid Vector Search	Performs semantic search over code vectors to retrieve context chunks before reasoning.
8	Memory Agent	SQLite / aiosqlite	Persists session history, user queries, repo cache, and conversation context.
9	Code Analysis Agent	Radon / Bandit / AST	Runs static code metric analysis (Cyclomatic complexity, Maintainability, Security scans).
10	Doc Search Agent	Tavily / Serper	Searches external documentation for libraries like FastAPI, React, PyTorch, LangChain.
11	Diagram Agent	Mermaid Synthesizer	Generates Mermaid diagrams (Architecture, Class, Sequence, Flowchart, Dependency).
12	File Explanation Agent	Gemma 31B	Performs line-by-line file walkthroughs, detailing purpose, inputs, outputs, and improvements.
13	Repo Summary Agent	Executive Synthesizer	Produces high-level executive summaries, technology stack evaluations, and SWOT analysis.

---

🚀 Quick Start Guide

1. Prerequisites

• Python 3.11+
• Git

2. Installation

# Clone or navigate to the repository
cd multiagent-github-assistant

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .[dev]

3. Environment Configuration

Copy .env.example to .env and set your API keys:

cp .env.example .env

Key configuration parameters:

• GEMINI_API_KEY: API Key for Gemma Cloud / Gemini API.
• USE_LOCAL_QWEN: Set to true to load local Qwen 2B model via HuggingFace transformers.

4. Running the Application

Option A: Local Development

Start the FastAPI backend service:

python -m app.main

The REST API will be live at http://localhost:8000 (Docs at http://localhost:8000/docs).

In another terminal, start the Streamlit UI:

streamlit run frontend/app.py

Open http://localhost:8501 in your browser.

Option B: Docker Compose

docker-compose -f docker/docker-compose.yml up --build

---

🧪 Running Tests & Quality Verification

# Run unit and integration test suite
pytest -v tests/

# Run static linting
ruff check app/ tests/

---

🔌 API Endpoints Reference

• POST /api/v1/repo/clone: Clone or ingest a GitHub repository.
• POST /api/v1/analysis/run: Trigger full 13-agent LangGraph workflow execution.
• POST /api/v1/analysis/chat: Semantic RAG chat over indexed codebase.
• POST /api/v1/analysis/explain-file: Deep walkthrough for a specific file.
• GET /api/v1/analysis/summary/{repo_name}: Retrieve cached executive summary and diagrams.

---

📚 Full Documentation

For a comprehensive guide, detailed architectural overview, agent workflows, and advanced configurations, please refer to the Full Documentation.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.