@botonic/plugin-ai-agents 0.46.0 → 2.23.0

package/src/agent-builder.ts

@@ -1,179 +0,0 @@
-import type { CampaignV2, ContactInfo, ResolvedPlugins } from '@botonic/core'
-import {
-  Agent,
-  type AgentOutputType,
-  type InputGuardrail,
-} from '@openai/agents'
-
-import { OPENAI_PROVIDER } from './constants'
-import type { DebugLogger } from './debug-logger'
-import { createInputGuardrail } from './guardrails'
-import type { GuardrailTrackingContext } from './guardrails/input'
-import type { LLMConfig } from './llm-config'
-import { OutputSchema } from './structured-output'
-import { mandatoryTools, retrieveKnowledge } from './tools'
-import type { AIAgent, Context, GuardrailRule, Tool } from './types'
-
-interface AIAgentBuilderOptions<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> {
-  name: string
-  instructions: string
-  tools: Tool<TPlugins, TExtraData>[]
-  campaignsContext?: CampaignV2[]
-  contactInfo: ContactInfo[]
-  inputGuardrailRules: GuardrailRule[]
-  sourceIds: string[]
-  llmConfig: LLMConfig
-  logger: DebugLogger
-  guardrailTrackingContext: GuardrailTrackingContext
-}
-
-export class AIAgentBuilder<
-  TPlugins extends ResolvedPlugins = ResolvedPlugins,
-  TExtraData = any,
-> {
-  private name: string
-  private instructions: string
-  private tools: Tool<TPlugins, TExtraData>[]
-  private inputGuardrails: InputGuardrail[]
-  public llmConfig: LLMConfig
-  private logger: DebugLogger
-
-  constructor(options: AIAgentBuilderOptions<TPlugins, TExtraData>) {
-    this.name = options.name
-    this.instructions = this.addExtraInstructions(
-      options.instructions,
-      options.contactInfo,
-      options.campaignsContext
-    )
-    this.tools = this.addHubtypeTools(options.tools, options.sourceIds)
-    this.inputGuardrails = []
-    this.llmConfig = options.llmConfig
-    this.logger = options.logger
-    if (options.inputGuardrailRules.length > 0) {
-      const inputGuardrail = createInputGuardrail(
-        options.inputGuardrailRules,
-        options.llmConfig,
-        options.guardrailTrackingContext
-      )
-      this.inputGuardrails.push(inputGuardrail)
-    }
-  }
-
-  build(): AIAgent<TPlugins, TExtraData> {
-    // When using standard OpenAI API, we need to specify the model
-    // Azure OpenAI uses deployment name instead
-
-    const model = this.llmConfig.modelName
-    const hasRetrieveKnowledge = this.tools.includes(retrieveKnowledge)
-
-    this.logger.logModelSettings({
-      provider: OPENAI_PROVIDER,
-      model,
-      reasoning: this.llmConfig.modelSettings.reasoning as
-        | { effort: string }
-        | undefined,
-      text: this.llmConfig.modelSettings.text as
-        | { verbosity: string }
-        | undefined,
-      toolChoice: this.llmConfig.modelSettings.toolChoice as string | undefined,
-      hasRetrieveKnowledge,
-    })
-
-    return new Agent<
-      Context<TPlugins, TExtraData>,
-      AgentOutputType<typeof OutputSchema>
-    >({
-      name: this.name,
-      model,
-      instructions: this.instructions,
-      tools: this.tools,
-      outputType: OutputSchema,
-      inputGuardrails: this.inputGuardrails,
-      outputGuardrails: [],
-    })
-  }
-
-  private addExtraInstructions(
-    initialInstructions: string,
-    contactInfo: ContactInfo[],
-    campaignsContext?: CampaignV2[]
-  ): string {
-    const instructions = `<instructions>\n${initialInstructions.trim()}\n</instructions>`
-    const metadataInstructions = this.getMetadataInstructions()
-    const contactInfoInstructions = this.getContactInfoInstructions(contactInfo)
-    const campaignInstructions = this.getCampaignInstructions(campaignsContext)
-    const outputInstructions = this.getOutputInstructions()
-    return `${instructions}\n\n${metadataInstructions}\n\n${contactInfoInstructions}\n\n${campaignInstructions}\n\n${outputInstructions}`
-  }
-
-  private getContactInfoInstructions(contactInfo: ContactInfo[]): string {
-    const structuredContactInfo = contactInfo
-      .map(
-        info =>
-          ` <contact_info>
-              <name>${info.name}</name>
-              <value>${info.value}</value>
-              <type>${info.type}</type>
-              ${
-                info.description
-                  ? `<description>${info.description}</description>`
-                  : ''
-              }
-            </contact_info>`
-      )
-      .join('\n')
-    return `<contact_info_fields>\n${structuredContactInfo}</contact_info_fields>`
-  }
-
-  private getMetadataInstructions(): string {
-    const metadata = `Current Date: ${new Date().toISOString()}`
-    return `<metadata>\n${metadata}\n</metadata>`
-  }
-
-  private getCampaignInstructions(campaignsContext?: CampaignV2[]): string {
-    if (!campaignsContext || campaignsContext.length === 0) {
-      return ''
-    }
-    const campaignsWithContext = campaignsContext.filter(
-      campaign => campaign.agent_context
-    )
-    if (campaignsWithContext.length === 0) {
-      return ''
-    }
-    return campaignsWithContext
-      .map(
-        (campaign, index) =>
-          `<campaign_context_${index + 1}>\n${campaign.agent_context}\n</campaign_context_${index + 1}>`
-      )
-      .join('\n')
-  }
-
-  private getOutputInstructions(): string {
-    const example = {
-      messages: [
-        {
-          type: 'text',
-          content: {
-            text: 'Hello, how can I help you today?',
-          },
-        },
-      ],
-    }
-    const output = `Return a JSON that follows the output schema provided. Never return multiple output schemas concatenated by a line break.\n<example>\n${JSON.stringify(example)}\n</example>`
-    return `<output>\n${output}\n</output>`
-  }
-
-  private addHubtypeTools(
-    tools: Tool<TPlugins, TExtraData>[],
-    sourceIds: string[]
-  ): Tool<TPlugins, TExtraData>[] {
-    const hubtypeTools: Tool[] = [...mandatoryTools]
-    if (sourceIds.length > 0) {
-      hubtypeTools.push(retrieveKnowledge)
-    }
-    return [...hubtypeTools, ...tools]
-  }
-}

