diff --git a/README.md b/README.md index 9919938..8f95215 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Sistema RAG (Retrieval-Augmented Generation) costruito da zero, senza framework di alto livello. Funziona su qualsiasi PDF digitale. Gira interamente in locale, senza GPU, senza cloud. -**Stack:** Python · Ollama · nomic-embed-text · Qwen3 8B · ChromaDB +**Stack:** Python · Ollama · nomic-embed-text · Qwen3.5 · ChromaDB **Compatibile con:** Linux · macOS · Windows (WSL2) · CPU Only · ~8 GB RAM libera --- @@ -72,25 +72,54 @@ rag-from-scratch/ ├── sources/ # PDF originali — non modificare mai │ └── documento.pdf │ -├── processed/ # Output di ogni step per ogni documento -│ └── documento/ -│ ├── raw.md # MD grezzo da marker (non toccare) -│ ├── clean.md # MD revisionato a mano -│ ├── structure_profile.json # Profilo struttura da step 3 +├── step-0/ +│ └── check_pdf.py # Verifica requisiti del PDF +│ +├── step-1/ +│ └── inspect_pdf.py # Ispezione automatica del PDF +│ +├── step-2/ +│ ├── convert_pdf.py # Conversione PDF → Markdown grezzo +│ └── / +│ └── raw.md # MD grezzo (non toccare) +│ +├── step-3/ +│ ├── detect_structure.py # Rilevamento struttura MD +│ └── / +│ └── structure_profile.json # Profilo struttura +│ +├── step-4/ +│ ├── revise.py # Pre-processing automatico MD +│ ├── revision_log.md # Log modifiche manuali +│ └── / +│ ├── clean.md # MD revisionato +│ └── structure_profile.json # Profilo aggiornato +│ +├── step-5/ +│ ├── chunker.py # Chunking adattivo +│ └── / │ └── chunks.json # Chunk pronti per la vettorizzazione │ -├── scripts/ -│ ├── inspect.py # Step 1 — ispezione PDF -│ ├── detect_structure.py # Step 3 — analisi struttura MD -│ ├── chunker.py # Step 5 — chunking adattivo -│ ├── verify_chunks.py # Step 6 — verifica chunk -│ ├── ingest.py # Step 8 — vettorizzazione -│ ├── rag.py # Step 9 — pipeline RAG -│ └── test_pipeline.py # Step 10 — test automatici +├── step-6/ +│ ├── verify_chunks.py # Verifica chunk +│ ├── fix_chunks.py # Fix chunk problematici +│ └── / +│ └── chunks.json # Chunk verificati │ -├── chroma_db/ # Vector store — generato da ingest.py -├── notes/ -│ └── revision_log.md # Log delle modifiche manuali al MD +├── step-7/ +│ ├── check_env.py # Verifica ambiente locale +│ └── README.md # Guida installazione Ollama e dipendenze +│ +├── step-8/ +│ └── ingest.py # Vettorizzazione → ChromaDB +│ +├── step-9/ +│ ├── config.py # Configurazione pipeline RAG ← modifica qui +│ ├── rag.py # Pipeline RAG interattiva +│ ├── test_ollama.py # Test chat Ollama senza RAG +│ └── README.md +│ +├── chroma_db/ # Vector store — generato da step-8 ├── requirements.txt ├── .gitignore └── README.md @@ -136,15 +165,15 @@ Se ottieni caratteri strani o testo nell'ordine sbagliato, il PDF ha problemi. ### Step 1 — Ispezione automatica **Tipo:** automatico -**Input:** `sources/documento.pdf` -**Output:** report testuale con score e lista problemi -**Script:** `scripts/inspect.py` +**Input:** tutti i PDF in `sources/` +**Output:** `step-1/_step1_report.txt` +**Script:** `step-1/inspect_pdf.py` ```bash -python scripts/inspect.py sources/documento.pdf --save +python step-1/inspect_pdf.py ``` -Lo script analizza il PDF pagina per pagina e produce un report. +Lo script scansiona automaticamente tutti i PDF in `sources/`, analizza ogni documento pagina per pagina e produce un report. Serve per capire la qualità del documento e mappare i problemi prima di affrontare la revisione manuale. @@ -186,33 +215,29 @@ PROSSIMI PASSI: ### Step 2 — Conversione in Markdown grezzo **Tipo:** automatico -**Input:** `sources/documento.pdf` -**Output:** `processed/documento/raw.md` -**Tool:** marker-pdf +**Input:** tutti i PDF in `sources/` (o uno solo con `--pdf`) +**Output:** `step-2//raw.md` + `step-2//clean.md` +**Script:** `step-2/convert_pdf.py` ```bash -marker_single sources/documento.pdf processed/documento/raw.md +python step-2/convert_pdf.py # tutti i PDF in sources/ +python step-2/convert_pdf.py --pdf sources/doc.pdf # un solo PDF ``` -Converte il PDF in Markdown. Il risultato non è perfetto — è la base +Converte il PDF in Markdown usando `pymupdf4llm`. Il risultato non è perfetto — è la base su cui lavorerai nello step 4. -**Regola fondamentale:** `raw.md` non va mai modificato. -È il punto di partenza di riferimento. Se qualcosa va storto -nella revisione, puoi sempre ripartire da qui. +Lo script crea due file: +- `raw.md` — conversione grezza, **non modificare mai**. È il punto di partenza di riferimento. +- `clean.md` — copia di lavoro che verrà modificata negli step successivi. -```bash -# Crea subito la copia su cui lavorare -cp processed/documento/raw.md processed/documento/clean.md -``` - -**Cosa produce marker:** +**Cosa produce la conversione:** - Titoli riconosciuti e convertiti in `#` `##` `###` - Paragrafi separati da righe vuote - Sillabazione parzialmente risolta -**Cosa non produce marker:** +**Cosa non produce:** - Rimozione intestazioni e piè di pagina - Correzione completa del layout a colonne @@ -223,15 +248,17 @@ cp processed/documento/raw.md processed/documento/clean.md ### Step 3 — Rilevamento struttura **Tipo:** automatico -**Input:** `processed/documento/raw.md` -**Output:** `processed/documento/structure_profile.json` -**Script:** `scripts/detect_structure.py` +**Input:** `step-2//` +**Output:** `step-3//structure_profile.json` +**Script:** `step-3/detect_structure.py` ```bash -python scripts/detect_structure.py processed/documento/raw.md +python step-3/detect_structure.py # tutti i documenti in step-2/ +python step-3/detect_structure.py --stem # un solo documento +python step-3/detect_structure.py --force # riesegui anche se già presente ``` -Analizza la struttura del Markdown grezzo senza modificarlo. +Copia `raw.md` e `clean.md` da `step-2//` e analizza la struttura del Markdown senza modificarla. Il profilo prodotto guida sia la revisione manuale che il chunker. **I quattro livelli strutturali:** @@ -472,35 +499,14 @@ Distribuzione lunghezze: **Output:** ambiente locale funzionante **Script:** `step-7/check_env.py` +Installa Ollama, scarica i modelli e verifica l'ambiente. Si esegue una volta sola. + +Vedi [`step-7/README.md`](step-7/README.md) per istruzioni dettagliate e scelta dei modelli. + ```bash -# Installa Ollama -curl -fsSL https://ollama.com/install.sh | sh - -# Scarica un modello di embedding e un LLM -ollama pull nomic-embed-text # Embedding — ~274 MB (consigliato) -ollama pull qwen3.5:4b # LLM — ~3.4 GB (consigliato per 8 GB RAM) - -# Installa dipendenze Python nel venv -source .venv/bin/activate -pip install -r requirements.txt - -# Verifica tutto python step-7/check_env.py ``` -**Modelli consigliati per 8 GB RAM:** - -| Modello | Ruolo | Dimensione | -|---|---|---| -| `nomic-embed-text` | Embedding | ~274 MB | -| `qwen3.5:4b` | LLM | ~3.4 GB | - -Per guide dettagliate su modelli alternativi, installazione e disinstallazione -di Ollama e ChromaDB, vedi [`step-7/README.md`](step-7/README.md). - -Questo step si esegue una volta sola. Da questo momento -Ollama è sempre disponibile sul sistema. - --- ### Step 8 — Vettorizzazione @@ -575,53 +581,16 @@ Non è necessario ripetere questo step a meno che il documento cambi. **Tipo:** interattivo **Input:** `chroma_db/` + domanda dell'utente **Output:** risposta basata sul documento -**Script:** `scripts/rag.py` +**Script:** `step-9/rag.py` ```bash -python scripts/rag.py +source .venv/bin/activate +python step-9/rag.py --stem ``` -Mette insieme retrieval e generation in un loop interattivo. +Loop interattivo che risponde a domande sul documento. Configura i parametri in `step-9/config.py` prima di avviare. -**Flusso per ogni domanda:** - -``` -La tua domanda in testo - │ - ▼ embedding della domanda (nomic-embed-text) -vettore 768 dimensioni - │ - ▼ ricerca per similarità coseno in ChromaDB -top 3 chunk semanticamente più vicini - │ - ▼ costruzione del prompt -"Rispondi SOLO dal contesto: - [chunk 1] - [chunk 2] - [chunk 3] - Domanda: ..." - │ - ▼ Ollama (Qwen3 8B) -risposta generata -``` - -**Come si usa:** - -``` -Domanda: La tua domanda qui -Domanda: La tua domanda qui -v ← aggiunge i chunk recuperati -Domanda: exit -``` - -**La similarità coseno:** -Misura l'angolo tra due vettori — non la distanza ma l'orientamento. -Due testi semanticamente simili puntano nella stessa direzione -nello spazio a 768 dimensioni, indipendentemente dalla loro lunghezza. - -**Regola del prompt:** -Il LLM risponde SOLO dal contesto fornito. -Se la risposta non è nel documento lo dice esplicitamente. -Non inventa, non integra con conoscenza esterna. +Vedi [`step-9/README.md`](step-9/README.md) per la configurazione completa. --- @@ -630,10 +599,10 @@ Non inventa, non integra con conoscenza esterna. **Tipo:** automatico **Input:** sistema completo **Output:** tutti i test verdi -**Script:** `scripts/test_pipeline.py` +**Script:** `step-10/test_pipeline.py` *(da implementare)* ```bash -python scripts/test_pipeline.py +python step-10/test_pipeline.py --stem ``` Verifica ogni componente in isolamento e poi nel sistema completo.