Docs/Architettura del Sistema

# Architettura del Sistema

Panoramica

Cognitor Assistant è un assistente virtuale che utilizza tecniche di NLP avanzate per comprendere gli intenti degli utenti ed estrarre entità significative dalle loro query.

Stack Tecnologico

  • PyTorch: Framework per il deep learning
  • FastText: Per word embeddings
  • FastAPI: Web framework per l'API REST
  • CRF (Conditional Random Fields): Per il riconoscimento delle entità

Architettura dei Modelli

1. FastText (Word Embeddings)

Modello Skip-gram per generare rappresentazioni vettoriali delle parole.

Parametri:

  • dim=300: Dimensione degli embeddings
  • epoch=20: Numero di epoche di training
  • lr=0.1: Learning rate
  • minCount=3: Frequenza minima delle parole
  • wordNgrams=2: N-grammi

Input: File di testo (data/fast-text.txt)

Output: models/fasttext_model.bin

2. Intent Classifier (PyTorch)

Rete neurale BiGRU con Attention per la classificazione degli intenti.

Architettura:

  • Embedding layer inizializzato con FastText (300 dimensioni)
  • BiGRU bidirezionale (hidden_dim=256)
  • Attention layer per focalizzarsi sulle parti rilevanti della sequenza
  • Dropout (0.3) per prevenire overfitting
  • Linear layer per classificazione finale
  • Branch NER con CRF per il riconoscimento delle entità

3. NER (Named Entity Recognition)

Utilizza un layer CRF (Conditional Random Field) per la segmentazione delle entità in formato BIO.

Flusso di Elaborazione

Utente → Tokenizzazione → FastText Embedding → BiGRU → Attention → Classificazione Intent
                                              ↓
                                           NER-CRF → Estrazione Entità
                                              ↓
Intent + Entità → Rule Engine → Answer Manager → Risposta

Componenti Principali

Agent (`agent/agent.py`)

Classe principale che orchestra l'intera conversazione:

  • Carica i modelli (FastText, Intent Classifier)
  • Carica la knowledge base (rules, responses)
  • Gestisce il loop di conversazione
  • Gestisce il "doping" dell'input per migliorare il riconoscimento

Session Manager (`agent/session_manager.py`)

Gestisce le sessioni conversazionali:

  • Creazione/eliminazione sessioni
  • Mantenimento del contesto conversazionale
  • Gestione slot (informazioni mancanti)
  • Timeout sessioni (default: 3600 secondi)

Answer Manager (`agent/answer_manager.py`)

Gestisce la generazione delle risposte:

  • Risolve le regole in base agli slot
  • Supporta condizioni complesse (eq, neq, gt, lt, contains)
  • Seleziona casualmente tra risposte multiple

Intent Classifier (`intellective/intent_classifier.py`)

Modello PyTorch che combina:

  • Classificazione intenti
  • Estrazione entità NER
  • Attention mechanism

Gestione delle Sessioni

Il sistema utilizza un singleton SessionManager che:

  • Mantiene un dizionario di sessioni attive
  • Cleanup automatico delle sessioni vecchie
  • Limite massimo di 1000 sessioni simultanee

Doping Preprocessor

Sistema per migliorare il riconoscimento degli intenti aggiungendo informazioni contestuali all'input.

Knowledge Base

Struttura gerarchica:

  • Intents: Definizioni degli intenti con esempi
  • Rules: Mappatura intent → risposte con condizioni
  • Responses: Template delle risposte

Design Patterns Utilizzati

  1. Singleton: Per SessionManager
  2. Factory: Per la creazione dei modelli
  3. Strategy: Per diversi tipi di risposte
  4. Observer: Per la gestione degli eventi conversazionali