Tool di Cheshire Cat: cosa sono e come crearne uno

I tool sono uno degli strumenti fondamentali per personalizzare il nostro Cheshire Cat, una piattaforma avanzata per lo sviluppo di assistenti virtuali intelligenti. Una delle sue caratteristiche più distintive è la capacità di estendere le funzionalità e integrare servizi di terze parti tramite plugin, permettendo agli sviluppatori di implementare funzionalità su misura. Uno di questi strumenti sono i tool, definiti dal decoratore @tool.

I decoratori in Python consentono di modificare in modo elegante e riutilizzabile il comportamento di funzioni e metodi esistenti.

In questo articolo, forniremo una breve descrizione dei decoratori e successivamente ci concentreremo sui tool di Cheshire Cat, spiegando come crearne uno da zero.

Se non si è ancora messo in funzione il framework, il primo passo è installare Cheshire Cat sul PC: solo con un’istanza attiva è possibile testare i tool che costruiremo.

Cosa sono i Decoratori in Python?

In Python, un decoratore è una funzione che consente di modificare il comportamento di altre funzioni o metodi. Funziona avvolgendo la funzione originale in un’altra funzione, aggiungendo o modificando il suo comportamento prima e dopo l’esecuzione dell’originale, senza alterare direttamente il suo codice.

Questo approccio risulta particolarmente utile per implementare funzionalità in modo pulito e riutilizzabile, quali la registrazione di log, la misurazione delle prestazioni, l’autenticazione e molto altro.

Esempio Pratico di un Decoratore Python

Per illustrare meglio il concetto, vediamo un esempio di decoratore che misura il tempo di esecuzione di qualsiasi funzione:

import time

def timer(func):
    """Decorator that measures the execution time of a function."""
    def wrapper(*args, **kwargs):
        start_time = time.time()
        result = func(*args, **kwargs)
        end_time = time.time()
        print(f"Esecuzione di {func.__name__} completata in {end_time - start_time} secondi.")
        return result
    return wrapper

@timer
def fetch_data():
    """Simula il recupero di dati con un ritardo."""
    time.sleep(2)
    return "Dati recuperati"

# Utilizzo del decoratore
fetch_data()

In questo scenario, il decoratore timer avvolge la funzione fetch_data, aggiungendo la registrazione del tempo impiegato per la sua esecuzione. Questo esempio dimostra come i decoratori possono essere utilizzati per aggiungere facilmente funzionalità trasversali senza modificare il codice originale della funzione.

I tool possono essere pensati come comandi che vengono inseriti nel prompt per il modello di linguaggio (LLM), che poi seleziona e attiva la funzione corrispondente del tool. Questo processo consente di estendere le capacità dell’assistente virtuale, permettendo una personalizzazione profonda e dinamica delle sue risposte in base alle esigenze specifiche dell’utente.

Ecco come funziona in dettaglio:

1. Interazione Utente: L’utente inserisce una richiesta o una domanda che viene interpretata dal sistema.
2. Valutazione del LLM: Il modello di linguaggio valuta la richiesta dell’utente e determina se è necessario utilizzare un tool specifico per rispondere in modo adeguato. Questa decisione si basa su come i tool sono stati descritti e configurati all’interno del sistema.
3. Selezione del Tool: Se il LLM decide che l’uso di un tool è appropriato, seleziona il tool più adeguato in base alle parole chiave, al contesto della richiesta, e alle specificazioni dei tool disponibili.
4. Esecuzione del Tool: Una volta selezionato, il tool viene eseguito. I tool sono funzioni Python, marcate con il decoratore @tool, che eseguono codice specifico per fornire la risposta o eseguire l’azione richiesta.
5. Ritorno della Risposta: Il risultato dell’esecuzione del tool viene poi passato indietro al LLM, che lo utilizza per formulare la risposta finale da presentare all’utente.
6. Interazione Finale: La risposta elaborata dal tool viene presentata all’utente come parte della conversazione.

Un esempio specifico di questo processo può essere visto in un tool che fornisce l’orario attuale. Se un utente chiede “Che ore sono?”, il sistema può attivare automaticamente un tool configurato per rispondere a questa domanda. Il tool esegue il codice per ottenere l’orario attuale e il risultato viene quindi utilizzato dal LLM per formulare una risposta all’utente.

Esempio di un tool per il Cheshire Cat

Qui potete trovare il codice di un semplice plugin che offre una curiosità per ogni numero che viene richiesto. Il servizio è http://numbersapi.com/.

Inizialmente, importiamo i moduli necessari. Importiamo tool da cat.mad_hatter.decorators, che è il decoratore utilizzato per marcare una funzione come un tool utilizzabile dal Cheshire Cat.

Importiamo anche requests, una libreria Python che permette di effettuare richieste HTTP, che utilizziamo per interrogare l’API NumbersAPI.

from cat.mad_hatter.decorators import plugin, hook, tool
import requests

Successivamente, definiamo la funzione fetch_number_fact e applichiamo il decoratore @tool sopra di essa. Questo decoratore indica al Cheshire Cat che la funzione è un tool e verrà passata all’LLM che valuterà se attivarla oppure no.

La funzione prende due parametri: number, che rappresenta il numero su cui l’utente vuole ottenere informazioni, e cat, che è un oggetto rappresentante l’istanza corrente del Cheshire Cat.

@tool
def fetch_number_fact(number, cat):
    """Quando l'utente chiede una curiosità su un numero, usa questa funzione"""
    url = f"http://numbersapi.com/{number}"
    response = requests.get(url)
    data = response.text

All’interno della funzione, costruiamo un URL utilizzando il numero chiesto dall’utente (url = f"http://numbersapi.com/{number}").

Utilizziamo requests.get(url) per effettuare una richiesta HTTP GET a questo URL. La risposta viene salvata come testo nella variabile data.

    if response.status_code == 200:
        return f"Se l'utente come input ha chiesto qualche curiosità, o cosa pensi di un numero, tu usa questa risposta articolandola: {data}"
    else:
        return "Mi spiace ma non ho trovato nessuna curiosità su questo numero"

Controlliamo quindi lo stato della risposta HTTP. Se il codice di stato è 200, significa che la richiesta è andata a buon fine e il tool restituisce un messaggio contenente il fatto numerico recuperato, formattato la risposta che diventerà una nuova istruzione da passare al large language model.

Le risposte del Cheshire Cat

Come potete vedere ora il chatbot risponde con una curiosità legata al numero che gli abbiamo chiesto.

Questo è solo un esempio molto semplice di come con poche righe di codice si possa andare a sfruttare servizi di terze parti e integrarli nel nostro chatbot.

Se siete interessati al Cheshire Cat o avete bisogno di assistenza per la scrittura dei vostri plugin, per implementarlo in produzione o per costruirvi il vostro chatbot aziendale contattateci.

Codice completo del plugin

from cat.mad_hatter.decorators import tool
import requests

@tool
def fetch_number_fact(number, cat):
    """Quando l'utente chiede una curiosità su un numero, usa questa funzione"""
    url = f"http://numbersapi.com/{number}"
    response = requests.get(url)
    data = response.text  # NumbersAPI returns plain text responses
    
    if response.status_code == 200:
        return f"Se l'utente come input ha chiesto qualche curiosità, o cosa pensi di un numero, tu usa questa risposta articolandola: {data}"
    else:
        return "Mi spiace ma non ho trovato nessuna curiosità su questo numero"