# CLAUDE.md — Contesto Progetto Tesi

## Panoramica

Questo è il progetto di tesi di laurea in **Ingegneria Informatica**, corso di **Natural Language Processing** (Prof.ssa Cristina Giannone).

L'obiettivo è progettare e implementare un **chatbot multi-agente per e-commerce** focalizzato sul dominio **abbigliamento (fashion)**. Il sistema supporta l'utente nella ricerca e nella scelta di prodotti tramite tre approcci: ricerca per attributi, raccomandazione personalizzata e visual recommending.

---

## Architettura

Il sistema è composto da **3 agenti** orchestrati da **LangGraph**:

### 1. Router Agent
- **Ruolo**: Punto di ingresso. Riceve il messaggio dell'utente, classifica l'intent e smista al sotto-agente appropriato.
- **Intent classification**: Basato sul dataset [ecommerce-intent-routing](https://huggingface.co/datasets/vansh-khaneja/ecommerce-intent-routing) (~2.750 esempi, 5 classi: sales, product, support, account, bugs).
- **Session memory**: Mantiene il contesto della conversazione corrente. Se l'utente dice "Cerco una giacca blu" e poi "La vorrei sotto i 100€", il Router capisce che si riferisce ancora alla giacca.
- **Gestione fuori scope**: Per richieste non pertinenti (spedizioni, resi, account, bug), risponde direttamente con un messaggio del tipo "Posso aiutarti solo a cercare e consigliare prodotti".
- **Routing**:
  - Intent `product` / `sales` → **Search Agent** o **Recommender Agent**
  - Intent `support` / `account` / `bugs` → risposta diretta fuori scope
  - Saluti / chit-chat → risposta diretta

### 2. Search Agent
- **Ruolo**: Ricerca prodotti nel catalogo basandosi sui filtri estratti dalla query dell'utente (colore, prezzo, categoria, taglia, brand).
- **Dataset**: Amazon Product Data — **Fashion Metadata** (metadati dei prodotti: titolo, descrizione, categoria, prezzo, immagini).
- **Approccio**: Estrazione attributi dalla query (NER o parsing LLM-based), poi ricerca/filtraggio nel catalogo.

### 3. Recommender Agent
- **Ruolo**: Suggerisce prodotti tramite tre approcci di raccomandazione.
- **Dataset**: Amazon Product Data — **Fashion Reviews** (recensioni utenti, rating, storico interazioni).
- **Approcci implementati/da implementare**:
  - **Content-based filtering**: Raccomandazioni basate sulla similarità degli attributi dei prodotti.
  - **Collaborative filtering**: Basato sulla similarità tra utenti con preferenze simili (tramite LightFM).
  - **Visual similarity**: Basato su embeddings di immagini prodotto generati con [Trendyol DinoV2](https://huggingface.co/Trendyol/trendyol-dino-v2-ecommerce-256d) (embedding a 256 dimensioni, cosine similarity per trovare prodotti visivamente simili).
- **Libreria**: LightFM per hybrid filtering (content-based + collaborative).

---

## Stack Tecnologico

| Componente | Tecnologia |
|---|---|
| Orchestrazione agenti | LangGraph (estensione di LangChain) |
| LLM conversazionale | **OpenAI API** (da implementare — sostituisce Gemini Flash che è stato abbandonato per limiti di token) |
| Recommender system | LightFM |
| Visual recommending | Trendyol DinoV2 (HuggingFace) |
| Linguaggio | Python (.py) |

---

## Dataset

| Dataset | Uso | Fonte |
|---|---|---|
| ecommerce-intent-routing | Training/eval del classificatore intent per il Router | [HuggingFace](https://huggingface.co/datasets/vansh-khaneja/ecommerce-intent-routing) |
| Amazon Product Data — Fashion (metadata) | Catalogo prodotti per il Search Agent | [Amazon](http://jmcauley.ucsd.edu/data/amazon/) |
| Amazon Product Data — Fashion (reviews) | Interazioni utente-prodotto per il Recommender Agent | [Amazon](http://jmcauley.ucsd.edu/data/amazon/) |
| Immagini prodotto (dal catalogo Amazon) | Embeddings con Trendyol DinoV2 per visual similarity | Estratte dal dataset Amazon |

---

## Stato Attuale del Progetto

### ✅ Completato
- **Struttura LangGraph**: Il grafo è funzionante con i nodi e il routing tra agenti.
- **Router Agent**: Intent classification implementata.
- **Search Agent**: Ricerca nel catalogo implementata.
- **Recommender Agent (LightFM)**: Recommending con content-based e collaborative filtering implementato.

### 🔄 Da fare / In corso
- **Migrazione LLM**: Sostituire Gemini Flash con **OpenAI API** (GPT). Gemini è presente nel codice ma non funziona per limiti di token della versione gratuita. Questa è la **priorità immediata**.
- **Visual Recommending**: Integrare Trendyol DinoV2 nel Recommender Agent per la similarity search basata su immagini.
- **Riorganizzazione struttura progetto**: Il progetto non ha ancora una struttura a cartelle definita. Andrebbe organizzato in modo pulito.

---

## Note Importanti per Claude Code

### Migrazione Gemini → OpenAI
- Nel codice troverai riferimenti a Gemini / Google AI. Vanno **tutti sostituiti con chiamate OpenAI**.
- Usare la libreria `openai` di Python.
- Il modello specifico da usare verrà scelto in base ai costi (probabilmente GPT-4o-mini per il buon rapporto qualità/prezzo).
- La API key va gestita tramite variabile d'ambiente `OPENAI_API_KEY`.

### Struttura consigliata
Se il progetto va riorganizzato, questa è la struttura target:

```
progetto-tesi/
├── CLAUDE.md                  # Questo file
├── requirements.txt           # Dipendenze Python
├── .env                       # API keys (non committare)
├── main.py                    # Entry point / interfaccia chatbot
├── graph.py                   # Definizione grafo LangGraph
├── agents/
│   ├── router.py              # Router Agent (intent + session memory)
│   ├── search.py              # Search Agent (catalogo)
│   └── recommender.py         # Recommender Agent (LightFM + visual)
├── models/
│   ├── intent_classifier.py   # Classificatore intent
│   └── visual_embeddings.py   # Trendyol DinoV2 wrapper
├── data/
│   ├── fashion_metadata.json  # Metadati prodotti Amazon Fashion
│   ├── fashion_reviews.json   # Reviews Amazon Fashion
│   └── embeddings/            # Embeddings pre-calcolati DinoV2
└── utils/
    ├── llm.py                 # Wrapper OpenAI API (centralizzato)
    └── config.py              # Configurazione e costanti
```

### Trendyol DinoV2 — Riferimento Implementazione
```python
# Esempio di utilizzo del modello per generare embeddings
from transformers import AutoModel, AutoImageProcessor
import torch
from PIL import Image

processor = AutoImageProcessor.from_pretrained(
    "Trendyol/trendyol-dino-v2-ecommerce-256d", trust_remote_code=True
)
model = AutoModel.from_pretrained(
    "Trendyol/trendyol-dino-v2-ecommerce-256d", trust_remote_code=True
)

image = Image.open("product_image.jpg").convert("RGB")
inputs = processor(images=image, return_tensors="pt")

with torch.no_grad():
    outputs = model(**inputs)
    embedding = outputs.last_hidden_state  # Shape: [1, 256]
```

### Scope del chatbot
Il chatbot si occupa **esclusivamente** di ricerca e raccomandazione prodotti fashion. NON gestisce: spedizioni, resi, account, bug tecnici. Per queste richieste il Router risponde cortesemente che non può aiutare.

---

## Metriche di Valutazione (per riferimento)

| Componente | Metrica | Target |
|---|---|---|
| Intent Classification | Accuracy, F1-score | > 90% |
| Product Search | Precision@5 | > 0.7 |
| Recommender (hybrid) | nDCG@10, MAP | nDCG > 0.5 |
| Visual Similarity | Cosine Similarity | > 0.85 |