UniqAI/hexabot
1
0
Fork 0
mirror of https://github.com/hexastack/hexabot synced 2025-06-26 18:27:28 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

GITBOOK-104: No subject

Browse Source
This commit is contained in:
Mohamed Marrouchi 2024-12-17 18:45:54 +00:00 committed by gitbook-bot
parent 1c25297ef8
commit 1af846fb73
No known key found for this signature in database
GPG Key ID: 07D2180C7B12D0FF
2 changed files with 44 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/SUMMARY.md
View File

@ -63,7 +63,7 @@
* [Hexabot NLU Engine](developer-guide/hexabot-nlu-engine.md)
* [Plugins](developer-guide/integrations/README.md)
* [Hexabot Plugin Development](developer-guide/integrations/hexabot-plugin-development.md)
* [Build Your First plugin](developer-guide/integrations/build-your-first-plugin.md)
* [Build your First Plugin](developer-guide/integrations/build-your-first-plugin.md)
* [SMTP Configuration and Emails](developer-guide/smtp-configuration-and-emails.md)
## Key Concepts

93
docs/developer-guide/integrations/build-your-first-plugin.md
View File

@ -1,11 +1,12 @@
# Build Your First plugin
# Build your First Plugin
Hexabot's functionalities can be extended by developing and installing extensions from the [Extension Library](https://hexabot.ai/extensions). This allows to add features like text-to-action responses and third-party system integrations.
Hexabot's features can be extended by developing and installing extensions from the [Extension Library](https://hexabot.ai/extensions). A plugin is an extension that allows to add features like text-to-action and third-party system integrations. Once you add a plugin, a new "**Building Block**" will appear in the [Visual Editor](https://docs.hexabot.ai/user-guide/visual-editor) for you to use when designing your flows.
If you want to write your custom block or integration to extend Hexabot blocks library, this guide will walk you through the process of creating a custom plugin for Hexabot.
If you want to add your own building block, this guide will walk you through the process of developing a custom plugin for your Hexabot project.
### Prerequisites
* **TypeScript, Node.js and Nest.js:** Being familiar with [TypeScript](https://www.typescriptlang.org/docs/), [Node.js](https://nodejs.org/en/learn/getting-started/introduction-to-nodejs) and [Nest.js](https://nestjs.com/) makes the process of plugin development smoother. But don't worry if you're just getting started – our detailed guide will walk you through creating your first plugin.
* **Node.js:** Ensure you have Node.js and a package manager (npm or yarn) installed.
{% include "../../.gitbook/includes/untitled.md" %}
@ -16,17 +17,20 @@ If you want to write your custom block or integration to extend Hexabot blocks l
[setting-up-docker-for-development-and-production.md](../setting-up-docker-for-development-and-production.md)
{% endcontent-ref %}
* **Hexabot Source Code:** Clone the [Hexabot repository](https://github.com/Hexastack/Hexabot) and set up your development environment according to the main [Hexabot documentation](../../quickstart/installation.md#installation).
* **TypeScript and React:** Being familiar with [TypeScript](https://www.typescriptlang.org/docs/) and [React](https://react.dev/learn) makes Hexabot Plugin development much smoother. But don't worry if you're just getting started – our detailed guide will walk you through creating your first plugin.
* **Create a new Hexabot project:** Download the Hexabot CLI and run the `hexabot create my-project` command.
## Plugin Structure
{% content-ref url="../../quickstart/installation.md" %}
[installation.md](../../quickstart/installation.md)
{% endcontent-ref %}
Hexabot plugins interact with Hexabot's existing infrastructure and can be managed through the Hexabot UI. Each plugin typically includes:
## Plugin Folder Structure
* **A Manifest file :** To define the plugin meta-data.
Hexabot plugins interact with Hexabot's existing boilerplate and can be managed through the Hexabot UI. Each plugin typically includes:
* **A package.json file :** To define the plugin meta-data (name, description, ...) as well as extra dependencies you may need to use.
* **Integration Code:** Code that defines how the plugin interacts with Hexabot and external APIs (like Google Gemini in this case).
* **Configuration Settings:** Customizable settings to tailor the plugin’s behaviour.
* **i18n translation directory** 
* **Settings:** Customizable settings to tailor the plugin’s behaviour.
* **i18n translation files** 
A Hexabot plugins resides in the following directory `/extensions/plugins/` within the root folder of the Hexabot project. Here's the recommended project structure:
@ -41,9 +45,9 @@ A Hexabot plugins resides in the following directory `/extensions/plugins/` wit
│ └── title.json
</code></pre>
## Step-by-step guide
## Step-by-Step Guide
This guide will walk you through creating a custom plugin for Hexabot, using a basic example: a block that retrieves and displays the current time. This approach can be expanded further to create all kinds of custom blocks, allowing you to add new functionality that aligns perfectly with your project needs.
Creating a new plugin will help you create a new custom block in the [Visual editor](../../user-guide/visual-editor/). This guide will walk you through creating a custom plugin, using a basic example: "**A block that retrieves and displays the current time**". This approach can be expanded further to create all kinds of custom blocks, allowing you to add new functionality that aligns perfectly with your project needs.
### Create Your Plugin Directory
@ -52,7 +56,7 @@ This guide will walk you through creating a custom plugin for Hexabot, using a b
### Create README.md
Inside the `hexabot-plugin-time` folder, create `README.md` file. The file provides an overview and essential details about the usage of your plugin.
Inside the `hexabot-plugin-time` folder, create `README.md` file. The file should use the Markdown syntax in order to provide an overview and essential details about the usage of your plugin.
{% code fullWidth="false" %}
```markdown
@ -96,11 +100,9 @@ Inside the hexabot-plugin-time folder, create package.json and add the following
}
```
### Create `settings.ts`
Creating a new Hexabot plugin will help you create a new custom block in the [Visual editor](../../user-guide/visual-editor/). The `settings.ts` file is the place where you'll be able to define the settings of your custom block, whether it's setting up API authentication or any other configurations.&#x20;
The `settings.ts` file is the place where you'll be able to define the settings of your custom block, whether it's setting up API authentication or any other configurations.&#x20;
In the same folder, create `settings.ts` file and paste the following::
@ -122,9 +124,9 @@ Later, the block configuration menu will display these settings, as illustrated
<figure><img src="../../.gitbook/assets/image (30).png" alt=""><figcaption></figcaption></figure>
### Create i18n folder
### Create i18n Folder
This folder stores translations for your plugin into multiple languages. You can add as many languages as needed by creating a new folder for each language under `i18n` folder. Place under each language file a JSON document that will define your translation for a specific language. For example, the file `title.json` includes the translation of your plugin name.
This folder stores translation filess for your plugin to be multilingual. You can add as many languages as needed by creating a new folder for each language under `i18n` folder. Place under each language file a JSON document that will define your translation for a specific language. For example, the file `title.json` includes the translation of your plugin name.
* Inside the hexabot-plugin-time directory, create a new folder named i18n
* Inside the i18n folder, create a new folder named en
@ -141,7 +143,7 @@ Refer to this example of Gemini Plugin to better understand how to define your i
### Building a Custom Block
1. **Implement Block Logic (index.plugin.ts):**
**Implement Block Logic (index.plugin.ts):**
This plugin example returns the current time when sending 'time' keyword in the chat to trigger the conversation flow. You can learn more about creating your flow and managing blocks [here](../../quickstart/create-your-first-flow.md).
@ -153,8 +155,8 @@ Import all the necessary modules, services, and types required for the plugin.
```typescript
import { Injectable } from '@nestjs/common';
import { BlockService } from 'hexabot/src/chat/services/block.service';
import { SettingService } from 'hexabot/src/setting/services/setting.service';
import { BlockService } from '@/chat/services/block.service';
import { SettingService } from '@/setting/services/setting.service';
import { Block } from '@/chat/schemas/block.schema';
import { Context } from '@/chat/schemas/types/context';
import {
@ -182,12 +184,12 @@ export class CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS> {
};
```
* @Injectable(): Decorator that makes the class injectable within the NestJS framework (Hexabot’s backend).
* CurrentTimePlugin extends BaseBlockPlugin\<typeof SETTINGS>: Defines our plugin class, inheriting from BaseBlockPlugin and specifying that the settings are defined by our previously created settings.ts file.
* template: Defines the metadata about the plugin block like:
* patterns: The list of keywords that will trigger the block.
* starts\_conversation: Whether the block can start a conversation or should it only be triggered by previous messages.
* name: The name of the block that will appear in the visual editor.
* `@Injectable()`: A decorator that makes the class injectable within the NestJS which is the underlying framework for Hexabot’s API.
* `CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS>`: Defines our plugin class, inheriting from BaseBlockPlugin and specifying that the settings are defined by our previously created settings.ts file.
* `template`: A class attribute that defines the default template for the building block:
* `patterns`: The list of keywords that will trigger the block.
* `starts_conversation`: Whether the block can start a conversation or should it only be triggered by previous messages.
* `name`: The name of the block that will appear in the visual editor.
**Constructor to initialize services:**
@ -205,20 +207,20 @@ constructor(
**Define the `getPath` method:**
Add `getPath()` method, which is need by Hexabot to identify the directory name of the current module and locating the plugin's files.
Adding the `getPath()` method is mandatory, which helps Hexabot to identify the directory name of the current module and locating the plugin's files.
```typescript
getPath(): string {
return __dirname;
}
}
```
#### Define the **`Process()` method to handle block main logic:**
#### Define the **`process()` method to handle block main logic:**
The `process` method performs the main logic of the block:
The `process()` method performs the main logic of the block:
* Fetch settings and arguments.
* Get the current time and format it.
* Gets the current time and format it.
* Generate a random response message by combining the formatted time with a predefined message.
* Create an outgoing message envelope with the response text.
* Return the message envelope.
@ -244,7 +246,7 @@ async process(
text: this.blockService.processText(
response,
context,
context.vars,
{},
settings,
),
},
@ -260,18 +262,9 @@ async process(
:tada: Below is the complete code for the `CurrentTimePlugin`:
```typescript
/*
* Copyright © 2024 Hexastack. All rights reserved.
*
* Licensed under the GNU Affero General Public License v3.0 (AGPLv3) with the following additional terms:
* 1. The name "Hexabot" is a trademark of Hexastack. You may not use this name in derivative works without express written permission.
* 2. All derivative works must include clear attribution to the original creator and software, Hexastack and Hexabot, in a prominent location (e.g., in the software's "About" section, documentation, and README file).
*/
import { Injectable } from '@nestjs/common';
import { BlockService } from 'hexabot/src/chat/services/block.service';
import { SettingService } from 'hexabot/src/setting/services/setting.service';
import { BlockService } from '@/chat/services/block.service';
import { SettingService } from '@/setting/services/setting.service';
import { Block } from '@/chat/schemas/block.schema';
import { Context } from '@/chat/schemas/types/context';
import {
@ -338,7 +331,7 @@ export class CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS> {
text: this.blockService.processText(
response,
context,
context.vars,
{},
settings,
),
},
@ -352,8 +345,8 @@ export class CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS> {
### Test your plugin
1. Restart Hexabot and test your plugin thoroughly. This is needed so that Hexabot recognises the newly added plugin.
2. Test in Visual Editor: Open the Visual Editor, your custom block named Current Time Plugin should be available within the Block Library. Add it to a conversation flow and use the ‘time’ keyword on the Live Chat Tester, the block should return the formatted time.
1. **Restart Hexabot API service** so that it recognises the newly added plugin. If you are using the development mode (using the \`_**hexabot dev**_\` CLI command), the API should restart automatically. In case you have installed extra node dependencies, then you may need to stop/start the service.
2. **Test in Visual Editor:** Open the Visual Editor, your custom block named **Current Time Plugin** should be available within the left panel under the "**Custom Blocks**" section. Add it to your flow and use the "_time"_ keyword in the **Admin Chat Console**, the block should then be triggered and return the formatted time.
\
The following represents what your custom plugin will look like based on the example above:
@ -362,13 +355,13 @@ The following represents what your custom plugin will look like based on the exa
## Publishing your plugin
After completing your plugin, be sure to connect with the Hexabot community on [Discord](https://discord.gg/rNb9t2MFkG) to showcase your plugin and work in the show-n-tell channel.&#x20;
After completing your plugin, be sure to connect with the Hexabot community on [Discord](https://discord.gg/rNb9t2MFkG) to showcase your plugin and work in the _show-n-tell_ channel.&#x20;
Consider publishing your plugin to a repository (e.g., NPM, GitHub) for others to use and continue to improve it.
### Hexabot's Extensions Library
The Hexabot Extension Library is built by the community, for the community. Contributors can share their extensions, allowing everyone to benefit from a growing collection of plugins, channels, and helpers to enhance their chatbots. [https://hexabot.ai/extensions](https://hexabot.ai/extensions)
The Hexabot [Extension Library](https://hexabot.ai/extensions) is a collection of extensions built by the community, for the community. Contributors can share their extensions, allowing everyone to benefit from a growing collection of plugins, channels, and helpers to enhance their conversational AIs.&#x20;
## Plugins examples
@ -376,4 +369,4 @@ The Hexabot Extension Library is built by the community, for the community. Cont
{% embed url="https://github.com/Hexastack/hexabot-plugin-chatgpt" %}
This guide should give you a solid foundation to start developing plugins for Hexabot. Remember that the best way to learn is to dive in, experiment, and build. Don't hesitate to refer back to the core Hexabot documentation and our Discord community as you continue your development journey!&#x20;
Remember that the best way to learn is to dive in, experiment, and build. Don't hesitate to refer back to the core Hexabot documentation and our Discord community as you continue your development journey!&#x20;