Update README.md

README.md

@@ -1,638 +1,337 @@
-# 🤖 AI Codebase Assistant — Complete Documentation
+# AI Codebase Assistant
 
-> An AI-powered developer tool that ingests any local code repository, answers questions about it using RAG (Retrieval-Augmented Generation), detects bugs, measures complexity, generates docs, proposes new files, and integrates with the GitHub MCP API — all from an interactive CLI.
+An AI-powered developer tool that lets you interact with an entire code repository using **RAG (Retrieval-Augmented Generation)** and LLMs.
+
+It can answer questions about your codebase, detect potential bugs, analyze code complexity, explain functions, generate documentation, create new files, and interact with GitHub through the GitHub MCP API.
 
 ---
 
-## Table of Contents
+## Features
 
-1. [Project Overview](#1-project-overview)
-2. [Repository Structure](#2-repository-structure)
-3. [Architecture & Flow](#3-architecture--flow)
-4. [Component Deep-Dive](#4-component-deep-dive)
-5. [Setup & Installation](#5-setup--installation)
-6. [Configuration (.env)](#6-configuration-env)
-7. [Running the CLI](#7-running-the-cli)
-8. [CLI Features — All 9 Options](#8-cli-features--all-9-options)
-9. [REST API](#9-rest-api)
-10. [Key Design Decisions & Bug Fixes](#10-key-design-decisions--bug-fixes)
-11. [Extending the Project](#11-extending-the-project)
+### Codebase Question Answering
 
----
+Ask natural-language questions about your repository.
 
-## 1. Project Overview
+**Example:**
 
-The **AI Codebase Assistant** is a local developer tool that:
+```text
+How does authentication work?
+```
 
-- 📂 **Ingests** any code repository (Python, JS, TS, Java, Go, Markdown)
-- 🔍 **Answers questions** about the code using RAG + LLM
-- 🐛 **Detects bugs** via LLM-powered code review
-- 📊 **Measures cyclomatic complexity** using Radon
-- 📝 **Explains functions** in plain English
-- 📄 **Generates module docs and READMEs** automatically
-- 🛠️ **Proposes & creates new files** using AI, saved to your chosen directory
-- 🔗 **Lists 44 GitHub MCP tools** via the GitHub Copilot MCP API
+The assistant searches the relevant parts of the codebase and generates an answer with source references.
 
-**LLM Providers supported:**
-| Provider | Model | Notes |
-|---|---|---|
-| Groq | `llama-3.3-70b-versatile` | Free tier, recommended |
-| Gemini | Configurable | Paid, stricter quota |
+---
 
-**Embedding:** Google Gemini Embedding API (`models/gemini-embedding-001`)  
-**Vector Store:** ChromaDB (local persistent)
+### Bug Detection
 
----
+Analyze a source file and identify potential issues using an LLM-powered code review.
 
-## 2. Repository Structure
+Example:
 
+```text
+[HIGH] Line 34
+SQL query uses string concatenation
+
+Recommendation:
+Use parameterized queries to prevent SQL injection.
 ```
-Codebase Assistant/
-│
-├── cli.py                     # ← Main entry point (interactive CLI)
-├── app.py                     # ← FastAPI REST server (optional)
-├── config.py                  # ← All settings via pydantic-settings + .env
-├── llm.py                     # ← LLM abstraction (Gemini / Groq) + prompt templates
-├── mcp_client.py              # ← GitHub MCP async context-manager client
-├── requirements.txt           # ← All Python dependencies
-├── .env                       # ← API keys and configuration (not committed)
-│
-├── rag/                       # ── RAG Pipeline ──────────────────────────────
-│   ├── repository_loader.py   #   Walk directory, read files → CodeDocument
-│   ├── splitter.py            #   Split CodeDocuments into chunks with metadata
-│   ├── embedding.py           #   Embed chunks/queries via Gemini Embeddings
-│   ├── retriever.py           #   ChromaDB vector store: build / load / query
-│   └── rag_chain.py           #   Orchestrate retrieve → build context → LLM
-│
-├── services/                  # ── Feature Services ──────────────────────────
-│   ├── code_analysis.py       #   Bug detection, complexity, function explainer
-│   ├── documentation.py       #   Module docs, README generator
-│   └── file_creator.py        #   AI file proposal + local disk write
-│
-├── api/                       # ── REST API (FastAPI) ────────────────────────
-│   └── routes.py              #   All HTTP endpoints (mirrors CLI features)
-│
-└── vector_db/                 # ── ChromaDB Storage (auto-created) ───────────
-    └── chroma.sqlite3         #   Persisted vector embeddings
-```
+
+The system returns the issue severity, location, and recommendation.
 
 ---
 
-## 3. Architecture & Flow
-
-### 3.1 Full System Architecture
-
-```mermaid
-graph TB
-    subgraph USER["User Interface"]
-        CLI["cli.py\n(Interactive CLI)"]
-        API["app.py\n(FastAPI REST API)"]
-    end
-
-    subgraph RAG["RAG Pipeline"]
-        RL["repository_loader.py\nWalk & read files"]
-        SP["splitter.py\nChunk by language"]
-        EM["embedding.py\nGemini Embeddings"]
-        RT["retriever.py\nChromaDB"]
-        RC["rag_chain.py\nOrchestrator"]
-    end
-
-    subgraph SERVICES["Feature Services"]
-        CA["code_analysis.py\nBugs · Complexity · Explain"]
-        DOC["documentation.py\nModule Docs · README"]
-        FC["file_creator.py\nAI File Creator"]
-    end
-
-    subgraph EXTERNAL["External APIs"]
-        GROQ["Groq API\nllama-3.3-70b"]
-        GEM["Gemini API\nEmbeddings"]
-        MCP["GitHub MCP\n44 tools"]
-    end
-
-    LLM["llm.py\nLLM Abstraction Layer"]
-    CFG["config.py\n.env Settings"]
-    DB[("vector_db/\nChromaDB")]
-
-    CLI --> RAG
-    CLI --> SERVICES
-    API --> RAG
-    API --> SERVICES
-
-    RL --> SP --> EM --> RT
-    RT --> DB
-    RC --> RT
-    RC --> LLM
-
-    CA --> LLM
-    DOC --> LLM
-    FC --> LLM
-
-    LLM --> GROQ
-    LLM --> GEM
-    EM --> GEM
-    CLI --> MCP
-
-    CFG -.->|settings| RAG
-    CFG -.->|settings| LLM
-    CFG -.->|settings| SERVICES
-```
+### Cyclomatic Complexity Analysis
 
-### 3.2 Ingest Flow (Step-by-step)
-
-```mermaid
-flowchart LR
-    A["User provides\nrepo path"] --> B["repository_loader.py\nwalk directories\nskip: .git venv __pycache__"]
-    B --> C["Filter by\nallowed extensions\n.py .js .ts .java .go .md"]
-    C --> D["Read each file\n→ CodeDocument\n(content, path, language, size)"]
-    D --> E["splitter.py\nLanguage-aware chunking\nRecursiveCharacterTextSplitter"]
-    E --> F["Each chunk gets\nmetadata: file_path\nlanguage · start_line · end_line"]
-    F --> G["embedding.py\nGemini embed_documents\n→ float vectors"]
-    G --> H["retriever.py\nDelete old collection\nCreate fresh ChromaDB\ncollection.add(...)"]
-    H --> I["✓ Vector store ready"]
-```
+Analyze the complexity of Python functions using **Radon**.
 
-### 3.3 RAG Query Flow
+Example:
 
-```mermaid
-flowchart LR
-    Q["User question"] --> E["embed_query\n(Gemini)"]
-    E --> S["ChromaDB\ncollection.query\ntop-k chunks"]
-    S --> C["build_context\nformat chunks\nwith file/line headers"]
-    C --> P["build_prompt\nqa template\ncontext + question"]
-    P --> L["LLM\n(Groq / Gemini)"]
-    L --> A["Answer + Sources\n(file_path, line range)"]
+```text
+[A] process_order        complexity = 2
+[B] validate_cart        complexity = 5
+[C] apply_discounts     complexity = 8
+[F] handle_edge_cases   complexity = 18
 ```
 
-### 3.4 CLI Menu Flow
-
-```mermaid
-flowchart TD
-    START([Start cli.py]) --> REPO["▶ Enter repo path"]
-    REPO --> INGEST["Ingest Repository\nload → split → embed → store"]
-    INGEST --> MENU["Show Menu\nOptions 1–9"]
-
-    MENU --> O1["1 Ask a question\n→ RAG Query"]
-    MENU --> O2["2 Detect bugs\n→ LLM code review"]
-    MENU --> O3["3 Cyclomatic complexity\n→ Radon"]
-    MENU --> O4["4 Explain function\n→ AST + LLM"]
-    MENU --> O5["5 Module docs\n→ LLM"]
-    MENU --> O6["6 Generate README\n→ LLM"]
-    MENU --> O7["7 Propose & create file\n→ LLM + local write"]
-    MENU --> O8["8 List GitHub MCP tools\n→ GitHub Copilot MCP"]
-    MENU --> O9["9 Re-ingest repo\n→ new repo path"]
-    MENU --> O0["0 Exit"]
-
-    O1 & O2 & O3 & O4 & O5 & O6 & O7 & O8 & O9 --> MENU
-    O0 --> END([Goodbye!])
-```
+This helps identify functions that may be difficult to maintain or test.
 
 ---
 
-## 4. Component Deep-Dive
-
-### 4.1 `config.py` — Settings
+### Function Explanation
 
-All configuration lives in one `pydantic-settings` class loaded from `.env`:
+Select a function and get a plain-English explanation of what it does.
 
-| Setting | Default | Description |
-|---|---|---|
-| `llm_provider` | `"groq"` | `"groq"` or `"gemini"` |
-| `groq_api_key` | `""` | From `.env` |
-| `groq_model` | `"llama-3.3-70b-versatile"` | Free Groq model |
-| `gemini_api_key` | `""` | From `.env` |
-| `embedding_model` | `"models/gemini-embedding-001"` | Always Gemini for embeddings |
-| `vector_db_path` | `"./vector_db"` | ChromaDB storage directory |
-| `chunk_size` | `1200` | Characters per chunk |
-| `chunk_overlap` | `100` | Overlap between chunks |
-| `allowed_extensions` | `[.py .js .ts .go .java .md]` | File types to load |
-| `max_file_size_kb` | `1042` | Skip files larger than this |
-| `github_mcp_url` | GitHub Copilot MCP endpoint | For option 8 |
-| `github_mcp_token` | `""` | GitHub PAT from `.env` |
-
-### 4.2 `rag/repository_loader.py` — File Ingestion
+For Python code, the project uses the `ast` module to extract the function and provides relevant repository context to the LLM.
 
-```
-load_repository(root_path)
-  └── os.walk(root_path)
-        ├── Skip: .git, node_modules, __pycache__, venv, .venv, dist, build
-        ├── should_include(fpath) → checks extension + file size
-        └── read_file_with_metadata(fpath) → CodeDocument(content, file_path, language, size_bytes)
-```
+---
 
-**Supported languages detected by extension:**
+### Documentation Generation
 
-| Extension | Language |
-|---|---|
-| `.py` | python |
-| `.js` | javascript |
-| `.ts` | typescript |
-| `.java` | java |
-| `.go` | go |
-| `.md` | markdown |
+Generate documentation automatically for your codebase.
 
-### 4.3 `rag/splitter.py` — Chunking
+The assistant can generate:
 
-Uses **LangChain's `RecursiveCharacterTextSplitter`** with language-aware splitting:
-- For Python/JS/TS/Java/Go — uses syntax-aware boundaries (functions, classes)
-- For Markdown/unknown — falls back to generic character splitting
-- Each chunk carries: `content`, `file_path`, `language`, `chunk_index`, `start_line`, `end_line`
+- Module documentation
+- Function explanations
+- Docstrings
+- Repository README files
 
-### 4.4 `rag/embedding.py` — Embeddings
+---
 
-- Uses `GoogleGenerativeAIEmbeddings` (`models/gemini-embedding-001`)
-- `embed_document(chunks)` — batch embeds all chunks, mutates dicts in-place
-- `embed_query(query)` — single query vector for similarity search
+### AI File Generation
 
-### 4.5 `rag/retriever.py` — Vector Store
+Describe the file you want to create and let the AI generate it.
 
-> **Critical fix applied:** collection is deleted and recreated on every ingest to prevent stale data from previous repos bleeding through.
+Example:
 
-```python
-build_vector_store(chunks)     # delete → create → add (fresh each ingest)
-load_vector_store()            # get_or_create for reading
-retrieve_relevant_chunks(q, k) # embed query → cosine similarity → top-k
+```text
+Create a Rectangle class in JavaScript
+that calculates area and perimeter.
 ```
 
-### 4.6 `rag/rag_chain.py` — Orchestration
-
-```python
-run_rag_query(query, k=5)
-  1. retrieve_relevant_chunks(query, k)
-  2. build_context(chunks)         # format with file/line headers
-  3. build_prompt(query, context)  # fill qa template
-  4. llm.generate(prompt)
-  5. return { answer, sources }
-```
+The generated file is shown before it is written to the repository, allowing the user to approve it first.
 
-### 4.7 `llm.py` — LLM Abstraction
+---
 
-Abstract `BaseLLM` with two concrete providers:
+### GitHub MCP Integration
 
-| Class | Provider | API |
-|---|---|---|
-| `GeminiLLM` | Google Gemini | `google-genai` SDK |
-| `GroqLLM` | Groq | `groq` SDK, chat completions |
+The project integrates with the **GitHub Copilot MCP API**.
 
-**Prompt templates (`build_prompt`):**
+It currently supports access to **44 GitHub MCP tools**, including:
 
-| `task_type` | Used by |
-|---|---|
-| `"qa"` | RAG query, function explain, module docs, README |
-| `"bug_finding"` | Bug detection (returns JSON) |
-| `"docstring"` | Docstring generation |
-| `"file_creation"` | AI file proposal |
+- `search_code`
+- `search_repositories`
+- `get_file_contents`
+- `list_issues`
+- `create_branch`
+- `create_pull_request`
+- `push_files`
+- `fork_repository`
 
-### 4.8 `mcp_client.py` — GitHub MCP Client
+---
 
-Async context-manager pattern using `AsyncExitStack` to keep all `anyio` cancel scopes in the **same task**:
+## RAG-Based Code Search
 
-```python
-async with get_github_mcp_client() as client:
-    tools = await client.list_tools()
-    result = await client.call_tool("create_branch", {...})
-```
+The project uses **Retrieval-Augmented Generation (RAG)** to work with repository-level code.
 
-Available GitHub MCP tools (44 total) include: `search_code`, `list_issues`, `create_pull_request`, `get_file_contents`, `push_files`, `create_branch`, `fork_repository`, `search_repositories`, and many more.
+Repository files are:
 
-### 4.9 `services/code_analysis.py`
+1. Loaded and filtered
+2. Split into smaller chunks
+3. Converted into embeddings
+4. Stored in ChromaDB
+5. Retrieved based on semantic similarity when a question is asked
 
-| Function | How it works |
-|---|---|
-| `explain_function(file, name)` | Python `ast` extracts the function source → RAG context → LLM |
-| `detect_bugs(file)` | Read file → `bug_finding` prompt → LLM returns JSON list |
-| `analyze_complexity(file)` | `radon.cc_visit` → cyclomatic complexity + rank A–F |
-
-### 4.10 `services/file_creator.py`
+The retrieved code is then provided to the LLM as context.
 
-```
-propose_new_file(description, context_query)
-  ├── RAG retrieve relevant context
-  ├── build_prompt(description, context, "file_creation")
-  ├── LLM generates complete file content
-  └── infer_file_path(description) → LLM suggests relative path
-
-apply_approved_file(proposal, confirmed, base_dir)
-  ├── Strip leading / or \ from LLM path
-  ├── os.path.join(base_dir, relative_path)
-  ├── os.makedirs(parent_dirs, exist_ok=True)
-  └── open(abs_path, "w").write(content)
-```
+Source metadata such as file path and line range is preserved during this process.
 
 ---
 
-## 5. Setup & Installation
+## Supported Languages
 
-### Prerequisites
+The repository ingestion system currently supports:
 
-| Requirement | Version |
+| Extension | Language |
 |---|---|
-| Python | 3.11+ |
-| pip | Latest |
-| Internet | For API calls |
+| `.py` | Python |
+| `.js` | JavaScript |
+| `.ts` | TypeScript |
+| `.java` | Java |
+| `.go` | Go |
+| `.md` | Markdown |
 
-### Step 1 — Clone / Download the project
+---
 
-```bash
-git clone <your-repo-url>
-cd "Codebase Assistant"
-```
+## Tech Stack
 
-### Step 2 — Create a virtual environment
+### AI / LLM
 
-```bash
-# Windows (PowerShell)
-python -m venv .venv
-.venv\Scripts\Activate.ps1
+- Groq
+- Llama 3.3 70B
+- Google Gemini
 
-# macOS / Linux
-python3 -m venv .venv
-source .venv/bin/activate
-```
+### RAG
 
-### Step 3 — Install dependencies
+- LangChain
+- Google Gemini Embeddings
+- ChromaDB
 
-```bash
-pip install -r requirements.txt
-```
+### Backend
 
-> [!TIP]
-> If you hit permission issues on Windows, use:
-> `pip install -r requirements.txt --user`
+- Python
+- FastAPI
+- Pydantic Settings
 
-### Step 4 — Create your `.env` file
+### Code Analysis
 
-Create a file named `.env` in the project root:
+- Python AST
+- Radon
+- LLM-based code analysis
 
-```env
-# Choose your LLM provider: "groq" (free) or "gemini"
-LLM_PROVIDER=groq
+### Integration
 
-# Groq — free at https://console.groq.com
-GROQ_API_KEY=gsk_your_key_here
+- GitHub MCP
+- GitHub Copilot MCP API
 
-# Gemini — get at https://aistudio.google.com
-GEMINI_API_KEY=your_gemini_key_here
+---
 
-# GitHub PAT for MCP tools — create at https://github.com/settings/tokens
-# Required scopes: repo, read:org
-GITHUB_MCP_TOKEN=github_pat_your_token_here
-```
+## LLM Providers
 
-> [!IMPORTANT]
-> `GEMINI_API_KEY` is **always required** regardless of LLM provider, because embeddings always use Gemini.
+| Provider | Model | Usage |
+|---|---|---|
+| Groq | `llama-3.3-70b-versatile` | LLM generation |
+| Gemini | Configurable | LLM generation |
+| Gemini Embeddings | `models/gemini-embedding-001` | Code embeddings |
 
-### Step 5 — Run the CLI
+The project supports switching between Groq and Gemini for LLM generation.
 
-```bash
-.venv\Scripts\python.exe cli.py     # Windows
-python cli.py                        # macOS / Linux
-```
+Gemini Embeddings are used for semantic retrieval.
 
 ---
 
-## 6. Configuration (.env)
-
-```env
-# ─── LLM Provider ────────────────────────────────────────
-LLM_PROVIDER=groq          # "groq" | "gemini"
-
-# ─── Groq (recommended — free tier) ─────────────────────
-GROQ_API_KEY=gsk_...
-GROQ_MODEL=llama-3.3-70b-versatile
-
-# ─── Gemini ──────────────────────────────────────────────
-GEMINI_API_KEY=...
-LLM_MODEL=gemini-1.5-flash        # only used if LLM_PROVIDER=gemini
-EMBEDDING_MODEL=models/gemini-embedding-001
-
-# ─── RAG / Vector DB ─────────────────────────────────────
-VECTOR_DB_PATH=./vector_db
-CHUNK_SIZE=1200
-CHUNK_OVERLAP=100
+# Installation
 
-# ─── File loader ─────────────────────────────────────────
-# comma-separated extensions
-ALLOWED_EXTENSIONS=[".py",".js",".ts",".go",".java",".md"]
-MAX_FILE_SIZE_KB=1042
+## 1. Clone the Repository
 
-# ─── GitHub MCP ──────────────────────────────────────────
-GITHUB_MCP_URL=https://api.githubcopilot.com/mcp/
-GITHUB_MCP_TOKEN=github_pat_...
+```bash
+git clone <your-repository-url>
+cd "Codebase Assistant"
 ```
 
----
+## 2. Create a Virtual Environment
 
-## 7. Running the CLI
+### Windows
 
+```bash
+python -m venv .venv
+.venv\Scripts\Activate.ps1
 ```
-╔══════════════════════════════════════════╗
-║       AI  Codebase  Assistant  CLI       ║
-╚══════════════════════════════════════════╝
-
-▶ Enter the path to the repository you want to analyse: D:\MyProject
-
-── Ingesting Repository ──────────────────────
-  Loading files from: D:\MyProject
-  ✓  Loaded 12 files
-  ✓  Split into 47 chunks
-  Embedding chunks (this may take a moment)...
-  ✓  Embedded 47 chunks
-  ✓  Vector store ready (ChromaDB)
-
-── What would you like to do? ────────────────
-   1  Ask a question about the codebase
-   2  Detect bugs in a file
-   3  Cyclomatic complexity analysis
-   4  Explain a function
-   5  Generate module documentation
-   6  Generate README for a repository
-   7  Propose & create a new file (AI)
-   8  List GitHub MCP tools
-   9  Re-ingest a repository
-    0  Exit
-
-▶ Choose an option [0–9]:
-```
-
----
 
-## 8. CLI Features — All 9 Options
-
-### Option 1 — Ask a Question (RAG Query)
+### Linux / macOS
 
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
 ```
-▶ Your question: How does the authentication work?
-▶ Number of source chunks to retrieve? [default: 5] 3
 
-── Answer ────────────────────────────────────
-The authentication uses JWT tokens ...
+## 3. Install Dependencies
 
-── Sources ───────────────────────────────────
-  • src/auth/middleware.py  lines 12–45
-  • src/auth/tokens.py  lines 1–30
+```bash
+pip install -r requirements.txt
 ```
 
-**Pipeline:** Embed question → ChromaDB similarity search → Build context → LLM → Answer + cited sources
-
 ---
+## 🏗️ Architecture
 
-### Option 2 — Detect Bugs
+![AI Codebase Assistant Architecture](./architecture.png)
 
-```
-▶ File path to analyse: src/payment.py
+The system combines a RAG pipeline, LLM providers, code analysis services,
+FastAPI, and GitHub MCP integration to provide repository-level AI assistance.
 
-── Found 2 issue(s) ──────────────────────────
-  [HIGH] Line 34: SQL query uses string concatenation
-    → Use parameterized queries to prevent SQL injection
 
-  [MEDIUM] Line 67: Exception swallowed silently
-    → Log or re-raise the exception
-```
+# Configuration
 
-**Pipeline:** Read file → `bug_finding` prompt → LLM returns JSON → parsed and displayed
+Create a `.env` file in the project root.
 
----
-
-### Option 3 — Cyclomatic Complexity
-
-```
-▶ File path to analyse: src/processor.py
-
-── 4 function(s) ─────────────────────────────
-  [A]  process_order              complexity=2  ██
-  [B]  validate_cart              complexity=5  █████
-  [C]  apply_discounts            complexity=8  ████████
-  [F]  handle_edge_cases          complexity=18 ██████████████████
-```
-
-**Rank scale:** A (1–5, simple) → F (26+, untestable)
+```env
+LLM_PROVIDER=groq
 
----
+GROQ_API_KEY=your_groq_api_key
+GROQ_MODEL=llama-3.3-70b-versatile
 
-### Option 4 — Explain a Function
+GEMINI_API_KEY=your_gemini_api_key
+EMBEDDING_MODEL=models/gemini-embedding-001
 
-```
-▶ File path: src/utils.py
-▶ Function name: parse_date_range
+VECTOR_DB_PATH=./vector_db
 
-── Explanation ───────────────────────────────
-parse_date_range takes a string like "2024-01-01:2024-12-31"
-and returns a tuple of (start_date, end_date) as datetime objects ...
+GITHUB_MCP_TOKEN=your_github_token
 ```
 
-**Pipeline:** Python `ast` module extracts exact function source → RAG retrieves usages → LLM explains
+### Required API Keys
 
----
+**Groq**
 
-### Option 5 — Generate Module Documentation
+Used for LLM generation when:
 
+```env
+LLM_PROVIDER=groq
 ```
-▶ File path: src/database.py
 
-── Documentation ─────────────────────────────
-## database.py
+**Gemini**
 
-### Overview
-This module provides the database connection layer ...
+Required for embeddings because the project uses Gemini Embeddings for repository indexing.
 
-### Functions
-- `connect(url)` — Establishes a connection ...
-- `execute(query, params)` — Runs a parameterized query ...
-```
-
----
+**GitHub Token**
 
-### Option 6 — Generate README
+Required for GitHub MCP functionality.
 
-```
-▶ Repository root path: D:\MyProject
+---
 
-── README Preview ────────────────────────────
-# MyProject
+# Running the CLI
 
-## Overview
-A FastAPI application that ...
+Start the interactive CLI:
 
-▶ Save to README.md in that directory? [y/N] y
-  ✓  Saved to D:\MyProject\README.md
+```bash
+python cli.py
 ```
 
----
-
-### Option 7 — Propose & Create a New File
+The application will ask for the repository you want to analyze.
 
+```text
+▶ Enter the path to the repository you want to analyse:
 ```
-▶ Describe the file you want to create: Rectangle area calculator in JavaScript
-▶ Optional context query (or press Enter to skip):
 
-── Proposed File ─────────────────────────────
-  Path:  /src/geometry/rectangle.js
+After the repository is indexed, you can choose from:
 
-  class Rectangle { ...full generated code... }
-
-▶ Write this file to disk? [y/N] y
-▶ Save under which directory? [default: D:\MyProject]
-
-  ✓  File written: D:\MyProject\src\geometry\rectangle.js
+```text
+1  Ask a question about the codebase
+2  Detect bugs in a file
+3  Cyclomatic complexity analysis
+4  Explain a function
+5  Generate module documentation
+6  Generate README
+7  Propose & create a new file
+8  List GitHub MCP tools
+9  Re-ingest repository
+0  Exit
 ```
 
-**Pipeline:** RAG context (optional) → `file_creation` prompt → LLM generates code → user confirms → write to `base_dir/relative_path`
-
 ---
 
-### Option 8 — List GitHub MCP Tools
+# REST API
 
-```
-── List GitHub MCP Tools ─────────────────────
-  44 tools available:
-    • create_branch                   Create a new branch in a GitHub repository
-    • create_pull_request             Create a new pull request ...
-    • search_code                     Fast and precise code search ...
-    • list_issues                     List issues in a GitHub repository ...
-    ...
-```
-
-**Connection:** Uses `streamable_http_client` → `ClientSession` → GitHub Copilot MCP endpoint
+The project also provides a FastAPI REST API.
 
----
+Start the server:
 
-### Option 9 — Re-ingest a Repository
-
-```
-▶ New repository path to ingest: D:\AnotherProject
-── Ingesting Repository ──────────────────────
-  ✓  Loaded 8 files ...
+```bash
+python -m uvicorn app:app --reload --port 8000
 ```
 
-Wipes the ChromaDB collection and ingests the new repo fresh. All subsequent queries answer from the new repo only.
-
----
-
-## 9. REST API
-
-Start the FastAPI server:
+Open the interactive API documentation:
 
-```bash
-.venv\Scripts\python.exe -m uvicorn app:app --reload --port 8000
+```text
+http://localhost:8000/docs
 ```
 
-Open docs at: `http://localhost:8000/docs`
-
-### Endpoints
+## API Endpoints
 
-| Method | Path | Description |
+| Method | Endpoint | Description |
 |---|---|---|
 | `GET` | `/health` | Health check |
-| `POST` | `/api/query` | RAG question answering |
-| `POST` | `/api/analyze/bugs?file_path=...` | Bug detection |
-| `POST` | `/api/analyze/complexity?file_path=...` | Cyclomatic complexity |
+| `POST` | `/api/query` | Ask questions about the codebase |
+| `POST` | `/api/analyze/bugs` | Detect potential bugs |
+| `POST` | `/api/analyze/complexity` | Analyze cyclomatic complexity |
 | `POST` | `/api/analyze/explain` | Explain a function |
-| `POST` | `/api/docs/module?file_path=...` | Module documentation |
-| `POST` | `/api/docs/readme?root_path=...` | README generation |
-| `POST` | `/api/files/propose` | Propose a new file |
-| `POST` | `/api/files/approve` | Write approved file to disk |
+| `POST` | `/api/docs/module` | Generate module documentation |
+| `POST` | `/api/docs/readme` | Generate README |
+| `POST` | `/api/files/propose` | Generate a file proposal |
+| `POST` | `/api/files/approve` | Write an approved file |
 
-### Example — Query
+---
+
+## Example API Request
 
 ```bash
 curl -X POST http://localhost:8000/api/query \
@@ -640,107 +339,124 @@ curl -X POST http://localhost:8000/api/query \
   -d '{"query": "How does authentication work?", "k": 5}'
 ```
 
+Example response:
+
 ```json
 {
   "answer": "Authentication is handled by ...",
   "sources": [
-    {"file_path": "src/auth.py", "start_line": 10, "end_line": 45}
+    {
+      "file_path": "src/auth.py",
+      "start_line": 10,
+      "end_line": 45
+    }
   ]
 }
 ```
 
 ---
 
-## 10. Key Design Decisions & Bug Fixes
-
-### Bug Fix 1 — Collection Isolation (retriever.py)
-
-**Problem:** ChromaDB used `upsert` on a shared `"codebase"` collection — stale chunks from previously ingested repos leaked into new queries.
-
-**Fix:** On every ingest, `delete_collection` + `create_collection` ensures a clean slate:
-
-```python
-# Before (bug)
-collection = client.get_or_create_collection("codebase")
-collection.upsert(...)
+# 📁 Project Structure
 
-# After (fix)
-client.delete_collection("codebase")   # wipe old repo
-collection = client.create_collection("codebase")
-collection.add(...)
+```text
+Codebase Assistant/
+│
+├── cli.py
+├── app.py
+├── config.py
+├── llm.py
+├── mcp_client.py
+├── requirements.txt
+│
+├── rag/
+│   ├── repository_loader.py
+│   ├── splitter.py
+│   ├── embedding.py
+│   ├── retriever.py
+│   └── rag_chain.py
+│
+├── services/
+│   ├── code_analysis.py
+│   ├── documentation.py
+│   └── file_creator.py
+│
+├── api/
+│   └── routes.py
+│
+└── vector_db/
+    └── chroma.sqlite3
 ```
 
 ---
 
-### Bug Fix 2 — GitHub MCP Cancel Scope (mcp_client.py)
-
-**Problem:** Manually calling `__aenter__`/`__aexit__` on `anyio`-backed context managers across tasks causes `RuntimeError: Attempted to exit cancel scope in a different task`.
+# Configuration Options
 
-**Fix:** Use `AsyncExitStack` to nest all context managers inside a single `async with`:
-
-```python
-async with get_github_mcp_client() as client:
-    tools = await client.list_tools()
-```
+| Setting | Default | Description |
+|---|---|---|
+| `LLM_PROVIDER` | `groq` | LLM provider |
+| `GROQ_MODEL` | `llama-3.3-70b-versatile` | Groq model |
+| `EMBEDDING_MODEL` | `models/gemini-embedding-001` | Embedding model |
+| `VECTOR_DB_PATH` | `./vector_db` | ChromaDB storage |
+| `CHUNK_SIZE` | `1200` | Chunk size |
+| `CHUNK_OVERLAP` | `100` | Chunk overlap |
+| `MAX_FILE_SIZE_KB` | `1042` | Maximum file size |
+| `ALLOWED_EXTENSIONS` | `.py,.js,.ts,.go,.java,.md` | Supported files |
 
 ---
 
-### Bug Fix 3 — Wrong Unpack Count (mcp_client.py)
-
-**Problem:** `streamable_http_client` yields 2 values, not 3. Unpacking 3 caused `ValueError: not enough values to unpack`.
+# Limitations
 
-```python
-# Before (bug)
-read, write, _ = await ctx.__aenter__()
-
-# After (fix)
-read, write = await stack.enter_async_context(streamable_http_client(...))
-```
+- Repository ingestion currently runs locally.
+- External API keys are required for LLM and embedding services.
+- Gemini embedding quotas may limit large repositories.
+- Only the currently supported file types are indexed.
+- LLM-generated code and bug reports should be reviewed before use.
+- The vector database currently focuses on the actively ingested repository.
 
 ---
 
-### Bug Fix 4 — File Save Path (file_creator.py)
+# Future Improvements
 
-**Problem:** Generated files saved to the current working directory regardless of user input.
+Planned or possible improvements include:
 
-**Fix:** 
-- Strip leading `/\` from LLM path to make it always relative
-- Accept `base_dir` defaulting to `_current_repo` (the ingested repo path)
-- Create all parent directories automatically
+- More programming language support
+- Incremental repository indexing
+- GitHub repository ingestion
+- AST-based code chunking
+- Hybrid keyword + vector search
+- Retrieval reranking
+- Dependency graph analysis
+- Automated test generation
+- Automated pull request review
+- Multi-repository search
+- Web-based developer interface
 
 ---
 
-## 11. Extending the Project
+# Project Goal
 
-### Add a new LLM provider
+The goal of this project is to build an AI developer assistant that can understand and interact with an entire codebase rather than only individual code snippets.
 
-1. Add a new class in `llm.py` extending `BaseLLM`
-2. Add the provider name to `get_llm_client()` factory
-3. Add matching settings in `config.py`
+It combines:
 
-### Add support for new file types
+**RAG + LLMs + Vector Search + Code Analysis + FastAPI + MCP**
 
-1. Add extension → language in `LANGUAGE_BY_EXT` in `repository_loader.py`
-2. Add extension to `allowed_extensions` in `config.py`
-3. If LangChain has a `Language` enum for it, add to `LANGUAGE_MAP` in `splitter.py`
+into a single developer-focused tool.
 
-### Use a GitHub MCP tool in a feature
+---
 
-```python
-async with get_github_mcp_client() as client:
-    result = await client.call_tool("create_branch", {
-        "owner": "myuser",
-        "repo": "myrepo",
-        "branch": "feature/new-branch",
-        "from_branch": "main"
-    })
-```
 
-### Add a new CLI option
+# Author
 
-1. Write a `feature_xxx()` function in `cli.py`
-2. Add `("Label", feature_xxx)` to the `MENU` list
-3. Add a matching FastAPI endpoint in `api/routes.py`
+**Armaan Alam**
 
----
+AI Engineer & Software Developer
+
+Interested in:
 
+- Generative AI
+- RAG Systems
+- Backend Engineering
+- LLM Applications
+- AI Developer Tools
+- Machine Learning