Knowledge Base — Cognitive Assistant

# Knowledge Base

La knowledge base di Cognitor Assistant è organizzata in tre componenti principali:

knowledge/
├── intents/    # Definizioni degli intenti con esempi
├── rules/      # Regole di mappatura intent -> risposte
└── responses/  # Template delle risposte

Intents (`knowledge/intents/`)

Gli intenti definiscono cosa l'utente vuole fare. Ogni file JSON contiene un array di intenti con esempi di frasi.

Struttura

json

{
  "nlu": {
    "intents": [
      {
        "intent": "greeting",
        "examples": [
          "ciao",
          "salve",
          "buongiorno"
        ]
      }
    ]
  }
}

Annotazioni NER negli Esempi

Gli esempi possono contenere annotazioni per il riconoscimento delle entità:

[Mario](PERSON) - Persona
[Roma](LOCATION) - Località
[Juventus](TEAM) - Squadra sportiva
[oggi](DATE) - Data
[Python](PRODUCT) - Prodotto
[10](TIME) - Orario
[TOPIC] - Topic generico
[NUMBER] - Numero

Intenti Supportati

Intent	Descrizione
`greeting`	Saluto
`farewell`	Arrivederci
`help`	Richiesta di aiuto
`ask_name`	Chiede il nome dell'assistente
`thank_you`	Ringraziamento
`compliment`	Complimento
`insult`	Insulto
`bot_challenge`	Domanda sull'identità del bot
`mood_great`	Umore positivo
`mood_unhappy`	Umore negativo
`joke`	Richiesta barzelletta
`weather_query`	Query meteo
`time_query`	Query orario
`date_query`	Query data
`search`	Ricerca informazioni
`call`	Effettuare chiamata
`send_message`	Inviare messaggio
`open_app`	Aprire applicazione
`set_reminder`	Impostare promemoria
`translate`	Tradurre
`define`	Definire
`calculate`	Calcolare
`play_game`	Giocare
`sing`	Cantare
e molti altri...

Rules (`knowledge/rules/`)

Le rules definiscono la mappatura tra intenti e risposte, con supporto per condizioni.

Struttura Semplice

json

{
  "rules": {
    "greeting": {
      "default": "greeting_response"
    }
  }
}

Struttura con Condizioni

json

{
  "rules": {
    "ask_city_touristic_information": {
      "conditions": [
        {
          "if": [
            {
              "slot": "LOCATION",
              "operator": "eq",
              "value": "Roma"
            }
          ],
          "response": "ask_city_touristic_information_roma_response"
        },
        {
          "if": [
            {
              "slot": "LOCATION",
              "operator": "not_filled"
            }
          ],
          "response": "ask_location_wait_response",
          "wait_for_slot": "LOCATION"
        }
      ],
      "default": "ask_location_wait_response"
    }
  }
}

Operatori Supportati

Operatore	Descrizione
`eq`	Uguale (case-insensitive)
`neq`	Non uguale
`gt`	Maggiore di
`lt`	Minore di
`contains`	Contiene
`filled`	Slot valorizzato
`not_filled`	Slot non valorizzato

Responses (`knowledge/responses/`)

Le responses contengono i template delle risposte che l'assistente può dare.

Struttura

json

{
  "responses": {
    "greeting_response": [
      "Ciao! Come posso aiutarti oggi?",
      "Hey! Sono qui per te. Cosa vuoi fare?"
    ]
  }
}

Placeholder

Le risposte possono contenere placeholder che vengono sostituiti dinamicamente:

[TIME] - Orario corrente
[DATE] - Data corrente
Slot values - Valori estratti dalla conversazione

Esempio di Risposte Completo

json

{
  "responses": {
    "greeting_response": [
      "Ciao! Come posso aiutarti oggi?",
      "Hey! Sono qui per te. Cosa vuoi fare?",
      "Ciao! Benvenuto! In cosa posso esserti utile?"
    ],
    "farewell_response": [
      "Arrivederci! È stato un piacere parlare con te!",
      "Ciao! Speriamo di sentirci presto. Buona giornata!"
    ],
    "help_response": [
      "Posso aiutarti con molte cose: cercare informazioni, rispondere a domande, fare calcoli, impostare promemoria e molto altro. Cosa ti serve?"
    ]
  }
}

Gestione degli Slot

Quando un intent richiede informazioni aggiuntive, il sistema utilizza wait_for_slot per richiedere le informazioni mancanti all'utente.

Esempio Completo

Rule:

json

{
  "ask_city_touristic_information": {
    "conditions": [
      {
        "if": [{"slot": "LOCATION", "operator": "not_filled"}],
        "response": "ask_location_wait_response",
        "wait_for_slot": "LOCATION"
      }
    ],
    "default": "city_info_response"
  }
}

Response:

json

{
  "ask_location_wait_response": [
    "Che bella domanda! Per darti informazioni più precise, puoi dirmi la località che ti interessa?"
  ]
}

Aggiunta di Nuovi Intenti

Per aggiungere un nuovo intent:

Aggiungere gli esempi in knowledge/intents/.json
Definire le regole in knowledge/rules/.json
Aggiungere le risposte in knowledge/responses/.json
Riaddestrare il modello

Best Practices

Esempi Diversificati: Fornire almeno 10-20 esempi per intent, coprendo diverse formulazioni
Risposte Multiple: Definire almeno 2-3 varianti per ogni risposta per rendere la conversazione più naturale
Gestione Errori: Sempre definire una risposta di fallback (default_fallback)
Slot Obbligatori: Usare wait_for_slot quando un'informazione è necessaria per completare l'azione