GITBOOK-110: No subject

docs/SUMMARY.md

@@ -23,6 +23,10 @@
     * [Using Attachment Block](user-guide/visual-editor/regular-blocks/using-attachment-block.md)
   * [Using Advanced Blocks](user-guide/visual-editor/using-advanced-blocks.md)
 * [Flows](user-guide/flows.md)
+* [NLU](user-guide/nlu/README.md)
+  * [Manage NLU Entities](user-guide/nlu/manage-nlu-entities.md)
+  * [NLU Engines](user-guide/nlu/nlu-engines/README.md)
+    * [LLM NLU Engine](user-guide/nlu/nlu-engines/llm-nlu-engine.md)
 * [NLU Training](user-guide/nlu-training.md)
 * [Knowledge Base](user-guide/knowledge-base/README.md)
   * [Content Types](user-guide/knowledge-base/content-types.md)

docs/user-guide/nlu-training.md

@@ -1,3 +1,7 @@
+---
+hidden: true
+---
+
 # NLU Training
 
 <figure><img src="../.gitbook/assets/image (2).png" alt=""><figcaption><p>NLU Training</p></figcaption></figure>

docs/user-guide/nlu/README.md

@@ -0,0 +1,30 @@
+# NLU
+
+### What is NLU?
+
+Natural Language Understanding (NLU) is a subfield of Artificial Intelligence (AI) focused on enabling machines to comprehend and interpret human language in a meaningful way. In Hexabot, the NLU engine can be used for example to:
+
+* **Detect Intents:** Understand the purpose or goal behind a user’s input, such as asking for information, making a request, or providing feedback.
+* **Slot Filling:** Extract specific pieces of information (e.g., dates, locations, or quantities) from user inputs to complete structured tasks or queries.
+* **Enhance Context Awareness:** Maintain a coherent understanding of user interactions to enable multi-turn conversations.
+* **Sentiment Analysis:** Assess the emotional tone behind user inputs, which can guide responses or trigger appropriate actions.
+* **Entity Recognition:** Identify named entities such as dates, numbers, and other contextual markers using libraries like Duckling.
+
+### The Role of NLU in AI Safety
+
+Hexabot embraces a safety-first approach to AI, advocating for responsible AI usage that prioritizes user protection over convenience. By leveraging NLU as the first step in the conversational pipeline, Hexabot ensures:
+
+* **Controlled Output:** The bot detects intents and entities before deciding whether generative AI is needed, reducing the likelihood of misinterpretation or unsafe responses.
+* **Context Awareness:** The bot maintains contextual understanding through structured NLU processing, enhancing conversational accuracy.
+* **Accountability:** NLU provides a traceable layer of logic that helps audit decisions, making Hexabot’s operation transparent and trustworthy.
+
+### Why is NLU is Important?
+
+Hexabot prioritizes AI safety and precision in understanding user interactions. The role of the NLU engine is critical for several reasons:
+
+1. **Intent-Driven Conversations:** By accurately detecting user intent, Hexabot ensures that each interaction aligns with the user’s needs. This leads to a more structured and predictable conversation flow.
+2. **Control Over Generative AI:** While generative AI models powered by Large Language Models (LLMs) are powerful, they also present risks such as hallucinations, jailbreaking, and unintended responses. By detecting intent first, Hexabot determines when and where generative AI should be used, ensuring that responses are safe, relevant, and aligned with ethical guidelines.
+3. **Improved AI Governance:** NLU acts as a safeguard layer, offering a controlled environment where generative AI operates only under predefined circumstances. This helps mitigate risks associated with over-reliance on LLMs.
+4. **Customizability and Extendibility:** The modular nature of Hexabot’s NLU engine allows developers to define custom intents, integrate domain-specific entities, and expand the engine’s functionality (e.g., adding sentiment analysis).
+5. **User Trust and Safety:** A well-implemented NLU ensures that users feel understood and that the bot operates within defined ethical and operational parameters. This fosters trust and minimizes the risk of generating harmful or irrelevant outputs.
+

docs/user-guide/nlu/manage-nlu-entities.md

