# Product ## Platform web ## Users Pubblico potenziale open source: ricercatori e archivisti digitali che lavorano su giornali storici con layout complessi (multi-colonna, tabelle dense) e vogliono affinare un modello di document parsing sul proprio corpus. Uso reale corrente: studio self-hosted, multi-utente — primo avvio con setup dell'amministratore, login con sessioni (cookie HttpOnly), ruoli globali (admin/editor/viewer), accesso ai progetti per proprietario o membro, impostazioni istanza e gestione utenti (creazione, attivazione, reset password, eliminazione). La registrazione è chiusa di default e l'admin la apre dalle Impostazioni; `TABULARIUM_AUTH=off` conserva la modalità locale a utente singolo per chi non vuole login. ## Product Purpose Tabularium è un ambiente professionale per generare testo strutturato da immagini e documenti. L'utente sceglie un modello e dove eseguirlo — macchina locale o provider remoto — poi usa lo stesso flusso per riconoscere una pagina o un intero archivio, controllare e correggere i risultati anche a GPU spenta, ed esportarli. Registra inoltre le pagine (immagini/PDF) con metadati e guida l'annotazione super-dettagliata (blocchi semantici, tabelle con celle unite, ordine di lettura, trascrizione con convenzioni), esporta il dataset nel formato ufficiale ms-swift (JSONL, coordinate 0–1000, tabelle OTSL), genera e lancia il training di MonkeyOCRv2-Parsing (LoRA/SFT) con monitoraggio live, e valuta su pagine mai viste (TEDS, CER/WER, IoU layout, ordine di lettura) per iterare. Successo = il proprietario di un archivio riesce, da solo, a trasformare pagine in risultati revisionabili ed esportabili e, quando serve, a produrre un modello affinato — senza dover conoscere l'infrastruttura del provider né toccare a mano JSONL, OTSL o script di training. ## Positioning Unico strumento end-to-end guidato per il fine-tuning di MonkeyOCRv2-Parsing su corpus storici: l'annotazione è pensata per layout giornalistico d'epoca (tabelle con celle unite, colonne "fantasma", ordine di lettura multi-colonna), l'export rispetta rigorosamente le convenzioni ufficiali del modello (JSONL ms-swift, coordinate 0–1000, OTSL verificato contro `otsl_to_html`), e il training usa gli script/iperparametri canonici del repo ufficiale — nessuna reinventazione del pipeline. ## Operating Context - Web app locale multipiattaforma (Windows/Linux/macOS): un solo processo backend FastAPI che serve la UI e orchestra tutto; annotazione ed export funzionano ovunque. - Il training richiede GPU NVIDIA con CUDA (env dedicato `monkeyocrv2-train`), tipicamente su Linux; il repo ufficiale `Yuliang-Liu/MonkeyOCRv2` resta un checkout esterno configurabile, mai modificato. - Sessioni di annotazione lunghe su scansioni ad alta risoluzione: zoom/pan fluido, scorri- mute da tastiera, autosave, undo/redo, checklist convenzioni sempre visibile. - Dati reali dell'utente: nessuna distruzione automatica; ogni operazione distruttiva richiede conferma esplicita. - Lingue del progetto: documentazione e commenti in italiano, identificatori e log in inglese. ## Capabilities and Constraints - M0–M8 completati e in uso quotidiano: scaffolding, progetti e pagine, studio di annotazione, tabelle e reading order, dataset builder, training center, valutazione e playground, pseudo-labeling, build servita dal backend. Sopra di esso il layer self-hosted (setup iniziale, login, ruoli, impostazioni istanza, gestione utenti). Roadmap e dettagli in `AGENTS.md` §12. - Le elaborazioni bulk sono persistite pagina per pagina: supportano risultati originali e revisionati, export JSON, CSV o testo, recupero delle sole pagine fallite e rilascio del server locale al termine. Una sola run modello usa la GPU alla volta. - Convenzioni dati non negoziabili (verificate su `core_runner.py` ufficiale): JSONL ms-swift con path assoluti, coordinate normalizzate 0–1000 solo in export, tabelle in OTSL, prompt ufficiali §2.3 di AGENTS.md. - Tassonomia estendibile per progetto: 11 label pubbliche del parsing + classi custom giornale (`Issue-header, Column, Headline, Byline, Advertisement, Note`). - Backend senza PyTorch: training/inferenza girano in processi/env separati (subprocess, vLLM, SSE per i log); il dashboard non dipende mai dal training in esecuzione. - Storage: SQLite + filesystem; percorsi mai hard-coded (env var `TABULARIUM_ROOT`). - Inferenza locale: **dipende dall'hardware, e Tabularium lo dichiara**. Su Linux con GPU NVIDIA il percorso è vLLM; su Apple Silicon è MLX (`mlx-vlm`), con un server OpenAI-compatibile che copre i modelli il cui percorso è stato **verificato su una pagina vera**: PaddleOCR-VL e Qwen3-VL. MonkeyOCRv2 e MinerU2.5 non hanno un port MLX; DeepSeek-OCR-2 e Unlimited-OCR richiedono un vincolo di decodifica (il logits processor n-gram di vLLM) che MLX non espone; dots.mocr e GLM-OCR si caricano ma non completano una pagina (fallimento rumoroso e successo vuoto, rispettivamente). Tutti e sei restano remoti su un Mac, e la UI lo dice per modello, con la causa, invece di offrire un comando che fallisce. Su Windows il percorso è WSL2. Il runtime locale (venv vLLM, venv MLX, pipeline Paddle per il percorso ufficiale di PaddleOCR-VL) lo prepara Tabularium al primo avvio: nessun passaggio manuale. Motore unico della decisione: `services/hardware.py`; matrice e misure in `docs/guide/local-inference.md`. - In decisamente deciso: destinazione del rilascio pubblico (licenza, repo pubblico, momento). ## Brand Commitments - Nome: **Tabularium**, legato al corpus di riferimento "Historic Shipping Index" (1900s). - Il prodotto è candidato a rilascio pubblico/open source: naming, UX e documentazione devono reggere l'esposizione a un pubblico esterno. ## Evidence on Hand - Corpus corrente: progetto "Tabularium Smoke" con 3 pagine registrate in `data/tabularium.db`; thumbnails in `data/thumbs/`. - Fonte di verità tecnica: `AGENTS.md` (contesto ufficiale MonkeyOCRv2, convenzioni dati, iperparametri, roadmap, regole operative). - Nessun corpus esterno verificato, nessuna metrica pubblicata, nessun testimonial: i claim futuri sulle metriche vanno prodotti dalla fase di valutazione (M6), mai inventati. ## Product Principles 1. **Inferenza prima, infrastruttura seconda**: modello e provider sono configurazione; il flusso di riconoscimento, revisione ed export resta identico ovunque venga eseguito. 2. **Fedeltà all'ufficiale**: ogni convenzione dati/prompt/formato segue il repo ufficiale MonkeyOCRv2; in dubbio, verificare il codice sorgente, mai approssimare. 3. **Guidato, non magico**: ogni correzione manuale dell'utente è dato di training; il tool mostra e insegna le convenzioni invece di nasconderle. 4. **I dati dell'utente sono sacri**: nessuna distruzione automatica, conferme esplicite, log/replay sempre disponibili. 5. **Funziona ovunque si annota**: la preparazione dati è multipiattaforma; solo il training richiede la GPU dedicata. 6. **Iterazione misurata**: ogni ciclo annotazione→training→valutazione produce metriche (TEDS, CER/WER, IoU) che guidano il ciclo successivo.