> For the complete documentation index, see [llms.txt](https://docs.opencityitalia.it/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opencityitalia.it/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/architettura-e-framework.md). # Architettura e framework ## Architettura software Il cuore tecnologico di OpenCity Chatbot AI si basa su un’architettura di tipo RAG (*Retrieval-Augmented Generation*). A differenza dei sistemi basati su sola intelligenza artificiale generica, questo approccio garantisce che ogni risposta sia ancorata esclusivamente a dati certi e verificati. Quando un utente pone una domanda, il flusso di elaborazione segue tre fasi principali: 1. *Retrieval*: la richiesta viene gestita dal componente open source OpenCity AI, che analizza il contenuto della domanda e interroga il motore di ricerca interno per individuare le informazioni specifiche presenti sul sito web dell'Ente; 2. Arricchimento del contesto: il sistema "arricchisce" la domanda dell'utente unendola ai frammenti di testo ufficiali recuperati dal sito. In questa fase, il chatbot ha già la risposta corretta sotto forma di dati grezzi; 3. *Generation*: il pacchetto informativo (domanda + dati ufficiali) viene inviato a un modello linguistico avanzato (LLM) tramite API sicure. In questa fase finale, l'LLM non attinge alla propria conoscenza generica, ma si limita a elaborare in forma di dialogo le informazioni ricevute, restituendo al cittadino una risposta chiara, cortese e precisa. Questa architettura garantisce la massima trasparenza, grazie alla base open source, e la massima affidabilità, poiché separa la fase di "conoscenza" (gestita dai dati comunali) dalla fase di "esposizione" (gestita dall'IA). ## Opensource e neutralità tecnologica OpenCity AI Chatbot è configurato come un modulo completamente autonomo, progettato per essere introdotto nell'ecosistema digitale dell'Ente senza generare vincoli o dipendenze tecnologiche. A differenza di altre soluzioni sul mercato, il sistema garantisce la massima libertà di manovra grazie a due pilastri: * **Nessun prerequisito di piattaforma**: il chatbot è pronto all'uso come **soluzione *****stand-alone***, capace di operare indipendentemente dai software già in dote all'Amministrazione; * **Nessun obbligo di migrazione**: l’Ente non è obbligato a migrare il proprio sito web o a modificare l’attuale infrastruttura digitale per poter beneficiare dell’assistente virtuale. Il sistema si integra sul portale esistente, permettendo all'Ente di evolvere i propri servizi ai cittadini senza dover affrontare i costi e le complessità di un cambio di piattaforma o di un trasloco di contenuti. Questa impostazione garantisce una piena interoperabilità e permette all'Ente di potenziare l'interazione con l'utenza in tempi rapidi, mantenendo intatto l'investimento tecnologico già effettuato sul proprio sito istituzionale. ### Erogazione in SaaS Il servizio viene fornito interamente in modalità SaaS (*Software as a Service*). Questa scelta architettonica è pensata per azzerare l’impatto sull'infrastruttura dell'Ente: essendo una soluzione *cloud* nativa, l'Ente non deve installare alcun software né configurare o gestire server dedicati. ### Agnosticismo rispetto ai modelli di linguaggio (LLM) OpenCity AI **è agnostico rispetto alla soluzione LLM** (*Large Language Model*) adottata, garantendo: * **intercambiabilità dei modelli**: attualmente il sistema utilizza Google Vertex AI, ma l'architettura è predisposta per integrare altri modelli leader di mercato a seconda delle necessità o dell'evoluzione tecnologica; * **sperimentazione**: il nostro team sta attivamente sperimentando l'uso di modelli locali Open Source. ### Ecosistema di plugin e repository L'estensibilità del sistema è garantita da un’architettura modulare che conta attualmente su 8 plugin interamente Open Source, progettati per potenziare le capacità di interazione e integrazione del chatbot. L'attuale configurazione prevede: * **5 plugin sviluppati internamente**: moduli progettati ad hoc dai nostri team per rispondere alle specifiche esigenze verticali della Pubblica Amministrazione italiana; * **3 plugin preesistenti**: componenti selezionati dalla comunità Open Source globale, integrati e ottimizzati per garantire la massima stabilità e interoperabilità. Tutti i moduli, corredati dalla relativa documentazione tecnica, sono descritti nella sezione [Gestione dei Plugin](https://docs.opencityitalia.it/sviluppatori-e-partner-tecnologici/integrazioni/installazione-chatbot/gestione-dei-plugin). ## Framework Il sistema si basa sul framework Open Source [Cheshire Cat AI](https://cheshirecat.ai/) che, tramite il nostro contributo sotto forma di plug-in anche essi Open Source, permette di gestire tutto il flusso delle chat. Le funzionalità del prodotto ci permettono di: * avere sempre a disposizione le [informazioni](/architettura-e-funzionalita-del-chatbot/chatbot-per-la-pa/funzionalita-del-chatbot.md#sincronizzazione-dei-contenuti-e-aggiornamento-dati) del sito web (aggiornate alla mezzanotte del giorno corrente); * mantenere la [privacy](/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/privacy-e-sicurezza-dei-dati.md) degli utenti tramite specifiche funzionalità di anonimizzazione; * mostrare le fonti da cui sono state prese le informazioni; * rifiutare richieste non pertinenti. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.opencityitalia.it/architettura-e-funzionalita-del-chatbot/architettura-e-sicurezza-dei-dati/architettura-e-framework.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.