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

[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

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.

Windows 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

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:

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

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

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:

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:

{
  "mcpServers": {
    "codebase-analyser": {
      "command": "python",
      "args": ["-m", "aica.mcp_server"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}

---

📄 License

Distributed under the MIT License.