ThothII/CONTEXT.md

Contesto di dominio di ThothII

Architettura del workflow

Workflow Kernel — Il coordinatore deterministico che possiede lo stato del workflow, le transizioni, il rollback, la finalizzazione e l'applicazione atomica degli esiti dei moduli.

Workflow Module — Una capacità incapsulata che espone un contratto versionato. Un modulo può partecipare a più stage e non modifica direttamente lo stato del workflow.

Stage — Un punto del workflow, identificato semanticamente, nel quale viene invocato un modulo. L'identità dello stage è indipendente dalla sua posizione visiva.

Display code — L'etichetta di presentazione associata a uno stage, per esempio da F1 a F8. I display code alimentano gli indicatori di avanzamento nel frontend, ma non sono usati come identità del workflow o chiavi di dipendenza.

Module outcome — Il risultato proposto da un modulo: eventi tipizzati, modifiche agli artifact, un'eventuale richiesta di revisione umana e uno stato di esecuzione. Il Workflow Kernel valida e applica l'esito.

Revision request — La proposta tipizzata con cui un modulo segnala che lo stage corrente non può concludersi validamente senza rieseguire lo stesso stage o uno stage precedente. Non produce direttamente una transizione: il Workflow Kernel valida la richiesta, sospende l'avanzamento e, per riaprire uno stage già completato, attende una decisione umana tipizzata. Il Kernel, non il modulo, determina gli eventi e gli artifact causalmente da rendere stale.

Question Admission — Il controllo preliminare eseguito prima delle fasi da F1 a F8. Nella prima release distingue una domanda utilizzabile da input garbage e verifica che la domanda appartenga allo scope dichiarato dal workspace. Il suo stato è mostrato separatamente dagli otto indicatori di fase.

Workspace scope — La dichiarazione gestita e versionata di ciò che il database di un workspace rappresenta e delle domande alle quali è destinato a rispondere. Question Admission la usa come riferimento per valutare la pertinenza di una domanda.

Datamart Plugin — Il modulo sostituibile che implementa lo stage semantico datamart, presentato con display code F8. La promozione della memory e la finalizzazione della sessione non appartengono al Datamart Plugin.

Ordered workflow — La pipeline deterministica composta dal preflight Admission, dagli otto stage principali ordinati da F1 a F8 e dalla finalizzazione. L'ordine degli stage è esplicito; il workflow non è un DAG generale.

Extension point — Una posizione semantica nel lifecycle dell'Ordered workflow alla quale possono contribuire uno o più moduli senza diventare nuovi stage visibili. Un extension point non possiede un display code.

Stage state — La proiezione deterministica degli eventi del workflow che descrive uno stage come pending, ready, running, awaiting_human, completed, skipped o failed. Non è un valore corrente memorizzato separatamente dal ledger.

Required contribution — Il contributo di un modulo a un extension point che deve concludersi o essere esplicitamente saltato secondo policy prima che il workflow possa avanzare.

Best-effort contribution — Il contributo di un modulo il cui fallimento viene registrato e mostrato come warning, ma non impedisce al workflow di avanzare.

Blocked workflow — La proiezione complessiva di un workflow che non può avanzare a causa di uno stage o di un contributo required fallito o non disponibile. Blocked non è uno Stage state autonomo.

Module invocation — Una singola richiesta del Workflow Kernel a un modulo in uno stage o extension point. Conserva la stessa identità attraverso eventuali retry, che sono tentativi distinti della medesima invocation.

Stage skip — La conclusione esplicita di uno stage senza eseguirne il comportamento. È ammessa soltanto dalla policy dello stage e registra motivo e attore; un fallimento non equivale mai implicitamente a uno skip.

Stage reopen — La riapertura di uno stage non finalizzato che rende stale gli esiti causalmente successivi. Gli effetti esterni già prodotti richiedono una marcatura o una compensazione esplicita e non sono presentati come automaticamente annullati. Può essere applicata dal Workflow Kernel in seguito all'approvazione di una Revision request, ma non può essere eseguita direttamente da Pi o da un Workflow Module.

Completion policy — La regola con cui uno stage si conclude: automatic quando il kernel può verificarne deterministicamente l'esito, oppure review_required quando è necessaria un'approvazione umana tipizzata.

