@botonic/plugin-ai-agents 0.46.1 → 2.23.0

package/src/services/hubtype-api-client.ts

@@ -1,240 +0,0 @@
-/* eslint-disable @typescript-eslint/naming-convention */
-import type { BotContext } from '@botonic/core'
-import axios from 'axios'
-
-import { HUBTYPE_API_URL } from '../constants'
-import type { AgenticInputMessage, Chunk } from '../types'
-import type {
-  GetMessagesV2Options,
-  GetMessagesV2Result,
-  HubtypeAssistantMessageV2,
-  HubtypeMessage,
-  HubtypeMessageV2,
-  HubtypeToolMessageV2,
-  MessageHistoryResponseV2,
-  MessageHistoryV2Params,
-  TrackLlmRunsData,
-} from './types'
-
-export class HubtypeApiClient {
-  private readonly authToken: string
-
-  constructor(authToken: string) {
-    this.authToken = authToken
-  }
-
-  async retrieveSimilarChunks(
-    query: string,
-    sourceIds: string[]
-  ): Promise<Chunk[]> {
-    const url = `${HUBTYPE_API_URL}/external/v1/ai/knowledge_base/similar_chunks/`
-    const headers = {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${this.authToken}`,
-    }
-    const params = {
-      query,
-      source_ids: sourceIds,
-      num_chunks: 5,
-    }
-    const response = await axios.post(url, params, { headers })
-    const chunks = response.data.chunks.map((chunk: Chunk) => ({
-      id: chunk.id,
-      text: chunk.text,
-    }))
-    return chunks
-  }
-
-  async getLocalMessages(
-    maxMemoryLength: number
-  ): Promise<AgenticInputMessage[]> {
-    const localBotonicState =
-      typeof globalThis !== 'undefined' && globalThis.localStorage
-        ? globalThis.localStorage.getItem('botonicState')
-        : null
-    const botonicState = JSON.parse(localBotonicState || '{}')
-    const messages = botonicState.messages
-    const filteredMessages = messages
-      .filter(message => message.data.text)
-      .map(message => ({
-        role: message.sentBy === 'user' ? 'user' : 'assistant',
-        content: message.data.text,
-      }))
-      .map(message => this.formatMessage(message))
-    return filteredMessages.slice(-maxMemoryLength)
-  }
-
-  async getMessages(
-    botContext: BotContext,
-    maxMemoryLength: number
-  ): Promise<AgenticInputMessage[]> {
-    const url = `${HUBTYPE_API_URL}/external/v1/ai/agent/message_history/`
-    const headers = {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${this.authToken}`,
-    }
-    const params = {
-      last_message_id: botContext.input.message_id,
-      num_messages: maxMemoryLength,
-    }
-
-    try {
-      const response = await axios.get<{ messages: HubtypeMessage[] }>(url, {
-        headers,
-        params,
-      })
-      const messages = response.data.messages
-      return messages.map(message => this.formatMessage(message))
-    } catch (error) {
-      console.error(error)
-      throw new Error('Failed to get messages from Hubtype')
-    }
-  }
-
-  async getMessagesV2(
-    botContext: BotContext,
-    options: GetMessagesV2Options = {}
-  ): Promise<GetMessagesV2Result> {
-    const url = `${HUBTYPE_API_URL}/external/v2/ai/agent/message_history/`
-    const headers = {
-      'Content-Type': 'application/json',
-      Authorization: `Bearer ${this.authToken}`,
-    }
-    const params: MessageHistoryV2Params = {
-      last_message_id: botContext.input.message_id,
-      ...(options.maxMessages !== undefined && {
-        max_messages: options.maxMessages,
-      }),
-      ...(options.includeToolCalls !== undefined && {
-        include_tool_calls: options.includeToolCalls,
-      }),
-      ...(options.maxFullToolResults !== undefined && {
-        max_full_tool_results: options.maxFullToolResults,
-      }),
-      ...(options.debugMode !== undefined && {
-        debug_mode: options.debugMode,
-      }),
-    }
-
-    try {
-      const response = await axios.get<MessageHistoryResponseV2>(url, {
-        headers,
-        params,
-      })
-      const { messages, conversation_id, truncated } = response.data
-      const formattedMessages = messages
-        .map(message => this.formatMessageV2(message))
-        .filter((message): message is AgenticInputMessage => message !== null)
-      return {
-        messages: formattedMessages,
-        conversationId: conversation_id,
-        truncated,
-      }
-    } catch (error) {
-      console.error(error)
-      throw new Error('Failed to get messages from Hubtype V2 API')
-    }
-  }
-
-  private formatMessageV2(
-    message: HubtypeMessageV2
-  ): AgenticInputMessage | null {
-    switch (message.role) {
-      case 'user':
-        return {
-          role: 'user',
-          content: message.content ?? '',
-        }
-      case 'assistant': {
-        const assistantMessage = message as HubtypeAssistantMessageV2
-        // If assistant message has tool_calls, include them for context
-        // Using double assertion as the OpenAI API supports this format,
-        // but the agents SDK types are more restrictive
-        if (
-          assistantMessage.tool_calls &&
-          assistantMessage.tool_calls.length > 0
-        ) {
-          return {
-            role: 'assistant',
-            content: assistantMessage.content ?? '',
-            tool_calls: assistantMessage.tool_calls.map(tc => ({
-              id: tc.id,
-              type: tc.type,
-              function: {
-                name: tc.function.name,
-                arguments: tc.function.arguments,
-              },
-            })),
-          } as unknown as AgenticInputMessage
-        }
-        // Regular assistant message without tool_calls
-        return {
-          role: 'assistant',
-          content: [
-            {
-              type: 'output_text',
-              text: assistantMessage.content ?? '',
-            },
-          ],
-          status: 'completed',
-        }
-      }
-      case 'tool': {
-        // Tool messages provide context about previous tool executions
-        // Using double assertion as the OpenAI API supports this format,
-        // but the agents SDK types are more restrictive
-        const toolMessage = message as HubtypeToolMessageV2
-        return {
-          role: 'tool',
-          tool_call_id: toolMessage.tool_call_id,
-          content: toolMessage.content ?? '',
-        } as unknown as AgenticInputMessage
-      }
-      case 'system':
-        return {
-          role: 'system',
-          content: message.content ?? '',
-        }
-      default:
-        throw new Error(
-          `Invalid message role: ${(message as HubtypeMessageV2).role}`
-        )
-    }
-  }
-
-  async trackLlmRuns(botId: string, data: TrackLlmRunsData): Promise<void> {
-    // Not stop the bot execution if the tracking fails, just log the error
-    try {
-      const url = `${HUBTYPE_API_URL}/external/v2/conversational_apps/${botId}/track_llm_runs/`
-      const headers = {
-        'Content-Type': 'application/json',
-        Authorization: `Bearer ${this.authToken}`,
-      }
-      await axios.post(url, data, { headers })
-    } catch (error) {
-      console.error('Failed to track LLM runs:', error)
-    }
-  }
-
-  private formatMessage(message: HubtypeMessage): AgenticInputMessage {
-    if (message.role === 'user') {
-      return {
-        content: message.content,
-        role: 'user',
-      }
-    } else if (message.role === 'assistant') {
-      return {
-        role: 'assistant',
-        content: [
-          {
-            type: 'output_text',
-            text: message.content,
-          },
-        ],
-        status: 'completed',
-      }
-    } else {
-      throw new Error('Invalid message role')
-    }
-  }
-}

