netgescon-day0/docs/support/INTEGRAZIONE-KB-ORCHESTRATOR-53.md

Integrazione knowledge base e orchestrator su .53

Scopo

Questo runbook serve a integrare sulla macchina 192.168.0.53 una memoria condivisa piu strutturata, partendo da due progetti open source gia individuati:

• knowledge-base-server
• agent-orchestrator

L obiettivo non e sostituire il repository Day0 o Gitea.

L obiettivo e aggiungere sopra il flusso gia esistente un livello di retrieval e coordinamento agent che renda piu facile:

• recuperare decisioni, fix e runbook senza ricostruire il contesto a mano
• condividere la stessa base di conoscenza tra agent diversi e macchine diverse
• usare .53 come nodo centrale non solo Git, ma anche come cervello operativo condiviso

Stato di partenza confermato

• il repository autorevole resta netgescon-day0
• il remote autorevole resta origin -> ssh://git@192.168.0.53:2222/michele/netgescon-day0.git
• docs/ resta la memoria operativa ufficiale del progetto
• .53 e gia il nodo centrale piu naturale per Gitea e coordinamento rete
• knowledge-base-server sulla .53 e gia installato, avviato e raggiungibile su http://192.168.0.53:3838
• l health endpoint operativo e http://192.168.0.53:3838/api/v1/health
• l orchestrator non va centralizzato sulla .53: la scelta confermata e orchestrator locale per macchina/progetto

Topologia confermata

• .53 = KB centrale + Gitea + nodo conoscenza condivisa
• .200 = orchestrator locale per NetGescon
• .205 = orchestrator locale per NetLabel

Questa separazione e importante:

• la .53 non deve diventare il terminale unico che esegue tutti i task agent
• la .53 deve restare il centro di conoscenza, retrieval e coordinamento
• le macchine progetto eseguono i task locali interrogando il KB centrale

Ruoli dei tre livelli

1. Git e Gitea

Restano la fonte di verita per:

• codice
• documentazione ufficiale in docs/
• cronologia versionata
• distribuzione verso staging e altri nodi

Regola:

• se una cosa deve essere ufficiale, auditabile e versionata, deve vivere prima in Day0 e poi su Gitea

2. Knowledge Base Server

Va usato come layer di indicizzazione, ricerca e memoria operativa sopra il materiale ufficiale.

Ruolo atteso:

• indicizzare docs/, runbook, note operative e materiale di scambio selezionato
• catturare sessioni, fix, decisioni e lezioni apprese
• servire contesto a piu agent via MCP o REST
• dare retrieval piu rapido di file lunghi o dispersi

Regola:

• il KB non sostituisce Git
• il KB accelera ricerca, richiamo e sintesi della conoscenza gia validata o da promuovere

3. Agent Orchestrator

Va trattato come livello di coordinamento runtime tra agent diversi.

Ruolo atteso:

• scegliere quale agent usare per pianificazione, implementazione, review o documentazione
• fare failover quando un agent e fermo o limitato
• interrogare il KB prima di rispondere

Regola:

• l orchestrator non deve inventare stato proprio fuori da Git e KB
• task, prompt e output rilevanti devono ricadere in docs/ o nel KB, non restare solo nel terminale

Architettura minima consigliata per NetGescon

Day0 workspace -> Git commit -> Gitea su .53
                      |
                      +-> docs/ e runbook ufficiali

Gitea / mirror docs -> Knowledge Base Server su .53
                      |
                      +-> ricerca BM25/semantica
                      +-> MCP / REST
                      +-> capture session/fix/decision

Agent Orchestrator -> Claude / Codex / Gemini
                      |
                      +-> query al KB prima del lavoro
                      +-> esecuzione per ruolo
                      +-> ritorno dei risultati su docs/Git

Decisione operativa importante

Per NetGescon il punto di verita deve restare doppio ma ordinato:

1. docs/ e Git per la conoscenza ufficiale e condivisa
2. KB server per retrieval, sintesi, memoria calda e cattura operativa

Questa distinzione evita il problema principale:

