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