package/src/services/types.ts

@@ -1,106 +0,0 @@
-import type { AgenticInputMessage } from '../types'
-
-export enum TrackProductName {
-  AI_AGENT = 'ai_agent',
-}
-
-export enum TrackFeature {
-  AI_AGENT_RUN = 'ai_agent_run',
-  AI_AGENT_GUARDRAIL = 'ai_agent_guardrail',
-}
-
-export interface LlmRunData {
-  inference_id: string
-  is_test: boolean
-  product_name: string
-  deployment_name: string
-  model_name: string
-  feature: string
-  api_version: string
-  num_prompt_tokens: number
-  num_completion_tokens: number
-  duration_in_milliseconds: number
-  temperature: number
-  error: string | null
-}
-
-export interface TrackLlmRunsData {
-  llm_runs: LlmRunData[]
-}
-
-interface HubtypeAssistantMessage {
-  role: 'assistant'
-  content: string
-}
-
-interface HubtypeUserMessage {
-  role: 'user'
-  content: string
-}
-
-export type HubtypeMessage = HubtypeAssistantMessage | HubtypeUserMessage
-
-// V2 API Types
-interface HubtypeToolCall {
-  id: string
-  type: 'function'
-  function: {
-    name: string
-    arguments: string
-  }
-}
-
-interface HubtypeUserMessageV2 {
-  role: 'user'
-  content: string | null
-}
-
-export interface HubtypeAssistantMessageV2 {
-  role: 'assistant'
-  content: string | null
-  tool_calls?: HubtypeToolCall[] | null
-}
-
-export interface HubtypeToolMessageV2 {
-  role: 'tool'
-  content: string | null
-  tool_call_id: string
-}
-
-interface HubtypeSystemMessageV2 {
-  role: 'system'
-  content: string | null
-}
-
-export type HubtypeMessageV2 =
-  | HubtypeUserMessageV2
-  | HubtypeAssistantMessageV2
-  | HubtypeToolMessageV2
-  | HubtypeSystemMessageV2
-
-export interface MessageHistoryResponseV2 {
-  messages: HubtypeMessageV2[]
-  conversation_id: string | null
-  truncated: boolean
-}
-
-export interface GetMessagesV2Options {
-  maxMessages?: number
-  includeToolCalls?: boolean
-  maxFullToolResults?: number
-  debugMode?: boolean
-}
-
-export interface GetMessagesV2Result {
-  messages: AgenticInputMessage[]
-  conversationId: string | null
-  truncated: boolean
-}
-
-export interface MessageHistoryV2Params {
-  last_message_id: string
-  max_messages?: number
-  include_tool_calls?: boolean
-  max_full_tool_results?: number
-  debug_mode?: boolean
-}

