================================================================================
TCHAT & OPERATOR SYSTEM DOCUMENTATION
================================================================================
1. INTRODUZIONE
--------------------------------------------------------------------------------
Tchat è una piattaforma integrata di assistenza virtuale guidata da un agente
intelligente denominato Operator ("agente_operator.py"). Il sistema combina
elaborazione del linguaggio naturale, analisi di dati e media, integrazione con
servizi web (come ricerca, meteo, prenotazioni viaggi e PayPal) e capacità di
esecuzione di codice in un ambiente protetto.
L'architettura è progettata per essere modulare, permettendo l'estensione delle
capacità dell'agente tramite script dedicati, database JSON locali e un corpus
di conoscenza strutturato.
2. ARCHITETTURA E COMPONENTI PRINCIPALI
--------------------------------------------------------------------------------
Il sistema si compone dei seguenti moduli e file chiave:
* app.py
Punto di ingresso principale dell'applicazione (Web/API server). Gestisce il
routing delle richieste utente, l'inizializzazione della sessione di chat e
l'interfaccia principale per le interazioni con Tchat.
* agente_operator.py
Il motore logico centrale di Tchat. Riceve gli input dell'utente, interpreta
l'intento, coordina le chiamate ai vari strumenti/script secondari e genera
le risposte finali.
* approfondimento.py
Modulo dedicato alla generazione di spiegazioni dettagliate, analisi approfondite
e risposte estese su argomenti complessi richiesti dall'utente.
* analizza_media.py
Strumento di elaborazione e analisi multimodale. Permette di analizzare,
estrarre testo e interpretare contenuto da immagini, file audio o allegati.
* corpus.txt & embeddings.npy
La base di conoscenza (RAG) di Tchat. "corpus.txt" contiene le informazioni
di contesto e i dati documentali, mentre "embeddings.npy" contiene le
rappresentazioni vettoriali pre-calcolate per consentire una ricerca semantica
rapida ed efficiente.
* admin.py
Interfaccia e strumenti di amministrazione per la gestione dei parametri di
sistema, controllo degli accessi e monitoraggio dello stato operativo.
3. FUNZIONALITÀ E MODULI SPECIFICI
--------------------------------------------------------------------------------
A. MODULO VIAGGI E PRENOTAZIONI (Booking & Travel)
* booking_operator.py: Orchestratore per la ricerca, comparazione e gestione
delle offerte di viaggio, voli e alloggi.
* booking_viaggi.py: Gestione dettagliata degli itinerari, calcolo percorsi,
preferenze di viaggio e integrazione API per strutture ricettive.
* booking_embed.py: Modulo per l'integrazione di widget e interfacce di
prenotazione all'interno della chat.
B. SISTEMA AMMINISTRATIVO E STATO (JSON Databases)
* admin_stato.json: Memorizza lo stato corrente del sistema, flag operativi e
configurazioni dinamiche.
* admin_messaggi.json: Registro dei messaggi di sistema, log di amministrazione
e notifiche di servizio.
* admin_richieste_chat.json: Coda e storico delle richieste chat in arrivo,
utilizzato per la gestione dei flussi e il controllo accessi.
C. INTEGRAZIONE CON SERVIZI ESTERNI & CONFIGURAZIONE
* .env: File di configurazione per la memorizzazione sicura delle variabili
d'ambiente, chiavi API e credenziali di accesso ai servizi esterni.
* README_PAYPAL.md: Documentazione specifica per la configurazione e l'uso
delle integrazioni di pagamento tramite PayPal.
4. CAPACITÀ OPERATIVE DI TCHAT
--------------------------------------------------------------------------------
* Conversazione e Assistenza Personale: Risposte a quesiti generali, supporto
nella scrittura, riassunto di testi e traduzione automatica.
* Elaborazione Dati e File: Generazione ed esportazione autonoma di file (PDF,
Excel XLSX, CSV, documenti Word) e calcolo/analisi tramite ambienti di
esecuzione Python.
* Ricerca Semantica (RAG): Recupero intelligente delle informazioni contestuali
sfruttando gli embeddings vettoriali.
* Pianificazione Viaggi: Gestione end-to-end della ricerca e organizzazione di
itinerari turistico-aziendali.
* Integrazione e Automazione: Interazione con form, moduli di pagamento ed
estensioni di sistema via script personalizzati.
================================================================================