package/src/bot-config-tools.ts

@@ -1,21 +0,0 @@
-import type { ToolConfigJSON } from '@botonic/core'
-import { zodToJsonSchema } from 'zod-to-json-schema'
-
-import type { CustomTool } from './types'
-
-/**
- * Maps custom AI agent tools to the format expected by bot config (e.g. for flow-builder).
- * Converts each tool's Zod schema to JSON Schema so it can be serialized in the config.
- */
-export function getToolsForBotConfig(
-  customTools: CustomTool[]
-): ToolConfigJSON[] {
-  return customTools.map(tool => ({
-    name: tool.name,
-    description: tool.description,
-    // Cast to avoid TS "Type instantiation is excessively deep" with zodToJsonSchema + ZodSchema
-    schema: zodToJsonSchema(tool.schema as never, {
-      $refStrategy: 'none',
-    }) as ToolConfigJSON['schema'],
-  }))
-}

package/src/constants.ts

@@ -1,21 +0,0 @@
-export const HUBTYPE_API_URL =
-  process.env.HUBTYPE_API_URL || 'https://api.hubtype.com'
-
-// OpenAI Provider Configuration
-export const OPENAI_API_KEY = process.env.OPENAI_API_KEY // pragma: allowlist secret
-export const OPENAI_MODEL = process.env.OPENAI_MODEL || 'gpt-4.1-mini'
-export const OPENAI_PROVIDER: 'openai' | 'azure' =
-  (process.env.OPENAI_PROVIDER as 'openai' | 'azure') || 'azure'
-
-// Azure OpenAI Configuration
-export const AZURE_OPENAI_API_KEY = process.env.AZURE_OPENAI_API_KEY // pragma: allowlist secret
-export const AZURE_OPENAI_API_BASE = process.env.AZURE_OPENAI_API_BASE
-export const AZURE_OPENAI_API_VERSION =
-  process.env.AZURE_OPENAI_API_VERSION || '2025-01-01-preview'
-
-export const isProd = process.env.NODE_ENV === 'production'
-
-export const MAX_MEMORY_LENGTH = 25
-
-export const DEFAULT_TIMEOUT_16_SECONDS = 16000
-export const DEFAULT_MAX_RETRIES = 2

