My Chat Bot

🧠 MyChatBot — Local AI Code Assistant

Un assistente AI locale che gira interamente sulla tua macchina, anche offline. Usa deepseek-r1:32b tramite Ollama per rispondere a domande sui tuoi progetti di codice, grazie a un'architettura RAG (Retrieval-Augmented Generation) e un server MCP (Model Context Protocol).

"Nel progetto IceSkating come funziona la fisica del movimento del player?"
→ L'AI cerca nel tuo codice, trova i file rilevanti, e risponde con dettagli precisi.

📐 Architettura

┌─────────────────────────────────────────────────────────┐
│                    Browser (localhost:8000)              │
│              Dark theme chat UI + streaming              │
└──────────────────────┬──────────────────────────────────┘
                       │ WebSocket
┌──────────────────────▼──────────────────────────────────┐
│                  FastAPI Server (UI)                      │
│                 src/ui/server.py                          │
└────────┬─────────────────────────────┬──────────────────┘
         │                             │
┌────────▼────────┐          ┌─────────▼─────────┐
│  RAG Retriever  │          │   LLM Client      │
│  ChromaDB +     │          │   Ollama async     │
│  rapidfuzz      │──context─▶   deepseek-r1:32b │
└────────┬────────┘          └─────────┬─────────┘
         │                             │
┌────────▼────────┐          ┌─────────▼─────────┐
│  Sentence-      │          │   Ollama Server    │
│  Transformers   │          │   localhost:11434  │
│  (embeddings)   │          └───────────────────┘
└─────────────────┘

┌─────────────────────────────────────────────────────────┐
│              MCP Server (porta 8001)                     │
│         Strumenti indipendenti per client esterni        │
└─────────────────────────────────────────────────────────┘

🧩 Cos'è cosa? (Guida ai concetti)

🔄 RAG — Retrieval-Augmented Generation

Il problema: un LLM sa solo quello che ha appreso durante il training. Non conosce i tuoi file.

La soluzione RAG aggiunge un passaggio prima di chiedere al modello:

1. CHUNKING     Il tuo codice viene diviso in pezzi da ~1500 caratteri
                Ogni funzione/classe diventa un "chunk"

2. EMBEDDING    Ogni chunk viene convertito in un vettore di 384 numeri
                Frasi simili → vettori vicini nello spazio
                Modello: all-MiniLM-L6-v2 (22MB, gira su CPU)

3. INDEXING     I vettori vengono salvati in ChromaDB (database vettoriale)
                Persistente su disco in data/chroma_db/

4. RETRIEVAL    Quando fai una domanda, la tua domanda viene convertita
                nello stesso spazio vettoriale e si cercano i chunk più simili
                (cosine similarity = quanto due vettori puntano nella stessa direzione)

5. AUGMENTATION I chunk trovati vengono aggiunti al prompt come "contesto"
                "Ecco del codice rilevante: [chunk1] [chunk2] ..."

6. GENERATION   Il modello legge il contesto e genera una risposta informata

Perché funziona anche con errori di battitura?

• La ricerca semantica (embeddings) cattura il significato, non le parole esatte
• rapidfuzz aggiunge fuzzy matching sui nomi di progetto/file per casi limite
• Esempio: "fisika del movimiento" → vettorialmente vicino a "physics of movement"

🔌 MCP — Model Context Protocol

MCP è un protocollo standard (creato da Anthropic) per dare strumenti all'AI:

Senza MCP:  L'AI può solo "parlare" — genera testo e basta
Con MCP:    L'AI può "agire" — leggere file, cercare codice, eseguire query

Concetti chiave:

• Tool — una funzione che l'AI può chiamare (es. read_file(path))
• Resource — un dato che l'AI può consultare (es. project://IceSkating/structure)
• Transport — come client e server comunicano (stdio per CLI, streamable-http per web)

Il nostro MCP server gira sulla porta 8001, separato dalla UI. Questo significa che in futuro puoi collegarlo a Claude Desktop, VS Code, o qualsiasi client MCP senza modificare nulla.

🦙 Ollama

Ollama è il runtime locale per modelli LLM:

