⚡ 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.

Related MCP server: Qurio MCP Server

🛠️ 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

🖥️ 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.