@hexabot-ai/api 3.0.0-alpha.3

package/src/nlp/services/nlp-value.service.ts

@@ -0,0 +1,264 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { forwardRef, Inject, Injectable } from '@nestjs/common';
+import { FindManyOptions, In } from 'typeorm';
+
+import { NlpValueMatchPattern } from '@/chat/types/pattern';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+import { Format } from '@/utils/types/format.types';
+
+import { NlpSampleEntityValue } from '..//types';
+import { NlpEntity } from '../dto/nlp-entity.dto';
+import {
+  NlpValue,
+  NlpValueCreateDto,
+  NlpValueDtoConfig,
+  NlpValueTransformerDto,
+  TNlpValueCount,
+} from '../dto/nlp-value.dto';
+import { NlpValueOrmEntity } from '../entities/nlp-value.entity';
+import { NlpValueRepository } from '../repositories/nlp-value.repository';
+
+import { NlpEntityService } from './nlp-entity.service';
+
+@Injectable()
+export class NlpValueService extends BaseOrmService<
+  NlpValueOrmEntity,
+  NlpValueTransformerDto,
+  NlpValueDtoConfig
+> {
+  constructor(
+    readonly repository: NlpValueRepository,
+    @Inject(forwardRef(() => NlpEntityService))
+    private readonly nlpEntityService: NlpEntityService,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Fetch values whose `value` field matches the patterns provided.
+   *
+   * @param patterns  Pattern list
+   * @returns Promise resolving to the matching values.
+   */
+  async findByPatterns(patterns: NlpValueMatchPattern[]) {
+    return await this.find({
+      where: {
+        value: In(patterns.map((p) => p.value)),
+      },
+    });
+  }
+
+  /**
+   * Adds new NLP values or updates existing ones based on the provided training sample.
+   * This method handles both the creation of new values and the addition of synonyms.
+   *
+   * @param sampleText The original text from the training sample.
+   * @param sampleEntities The entities and values extracted from the sample.
+   * @param storedEntities The stored NLP entities to be updated with new values.
+   *
+   * @returns A promise that resolves with the updated sample entities containing their IDs.
+   */
+  async storeNewValues(
+    sampleText: string,
+    sampleEntities: NlpSampleEntityValue[],
+    storedEntities: NlpEntity[],
+  ): Promise<NlpSampleEntityValue[]> {
+    const eMap: Record<string, NlpEntity> = storedEntities.reduce(
+      (acc, curr) => {
+        if (curr.name) acc[curr?.name] = curr;
+
+        return acc;
+      },
+      {},
+    );
+    // Extract entity values from sampleEntities
+    const values = sampleEntities.map((e) => e.value);
+
+    // Retrieve stored values
+    let storedValues = await this.find({
+      where: { value: In(values) },
+    });
+
+    // Compute the values to be added
+    const valuesToAdd = sampleEntities
+      // Remove already stored values
+      .filter((e) => storedValues.findIndex((v) => v.value === e.value) === -1)
+      // Filter unique values to avoid duplicates
+      .filter(
+        (e, idx, self) =>
+          self.findIndex(({ value }) => e.value === value) === idx,
+      )
+      // Build the value dto object
+      .map((e) => {
+        const newValue: NlpValueCreateDto = {
+          entity: eMap[e.entity].id,
+          value: e.value,
+          expressions: [],
+        };
+        // Deal with synonym case
+        if ('start' in e && 'end' in e) {
+          const word = sampleText.slice(e.start, e.end);
+          if (word !== e.value) {
+            newValue.expressions = [word];
+          }
+        }
+
+        return newValue;
+      });
+    // Store new values
+    const newValues = await this.createMany(valuesToAdd);
+
+    storedValues = storedValues.concat(newValues);
+
+    const vMap: Record<string, NlpValue> = storedValues.reduce((acc, curr) => {
+      acc[curr.value] = curr;
+
+      return acc;
+    }, {});
+    // Store new synonyms for existing values
+    const synonymsToAdd = sampleEntities
+      .filter((e) => {
+        if ('start' in e && 'end' in e) {
+          const word = sampleText.slice(e.start, e.end);
+
+          return (
+            word !== e.value && vMap[e.value].expressions?.indexOf(word) === -1
+          );
+        }
+
+        return false;
+      })
+      .map((e) => {
+        const value = vMap[e.value];
+        const expression = sampleText.slice(e.start, e.end);
+
+        return this.updateOne(value.id, {
+          expressions: [...(value.expressions ?? []), expression],
+        });
+      });
+
+    await Promise.all(synonymsToAdd);
+
+    // Replace entities/values with ids
+    const result: NlpSampleEntityValue[] = sampleEntities.map((e) => {
+      return {
+        ...e,
+        entity: eMap[e.entity].id,
+        value: vMap[e.value].id,
+      };
+    });
+
+    // Return sample entities with ids
+    return result;
+  }
+
+  /**
+   * Adds new NLP values or updates existing ones based on the training sample.
+   * Handles the addition of synonyms and ensures that each value has the correct entity association.
+   *
+   * @param sampleText The original text from the training sample.
+   * @param sampleEntities The entities and values extracted from the sample.
+   *
+   * @returns A promise that resolves with the stored NLP values.
+   */
+  async storeValues(
+    sampleText: string,
+    sampleEntities: NlpSampleEntityValue[],
+  ): Promise<NlpValue[]> {
+    const entities = sampleEntities.map((e) => e.entity);
+    // Get all used entities from database
+    const storedEntities = await this.nlpEntityService.find({
+      where: { name: In(entities) },
+    });
+    // Prepare values objects for storage
+    const valuesToAddMap = new Map<string, NlpValueCreateDto>();
+    for (const entityValue of sampleEntities) {
+      let expressions: string[] = [];
+      if (
+        'start' in entityValue &&
+        entityValue.start &&
+        entityValue.start >= 0 &&
+        'end' in entityValue &&
+        entityValue.end &&
+        entityValue.end > 0
+      ) {
+        const word = sampleText.slice(entityValue.start, entityValue.end);
+        if (word !== entityValue.value) {
+          expressions = [word];
+        }
+      }
+
+      const storedEntity = storedEntities.find(
+        (se) => se.name === entityValue.entity,
+      );
+      if (!storedEntity) {
+        throw new Error(
+          `Unable to find the stored entity ${entityValue.entity}`,
+        );
+      }
+
+      const existing = valuesToAddMap.get(entityValue.value);
+      if (existing) {
+        const mergedExpressions = new Set([
+          ...(existing.expressions ?? []),
+          ...expressions,
+        ]);
+        existing.expressions = mergedExpressions.size
+          ? Array.from(mergedExpressions)
+          : undefined;
+      } else {
+        valuesToAddMap.set(entityValue.value, {
+          entity: storedEntity.id,
+          value: entityValue.value,
+          expressions: expressions.length ? expressions : undefined,
+        });
+      }
+    }
+
+    const valuesToAdd = Array.from(valuesToAddMap.values());
+    // Find or create values
+    const promises = valuesToAdd.map(async (v) => {
+      const createdOrFound = await this.findOneOrCreate(
+        { where: { value: v.value } },
+        v,
+      );
+      // If value is found in database, then update it's synonyms
+      const expressions = v.expressions
+        ? createdOrFound.expressions
+            ?.concat(v.expressions) // Add new synonyms
+            .filter((v, i, a) => a.indexOf(v) === i)
+        : createdOrFound.expressions?.filter((v, i, a) => a.indexOf(v) === i); // Filter unique values
+      // Update expressions
+      const result = await this.updateOne(
+        { where: { value: v.value } },
+        { expressions },
+      );
+
+      if (!result) throw new Error(`Unable to update NLP value ${v.value}`);
+
+      return result;
+    });
+
+    return Promise.all(promises);
+  }
+
+  /**
+   * Retrieves NLP values with their training sample counts from the repository,
+   * applying pagination, filters, and formatting.
+   * @param format - Desired result format: FULL or STUB.
+   * @param options - TypeORM find options to control filtering, sorting, and pagination.
+   * @returns A promise that resolves to a list of NLP values with their training sample counts,
+   *          typed according to the requested format.
+   */
+  async findWithCount<F extends Format>(
+    format: F,
+    options: FindManyOptions<NlpValueOrmEntity> = {},
+  ): Promise<TNlpValueCount<F>[]> {
+    return await this.repository.findWithCount(format, options);
+  }
+}

package/src/nlp/services/nlp.service.ts

@@ -0,0 +1,311 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { In, InsertEvent, RemoveEvent, UpdateEvent } from 'typeorm';
+
+import { HelperService } from '@/helper/helper.service';
+import { HelperType, NLU } from '@/helper/types';
+import { LoggerService } from '@/logger/logger.service';
+
+import { NlpEntity, NlpEntityFull } from '../dto/nlp-entity.dto';
+import { NlpValue, NlpValueFull } from '../dto/nlp-value.dto';
+import { NlpEntityOrmEntity } from '../entities/nlp-entity.entity';
+import { NlpValueOrmEntity } from '../entities/nlp-value.entity';
+
+import { NlpEntityService } from './nlp-entity.service';
+import { NlpSampleEntityService } from './nlp-sample-entity.service';
+import { NlpSampleService } from './nlp-sample.service';
+import { NlpValueService } from './nlp-value.service';
+
+type HelperEntityPayload = Omit<NlpEntityFull, 'values'> & {
+  values?: NlpValue[];
+};
+
+const mapValueForHelper = (value: NlpValueFull | NlpValue): NlpValue => {
+  const { entity, ...rest } = value as NlpValueFull;
+  const entityId =
+    typeof entity === 'object' ? (entity.id as string) : (entity as string);
+
+  return {
+    ...(rest as unknown as Omit<NlpValue, 'entity'>),
+    entity: entityId,
+  };
+};
+const mapEntityForHelper = (entity: NlpEntityFull): HelperEntityPayload => {
+  const { values, ...rest } = entity;
+
+  return {
+    ...rest,
+    values: values?.map((value) => mapValueForHelper(value)),
+  };
+};
+
+@Injectable()
+export class NlpService {
+  constructor(
+    private readonly logger: LoggerService,
+    protected readonly nlpSampleService: NlpSampleService,
+    protected readonly nlpEntityService: NlpEntityService,
+    protected readonly nlpValueService: NlpValueService,
+    protected readonly helperService: HelperService,
+    protected readonly nlpSampleEntityService: NlpSampleEntityService,
+  ) {}
+
+  /**
+   * Computes a prediction score for each parsed NLU entity based on its confidence and a predefined weight.
+   *
+   * `score = confidence * weight`
+   *
+   * If a weight is not defined for a given entity, a default of 1 is used.
+   *
+   * @param input - The input object containing parsed entities.
+   * @param input.entities - The list of entities returned from NLU inference.
+   *
+   * @returns A promise that resolves to a list of scored entities.
+   */
+  async computePredictionScore({
+    entities,
+  }: NLU.ParseEntities): Promise<NLU.ScoredEntities> {
+    const nlpMap = await this.nlpEntityService.getNlpMap();
+    const scoredEntities = entities
+      .filter(({ entity }) => nlpMap.has(entity))
+      .map((e) => {
+        const entity = nlpMap.get(e.entity)!;
+
+        return {
+          ...e,
+          score: e.confidence * (entity.weight || 1),
+        };
+      });
+
+    return { entities: scoredEntities };
+  }
+
+  /**
+   * Handles the event triggered when a new NLP entity is created. Synchronizes the entity with the external NLP provider.
+   *
+   * @param entity - The NLP entity to be created.
+   */
+  @OnEvent('hook:nlpEntity:postCreate')
+  async handleEntityPostCreate(
+    event: InsertEvent<NlpEntityOrmEntity>,
+  ): Promise<void> {
+    const created = event.entity;
+
+    if (!created || created.builtin) {
+      return;
+    }
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+      const entityFull = await this.nlpEntityService.findOneAndPopulate(
+        created.id,
+      );
+
+      if (!entityFull) {
+        return;
+      }
+
+      const helperPayload = mapEntityForHelper(entityFull);
+      const foreignId = await helper.addEntity(
+        helperPayload as unknown as NlpEntity,
+      );
+      this.logger.debug('New entity successfully synced!', foreignId);
+      await this.nlpEntityService.updateOne(created.id, {
+        foreignId,
+      });
+    } catch (err) {
+      this.logger.error('Unable to sync a new entity', err);
+    }
+  }
+
+  /**
+   * Handles the event triggered when an NLP entity is updated. Synchronizes the updated entity with the external NLP provider.
+   *
+   * @param entity - The NLP entity to be updated.
+   */
+  @OnEvent('hook:nlpEntity:postUpdate')
+  async handleEntityPostUpdate(
+    event: UpdateEvent<NlpEntityOrmEntity>,
+  ): Promise<void> {
+    const previous = event.databaseEntity;
+
+    if (!previous) {
+      return;
+    }
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+      const entityFull = await this.nlpEntityService.findOneAndPopulate(
+        previous.id,
+      );
+
+      if (!entityFull || entityFull.builtin) {
+        return;
+      }
+
+      await helper.updateEntity(
+        mapEntityForHelper(entityFull) as unknown as NlpEntity,
+      );
+      this.logger.debug('Updated entity successfully synced!', event);
+    } catch (err) {
+      this.logger.error('Unable to sync updated entity', err);
+    }
+  }
+
+  /**
+   * Before deleting a `nlpEntity`, this method deletes the related `nlpValue` and `nlpSampleEntity`. Synchronizes the deletion with the external NLP provider
+   *
+   * @param _query - The query object used for deletion.
+   * @param criteria - The filter criteria for finding the nlpEntities to be deleted.
+   */
+  @OnEvent('hook:nlpEntity:preDelete')
+  async handleEntityDelete(
+    event: RemoveEvent<NlpEntityOrmEntity>,
+  ): Promise<void> {
+    const entity = event.databaseEntity;
+
+    if (!entity) {
+      return;
+    }
+
+    await Promise.all([
+      this.nlpValueService.deleteMany({
+        where: { entity: In([entity.id]) },
+      }),
+      this.nlpSampleEntityService.deleteMany({
+        where: { entity: In([entity.id]) },
+      }),
+    ]);
+
+    if (entity.builtin) {
+      return;
+    }
+
+    const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+
+    try {
+      if (entity.foreignId) {
+        await helper.deleteEntity(entity.foreignId);
+        this.logger.debug('Deleted entity successfully synced!', entity);
+      } else {
+        this.logger.error(`Entity ${entity.id} is missing foreignId`);
+        throw new NotFoundException(`Entity ${entity.id} is missing foreignId`);
+      }
+    } catch (err) {
+      this.logger.error('Unable to sync deleted entity', err);
+    }
+  }
+
+  /**
+   * Handles the event triggered when a new NLP value is created. Synchronizes the value with the external NLP provider.
+   *
+   * @param value - The NLP value to be created.
+   */
+  @OnEvent('hook:nlpValue:postCreate')
+  async handleValuePostCreate(
+    event: InsertEvent<NlpValueOrmEntity>,
+  ): Promise<void> {
+    const created = event.entity;
+
+    if (!created || created.builtin) {
+      return;
+    }
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+      const valueFull = await this.nlpValueService.findOneAndPopulate(
+        created.id,
+      );
+
+      if (!valueFull) {
+        return;
+      }
+
+      const helperValuePayload = mapValueForHelper(valueFull);
+      const foreignId = await helper.addValue(helperValuePayload);
+      this.logger.debug('New value successfully synced!', foreignId);
+      await this.nlpValueService.updateOne(created.id, {
+        foreignId,
+      });
+    } catch (err) {
+      this.logger.error('Unable to sync a new value', err);
+    }
+  }
+
+  /**
+   * Handles the event triggered when an NLP value is updated. Synchronizes the updated value with the external NLP provider.
+   *
+   * @param value - The NLP value to be updated.
+   */
+  @OnEvent('hook:nlpValue:postUpdate')
+  async handleValuePostUpdate(
+    event: UpdateEvent<NlpValueOrmEntity>,
+  ): Promise<void> {
+    const previous = event.databaseEntity;
+
+    if (!previous) {
+      return;
+    }
+
+    try {
+      const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+      const valueFull = await this.nlpValueService.findOneAndPopulate(
+        previous.id,
+      );
+
+      if (!valueFull || valueFull.builtin) {
+        return;
+      }
+
+      await helper.updateValue(mapValueForHelper(valueFull));
+      this.logger.debug('Updated value successfully synced!', event);
+    } catch (err) {
+      this.logger.error('Unable to sync updated value', err);
+    }
+  }
+
+  /**
+   * Before deleting a `nlpValue`, this method deletes the related `nlpSampleEntity`. Synchronizes the deletion with the external NLP provider
+   *
+   * @param _query - The query object used for deletion.
+   * @param criteria - The filter criteria for finding the nlpValues to be deleted.
+   */
+  @OnEvent('hook:nlpValue:preDelete')
+  async handleValueDelete(
+    event: RemoveEvent<NlpValueOrmEntity>,
+  ): Promise<void> {
+    const value = event.databaseEntity;
+
+    if (!value) {
+      return;
+    }
+
+    await this.nlpSampleEntityService.deleteMany({
+      where: { value: In([value.id]) },
+    });
+
+    if (value.builtin) {
+      return;
+    }
+
+    const helper = await this.helperService.getDefaultHelper(HelperType.NLU);
+
+    try {
+      const populatedValue = await this.nlpValueService.findOneAndPopulate(
+        value.id,
+      );
+      if (populatedValue) {
+        await helper.deleteValue(populatedValue);
+        this.logger.debug('Deleted value successfully synced!', value);
+      }
+    } catch (err) {
+      this.logger.error('Unable to sync deleted value', err);
+    }
+  }
+}