• Scarica e gestisce i pesi del modello (~20GB per deepseek-r1:32b)
• Espone un'API HTTP su localhost:11434
• Gestisce automaticamente CPU/GPU, quantizzazione, context window
• Nel nostro progetto, il Python ollama package chiama questa API

⚡ Quickstart

Prerequisiti (da installare manualmente)

Hardware consigliato: 32GB RAM, SSD. Il modello 32B usa ~20GB di RAM quando attivo.

Setup (una volta sola)

# 1. Clona o entra nella cartella del progetto
cd C:\Users\Luigi\Developing\Personal\MyChatBot

# 2. Crea un virtual environment
python -m venv venv

# 3. Attivalo
# Windows:
venv\Scripts\activate
# Linux/Mac:
# source venv/bin/activate

# 4. Installa PyTorch CPU-only (risparmia ~1.5GB)
pip install torch --index-url https://download.pytorch.org/whl/cpu

# 5. Installa le dipendenze
pip install -r requirements.txt

# 6. (Opzionale) Copia e personalizza la configurazione
copy .env.example .env

Avvio

# Un solo comando avvia TUTTO (Ollama, indicizzazione, MCP, UI)
python launch.py

Il browser si aprirà automaticamente su http://localhost:8000.

Chiusura

• Ctrl+C nel terminale → tutti i servizi si fermano ordinatamente
• Oppure chiudi il terminale → stessa cosa

📁 Struttura del Progetto

MyChatBot/
├── launch.py                  # 🚀 Entry point — avvia tutto
├── requirements.txt           # 📦 Dipendenze Python
├── .env.example               # ⚙️ Template configurazione
├── .gitignore
├── copilot_instructions.md    # 🤖 Regole per GitHub Copilot
├── README.md                  # 📖 Questo file
│
├── src/
│   ├── config.py              # ⚙️ Configurazione centralizzata
│   │
│   ├── rag/                   # 🔍 Retrieval-Augmented Generation
│   │   ├── chunker.py         #    Divide i file in pezzi
│   │   ├── indexer.py         #    Indicizza i progetti in ChromaDB
│   │   └── retriever.py       #    Cerca i chunk più rilevanti
│   │
│   ├── llm/                   # 🧠 Integrazione LLM
│   │   ├── client.py          #    Wrapper async per Ollama
│   │   └── prompts.py         #    Template dei prompt di sistema
│   │
│   ├── mcp/                   # 🔌 Model Context Protocol
│   │   ├── server.py          #    Server MCP (porta 8001)
│   │   └── tools.py           #    Definizione degli strumenti
│   │
│   └── ui/                    # 🎨 Interfaccia utente
│       ├── server.py          #    FastAPI + WebSocket
│       └── static/            #    Frontend (HTML/CSS/JS)
│           ├── index.html
│           ├── style.css
│           └── script.js
│
├── docker/                    # 🐳 Containerizzazione (opzionale)
│   ├── Dockerfile
│   └── docker-compose.yml
│
└── data/                      # 💾 Dati persistenti (gitignored)
    └── chroma_db/             #    Database vettoriale

🐳 Docker (opzionale)

Docker containerizza solo l'app Python. Ollama rimane sull'host per massime performance (accesso diretto a CPU/RAM, nessun overhead).

# Avvia
docker-compose -f docker/docker-compose.yml up --build

# Ferma
docker-compose -f docker/docker-compose.yml down

Nota: il container comunica con Ollama sull'host tramite host.docker.internal:11434. Assicurati che Ollama sia in esecuzione prima di avviare il container.

🔧 Configurazione

Tutte le impostazioni sono in .env (copia da .env.example). Le più importanti:

🗺️ Roadmap

• [x] Chat base con streaming
• [x] RAG su progetti locali
• [x] MCP server con strumenti base
• [x] Dark theme UI moderna
• [ ] Cronologia conversazioni persistente
• [ ] Multi-modello (switch tra modelli Ollama)
• [ ] Upload file nella chat
• [ ] MCP tools aggiuntivi (esegui test, analisi dipendenze)
• [ ] Indicizzazione incrementale (solo file modificati)
• [ ] Deploy cloud con Docker

📄 Licenza

Progetto personale di apprendimento. Uso interno.