Créez votre premier plugin

Les fonctionnalités de Hexabot peuvent être étendues en développant et en installant des extensions depuis la Bibliothèque d'Extensions. Un plugin est une extension qui permet d'ajouter des fonctionnalités comme le texte-en-action et des intégrations avec des systèmes tiers. Une fois que vous ajoutez un plugin, un nouveau «Bloc de Construction» apparaîtra dans le Éditeur Visuel pour que vous puissiez l'utiliser lors de la conception de vos flux.

Si vous souhaitez ajouter votre propre bloc de construction, ce guide vous expliquera le processus de développement d'un plugin personnalisé pour votre projet Hexabot.

Prérequis

TypeScript, Node.js et Nest.js : Être familier avec TypeScript, Node.js et Nest.js rend le processus de développement de plugin plus fluide. Mais ne vous inquiétez pas si vous débutez – notre guide détaillé vous accompagnera pas à pas pour créer votre premier plugin.
Node.js : Assurez-vous d'avoir Node.js et un gestionnaire de paquets (npm ou yarn) installés.

Configurer Node.js avec NVM

Docker : Assurez-vous d'avoir Docker installé.

Configurer Docker pour le développement et la production

Créer un nouveau projet Hexabot : Téléchargez le CLI Hexabot et exécutez la commande hexabot create my-project .

Installation

Structure du dossier du plugin

Les plugins Hexabot interagissent avec le squelette existant de Hexabot et peuvent être gérés via l'interface Hexabot. Chaque plugin inclut généralement :

Un fichier package.json : Pour définir les métadonnées du plugin (nom, description, ...) ainsi que les dépendances supplémentaires dont vous pourriez avoir besoin.
Code d'intégration : Code qui définit comment le plugin interagit avec Hexabot et les API externes (comme Google Gemini dans ce cas).
Paramètres : Paramètres personnalisables pour adapter le comportement du plugin.
fichiers de traduction i18n

Un plugin Hexabot réside dans le répertoire suivant /extensions/plugins/ dans le dossier racine du projet Hexabot. Voici la structure de projet recommandée :

hexabot-plugin-example/
│
├── README.md                        // Documentation du plugin
├── index.plugin.ts                  // Point d'entrée principal du plugin
├── package.json                     // Manifest du plugin
├── settings.ts                      // Paramètres du plugin
├── i18n/                            // Répertoire de traduction
│   └── en/                        
│        └── title.json

Guide étape par étape

La création d'un nouveau plugin vous aidera à créer un nouveau bloc personnalisé dans l' éditeur visuel. Ce guide vous expliquera comment créer un plugin personnalisé, en utilisant un exemple basique : «Un bloc qui récupère et affiche l'heure actuelle» . Cette approche peut être étendue davantage pour créer toutes sortes de blocs personnalisés, vous permettant d'ajouter de nouvelles fonctionnalités parfaitement adaptées aux besoins de votre projet.

Créez votre répertoire de plugin

Accédez à extensions/plugins/ dossier dans votre projet Hexabot.
Créez un nouveau dossier nommé hexabot-plugin-time

Créez README.md

À l'intérieur du hexabot-plugin-time dossier, créez README.md fichier. Le fichier doit utiliser la syntaxe Markdown afin de fournir un aperçu et des détails essentiels sur l'utilisation de votre plugin.

## Nom du Plugin
**Description du Plugin** : 
    Explique brièvement de quoi traite le plugin.
**Fonctionnalités** : 
    Principales fonctionnalités du plugin.
**Prérequis** : 
     Outils, bibliothèques ou compétences requises.
**Instructions d'Installation** : 
    Étapes pour configurer le plugin.
**Configuration** : 
    Détails sur la façon de configurer ou d'adapter le plugin à des besoins spécifiques.
**Guide d'Utilisation** : 
    Comment utiliser le plugin.

Créez `package.json`

Le package.json est le fichier manifeste de votre plugin. Il décrit le plugin à Hexabot :

{
  "name": "hexabot-plugin-example",
  "version": "1.0.0",
  "author": "Votre Nom",
  "description": "Une brève description de votre plugin."
}

À l'intérieur du dossier hexabot-plugin-time, créez package.json et ajoutez ce qui suit :

{
    "name": "hexabot-plugin-time",
    "version": "1.0.0",
    "author": "Votre Nom",
    "description": "Plugin Hexabot pour obtenir l'heure actuelle.",
}

Créez `settings.ts`

Le settings.ts le fichier est l'endroit où vous pourrez définir les paramètres de votre bloc personnalisé, que ce soit pour configurer l'authentification d'une API ou toute autre configuration.

Dans le même dossier, créez settings.ts fichier et collez ce qui suit :

import { PluginSetting } from '@/plugins/types';
import { SettingType } from '@/setting/schemas/types';