package/src/debug-logger.ts

@@ -1,166 +0,0 @@
-import type { AiAgentArgs, ToolExecution } from '@botonic/core'
-import type { ModelSettings } from '@openai/agents'
-import { MAX_MEMORY_LENGTH, OPENAI_PROVIDER } from './constants'
-import type { AgenticInputMessage, MemoryOptions, RunResult } from './types'
-
-const PREFIX = '[BotonicPluginAiAgents]'
-
-export interface DebugLoggerConfig {
-  messageHistoryApiVersion: string
-  maxRetries: number
-  timeout: number
-  customToolNames: string[]
-  memory: MemoryOptions
-}
-
-export interface ModelSettingsInfo {
-  provider: string
-  model: string | undefined
-  reasoning?: { effort: string }
-  text?: { verbosity: string }
-  toolChoice?: string
-  hasRetrieveKnowledge: boolean
-}
-
-export interface DebugLogger {
-  logInitialConfig(config: DebugLoggerConfig): void
-  logAgentDebugInfo(
-    aiAgentArgs: AiAgentArgs,
-    toolNames: string[],
-    messages: AgenticInputMessage[]
-  ): void
-  logModelSettings(settings: ModelSettingsInfo): void
-  logRunnerStart(model: string, modelSettings: ModelSettings): void
-  logRunResult(runResult: RunResult, startTime: number): void
-  logGuardrailTriggered(): void
-  logRunnerError(startTime: number, error: unknown): void
-  logToolExecution(toolExecution: ToolExecution): void
-}
-
-class EnabledDebugLogger implements DebugLogger {
-  logInitialConfig(config: DebugLoggerConfig): void {
-    console.log(`${PREFIX} === Plugin Initialization ===`)
-    console.log(`${PREFIX} Provider: ${OPENAI_PROVIDER}`)
-    console.log(
-      `${PREFIX} Message History API Version: ${config.messageHistoryApiVersion}`
-    )
-    console.log(`${PREFIX} Max Retries: ${config.maxRetries}`)
-    console.log(`${PREFIX} Timeout: ${config.timeout}ms`)
-    console.log(
-      `${PREFIX} Custom Tools Registered: ${config.customToolNames.join(', ') || 'none'}`
-    )
-    console.log(`${PREFIX} Memory Options:`, {
-      maxMessages: config.memory.maxMessages ?? MAX_MEMORY_LENGTH,
-      includeToolCalls: config.memory.includeToolCalls ?? true,
-      maxFullToolResults: config.memory.maxFullToolResults ?? 1,
-      debugMode: config.memory.debugMode ?? false,
-    })
-    console.log(`${PREFIX} === End Plugin Initialization ===`)
-  }
-
-  logAgentDebugInfo(
-    aiAgentArgs: AiAgentArgs,
-    toolNames: string[],
-    messages: AgenticInputMessage[]
-  ): void {
-    console.log(`${PREFIX} === AI Agent Debug Info ===`)
-    console.log(`${PREFIX} Agent Name: ${aiAgentArgs.name}`)
-    console.log(`${PREFIX} Active Tools: ${JSON.stringify(toolNames)}`)
-    console.log(
-      `${PREFIX} Source IDs: ${JSON.stringify(aiAgentArgs.sourceIds || [])}`
-    )
-    console.log(`${PREFIX} Message History Count: ${messages.length}`)
-    console.log(
-      `${PREFIX} Input Guardrail Rules: ${aiAgentArgs.inputGuardrailRules?.length || 0}`
-    )
-    console.log(`${PREFIX} Instructions:`)
-    console.log(aiAgentArgs.instructions)
-    console.log(`${PREFIX} === End Debug Info ===`)
-  }
-
-  logModelSettings(settings: ModelSettingsInfo): void {
-    console.log(`${PREFIX} === Agent Model Settings ===`)
-    console.log(
-      `${PREFIX} Has Retrieve Knowledge Tool: ${settings.hasRetrieveKnowledge}`
-    )
-    if (settings.reasoning) {
-      console.log(`${PREFIX} Reasoning Effort: ${settings.reasoning.effort}`)
-    }
-    if (settings.text) {
-      console.log(`${PREFIX} Text Verbosity: ${settings.text.verbosity}`)
-    }
-    if (settings.toolChoice) {
-      console.log(`${PREFIX} Tool Choice: ${settings.toolChoice}`)
-    }
-    console.log(`${PREFIX} === End Model Settings ===`)
-  }
-
-  logRunnerStart(model: string, modelSettings: ModelSettings): void {
-    console.log(`${PREFIX} === Runner Execution Start ===`)
-    console.log(`${PREFIX} Model: ${model}`)
-    console.log(`${PREFIX} Model Settings: ${JSON.stringify(modelSettings)}`)
-  }
-
-  logRunResult(runResult: RunResult, startTime: number): void {
-    const elapsedMs = Date.now() - startTime
-
-    console.log(`${PREFIX} === Runner Execution Complete ===`)
-    console.log(`${PREFIX} Execution Time: ${elapsedMs}ms`)
-    console.log(`${PREFIX} Output Messages Count: ${runResult.messages.length}`)
-    console.log(`${PREFIX} Exit: ${runResult.exit}`)
-    console.log(`${PREFIX} Error: ${runResult.error}`)
-    console.log(
-      `${PREFIX} Tools Executed: ${JSON.stringify(runResult.toolsExecuted.map(t => t.toolName))}`
-    )
-    if (runResult.inputGuardrailsTriggered.length > 0) {
-      console.log(
-        `${PREFIX} Input Guardrails Triggered: ${runResult.inputGuardrailsTriggered.length}`
-      )
-    }
-    if (runResult.outputGuardrailsTriggered.length > 0) {
-      console.log(
-        `${PREFIX} Output Guardrails Triggered: ${runResult.outputGuardrailsTriggered.length}`
-      )
-    }
-    console.log(`${PREFIX} === End Runner Execution ===`)
-  }
-
-  logGuardrailTriggered(): void {
-    console.log(`${PREFIX} Input guardrail triggered`)
-  }
-
-  logRunnerError(startTime: number, error: unknown): void {
-    const elapsedMs = Date.now() - startTime
-    console.log(`${PREFIX} Runner execution failed after ${elapsedMs}ms`)
-    console.log(`${PREFIX} Error:`, error)
-  }
-
-  logToolExecution(toolExecution: ToolExecution): void {
-    console.log(`${PREFIX} Tool Execution: ${toolExecution.toolName}`)
-    console.log(
-      `${PREFIX} Tool Arguments: ${JSON.stringify(toolExecution.toolArguments)}`
-    )
-    console.log(`${PREFIX} Tool Results: ${toolExecution.toolResults}`)
-    console.log(
-      `${PREFIX} Knowledgebase Sources IDs: ${JSON.stringify(toolExecution.knowledgebaseSourcesIds)}`
-    )
-    console.log(
-      `${PREFIX} Knowledgebase Chunks IDs: ${JSON.stringify(toolExecution.knowledgebaseChunksIds)}`
-    )
-  }
-}
-
-class DisabledDebugLogger implements DebugLogger {
-  logInitialConfig(): void {}
-  logAgentDebugInfo(): void {}
-  logModelSettings(): void {}
-  logRunnerStart(_model: string, _modelSettings: ModelSettings): void {}
-  logRunResult(): void {}
-  logGuardrailTriggered(): void {}
-  logRunnerError(): void {}
-  logToolExecution(): void {}
-}
-
-export function createDebugLogger(enableDebug: boolean): DebugLogger {
-  return enableDebug ? new EnabledDebugLogger() : new DisabledDebugLogger()
-}

