@hexabot-ai/api 3.0.0-alpha.3

package/src/nlp/repositories/nlp-sample.repository.ts

@@ -0,0 +1,214 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { plainToInstance } from 'class-transformer';
+import {
+  DeepPartial,
+  FindManyOptions,
+  Repository,
+  SelectQueryBuilder,
+} from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+
+import { NlpSampleState } from '..//types';
+import {
+  NlpSample,
+  NlpSampleFull,
+  NlpSampleTransformerDto,
+  TNlpSampleDto,
+} from '../dto/nlp-sample.dto';
+import { NlpValue } from '../dto/nlp-value.dto';
+import { NlpSampleOrmEntity } from '../entities/nlp-sample.entity';
+
+@Injectable()
+export class NlpSampleRepository extends BaseOrmRepository<
+  NlpSampleOrmEntity,
+  NlpSampleTransformerDto,
+  TNlpSampleDto
+> {
+  /**
+   * Initializes the repository with default relations and transformers.
+   * @param repository The TypeORM repository for `NlpSampleOrmEntity`.
+   */
+  constructor(
+    @InjectRepository(NlpSampleOrmEntity)
+    repository: Repository<NlpSampleOrmEntity>,
+  ) {
+    super(repository, ['language', 'entities'], {
+      PlainCls: NlpSample,
+      FullCls: NlpSampleFull,
+    });
+  }
+
+  /**
+   * Finds samples that match the provided entity/value pairs.
+   * @param criterias Optional query options and the entity/value constraints to apply.
+   * @returns Samples transformed into `NlpSample` instances.
+   */
+  async findByEntities(criterias: {
+    options?: FindManyOptions<NlpSampleOrmEntity>;
+    values: NlpValue[];
+  }): Promise<NlpSample[]> {
+    const entities = await this.buildFindByEntitiesQuery(criterias).getMany();
+
+    return entities.map((entity) => plainToInstance(NlpSample, entity));
+  }
+
+  /**
+   * Finds samples that match the provided entity/value pairs and loads relations.
+   * @param criterias Optional query options and the entity/value constraints to apply.
+   * @returns Samples transformed into `NlpSampleFull` instances.
+   */
+  async findByEntitiesAndPopulate(criterias: {
+    options?: FindManyOptions<NlpSampleOrmEntity>;
+    values: NlpValue[];
+  }): Promise<NlpSampleFull[]> {
+    const entities = await this.buildFindByEntitiesQuery(criterias)
+      .leftJoinAndSelect('sample.language', 'language')
+      .leftJoinAndSelect('sample.entities', 'sampleEntities')
+      .leftJoinAndSelect('sampleEntities.entity', 'entity')
+      .leftJoinAndSelect('sampleEntities.value', 'value')
+      .getMany();
+
+    return entities.map((entity) => plainToInstance(NlpSampleFull, entity));
+  }
+
+  /**
+   * Counts samples that match the provided entity/value pairs.
+   * @param criterias Optional query options and the entity/value constraints to apply.
+   * @returns Number of samples that satisfy the constraints.
+   */
+  async countByEntities(criterias: {
+    options?: FindManyOptions<NlpSampleOrmEntity>;
+    values: NlpValue[];
+  }): Promise<number> {
+    const qb = this.buildFindByEntitiesQuery(criterias);
+
+    return await qb.getCount();
+  }
+
+  /**
+   * Creates the query builder used to retrieve samples filtered by entity/value pairs.
+   * @param options Optional TypeORM `FindManyOptions` used to refine filtering.
+   * @param values Entity/value constraints to enforce on the query.
+   * @returns Configured query builder that applies the provided constraints.
+   */
+  private buildFindByEntitiesQuery({
+    options = {},
+    values,
+  }: {
+    options?: FindManyOptions<NlpSampleOrmEntity>;
+    values: NlpValue[];
+  }): SelectQueryBuilder<NlpSampleOrmEntity> {
+    const qb = this.repository.createQueryBuilder('sample');
+    const findOptions: FindManyOptions<NlpSampleOrmEntity> = {};
+    const hasWhere = options.where !== undefined;
+    const hasOrder =
+      options.order !== undefined &&
+      Object.keys(options.order as Record<string, unknown>).length > 0;
+
+    if (hasWhere) {
+      findOptions.where = options.where;
+    }
+
+    if (hasOrder) {
+      findOptions.order = options.order;
+    }
+
+    if (Object.keys(findOptions).length > 0) {
+      qb.setFindOptions(findOptions);
+    }
+
+    if (!hasOrder) {
+      qb.addOrderBy('sample.createdAt', 'DESC');
+    }
+
+    if (typeof options?.skip === 'number') {
+      qb.skip(options.skip);
+    }
+
+    if (typeof options?.take === 'number') {
+      qb.take(options.take);
+    }
+
+    this.applyValueConstraints(qb, values);
+
+    return qb;
+  }
+
+  /**
+   * Constrains the query so that each provided value must be present in the sample.
+   * @param qb Query builder to update.
+   * @param values Entity/value pairs used in `EXISTS` subqueries.
+   */
+  private applyValueConstraints(
+    qb: SelectQueryBuilder<NlpSampleOrmEntity>,
+    values: NlpValue[],
+  ): void {
+    values.forEach((value, index) => {
+      qb.andWhere(
+        `EXISTS (SELECT 1 FROM nlp_sample_entities sampleEntity${index} WHERE sampleEntity${index}.sample_id = sample.id AND sampleEntity${index}.entity_id = :entityId${index} AND sampleEntity${index}.value_id = :valueId${index})`,
+        {
+          [`entityId${index}`]: value.entity,
+          [`valueId${index}`]: value.id,
+        },
+      );
+    });
+  }
+
+  /**
+   * Searches for samples containing keywords and optionally filtered by types.
+   * @param keywords Keywords to match within the sample text (case-insensitive).
+   * @param types Optional sample states to limit the search scope.
+   * @returns Samples transformed into `NlpSample` instances.
+   */
+  async findContainingKeywords(
+    keywords: string[],
+    types: NlpSampleState[],
+  ): Promise<NlpSample[]> {
+    if (!keywords.length) {
+      return [];
+    }
+
+    const qb = this.repository.createQueryBuilder('sample');
+
+    if (types.length) {
+      qb.where('sample.type IN (:...types)', { types });
+    }
+
+    const params: Record<string, string> = {};
+    const clauses = keywords.map((keyword, index) => {
+      const param = `keyword${index}`;
+      params[param] = `%${keyword.toLowerCase()}%`;
+
+      return `LOWER(sample.text) LIKE :${param}`;
+    });
+
+    if (clauses.length === 1) {
+      if (types.length) {
+        qb.andWhere(clauses[0], params);
+      } else {
+        qb.where(clauses[0], params);
+      }
+    } else {
+      const combined = clauses.map((c) => `(${c})`).join(' OR ');
+      if (types.length) {
+        qb.andWhere(combined, params);
+      } else {
+        qb.where(combined, params);
+      }
+    }
+
+    const entities = await qb.getMany();
+
+    return entities.map((entity) =>
+      plainToInstance(NlpSample, entity as DeepPartial<NlpSampleOrmEntity>),
+    );
+  }
+}