Paused session — Una sessione interrotta intenzionalmente ma resumibile. L'azione “Stop and save” mette la sessione in pausa; non la completa e non la marca come fallita.

Finalized session — Una sessione completata con esito canonico e immutabile. Una correzione successiva crea una nuova sessione derivata, collegata a quella precedente.

After-finalize hook — Una notifica o attività best-effort eseguita tramite outbox dopo la finalizzazione. Non può modificare il ledger, gli artifact canonici o lo stato terminale della sessione.

Memory

Memory Module — Il modulo che possiede le conoscenze ed esperienze curate per migliorare schema linking e generazione SQL di domande future. Le Memory appartengono a un workspace e rimangono distinte dalle Evidence.

Memory Card — L'unità di contenuto gestibile del Memory Module, con identità, ambito di applicazione e provenienza. Il formato è allineato per analogia alle Evidence, senza implicare la stessa origine o lo stesso percorso di pubblicazione.

Reusable Memory — Una Memory Card che esprime un chiarimento di dominio, una regola di costruzione SQL o un errore da evitare con motivo compreso e approvato. La sua validità è circoscritta a un ambito esplicito e non deriva dalla sola approvazione di una scelta occasionale in una domanda.

Solved Question — Una Memory Card che conserva una domanda risolta con la relativa soluzione SQL e il contesto necessario a interpretarla. È un exemplar consultativo: i parametri e le scelte del caso non diventano regole generali.

Memory Graph — L'insieme dei collegamenti espliciti fra card che contribuisce al recupero di conoscenze pertinenti oltre alla somiglianza del contenuto. Il ritrovamento di una card tramite un collegamento non ne implica l'approvazione.

Memory Link — Un collegamento curato fra card, con destinazione e significato espliciti, che contribuisce alla consultazione di contenuti pertinenti. La sua rimozione non comporta la cancellazione delle card collegate.

Evidence

Context specialist — La persona competente sul dominio che redige e cura il contenuto delle Evidence. Può essere distinta da chi amministra l'installazione; il suo lavoro di redazione non richiede accesso al database applicativo.

Evidence draft — Il documento iniziale scritto dallo specialista di contesto, che il sistema acquisisce e raffina in Evidence Unit. Può essere redatto e consegnato indipendentemente dall'installazione che userà le Evidence risultanti.

Evidence Module — Il modulo autonomo che possiede la preparazione delle Evidence e la loro consultazione durante il workflow. La preparazione avviene fuori dalle singole sessioni; il workflow usa soltanto contenuti già pubblicati. A runtime contribuisce agli stage semantici esistenti, senza diventare uno stage visibile e senza modificare ledger, artifact o stato del workflow.

Source Evidence — Il documento o la dichiarazione che sostiene il contenuto corrente di una Evidence Unit. Un documento acquisito viene conservato come riferimento umano; una dichiarazione manuale attribuisce il contenuto alla persona che lo ha scritto e approvato.

Manual Evidence declaration — Una dichiarazione esplicita dell'amministratore che sostiene una Evidence creata direttamente o una correzione del suo significato. Non implica una verifica indipendente da parte di una fonte documentale esterna.

Evidence origin — Il documento da cui una Evidence Unit è stata inizialmente derivata. Può restare collegato per provenienza e confronto con gli aggiornamenti anche quando una dichiarazione manuale sostiene il testo corrente. La sola origine non dimostra il supporto semantico di una successiva correzione.

Local Evidence archive — L'insieme delle Evidence curate custodite dall'installazione, distinto dalle draft originali e dai contenuti derivati per la ricerca. Comprende le correzioni manuali e i ritiri deliberati.

Consolidated Evidence — Una versione delle Evidence locali controllata come insieme coerente e pronta per l'attivazione. I file ancora in modifica non ne cambiano il contenuto.

Active Evidence — La versione consolidata disponibile alla consultazione del core. Un tentativo di aggiornamento fallito conserva la versione attiva precedente.

Evidence Unit — La più piccola unità semantica coerente, revisionabile e ricercabile fondata su una Source Evidence corrente, anche manuale, e con eventuale origine documentale distinta. Possiede un identificatore stabile indipendente dal kind, assegnato una volta nella forma evidence:<slug>; fonti diverse non vengono fuse automaticamente.