package/src/structured-output/bot-executor.ts

@@ -1,21 +0,0 @@
-import type { BotExecutorMessage } from '@botonic/core'
-import z from 'zod'
-
-export type { BotExecutorMessage }
-
-export const BotExecutorSchema = z
-  .object({
-    type: z.enum(['botExecutor']),
-    content: z.object({
-      text: z.string(),
-      buttons: z.array(
-        z.object({
-          text: z.string(),
-          payload: z.string(),
-        })
-      ),
-    }),
-  })
-  .describe(
-    'A text message with buttons to allow the bot to execute a specific action. Use it only when asked explicitly in the prompt'
-  )

package/src/structured-output/carousel.ts

@@ -1,24 +0,0 @@
-import type { CarouselMessage } from '@botonic/core'
-import { z } from 'zod'
-
-export type { CarouselMessage }
-
-export const CarouselSchema = z
-  .object({
-    type: z.enum(['carousel']),
-    content: z.object({
-      text: z.string().nullable().optional(),
-      elements: z.array(
-        z.object({
-          title: z.string(),
-          subtitle: z.string(),
-          image: z.string(),
-          button: z.object({
-            text: z.string(),
-            url: z.string().nullable().optional(),
-          }),
-        })
-      ),
-    }),
-  })
-  .describe('A carousel message containing a list of elements')

package/src/structured-output/exit.ts

@@ -1,12 +0,0 @@
-import type { ExitMessage } from '@botonic/core'
-import z from 'zod'
-
-export type { ExitMessage }
-
-export const ExitSchema = z
-  .object({
-    type: z.enum(['exit']),
-  })
-  .describe(
-    'An exit message. This message should only be used to exit the agent due to out of context or the user asking to exit the conversation'
-  )

package/src/structured-output/index.ts

@@ -1,34 +0,0 @@
-import type { OutputMessage } from '@botonic/core'
-import { z } from 'zod'
-import { BotExecutorSchema } from './bot-executor'
-import { CarouselSchema } from './carousel'
-import { ExitSchema } from './exit'
-import { TextSchema } from './text'
-import { TextWithButtonsSchema } from './text-with-buttons'
-
-export interface Output {
-  messages: OutputMessage[]
-}
-
-const baseMessageSchemas = [
-  TextSchema,
-  TextWithButtonsSchema,
-  CarouselSchema,
-  ExitSchema,
-  BotExecutorSchema,
-] as const
-export const OutputSchema = z
-  .object({
-    messages: z.array(z.union(baseMessageSchemas)),
-  })
-  .describe('The messages to be sent to the user')
-
-export function getOutputSchema(
-  externalOutputMessagesSchemas: z.ZodObject<any>[]
-) {
-  return z.object({
-    messages: z.array(
-      z.union([...baseMessageSchemas, ...externalOutputMessagesSchemas])
-    ),
-  })
-}

package/src/structured-output/text-with-buttons.ts

@@ -1,29 +0,0 @@
-import type { TextWithButtonsMessage } from '@botonic/core'
-import z from 'zod'
-
-export type { TextWithButtonsMessage }
-
-export const TextWithButtonsSchema = z
-  .object({
-    type: z.enum(['textWithButtons']),
-    content: z.object({
-      text: z.string(),
-      buttons: z.array(
-        z.object({
-          text: z.string(),
-          url: z.string().nullable().optional(),
-          target: z
-            .enum(['_blank', '_self'])
-            .default('_blank')
-            .nullable()
-            .optional()
-            .describe(
-              'The target of the button when it has an url. If not provided, it will default to _blank.'
-            ),
-        })
-      ),
-    }),
-  })
-  .describe(
-    'A text message with buttons to allow the user to use quick replies'
-  )

