🚀 Come iniziare

DatasetForge è protetto da autenticazione tramite API key. All'apertura dell'app viene mostrato un dialog di login. Per iniziare a lavorare serve una chiave valida.

Ottenere e inserire l'API key

1. Richiedi la chiave all'amministratore del sistema. Le chiavi sono definite nel file keys.json sul server. Ogni chiave ha associato un nome identificativo.
2. Inserisci la chiave nel campo "API key" del dialog di login che appare all'apertura dell'app.
3. Premi Invio o clicca "Accedi". Se la chiave è valida, il dialog scompare e viene caricato il dataset.

Dopo il login

L'app carica automaticamente le entry del dataset, i flag aperti e l'overview del grafo. Nell'header vedi:

• Conteggio entry — numero totale di entry nel dataset (con eventuale avviso ⚠ disco quando lo spazio del server è sotto soglia)
• Tab Entries / Flags / Graph / Timeline / Regole / Cataloghi — le sei viste principali (Flags mostra un badge rosso con i flag aperti)
• Barra di ricerca — ricerca full-text con suggerimenti live
• Pulsante "+ Nuova" — crea una nuova entry
• Menu "More" — stats, coverage, validazione, export/import, dedup, integrità, system prompt, webhooks, versioni, cross-validazione, docs, dashboard
• "📋 Guida" — riavvia il tour guidato; "?" — apre questa guida; tema — toggle chiaro/scuro

📝 Editing entries

Le entry sono le coppie domanda/risposta del dataset JSONL. Ogni entry ha un ID numerico (1-based: la riga 1 del file = ID 1).

Aprire l'editor

• Click su una riga della tabella Entries → apre il pannello editor laterale
• Tastiera: posizionati su una riga (con Tab o click) e premi Enter o Space
• Quick jump: premi g seguito dal numero ID della entry (es. g 42 ↵)
• Ricerca: digita nella barra di ricerca, clicca un risultato dell'omnibox

Campi modificabili

In header dell'editor trovi anche il badge qualità (score 0–1 con dettaglio al passaggio del mouse) e il badge ● Non salvato quando ci sono modifiche pendenti.

Grounding: il ponte entry ↔ grafo

Il pannello Grounding elenca le entità del grafo (schermate, campi, azioni…) a cui la entry è ancorata: cercale per nome con il campo 🔍. I chip di grounding sono cliccabili: un click apre il dettaglio dell'entità direttamente nella pagina Graph. Il pulsante ⌫ sul chip rimuove il riferimento (con relativo dirty state).

Pannelli di supporto nell'editor

Salvare le modifiche

1. Modifica i campi desiderati. Un badge ● Non salvato compare in alto a destra e i campi modificati mostrano il badge MODIFICATO.
2. Premi Ctrl+S per salvare senza chiudere, oppure Ctrl+Enter per salvare e chiudere.
3. In alternativa, clicca il pulsante "Salva" nel footer dell'editor.

Navigare tra le entry

Mentre l'editor è aperto puoi passare alla entry successiva/precedente in tre modi:

