Content
# ⚡ CodeBase Analyser
An intelligent, AI-driven codebase analytics engine powered by **Retrieval-Augmented Generation (RAG)**. It performs precise repository analysis with **hybrid search**, **language-aware AST chunking**, **exact line-level citations**, and **MCP (Model Context Protocol)** tools for seamless integration with IDEs and AI agents.
---
## ✨ Features
- **🔍 Hybrid Retrieval Pipeline (Dense + Sparse)**: Combines **FAISS** dense vector search with **BM25** sparse keyword retrieval via **Reciprocal Rank Fusion (RRF)** for high precision on exact code identifiers.
- **🌳 Language-Aware AST Chunking**: Uses `langchain-text-splitters` to split code along syntactic boundaries (functions, methods, classes) rather than arbitrary mechanical line cutoffs.
- **📌 Exact Line-Level Source Citations**: Direct links and line ranges (`path/file.py:L10-L45`) for full traceability and hallucination prevention.
- **⚡ Persistent Index & Chunk Caching**: Caches generated FAISS indices and metadata (`chunks.jsonl`) to disk for instant loading on subsequent queries.
- **🔌 Model Context Protocol (MCP) Tools**: Exposes modular tools for repository ingestion, semantic search, and context retrieval to external AI clients (Claude Desktop, Cursor, VS Code).
- **🎨 Modern Web UI & CLI**: Dark-mode web interface with dynamic Markdown rendering alongside a fast, production-ready CLI.
---
## 🛠️ Architecture Overview
```text
[Git Repo URL / Directory]
│
▼
[AST / Language Splitter] ──► Preserves syntactic code structure
│
├──► [FAISS Index] (Dense Semantic Vectors) ──┐
│ ├──► [RRF Fusion] ──► [LLM Context & Citations]
└──► [BM25 Index] (Exact Identifier Tokens) ──┘
```
---
## 📋 Requirements
- Python 3.11+
- `git`
---
## 🚀 Quick Start & Installation
### 1. Clone & Set Up Environment
```bash
python -m venv .venv
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt
```
### 2. Configure Gemini API Key
Get an API key from [Google AI Studio](https://aistudio.google.com/apikey).
**Windows PowerShell**
```powershell
$env:AICA_LLM_PROVIDER="gemini"
$env:AICA_GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
$env:AICA_GEMINI_MODEL="gemini-2.5-pro"
```
**Linux/macOS**
```bash
export AICA_LLM_PROVIDER="gemini"
export AICA_GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
export AICA_GEMINI_MODEL="gemini-2.5-pro"
```
### Recommended Models
| Model | Recommended Use Case |
|--------|----------------------|
| `gemini-2.5-pro` | Best reasoning for complex code and architecture questions |
| `gemini-2.0-flash-lite` | Ultra-fast and efficient for rapid Q&A |
| `gemini-1.5-flash` | Stable fallback option |
---
## 🖥️ Web UI & CLI Usage
### Web UI (Recommended)
Start the FastAPI application:
```bash
python -m aica.web_app
# or using PowerShell script
.\run_web.ps1
```
Open **http://127.0.0.1:8080** to view the dashboard, configure model parameters, ingest repositories, and query with real-time Markdown-rendered citations.
### CLI Usage
#### Ingest a Repository
```bash
python -m aica ingest https://github.com/pallets/flask
```
Creates:
- `data/repos/<repo_hash>/` – Cloned repository files
- `data/index/<repo_hash>/` – FAISS index and chunk metadata
#### Ask a Question
```bash
python -m aica ask https://github.com/pallets/flask "Where is the request context created?" --top-k 4 --show-citations
```
---
## 🔌 MCP Server (For External AI Agents & IDEs)
Run the MCP server locally:
```bash
python -m aica.mcp_server
```
### Exposed Tools
- `ingest_repo_tool(repo_url)`
- `search_code(repo_url, query, top_k)`
- `ask_repo(repo_url, question, top_k)`
### Integrating with Claude Desktop / Cursor
Add the server to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"codebase-analyser": {
"command": "python",
"args": ["-m", "aica.mcp_server"],
"env": {
"PYTHONPATH": "."
}
}
}
}
```
---
## 📄 License
Distributed under the MIT License.
