KibCat (Kibana Cat) is the best chocolate you'll ever find!

---

📖 Wiki

• 📘 Diario: Storia del progetto e informazioni principali
• 📕 Conclusioni: Stato attuale del progetto e obiettivi raggiunti

---

📜 Descrizione

Generazione di URL Kibana per interrogazione database ElasticSearch e filtraggio di log in linguaggio naturale con correzione errori e validazione, tramite LLM ma nel modo più deterministico possibile.

graph LR
    
  UTENTE[UTENTE] <--> CHESHIRE_CAT["CHESHIRE<br>CAT"]
  CHESHIRE_CAT <--> LLM[LLM]

  subgraph EXT[Servizi Esterni]
    style EXT fill:#f,stroke-width:2px
    direction TB
    KIBANA[KIBANA] <--> ELASTIC[ELASTIC]
  end

  CHESHIRE_CAT --> ELASTIC
  CHESHIRE_CAT --> KIBANA

Loading

Abbiamo sviluppato due plugin per Cheshire Cat:

• KibCat: Plugin per la generazione di URL Kibana con linguaggio naturale - Il progetto principale.
• Token Counter: Plugin per contare i token utilizzati in Input/Output dall'LLM.

⚙️ Configurazione e struttura

Il progetto è composto da varie cartelle:

• /assets: Contiene immagini relative al progetto, come il logo o la demo.
• /cat: Cartella che contiene i volumi mappati con docker del CheshireCat. Contiene i file dei plugin e le varie utils relative.
• /cc_docker_image: L'immagine Docker del CheshireCat che consente i cambiamenti all'UI tramite iniezione di css e js esterno.
• /examples: Esempi pratici di uso del codice contenuto nella cartella src.
• /src: Cartella principale contenente la logica del progetto e tutte le funzioni.
• /tests: Test automatici per verificare i moduli all'interno di src.
• /wiki: Contiene il diario e le conclusioni.

Setup iniziale

Per poter utilizzare questo plugin con CheshireCat è necessario creare un file .env e il file main_fields.json.

Esempio di file .env, da posizionare nella root del progetto:

KIBANA_URL=http://kibana.localhost.example
ELASTIC_URL=http://elastic.localhost.example
KIBANA_BASE_URL_PART=/app/discover
KIBANA_USERNAME=kibana_username_example
KIBANA_PASS=kibana_password_example
KIBANA_SPACE_ID=default
KIBANA_DATA_VIEW_ID=container-log*

FIELDS_JSON_PATH=/app/cat/plugins/kibcat/main_fields.json

# These values are just for specific cases and probably wont ever be needed
# They can be removed most of the times
ELASTIC_URL_PRIVATE=elastic.localhost.example
KIBANA_URL_PRIVATE=kibana.localhost.example
IP_PRIVATE=256.256.256.256

Esempio di file main_fields.json in kibcat (Il percorso è indicato nella variabile globale FIELDS_JSON_PATH e può essere cambiato):

{
    "field.example.1": "Descrizione del primo field",
    "field.example.2": "Descrizione del secondo field",
    "field.example.3": "Descrizione del terzo field",
    // ...
}

In questo file nella descrizione delle field è possibile indicare che valori contiene la field, a cosa serve, o altre informazioni utili all'LLM per capire che l'utente sta facendo riferimento a quella field.

Aggiornamento UI e cambio delle frasi di default

Per poter applicare questi cambiamenti al Cat è stato creato un Dockerfile che si occupa semplicemente di "iniettare" nel codice del gatto i cambiamenti desiderati.

Per quanto riguarda la parte delle frasi di default (quelle che appaiono appena si entra sulla chat del Cat) è stato creato un file JSON example_messages.json contenente la lista di frasi con cui si vogliono rimpiazzare quelle originali:

[
    "Filtra per i log di errore sul container di devicehub",
    "Filtra per tutti i log che sono di warning o di informazione",
    "Filtra per i container di devicehub",
    "Filtra per i log di informazione da ieri a oggi.",
    "Filtra per i log dell'ultima settimana.",
    "Filtra per i log di kibcat nell'ultimo mese"
    // ...
]

Invece per i cambiamenti alla UI è stato creato uno style_override.css che viene mappato all'interno del container, e successivamente modificando una parte dell'HTML del Cat è stato possibile farlo caricare insieme al css originale del gatto, per poter apportare le modifiche desiderate alla UI usando la notazione !important.

Uso del plugin Token Counter

Questo plugin si occupa di tenere conto dell'uso dei token del modello, a causa del fatto che la funzione di token counter integrata nel gatto non funzionava in modo corretto. Maggiori dettagli nel diario 06/06/2025 e nel diario 11/06/2025.

Per utilizzare questo plugin, una volta attivato dalle impostazioni del Cat, è sufficiente scrivere un messaggio simile a Ottieni conteggio token o Get token count, e il plugin risponderà con il conteggio dei token utilizzati in input e output dall'LLM:

Input tokens: 790
Output tokens: 392

Warning