Evidence kind — La categoria semantica di una Evidence Unit, che ne determina i campi specifici e ne orienta l'uso. Ogni unità ha un solo kind primario; i tipi iniziali sono glossary, domain, enum, example, mapping, normalization, formula e reference.

Glossary Evidence — Una Evidence Unit che definisce il significato linguistico, i sinonimi o le varianti di un termine.

Domain Evidence — Una Evidence Unit che esprime una regola o un vincolo del dominio non rappresentato da un kind più specifico.

Enum Evidence — Una Evidence Unit che collega un insieme finito di valori memorizzati ai relativi significati.

Example Evidence — Una Evidence Unit che associa un input o una domanda alla sua interpretazione o al risultato atteso.

Mapping Evidence — Una Evidence Unit che collega un concetto logico agli elementi del relativo schema fisico.

Normalization Evidence — Una Evidence Unit che descrive la trasformazione di una rappresentazione in una forma canonica.

Formula Evidence — Una Evidence Unit che contiene una singola espressione PostgreSQL componibile e ne dichiara gli input. Una query SQL completa non è una Formula Evidence.

Reference Evidence — Una Evidence Unit che rappresenta un collegamento esterno da restituire come contenuto autonomo, anziché come semplice provenienza.

Evidence purpose — La destinazione dichiarata di una Evidence Unit nel workflow: disambiguation, rewriting, schema linking o SQL generation. È distinta dall'Evidence kind: il tipo descrive cosa contiene, il purpose quando può essere utile; durante la ricerca il purpose richiesto è un filtro obbligatorio. Il recupero di esperienze e soluzioni precedenti appartiene al Memory Module e non è un Evidence purpose.

Evidence Search Outcome — Il risultato tipizzato di una consultazione del modulo Evidence. Distingue una ricerca disponibile, che può legittimamente non trovare corrispondenze, da un'indisponibilità tecnica che impedisce allo stage chiamante di avanzare fino a un retry riuscito.

Evidence receipt — La traccia minima di una consultazione disponibile conservata nella sessione: stage semantico, purpose, generazione interrogata e identificatori delle Evidence restituite. Non duplica il contenuto delle Evidence.

Curated Evidence — Una o più Evidence Unit preparate da documenti o curate manualmente. La presenza nell'archivio curato non implica da sola che il contenuto sia già attivo per il workflow.

Published Evidence — Le Curated Evidence valide appartenenti alla revisione attiva del workspace e alla generazione Evidence pubblicata. L'approvazione umana precede l'attivazione, ma non viene duplicata come stato nel manifest.

Evidence Index — La proiezione ricercabile e ricostruibile delle Published Evidence. Accelera il recupero delle informazioni, ma non è una fonte di verità.

Evidence preparation — Il processo di authoring che trasforma Source Evidence in Curated Evidence mediante estrazione e normalizzazione deterministiche, una singola ristrutturazione assistita dal modello e una validazione finale deterministica. Nella prima versione accetta Markdown o testo UTF-8 e non acquisisce automaticamente il contenuto di URL o documenti esterni. Prepara l'intero insieme delle modifiche in un'area temporanea e lo applica atomicamente soltanto se tutti gli output sono validi; non ritenta automaticamente una chiamata al modello fallita.

Supporting excerpt — Un breve estratto presente nel Source Evidence che sostiene una Evidence Unit. Il sistema ne verifica deterministicamente la presenza dopo la normalizzazione meccanica; il curatore resta responsabile di verificarne la sufficienza semantica.

Evidence resolution — La decisione esplicita con cui un curatore risolve un problema di una Evidence Unit, correggendola, ritirandola oppure ricollegandola a una fonte adeguata.

Source update conflict — Un contrasto fra una fonte aggiornata e una correzione manuale già approvata. La correzione resta in uso fino alla risoluzione esplicita del confronto da parte dell'amministratore.

Evidence source refresh — La riacquisizione delle fonti esterne richiesta dall'amministratore per rilevarne le modifiche. Fra due aggiornamenti il contenuto già acquisito resta il riferimento per preparazione e consultazione.

Review item — Un blocco di revisione descritto da codice stabile, messaggio umano e campo opzionale. Finché viene mantenuto nell'Evidence Unit, ne impedisce la pubblicazione; la sua storia è conservata da Git, non da uno stato interno all'item.

