# Traduttore Multiformato - Architettura e Regole

## 1. Chunking e preservazione struttura
- Ogni chunk copre max 2.500 caratteri (testi vocali) o un paragrafo intero se più corto.
- Il chunking cerca di rispettare titoli e separazioni: i chunk iniziano al punto in cui viene individuato un titolo o una riga vuota pre-esistente. Titoli (H1/H2/H3 o linee con `#`) vengono mantenuti e replicati nel chunk iniziale che li contiene.
- Se il chunk contiene più paragrafi, viene inserito un marcatore interno (`¶`) per mantenere la separazione e garantire il merge coerente.
- Per PDF/EPUB, il parser mantiene i metadati originali (titolo, sottotitoli) e li allega al primo chunk.
- Chunk sequenziali vengono inviati a `translategemma:latest` via Ollama e la traduzione restituita viene appesa immediatamente all'interfaccia.
- Il sistema calcola ETA dinamico: media temporale (ms o s) degli ultimi 3 chunk * chunk rimanenti; aggiornato dopo ogni chunk completato.

## 2. Metadati e stato della sessione
- Ogni sessione mantiene:
  - `session_id` (UUID breve)
  - `file_title`: nome file caricato.
  - `text_title`: se disponibile, titolo interno del documento.
  - `source_lang`: lingua rilevata (via `langdetect`).
  - `target_lang`: scelta dropdown (almeno `en`, `it` + altre 13 principali).
  - `total_chunks` e `current_chunk_index`.
  - `started_at`, `ended_at`, `last_chunk_at` (timestamp ISO).
  - `status`: `pending`, `running`, `stopped`, `error`, `completed`.
  - `eta_seconds` e `chunks_remaining` ma anche `error_message`.*
- Il backend espone `/status/{session_id}` per restituire stato, ETA, chunk totali/rimanenti, flag stop, e testo tradotto attualmente completo.

## 3. API FastAPI proposta
- `POST /upload`:
  - Input: file multipart, `target_lang` (codice ISO), optional `session_id` (per riprendere).
  - Output: metadati del file, session_id, chunk count, detected source lang.
  - Effettua parsing in `processors/` e costruisce buffer chunking.
- `POST /start`:
  - Input: `session_id`, `start_from_chunk` optional.
  - Output: conferma avvio, stats iniziali.
  - Inizia loop chunk → Ollama, aggiorna stato, notifica SSE/polling.
- `POST /stop`:
  - Input: `session_id`.
  - Output: flag stop e stato corrente; ferma la sequenza.
- `GET /status/{session_id}`:
  - Output: sessione JSON con tuti i campi sopra incluse caption (titolo file/text, numeri chunk, ETA per UI).
- `GET /stream/{session_id}` (opzionale SSE o websocket): trasmette chunk completati insieme al testo parziale per box traduzione.

## 4. Interfaccia e flusso operativo
- Dropdown lingua: 15 lingue principali (es. `en`, `it`, `es`, `fr`, `de`, `pt`, `ru`, `zh`, `ja`, `ko`, `ar`, `hi`, `nl`, `sv`, `pl`). Inglese e italiano obbligatori.
- Titolo file e titolo testo in caption; seguenti caption per orari e chunk:
  - `File caricato: {file_title}`
  - `Titolo documento: {text_title or titolo fallback}`
  - `Avvio traduzione: {started_at}`
  - `Fine traduzione: {ended_at}` (aggiornato a fine)
  - `ETA: {eta_seconds} sec` (aggiornamento ogni chunk)
  - `Chunk totali: {total_chunks}`
  - `Chunk rimanenti: {chunks_remaining}`
- Box traduzione aggiorna per append di chunk completato; log di errore appare nella caption dedicata.
- Pulsanti: `Avvia traduzione` (chiama /start), `Stop traduzione` (chiama /stop).

## 5. Comunicazione con Ollama
- Client HTTP (es. `httpx.AsyncClient`) verso `https://ollama.solarpi.net/api/models/translategemma:latest`.
- Payload chunk: {"prompt": "translate ...", ... } definire parametro prompt per target.
- Timeout controllato (es. 60s) e retry (max 2) per chunk.
- Se errore, sessione passa in `error` con `error_message` e UI mostra caption rosso.

## 6. Next step suggerito
1. Creare `backend/` e `frontend/` skeleton con router, componenti e placeholder per captions e stato.
2. Implementare parser file e chunker.
3. Costruire client Ollama e endpoint di stato.