Creare un plugin per Cheshire Cat

Il progetto Cheshire Cat creato da Piero Savastano, creato poco più di un anno fa, sta crescendo rapidamente e insieme a lui anche le funzionalità: vediamo come estendere i superpoteri dello Stregatto attraverso il concetto di plugin.

Se non conosci il progetto, leggi questo articolo per recuperare in meno di 4 minuti di cosa parliamo!

Cos’è un plugin

I plugin sono estensioni che lo Stregatto permette di aggiungere alle sue funzionalità di base per estenderne i superpoteri. In altre parole, possono essere considerate delle librerie esterne, sviluppate in Python, che è possibile “agganciare” al core dello Stregatto per aumentare le sue potenzialità.

Come creare un plugin

Il primo step è quello di clonare il template messo a disposizione dal progetto in una cartella locale e seguire le istruzioni presenti nel README.md.

Una volta fatto, ci troveremo una struttura simile alla seguente:

Ci sono diversi file con cui lavorare: requirements.txt permette di specificare eventuali librerie esterne che il nostro plugin dovrà utilizzare, e qui non c’è limite alla fantasia!

Inoltre, il file plugin.json ci permette di aggiungere dei metadati che possano rappresentare il plugin che andremo a creare. Questi dati saranno utilizzati anche all’interno dell’elenco dei plugin dell’istanza del gattone per mostrare il nome o chi ha creato il plugin.

Invece, il file principale in cui aggiungere la logica del plugin è my_plugin.py: quando il gattone riceverà un input dall’utente, cercherà all’interno dei plugin se ce n’è uno che risponde alle esigenze dell’utente e sfrutterà i suoi tools e hooks per agire di conseguenza.

Cos’è un tool

Semplice: sono delle funzioni Python invocate dal LLM per eseguire delle azioni.

Ad esempio, se avessimo un plugin che ci conta il numero di vocali in una data frase, potremmo avere una funzione di questo tipo:

@tool
def count_vowels(sentence, cat):
    """How many vowels has this sentence? Input is the sentence."""
    
    counter = 0
    for char in sentence:
      if char in ['a', 'e', 'i', 'o', 'u']:
        counter += 1
    return counter

I tool vengono riconosciuti dal LLM come tali grazie al decorator ‘@tool’ all’inizio della funzione. Anche la docstring è fondamentale: serve al LLM per comprendere qual è il contesto entro il quale deve agire e cosa aspettarsi.

Il parametro sentence permette di utilizzare l’input dell’utente per eseguire l’azione specificata nella funzione.

Il resto, è banale codice Python: con un ciclo for, andiamo ad esplorare carattere per carattere la frase e andiamo a verificare quanti di questi siano vocali.

Il decoratore permette anche di specificare due parametri opzionali: degli esempi che il LLM possa utilizzare per avere degli esempi su cui basarsi, come nell’esmepio di seguito:

@tool(examples=["count the vowels in this sentence", "how many vowels has my sentence"])
def count_vowels(sentence, cat):
    """How many vowels has this sentence? Input is the sentence."""
    ...

Un’altra opzione è quella che permette di restituire la risposta dell’output della funzione così com’è, senza che venga aggiunto alcun messaggio da parte dell’agente: è il caso del parametro return_direct:

@tool(return_direct=True)
def count_vowels(sentence, cat):
    """How many vowels has this sentence? Input is the sentence."""
    ...

Per vedere in azione il plugin, non dovremo fare molto.. Quando vengono rilevate modifiche al codice sorgente di quest’ultimo, Cat si riavvia automaticamente!

Cos’è un hook

Sono delle funzioni speciali che permettono di modificare il comportamento del core del LLM: un esempio classico è quello che permette di definire la personalità che l’agente deve assumere quando interagisce con l’utente.

@hook
def agent_prompt_prefix(prefix, cat):

prefix = """You are Mark, a grumpy human calculator. You can calculate how many vowels a sentence have in a blink of 
an eye.
"""

return prefix

Anche in questo caso, esiste un decoratore speciale che indica al LLM che questo è un hook e che il gattone, se interrogato su chi sia, dovrà impersonare il personaggio che abbiamo descritto.

Tornando al plugin, una volta eseguito il clone, potremo copiare la cartella all’interno della directory core/cat/plugins/ del progetto principale.

Un esempio di plugin potrebbe quindi essere il seguente: costruiamo un agente in grado di calcolare il numero di vocali in una parola. Un compito assai semplice, che però dimostra quanto sia facile creare un plugin per lo Stregatto:

from cat.mad_hatter.decorators import hook,tool

@hook
def agent_prompt_prefix(prefix, cat):

prefix = """You are Mark, a grumpy human calculator. You can calculate how many vowels a sentence have in a blink of 
an eye.
"""

return prefix

@tool
def count_vowels(sentence, cat):
    """How many vowels has this sentence? Input is the sentence."""
    
    counter = 0
    for char in sentence:
      if char.lower() in ['a', 'e', 'i', 'o', 'u']:
        counter += 1
    return counter

Una volta ultimato, il LLM andrà ad abilitare il plugin, potremo abilitarlo tramite la sezione dedicata:

E potremo finalmente utilizzarlo!

Se vuoi dare un’occhiata ad un altro esempio, qui trovi il plugin per parlare in codice farfallino con lo Stregatto e criptare i tuoi messaggi!