Retirement candidate — Una Curated Evidence che il Source Evidence esistente non sostiene più. Rimane visibile con un Review item e blocca la pubblicazione finché il curatore non la elimina oppure la rende nuovamente coerente con il sorgente.

Evidence evaluation set — Un piccolo insieme versionato di domande rappresentative e relativi risultati attesi. La baseline è accettabile quando ogni domanda recupera almeno un risultato atteso nei primi dieci risultati della fusione RRF; il risultato nei primi cinque è informativo. Comprende almeno un caso lessicale, uno semantico e uno misto e conserva, a fini diagnostici, le posizioni dense, BM25 e fused.

Candidate Evidence Generation — Una generazione completa dell'Evidence Index che può essere valutata ma non è ancora visibile alle sessioni. Diventa attiva soltanto se supera l'Evidence evaluation set.

Evidence manifest — Il file versionato e gestito dal sistema che collega ogni Source Evidence al suo hash e alle Evidence Unit derivate. Conserva gli identificatori stabili, permette l'elaborazione incrementale e segnala le unità rimaste orfane senza cancellarle automaticamente.

Orphaned Evidence Unit — Una Curated Evidence il cui Source Evidence non esiste più. Rimane disponibile per la revisione, ma blocca la pubblicazione finché non viene eliminata, ricollegata oppure ne viene ripristinato il sorgente.

Evidence Fragment — Una proiezione ricercabile di una sezione semanticamente coerente di una Published Evidence. La divisione segue intestazioni e confini di paragrafo; formule, coppie valore/significato, mapping, regole e URL non vengono mai tagliati. Il testo completo reso per il frammento usa il solo limite esistente max_chunk_chars, pari per default a 4.000 caratteri; un elemento atomico troppo grande produce un Review item bloccante. Qdrant indicizza i frammenti, mentre l'Evidence Module li raggruppa per Evidence Unit.

Evidence Result — La rappresentazione di una singola Evidence Unit restituita dalla ricerca con metadati, migliori estratti, provenienza e riferimento al documento completo.

Hybrid Evidence retrieval — La ricerca che combina in Qdrant una graduatoria semantica dense e una graduatoria lessicale BM25 sparse mediante Reciprocal Rank Fusion. I metadati tipizzati restringono o orientano i risultati senza creare una collezione separata per ogni Evidence kind.

Evidence query text — La rappresentazione deterministica condivisa dalla ricerca dense e BM25: domanda originale, concetti, tabelle e colonne in ordine fisso. I campi vuoti sono omessi; domanda e contesto ricevono soltanto normalizzazione Unicode NFC, conversione degli a-capo e rimozione degli spazi esterni. Gli elementi contestuali sono poi deduplicati e ordinati senza conversione delle maiuscole, mentre punteggiatura e spazi interni della domanda non vengono riscritti.

Reference Vector Collection — La collezione Qdrant ricostruibile di un workspace che contiene Schema, relazioni ed Evidence. Possiede il vettore dense predefinito e il vettore sparse bm25; soltanto gli Evidence Fragment ricevono valori BM25. Il preprocessing può sostituirla o eliminarla integralmente.

Memory Vector Collection — La collezione Qdrant persistente di un workspace che contiene memory e solved_question. Non è un output del preprocessing e non viene eliminata dal Preprocessing Clear.

Preprocessing Clear — L'operazione amministrativa che elimina Reference Vector Collection, LSH, corpus e checkpoint derivati e rende il workspace non pronto. Conserva Memory Vector Collection, sessioni, Catalog Metadata e database sorgente; non offre history o rollback.

Formula proposal — Una formula individuata durante una sessione e conservata come artefatto della sessione. Non diventa Published Evidence finché non viene importata, revisionata e approvata nel repository del workspace.

Fail-closed Evidence retrieval — Il comportamento per cui un indice assente, incompatibile o non aggiornato produce nessuna Evidence e un avviso esplicito. Il workflow può continuare, ma non usa mai silenziosamente contenuti di una revisione precedente o di un altro workspace.

Configurazione dei modelli

Workspace Descriptor — La dichiarazione versionata dell'identità del workspace e dello scope delle sue Evidence. Non contiene identità o configurazione del Workspace Database, Database Binding, fatti strutturali o metadati semantici: il Metadata Catalog associa il workspace al relativo database.

