# Guida Utente HumAIn Flow ## Introduzione HumAIn Flow e un'applicazione web per progettare, validare ed eseguire workflow composti da blocchi logici, connessioni dati e dipendenze di esecuzione. L'app supporta due modi principali di lavoro: - costruzione manuale del flow nell'editor visuale - generazione o modifica del flow tramite assistente Una volta creato il flow, puoi salvarlo, controllarne gli errori di validazione ed eseguirlo nel tab `Tasks`. ## Accesso all'applicazione Dopo il login entri nella schermata principale. La barra superiore contiene: - `Editor`: area in cui si progettano i flow - `Tasks`: area in cui si consultano ed eseguono le istanze dei flow - menu utente: operazioni personali come cambio password Se il tuo account ha accesso ad aree aggiuntive, queste compaiono nel menu utente. Questa guida si concentra sull'uso standard dell'editor e delle esecuzioni. ## Struttura generale dell'interfaccia ### Editor Nel tab `Editor` trovi tre aree principali: - pannello sinistro con elenco di `Blocks` e `Containers` - canvas centrale del workflow - pannello destro con `Assistant` ed eventuali `Errors` ### Tasks Nel tab `Tasks` trovi: - lista delle esecuzioni nella colonna sinistra - dettaglio della singola esecuzione nella parte centrale ## Concetti base ### Flow Un flow e la definizione del workflow. Contiene: - blocchi - container - connessioni dati - dipendenze di esecuzione ### Block Un block rappresenta un singolo step del workflow. Alcuni esempi tipici: - blocchi LLM - blocchi di input o output - blocchi di interazione umana - blocchi condizionali ### Container Un container contiene un `subFlow`, cioe un flow annidato. Serve per raggruppare una parte del workflow in un'unita riutilizzabile o piu leggibile. Un container senza `subFlow` e considerato incompleto. ### Connessioni dati Le connessioni standard collegano: - un output sorgente - a un input destinazione Servono per trasferire valori tra nodi. ### Dipendenze di esecuzione Le dipendenze non trasferiscono dati. Impongono solo un ordine di esecuzione. Le label visibili sui nodi sono: - `Depends on`: questo nodo deve aspettare un altro nodo - `Prerequisite of`: questo nodo sblocca l'esecuzione di un altro Usa una dependency quando vuoi garantire l'ordine corretto tra due step, ma senza passare un valore in input. ## Creare un flow manualmente ### 1. Aprire l'editor Vai nel tab `Editor`. Se non hai un flow aperto puoi: - crearne uno nuovo - usare l'assistente per generarlo ### 2. Aggiungere blocchi o container Dal pannello sinistro: - cerca il tipo di blocco o container - trascinalo nel canvas Se il catalogo non e ancora pronto, vedrai un loader al posto del messaggio vuoto. ### 3. Spostare e organizzare i nodi Puoi: - trascinare i nodi nel canvas - selezionare e spostare nodi - clonare un nodo con l'icona di clone - eliminare un nodo con l'icona di delete Quando elimini un nodo, vengono rimosse anche: - le connessioni dati collegate - le dependency edges collegate ### 4. Collegare i nodi Per passare dati: - collega un output a un input Per imporre solo ordine di esecuzione: - collega `Prerequisite of` del nodo sorgente - a `Depends on` del nodo destinazione Le connessioni di dependency sono visualizzate in modo diverso dalle connessioni dati, con linea piu fine e tratteggiata. ### 5. Modificare il nome dei nodi Per i blocchi e i container: - clicca l'icona matita accanto al nome - modifica il nome - conferma con `Save` ### 6. Configurare i parametri Cliccando su un nodo puoi vedere i suoi parametri. Per i campi editabili: - usa il pulsante matita sui parametri - modifica il valore nel dialog - salva Per i testi lunghi: - se il campo e lungo viene troncato - puoi aprirlo per intero con l'icona occhio Nel caso dei subflow in sola lettura, i campi lunghi mantengono comunque l'icona occhio per una lettura completa in readonly. ## Lavorare con i container ### Inserire un subflow Un container puo ricevere un subflow in piu modi: - importando un flow - trascinando dentro una selezione di nodi Quando un subflow viene sostituito: - la configurazione strutturale del container viene ricostruita - i vecchi parametri del subflow precedente non vengono mantenuti ### Importare un flow nel container Se il tipo di container lo supporta: - clicca `Import flow` - scegli il flow disponibile - conferma ### Visualizzare il subflow Se il container contiene un subflow: - compare il pulsante `View Flow` - si apre una finestra di anteprima in sola lettura Da questa vista puoi: - esplorare il subflow - aprire i parametri lunghi in readonly con l'icona occhio ## Parametri obbligatori e validazione locale Se un nodo ha parametri mancanti, compare un indicatore di warning. Per i blocchi il warning mostra i campi obbligatori mancanti. Per i container: - se manca il `subFlow`, viene mostrato solo `Subflow` - non vengono mostrati come mancanti i campi interni del `FlowData` come `Blocks`, `Connections` o `Dependencies` Inoltre i campi tecnici di tipo non vengono mostrati come parametri utente. Questo include campi come: - `type` - `typeName` - `containerType` - `configurationType` - `configurationClass` ## Uso dell'assistente L'assistente si trova nel pannello destro dell'editor. ### Modalita create e refine L'assistente cambia comportamento in base allo stato del flow aperto: - se non c'e nessun flow aperto, oppure il flow aperto e vuoto, l'assistente lavora in modalita `Create` - se il flow aperto contiene gia nodi o connessioni, l'assistente lavora in modalita `Refine` Questo significa che un flow vuoto non blocca la creazione assistita. ### Cosa puoi chiedere all'assistente Esempi tipici: - creare un flow da zero - modificare un flow esistente - spiegare un flow - aiutare a correggere problemi di validazione ### Risultato dell'assistente Quando l'assistente restituisce un draft: - il flow viene caricato nell'editor - puoi continuare a modificarlo manualmente - puoi salvarlo come un flow normale ## Salvataggio del flow Quando lavori nell'editor, il flow puo essere modificato ma non ancora salvato. ### Salvataggio Usa il pulsante `Save` nella toolbar del flow. Il save: - aggiorna il flow sul backend - ricalcola la validazione quando necessario ### Rinominare il flow Il titolo del flow usa azioni esplicite: - `Save` - `Cancel` Non viene piu salvato automaticamente al blur del campo. ## Pannello errori di validazione Nel pannello destro c'e un'icona dedicata agli errori del flow. ### Quando compare L'icona: - e sempre visibile nella rail destra - e disabilitata se non ci sono errori - si attiva quando il flow ha errori di validazione ### Come vengono caricati gli errori Gli errori vengono richiesti dal backend: - dopo il save, se il flow non e `EXECUTABLE` - anche all'apertura di un flow gia `DRAFT` ### Cosa mostra il pannello errori Per ogni errore vengono mostrati: - codice - messaggio leggibile I metadati troppo rumorosi come `entity`, `field` e `id` non vengono mostrati nella card. ### Evidenziazione dei nodi Se l'errore include nodi correlati: - questi nodi vengono evidenziati nel canvas ### Validazione stale Se fai una modifica strutturale senza salvare ancora, il pannello errori mostra un avviso: - `Validation will be recomputed after save.` Gli spostamenti puramente grafici dei nodi non contano come modifica strutturale. ## Published e Finalized Se sei il proprietario del flow puoi vedere due controlli nella toolbar: - `Published` - `Finalized` ### Published Controlla la visibilita del flow. Puoi: - pubblicare - depubblicare ### Finalized Segna il flow come definitivo e non piu modificabile. Una volta finalizzato: - il contenuto del flow diventa read-only - il flow non puo essere un-finalized - il flow non puo essere cancellato - il publish/depublish resta comunque disponibile ## Eseguire un flow Quando un flow e valido ed eseguibile, puoi usare `Execute`. ### Cosa succede al click su Execute L'app: - apre subito il tab `Tasks` - crea l'esecuzione in background - mostra un loader finche la nuova execution non e pronta Questo evita il ritardo percepito prima del cambio tab. ## Lavorare nel tab Tasks Nel tab `Tasks` hai una lista di esecuzioni sulla sinistra e il dettaglio a destra. ### Lista delle esecuzioni Ogni elemento mostra: - nome - stato - data/ora - eventuale badge `Simulated` ### Dettaglio di una esecuzione Nel dettaglio puoi: - vedere il grafo in sola lettura - controllare input richiesti - leggere output e log - eseguire azioni come start, simulate, cancel o resume se disponibili ## Input delle esecuzioni Se un execution step richiede input manuali, li trovi nel pannello dedicato. ### Modalita di salvataggio degli input Gli input non vengono piu inviati automaticamente on blur. Ora il comportamento e: - modifichi il valore - il draft resta locale - premi `Save` per inviarlo Questo vale anche per campi multipli. ## Blocchi Human Interaction I blocchi di interazione umana possono richiedere conferma o inserimento manuale. ### Dialog di interazione Quando il nodo lo richiede, si apre un dialog dedicato. Nel caso non-chat puoi: - confermare l'input corrente - modificare la risposta - inviare con `Send Output` Nel caso chat puoi: - continuare la conversazione - inviare una risposta finale ### Invio reale al backend I pulsanti di invio effettuano una chiamata reale al backend. In particolare: - `Send Output` - `Confirm Input` - invio messaggi chat - invio risposta finale passano attraverso l'endpoint di interaction dell'esecuzione. ## Visualizzazione dei task node Nel viewer di esecuzione: - i container mostrano il pulsante `View Subflow` - le dependency ports vengono mostrate solo se effettivamente connesse - i testi lunghi possono essere aperti in readonly Se un prompt o un parametro contiene placeholder: - quando il valore runtime e disponibile, il preview puo mostrarlo risolto - se il valore non e ancora pronto, il placeholder originale resta visibile ## Output delle esecuzioni Gli output sono raggruppati per nodo. ### Struttura della vista output Per ogni nodo trovi: - titolo del nodo - elenco dei singoli output Se un output supera la lunghezza prevista: - viene troncato - puoi aprirlo interamente con l'icona occhio ### Output array Se la response e un array: - non viene mostrata come blob unico - viene espansa in entry separate, come `Item 1`, `Item 2`, eccetera ## Logs delle esecuzioni Nel tab dei log: - il contenuto scorre automaticamente in basso durante il refresh - viene mostrato il testo leggibile - il blocco JSON raw dei dettagli non viene piu visualizzato ## Caricamento di blocchi, container e schemi ### Catalogo blocchi e container Nel pannello sinistro: - se il catalogo e in caricamento, compare un loader - non viene mostrato `No blocks found` o `No containers found` durante il fetch iniziale ### Caricamento schema del nodo Se clicchi un nodo e lo schema non e ancora disponibile: - il nodo mostra un loader (`Loading block...` o `Loading container...`) - il click puo forzare un retry del caricamento Questo e utile quando i type descriptor arrivano in cache solo dopo il mount del nodo. ## Connessioni e selezione Le connessioni, sia dati sia dependency, possono essere selezionate. Quando una connessione e selezionata: - viene evidenziata - compare l'icona `x` per eliminarla - puoi anche usare `Delete` o `Backspace` Cliccando nel vuoto del canvas: - la connessione viene deselezionata ## Suggerimenti pratici - salva spesso dopo modifiche strutturali - controlla il pannello errori prima di eseguire - usa `Connections` per passare dati e `Dependencies` solo per imporre ordine - usa i container per isolare parti riutilizzabili del flow - se un nodo sembra incompleto, controlla i parametri mancanti prima di eseguire - se un testo e troncato, usa l'icona occhio invece di allargare il nodo ## Problemi comuni ### Vedo un loader invece dei blocchi nella sidebar Il catalogo blocchi o container e ancora in caricamento. Attendi che il backend restituisca i type descriptor. ### Un nodo sembra vuoto quando lo apro Lo schema del tipo potrebbe non essere ancora disponibile. Cliccando il nodo l'app puo ritentare automaticamente il caricamento. ### Un container risulta incompleto Verifica che abbia un `Subflow`. Un container senza subflow viene considerato mancante. ### Il flow resta DRAFT dopo il save Apri il pannello errori di validazione. Il flow puo essere stato salvato ma non essere ancora eseguibile. ### Non vedo una risposta intera nei task Se il valore e lungo o e stato troncato, usa l'icona occhio per aprire il contenuto completo in readonly. ## Conclusione HumAIn Flow permette di lavorare sia in modo visuale sia assistito. Il percorso tipico consigliato e: 1. creare o aprire un flow 2. costruirlo manualmente o con l'assistente 3. salvare 4. correggere eventuali errori di validazione 5. eseguire il flow dal tab `Tasks` 6. monitorare input, output e log fino al completamento Se vuoi distribuire questa guida agli utenti finali, puoi condividerla direttamente come documento markdown oppure convertirla in PDF o pagina documentazione interna.