AI Codebase Assistant

A local-first AI developer assistant for understanding, documenting, analyzing, and improving software repositories using free AI models and modern retrieval pipelines.

Built as a production-style AI engineering portfolio project focused on developer tooling, repository intelligence, semantic retrieval, and AI-assisted maintenance workflows.

---

Features

Repository Intelligence

• Safe local repository scanning
• Repository structure visualization
• Architecture layer detection
• Dependency/import analysis
• Language and file-type detection
• Repository metrics and statistics

AI-Powered Developer Tools

• AI repository summaries
• Repository Q&A using semantic retrieval
• AI file explanations
• README generation
• Refactor/improvement suggestions
• Safe patch preview generation
• Suggested fix detection

Code Quality & Maintenance

• TODO / FIXME extraction
• Potential issue detection
• Suggested improvements
• Architecture insights
• Maintainability analysis

AI & Retrieval Infrastructure

• Multi-provider AI support
  • Ollama
  • Groq
  • Gemini
• Semantic vector retrieval
• Persistent FAISS vector indexes
• Embedding-based repository search
• Local-first caching system

---

Screenshots

Landing Page

---

Repository Overview Dashboard

---

AI Repository Understanding

---

Architecture Intelligence

---

AI File Explanation

---

AI Refactor Suggestions

---

Patch Preview Mode

---

README Generator

---

Maintenance Dashboard

---

Architecture Overview

Frontend (Streamlit)
        │
        ▼
FastAPI Backend API Layer
        │
        ├── Repository Scanner
        ├── Analysis Engine
        ├── AI Provider Layer
        ├── Retrieval Pipeline
        ├── Vector Search (FAISS)
        ├── Caching System
        └── Refactor / Patch Engine

---

Tech Stack

Backend

• Python
• FastAPI
• SQLite

Frontend

• Streamlit
• Plotly

AI / LLM

• Ollama
• Groq API
• Gemini API

Retrieval & Embeddings

• sentence-transformers
• FAISS

Infrastructure

• Local JSON caching
• Modular API routing
• Repository-safe scanning rules

---

Repository Structure

backend/
├── analysis/
├── api/
├── core/
├── ingestion/
├── llm/
├── retrieval/
├── scanner/

frontend/
├── streamlit_app.py

data/
├── cache/
├── indexes/

---

Quick Start

1. Clone Repository

git clone <your-repository-url>
cd ai-codebase-assistant

---

2. Create Virtual Environment

python -m venv .venv

Activate:

Windows

.venv\Scripts\activate

Linux / macOS

source .venv/bin/activate

---

3. Install Dependencies

cd backend
pip install -r requirements.txt

---

4. Run Backend

uvicorn app.main:app

---

5. Run Frontend

Open another terminal:

cd frontend
streamlit run streamlit_app.py

---

Optional AI Providers

Ollama (Local)

Install Ollama:

https://ollama.com/

Example local model:

ollama pull gemma2:2b

---

Groq

Set environment variable:

GROQ_API_KEY=your_key_here

---

Gemini

Set environment variable:

GEMINI_API_KEY=your_key_here

---

Current Capabilities

• Local repository scanning
• Persistent vector search indexes
• AI-assisted repository understanding
• AI-powered developer Q&A
• Dependency mapping
• README generation
• Refactor suggestion generation
• Patch preview generation
• Multi-provider AI routing
• Local caching system

---

Roadmap

Planned Improvements

• Tree-sitter AST parsing
• Monaco-style code viewer
• True patch application engine
• Dockerized deployment
• GitHub repository ingestion
• Multi-language parsing
• Async/background processing
• Session/project history
• Advanced architecture graphing

---

Design Goals

This project was designed to:

• simulate real AI developer tooling platforms
• demonstrate AI engineering architecture skills
• showcase retrieval-augmented workflows
• demonstrate scalable backend organization
• remain fully usable with free/local AI models

---

License

MIT License