Synthesis e una piattaforma RAG (Retrieval Augmented Generation) scritta interamente in Python. Permette di:

• caricare documenti (pdf, doc, docx, txt, csv)
• estrarre e chunkare il contenuto
• storicizzare i chunk in ChromaDB
• interrogare i dati tramite assistant virtuale web
• scegliere runtime LLM tra provider locali (Ollama) e commerciali (OpenAI, Gemini, Anthropic, Kimi)

L'interfaccia e web-based, responsive, usabile da desktop e mobile.

Cosa fa il sistema

Il flusso end-to-end e:

1. Upload file dalla UI.
2. Parsing del documento (con fallback per PDF scannerizzati).
3. Chunking del testo.
4. Indicizzazione su ChromaDB.
5. Retrieval dei chunk pertinenti alla domanda.
6. Generazione risposta con integrazione:
   • evidenze documentali [DOC]
   • conoscenza modello [Syntesis]
7. Visualizzazione risposta con fonti e formule LaTeX renderizzate in UI.

Come funziona (architettura)

• backend/main.py
  • API REST FastAPI
  • gestione upload/list/delete file
  • endpoint chat/query
  • serving frontend (/ e /static)
• backend/services/file_parser.py
  • estrazione testo multi-formato
  • fallback PDF image-only (quando non esiste testo estraibile)
• backend/services/chunking.py
  • split in chunk sovrapposti
• backend/services/rag_store.py
  • persistenza/query su ChromaDB
• backend/services/rag_service.py
  • retrieval + orchestrazione contesto RAG
• backend/services/llm_providers.py
  • gateway provider LLM (ollama, openai, gemini, anthropic, kimi)
• frontend/index.html
  • struttura UI
• frontend/static/app.js
  • logica client (upload, chat, stop risposta, cronologia locale)
• frontend/static/styles.css
  • tema e stile UI responsive

Funzionalita principali

• Upload e indicizzazione singolo file.
• Lista file con icona formato, dimensione, data, chunk count.
• Cancellazione file da UI (metadata + file + chunk ChromaDB).
• Chat con selezione provider/modello/top-k.
• Chat con allegato diretto nel prompt (documenti e immagini, analisi one-shot senza storicizzazione su ChromaDB).
• Cronologia chat persistente lato browser (localStorage).
• Cancellazione singolo messaggio e cancellazione totale chat.
• Pulsante invio stile freccia su, con stop (square) durante la generazione.
• Rendering formule LaTeX in risposta.

Prerequisiti

1) Sistema

• macOS, Linux o Windows
• Python consigliato: 3.13

Nota: con Python 3.14 alcune versioni di ChromaDB possono causare errori runtime.

2) Runtime LLM

• Per uso locale: Ollama in esecuzione (OLLAMA_BASE_URL, default http://localhost:11434)
• Per provider commerciali: API key opzionali in .env
  • OPENAI_API_KEY
  • ANTHROPIC_API_KEY
  • GEMINI_API_KEY
  • KIMI_API_KEY (opzionale, con endpoint OpenAI-compatible)

Nota OpenAI: per "GPT 5.3" in API usa gpt-5.3-codex (Responses API).

3) Dipendenze opzionali

• Supporto .doc legacy:
  • antiword installato a sistema
  • oppure textract (requirements-doc.txt)

Installazione

Opzione A (consigliata): uv + Python 3.13

uv python install 3.13
uv venv --python 3.13 .venv313
uv pip install --python .venv313/bin/python -r requirements.txt

Per supporto .doc via textract:

uv pip install --python .venv313/bin/python -r requirements-doc.txt

Opzione B: venv classico

python3.13 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

Configurazione

1. Copia il file env:

2. (Opzionale) modifica variabili principali:

• DATA_DIR, UPLOAD_DIR, CHROMA_DIR, METADATA_DB_PATH
• CHUNK_SIZE, CHUNK_OVERLAP, TOP_K_DEFAULT
• OLLAMA_BASE_URL
• SYNTHESIS_HOST, SYNTHESIS_PORT (host/porta server web)
• API key provider commerciali

Avvio

Avvio backend + web app

Con ambiente uv:

.venv313/bin/python run_backend.py

Con venv classico:

.venv/bin/python run_backend.py

Apri:

• http://127.0.0.1:8002

Helper opzionale per aprire il browser:

.venv313/bin/python run_ui.py

Uso rapido

1. Vai su Documenti.
2. Seleziona file e clicca Carica e indicizza.
3. Vai su Assistant.
4. Scegli provider/modello/top-k.
5. Scrivi domanda e premi Enter (invio diretto).
6. (Opzionale) Allega un file direttamente dal box chat per una richiesta one-shot.
   • Per allegati immagine usa provider kimi (multimodale).
7. Durante la generazione puoi cliccare il bottone stop per interrompere.

API principali

• GET /api/health
• GET /api/providers
• GET /api/models/{provider}
• POST /api/files/upload
• GET /api/files
• DELETE /api/files/{file_id}
• POST /api/files/{file_id}/delete (fallback compatibilita)
• POST /api/chat/query
• POST /api/chat/query-with-file (multipart: domanda + allegato prompt)
• GET /api/debug/retrieval

Note importanti

PDF scannerizzati (image-only)

Se un PDF non contiene testo nativo, il sistema:

• non fallisce ingestione
• indicizza un fallback descrittivo (metadati + avviso OCR richiesto)

Per indicizzare il testo reale di questi PDF serve OCR esterno (es. Tesseract/OCRmyPDF).

Troubleshooting rapido

• Errore ChromaDB con Python 3.14:
  • usa Python 3.13 (vedi installazione Opzione A)
• HTTP 404 su delete file:
  • aggiorna backend all'ultima versione e riavvia
• UI non aggiornata:
  • hard refresh browser (Cmd+Shift+R su macOS)