Qualche giorno fa ho rilasciato su GitHub un plugin, chiamato Uptime Kuma Connector, per Cheshire Cat AI alias Stregatto alias gattone che, una volta installato, può rispondere a domande del tipo:

• Il servizio XYZ è attivo?
• Perché non riesco a collegarmi a(l sito) XYZ?
• Il sito XYZ è disponibile?
• È un problema mio o del servizio?

Per fare queste verifiche, il plugin si collega a una installazione di Uptime Kuma e la interroga, verificando se il servizio o il sito richiesto sta funzionando o meno.

Come funziona il plugin?

Il plugin espone allo Stregatto un solo tool, service_status(). Quando l’utente scrive “non riesco ad accedere a Esse3“, il modello recupera il tool, deduce il nome del servizio dalla richiesta e invoca il tool passando come parametro il nome del servizio.

A quel punto il plugin:

• legge l’endpoint /metrics dell’istanza Uptime Kuma, autenticandosi con la API key;
• risolve il nome chiesto dall’utente in uno o più monitor: prima con gli alias configurati, poi per nome esatto, infine per contenimento (con un minimo di 3 caratteri per lato);
• restituisce al modello una frase del tipo: “il sistema è disponibile” (non un JSON da interpretare).

Ho usato /metrics e non le API perché Uptime Kuma non ha una REST API generale, e le status page richiedono di pubblicare i dati. /metrics, invece, è protetto da chiave e contiene già tutto quello che serve.

Lo stato di un servizio non viene mai “inventato”, al massimo si ammette di non essere in grado di recuperarlo. Gli esiti possibili, infatti, sono quattro:

• known: il servizio è stato riconosciuto e lo stato è noto (up, down, pending, maintenance);
• not_monitored: nessun monitor corrisponde e il plugin dice esplicitamente al modello di non dedurne che il servizio funzioni;
• ambiguous: troppi monitor corrispondono, meglio chiedere all’utente quale intende;
• unknown: configurazione mancante, istanza irraggiungibile, risposta illeggibile.

Il plugin è in sola lettura, cioè non effettua modifiche su Uptime Kuma e sui monitor definiti.

Installazione e configurazione

Su Uptime Kuma: andare in Settings > API Keys > Add API Key e creare una chiave di sola lettura. Va copiata subito, perché Kuma non la mostra una seconda volta.

Su Cheshire Cat AI: andare in plugins cercare Uptime Kuma Connector e poi cliccare prima su Installa e poi su Configura, infine impostare i parametri di configurazione.

Tutte le impostazioni del plugin sono nel pannello di amministrazione:

• URL istanza: solo l’URL base, tipo https://kuma.example.org. Se è vuoto, il connettore è disattivato;
• API key: quella creata sopra;
• Mappa alias (opzionale): una voce per riga, nella forma U-GOV, UGOV: 12, dove a sinistra ci sono i nomi che usano gli utenti e a destra gli ID dei monitor. Serve quando il nome “umano” del servizio non somiglia al nome del monitor — che è praticamente sempre;
• Risposta massima (KiB) e timeout (secondi): limiti di sicurezza, default 1024 KiB e 2 secondi.

Piccola avvertenza: nelle impostazioni del gattone procedural_memory_k deve essere almeno 1, altrimenti il tool non viene mai recuperato e sembra che il plugin non funzioni.

Esempi d’uso

Dall’interfaccia di interrogazione dello Stregatto:

Un esempio dei log prodotti da queste interrogazioni:

Conclusioni

È un prodotto che può essere riutilizzato in vari contesti; noi lo abbiamo usato per un chatbot di help desk basato su un sistema RAG, dove la domanda “il servizio è giù?” arriva parecchie volte al giorno e la risposta giusta non sta in nessun documento indicizzato.

La licenza è GPL-3.0, quindi chiunque può scaricarlo, installarlo e modificarlo. L’unica dipendenza è httpx, che però è già presente nel core di Cheshire Cat AI: in pratica non si installa nulla.

Se servono maggiori chiarimenti o ci sono proposte di modifica, contattatemi pure, o ancora meglio, aprite direttamente una issue su GitHub.

 

Fonti e riferimenti

• Cheshire Cat AI, sito ufficiale.
• Cheshire Cat AI repository della versione 1.9.2 (quella per cui questo plugin è strato realizzato).
• Uptime Kuma Connector, repository su GitHub.