• se il KB diventa l unico posto dove vivere, perdiamo auditabilita Git
• se tutto resta solo in Markdown senza retrieval, la conoscenza cresce ma diventa difficile da usare

Cosa ingestire per primi

Prima fase consigliata sulla .53:

1. docs/README.md
2. docs/00-INDICE-LAVORO-DISTRIBUITO.md
3. docs/support/
4. scripts/ai/ solo per gli script realmente in uso
5. eventuale materiale in Scambio/ o share SMB solo dopo selezione minima

Regola di igiene:

• non ingestire tutta la share di rete in blocco al primo passaggio
• prima selezionare i file che contengono runbook, analisi, handoff o specifiche utili
• escludere dump rumorosi, duplicati, export casuali o file binari non classificati

Cosa NON fare nella prima fase

• non duplicare tutto il repository applicativo dentro il KB senza criterio
• non usare il KB come archivio cieco di qualsiasi file di scambio
• non lasciare che sessioni agent importanti restino solo nel KB se richiedono una traccia ufficiale in docs/
• non installare l orchestrator con permessi troppo larghi su una macchina non ancora considerata trusted per automazione completa

Modello operativo pratico

Fase A - bootstrap della conoscenza

Obiettivo:

• portare nel KB solo la base operativa che oggi e gia stabile

Checklist:

1. usare la .53 come endpoint KB centrale gia disponibile, senza duplicare un secondo KB altrove
2. creare o confermare un path sorgente chiaro per il mirror docs su .53
3. ingestire la base docs/ minima e verificare le prime query
4. mantenere credenziali e API key operative fuori dal repository versionato

Fase B - cattura delle sessioni utili

Obiettivo:

• iniziare a registrare fix, decisioni e handoff tecnici in modo coerente

Checklist:

1. definire convenzione minima per session, fix, decision, runbook
2. stabilire quali output devono finire prima in docs/ e quali possono restare solo nel KB
3. collegare le note piu utili al progetto o stream corretto

Fase C - orchestrazione multi-agent

Obiettivo:

• usare l orchestrator per lavorare su task distinti con retrieval automatico dal KB

Checklist:

1. installare l orchestrator locale sulla macchina progetto, non sulla .53
2. definire almeno 4 ruoli: orchestrator, implementation, review, uidocs
3. definire una radice task condivisa coerente con NetGescon
4. verificare che ogni task richiami sempre il KB centrale .53

Nota pratica sul pacchetto scelto:

• per il rollout attuale e stato indicato il pacchetto PyPI agent-orchestrator con repository https://github.com/luhfilho/agent-orchestrator
• questo upstream dichiara come prerequisiti Claude e Gemini
• in pratica possiamo comunque avviare il setup macchina e il primo bootstrap anche con il solo Gemini gia autenticato
• la parte dual-agent completa e il test di tutti gli agent richiedono anche Claude

Regola operativa consigliata:

1. installare subito agent-orchestrator
2. collegare subito Gemini se l autenticazione Google e gia disponibile
3. aggiungere Claude quando sara disponibile un account Anthropic compatibile con Claude Code

Nota sui comandi CLI:

• per Gemini il pacchetto npm corretto e @google/gemini-cli
• per Claude usare il pacchetto ufficiale @anthropic-ai/claude-code oppure l installer ufficiale Anthropic
• evitare sudo npm install -g per Claude Code

Collegamento con il materiale SMB scambio/200

Lo share SMB puo diventare sorgente di materiale grezzo o semilavorato, ma non va trattato subito come fonte autorevole.

Uso corretto:

• inbox tecnica
• handoff tra macchine
• allegati da promuovere
• materiale esterno da classificare e sintetizzare

Uso scorretto:

• sostituire docs/
• sostituire Git
• lasciare file importanti solo nello share senza promozione in docs/ o KB

Path confermati per .200

Path logici confermati per la macchina .200:

• percorso logico share: //192.168.0.53/Scambio/200
• percorso workspace centrale dichiarato: /home/michele/netgescon-git/Scambio/200

Regola pratica:

• docs/ resta il patrimonio tecnico di progetto
• Scambio/200 resta area operativa, inbox tecnica, handoff rapido e materiale di avvio macchina
• dopo registrazione chiave macchina, il workspace quotidiano puo essere spostato da SMB guest a mount SSHFS fidati verso .53

Risposte operative confermate

Priorita architetturale

1. il knowledge-base-server sulla .53 e gia attivo e va considerato il KB centrale di rete
2. l agent-orchestrator va tenuto locale alla macchina/progetto: .200 per NetGescon, .205 per NetLabel
3. il KB va usato prima di tutto come cervello condiviso per agent, ma puo restare anche dashboard umana consultabile

Sorgenti da ingestire

1. per .200 il riferimento dichiarato e //192.168.0.53/Scambio/200, con workspace centrale /home/michele/netgescon-git/Scambio/200
2. le prime priorita non sono cartelle generiche ma documenti operativi mirati dentro Scambio/200
3. in prima fase conviene promuovere documentazione, istruzioni macchina, handoff e runbook; il materiale piu grezzo va selezionato prima della promozione

Modello di conoscenza

1. docs/ e la sorgente primaria; Scambio/ e inbox tecnica e area handoff
2. la tassonomia minima va trattata almeno come runbook, fix, decision, roadmap, handoff, ricerca
3. la separazione per stream va introdotta subito almeno a livello logico

Stream iniziali confermati

1. core-anagrafica
2. immobili-unita-import
3. ticket-operativita
4. banca-contabilita-fe
5. aggiornamenti-distribuzione
6. api-moduli-integrazioni
7. netlabel-etichette
8. netlabel-waba-webhook
9. pbx-telefonia
10. infrastruttura-gitea-dns-edge-kb

Documenti prioritari iniziali in Scambio/200

Per .200 i primi documenti da promuovere o usare come bootstrap sono:

1. ISTRUZIONI_AGENT_200_NETGESCON.md
2. ACCESSO_KB_CENTRALE_DA_200.md
3. PRIMO_CANTIERE_200_STABILIZZAZIONE_E_CONDIVISIONE.md
4. PROPOSTA_CATTURA_AUTOMATICA_DA_200.md
5. RISPOSTE_AGENT_200_KB_ORCHESTRATOR_E_ACCESSO.md

Nota:

• eventuali token, API key o credenziali presenti nei documenti di scambio non vanno riportati in docs/ versionato
• in docs/ va riportata la procedura, non il segreto operativo

Primo criterio di successo

Questo cantiere puo dirsi avviato bene quando sulla .53 otteniamo insieme questi risultati minimi:

1. il KB server indicizza almeno i file base di docs/
2. una query dal KB trova correttamente i runbook su .53, Gitea e docs distribuite
3. l orchestrator o un agent singolo riesce a leggere quel contesto prima di lavorare
4. almeno un esito operativo viene riportato sia nel KB sia nel repository Day0

Prossimo passo consigliato

Il prossimo passo pratico per .200 e questo:

1. verificare l accesso dal client .200 al KB centrale .53
2. installare l orchestrator locale sulla .200
3. configurarlo per usare il KB centrale .53
4. promuovere nel KB i cinque documenti bootstrap di Scambio/200
5. partire dal primo stream core-anagrafica, poi ticket-operativita, poi banca-contabilita-fe

Script di bootstrap replicabile

Per rendere il setup riusabile sulle altre macchine e disponibile uno script locale:

• scripts/ops/netgescon-client-kb-bootstrap.sh

Scopo:

• verificare trust SSH verso .53
• montare Documenti condivisi, Progetti e Scambio via SSHFS
• creare un workspace locale basato su symlink verso i mount fidati
• verificare KB health e, se presente NETGESCON_KB_API_KEY, anche una query reale
• installare opzionalmente agent-orchestrator in una virtualenv locale senza dipendere da pipx

Uso minimo:

NETGESCON_KB_API_KEY='...' scripts/ops/netgescon-client-kb-bootstrap.sh --client-id 200 --install-orchestrator

Per altre macchine basta cambiare --client-id, per esempio 205.