@@ -0,0 +1,69 @@
+# Manage NLU Entities
+
+In Hexabot’s NLU engine, entities play a crucial role in extracting meaningful information from user inputs. Entities can be categorized into two types: **Trait Entities** and **Keyword Entities**. These entity types provide flexibility and depth in understanding user inputs, enabling Hexabot to process both high-level intentions and granular details.
+
+### Trait Entities
+
+Trait entities are inferred by analyzing the entire sentence or the overall context of the input. These entities represent high-level attributes or characteristics of the input and are not tied to specific words or phrases. Below some examples:
+
+<table><thead><tr><th width="129">Entity</th><th width="185">Description</th><th width="192">Text</th><th>Value</th></tr></thead><tbody><tr><td>Intent</td><td>The purpose of the user’s input.</td><td>"<em>Hello</em>"</td><td>greeting</td></tr><tr><td>Intent</td><td>The purpose of the user’s input.</td><td>"<em>I want to book a flight</em>"</td><td>book_flight</td></tr><tr><td>Sentiment</td><td>The emotional tone behind the input.</td><td>"<em>I’m really frustrated with my current plan.</em>"</td><td>negative</td></tr><tr><td>Urgency</td><td>An attribute that determines the priority of the input.</td><td>"<em>I need help right away!</em>"</td><td>high</td></tr></tbody></table>
+
+Trait entities allow Hexabot to grasp the overarching context of the input, providing a deeper understanding that informs appropriate responses and actions.
+
+### Keyword Entities
+
+Keyword entities are specific words or phrases extracted from the input to identify important attributes and convert unstructured data into structured information. These entities are tied to identifiable patterns or specific terms within the user input. Below some examples:
+
+| Entity   | Description                                                               | Text                                            | Value     |
+| -------- | ------------------------------------------------------------------------- | ----------------------------------------------- | --------- |
+| Location | Identifying places from the input.                                        | "_I want to book a flight to **Paris**."_       | Paris     |
+| Product  | Recognizing product names or types.                                       | "_I’m interested in buying the **iPhone 15**."_ | iPhone 15 |
+| Topic    | Detecting specific keywords that activate certain workflows or responses. | "_Show me the latest **offers**."_              | offers    |
+
+### Manage NLU Entities
+
+Hexabot provides an intuitive interface to manage NLU entities efficiently, allowing you to create, update, and administer both Trait and Keyword entities. Follow these steps to manage NLU entities:
+
+1. **Navigate to the NLU Section**
+
+* Open the main menu and select the “NLU” option.
+* Click on the “NLU Entities” tab.
+
+2. **View the Entities List**
+
+* A data grid will display all the existing entities, including both Trait and Keyword entities.
+* Use the search bar to find specific entities or navigate through the list using pagination.
+
+3. **Add New Entities**
+
+* Click on the ”**+ Add**” button to create a new entity.
+* Choose the type of entity by selecting the **Lookup Strategy**: **Trait** or **Keyword**.
+* Fill in the required fields:
+  * **Name**: The unique identifier for the entity.
+  * **Description**: A brief explanation of the entity’s purpose.
+  * Click **Save** to add the entity to the list.
+
+4. **Update or Delete Entities**
+
+* Locate the entity you want to modify.
+* Click on the Edit icon to update its details or the Delete icon to remove the entity permanently.
+
+5. **Administer Entity Values**
+
+* For each entity, you can manage its possible values by clicking on the “**Values**” icon.
+
+### Managing Entity Values
+
+Once you click the “**Values**” icon, a new data grid will display the possible values associated with the selected entity.
+
+1. **Guidelines for Values:**
+
+* Use lowercase text and separate words with underscores (e.g., high\_priority, low\_stock).
+* Ensure that values are descriptive and concise.
+
+2. **Update or Remove Values:**
+
+* Click the Edit icon to update an existing value or its synonyms.
+* Use the Delete icon to remove a value permanently.
+
+This flexible management system ensures Hexabot’s NLU remains robust, adaptable, and capable of handling a wide range of conversational scenarios.

docs/user-guide/nlu/nlu-engines/README.md

