From b49ef8edf0b570f1ff14c99fd3bef216d5d53293 Mon Sep 17 00:00:00 2001
From: Davide Grilli <davide.grilli@outlook.com>
Date: Mon, 11 May 2026 16:05:23 +0200
Subject: [PATCH] docs: aggiorna README con flusso ingestion completo

- README.md: aggiunge step 7 (ingestion) con verifica ambiente,
  comandi base e --force; aggiorna pipeline header e riferimenti
- ingestion/README.md: rinomina da "Step 8" a "Ingestion",
  aggiorna riferimenti da step-6 a chunks/, aggiunge sezione
  "Verifica ambiente", corregge comandi con .venv/bin/python

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md           | 26 +++++++++++++++++++++++++-
 ingestion/README.md | 28 +++++++++++++++++++---------
 2 files changed, 44 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index cea5b99..dfbad1d 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 Converte PDF digitali in chunk semantici pronti per la vettorizzazione RAG,
 senza LLM né OCR.
 
-**Pipeline:** PDF → Markdown strutturato → chunk semantici  
+**Pipeline:** PDF → Markdown strutturato → chunk semantici → embedding ChromaDB  
 **Stack:** Python · PyMuPDF · pdfplumber  
 **Non supportati:** PDF scansionati (solo immagini), PDF protetti da password.
 
@@ -105,6 +105,29 @@ Il fix gestisce automaticamente: chunk incompleti (frase spezzata), chunk
 troppo corti (accorpa al successivo), chunk eccessivamente lunghi (spezza
 su punteggiatura). Ogni chunk termina sempre su un confine di frase.
 
+### 7. Esegui l'ingestion
+
+Prima verifica che Ollama e i modelli siano pronti:
+
+```bash
+.venv/bin/python ollama/check_env.py
+```
+
+Poi genera gli embedding e salva in ChromaDB:
+
+```bash
+# Singolo documento
+.venv/bin/python ingestion/ingest.py --stem <nome>
+
+# Tutti i documenti in chunks/
+.venv/bin/python ingestion/ingest.py
+
+# Rigenera dopo aver cambiato modello o aggiornato i chunk
+.venv/bin/python ingestion/ingest.py --stem <nome> --force
+```
+
+Output in `chroma_db/<nome>/` (ignorata da git).
+
 ---
 
 ## Configurazione del chunking
@@ -135,3 +158,4 @@ Modificare solo questo file — chunker, verify e fix si aggiornano automaticame
 ## Riferimenti
 
 - [`conversione/README.md`](conversione/README.md) — dettagli sulla pipeline PDF→Markdown e sui tipi di documento supportati
+- [`ingestion/README.md`](ingestion/README.md) — configurazione embedding, scelta modello, regole --force
diff --git a/ingestion/README.md b/ingestion/README.md
index aed571d..1e86ba0 100644
--- a/ingestion/README.md
+++ b/ingestion/README.md
@@ -1,18 +1,28 @@
-# Step 8 — Vettorizzazione
+# Ingestion — Vettorizzazione
 
-Legge i chunk prodotti da step-6, genera gli embedding tramite Ollama e li
+Legge i chunk prodotti dal chunker, 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`)
+- Chunking completato (esiste `chunks/<stem>/chunks.json`)
 - Ollama attivo con il modello di embedding scaricato
 - `chromadb` installato (`pip install -r requirements.txt`)
 
 ---
 
+## Verifica ambiente
+
+Prima di eseguire l'ingestion, verifica che Ollama e i modelli siano disponibili:
+
+```bash
+.venv/bin/python ollama/check_env.py
+```
+
+---
+
 ## Configurazione modello
 
 Il modello di embedding viene letto da **`config.py`**:
@@ -31,16 +41,16 @@ EMBED_MODEL = "nomic-embed-text"   # ← cambia qui
 
 ```bash
 # Vettorizza un singolo documento
-python ingestion/ingest.py --stem <nome>
+.venv/bin/python ingestion/ingest.py --stem <nome>
 
 # Vettorizza tutti i documenti trovati in step-6/
-python ingestion/ingest.py
+.venv/bin/python ingestion/ingest.py
 
 # Sovrascrive una collection già esistente
-python ingestion/ingest.py --stem <nome> --force
+.venv/bin/python ingestion/ingest.py --stem <nome> --force
 
 # Override modello (senza modificare config.py)
-python ingestion/ingest.py --stem <nome> --model bge-m3
+.venv/bin/python ingestion/ingest.py --stem <nome> --model bge-m3
 ```
 
 ---
@@ -94,7 +104,7 @@ Senza `--force` lo script salta la collection già esistente — i vecchi vettor
 
 ```bash
 # Cambio modello → ricrea sempre la collection
-python ingestion/ingest.py --stem <nome> --force
+.venv/bin/python ingestion/ingest.py --stem <nome> --force
 ```
 
 ### Quando usare `--force`
@@ -103,7 +113,7 @@ python ingestion/ingest.py --stem <nome> --force
 |---|---|
 | Prima esecuzione | No |
 | Hai cambiato `EMBED_MODEL` | **Sì** |
-| Hai migliorato i chunk in step-6 | **Sì** |
+| Hai migliorato i chunk in chunks/ | **Sì** |
 | Hai aggiunto nuovi documenti (stem diverso) | No |
 | Vuoi solo verificare che funzioni | No |