package/src/nlp/types.ts

@@ -0,0 +1,45 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { NlpEntityFull, NlpEntityStub } from './dto/nlp-entity.dto';
+import { NlpValueStub } from './dto/nlp-value.dto';
+
+export enum LookupStrategy {
+  keywords = 'keywords',
+  trait = 'trait',
+  free_text = 'free-text',
+  pattern = 'pattern',
+}
+
+export type Lookup = `${LookupStrategy}`;
+
+export interface NlpSampleEntityValue {
+  entity: string; // entity name
+  value: string; // entity value
+  start?: number;
+  end?: number;
+}
+
+export type NlpEntityMap<T extends NlpEntityStub> = { [entityId: string]: T };
+
+export type NlpValueMap<T extends NlpValueStub> = { [valueId: string]: T };
+
+export enum NlpSampleState {
+  train = 'train',
+  test = 'test',
+  inbox = 'inbox',
+}
+
+export type NlpCacheMap = Map<string, NlpEntityFull>;
+
+export type NlpMetadata = {
+  // Required when lookups is "pattern"
+  pattern?: string;
+  wordBoundary?: boolean;
+  removeSpaces?: boolean;
+  toLowerCase?: boolean;
+  stripDiacritics?: boolean;
+};

package/src/plugins/base-block-plugin.ts

