davide
98653464dd
README.md: sezione MinerU espansa con requisiti di sistema, installazione (pip/conda/Docker), CLI completo con tutti i flag, tabella comparativa backend (pipeline/hybrid-auto-engine/vlm-auto-engine), configurazione avanzata, struttura output e limitazioni note. CLAUDE.md: aggiornato diagramma pipeline, input RICHIESTO/RACCOMANDATO, comandi con --force e --skip-optimize, architettura chunker/md_optimizer. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
130 lines
5.1 KiB
Markdown
130 lines
5.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
---
|
|
|
|
## Lingua e comportamento
|
|
|
|
- **Lingua:** Rispondi sempre in italiano.
|
|
- **Prima di eseguire qualsiasi istruzione**, esponi:
|
|
1. Come intendi procedere (approccio, file coinvolti).
|
|
2. Se l'istruzione ha problemi concettuali — e perché — con una proposta alternativa.
|
|
3. Aspetta conferma o correzione prima di toccare il codice, salvo che l'istruzione sia banale (rinomina, formattazione).
|
|
|
|
---
|
|
|
|
## Missione
|
|
|
|
Pipeline RAG su documenti accademici. La conversione PDF → Markdown è delegata a **MinerU** (tool esterno). Questo repository si occupa solo di: pulizia Markdown, chunking, vettorizzazione e retrieval/generazione.
|
|
|
|
```
|
|
MinerU (esterno) → sources/<stem>/auto/
|
|
↓
|
|
chunker.py (Stage 1: _clean.md + Stage 2: chunks.json)
|
|
↓
|
|
ingest.py (embedding → ChromaDB)
|
|
↓
|
|
rag.py / retrieve.py
|
|
```
|
|
|
|
---
|
|
|
|
## Regole invarianti
|
|
|
|
- **Venv:** Usa `.venv/bin/python`. Mai `pip`/`python` di sistema.
|
|
- **Niente LLM nella pipeline:** chunking e pulizia devono essere rule-based e riproducibili.
|
|
- **Input immutabile:** Non modificare mai i file originali in `sources/<stem>/auto/`. Il `chunker.py` scrive solo `_clean.md` (prodotto derivato) nella stessa cartella e `chunks.json` in `chunks/<stem>/`.
|
|
|
|
---
|
|
|
|
## Input — struttura MinerU
|
|
|
|
MinerU produce una cartella per ogni documento. Posizionarla in `sources/`:
|
|
|
|
```
|
|
sources/<stem>/auto/<stem>_content_list_v2.json ← struttura ricca (tipo, livello, bbox) [RICHIESTO]
|
|
sources/<stem>/auto/<stem>_model.json ← label di layout (doc_title, abstract…) [RACCOMANDATO]
|
|
sources/<stem>/auto/<stem>.md ← Markdown grezzo (non usato dalla pipeline)
|
|
sources/<stem>/auto/<stem>_middle.json ← dati intermedi (non usato)
|
|
sources/<stem>/auto/images/ ← immagini estratte
|
|
```
|
|
|
|
`<stem>` = nome del documento, usato in tutti i comandi come identificatore.
|
|
|
|
---
|
|
|
|
## Comandi
|
|
|
|
```bash
|
|
# Setup
|
|
python -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt
|
|
|
|
# Chunking unificato: Stage 1 (_clean.md) + Stage 2 (chunks.json)
|
|
.venv/bin/python chunks/chunker.py --stem <stem>
|
|
.venv/bin/python chunks/chunker.py # tutti gli stem in sources/
|
|
.venv/bin/python chunks/chunker.py --stem <stem> --force # rigenera tutto
|
|
.venv/bin/python chunks/chunker.py --stem <stem> --skip-optimize # salta Stage 1
|
|
|
|
# Solo Stage 1 (se serve rigenerare solo il _clean.md)
|
|
.venv/bin/python chunks/md_optimizer.py --stem <stem> --force
|
|
|
|
# Verifica e correzione chunk
|
|
.venv/bin/python chunks/verify_chunks.py --stem <stem>
|
|
.venv/bin/python chunks/fix_chunks.py --stem <stem>
|
|
|
|
# Vettorizzazione (richiede Ollama attivo)
|
|
.venv/bin/python ingestion/ingest.py --stem <stem>
|
|
.venv/bin/python ingestion/ingest.py --stem <stem> --force
|
|
|
|
# RAG interattivo
|
|
.venv/bin/python rag.py --stem <stem>
|
|
.venv/bin/python retrieve.py --stem <stem> # retrieval puro, senza LLM
|
|
```
|
|
|
|
---
|
|
|
|
## Architettura
|
|
|
|
### Chunking — `chunks/`
|
|
|
|
| File | Responsabilità |
|
|
|------|---------------|
|
|
| `chunker.py` | Entry point unificato: chiama `md_optimizer` (Stage 1) poi esegue il chunking (Stage 2) |
|
|
| `md_optimizer.py` | Modulo Stage 1: `_content_list_v2.json` + `_model.json` → `<stem>_clean.md` |
|
|
| `config.py` | Tutti i parametri: `MAX_CHARS`, `MIN_CHARS`, `OVERLAP_SENTENCES`, `FRONTMATTER_HEADINGS`, `SOMMARIO_PATTERNS`, label sets model.json |
|
|
| `verify_chunks.py` | Verifica qualità chunk (lunghezze, frasi spezzate, prefissi) |
|
|
| `fix_chunks.py` | Correzioni post-chunking (merge incompleti, split lunghi) |
|
|
|
|
`md_optimizer.py` è generico rispetto al documento: usa le strutture comuni di tutti gli output MinerU (`_content_list_v2.json` e `_model.json`) senza dipendere da pattern testuali lingua-specifici. I parametri documento-specifici (es. `FRONTMATTER_HEADINGS` per documenti italiani) sono in `config.py`.
|
|
|
|
Output: `chunks/<stem>/chunks.json`, `chunks/<stem>/meta.json`, `chunks/<stem>/report.json`
|
|
|
|
### Vettorizzazione — `ingestion/ingest.py`
|
|
|
|
Legge `chunks/<stem>/chunks.json`, genera embedding via Ollama (`EMBED_MODEL`), indicizza in ChromaDB persistente (`chroma_db/`). Supporta collection multi-documento (`--collection <nome> --stems doc1 doc2`).
|
|
|
|
### RAG — file radice
|
|
|
|
| File | Responsabilità |
|
|
|------|---------------|
|
|
| `rag.py` | Loop interattivo: retrieval + generazione Ollama |
|
|
| `retrieve.py` | Retrieval puro (debug senza LLM) |
|
|
| `config.py` | `TOP_K`, `TEMPERATURE`, `OLLAMA_MODEL`, `EMBED_MODEL`, `SYSTEM_PROMPT`, `OLLAMA_URL` |
|
|
|
|
### Output per stem
|
|
|
|
```
|
|
chunks/<stem>/chunks.json
|
|
chunks/<stem>/meta.json
|
|
chunks/<stem>/report.json
|
|
chroma_db/<stem>/ ← collection ChromaDB
|
|
```
|
|
|
|
---
|
|
|
|
## Skills custom
|
|
|
|
- `/prepare-md <path|stem>` — corregge il Markdown MinerU: sillabazione, artefatti, header malformati, gerarchia incoerente. Opera su una copia, non sull'originale.
|
|
- `/post-chunk` — verifica e perfeziona i chunk prima della vettorizzazione.
|