feat: make nlu penalty factor setting configurable in UI

Author: MohamedAliBouhaouala

api/src/chat/services/block.service.ts

@@ -210,13 +210,14 @@ export class BlockService extends BaseService<
             return acc;
           }, []);
 
-        // @TODO Make nluPenaltyFactor configurable in UI settings
-        const nluPenaltyFactor = 0.95;
         // Log the matched patterns
         this.logger.debug(
           `Matched patterns: ${JSON.stringify(matchesWithPatterns.map((p) => p.matchedPattern))}`,
         );
 
+        // Retrieve Nlu Penalty Factor from global settings
+        const nluPenaltyFactor = await this.getDefaultNluPenaltyFactor();
+
         // Proceed with matching the best NLP block
         if (matchesWithPatterns.length > 0) {
           block = (await this.matchBestNLP(
@@ -474,6 +475,20 @@ export class BlockService extends BaseService<
     return patternScores.reduce((sum, score) => sum + score, 0);
   }
 
+  /**
+   * Retrieves the default NLU penalty factor from chatbot settings.
+   *
+   * This factor is used in NLU-based block scoring to reduce the influence
+   * of generic or broad entity matches (e.g. patterns using "Any").
+   * It helps prioritize blocks with more specific and confident entity matches.
+   *
+   * @returns {Promise<number>} The configured default NLU penalty factor.
+   */
+  async getDefaultNluPenaltyFactor(): Promise<number> {
+    const settings: Settings = await this.settingService.getSettings();
+    return settings.chatbot_settings.default_nlu_penalty_factor;
+  }
+
   /**
    * Matches an outcome-based block from a list of available blocks
    * based on the outcome of a system message.

api/src/migration/migrations/1735836154221-v-2-2-0.migration.ts

@@ -817,6 +817,49 @@ const removeDefaultStorageHelper = async ({ logger }: MigrationServices) => {
   }
 };
 
+const addDefaultNluPenaltyFactor = async ({ logger }: MigrationServices) => {
+  const SettingModel = mongoose.model<Setting>(Setting.name, settingSchema);
+  try {
+    await SettingModel.updateOne(
+      {
+        group: 'chatbot_settings',
+        label: 'default_nlu_penalty_factor',
+      },
+      {
+        group: 'chatbot_settings',
+        label: 'default_nlu_penalty_factor',
+        value: 0.95,
+        type: SettingType.number,
+        config: {
+          min: 0,
+          max: 1,
+          step: 0.01,
+        },
+        weight: 2,
+      },
+      {
+        upsert: true,
+      },
+    );
+    logger.log('Successfuly added the default NLU penalty factor setting');
+  } catch (err) {
+    logger.error('Unable to add the default NLU penalty factor setting');
+  }
+};
+
+const removeDefaultNluPenaltyFactor = async ({ logger }: MigrationServices) => {
+  const SettingModel = mongoose.model<Setting>(Setting.name, settingSchema);
+  try {
+    await SettingModel.deleteOne({
+      group: 'chatbot_settings',
+      label: 'default_nlu_penalty_factor',
+    });
+    logger.log('Successfuly removed the default NLU penalty factor setting');
+  } catch (err) {
+    logger.error('Unable to remove the default local storage helper setting');
+  }
+};
+
 module.exports = {
   async up(services: MigrationServices) {
     await updateOldAvatarsPath(services);
@@ -830,6 +873,7 @@ module.exports = {
     await populateUserAvatars(services);
     await populateSubscriberAvatars(services);
     await addDefaultStorageHelper(services);
+    await addDefaultNluPenaltyFactor(services);
     return true;
   },
   async down(services: MigrationServices) {
@@ -839,6 +883,7 @@ module.exports = {
     await migrateAttachmentBlocks(MigrationAction.DOWN, services);
     await migrateAttachmentContents(MigrationAction.DOWN, services);
     await removeDefaultStorageHelper(services);
+    await removeDefaultNluPenaltyFactor(services);
     return true;
   },
 };

api/src/setting/seeds/setting.seed-model.ts

@@ -52,12 +52,24 @@ export const DEFAULT_SETTINGS = [
     },
     weight: 3,
   },
+  {
+    group: 'chatbot_settings',
+    label: 'default_nlu_penalty_factor',
+    value: 0.95,
+    type: SettingType.number,
+    config: {
+      min: 0,
+      max: 1,
+      step: 0.01,
+    },
+    weight: 4,
+  },
   {
     group: 'chatbot_settings',
     label: 'global_fallback',
     value: true,
     type: SettingType.checkbox,
-    weight: 4,
+    weight: 5,
   },
   {
     group: 'chatbot_settings',
@@ -72,7 +84,7 @@ export const DEFAULT_SETTINGS = [
       idKey: 'id',
       labelKey: 'name',
     },
-    weight: 5,
+    weight: 6,
   },
   {
     group: 'chatbot_settings',
@@ -82,7 +94,7 @@ export const DEFAULT_SETTINGS = [
       "I'm really sorry but i don't quite understand what you are saying :(",
     ] as string[],
     type: SettingType.multiple_text,
-    weight: 6,
+    weight: 7,
     translatable: true,
   },
   {

frontend/public/locales/en/chatbot_settings.json

@@ -8,13 +8,15 @@
     "fallback_block": "Fallback Block",
     "default_nlu_helper": "Default NLU Helper",
     "default_llm_helper": "Default LLM Helper",
-    "default_storage_helper": "Default Storage Helper"
+    "default_storage_helper": "Default Storage Helper",
+    "default_nlu_penalty_factor": "Default NLU Penalty Factor"
   },
   "help": {
     "global_fallback": "Global fallback allows you to send custom messages when user entry does not match any of the block messages.",
     "fallback_message": "If no fallback block is selected, then one of these messages will be sent.",
     "default_nlu_helper": "The NLU helper is responsible for processing and understanding user inputs, including tasks like intent prediction, language detection, and entity recognition.",
     "default_llm_helper": "The LLM helper leverages advanced generative AI to perform tasks such as text generation, chat completion, and complex query responses.",
-    "default_storage_helper": "The storage helper defines where to store attachment files. By default, the default local storage helper stores them locally, but you can choose to use Minio or any other storage solution."
+    "default_storage_helper": "The storage helper defines where to store attachment files. By default, the default local storage helper stores them locally, but you can choose to use Minio or any other storage solution.",
+    "default_nlu_penalty_factor": "The NLU penalty factor is a coefficient (between 0 and 1) applied exclusively to NLU-based entity matching. It reduces the score contribution of patterns that match broadly (e.g. using wildcard values like Any) rather than specific entity values. This helps the engine prioritize blocks triggered by more precise NLU matches, without affecting other matching strategies such as text, regex, or interaction triggers."
   }
 }

frontend/public/locales/fr/chatbot_settings.json

@@ -8,13 +8,15 @@
     "fallback_block": "Bloc de secours",
     "default_nlu_helper": "Utilitaire NLU par défaut",
     "default_llm_helper": "Utilitaire LLM par défaut",
-    "default_storage_helper": "Utilitaire de stockage par défaut"
+    "default_storage_helper": "Utilitaire de stockage par défaut",
+    "default_nlu_penalty_factor": "Facteur de pénalité NLU par défaut"
   },
   "help": {
     "global_fallback": "La réponse de secours globale vous permet d'envoyer des messages personnalisés lorsque l'entrée de l'utilisateur ne correspond à aucun des messages des blocs.",
     "fallback_message": "Si aucun bloc de secours n'est sélectionné, l'un de ces messages sera envoyé.",
     "default_nlu_helper": "Utilitaire du traitement et de la compréhension des entrées des utilisateurs, incluant des tâches telles que la prédiction d'intention, la détection de langue et la reconnaissance d'entités.",
     "default_llm_helper": "Utilitaire responsable de l'intelligence artificielle générative avancée pour effectuer des tâches telles que la génération de texte, la complétion de chat et les réponses à des requêtes complexes.",
-    "default_storage_helper": "Utilitaire de stockage définit l'emplacement où stocker les fichiers joints. Par défaut, le stockage local les conserve localement, mais vous pouvez choisir d'utiliser Minio ou toute autre solution de stockage."
+    "default_storage_helper": "Utilitaire de stockage définit l'emplacement où stocker les fichiers joints. Par défaut, le stockage local les conserve localement, mais vous pouvez choisir d'utiliser Minio ou toute autre solution de stockage.",
+    "default_nlu_penalty_factor": "Le facteur de pénalité NLU est un coefficient (entre 0 et 1) appliqué exclusivement aux correspondances d'entités basées sur NLU. Il réduit la contribution au score des motifs qui correspondent de manière générale (par exemple, en utilisant des valeurs génériques comme Any) plutôt que des valeurs d'entité spécifiques. Cela permet au chatbot de donner la priorité aux blocs déclenchés par des correspondances NLU plus précises, sans affecter d'autres stratégies de correspondance telles que le texte, les expressions regex ou les déclencheurs d'interaction."
   }
 }