@@ -0,0 +1,73 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import path from 'path';
+
+import { Injectable } from '@nestjs/common';
+
+import { Block, BlockFull } from '@/chat/dto/block.dto';
+import { Context } from '@/chat/types/context';
+import { StdOutgoingEnvelope } from '@/chat/types/message';
+
+import { BasePlugin } from './base-plugin.service';
+import { PluginService } from './plugins.service';
+import {
+  PluginBlockTemplate,
+  PluginEffects,
+  PluginName,
+  PluginSetting,
+  PluginType,
+} from './types';
+
+@Injectable()
+export abstract class BaseBlockPlugin<
+  T extends PluginSetting[],
+> extends BasePlugin {
+  public readonly type: PluginType = PluginType.block;
+
+  private readonly settings: T;
+
+  constructor(name: PluginName, pluginService: PluginService<BasePlugin>) {
+    super(name, pluginService);
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    this.settings = require(path.join(this.getPath(), 'settings')).default;
+  }
+
+  getDefaultSettings(): Promise<T> | T {
+    return this.settings;
+  }
+
+  abstract template: PluginBlockTemplate;
+
+  effects?: PluginEffects;
+
+  abstract process(
+    block: Block | BlockFull,
+    context: Context,
+    convId?: string,
+  ): Promise<StdOutgoingEnvelope>;
+
+  protected getArguments(block: Block) {
+    if ('args' in block.message) {
+      return (
+        Object.entries(block.message.args)
+          // Filter out old settings
+          .filter(
+            ([argKey]) =>
+              this.settings.findIndex(({ label }) => label === argKey) !== -1,
+          )
+          .reduce(
+            (acc, [k, v]) => ({
+              ...acc,
+              [k]: v,
+            }),
+            {} as SettingObject<T>,
+          )
+      );
+    }
+    throw new Error(`Block ${block.name} does not have any arguments.`);
+  }
+}

package/src/plugins/base-event-plugin.ts

@@ -0,0 +1,20 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BasePlugin } from './base-plugin.service';
+import { PluginService } from './plugins.service';
+import { PluginName, PluginType } from './types';
+
+@Injectable()
+export abstract class BaseEventPlugin extends BasePlugin {
+  public readonly type: PluginType = PluginType.event;
+
+  constructor(name: PluginName, pluginService: PluginService<BasePlugin>) {
+    super(name, pluginService);
+  }
+}