export default [
  {
    label: 'response_message',
    group: 'default',
    type: SettingType.multiple_text,
    value: ['Time now is: ', 'Right now it\'s: '],
  },
] as const satisfies PluginSetting[];

Plus tard, le menu de configuration du bloc affichera ces paramètres, comme illustré ci-dessous

Créer le dossier i18n

Ce dossier stocke les fichiers de traduction pour que votre plugin soit multilingue. Vous pouvez ajouter autant de langues que nécessaire en créant un nouveau dossier pour chaque langue sous i18n dossier. Placez dans chaque fichier de langue un document JSON qui définira votre traduction pour une langue spécifique. Par exemple, le fichier title.json contient la traduction du nom de votre plugin.

À l'intérieur du répertoire hexabot-plugin-time, créez un nouveau dossier nommé i18n
À l'intérieur du dossier i18n, créez un nouveau dossier nommé en

{
  "currenttime_plugin": "Plugin Hexabot Heure Actuelle"
}

Reportez-vous à cet exemple de plugin Gemini pour mieux comprendre comment définir votre chaîne de traduction i18n :

hexabot-plugin-gemini/i18n/en at main · Hexastack/hexabot-plugin-geminiGitHub

Construction d'un bloc personnalisé

Implémenter la logique du bloc (index.plugin.ts) :

Cet exemple de plugin renvoie l'heure actuelle lorsqu'on envoie le mot-clé 'time' dans le chat pour déclencher le flux de conversation. Vous pouvez en apprendre davantage sur la création de votre flux et la gestion des blocs ici.

Dans le même répertoire hexabot-plugin-time créez le fichier index.plugin.ts avec le code suivant :

Commençons par importer les modules et services nécessaires :

Importez tous les modules, services et types nécessaires pour le plugin.

import { Injectable } from '@nestjs/common';
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 {
  OutgoingMessageFormat,
  StdOutgoingEnvelope,
  StdOutgoingTextEnvelope,
} from '@/chat/schemas/types/message';
import { BaseBlockPlugin } from '@/plugins/base-block-plugin';
import { PluginService } from '@/plugins/plugins.service';
import { PluginBlockTemplate } from '@/plugins/types';
import SETTINGS from './settings';

Définissez la classe du plugin et spécifiez son modèle :

Créez une classe CurrentTimePlugin étendant BaseBlockPlugin et définissez le modèle du plugin avec des motifs, un démarrage de conversation et un nom d'affichage.

@Injectable()
export class CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS> {
  template: PluginBlockTemplate = {
    patterns: ['time'],
    starts_conversation: true,
    name: 'Current Time Plugin',
  };

@Injectable(): Un décorateur qui rend la classe injectable dans NestJS, qui est le framework sous-jacent de l'API Hexabot.
CurrentTimePlugin étend BaseBlockPlugin<typeof SETTINGS>: Définit notre classe de plugin, héritant de BaseBlockPlugin et spécifiant que les paramètres sont définis par notre fichier settings.ts créé précédemment.
template: Un attribut de classe qui définit le modèle par défaut pour le bloc de construction :
- patterns: La liste des mots-clés qui déclencheront le bloc.
- starts_conversation: Si le bloc peut démarrer une conversation ou s'il ne doit être déclenché que par des messages précédents.
- name: Le nom du bloc qui apparaîtra dans l'éditeur visuel.

Constructeur pour initialiser les services :

Initialisez les services nécessaires (PluginService, BlockService, et SettingService) dans le constructeur.

constructor(
    pluginService: PluginService,
    private readonly blockService: BlockService,
    private readonly settingService: SettingService,
  ) {
    super('currenttime-plugin', pluginService);
  }

Définir la getPath méthode :

Ajouter la getPath() méthode est obligatoire, ce qui aide Hexabot à identifier le nom du répertoire du module actuel et à localiser les fichiers du plugin.

getPath(): string { 
    return __dirname; 
}

Définir la `process()` méthode pour gérer la logique principale du bloc :

Le process() la méthode exécute la logique principale du bloc :

Récupérer les paramètres et les arguments.
Obtenir l'heure actuelle et la formater.
Générer un message de réponse aléatoire en combinant l'heure formatée avec un message prédéfini.
Créer une enveloppe de message sortant avec le texte de la réponse.
Retourner l'enveloppe du message.

async process(
    block: Block,
    context: Context,
    _convId: string,
  ): Promise<StdOutgoingEnvelope> {
    const settings = await this.settingService.getSettings();
    const args = this.getArguments(block);

    const now = new Date();
    const formattedTime = now.toLocaleTimeString('en-US', { hour12: false });

    const response: string =
      this.blockService.getRandom([...args.response_message]) + formattedTime;

    const msg: StdOutgoingTextEnvelope = {
      format: OutgoingMessageFormat.text,
      message: {
        text: this.blockService.processText(
          response,
          context,
          {},
          settings,
        ),
      },
    };

    return msg;
  }
}