Se si esegue questo comando mentre si sta interagendo con un form (ad esempio il nostro form per la generazione di URL Kibana), il plugin non funzionerà correttamente, in quanto i tool vengono disabilitati in quel caso. Per poter utilizzare questo o altri plugin, è necessario inviare prima un altro messaggio per interrompere l'interazione con il form, ad esempio Exit form o Esci dal form, e poi inviare il comando per il conteggio dei token.

Uso dello strumento di benchmark

Per poter decidere in maniera più accurata quale modello utilizzare, è stato creato uno strumento di benchmark che permette di testare le performance dei vari modelli LLM.

Per poterlo utilizzare, seguire i seguenti passaggi:

1. Creare un file config.json nella cartella benchmark/, utilizzando il formato contenuto nel file di esempio config_example.json.

Spiegazione impostazioni del file config.json

Configurazione config.json per Benchmark LLM su CheshireCat

Il file config.json contiene tutte le configurazioni necessarie per eseguire i benchmark sui modelli LLM tramite la piattaforma CheshireCat.
Di seguito sono descritte nel dettaglio tutte le impostazioni disponibili.

---

📦 Configurazione Generale

Chiave	Descrizione	Default/Esempio
base_url	L'indirizzo del server su cui eseguire il benchmark.	"127.0.0.1"
port	La porta da utilizzare per la connessione al server.	1865
user_id	Identificativo dell'utente che esegue il test.	"testing_user"
username	Nome utente per l'autenticazione (se richiesta).	"admin"
password	Password per l'autenticazione (se richiesta).	"admin"
timeout	Tempo massimo di attesa (in secondi) per una risposta dal modello.	60
check_tokens_usage	Attiva/disattiva il controllo del numero di token utilizzati durante l'esecuzione (true/false).	true o false

---

🤖 Configurazione dei Modelli LLM

Il campo llm_config contiene un array di configurazioni dedicate ai modelli LLM che si vogliono testare.

Gli oggetti da inserire all'interno di questo array devono seguire lo stesso schema utilizzato nelle chiamate HTTP PUT a http://cheshirecatserver/llm/settings/LLMOpenAIChatConfig:

Di seguito un esempio di configurazione per LLM di tipo OpenAI ChatGPT:

{
  "name": "LLMOpenAIChatConfig",
  "value": {
    "openai_api_key": "REPLACE_ME",
    "model_name": "gpt-4o-mini",
    "temperature": 0.7,
    "streaming": false
  },
  "cost_per_million_tokens": {
    "input": 5.0,
    "output": 15.0
  }
}

Chiave	Descrizione
name	Tipo di configurazione per il modello (es. "LLMOpenAIChatConfig").
openai_api_key	Chiave API per accedere al modello specificato.
model_name	Nome del modello da utilizzare (es. "gpt-4o-mini", "gpt-4.1-mini").
temperature	Controllo della casualità delle risposte (valore compreso tra 0.0 e 1.0).
streaming	Abilita (true) o disabilita (false) la modalità streaming delle risposte nel CC.

Per attivare il conteggio dei token e il calcolo del costo medio di ogni conversazione, è necessario specificare i campi cost_per_million_tokens con i valori di costo per milione di token in input e output.

---

📝 Configurazione dei Test

Chiave	Descrizione
conversations	Array di conversazioni da utilizzare per il benchmark. Ogni conversazione è un array di messaggi che la compongono.
num_runs	Numero di volte che ogni configurazione deve essere eseguita nel benchmark.

Se nel benchmark è necessario interagire con un form, è possibile inserire un messaggio fittizzio %%END_FORM%% per permettere il conteggio dei token prima di continuare con il test.

Per utilizzare la funzione di conteggio dei token e di calcolo del costo medio di ogni conversazione, è necessario che il plugin Token Counter sia attivo nel CheshireCat.

---

📎 Esempio Completo di config.json

{
  "base_url": "127.0.0.1",
  "port": 1865,
  "user_id": "testing_user",
  "username": "admin",
  "password": "admin",
  "timeout": 60,
  "check_tokens_usage": false,
  "llm_config": [
    {
      "name": "LLMOpenAIChatConfig",
      "value": {
        "openai_api_key": "REPLACE_ME",
        "model_name": "gpt-4o-mini",
        "temperature": 0.7,
        "streaming": true
      },
      "cost_per_million_tokens": {
        "input": 0.15,
        "output": 0.6
      }
    },
    {
      "name": "LLMOpenAIChatConfig",
      "value": {
        "openai_api_key": "REPLACE_ME",
        "model_name": "gpt-4.1-mini",
        "temperature": 0.4,
        "streaming": true
      },
      "cost_per_million_tokens": {
        "input": 0.4,
        "output": 1.6
      }
    }
  ],
  "conversations": [
    [
      "How are you?"
    ],
    [
      "My name is Luigi",
      "What's my name?"
    ],
    [
      "Order me a pizza with mushrooms and ham",
      "Deliver it to Via Da Qui 25, BS",
      "%%END_FORM%%"
    ]
  ],
  "num_runs": 2
}

2. Eseguire il comando pip install -r benchmark/requirements.txt per installare le dipendenze necessarie.
3. Eseguire il comando python -m benchmark.run per avviare il benchmark. I risultati verranno salvati nella cartella benchmark/output/ in un file .json (e i log in un file .log).