refactor: rinomina step-8 → ingestion

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ingestion/README.md

@@ -0,0 +1,114 @@
+# Step 8 — Vettorizzazione
+
+Legge i chunk prodotti da step-6, genera gli embedding tramite Ollama e li
+salva in ChromaDB (vector store persistente su disco).
+
+---
+
+## Prerequisiti
+
+- Step-6 completato (esiste `step-6/<stem>/chunks.json`)
+- Ollama attivo con il modello di embedding scaricato
+- `chromadb` installato (`pip install -r requirements.txt`)
+
+---
+
+## Configurazione modello
+
+Il modello di embedding viene letto da **`config.py`**:
+
+```python
+# config.py
+EMBED_MODEL = "nomic-embed-text"   # ← cambia qui
+```
+
+> Il modello scelto qui deve corrispondere a quello usato in rag.py.
+> Se lo cambi dopo aver già vettorizzato, devi rieseguire ingestion con `--force`.
+
+---
+
+## Uso
+
+```bash
+# Vettorizza un singolo documento
+python ingestion/ingest.py --stem <nome>
+
+# Vettorizza tutti i documenti trovati in step-6/
+python ingestion/ingest.py
+
+# Sovrascrive una collection già esistente
+python ingestion/ingest.py --stem <nome> --force
+
+# Override modello (senza modificare config.py)
+python ingestion/ingest.py --stem <nome> --model bge-m3
+```
+
+---
+
+## Output
+
+I vettori vengono salvati in `chroma_db/<stem>/` come collection ChromaDB con
+distanza coseno. La directory è ignorata da git (generata automaticamente).
+
+---
+
+## Modelli supportati
+
+Stessi modelli raccomandati nel [README di ollama](../ollama/README.md).
+Il modello deve essere scaricato in Ollama prima di eseguire questo script
+(`ollama pull <modello>`).
+
+---
+
+## Regole d'oro per parametri ottimali
+
+### Modello di embedding
+
+**Usa un modello multilingue per testi italiani.**
+I modelli English-first (`nomic-embed-text`, `mxbai-embed-large`, `all-minilm`)
+producono vettori di qualità inferiore su italiano, con retrieval meno preciso.
+Prima scelta: `qwen3-embedding:0.6b`.
+
+**Più dimensioni = retrieval più preciso, ma più spazio su disco.**
+
+| Dimensioni | Modelli | Quando usarlo |
+|---|---|---|
+| 1024 | `qwen3-embedding:0.6b`, `bge-m3` | documenti tecnici, testi lunghi |
+| 768 | `nomic-embed-text-v2-moe` | buon compromesso |
+| 384 | `all-minilm` | solo per test rapidi |
+
+**Usa la stessa famiglia LLM + embedding quando possibile.**
+`qwen3-embedding` + `qwen3.5` condividono tokenizer e spazio semantico —
+il retrieval è più coerente rispetto a modelli di famiglie diverse.
+
+### Coerenza tra ingest e retrieval
+
+**`EMBED_MODEL` deve essere identico in `ingest.py` e `rag.py`.**
+ChromaDB memorizza i vettori generati con un certo modello. Se `rag.py` usa un
+modello diverso per la query di ricerca, gli spazi vettoriali non corrispondono
+e il retrieval restituisce risultati casuali — senza alcun errore visibile.
+
+**Dopo aver cambiato `EMBED_MODEL`, riesegui sempre con `--force`.**
+Senza `--force` lo script salta la collection già esistente — i vecchi vettori
+(generati col modello precedente) restano e continuano a essere usati da `rag.py`.
+
+```bash
+# Cambio modello → ricrea sempre la collection
+python ingestion/ingest.py --stem <nome> --force
+```
+
+### Quando usare `--force`
+
+| Situazione | `--force` necessario? |
+|---|---|
+| Prima esecuzione | No |
+| Hai cambiato `EMBED_MODEL` | **Sì** |
+| Hai migliorato i chunk in step-6 | **Sì** |
+| Hai aggiunto nuovi documenti (stem diverso) | No |
+| Vuoi solo verificare che funzioni | No |
+
+### Distanza vettoriale
+
+Lo script usa **distanza coseno** (hardcoded), che è la scelta corretta per
+embedding testuali — misura l'angolo tra vettori indipendentemente dalla loro
+lunghezza. Non cambiare questo parametro.