UniqAI/hexabot
1
0
Fork 0
mirror of https://github.com/hexastack/hexabot synced 2025-04-04 05:11:09 +00:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

feat: add outcome attribute

Browse Source
This commit is contained in:
Mohamed Marrouchi 2025-03-03 09:54:31 +01:00
parent b3a5bc2ac3
commit 7e48eb6067
10 changed files with 267 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
api/src/chat/controllers/block.controller.spec.ts
View File

@ -1,5 +1,5 @@
/*
* Copyright © 2024 Hexastack. All rights reserved.
* Copyright © 2025 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.
@ -251,6 +251,7 @@ describe('BlockController', () => {
name: 'block with nextBlocks',
nextBlocks: [hasNextBlocks.id],
patterns: ['Hi'],
outcomes: [],
trigger_labels: [],
assign_labels: [],
trigger_channels: [],

19
api/src/chat/dto/block.dto.ts
View File

@ -1,5 +1,5 @@
/*
* Copyright © 2024 Hexastack. All rights reserved.
* Copyright © 2025 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.
@ -45,6 +45,14 @@ export class BlockCreateDto {
@IsPatternList({ message: 'Patterns list is invalid' })
patterns?: Pattern[] = [];
@ApiPropertyOptional({
description: "Block's outcomes",
type: Array,
})
@IsOptional()
@IsArray({ message: 'Outcomes are invalid' })
outcomes?: string[] = [];
@ApiPropertyOptional({ description: 'Block trigger labels', type: Array })
@IsOptional()
@IsArray()
@ -120,6 +128,7 @@ export class BlockCreateDto {
export class BlockUpdateDto extends PartialType(
OmitType(BlockCreateDto, [
'patterns',
'outcomes',
'trigger_labels',
'assign_labels',
'trigger_channels',
@ -130,6 +139,14 @@ export class BlockUpdateDto extends PartialType(
@IsPatternList({ message: 'Patterns list is invalid' })
patterns?: Pattern[];
@ApiPropertyOptional({
description: "Block's outcomes",
type: Array,
})
@IsOptional()
@IsArray({ message: 'Outcomes are invalid' })
outcomes?: string[];
@ApiPropertyOptional({ description: 'Block trigger labels', type: Array })
@IsOptional()
@IsArray()

6
api/src/chat/schemas/block.schema.ts
View File

@ -42,6 +42,12 @@ export class BlockStub extends BaseSchema {
})
patterns: Pattern[];
@Prop({
type: Object,
default: [],
})
outcomes: string[];
@Prop([
{
type: MongooseSchema.Types.ObjectId,

1
api/src/chat/schemas/types/button.ts
View File

@ -40,4 +40,5 @@ export enum PayloadType {
attachments = 'attachments',
quick_reply = 'quick_reply',
button = 'button',
outcome = 'outcome',
}

38
api/src/chat/schemas/types/message.ts
View File

@ -6,14 +6,6 @@
* 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).
*/
/*
* Copyright © 2025 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 { z } from 'zod';
import { PluginName } from '@/plugins/types';
@ -62,6 +54,7 @@ export enum OutgoingMessageFormat {
attachment = 'attachment',
list = 'list',
carousel = 'carousel',
system = 'system',
}
export const outgoingMessageFormatSchema = z.nativeEnum(OutgoingMessageFormat);
@ -147,6 +140,15 @@ export type StdOutgoingAttachmentMessage = z.infer<
typeof stdOutgoingAttachmentMessageSchema
>;
export const stdOutgoingSystemMessageSchema = z.object({
outcome: z.string().optional(), // "any" or any other string (in snake case)
data: z.any().optional(),
});
export type StdOutgoingSystemMessage = z.infer<
typeof stdOutgoingSystemMessageSchema
>;
export const pluginNameSchema = z
.string()
.regex(/-plugin$/) as z.ZodType<PluginName>;
@ -290,7 +292,16 @@ export type StdOutgoingAttachmentEnvelope = z.infer<
typeof stdOutgoingAttachmentEnvelopeSchema
>;
export const stdOutgoingEnvelopeSchema = z.union([
export const stdOutgoingSystemEnvelopeSchema = z.object({
format: z.literal(OutgoingMessageFormat.system),
message: stdOutgoingSystemMessageSchema,
});
export type StdOutgoingSystemEnvelope = z.infer<
typeof stdOutgoingSystemEnvelopeSchema
>;
export const stdOutgoingMessageEnvelopeSchema = z.union([
stdOutgoingTextEnvelopeSchema,
stdOutgoingQuickRepliesEnvelopeSchema,
stdOutgoingButtonsEnvelopeSchema,
@ -298,6 +309,15 @@ export const stdOutgoingEnvelopeSchema = z.union([
stdOutgoingAttachmentEnvelopeSchema,
]);
export type StdOutgoingMessageEnvelope = z.infer<
typeof stdOutgoingMessageEnvelopeSchema
>;
export const stdOutgoingEnvelopeSchema = z.union([
stdOutgoingMessageEnvelopeSchema,
stdOutgoingSystemEnvelopeSchema,
]);
export type StdOutgoingEnvelope = z.infer<typeof stdOutgoingEnvelopeSchema>;
// is-valid-message-text validation

138
api/src/chat/services/block.service.ts
View File

@ -11,6 +11,7 @@ import { OnEvent } from '@nestjs/event-emitter';
import { AttachmentService } from '@/attachment/services/attachment.service';
import EventWrapper from '@/channel/lib/EventWrapper';
import { ChannelName } from '@/channel/types';
import { ContentService } from '@/cms/services/content.service';
import { CONSOLE_CHANNEL_NAME } from '@/extensions/channels/console/settings';
import { NLU } from '@/helper/types';
@ -27,11 +28,13 @@ import { BlockDto } from '../dto/block.dto';
import { BlockRepository } from '../repositories/block.repository';
import { Block, BlockFull, BlockPopulate } from '../schemas/block.schema';
import { Label } from '../schemas/label.schema';
import { Subscriber } from '../schemas/subscriber.schema';
import { Context } from '../schemas/types/context';
import {
BlockMessage,
OutgoingMessageFormat,
StdOutgoingEnvelope,
StdOutgoingSystemEnvelope,
} from '../schemas/types/message';
import { NlpPattern, PayloadPattern } from '../schemas/types/pattern';
import { Payload, StdQuickReply } from '../schemas/types/quick-reply';
@ -57,10 +60,75 @@ export class BlockService extends BaseService<
super(repository);
}
/**
* Filters an array of blocks based on the specified channel.
*
* This function ensures that only blocks that are either:
* - Not restricted to specific trigger channels (`trigger_channels` is undefined or empty), or
* - Explicitly allow the given channel (or the console channel)
*
* are included in the returned array.
*
* @param blocks - The list of blocks to be filtered.
* @param channel - The name of the channel to filter blocks by.
*
* @returns The filtered array of blocks that are allowed for the given channel.
*/
filterBlocksByChannel<B extends Block | BlockFull>(
blocks: B[],
channel: ChannelName,
) {
return blocks.filter((b) => {
return (
!b.trigger_channels ||
b.trigger_channels.length === 0 ||
[...b.trigger_channels, CONSOLE_CHANNEL_NAME].includes(channel)
);
});
}
/**
* Filters an array of blocks based on subscriber labels.
*
* This function selects blocks that either:
* - Have no trigger labels (making them applicable to all subscribers), or
* - Contain at least one trigger label that matches a label from the provided list.
*
* The filtered blocks are then **sorted** in descending order by the number of trigger labels,
* ensuring that blocks with more specific targeting (more trigger labels) are prioritized.
*
* @param blocks - The list of blocks to be filtered.
* @param labels - The list of subscriber labels to match against.
* @returns The filtered and sorted list of blocks.
*/
filterBlocksBySubscriberLabels<B extends Block | BlockFull>(
blocks: B[],
profile?: Subscriber,
) {
if (!profile) {
return blocks;
}
return (
blocks
.filter((b) => {
const triggerLabels = b.trigger_labels.map((l) =>
typeof l === 'string' ? l : l.id,
);
return (
triggerLabels.length === 0 ||
triggerLabels.some((l) => profile.labels.includes(l))
);
})
// Priority goes to block who target users with labels
.sort((a, b) => b.trigger_labels.length - a.trigger_labels.length)
);
}
/**
* Find a block whose patterns matches the received event
*
* @param blocks blocks Starting/Next blocks in the conversation flow
* @param filteredBlocks blocks Starting/Next blocks in the conversation flow
* @param event Received channel's message
*
* @returns The block that matches
@ -77,37 +145,15 @@ export class BlockService extends BaseService<
let block: BlockFull | undefined = undefined;
const payload = event.getPayload();
// Perform a filter on the specific channels
const channel = event.getHandler().getName();
blocks = blocks.filter((b) => {
return (
!b.trigger_channels ||
b.trigger_channels.length === 0 ||
[...b.trigger_channels, CONSOLE_CHANNEL_NAME].includes(channel)
);
});
// Perform a filter on trigger labels
let userLabels: string[] = [];
const profile = event.getSender();
if (profile && Array.isArray(profile.labels)) {
userLabels = profile.labels.map((l) => l);
}
blocks = blocks
.filter((b) => {
const trigger_labels = b.trigger_labels.map(({ id }) => id);
return (
trigger_labels.length === 0 ||
trigger_labels.some((l) => userLabels.includes(l))
);
})
// Priority goes to block who target users with labels
.sort((a, b) => b.trigger_labels.length - a.trigger_labels.length);
// Perform a filter to get the candidates blocks
const filteredBlocks = this.filterBlocksBySubscriberLabels(
this.filterBlocksByChannel(blocks, event.getHandler().getName()),
event.getSender(),
);
// Perform a payload match & pick last createdAt
if (payload) {
block = blocks
block = filteredBlocks
.filter((b) => {
return this.matchPayload(payload, b);
})
@ -131,7 +177,7 @@ export class BlockService extends BaseService<
}
// Perform a text pattern match
block = blocks
block = filteredBlocks
.filter((b) => {
return this.matchText(text, b);
})
@ -141,7 +187,7 @@ export class BlockService extends BaseService<
if (!block && nlp) {
// Find block pattern having the best match of nlp entities
let nlpBest = 0;
blocks.forEach((b, index, self) => {
filteredBlocks.forEach((b, index, self) => {
const nlpPattern = this.matchNLP(nlp, b);
if (nlpPattern && nlpPattern.length > nlpBest) {
nlpBest = nlpPattern.length;
@ -295,6 +341,36 @@ export class BlockService extends BaseService<
});
}
/**
* Matches an outcome-based block from a list of available blocks
* based on the outcome of a system message.
*
* @param blocks - An array of blocks to search for a matching outcome.
* @param envelope - The system message envelope containing the outcome to match.
*
* @returns - Returns the first matching block if found, otherwise returns `undefined`.
*/
matchOutcome(
blocks: Block[],
event: EventWrapper<any, any>,
envelope: StdOutgoingSystemEnvelope,
) {
// Perform a filter to get the candidates blocks
const filteredBlocks = this.filterBlocksBySubscriberLabels(
this.filterBlocksByChannel(blocks, event.getHandler().getName()),
event.getSender(),
);
return filteredBlocks.find((b) => {
return b.patterns
.filter(
(p) => typeof p === 'object' && 'type' in p && p.type === 'outcome',
)
.some((p: PayloadPattern) =>
['any', envelope.message.outcome].includes(p.value),
);
});
}
/**
* Replaces tokens with their context variables values in the provided text message
*

4
api/src/chat/services/bot.service.spec.ts
View File

@ -1,5 +1,5 @@
/*
* Copyright © 2024 Hexastack. All rights reserved.
* Copyright © 2025 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.
@ -201,7 +201,7 @@ describe('BlockService', () => {
let hasBotSpoken = false;
const clearMock = jest
.spyOn(botService, 'findBlockAndSendReply')
.spyOn(botService, 'triggerBlock')
.mockImplementation(
(
actualEvent: WebEventWrapper<typeof WEB_CHANNEL_NAME>,

160
api/src/chat/services/bot.service.ts
View File

@ -21,8 +21,11 @@ import {
getDefaultConversationContext,
} from '../schemas/conversation.schema';
import { Context } from '../schemas/types/context';
import { IncomingMessageType } from '../schemas/types/message';
import { SubscriberContext } from '../schemas/types/subscriberContext';
import {
IncomingMessageType,
OutgoingMessageFormat,
StdOutgoingMessageEnvelope,
} from '../schemas/types/message';
import { BlockService } from './block.service';
import { ConversationService } from './conversation.service';
@ -40,40 +43,24 @@ export class BotService {
) {}
/**
* Sends a processed message to the user based on a specified content block.
* Replaces tokens within the block with context data, handles fallback scenarios,
* and assigns relevant labels to the user.
* Sends a message to the subscriber via the appropriate messaging channel and handles related events.
*
* @param event - The incoming message or action that triggered the bot's response.
* @param envelope - The outgoing message envelope containing the bot's response.
* @param block - The content block containing the message and options to be sent.
* @param context - Optional. The conversation context object, containing relevant data for personalization.
* @param fallback - Optional. Boolean flag indicating if this is a fallback message when no appropriate response was found.
* @param conversationId - Optional. The conversation ID to link the message to a specific conversation thread.
*
* @returns A promise that resolves with the message response, including the message ID.
*/
async sendMessageToSubscriber(
envelope: StdOutgoingMessageEnvelope,
event: EventWrapper<any, any>,
block: BlockFull,
context?: Context,
fallback?: boolean,
conservationId?: string,
) {
context = context || getDefaultConversationContext();
fallback = typeof fallback !== 'undefined' ? fallback : false;
const options = block.options;
this.logger.debug('Sending message ... ', event.getSenderForeignId());
// Process message : Replace tokens with context data and then send the message
const recipient = event.getSender();
const envelope = await this.blockService.processMessage(
block,
context,
recipient?.context as SubscriberContext,
fallback,
conservationId,
);
// Send message through the right channel
this.logger.debug('Sending message ... ', event.getSenderForeignId());
const response = await event
.getHandler()
.sendMessage(event, envelope, options, context);
@ -114,35 +101,56 @@ export class BotService {
);
this.logger.debug('Assigned labels ', blockLabels);
return response;
}
/**
* Finds an appropriate reply block and sends it to the user.
* If there are additional blocks or attached blocks, it continues the conversation flow.
* Ends the conversation if no further blocks are available.
* Processes and executes a block, handling its associated messages and flow logic.
*
* The function performs the following steps:
* 1. Retrieves the conversation context and recipient information.
* 2. Generates an outgoing message envelope from the block.
* 3. Sends the message to the subscriber unless it's a system message.
* 4. Handles block chaining:
* - If the block has an attached block, it recursively triggers the attached block.
* - If the block has multiple possible next blocks, it determines the next block based on the outcome of the system message.
* - If there are next blocks but no outcome-based matching, it updates the conversation state for the next steps.
* 5. If no further blocks exist, it ends the flow execution.
*
* @param event - The incoming message or action that initiated this response.
* @param convo - The current conversation context and flow.
* @param block - The content block to be processed and sent.
* @param fallback - Boolean indicating if this is a fallback response in case no appropriate reply was found.
*
* @returns A promise that continues or ends the conversation based on available blocks.
* @returns A promise that either continues or ends the flow execution based on the available blocks.
*/
async findBlockAndSendReply(
async triggerBlock(
event: EventWrapper<any, any>,
convo: Conversation,
block: BlockFull,
fallback: boolean,
fallback: boolean = false,
) {
try {
await this.sendMessageToSubscriber(
event,
const context = convo.context || getDefaultConversationContext();
const recipient = event.getSender();
const envelope = await this.blockService.processMessage(
block,
convo.context,
context,
recipient?.context,
fallback,
convo.id,
);
if (envelope.format !== OutgoingMessageFormat.system) {
await this.sendMessageToSubscriber(
envelope,
event,
block,
context,
fallback,
);
}
if (block.attachedBlock) {
// Sequential messaging ?
try {
@ -154,12 +162,7 @@ export class BotService {
'No attached block to be found with id ' + block.attachedBlock,
);
}
return await this.findBlockAndSendReply(
event,
convo,
attachedBlock,
fallback,
);
return await this.triggerBlock(event, convo, attachedBlock, fallback);
} catch (err) {
this.logger.error('Unable to retrieve attached block', err);
this.eventEmitter.emit('hook:conversation:end', convo, true);
@ -168,20 +171,47 @@ export class BotService {
Array.isArray(block.nextBlocks) &&
block.nextBlocks.length > 0
) {
// Conversation continues : Go forward to next blocks
this.logger.debug('Conversation continues ...', convo.id);
const nextIds = block.nextBlocks.map(({ id }) => id);
try {
await this.conversationService.updateOne(convo.id, {
current: block.id,
next: nextIds,
});
if (envelope.format === OutgoingMessageFormat.system) {
// System message: Trigger the next block based on the outcome
this.logger.debug(
'Matching the outcome against the next blocks ...',
convo.id,
);
const match = this.blockService.matchOutcome(
block.nextBlocks,
event,
envelope,
);
if (match) {
const nextBlock = await this.blockService.findOneAndPopulate(
match.id,
);
if (!nextBlock) {
throw new Error(
'No attached block to be found with id ' +
block.attachedBlock,
);
}
return await this.triggerBlock(event, convo, nextBlock, fallback);
} else {
this.logger.warn(
'Block outcome did not match any of the next blocks',
convo,
);
}
} else {
// Conversation continues : Go forward to next blocks
this.logger.debug('Conversation continues ...', convo.id);
const nextIds = block.nextBlocks.map(({ id }) => id);
await this.conversationService.updateOne(convo.id, {
current: block.id,
next: nextIds,
});
}
} catch (err) {
this.logger.error(
'Unable to update conversation when going next',
convo,
err,
);
this.logger.error('Unable to continue the flow', convo, err);
return;
}
} else {
@ -275,12 +305,7 @@ export class BotService {
// Otherwise, old captured const value may be replaced by another const value
!fallback,
);
await this.findBlockAndSendReply(
event,
updatedConversation,
next,
fallback,
);
await this.triggerBlock(event, updatedConversation, next, fallback);
} catch (err) {
this.logger.error('Unable to store context data!', err);
return this.eventEmitter.emit('hook:conversation:end', convo, true);
@ -376,12 +401,7 @@ export class BotService {
subscriber.id,
block.name,
);
return this.findBlockAndSendReply(
event,
updatedConversation,
block,
false,
);
return this.triggerBlock(event, updatedConversation, block, false);
} catch (err) {
this.logger.error('Unable to store context data!', err);
this.eventEmitter.emit('hook:conversation:end', convo, true);
@ -459,7 +479,7 @@ export class BotService {
'No global fallback block defined, sending a message ...',
err,
);
this.sendMessageToSubscriber(event, {
const globalFallbackBlock = {
id: 'global-fallback',
name: 'Global Fallback',
message: settings.chatbot_settings.fallback_message,
@ -473,7 +493,19 @@ export class BotService {
createdAt: new Date(),
updatedAt: new Date(),
attachedBlock: null,
} as any as BlockFull);
} as any as BlockFull;
const envelope = await this.blockService.processMessage(
globalFallbackBlock,
getDefaultConversationContext(),
{ vars: {} }, // @TODO: use subscriber ctx
);
await this.sendMessageToSubscriber(
envelope as StdOutgoingMessageEnvelope,
event,
globalFallbackBlock,
);
}
}
// Do nothing ...

1
api/src/i18n/services/translation.service.spec.ts
View File

@ -136,6 +136,7 @@ describe('TranslationService', () => {
const block: Block = {
name: 'Ollama Plugin',
patterns: [],
outcomes: [],
assign_labels: [],
trigger_channels: [],
trigger_labels: [],

5
api/src/utils/test/fixtures/block.ts vendored
View File

@ -35,6 +35,7 @@ export const blocks: TBlockFixtures['values'][] = [
{
name: 'hasNextBlocks',
patterns: ['Hi'],
outcomes: [],
category: null,
options: {
typing: 0,
@ -53,6 +54,7 @@ export const blocks: TBlockFixtures['values'][] = [
{
name: 'hasPreviousBlocks',
patterns: ['colors'],
outcomes: [],
category: null,
options: {
typing: 0,
@ -90,6 +92,7 @@ export const blocks: TBlockFixtures['values'][] = [
{
name: 'buttons',
patterns: ['about'],
outcomes: [],
category: null,
options: {
typing: 0,
@ -127,6 +130,7 @@ export const blocks: TBlockFixtures['values'][] = [
{
name: 'attachment',
patterns: ['image'],
outcomes: [],
category: null,
options: {
typing: 0,
@ -153,6 +157,7 @@ export const blocks: TBlockFixtures['values'][] = [
{
name: 'test',
patterns: ['yes'],
outcomes: [],
category: null,
//to be verified
options: {