Installation Model Catalog — L'insieme dichiarativo, proprio di un'installazione, dei modelli disponibili, dei loro Model Usage e dei relativi default. È l'unica autorità per i modelli di sessione, generazione dei metadati ed embedding e non appartiene a un workspace. Avoid: Model Catalog, Metadata Generation Model Configuration

Model Usage — Lo scopo per cui un modello dell'Installation Model Catalog può essere usato: session, metadata_generation oppure embedding. L'ammissibilità e il default dipendono dall'uso, non dal workspace.

Model Selection — La scelta runtime, a livello di installazione, di un modello del catalogo per uno specifico Model Usage. Riferisce l'identità canonica del modello senza ridefinirne provider, endpoint o capacità.

Model Runtime Projection — La rappresentazione derivata e non autoritativa dell'Installation Model Catalog richiesta da uno specifico runtime. Può essere rigenerata integralmente dalla configurazione dell'installazione.

Distribuzione del prodotto

Customer-Hosted Installation — Un'installazione eseguita interamente nel trust boundary controllato dall'organizzazione cliente, inclusi eventuali tenant cloud privati. Credenziali, domande, prompt, metadati e risultati non attraversano quel boundary. Avoid: on-premise deployment, self-managed deployment

Community Edition — La distribuzione open source utilizzabile gratuitamente anche in produzione e capace di eseguire il workflow fondamentale completo. Avoid: free tier, trial edition

Enterprise Edition — La distribuzione con licenza commerciale che aggiunge governance organizzativa, esercizio production-grade e industrializzazione alla Community Edition. Avoid: paid tier, pro edition

Catalogo dei metadati

Workspace Database — Il database che appartiene a un solo workspace e non può essere condiviso con altri workspace; un workspace può averne al massimo uno. È considerato nella coppia composta dal database PostgreSQL e da un solo schema: tutte le tabelle, le colonne e le relazioni catalogate appartengono a quello schema. Il Metadata Catalog conserva l'associazione, ma non crea né possiede l'identità del workspace.

Database Binding — La configurazione specifica di un'installazione che seleziona un trasporto e fornisce i riferimenti necessari a raggiungere un Workspace Database. Non è una seconda identità del database e non viene condivisa automaticamente fra installazioni.

Thoth REST Connector — Il trasporto REST tipizzato con cui ThothII interroga ed introspeziona un Workspace Database attraverso il contratto RPC DWH supportato. Non è un client configurabile per API REST arbitrarie.

Orphaned Workspace Database — Un Workspace Database il cui workspace non è più presente nel catalogo autorevole. Rimane conservato per il recupero amministrativo, ma non può essere usato dal workflow finché non viene riassegnato a un workspace esistente.

Metadata Catalog — L'autorità per l'associazione fra workspace e Workspace Database, la relativa Database Binding, i fatti strutturali osservati e i metadati semantici curati. Ogni uso downstream dei metadati del database deriva da questo catalogo.

Database Profile — L'insieme curato di scope, descrizioni e metadati semantici associato a un Workspace Database.

Physical Table — Una tabella osservata nello schema esterno di un Workspace Database. La sua identità e il suo nome appartengono al database esterno, non al Metadata Catalog.

Catalog Table — La rappresentazione persistita di una Physical Table nel Metadata Catalog. La sua appartenenza e identità fisica derivano dall'introspezione: non può essere creata o rinominata manualmente, ma può essere rimossa tramite Catalog Metadata Cleanup. Avoid: SqlTable, managed table

Physical Column — Una colonna osservata in una Physical Table, inclusi nome, posizione, tipo e appartenenza a chiavi dichiarate. La sua identità e i suoi fatti strutturali appartengono al database esterno.

Catalog Column — La rappresentazione persistita di una Physical Column nel Metadata Catalog. I fatti osservati sono governati dalla sincronizzazione; Description e Generated Description sono metadati amministrativi modificabili e la rappresentazione può essere rimossa tramite Catalog Metadata Cleanup. Avoid: SqlColumn, managed column

Physical Relationship — Un vincolo foreign key dichiarato nel database esterno. La sua identità comprende il vincolo e la sequenza ordinata delle coppie di colonne che lo compongono.

Catalog Relationship — La rappresentazione persistita di una Physical Relationship nel Metadata Catalog. Non è creata o modificata manualmente, ma può essere rimossa tramite Catalog Metadata Cleanup. Avoid: denormalized FK, relationship string