Code final :

🎉 Ci-dessous le code complet pour le CurrentTimePlugin:

import { Injectable } from '@nestjs/common';
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 {
  OutgoingMessageFormat,
  StdOutgoingEnvelope,
  StdOutgoingTextEnvelope,
} from '@/chat/schemas/types/message';
import { BaseBlockPlugin } from '@/plugins/base-block-plugin';
import { PluginService } from '@/plugins/plugins.service';
import { PluginBlockTemplate } from '@/plugins/types';

import SETTINGS from './settings';

@Injectable()
export class CurrentTimePlugin extends BaseBlockPlugin<typeof SETTINGS> {
  template: PluginBlockTemplate = {
    // déclencheur par défaut pour votre bloc personnalisé
    patterns: ['time'],
    // si défini à true alors votre bloc devient point d'entrée par défaut
    starts_conversation: true,
    // nom affiché pour votre plugin
    name: 'Current Time Plugin',
  };

  constructor(
    pluginService: PluginService,
    private readonly blockService: BlockService,
    private readonly settingService: SettingService,
  ) {
    super('currenttime-plugin', pluginService);
  }

  getPath(): string {
    return __dirname;
  }

  async process(
    block: Block,
    context: Context,
    _convId: string,
  ): Promise<StdOutgoingEnvelope> {
    const settings = await this.settingService.getSettings();
    const args = this.getArguments(block);

    const now = new Date();
    const formattedTime = now.toLocaleTimeString('en-US', { hour12: false });

    /**
     * getRandom() sélectionnera au hasard une chaîne depuis la valeur response_message
     * tableau défini dans le fichier settings pour construire la réponse.
     */
    const response: string =
      this.blockService.getRandom([...args.response_message]) +
      ' ⌚ ' +
      formattedTime;

    /**
     * réponse renvoyée par votre bloc personnalisé lors de son déclenchement, dans cet exemple
     * il renvoie un message texte affichant l'heure actuelle.
     */
    const msg: StdOutgoingTextEnvelope = {
      format: OutgoingMessageFormat.text,
      message: {
        text: this.blockService.processText(
          response,
          context,
          {},
          settings,
        ),
      },
    };

    return msg;
  }
}

Testez votre plugin

Redémarrez le service API Hexabot afin qu'il reconnaisse le plugin nouvellement ajouté. Si vous utilisez le mode développement (en utilisant la commande CLI `hexabot dev`), l'API devrait redémarrer automatiquement. Dans le cas où vous avez installé des dépendances node supplémentaires, vous devrez peut-être arrêter/relancer le service.
Test dans l'éditeur visuel : Ouvrez l'éditeur visuel, votre bloc personnalisé nommé Current Time Plugin devrait être disponible dans le panneau de gauche sous la section "Blocs Personnalisés". Ajoutez-le à votre flux et utilisez le mot-clé "time" dans la Console de Chat Admin, le bloc devrait alors être déclenché et renvoyer l'heure formatée.

Ce qui suit représente à quoi ressemblera votre plugin personnalisé basé sur l'exemple ci-dessus :

Publication de votre plugin

Après avoir terminé votre plugin, assurez-vous de vous connecter avec la communauté Hexabot sur Discord pour présenter votre plugin et travailler dans le show-n-tell canal.

Envisagez de publier votre plugin dans un dépôt (par exemple, NPM, GitHub) pour que d'autres puissent l'utiliser et continuer à l'améliorer.

Bibliothèque d'Extensions de Hexabot

Le Bibliothèque d'Extensions est une collection d'extensions créées par la communauté, pour la communauté. Les contributeurs peuvent partager leurs extensions, permettant à chacun de bénéficier d'une collection croissante de plugins, canaux et aides pour améliorer leurs IA conversationnelles.

Exemples de plugins

GitHub - Hexastack/hexabot-plugin-gemini: The Google Gemini Plugin for Hexabot Chatbot / Agent Builder to enable the LLM RAG CapabilityGitHub

GitHub - Hexastack/hexabot-plugin-chatgpt: The OpenAI ChatGPT Plugin for Hexabot Chatbot / Agent Builder to enable the LLM RAG CapabilityGitHub

N'oubliez pas que la meilleure façon d'apprendre est de plonger, d'expérimenter et de construire. N'hésitez pas à vous référer à la documentation centrale de Hexabot et à notre communauté Discord pendant que vous poursuivez votre parcours de développement !

PrécédentDéveloppement de plugins Hexabot SuivantEntraîner des modèles NLU personnalisés avec Ludwig AI

Mis à jour il y a 2 mois

Ce contenu vous a-t-il été utile ?

Bonjour