Docs/Componenti del Progetto

# Componenti del Progetto

Questa sezione documenta i principali componenti del codebase.

Agent (`agent/`)

Agent (`agent/agent.py`)

Classe principale che orchestra l'intero sistema conversazionale.

Metodi principali:

python
class Agent:
    def __init__(self):
        # Inizializza l'agent con i percorsi ai modelli e knowledge base
        
    def load_models(self):
        # Carica FastText e modello Intent Classifier
        
    def load_knowledge(self):
        # Carica rules e responses dalla knowledge base
        
    def predict(self, text):
        # Predice intent ed entità da un testo
        # Returns: dict con intent, confidence, entities
        
    def get_response(self, intent_name, slots):
        # Genera risposta basata su intent e slot
        
    def chat(self):
        # Avvia loop conversazionale interattivo

Session Manager (`agent/session_manager.py`)

Gestisce le sessioni conversazionali utilizzando il pattern Singleton.

Classe: ConversationSession

python
@dataclass
class ConversationSession:
    session_id: str
    created_at: datetime
    updated_at: datetime
    history: list
    context: dict
    metadata: dict
    waiting_for_slot: dict | None

Classe: SessionManager

python
class SessionManager:
    def create_session(self, user_id=None, metadata=None) -> str
    def get_session(self, session_id) -> ConversationSession
    def delete_session(self, session_id) -> bool
    def get_active_sessions(self) -> list

Answer Manager (`agent/answer_manager.py`)

Gestisce la generazione delle risposte basata su regole.

python
class AnswerManager:
    def resolve(self, intent: str, slots: dict) -> dict
    def get_response(self, intent: str, slots: dict, responses: dict) -> tuple[str, str | None]

Operatori supportati:

  • eq: Uguale
  • neq: Non uguale
  • gt: Maggiore di
  • lt: Minore di
  • contains: Contiene
  • filled: Slot valorizzato
  • not_filled: Slot non valorizzato

Entity Manager (`agent/entity_manager.py`)

Gestisce le entità estratte dalla conversazione.

API (`api/`)

Auth (`api/auth.py`)

Endpoint per l'autenticazione JWT.

python
@router.post("/token")
def login(form_data: OAuth2PasswordRequestForm = Depends()):
    # Restituisce JWT token

Chatbot (`api/chatbot.py`)

Endpoint per l'invio di messaggi.

python
@router.post("/message")
def send_message(chat_message: ChatMessage, current_user: User = Depends(get_current_user)):
    # Restituisce risposta del chatbot

Intellective (`intellective/`)

Intent Classifier (`intellective/intent_classifier.py`)

Modello PyTorch che combina classificazione intenti e NER.

Architettura:

  • Embedding Layer (pre-addestrato con skip-gram interno o FastText, secondo USE_FASTTEXT)
  • BiGRU (bidirezionale)
  • Attention Layer
  • FC Layer per classificazione
  • CRF Layer per NER
python
class IntentClassifier(nn.Module):
    def __init__(self, vocab_size, embed_dim, hidden_dim, output_dim, 
                 dropout_prob, fasttext_model_path, num_ner_tags=None, 
                 freeze_embeddings=False)
    
    def forward(self, x, ner_tags=None, mask=None) -> tuple
    def predict(self, text) -> dict
    def _extract_entities(self, tokens, ner_tags) -> list

Training (`intellective/train_intent_classifier.py`)

Script per l'addestramento del classificatore.

python
class IntentDataset(Dataset):
    def __getitem__(self, idx) -> tuple

def collate_fn(batch) -> tuple
def train_model(model, dataloader, epochs, lr, device) -> None
def train_main_model() -> None

Embedding Training (`intellective/train_own_embedder.py`)

Default (USE_FASTTEXT=false): skip-gram + negative sampling su vocabolario SentencePiece.

FastText Training (`intellective/train_fast_text.py`)

Alternativa opzionale (USE_FASTTEXT=true): addestramento del modello FastText.

Doping Preprocessor (`intellective/doping_preprocessor.py`)

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

Classes (`classes/`)

Simple Tokenizer (`classes/simple_tokenizer.py`)

Tokenizer per l'embedding attivo (FastText o SentencePiece, vedi config.USE_FASTTEXT).

NER Tag Builder (`classes/ner_tag_builder.py`)

Gestisce i tag NER in formato BIO.

NER Markup Parser (`classes/ner_markup_parser.py`)

Parser per le annotazioni NER nel formato [testo](TIPOLOGIA).

Dataset Generator (`classes/dataset_generator.py`)

Genera dataset di training.

Intent Normalizer (`classes/intent_normalizer.py`)

Normalizza gli intenti per il training.

Pipeline (`pipeline/`)

Pipeline Principale (`pipeline/__main__.py`)

python
def run_full_pipeline():
    # Esegue tutti gli step di training

Intent Builder (`pipeline/intent_builder.py`)

Costruisce i dati di training dagli intenti.

Merge Data (`pipeline/merge_data.py`)

Unisce dati da diverse fonti.

Validator (`pipeline/validator.py`)

Valida intenti ed entità NER (duplicati, esempi ripetuti) su knowledge/ e training_data/.

Modelli

Modelli Addestrati

  • models/dialogue_policy.pth: Modello PyTorch della Dialogue Policy
  • models/fasttext_model.bin: Modello FastText (solo con USE_FASTTEXT=true)
  • models/intent_model_fast.pth: Modello PyTorch per classificazione intenti

Dati

  • .cognitor/intent_dict.json: Dizionario intenti
  • .cognitor/tokenized_data.npy: Dati tokenizzati
  • .cognitor/fast-text.txt: Corpus per l'addestramento dell'embedding
  • .cognitor/sentencepiece.model: Vocabolario SentencePiece (default)
  • .cognitor/vocab.json, .cognitor/wordvectors.vec: Vocabolario e vettori dell'embedding