• Frecce ↑/↓ nell'header dell'editor
• Alt+↑ / Alt+↓ (senza chiudere l'editor)
• Tasti j/k quando il focus è sulla tabella

Creare una nuova entry

Clicca "+ Nuova" nell'header (o premi n). Compila i campi e clicca "Crea entry". La nuova entry ottiene il prossimo ID disponibile.

Operazioni rapide dalla tabella

Nella colonna ⚙ di ogni riga trovi i quick action: Flag (flag veloce), Duplica, Elimina.

Operazioni batch

Seleziona una o più righe con le checkbox (o "Seleziona pagina"): appare una toolbar fluttuante con Elimina, Tag (aggiunta in blocco), Lingua (solo italiano), Difficoltà, Flag (crea un flag su tutte le selezionate), Esporta (JSONL della selezione) e Deseleziona. Con molte entry una barra di progresso mostra l'avanzamento.

L'aggiunta tag in blocco e l'export della selezione sono operazioni singole ottimizzate: anche su centinaia di entry la richiesta al server è una sola (niente attese cumulative).

🕒 Timeline (audit log)

Il tab Timeline è il registro audit di tutto ciò che succede al dataset e alla KB: ogni creazione, modifica, eliminazione, flag e backup con actor e timestamp.

Cosa vedi

• Stat card: Eventi totali, Ultimi 30 giorni (cliccabile: filtra il periodo), Actor (top 10), Ora più attiva
• Grafici: eventi/giorno (30 giorni — clicca una barra per filtrare sul giorno) ed eventi/ora (0–23)
• Chip actor: i top actor, cliccabili per filtrare

Filtri

Nel pannello Filtri: Actor (sottostringa, con suggerimenti), checkbox Tipo azione (Create, Update, Delete, Flag, Resolve, Backup, Altro), Da data / A data, Entry #. Poi Applica per applicare e ⬇ Export per scaricare gli eventi filtrati in JSONL. ↻ Reset azzera; "Questa entry" filtra sulla entry aperta nell'editor.

Catena audit e KB sigillata

Il pannello Catena audit (hash-chain) mostra l'esito della verifica d'integrità della catena degli eventi e lo stato di sigillo della KB:

• badge catena (valida / compromessa) con tail_hash copiabile per attestazione esterna
• stato KB: sealed 🔐, drift ⚠ o unsealed ○; 🔐 Sigilla ora è riservato agli admin
• Report auditor (con export JSON): riepilogo per actor delle azioni svolte

🚩 Flag

I flag sono segnalazioni di revisione associate a una o più entry. Permettono di tracciare problemi, domande, correzioni e miglioramenti da apportare al dataset.

Tipi di flag

Il dialog "Nuovo Flag" offre 12 tipi: i 9 tipi "umani" più 3 tipi automatici generati da scan/crawler del grafo.

Priorità

Ogni flag ha una priorità che ne definisce l'urgenza:

Creare un flag

1. Apri la entry desiderata nell'editor e clicca "Flag", oppure usa il quick action Flag dalla tabella.
2. Nel dialog "Nuovo Flag", seleziona il Tipo e la Priorità.
3. Inserisci un Titolo breve e una Descrizione dettagliata.
4. Per i tipi Duplicate/Contradiction, specifica l'ID della entry collegata.
5. Aggiungi eventuali tag (separati da virgola).
6. Clicca "Crea".

Il nuovo flag compare immediatamente nel tab Flags con stato "Aperto".

Ciclo di vita di un flag (stati)

Risolvere un flag

1. Clicca sul flag nella vista Flags per aprire il dettaglio.
2. Il dettaglio mostra le entry collegate (con la pill → Grafo per le entità citate), la descrizione e l'eventuale discussione (thread).
3. Il form di risoluzione è adattivo: cambia in base al tipo di flag (es. Correction richiede il testo corretto, Duplicate chiede l'ID master da tenere).
4. Compila i campi della risposta e usa i pulsanti in fondo al dialog: cambiano per tipo (es. Applica Fix + Rifiuta per Correction, Deduplica per Duplicate, Crea entry dalla risposta per Question/Gap).

Vista flags: filtri e batch

• In alto i chip rapidi: Aperti, Risolti, Priorità alta, più i dropdown Per tipo e di stato.
• Toggle ▦ / ☰ per passare da vista card a vista tabella.
• Multi-selezione con le checkbox → toolbar batch: ✓ Risolvi tutti, cambio priorità in blocco, Elimina.

🕸️ Graph

La vista Graph è il centro di manutenzione della knowledge base: il grafo di navigazione (schermate, dialog, archi, campi, azioni, sezioni…) più il browser delle collezioni KB e le console di manutenzione.

Statistiche in alto

Una barra di stat-card riassume lo stato del grafo: Screens, Dialogs, Archi nav, Azioni, Densità, Orfani (cliccabile: apre la vista orfani), Placeholders, Ref pendenti (archi verso schermate inesistenti) e KB ver. (versione della KB — cliccala per ricaricare l'overview). Sotto, Dettagli overview espande ruoli, placeholders, ref pendenti e conteggi delle collezioni.

Dopo ogni operazione di scrittura il canvas e le tabelle si aggiornano in modo incrementale (senza reload completo); le card riflettono la nuova kb_version.

Grafo interattivo (Cytoscape)

Sulla destra, un canvas Cytoscape visualizza i nodi e gli archi. Puoi:

• Trascinare i nodi per riorganizzare la vista, scroll per lo zoom
• Cliccare un nodo per aprirne il dettaglio (hub a 7 tab, vedi sotto)
• Usare la ricerca nel grafo (campo in alto) per evidenziare nodi; Reset per pulire, Orfani per i nodi isolati
• Toolbar: Layout (gerarchico ↓/→, organico, cerchio, griglia), ⤢ Fit, ↻ Ridisegna, 🎯 Coverage (verde = coperta da entry, rosso = scoperta), Legenda, ❓ Guida grafo (tour dedicato)
• Passando il mouse su un nodo compare un tooltip con id, tipo, gradi, route e ruoli

Hub di dettaglio (7 tab)

Un click su un nodo/schermata apre il modal di dettaglio con sette tab, navigabili anche con le frecce ←/→:

Ogni riga di entità offre ✏️ modifica inline (writer), 🗑 elimina (admin) e ⧉ copia id.

Tabella schermate

Nel pannello sinistro, una tabella elenca tutte le schermate con ID, nome, tipo (screen/dialog), in-degree e out-degree: ricerca, ordinamento e paginazione. Con il focus sul pannello, j/k navigano le righe e Enter apre il dettaglio.

Path Finder

Il Path Finder trova i percorsi di navigazione tra due schermate:

1. Seleziona la schermata di partenza nel dropdown From.
2. Seleziona la schermata di arrivo nel dropdown To.
3. Scegli il numero massimo di percorsi (Max: 3, 5 o 10).
4. Clicca "Trova" (o "Azzera" per pulire). I percorsi compaiono sotto e vengono evidenziati in arancione sul grafo.

Scanner

Il pannello Scanner confronta la KB con lo stato reale del frontend: "Scansiona grafo" avvia la scansione, il toggle "Crawl dinamico (lento)" la approfondisce. Da "📦 Sorgente bundle" configuri URL e credenziali del bundle remoto (altrimenti viene usato il file locale del server). L'output è un diff report con le discrepanze trovate; lo storico scansioni è nella tabella sotto.

Collezioni KB

Il pannello Collezioni KB è il browser delle 21 collezioni secondarie della KB (Schermate, Archi navigazione, Contenimenti, Azioni, Sezioni, Campi, Dialogs, Interazioni, Entità dominio, Items, User stories, State conditions, Option set, Regole dominio, Layout, Ruoli, Route, Matrice ruoli, Coverage gap, Feature flag, Codici interni esclusi):

• dropdown Collezione + ricerca + filtro "solo senza id"; ↻ ricarica, ⬇ JSON esporta la vista filtrata
• + Nuova crea entità dove la collezione lo consente (form dedicato, con campi nested per il Layout: groups, route_map, boxes…)
• un click su una riga apre il drawer di dettaglio: modifica dei campi patchabili, note/source_ref, eliminazione; per la Matrice ruoli un editor dedicato modifica funzione, ruoli e stringhe della riga
• il badge in testata mostra il totale entità e la kb_version corrente

Manutenzione

Il pannello Manutenzione raggruppa le analisi rapide (output condiviso sotto i pulsanti):

• ⛓ Archi duplicati — stessa from+to+trigger
• 🚧 Vicoli ciechi — schermate da cui non si torna alla home
• ❤️ Salute grafo — score 0–100 di qualità
• 🔗 Valida grounding — cross-check dataset ↔ grafo (il badge ⚠️ in testata conta i grounding pendenti)
• 👥 Ruoli — accessibilità delle schermate per ruolo
• 💾 Backup KB — lista e ripristino (admin)
• ⇄ Confronta versioni — diff tra due versioni della KB (backup vs attuale): schermate/archi/azioni aggiunti, rimossi e modificati, con sezioni espandibili
• ⬇ KB — scarica la KB in JSON

Manutenzione avanzata (dry-run first)

Sotto le collezioni, ogni operazione distruttiva segue lo schema Anteprima (dry-run) → Applica:

• ⛓ Id duplicati — scansione id ripetuti attraverso le collezioni
• 🧹 Normalizza source_ref — anteprima della normalizzazione, poi Applica
• Rinomina id — sposta un id (es. dlg_conferma) su un nuovo nome; con rewrite_grounding aggiorna anche i riferimenti nel dataset
• 🔗 Rewrite grounding — remap di massa vecchio -> nuovo per tipo KB (una coppia per riga)

Finché non premi Applica (rosso, appare solo dopo un'anteprima valida) nulla viene scritto.

Console bulk

Il pannello Console operazioni bulk esegue scritture multiple in una sola transazione: schermate, sezioni, campi, azioni, archi, containment e item in un unico payload JSON (schema di esempio incluso, contatore item con cap 500, strategia on conflict selezionabile).

• Anteprima (dry-run) (Ctrl+Enter) valida il payload senza scrivere
• Applica si abilita solo dopo un'anteprima valida dello stesso payload
• dopo l'applicazione un toast propone ANNULLA: è un undo reale (il server ha creato un backup pre-scrittura e il ripristino lo reacca)
• Copia report, Esempio e la cronologia dei bulk precedenti (con Svuota) completano la console

✅ Regole (Catalogo check + Pragmatica)

Il tab Regole unifica tutti i check di qualità del dataset in due tab: Catalogo e Pragmatica.

Catalogo dei check

Una lista unica con tutti i check (qualità, copertura, stile, struttura):

• Ricerca (nome, id, descrizione) e filtri Stato (attivi / disattivi / con violazioni) e Severity; i chip (Tutte, Qualità, Copertura, Stile, Struttura, Tue) e le stat-card in alto sono essi stessi filtri
• ogni riga mostra: nome, id, badge di provenienza — Tua (regola creata da te), Pragmatica vN (check di stile dal playbook) o Built-in — severity, eventuali chip autofix, numero di violazioni dall'ultimo report e → sezione 16 per i check di stile
• il toggle sulla riga attiva/disattiva il check in tempo reale (admin; Stile e Qualità si possono spegnere). I check Built-in strutturali mostrano 🔒: sono sempre attivi
• solo le regole Tua si possono Modifica, Duplica ed Elimina (dal pannello di dettaglio)
• + Nuova regola apre il form (scope entry o coverage, campo, operatore min_len/max_len/regex/required/forbidden/between/min_count/max_count, severity, valore): una frase in italiano riassume la regola mentre la scrivi
• Export JSON / Importa JSON per portarti le regole dietro

Seleziona un check per leggere descrizione, parametri, provenienza e — dopo una validazione — le entry in violazione (cliccabili, aprono l'editor). Da qui anche Copia id, Prova su entry e Apri playbook per i check di stile.

Valida tutto

Il pulsante ✓ Valida tutto controlla TUTTE le entry contro i check attivi e apre il report:

• stat card: Entry controllate, Violazioni totali, Error, Warning
• Top violazioni come bar chart: ogni barra è cliccabile e porta al check, con badge di provenienza
• elenco delle entry con errori (cliccabili; "Mostra tutte" espande)
• sezione Coverage (soglie grafo): i nodi fuori soglia
• sezione Stile (Pragmatica): violazioni ripartite per check con link a ciascuno

🔧 Autofix applica con una conferma le sole correzioni sicure (es. spazi superflui) a tutte le entry: viene creato un backup prima dell'applicazione. "Valida entry" (campo ID + pulsante) fa la stessa cosa su una singola entry.

Pragmatica

Il tab Pragmatica edita il playbook di stile ("Pragmatica Nutriverso", guida di stile delle FAQ):

• stat card: Versione, Check stile attivi, Aggiornato
• Titolo e Testo (markdown) del playbook, con Anteprima renderizzata, ↻ Ricarica e Salva (admin); il badge non salvato compare alle modifiche
• pannello Check della sezione 16: le 9 regole di stile con nome e descrizione estesa editabili. Ogni riga mostra la provenienza del testo — standard (dal codice) o personalizzato (salvato nel sidecar pragmatica.checks.json) — e il reset singolo ↺ che torna al testo del codice. Salva metadati pubblica le modifiche (admin)
• pannello Check di stile: gli stessi 9 check con toggle (allineato al Catalogo, categoria Stile)

🗂️ Cataloghi

Il tab Cataloghi consulta l'inventario RK (cataloghi Nutriverso): alimenti, categorie, farmaci, trattamenti, stili e sport dal dropdown Tipo catalogo; le altre liste (cliniche, anagrafiche…) sono nell'Inventario sotto.

• Lingua della colonna label (it/en/es/fr/pt/de), righe per pagina (50–500) e ricerca in tutte le lingue
• ↻ Sync (admin) scarica i dump dal backend Nutriverso: un kind che fallisce non cancella gli altri
• i cataloghi non generano entry FAQ e non entrano nel fine-tune: sono un inventario di riferimento

🔍 Ricerca

DatasetForge offre tre livelli di ricerca: omnibox istantanea, filtri strutturati e ricerca avanzata via command palette.

Barra di ricerca (omnibox)

La barra nell'header cerca full-text su domande, risposte e tag del dataset. Mentre digiti:

• Appaiono suggerimenti live (tag, termini frequenti) — cliccali per rifinire
• Appaiono i risultati istantanei — clicca un risultato per aprire l'editor
• La tabella Entries si aggiorna per mostrare solo le entry corrispondenti
• Digita # seguito dall'ID (es. #42) per trovare esattamente quella entry

Premi / in qualsiasi momento per portare il focus sulla barra di ricerca.

Filtri (barra collapsible)

Sotto l'header c'è una barra filtri (apri/chiudi con il pulsante 🔧 Filtri):

I filtri si combinano con la ricerca testuale (e vengono riflessi nell'URL, così un link condiviso ripristina la vista). Il pulsante "Reset" azzera tutti i filtri.

Ricerca avanzata (Command Palette)

Premi Ctrl+K (o Cmd+K su Mac) per aprire la command palette. È un input potente che:

• Elenca tutti i comandi disponibili (nuova entry, vai a vista, export…)
• Include i comandi Grafo: apri schermata… (digita l'id), salute, orfani, collezioni KB, confronta versioni
• Esegue ricerche nel dataset con la stessa logica dell'omnibox (anche qui #id funziona)
• Naviga con ↑/↓ ed esegui con Enter
• Chiudi con Esc

Coverage KB↔Dataset

Da ☰ More → 🎯 Coverage si apre il modal con tre tab:

• Panorama — copertura per tipo di entità e per lingua (by_lang)
• Distribuzione — istogramma delle entry per entità (bucket 0–4+) e soglie under/over con la regola che le ha generate
• Gap da coprire — le entità scoperte, priorità in testa

I pulsanti → Grafo sulle entità aprono il dettaglio nella pagina Graph (schermata nel canvas, le altre nel browser collezioni). Il 🎯 Coverage sulla toolbar del canvas usa gli stessi dati.

⬇️ Export

Esporta il dataset (o un sottoinsieme) in vari formati per uso esterno, training di modelli o integrazioni RAG.

Avviare l'export

Tutto dal menu ☰ More:

• ⬇ Export JSONL — esporta subito tutto il dataset nel formato nativo, un click
• ⚙ Export personalizzato… — apre il dialog con formati, campi e filtri (vedi sotto)
• 📥 Importa Entry… — import in blocco da JSONL/CSV con dry-run
• 🔗 Export RAG — bundle per Langflow KB, pronto da caricare nella knowledge base del chatbot
• 🔄 Sync KB Langflow — ricostruisce la KB Langflow dal dataset (admin, qualche minuto)

Formati disponibili

Selezionare i campi

Nel dialog puoi scegliere quali campi includere nell'export:

• user, assistant — contenuti principali
• lang, source, difficulty — metadata
• tags — etichette
• group_id — gruppo multilingua
• grounding — informazioni di ancoraggio

Filtri di export

Puoi filtrare l'export per lingua, difficoltà, sorgente e tag. Spunta "Includi metadata" per aggiungere ID e timestamp di export.

Export RAG (Langflow)

L'opzione 🔗 Export RAG genera un bundle formattato per Langflow KB, pronto da caricare nella knowledge base del chatbot.

⌨️ Scorciatoie da tastiera

DatasetForge è progettato per un uso intensivo da tastiera. Premi ? in qualsiasi momento per vedere il riepilogo inline nell'app.

📊 Dashboard (Health Monitoring)

La Dashboard è una pagina dedicata al monitoraggio dello stato di salute del sistema e del dataset. È accessibile separatamente dall'app principale.

Metriche monitorate

Health Score

Il Health Score è un punteggio che riassume la qualità globale del dataset, calcolato su più fattori. Una barra verde (ottimo), gialla (attenzione) o rossa (critico) ne indica il livello.

Event Log

In fondo alla dashboard, un log degli eventi in tempo reale mostra le operazioni del server (richieste, errori, backup) con timestamp.

Auto-refresh

La dashboard si aggiorna automaticamente a intervalli regolari. Puoi configurare l'intervallo o mettere in pausa l'auto-refresh.