Oliver — l'assistente AI del sito

Oliver non è un widget di chat generica collegato a un modello. È un agente con un preciso set di responsabilità: risponde a domande su di me e sul mio lavoro, capisce quando un visitatore vuole contattarmi, raccoglie le informazioni necessarie, e invia una notifica su Telegram con tutto il necessario per fissare una call.

L’implementazione è in Python, gira sullo stesso backend FastAPI del sito, e usa RAG per tenere le risposte ancorate a documenti reali — non alla fantasia del modello.

State machine: come cambia il comportamento

La conversazione è guidata da una state machine a 6 stati. In ogni stato Oliver sa cosa fare: che domanda fare, come interpretare la risposta, quando avanzare al prossimo step.

chatting

risponde con RAG

→

booking_name

chiede il nome

→

booking_contact

email o telefono

→

booking_reason

motivo contatto

→

booking_slot

scelta orario

→

done

notifica inviata

chatting

Conversazione libera con RAG

Stato di default. Oliver risponde a qualsiasi domanda usando il retrieval su ChromaDB. Se rileva un’intenzione di contatto (parole chiave come appuntamento, chiamata, prenota, consulenza) transita automaticamente a booking_name.

booking_name

Raccolta nome

Oliver chiede il nome del visitatore. Salva il valore nel contesto della sessione SQLite. Se il visitatore vuole annullare (parole come lascia stare, torna) torna a chatting.

booking_contact

Raccolta email o telefono

Chiede come contattare il visitatore. Il backend valida il formato con regex per email (EMAIL_RE) e numero di telefono (PHONE_RE). Se il visitatore non vuole fornire un contatto, lo step viene saltato.

booking_reason

Raccolta motivo

Chiede brevemente l’argomento o il progetto su cui vuole parlare. Risposta libera, nessuna validazione: tutto quello che scrive viene salvato come nota.

booking_slot

Scelta dello slot

Oliver mostra gli slot disponibili della settimana corrente (generati dinamicamente in base alla disponibilità configurata: lun-gio 08-09, ven 08-09 e 16:30-19:30, sab 08-13). Il visitatore sceglie per numero.

done

Prenotazione completata

La prenotazione viene salvata in SQLite con stato pending e viene inviata una notifica a Nicola su Telegram con tutti i dati. La sessione di booking viene chiusa. Oliver torna disponibile per nuove domande.

Come Oliver sa chi è Nicola

I modelli LLM non sanno nulla di Nicola Silvestre. Per rispondere in modo accurato, Oliver usa RAG: recupera i pezzi di testo più rilevanti da un set di documenti, li inietta nel contesto e poi chiede al modello di rispondere basandosi su quei testi.

Embedding

I documenti .md vengono spezzati in chunk e trasformati in vettori con il modello all-MiniLM-L6-v2 di HuggingFace. Gira in locale, nessuna API esterna necessaria.

Vector store

I vettori sono salvati in ChromaDB su disco. Lightweight, zero configurazione, persistente tra riavvii del backend. Ideale per RAG su documenti piccoli.

Retrieval

A ogni messaggio, la query del visitatore viene convertita in vettore e confrontata con i chunk salvati. I 4 chunk con similarity score più alto vengono passati al modello.

LangChain LCEL

La pipeline usa LangChain 1.x con RunnablePassthrough e StrOutputParser. Il prompt system include il tono definito, le regole e i chunk recuperati dal retriever.

Documenti indicizzati

01-chi-sono

Chi è Nicola Silvestre

Percorso, esperienze lavorative (Cattolica, GDO, PwC, Saffi, FinecoBank), approccio autodidatta al coding e all’AI.

02-progetti

I progetti costruiti

Descrizione dei progetti live: questo sito, Oliver, Fisco Scacco Matto, Hand Vision, ThesisForge.

03-valori

Valori e modo di lavorare

Come Nicola si approccia ai problemi, cosa cerca in una collaborazione, cosa non fa.

04-competenze

Competenze tecniche e contesto

Stack tecnologico, cosa riesce a costruire, limiti dichiarati. Scritto in tono realistico, non da CV.

05-contatti

Come contattare Nicola

Canali disponibili, disponibilità oraria, cosa succede dopo aver prenotato un appuntamento.

06-sito

Come funziona questo sito

Spiegazione ad alto livello dell’architettura: pipeline articoli, news, agente, chatbot. Per rispondere a domande tecniche dei visitatori.

Telegram come backend di notifica

Quando un visitatore completa il flusso di booking, Oliver non invia una email o salva solo un record in un database. Invia un messaggio direttamente a Nicola su Telegram, con tutti i dati raccolti e i pulsanti di risposta rapida.

Notifica

Messaggio automatico a Nicola

Il bot invia nome, contatto, motivo e slot scelto. Il messaggio include anche l’ID prenotazione per poter rispondere con comandi diretti.

Comandi

/conferma e /rifiuta da Telegram

Nicola può rispondere con /conferma [id] o /rifiuta [id] direttamente dalla chat Telegram. Il sistema aggiorna lo stato nel DB e, se implementato, notifica il visitatore.

Agenda

/agenda e /clienti

Altri comandi admin disponibili: /agenda mostra le prenotazioni in sospeso, /clienti mostra la lista dei contatti, /status mostra lo stato del backend.

Protezioni anti-injection

Un chatbot pubblico riceve input non controllato. Senza protezioni, tentativi di prompt injection possono modificare il comportamento del modello. Le difese qui sono semplici ma efficaci.

Limite di lunghezza — 600 caratteri. _sanitize_input() tronca ogni messaggio a 600 caratteri prima di qualsiasi elaborazione. Nessun wall-of-text da iniettare nel contesto.

Pattern matching pre-LLM — 15 pattern IT+EN. _is_injection_attempt() controlla il messaggio contro pattern come ignora le istruzioni, ignore previous, act as, jailbreak, system prompt e altri. Se trova un match, il messaggio non arriva mai al modello.

Risposta fissa per i tentativi rilevati. In caso di injection rilevata, Oliver risponde sempre con la stessa frase neutra: “Sono Oliver, posso rispondere a domande su Nicola o aiutarti a contattarlo.” Nessun feedback su cosa è stato bloccato.

Rate limiting sull’endpoint /chat. slowapi limita le richieste a 10 al minuto per IP. Blocca burst automatici e tentativi di flooding.