package/src/nlp/repositories/nlp-value.repository.ts

@@ -0,0 +1,139 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { plainToInstance } from 'class-transformer';
+import { FindManyOptions, Repository, SelectQueryBuilder } from 'typeorm';
+
+import { BaseOrmRepository } from '@/utils/generics/base-orm.repository';
+import { Format } from '@/utils/types/format.types';
+
+import { NlpSampleState } from '..//types';
+import {
+  NlpValue,
+  NlpValueDtoConfig,
+  NlpValueFull,
+  NlpValueFullWithCount,
+  NlpValueTransformerDto,
+  NlpValueWithCount,
+  TNlpValueCount,
+} from '../dto/nlp-value.dto';
+import { NlpValueOrmEntity } from '../entities/nlp-value.entity';
+
+@Injectable()
+export class NlpValueRepository extends BaseOrmRepository<
+  NlpValueOrmEntity,
+  NlpValueTransformerDto,
+  NlpValueDtoConfig
+> {
+  /**
+   * Initializes the repository with relations and DTO classes used for value entities.
+   * @param repository The TypeORM repository for `NlpValueOrmEntity`.
+   */
+  constructor(
+    @InjectRepository(NlpValueOrmEntity)
+    repository: Repository<NlpValueOrmEntity>,
+  ) {
+    super(repository, ['entity'], {
+      PlainCls: NlpValue,
+      FullCls: NlpValueFull,
+    });
+  }
+
+  /**
+   * Retrieves values with the count of linked training samples, using the requested format.
+   * @param format Determines whether plain or full DTOs are returned.
+   * @param options Optional TypeORM find options to refine filtering, sorting, or pagination.
+   * @returns Array of values enriched with their linked training sample counts.
+   * @throws Logs the underlying error before rethrowing when the query fails.
+   */
+  async findWithCount<F extends Format>(
+    format: F,
+    options: FindManyOptions<NlpValueOrmEntity> = {},
+  ): Promise<TNlpValueCount<F>[]> {
+    try {
+      const results = await this.buildCountQuery(format, options).getMany();
+
+      return results.map((entity) => {
+        const payload = {
+          ...entity,
+          nlpSamplesCount: entity.nlpSamplesCount ?? 0,
+        };
+        const dto =
+          format === Format.FULL
+            ? plainToInstance(NlpValueFullWithCount, payload)
+            : plainToInstance(NlpValueWithCount, payload);
+
+        return dto as TNlpValueCount<F>;
+      });
+    } catch (error) {
+      this.logger.error(`Error in findWithCount: ${error.message}`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * Builds the query used to load values alongside their linked training sample counts.
+   * @param format Determines which relations are joined and selected.
+   * @param options Optional TypeORM find options to apply to the query builder.
+   * @returns A query builder prepared with the requested joins, ordering, and pagination.
+   */
+  private buildCountQuery(
+    format: Format,
+    options: FindManyOptions<NlpValueOrmEntity>,
+  ): SelectQueryBuilder<NlpValueOrmEntity> {
+    const qb = this.repository.createQueryBuilder('value');
+
+    if (format === Format.FULL) {
+      qb.leftJoinAndSelect('value.entity', 'entity');
+    } else {
+      qb.leftJoin('value.entity', 'entity');
+    }
+
+    qb.loadRelationCountAndMap(
+      'value.nlpSamplesCount',
+      'value.sampleEntities',
+      'sampleEntity',
+      (relationQb) =>
+        relationQb
+          .leftJoin('sampleEntity.sample', 'sample')
+          .where('sample.type = :trainType', {
+            trainType: NlpSampleState.train,
+          }),
+    );
+
+    const findOptions: FindManyOptions<NlpValueOrmEntity> = {};
+
+    if (options.where) {
+      findOptions.where = options.where;
+    }
+
+    const hasOrder = options.order && Object.keys(options.order).length > 0;
+
+    if (hasOrder) {
+      findOptions.order = options.order;
+    }
+
+    if (Object.keys(findOptions).length > 0) {
+      qb.setFindOptions(findOptions);
+    }
+
+    if (!hasOrder) {
+      qb.addOrderBy('value.createdAt', 'DESC');
+    }
+
+    if (typeof options.skip === 'number') {
+      qb.skip(options.skip);
+    }
+
+    if (typeof options.take === 'number') {
+      qb.take(options.take);
+    }
+
+    return qb;
+  }
+}

package/src/nlp/seeds/nlp-entity.seed-model.ts

@@ -0,0 +1,16 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { NlpEntityCreateDto } from '../dto/nlp-entity.dto';
+
+export const nlpEntityModels: NlpEntityCreateDto[] = [
+  {
+    name: 'intent',
+    lookups: ['trait'],
+    doc: `"intent" refers to the underlying purpose or goal that a piece of text aims to convey. Identifying the intent involves determining what action or response the text is prompting. For instance, in customer service chatbots, recognizing the intent behind a user's message, such as "book a flight" or "check account balance," is crucial to provide accurate and relevant responses`,
+    builtin: true,
+  },
+];

package/src/nlp/seeds/nlp-entity.seed.ts

@@ -0,0 +1,27 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmSeeder } from '@/utils/generics/base-orm.seeder';
+
+import {
+  NlpEntityDtoConfig,
+  NlpEntityTransformerDto,
+} from '../dto/nlp-entity.dto';
+import { NlpEntityOrmEntity } from '../entities/nlp-entity.entity';
+import { NlpEntityRepository } from '../repositories/nlp-entity.repository';
+
+@Injectable()
+export class NlpEntitySeeder extends BaseOrmSeeder<
+  NlpEntityOrmEntity,
+  NlpEntityTransformerDto,
+  NlpEntityDtoConfig
+> {
+  constructor(nlpEntityRepository: NlpEntityRepository) {
+    super(nlpEntityRepository);
+  }
+}

package/src/nlp/seeds/nlp-value.seed-model.ts

@@ -0,0 +1,9 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { NlpValueCreateDto } from '../dto/nlp-value.dto';
+
+export const nlpValueModels: NlpValueCreateDto[] = [];

package/src/nlp/seeds/nlp-value.seed.ts

@@ -0,0 +1,47 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { Injectable } from '@nestjs/common';
+
+import { BaseOrmSeeder } from '@/utils/generics/base-orm.seeder';
+
+import {
+  NlpValueCreateDto,
+  NlpValueDtoConfig,
+  NlpValueTransformerDto,
+} from '../dto/nlp-value.dto';
+import { NlpValueOrmEntity } from '../entities/nlp-value.entity';
+import { NlpEntityRepository } from '../repositories/nlp-entity.repository';
+import { NlpValueRepository } from '../repositories/nlp-value.repository';
+
+@Injectable()
+export class NlpValueSeeder extends BaseOrmSeeder<
+  NlpValueOrmEntity,
+  NlpValueTransformerDto,
+  NlpValueDtoConfig
+> {
+  constructor(
+    nlpValueRepository: NlpValueRepository,
+    private readonly nlpEntityRepository: NlpEntityRepository,
+  ) {
+    super(nlpValueRepository);
+  }
+
+  async seed(models: NlpValueCreateDto[]): Promise<boolean> {
+    if (await this.isEmpty()) {
+      const entities = await this.nlpEntityRepository.findAll();
+      const modelDtos = models.map((v) => ({
+        ...v,
+        entity: entities.find(({ name }) => name === v.entity)?.id as string,
+      }));
+      await this.repository.createMany(modelDtos);
+
+      return true;
+    }
+
+    return false;
+  }
+}

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

@@ -0,0 +1,212 @@
+/*
+ * Hexabot — Fair Core License (FCL-1.0-ALv2)
+ * Copyright (c) 2025 Hexastack.
+ * Full terms: see LICENSE.md.
+ */
+
+import { CACHE_MANAGER } from '@nestjs/cache-manager';
+import { BadRequestException, Inject, Injectable } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { Cache } from 'cache-manager';
+import { In } from 'typeorm';
+
+import { LoggerService } from '@/logger/logger.service';
+import { NLP_MAP_CACHE_KEY } from '@/utils/constants/cache';
+import { Cacheable } from '@/utils/decorators/cacheable.decorator';
+import { BaseOrmService } from '@/utils/generics/base-orm.service';
+
+import { Lookup, NlpCacheMap, NlpSampleEntityValue } from '..//types';
+import {
+  NlpEntity,
+  NlpEntityDtoConfig,
+  NlpEntityFull,
+  NlpEntityTransformerDto,
+} from '../dto/nlp-entity.dto';
+import { NlpEntityOrmEntity } from '../entities/nlp-entity.entity';
+import { NlpEntityRepository } from '../repositories/nlp-entity.repository';
+
+import { NlpValueService } from './nlp-value.service';
+
+@Injectable()
+export class NlpEntityService extends BaseOrmService<
+  NlpEntityOrmEntity,
+  NlpEntityTransformerDto,
+  NlpEntityDtoConfig
+> {
+  constructor(
+    readonly repository: NlpEntityRepository,
+    @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,
+    private readonly nlpValueService: NlpValueService,
+    private readonly logger: LoggerService,
+  ) {
+    super(repository);
+  }
+
+  /**
+   * Deletes an entity by its ID.
+   *
+   * @param id - The ID of the entity to delete.
+   *
+   * @returns A promise that resolves when the entity is deleted.
+   */
+  async deleteCascadeOne(id: string) {
+    return await this.repository.deleteOne(id);
+  }
+
+  /**
+   * Updates the `weight` field of a specific NLP entity by its ID.
+   *
+   * This method is part of the NLP-based blocks prioritization strategy.
+   * The weight influences the scoring of blocks when multiple blocks match a user's input.
+   * @param id - The unique identifier of the entity to update.
+   * @param updatedWeight - The new weight to assign. Must be a positive number.
+   * @throws Error if the weight is not a positive number.
+   * @returns A promise that resolves to the updated entity.
+   */
+  async updateWeight(id: string, updatedWeight: number): Promise<NlpEntity> {
+    if (updatedWeight <= 0) {
+      throw new BadRequestException(
+        'Weight must be a strictly positive number',
+      );
+    }
+
+    return await this.repository.updateOne(id, { weight: updatedWeight });
+  }
+
+  /**
+   * Stores new entities based on the sample text and sample entities.
+   * Deletes all values relative to this entity before deleting the entity itself.
+   * This is typically used during an import process.
+   *
+   * @param sampleText - The text sample containing NLP entities.
+   * @param sampleEntities - The list of sample entity values to be processed.
+   * @param lookups - Optional list of lookups used to classify the entities.
+   *
+   * @returns A promise that resolves when the entities and their values are stored.
+   */
+  async storeNewEntities(
+    sampleText: string,
+    sampleEntities: NlpSampleEntityValue[],
+    lookups: Lookup[] = ['keywords'],
+  ) {
+    // Extract entity names from sampleEntities
+    const entities = sampleEntities.map((e) => e.entity);
+    const uniqueEntities = Array.from(new Set(entities));
+
+    // Retrieve stored entities
+    let storedEntities = uniqueEntities.length
+      ? await this.find({ where: { name: In(uniqueEntities) } })
+      : [];
+    // Find newly added entities
+    const entitiesToAdd = entities
+      .filter((e) => storedEntities.findIndex((se) => se.name === e) === -1)
+      .filter((e, idx, self) => self.indexOf(e) === idx)
+      .map((e) => ({ name: e, lookups }));
+    // Create new entities
+    const newEntities = await this.createMany(entitiesToAdd);
+    // Add new entities to the storedEntities array
+    storedEntities = storedEntities.concat(newEntities);
+
+    return await this.nlpValueService.storeNewValues(
+      sampleText,
+      sampleEntities,
+      storedEntities,
+    );
+  }
+
+  /**
+   * Stores only new entities based on the provided sample entities and returns them.
+   * It creates new entities if they do not already exist.
+   *
+   * @param sampleEntities - The list of sample entity values to process.
+   *
+   * @returns A promise that resolves with the list of stored entities, including their IDs.
+   */
+  storeEntities(sampleEntities: NlpSampleEntityValue[]): Promise<NlpEntity[]> {
+    const uniqueEntities = Array.from(
+      new Set(sampleEntities.map((entity) => entity.entity)),
+    );
+    const findOrCreate = uniqueEntities.map((entityName) =>
+      this.findOneOrCreate(
+        { where: { name: entityName } },
+        { name: entityName },
+      ),
+    );
+
+    return Promise.all(findOrCreate);
+  }
+
+  /**
+   * Clears the NLP map cache
+   */
+  async clearCache() {
+    await this.cacheManager.del(NLP_MAP_CACHE_KEY);
+  }
+
+  /**
+   * Event handler for Nlp Entity updates. Listens to 'hook:nlpEntity:*' events
+   * and invalidates the cache for nlp entities when triggered.
+   */
+  @OnEvent('hook:nlpEntity:*')
+  async handleNlpEntityUpdateEvent() {
+    try {
+      await this.clearCache();
+    } catch (error) {
+      this.logger.error('Failed to clear NLP entity cache', error);
+    }
+  }
+
+  /**
+   * Event handler for Nlp Value updates. Listens to 'hook:nlpValue:*' events
+   * and invalidates the cache for nlp values when triggered.
+   */
+  @OnEvent('hook:nlpValue:*')
+  async handleNlpValueUpdateEvent() {
+    try {
+      await this.clearCache();
+    } catch (error) {
+      this.logger.error('Failed to clear NLP value cache', error);
+    }
+  }
+
+  /**
+   * Retrieves NLP entity lookup information for the given list of entity names.
+   *
+   * This method queries the database for nlp entities,
+   * transforms the result into a map structure where each key is
+   * the entity name and each value contains metadata (id, weight, and list of values),
+   * and caches the result using the configured cache key.
+   *
+   * @returns A Promise that resolves to a map of entity name to its corresponding lookup metadata.
+   */
+  @Cacheable(NLP_MAP_CACHE_KEY)
+  async getNlpMap(): Promise<NlpCacheMap> {
+    const entities = await this.findAllAndPopulate();
+
+    return entities.reduce((acc, curr) => {
+      acc.set(curr.name, curr);
+
+      return acc;
+    }, new Map());
+  }
+
+  /**
+   * Retrieves all NLP entities that declare at least one of the specified
+   * lookup strategies.
+   *
+   * @async
+   * @param lookups - One or more lookup strategies to match
+   * against (e.g., {@link LookupStrategy.keywords}, {@link LookupStrategy.pattern}).
+   * An entity is included in the result if **any** of these strategies is found
+   * in its own `lookups` array.
+   * @returns A promise that resolves to the
+   * collection of matching entities.
+   */
+  async getNlpEntitiesByLookup(lookups: Lookup[]): Promise<NlpEntityFull[]> {
+    const entities = [...(await this.getNlpMap()).values()];
+
+    return entities.filter((e) => {
+      return lookups.filter((l) => e.lookups.includes(l)).length > 0;
+    });
+  }
+}