package/src/guardrails/index.ts

@@ -1 +0,0 @@
-export * from './input'

package/src/guardrails/input.ts

@@ -1,122 +0,0 @@
-import {
-  Agent,
-  type InputGuardrail,
-  Runner,
-  type UserMessageItem,
-} from '@openai/agents'
-import { z } from 'zod'
-import { AZURE_OPENAI_API_VERSION, isProd, OPENAI_PROVIDER } from '../constants'
-import type { LLMConfig } from '../llm-config'
-import { HubtypeApiClient } from '../services/hubtype-api-client'
-import { TrackFeature, TrackProductName } from '../services/types'
-import type { GuardrailRule, ResultRawResponse } from '../types'
-
-export interface GuardrailTrackingContext {
-  botId: string
-  isTest: boolean
-  authToken: string
-  inferenceId: string
-}
-
-export function createInputGuardrail(
-  rules: GuardrailRule[],
-  llmConfig: LLMConfig,
-  trackingContext: GuardrailTrackingContext
-): InputGuardrail {
-  const outputType = z.object(
-    Object.fromEntries(
-      rules.map(rule => [rule.name, z.boolean().describe(rule.description)])
-    )
-  )
-
-  const agent = new Agent({
-    name: 'InputGuardrail',
-    instructions:
-      'Check if the user triggers some of the following guardrails.',
-    outputType,
-  })
-
-  return {
-    name: 'InputGuardrail',
-    execute: async ({ input, context }) => {
-      const lastMessage = input[input.length - 1] as UserMessageItem
-      const modelProvider = llmConfig.modelProvider
-      const modelSettings = llmConfig.modelSettings
-      modelSettings.toolChoice = undefined
-      const runner = new Runner({
-        modelSettings,
-        modelProvider,
-        tracingDisabled: true,
-      })
-      const startTime = Date.now()
-      const result = await runner.run(agent, [lastMessage], { context })
-      const endTime = Date.now()
-
-      void sendGuardrailLlmRunTracking(
-        result,
-        trackingContext,
-        llmConfig,
-        startTime,
-        endTime
-      )
-
-      const finalOutput = result.finalOutput as Record<string, boolean>
-      if (finalOutput === undefined) {
-        throw new Error('Guardrail agent failed to produce output')
-      }
-      const triggered = Object.values(finalOutput).some(value => value === true)
-      const triggeredGuardrails = Object.keys(finalOutput).filter(
-        key => finalOutput[key] === true
-      )
-      return {
-        outputInfo: triggeredGuardrails,
-        tripwireTriggered: triggered,
-      }
-    },
-  }
-}
-
-async function sendGuardrailLlmRunTracking(
-  result: {
-    rawResponses?: ResultRawResponse[]
-  },
-  trackingContext: GuardrailTrackingContext,
-  llmConfig: LLMConfig,
-  startTime: number,
-  endTime: number
-): Promise<void> {
-  if (!isProd) {
-    return
-  }
-  const rawResponses = result.rawResponses ?? []
-  if (rawResponses.length === 0) {
-    return
-  }
-  const totalDuration = endTime - startTime
-  const durationPerCall = Math.round(totalDuration / rawResponses.length)
-  const temperature =
-    (llmConfig.modelSettings.temperature as number | undefined) ?? 0
-  const apiVersion = OPENAI_PROVIDER === 'azure' ? AZURE_OPENAI_API_VERSION : ''
-
-  const llmRuns = rawResponses.map(response => ({
-    inference_id: trackingContext.inferenceId,
-    is_test: trackingContext.isTest,
-    product_name: TrackProductName.AI_AGENT,
-    deployment_name: llmConfig.modelName,
-    model_name:
-      (response.providerData?.['model'] as string | undefined) ??
-      llmConfig.modelName,
-    feature: TrackFeature.AI_AGENT_GUARDRAIL,
-    api_version: apiVersion,
-    num_prompt_tokens: response.usage.inputTokens,
-    num_completion_tokens: response.usage.outputTokens,
-    duration_in_milliseconds: durationPerCall,
-    temperature,
-    error: null,
-  }))
-
-  const client = new HubtypeApiClient(trackingContext.authToken)
-  await client.trackLlmRuns(trackingContext.botId, {
-    llm_runs: llmRuns,
-  })
-}