@@ -0,0 +1,68 @@
+# NLU Engines
+
+The NLU Engine is the core component of Hexabot’s natural language understanding pipeline, responsible for detecting intents, entities, and other attributes from user inputs. Hexabot supports multiple NLU Engines to cater to different levels of expertise and use cases.
+
+### LLM NLU Engine
+
+Leverages Large Language Models (LLMs) such as Ollama, Gemini, or ChatGPT to detect intents and language without requiring custom training. This is the default NLU engine which is ideal for those looking for a ready-to-use NLU solution without requiring prior AI expertise.
+
+**Benefits:**
+
+* No need to train your own models.
+* Quick setup and instant results for supported intents
+
+**Limitations:**
+
+* Does not provide a confidence score (e.g., probability of accuracy).
+* Performance may vary for lesser-known languages and dialects.
+* Primarily effective for widely spoken languages like English, French, etc.
+
+### Ludwig NLU Engine
+
+Uses [Ludwig](https://ludwig.ai/latest/), a low-code AI framework, to help you build custom AI models with minimal coding. It supports modern architectures like BERT, LSTM, and RNN. This is a good option for developers or teams looking to create customizable models quickly without diving deep into coding.
+
+**Benefits:**
+
+* Requires little to no coding; you configure models via YAML or JSON files.
+* Accessible for junior to intermediate AI practitioners.
+
+**Limitations:**
+
+* Requires some understanding of AI concepts to configure effectively.
+
+### Tensorflow NLU Engine
+
+A Python boilerplate that we built ourselves is provided to facilitate the development of TensorFlow-based models. This could be suitable for experienced data scientists who want full control over their AI pipeline.
+
+**Benefits:**
+
+* Gives complete control over the model design and training process.
+* Supports advanced customization for experienced data scientists.
+
+**Limitations:**
+
+* Requires strong expertise in machine learning and TensorFlow.
+* More time-intensive to develop and maintain.
+
+### Building Your Own NLU Engine
+
+Hexabot’s architecture allows you to integrate custom NLU engines by following these steps:
+
+**1. Build a Service (API):**
+
+* Develop an inference service that performs intent detection, entity recognition, or other NLU tasks.
+* The service should expose an API endpoint that accepts input text and returns predictions.
+
+**2. Create a Helper Extension:**
+
+* Implement a helper extension in Hexabot to call the custom NLU service.
+* The extension should handle the integration, sending input to the API and processing predictions.
+
+**3. Use Existing Examples:**
+
+* Refer to the source code of existing NLU engines (LLM, Ludwig, TensorFlow) for guidance.
+* Source code is available on Hexabot’s GitHub repository.
+
+### Summary
+
+Hexabot’s NLU Engine supports a range of solutions, from plug-and-play LLM-based inference to fully customizable TensorFlow models. Whether you are a novice or an expert, there’s an option tailored to your needs. Additionally, Hexabot’s open design empowers developers to build and integrate custom engines, expanding the possibilities of natural language understanding in your conversational AI projects.

docs/user-guide/nlu/nlu-engines/llm-nlu-engine.md

@@ -0,0 +1,77 @@
+# LLM NLU Engine
+
+The LLM NLU Engine in Hexabot leverages the power of Large Language Models (LLMs) to detect intents and determine language efficiently. This engine is ideal for users who want a quick, pre-trained solution without the need to develop and train custom AI models. Below is the detailed guide on configuring and using the LLM NLU Engine in Hexabot.
+
+### Configuring the LLM NLU Engine
+
+<figure><img src="../../../.gitbook/assets/image (31).png" alt=""><figcaption></figcaption></figure>
+
+#### **Step 1: Set the Default NLU Helper**
+
+* Navigate to “**Settings**” from the main menu.
+* Select the “**Chatbot**” tab.
+* Ensure that the “**Default NLU Helper**” is set to "**llm-nlu-helper**".
+
+This ensures that Hexabot uses the LLM-powered NLU engine for processing intents and language detection.
+
+#### **Step 2: Select the Default LLM Helper**
+
+1. In the same “Chatbot” tab, locate the “Default LLM Helper” setting.
+2. Choose your preferred LLM helper from the installed options. Below some LLM helpers as an example:
+   1. **Ollama Helper (**[**hexabot-helper-ollama**](https://hexabot.ai/extensions/672731347ddd71f5fb2f0d7a)**) :** A helper for integrating with [Ollama](https://ollama.ai/), an LLM platform designed for localized or containerized usage. Install Ollama either locally on your machine or as a Docker container.
+   2. **Google Gemini Helper (**[**hexabot-helper-gemini**](https://hexabot.ai/extensions/67272e927ddd71f5fb2f0c5c)**):** A helper for integrating with Google Gemini, Google’s advanced LLM for high-performance AI applications. Generate an API key from Google Cloud Console. Configure the helper with the API key in Hexabot’s settings.
+   3. **OpenAI ChatGPT Helper (**[**hexabot-helper-chatgpt**](https://hexabot.ai/extensions/67272fef7ddd71f5fb2f0d02)**):** A helper for integrating with OpenAI’s ChatGPT, a widely used and versatile LLM. Generate an API key from the OpenAI dashboard. Configure the helper with the API key in Hexabot’s settings.
+
+3\. Ensure the necessary helper is installed and configured.
+
+#### **Step 3: Configure the prompts of the LLM NLU Engine**
+
+The LLM NLU Helper Settings allow you to configure and fine-tune the behavior of the LLM-powered NLU engine in Hexabot. These settings include options for selecting the model, defining language detection prompts, and customizing trait classification prompts. Below are the details and guidelines for configuring these settings.
+
+<figure><img src="../../../.gitbook/assets/image (32).png" alt=""><figcaption></figcaption></figure>
+
+1. Navigate to “**Settings**” from the main menu.
+2. Select the “**LLM NLU Engine**” tab.
+3. Specify the name of the LLM (Large Language Model) you want to use. Leave this field empty to use the default model specified in the LLM helper’s settings. Examples:&#x20;
+   1. **Ollama Models:** [https://ollama.com/library](https://ollama.com/library) (Note that you will need to download each model you would like to in Ollama)
+   2. **Google Gemini Models:** [**https://ai.google.dev/gemini-api/docs/models/gemini#model-variations**](https://ai.google.dev/gemini-api/docs/models/gemini#model-variations)
+   3. **OpenAI ChatGPT Models:** [**https://platform.openai.com/docs/models/gp**](https://platform.openai.com/docs/models/gp)
+4. The **language detection prompt** is used to identify the language of a given input text. The LLM helper uses this template to dynamically generate prompts.
+5. The **trait classifier prompt** is designed for tasks like detecting intent, sentiment, or other high-level attributes from input text.
+
+{% hint style="info" %}
+Prompts use [Handlebars](https://handlebarsjs.com/guide/) for dynamic templates:
+
+* Enclose variables in `{{` and `}}`. For example: `{{variableName}}`.
+* Use `{{#if}}` for conditional statements.
+* Loop through arrays with `{{#each arrayName}}`.
+{% endhint %}
+
+**Step 4: Test the LLM NLU Engine**
+
+1. Navigate to the "**NLU**" from the main menu and then select the "**NLU Entities**" tab to add some entities and/or intent values.
+
+{% content-ref url="../manage-nlu-entities.md" %}
+[manage-nlu-entities.md](../manage-nlu-entities.md)
+{% endcontent-ref %}
+
+2. Use the **NLU training form** to test out some text and see if predictions are good.
+
+<figure><img src="../../../.gitbook/assets/image (33).png" alt=""><figcaption></figcaption></figure>
+
+3. Finally, you can use NLU Entities when configuring triggers in the blocks within the [Visual Editor](../../visual-editor/)
+
+{% content-ref url="../../visual-editor/regular-blocks/" %}
+[regular-blocks](../../visual-editor/regular-blocks/)
+{% endcontent-ref %}
+
+### Key Considerations
+
+**1. Helper Installation:** Ensure the desired LLM helper is installed before selecting it in the settings. Installation instructions for each helper are provided in their respective documentation.
+
+**2. Performance and Limitations:** LLMs excel at detecting intents and languages without custom training, but they lack confidence scores and may perform poorly with less-common languages or dialects.
+
+**3. Security and Privacy:**
+
+* Use local deployment options like **Ollama** if privacy is a concern.
+* For cloud-based APIs (Google Gemini and OpenAI ChatGPT), ensure API keys are securely managed and adhere to organizational security policies.