Logical Relationship — Una relazione modificabile fra due Catalog Column che non corrisponde necessariamente a un vincolo fisico. Può essere Generated o Manual e rimane distinta dalla Catalog Relationship osservata nel database.

Generated Relationship — Una Logical Relationship ricavata dai nomi delle colonne, dalle primary key e dalla compatibilità dei tipi mediante regole deterministiche, senza LLM, embedding o campionamento dei dati. Una ricostruzione non riattiva una Generated Relationship cancellata logicamente, ma può ricrearne una cancellata fisicamente.

Manual Relationship — Una Logical Relationship aggiunta dall'utente. La ricostruzione delle Generated Relationship non la modifica.

Logical Relationship Deletion — L'esclusione persistente di una Logical Relationship che ne conserva l'identità per impedirne la ricreazione automatica finché esistono entrambe le Catalog Column alle quali è collegata.

Permanent Relationship Deletion — La rimozione completa di una Logical Relationship. Una ricostruzione successiva può ricrearla quando soddisfa nuovamente le regole di inferenza. Anche il cleanup distruttivo di una tabella o colonna endpoint rimuove permanentemente le relative esclusioni.

Relationship Reconstruction — L'operazione amministrativa esplicita che scopre e aggiunge le Generated Relationship mancanti. Conserva le Manual Relationship e le relationship già presenti e non riattiva quelle cancellate logicamente.

Relationship Restore — La riattivazione esplicita di una Logical Relationship cancellata logicamente.

Effective Relationship Map — La vista unificata delle Catalog Relationship fisiche e delle Logical Relationship, con origine e stato espliciti. È l'interfaccia usata dall'amministrazione e dalla comprensione dello schema, non un ulteriore modello persistito.

Catalog Metadata Snapshot — La proiezione immutabile e versionata della struttura catalogata, delle descrizioni pubblicabili e delle relazioni effettive attive di un Workspace Database che il core consuma. È derivata esclusivamente dal Metadata Catalog e non è un archivio autoritativo.

Schema Index — La proiezione vettoriale ricostruibile dei metadati del Workspace Database nel Metadata Catalog. Il preprocessing la sostituisce integralmente e non è una fonte di verità.

Description — Il testo curato e consolidato che descrive una Catalog Table o Catalog Column per gli usi downstream. Quando presente, prevale sulla relativa Generated Description.

Generated Description — Il testo modificabile prodotto dall'AI per una Catalog Table o Catalog Column. È pubblicabile per gli usi downstream quando manca una Description, anche senza essere prima consolidato, e rimane distinto dal commento osservato nel database. Avoid: generated comment, source comment

Description Consolidation — L'azione amministrativa esplicita che copia la Generated Description di Catalog Table o Catalog Column selezionate nella relativa Description. Opera sulla selezione corrente, conserva la Generated Description e non modifica il commento osservato o il database esterno.

Table Synchronization — La riconciliazione esplicita che rende le Catalog Table di un Workspace Database uguali alle Physical Table osservate: crea quelle nuove, aggiorna i metadati di origine ed elimina definitivamente quelle assenti. Non modifica mai il database esterno. Avoid: table import

Schema Synchronization — La riconciliazione esplicita e autorevole di tabelle, colonne e Catalog Relationship di un Workspace Database. Può operare su uno scope specifico oppure su un unico snapshot completo tramite Synchronize All.

Catalog Sync Run — L'esecuzione durevole in background di una Schema Synchronization, con scope, stato, avanzamento e log propri. Al massimo un run per Workspace Database può essere attivo.

Description Generation Run — L'esecuzione asincrona e sequenziale che usa il modello scelto per produrre Generated Description di Catalog Table o Catalog Column. Al massimo una run è attiva nell'intera installazione e ogni risultato valido viene salvato appena disponibile. Dopo un'interruzione il recupero è manuale tramite una nuova generazione dei soli elementi mancanti.

Description Generation Event — Una riga testuale ordinata che registra avanzamento, risultato o errore di una Description Generation Run e alimenta il log visibile all'amministratore.

Non-generatable Description — L'esito valido con cui il modello dichiara di non disporre di informazioni sufficienti per descrivere il target. Produce una Generated Description standard nella lingua del workspace e non rappresenta un timeout, un errore del provider o una risposta non valida.