package/src/structured-output/text.ts

@@ -1,13 +0,0 @@
-import type { TextMessage } from '@botonic/core'
-import { z } from 'zod'
-
-export type { TextMessage }
-
-export const TextSchema = z
-  .object({
-    type: z.enum(['text']),
-    content: z.object({
-      text: z.string(),
-    }),
-  })
-  .describe('A text message')

package/src/tools/index.ts

@@ -1,5 +0,0 @@
-import type { Tool } from '../types'
-
-export { retrieveKnowledge } from './retrieve-knowledge'
-
-export const mandatoryTools: Tool[] = []

package/src/tools/retrieve-knowledge.ts

@@ -1,37 +0,0 @@
-import { type RunContext, tool } from '@openai/agents'
-import { z } from 'zod'
-
-import { HubtypeApiClient } from '../services/hubtype-api-client'
-import type { Context } from '../types'
-
-export const retrieveKnowledge = tool({
-  name: 'retrieve_knowledge',
-  description:
-    'Consult the knowledge base for information before answering. Use this tool to make sure the information you provide is faithful.',
-  parameters: z.object({
-    query: z.string().describe('The query to search the knowledge base for'),
-  }),
-  execute: async (
-    input: { query: string },
-    runContext?: RunContext<Context>
-  ): Promise<string[]> => {
-    const context = runContext?.context
-    const query = input.query
-    if (!context) {
-      throw new Error('Context is required')
-    }
-    const sourceIds = context.sourceIds
-    const client = new HubtypeApiClient(context.authToken)
-    const chunks = await client.retrieveSimilarChunks(query, sourceIds)
-    const chunkTexts = chunks.map(chunk => chunk.text)
-
-    context.knowledgeUsed = {
-      query,
-      sourceIds,
-      chunksIds: chunks.map(chunk => chunk.id),
-      chunkTexts,
-    }
-
-    return chunkTexts
-  },
-})

package/src/types.ts

@@ -1,110 +0,0 @@
-import {
-  AgenticOutputMessage,
-  AiAgentArgs,
-  type BotContext,
-  GuardrailRule,
-  InferenceResponse,
-  type ResolvedPlugins,
-  RunResult,
-} from '@botonic/core'
-import type {
-  Agent,
-  AgentInputItem,
-  AgentOutputType,
-  RunContext as OpenAIRunContext,
-  Tool as OpenAITool,
-} from '@openai/agents'
-import type { ZodSchema } from 'zod'
-
-import type { OutputSchema } from './structured-output'
-
-export interface Context<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> {
-  authToken: string
-  sourceIds: string[]
-  knowledgeUsed: {
-    query: string
-    sourceIds: string[]
-    chunksIds: string[]
-    chunkTexts: string[]
-  }
-  request: BotContext<TPlugins, TExtraData>
-}
-
-export type RunContext<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> = OpenAIRunContext<Context<TPlugins, TExtraData>>
-
-export interface CustomTool<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> {
-  name: string
-  description: string
-  schema: ZodSchema
-  func: (
-    input?: any,
-    runContext?: RunContext<TPlugins, TExtraData>
-  ) => Promise<any>
-}
-
-export interface Chunk {
-  id: string
-  text: string
-}
-
-export type Tool<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> = OpenAITool<Context<TPlugins, TExtraData>>
-
-export type AIAgent<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> = Agent<Context<TPlugins, TExtraData>, AgentOutputType<typeof OutputSchema>>
-
-export type MessageHistoryApiVersion = 'v1' | 'v2'
-
-export interface MemoryOptions {
-  maxMessages?: number
-  includeToolCalls?: boolean
-  maxFullToolResults?: number
-  debugMode?: boolean
-}
-
-export interface PluginAiAgentOptions<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> {
-  authToken?: string
-  customTools?: CustomTool<TPlugins, TExtraData>[]
-  maxRetries?: number
-  timeout?: number
-  /** API version for message history endpoint. Defaults to 'v2'. */
-  messageHistoryApiVersion?: MessageHistoryApiVersion
-  /** Options for V2 message history API. Only used when messageHistoryApiVersion is 'v2'. */
-  memory?: MemoryOptions
-  /** Enable debug logging for AI agent configuration and execution details. */
-  enableDebug?: boolean
-}
-
-export interface ResultRawResponse {
-  usage: {
-    inputTokens: number
-    outputTokens: number
-  }
-  providerData?: Record<string, unknown>
-}
-
-export type AgenticInputMessage = AgentInputItem
-
-export {
-  AgenticOutputMessage,
-  AiAgentArgs,
-  GuardrailRule,
-  InferenceResponse,
-  RunResult,
-}