ThothII/prd/ThothII-prd.md

ThothII

Obiettivo del progetto: costruzione di un sistema che permetta, a partire da una richiesta fatta in linguaggio naturale, di generare un SQL eseguibile su un certo database

ThothII deve essere scritto in Python e Typescript/Javascript ed appoggiarsi al coding harness Pi (http://pi.dev) per l'esecuzione dei task che devono essere delegati a un AI model.

Il codice va organizzato in tre layer. ognuno dei quali va sviluppato all'interno di una sua cartella:

1. un frontend in React, che usa NextJs+ShadCn+AGGrid + qualunque altra libreria di frontend adatta allo scopo;
2. un backend scritto in qualunque modo, che si interfaccia con il coding harness Pi per eseguire i task che devono essere delegati a un AI model. Può essere tranquillamente un'applicazione NodeJs+Fastify
3. un harness, cioè un insieme di Typescript/Javascript + Skills in markdown che costituiscano l'harness di Pi usato in modalità rpc. E' già stato scritto un harness, disponibile in ./ChironeWp3, che funziona, ma va riscritto tenendo conto che ThothII non prevede la possibilità di interagire direttamente con il coding harness Pi. Il codice di ChironeWp3 va riscritto tenendo conto che Pi deve rispondere solo im json, in modo che le sue risposte possano essere facilmente parsate dal backend ed esposte nel frontend con i giusti widget. Ciò è una importante variazione. Inoltre

L'architettura può essere oggetto di discussione durante la fase di brainstorming e design.

Punti chiave di discussione

Per facilitare la discussione, riporto in ordine sparso idee e considerazioni varie, tutte potenziale oggetto di arricchimento durante il brainstorming.

L'applicazione deve avere al centro il workflow di generazione del SQL a partire da una domanda espressa in linguggio naturale, ma deve anche fornire un frontend per l'esecuzione di attività normalmente fatte tramite CLI su Pi come la scelta del model, del tema, del linguaggio, la selezione, il richiamo e la navigazione di una session, ecc. La lista dei comandi di Pi e della lista del setup del frontend React da implementare sarà oggetto di discussione durante il brainstorming ed il design.

L'aderenza al workflow delineato in ./ChironeWp3 deve essere stretta in quanto funzionante. Potrà essere oggetto di perfezionamento in versioni future, ma il MVP deeve aderire a quanto sviluppato, a parte eventuali bug fix o evidenti miglioramenti applicabili subito.

L'applicazione, come già fa quella attualmente sviluppata, può contare su tre risorse disponibili collegandosi al server di produzione:

• un Supabase contenente il datawarehouse per cui si vuole generare il SQL
• un pgvector, contenuto anch'esso nel Supabase, che contiene gli embeddings dei documenti che descrivono il datawarehouse
• un LLM (qwen 3.6 - 35B) utilizzabile da Pi che gira sulle GPU del server di produzione, ed è quindi gratuito

all'interno del progetto ./ChironeWp3 vi sono già tutti gli elementi necessari per gestire la connessione col datawarehouse del policlinicosandonato, ma ThothII deve potersi interfacciare con qualunque database e con un pgvector locale nel caso non sia disponibile un pgvector remoto. Per cui deve essere previsto un insime di configurazioni destinate a implementare il concetto di workspace composto da db relazionale + pgvector (locale o remoto) su cui operare prevedendo diverse modalità di accesso (REST, tunnel ssh, accesso diretto) e diverse tipologie di db relazionale (posthres, sqlserver, mariadb ed informix innanzitutto)

Per quanto riguarda il collegamento ad un database qualunque trovi in ./Thoth/thoth_sqldb2 del codice a cui potersi ispirarsi per l'implementazione di un modulo di connessione a database generico.

il workflow

1. disambiguazione della richiesta fatta
2. recupero delle memory per loro utilizzo nella creazione dello schema-linking
3. riscrittura ed approvazione della domanda riscritta
4. creazione e discussione dello schema-linking
5. sintesi dello schema-linking determinato
6. costruzione e discussione dei CTE
7. generazione e discussione del SQL finale
8. visualizzazione, tramite AGGrid, del risultato ed eventuale generazione del dbt in grado di essere eseguito in un flusso ETL

Questo workflow è già stato implementato in ./ChironeWp3, ma ThothII deve avere una gestne basata su una UI gestita in REACT appositamente per avere un controllo migliore del workflow e dei documenti intermedi che vengono prodotti.

Prima di tutto ci deve essere, in ThothII, una pagina in cui si vede il workflow, come una specie di lista numerata, com visualizzazione deegli step terminati e possibilità di reset del processo al punto richiamato. Ogni step del workflow deve produrre un documento che sta alla base dello step successivo, in modo da minimizzare il contesto necessario ad ogni fase.

L'interfaccia utente

l'interfaccia deve mostrare i messaggi che arrivano da PI sia come messaggi che spiegano, sia come richieste di scelta tra diverse opzioni o richieste di informazioni tramite chat. Deve però mostrare solo i messaggi principali, mentre i COT e l'eventuale thinking, se presente, devono essere visibili in finestre dedicate, nel sidebar di destra, a richiesta.

La deve essere divisa in quattro parti, come fa Codex di OpenAI. Un sidebar di sinistra dove avere link verso determinate funzioni e una lista gestibile di sessioni. Una parte centrale divisa in due: la parte bassa come area di input, ed una parte alta dove vengono mostrati i messaggi da parte del modello e dove vengono proposte le possibili risposte alle domande poste dal modello. Una sidebar di destra dove vengono mostratigli gli artefatti come messaggi, schema-linking, COT ed SQL e dove è possibile visualizzare le COT ed il thinking, se presenti.

Come si può vedere, in buona parte delle volte che il model in ChironeWp3 interagisce con l'utente lo fa in tre modi:

1. lo informa di quanto sta per fare (le domande per togliere ambiquità alla richresta, o gli elementi dello schema-linking che sta per proporgli
2. gli fa la domanda vera e propria, proponendo di selezionare una o più risposte, oppure di inserire un testo libero, o di tornare indietro o di interrompere il processo.
3. gli fa vedere il risultato di un blocco di domande-risposte (intero messaggio disambiguato, intero schema-linking, intero SQL generato, ecc.)

Per ogni tipo di interazione occorre prevedere una specifica forma di widget, ispirata a come fa codex, oppure ZCode o la versione desktop di Claude Code. E ogni output di tipo 3 deve essere correttamente gestito con la parte destra della UI, che deve comparire solo a richiesta, e deve essere possibile salvare ogni output in una pagina separata, con un link che lo riporti alla pagina principale.

In particolare:

• i testi lunghi devono essere inseriti in box con scorrimento orizzontale e verticale
• i markdown devono essere mostrati in modo "mermaid enanced", nel senso che devono avere la formattazione e mostrare eventuali schemi mermaid inclusi nel testo
• gli sql devono essere formattati come codice ed essere presentati in modo colorato, con le liste dei campi delle select espansi in modo orizzontale e con un widget che mi permetta di espandere o collassare le varie parti dello statement SQL

Ovviamente l'interfaccia utente deve permettere la selezione del workspace su cui si vuole operare, che a sua volta permette la determinazione del DB, del VectorDb e della collection associata, delle evidence associate.

La visualizzaione dello schema-link

Lo schema Link richiede una presentazione particolarmente accurata infatti si tratta di presentare un insieme di tabelle correlate tra di loro i campi di queste tabelle selezionati per essere fonte dei dati e il collegamento concettuale che ha portato a scegliere quei campi e quelle tabelle per estrarre le informazioni richieste. Di conseguenza è necessario prevedere una attenta impostazione nella presentazione di queste informazioni per aiutare l'utente a determinare se si tratta di impostazioni corrette o se bisogna applicare delle modifiche per ottenere il migliore dei risultati importante, quindi sarà l'impostazione grafica che dovrà essere data per comunicare queste informazioni includi tra le possibilità l'uso di Mermaid per rappresentare schemi concettuali, ma mantieni sempre l'obiettivo di contenere ad un massimo di 45 elementi da includere nello schema e di sviluppare lo schema in verticale e non in orizzontale per permetterne una maggiore leggibilità

l'visualizzazione dei CTE

I CTE devono essere presentati in modo che sia possibile espandere e collassare le varie parti del CTE, e che sia possibile visualizzare il CTE in modo orizzontale o verticale.

Inoltre per ogni campo incluso nel CTE deve esserci un commento che indica il contenuto atteso nel campo e le motivazioni per cui è stato selezionato

La visualizzazione del SQL Finale

Il seguente finale deve essere presentato in modo che sia leggibile facilmente da parte dell'utente. Quindi tutti i campi delle Select devono essere sviluppati in orizzontale senza preoccuparsi di commentarne il contenuto perché questo è già avvenuto a livello di CTE. Devono essere invece commentati le JOIN le WHERE le HAVING, le ORDER BY e tutti gli altri elementi che sono stati aggiunti a livello di assemblaggio finale

la gestione delle sessioni

Le sessioni devono essere:

• listate e gestite nella sidebar di sinistra
• richiamabili con recupero delll'interezza degli artefatti della sessione richiamata e la possibilità di ripartire da un punto del workflow, modificare le risposte ad una domanda e rifare le fasi terminali del processo

Ogni sessione deve essere evidenziata con un codice autogenerato, l'id github dell'autore, una summary della domanda, la domanda per esteso, u timestamp della data e dell'autore della creazione della sessione, un timestamp con data ed autore dell'ultima modifica.

La presentazione dell'esecuzione del SQL prodotto

L'esecuzione del SQL può produrre un numero, o una lista di elementi presentabili. Nel primo caso il numero deve essere presentato in grassetto, mentre nel secondo caso deve essere usata la libreria AGGrid in versione community per presentare la lista di elementi, con attiva l'opzione di esportazione in csv. Deve essere data la possibilità all'utente di scegliere tra presentare l'intera lista o un estratto di 10 record.

La generazione dei Datamart

Il passo finale previsto dal Workflow deve essere:

• la generazione di un artefatto utile per essere inserito in un processo ETL. Nel MVP sarebbe il dbt da inserire nel processo ETL implementato in Policlinico San Donato.
• la generazione di altro tipo di artefatto secondo indicazioni indicate nei parametri di workspace;
• una lista in formato CSV dei dati estratti, sia con nomi, cognomi ed ID pseudoanonimizzati, sia con anagrafica in chiaro
• lo stesso tipo di lista ma in formato Excel

Gli artifacts e le altre impostazioni di ChironeWp3

Il processo previsto da ThothII si basa, tra le altre cose, sulla presenza di artifacts che comprendono delle Evidence. Prevedere una gestione locale delle evidence, con memorizzazione degi chunk creati e di cui si è fatto l'embedding nel database vettoriale associato al workspace. Ovviamente le evidence devono esssere distinte per workspace.

L'autenticazione

L'applicazione deve prevedere la possibilità di collegarsi via http ad un Identity Manager. Nel MVP deve essere impostata l'autenticazione via Athentik, il quale a sua volta si interfaccia con il sistema di autenticazione del Policlinico San Donato basato su LDAP. Però deve essere anche prevista la possibilità di autenticarsi con un Entra ID. Per cui il sistema deve prevedere la possibilità di collegarsi a più Identity Manager, sostanzialmente tutti OIDC, ma diversi tra loro. Deve però poter operare anche senza autenticazione, sia per facilitare i test e lo sviluppo, sia come condizione potenziale di configurazione anche a sistema sviluppato e ready-for-production