Description Generation Unlock — Il recupero amministrativo che marca come interrotta una Description Generation Run registrata come attiva quando il backend non ha alcun processo di generazione vivo. Non è un meccanismo di lock distribuito.

Catalog Metadata Cleanup — La rimozione amministrativa esplicita di Catalog Table, Catalog Column o Catalog Relationship selezionate. Non modifica il Workspace Database, la Database Binding o i segreti, e può lasciare il Metadata Catalog intenzionalmente incompleto fino alla prossima Schema Synchronization.

Catalog Freshness — La corrispondenza fra uno scope sincronizzato e la versione corrente della Database Binding. Uno scope rimane consultabile ma è stale finché non viene sincronizzato con la binding corrente.

Metadata Content Revision — La revisione monotona di tutto lo stato del Metadata Catalog che può modificare il comportamento del core. Ogni mutazione rilevante produce una nuova revisione nella stessa transazione che la rende durevole.

Preprocessing State — Lo stato corrente running, succeeded o failed del preprocessing di un workspace, insieme all'identità dei suoi input. Il core può usare il workspace soltanto quando lo stato è succeeded e gli input coincidono ancora.

Catalog Metadata — I campi mutabili che descrivono database, tabelle, colonne e relazioni, distinti dai fatti strutturali governati dalla sincronizzazione. Possono essere popolati dall'AI, o da una modifica amministrativa senza cambiare il database esterno.

Model Completion Helper — Il processo Python interno ed effimero che esegue una singola richiesta LiteLLM per conto del backend. Non è un servizio HTTP, non possiede il lifecycle della Description Generation Run e non è una CLI esposta agli utenti.

Catalog Sample — Un input transitorio composto da un massimo di cinque righe e da valori di esempio bounded di una Catalog Table per la generazione delle descrizioni. Può contenere valori reali oppure sintetici in base alla Source Value Disclosure Decision; non viene persistito e non diventa Catalog Metadata.

Sensitive Data Flag — La classificazione binaria umana applicata a una Catalog Column. Può essere impostata liberamente dall'amministratore anche in contrasto con una valutazione automatica.

Sensitivity Reason — La motivazione sanificata persistita insieme al Sensitive Data Flag quando l'amministratore salva una Sensitivity Review Draft. È Catalog Metadata della colonna, non history della run; viene rimossa quando il flag torna non-sensitive e può essere assente per una classificazione manuale priva di valutazione locale. Avoid: AI reasoning, source evidence

Local Sensitivity Assessment — La valutazione locale, non autoritativa e priva di LLM di una Catalog Column, basata su metadati e contenuto sorgente, con esito sensitive, non_sensitive oppure unknown. Avoid: AI suggestion, automatic flag

Local NER Detector — Il componente NLP opzionale e CPU-only che esamina soltanto testo ancora ambiguo e restituisce evidenze al Local Sensitivity Assessment. Non decide lo stato della colonna, non usa un LLM generativo e non persiste valori sorgente. Avoid: AI classifier, local LLM fallback

Model Data Boundary — La qualificazione amministrativa di un modello come internal oppure external rispetto al confine entro cui i valori sorgente possono essere comunicati. Avoid: local model, remote model

Source Value Disclosure Decision — L'unica decisione effettiva che stabilisce se un modello riceve valori sorgente reali oppure sostituti sintetici, combinando Model Data Boundary e Sensitive Data Flag. Avoid: sample filter, export flag

Sensitive Data Policy — L'insieme versionato di regole locali generali e specifiche che produce una Local Sensitivity Assessment. Un singolo riscontro blocca l'intera colonna e qualsiasi valore testuale più lungo di 500 caratteri rende sensibile la colonna. Avoid: PII filter, sample filter

Sensitivity Analysis Run — Il tentativo amministrativo esplicito e tracciato che valuta una selezione di colonne mediante la Sensitive Data Policy. Conserva stato, copertura e conteggi aggregati, ma non valori sorgente né esiti per colonna. Avoid: Sensitive Data Suggestion Run, AI analysis

Sensitivity Review Draft — La proposta transitoria che associa alle colonne selezionate una Local Sensitivity Assessment e le relative evidenze sanificate. Non modifica il Sensitive Data Flag né la Sensitivity Reason finché l'amministratore non salva le proprie decisioni e viene scartata al reload. Avoid: automatic flag

Sensitivity Analysis Event — Una riga testuale ordinata e sanificata che registra l'avvio, l'avanzamento per fase e batch, l'esito o l'errore di una Sensitivity Analysis Run senza conservare contenuti sorgente, output grezzi del detector o proposte per colonna. Avoid: Sensitive Data Suggestion Event

Introspection Capability — Una categoria di struttura fisica che una Database Binding può osservare, come tabelle, colonne, relazioni, indici o enum. Una capability non disponibile è distinta da una capability osservata che non ha restituito elementi.

Amministrazione e integrazione

Workspace Readiness — La preparazione di uno specifico Workspace per l'uso nel workflow, comprensiva della disponibilità degli artefatti derivati dai suoi metadati Database e dalle sue Evidence. Il preprocessing appartiene a questa preparazione; la configurazione e la sincronizzazione del catalogo restano responsabilità Database.

Administration Surface — Una superficie amministrativa autonoma per configurare o curare una parte dell'installazione. Workspace, Evidence, Memory, Database e Pi sono superfici peer e non dipendono dall'esistenza di una sessione attiva.

Administration Page — La rappresentazione a pagina intera di una Administration Surface, con una gerarchia condivisa per identità, stato, azioni e contenuto. Un form amministrativo appartiene alla pagina e non a una popup come contenitore principale. Avoid: management popup, settings modal

Administration Route — L'identità navigabile di una Administration Surface nel browser. Deve essere ripristinabile con refresh e cronologia e non contiene valori transitori o segreti dei form.

Embedded Thoth Shell — L'esperienza Thoth ospitata dentro il documento e il contesto visuale di un portale host. Conserva la propria gerarchia funzionale, ma deve rispettare la geometria, l'autenticazione e le regole responsive del portale host.

Full Thoth Shell — L'esperienza Thoth autonoma che possiede il proprio header e il proprio layout di pagina. Non replica la navigazione amministrativa del portale host e non dipende dal suo template visuale.

Shell mode — La scelta di installazione fra embedded e full. Determina chi possiede il chrome globale, i comandi di identità e le integrazioni visuali, ma non cambia il workflow o la persistenza delle sessioni.

Fullscreen state — Lo stato temporaneo in cui il documento applicativo occupa il fullscreen del browser. È distinto da Shell mode: una Full Thoth Shell può essere aperta senza fullscreen; il passaggio è attivato da un comando esplicito e può essere annullato con la stessa azione o con il comando nativo del browser.

Portal Shell Adapter — Il confine sostituibile che traduce lo stato e i comandi del chrome di un portale host nel modello semantico usato da Thoth. L'adapter non possiede autorizzazione, sessioni di workflow o contenuti del modello.

Host Shell State — Il minimo stato visuale fornito dal portale host: locale UI, tema e stato fullscreen. In una Embedded Thoth Shell è la fonte autorevole per queste preferenze; non include identità, token o stato di autenticazione, che restano responsabilità dell'accesso.

UI locale — La lingua delle label, dei messaggi, dei tooltip, degli stati e delle istruzioni non generate dal modello nell'interfaccia Thoth. È distinta dalla lingua dei contenuti di un workspace.

Interaction language — La lingua in cui il modello presenta domande, spiegazioni e proposte al revisore durante una sessione. Viene fissata alla creazione della sessione e rimane invariata durante una ripresa, anche se la UI locale corrente cambia.

Administrative Page Family — L'insieme delle cinque Administration Page che condividono shell, navigazione, tipografia e regole responsive, pur mantenendo contenuti e operazioni specifici: Workspace, Evidence, Memory, Database e Pi.

Installazione

Manual standalone installation — Una copia di ThothII predisposta per l'uso autonomo da una persona che possiede il computer, con una Full Thoth Shell e servizi applicativi locali. La procedura non implica che DWH o provider LLM siano locali o disponibili offline.

Installation bootstrap — L'insieme delle attività iniziali che rende disponibile una installazione manuale: verifica dell'host, generazione della configurazione, predisposizione delle credenziali protette e avvio dei servizi. Non è un installer dell'applicazione.

Platform acceptance — La verifica che una Manual standalone installation possa essere predisposta e avviata su una specifica combinazione di sistema operativo, architettura e runtime, distinta dalla verifica funzionale del collegamento a DWH e provider LLM.