signalwire-agents 0.1.0

package/src/prefabs/ConciergeAgent.ts

@@ -0,0 +1,251 @@
+/**
+ * ConciergeAgent - A prefab agent that provides multi-department routing
+ * with a knowledge base of department info, hours, and transfer capabilities.
+ */
+
+import { AgentBase } from '../AgentBase.js';
+import { SwaigFunctionResult } from '../SwaigFunctionResult.js';
+import type { AgentOptions } from '../types.js';
+
+// ── Config types ────────────────────────────────────────────────────────────
+
+export interface Department {
+  /** Department name (e.g. "Sales", "Support"). */
+  name: string;
+  /** Description of what this department handles. */
+  description: string;
+  /** Phone number or SIP address for transfers. */
+  transferNumber?: string;
+  /** Keywords that help route callers to this department. */
+  keywords?: string[];
+  /** Human-readable hours of operation (e.g. "Mon-Fri 9am-5pm EST"). */
+  hoursOfOperation?: string;
+}
+
+export interface ConciergeConfig {
+  /** Agent display name. */
+  name?: string;
+  /** List of departments available for routing. */
+  departments: Department[];
+  /** Company name used in greetings and prompts. */
+  companyName?: string;
+  /** General company information the agent can share. */
+  generalInfo?: string;
+  /** Message spoken when a department is closed or unavailable. */
+  afterHoursMessage?: string;
+  /** Additional AgentBase options forwarded to super(). */
+  agentOptions?: Partial<AgentOptions>;
+}
+
+// ── Agent ───────────────────────────────────────────────────────────────────
+
+/** Prefab agent that provides multi-department routing with a knowledge base of department info, hours, and transfer capabilities. */
+export class ConciergeAgent extends AgentBase {
+  private departments: Department[];
+  private companyName: string;
+  private generalInfo: string;
+  private afterHoursMessage: string;
+
+  /** Declarative prompt sections merged by AgentBase constructor. */
+  static override PROMPT_SECTIONS = [
+    {
+      title: 'Role',
+      body: 'You are a professional concierge agent. Help callers find the right department, provide information about available services, and transfer calls when requested.',
+    },
+    {
+      title: 'Rules',
+      bullets: [
+        'Greet the caller warmly and ask how you can help.',
+        'Use list_departments to describe available departments if the caller is unsure where to go.',
+        'Use get_department_info to provide detailed information about a specific department.',
+        'Use transfer_to_department to connect the caller to the right department.',
+        'If a department has hours of operation listed, mention them before transferring.',
+        'If a department does not have a transfer number, inform the caller and offer alternatives.',
+        'Be polite, professional, and efficient.',
+      ],
+    },
+  ];
+
+  /**
+   * Create a ConciergeAgent with the specified departments and company info.
+   * @param config - Configuration including departments, company name, and after-hours message.
+   */
+  constructor(config: ConciergeConfig) {
+    const agentName = config.name ?? 'Concierge';
+    super({
+      name: agentName,
+      ...config.agentOptions,
+    });
+
+    this.departments = config.departments;
+    this.companyName = config.companyName ?? 'our company';
+    this.generalInfo = config.generalInfo ?? '';
+    this.afterHoursMessage = config.afterHoursMessage ?? 'This department is currently closed. Please try again during business hours.';
+
+    // Company intro section
+    let introBody = `You are the concierge for ${this.companyName}.`;
+    if (this.generalInfo) {
+      introBody += ` Company information: ${this.generalInfo}`;
+    }
+    this.promptAddSection('Company', { body: introBody });
+
+    // Build department overview section
+    const deptBullets = this.departments.map((dept) => {
+      let desc = `${dept.name}: ${dept.description}`;
+      if (dept.hoursOfOperation) desc += ` (Hours: ${dept.hoursOfOperation})`;
+      if (dept.transferNumber) desc += ' [transfer available]';
+      return desc;
+    });
+    this.promptAddSection('Available Departments', { bullets: deptBullets });
+
+    // Speech recognition hints from department names and keywords
+    const hints: string[] = this.departments.map((d) => d.name);
+    for (const dept of this.departments) {
+      if (dept.keywords) hints.push(...dept.keywords);
+    }
+    this.addHints(hints);
+
+    // Register tools after all fields are initialized
+    this.defineTools();
+  }
+
+  // ── Department helpers ────────────────────────────────────────────────
+
+  private findDepartment(name: string): Department | undefined {
+    const normalized = name.toLowerCase().trim();
+    return this.departments.find(
+      (d) =>
+        d.name.toLowerCase() === normalized ||
+        d.keywords?.some((k) => k.toLowerCase() === normalized),
+    );
+  }
+
+  // ── Tool registration ─────────────────────────────────────────────────
+
+  /** Register the list_departments, get_department_info, and transfer_to_department SWAIG tools. */
+  protected override defineTools(): void {
+    // Tool: list_departments
+    this.defineTool({
+      name: 'list_departments',
+      description: `List all available departments at ${this.companyName} with their descriptions and hours of operation.`,
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      handler: () => {
+        if (this.departments.length === 0) {
+          return new SwaigFunctionResult('No departments are currently configured.');
+        }
+
+        const lines = this.departments.map((dept) => {
+          let line = `${dept.name}: ${dept.description}`;
+          if (dept.hoursOfOperation) line += ` | Hours: ${dept.hoursOfOperation}`;
+          if (!dept.transferNumber) line += ' | (no direct transfer available)';
+          return line;
+        });
+
+        return new SwaigFunctionResult(
+          `Available departments at ${this.companyName}:\n${lines.join('\n')}`,
+        );
+      },
+    });
+
+    // Tool: get_department_info
+    this.defineTool({
+      name: 'get_department_info',
+      description: 'Get detailed information about a specific department including description, hours of operation, and transfer availability.',
+      parameters: {
+        type: 'object',
+        properties: {
+          department_name: {
+            type: 'string',
+            description: 'The name of the department to look up.',
+          },
+        },
+        required: ['department_name'],
+      },
+      handler: (_args: Record<string, unknown>) => {
+        const deptName = _args['department_name'] as string;
+        if (!deptName) {
+          return new SwaigFunctionResult('Please provide a department name.');
+        }
+
+        const dept = this.findDepartment(deptName);
+        if (!dept) {
+          const available = this.departments.map((d) => d.name).join(', ');
+          return new SwaigFunctionResult(
+            `Department "${deptName}" not found. Available departments: ${available}`,
+          );
+        }
+
+        let info = `Department: ${dept.name}\nDescription: ${dept.description}`;
+        if (dept.hoursOfOperation) info += `\nHours: ${dept.hoursOfOperation}`;
+        if (dept.transferNumber) {
+          info += '\nTransfer: available';
+        } else {
+          info += '\nTransfer: not available (no phone number configured)';
+        }
+        if (dept.keywords && dept.keywords.length > 0) {
+          info += `\nRelated topics: ${dept.keywords.join(', ')}`;
+        }
+
+        return new SwaigFunctionResult(info);
+      },
+    });
+
+    // Tool: transfer_to_department
+    this.defineTool({
+      name: 'transfer_to_department',
+      description: 'Transfer the caller to a specific department. Only works if the department has a transfer number configured.',
+      parameters: {
+        type: 'object',
+        properties: {
+          department_name: {
+            type: 'string',
+            description: 'The name of the department to transfer to.',
+          },
+        },
+        required: ['department_name'],
+      },
+      handler: (_args: Record<string, unknown>) => {
+        const deptName = _args['department_name'] as string;
+        if (!deptName) {
+          return new SwaigFunctionResult('Please provide a department name.');
+        }
+
+        const dept = this.findDepartment(deptName);
+        if (!dept) {
+          const available = this.departments.map((d) => d.name).join(', ');
+          return new SwaigFunctionResult(
+            `Department "${deptName}" not found. Available departments: ${available}`,
+          );
+        }
+
+        if (!dept.transferNumber) {
+          return new SwaigFunctionResult(
+            `The ${dept.name} department does not have a direct transfer number. ${this.afterHoursMessage}`,
+          );
+        }
+
+        const result = new SwaigFunctionResult(
+          `Transferring you to the ${dept.name} department now.`,
+        );
+        result.connect(dept.transferNumber);
+        return result;
+      },
+    });
+  }
+}
+
+// ── Factory function ────────────────────────────────────────────────────────
+
+/**
+ * Factory function that creates and returns a new ConciergeAgent.
+ * @param config - Configuration for the concierge agent.
+ * @returns A configured ConciergeAgent instance.
+ */
+export function createConciergeAgent(config: ConciergeConfig): ConciergeAgent {
+  return new ConciergeAgent(config);
+}
+
+export default ConciergeAgent;

package/src/prefabs/FAQBotAgent.ts

@@ -0,0 +1,263 @@
+/**
+ * FAQBotAgent - A prefab agent that answers frequently asked questions using
+ * keyword/word-overlap matching with configurable similarity thresholds
+ * and optional escalation to a live agent.
+ */
+
+import { AgentBase } from '../AgentBase.js';
+import { SwaigFunctionResult } from '../SwaigFunctionResult.js';
+import type { AgentOptions } from '../types.js';
+
+// ── Config types ────────────────────────────────────────────────────────────
+
+export interface FAQEntry {
+  /** The representative question text. */
+  question: string;
+  /** The answer to provide when this FAQ matches. */
+  answer: string;
+  /** Additional keywords to boost matching accuracy. */
+  keywords?: string[];
+}
+
+export interface FAQBotConfig {
+  /** Agent display name. */
+  name?: string;
+  /** List of FAQ entries for the knowledge base. */
+  faqs: FAQEntry[];
+  /** Minimum match score (0-1) for an FAQ to be considered a match. Default 0.5. */
+  threshold?: number;
+  /** Message spoken when no FAQ matches the query. */
+  escalationMessage?: string;
+  /** Phone number to transfer to on escalation. If not set, escalate tool is not registered. */
+  escalationNumber?: string;
+  /** Additional AgentBase options forwarded to super(). */
+  agentOptions?: Partial<AgentOptions>;
+}
+
+// ── Agent ───────────────────────────────────────────────────────────────────
+
+/** Prefab agent that answers frequently asked questions using keyword matching with optional escalation to a live agent. */
+export class FAQBotAgent extends AgentBase {
+  private faqs: FAQEntry[];
+  private threshold: number;
+  private escalationMessage: string;
+  private escalationNumber: string | null;
+
+  /** Declarative prompt sections merged by AgentBase constructor. */
+  static override PROMPT_SECTIONS = [
+    {
+      title: 'Role',
+      body: 'You are a helpful FAQ assistant. Answer the caller\'s questions by searching the knowledge base. If you cannot find a satisfactory answer, offer to escalate to a human agent.',
+    },
+    {
+      title: 'Rules',
+      bullets: [
+        'Always use the search_faq tool to find answers. Do not make up answers.',
+        'If the search returns a good match, relay the answer naturally to the caller.',
+        'If the match score is low or no match is found, let the caller know and offer to escalate.',
+        'Be concise and helpful in your responses.',
+        'If the caller asks a follow-up, search again with the new query.',
+      ],
+    },
+  ];
+
+  /**
+   * Create a FAQBotAgent with the specified FAQ entries and matching threshold.
+   * @param config - Configuration including FAQ entries, threshold, and escalation settings.
+   */
+  constructor(config: FAQBotConfig) {
+    const agentName = config.name ?? 'FAQBot';
+    super({
+      name: agentName,
+      ...config.agentOptions,
+    });
+
+    this.faqs = config.faqs;
+    this.threshold = config.threshold ?? 0.5;
+    this.escalationMessage = config.escalationMessage ?? 'I\'m sorry, I couldn\'t find an answer to your question. Let me transfer you to someone who can help.';
+    this.escalationNumber = config.escalationNumber ?? null;
+
+    // Build FAQ topics section for the prompt
+    const topicBullets = this.faqs.map((faq) => {
+      const kw = faq.keywords ? ` (keywords: ${faq.keywords.join(', ')})` : '';
+      return `${faq.question}${kw}`;
+    });
+    this.promptAddSection('Available FAQ Topics', { bullets: topicBullets });
+
+    // Add hints from FAQ keywords for speech recognition
+    const allKeywords: string[] = [];
+    for (const faq of this.faqs) {
+      if (faq.keywords) allKeywords.push(...faq.keywords);
+    }
+    if (allKeywords.length > 0) {
+      this.addHints(allKeywords);
+    }
+
+    // Register tools after all fields are initialized
+    this.defineTools();
+  }
+
+  // ── Matching engine ───────────────────────────────────────────────────
+
+  /**
+   * Compute a word-overlap similarity score between a query and an FAQ entry.
+   * Combines question text similarity and keyword overlap.
+   * Returns a value between 0 and 1.
+   */
+  private computeMatchScore(query: string, faq: FAQEntry): number {
+    const queryWords = this.tokenize(query);
+    if (queryWords.length === 0) return 0;
+
+    // Score against the question text
+    const questionWords = this.tokenize(faq.question);
+    const questionOverlap = this.wordOverlap(queryWords, questionWords);
+
+    // Score against keywords
+    let keywordScore = 0;
+    if (faq.keywords && faq.keywords.length > 0) {
+      const keywordTokens = faq.keywords.map((k) => k.toLowerCase().trim());
+      const queryLower = query.toLowerCase();
+      let keywordHits = 0;
+      for (const kw of keywordTokens) {
+        if (queryLower.includes(kw)) {
+          keywordHits++;
+        }
+      }
+      keywordScore = keywordTokens.length > 0 ? keywordHits / keywordTokens.length : 0;
+    }
+
+    // Weighted combination: 60% question overlap, 40% keyword score
+    return faq.keywords && faq.keywords.length > 0
+      ? questionOverlap * 0.6 + keywordScore * 0.4
+      : questionOverlap;
+  }
+
+  private tokenize(text: string): string[] {
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9\s]/g, ' ')
+      .split(/\s+/)
+      .filter((w) => w.length > 1 && !STOP_WORDS.has(w));
+  }
+
+  private wordOverlap(queryWords: string[], targetWords: string[]): number {
+    if (queryWords.length === 0 || targetWords.length === 0) return 0;
+    const targetSet = new Set(targetWords);
+    let matches = 0;
+    for (const word of queryWords) {
+      if (targetSet.has(word)) matches++;
+    }
+    // Normalize by the smaller set to be lenient
+    const divisor = Math.min(queryWords.length, targetWords.length);
+    return divisor > 0 ? matches / divisor : 0;
+  }
+
+  // ── Tool registration ─────────────────────────────────────────────────
+
+  /** Register the search_faq and optional escalate SWAIG tools. */
+  protected override defineTools(): void {
+    // Tool: search_faq
+    this.defineTool({
+      name: 'search_faq',
+      description: 'Search the FAQ knowledge base for an answer to the caller\'s question. Returns the best matching FAQ entry with a confidence score.',
+      parameters: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'The caller\'s question or search query.',
+          },
+        },
+        required: ['query'],
+      },
+      handler: (_args: Record<string, unknown>) => {
+        const query = _args['query'] as string;
+        if (!query) {
+          return new SwaigFunctionResult('A query is required to search the FAQ.');
+        }
+
+        // Score all FAQs
+        const scored = this.faqs.map((faq) => ({
+          faq,
+          score: this.computeMatchScore(query, faq),
+        }));
+
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+
+        const best = scored[0];
+
+        if (!best || best.score < this.threshold) {
+          return new SwaigFunctionResult(
+            `No FAQ matched the query "${query}" with sufficient confidence (best score: ${best ? best.score.toFixed(2) : '0.00'}, threshold: ${this.threshold.toFixed(2)}). ${this.escalationMessage}`,
+          );
+        }
+
+        // Return the best match
+        let response = `FAQ Match (confidence: ${best.score.toFixed(2)}): Q: "${best.faq.question}" A: ${best.faq.answer}`;
+
+        // If there are close runner-ups, mention them
+        const runnerUps = scored.filter((s, i) => i > 0 && s.score >= this.threshold);
+        if (runnerUps.length > 0) {
+          const alsoStr = runnerUps
+            .slice(0, 2)
+            .map((s) => `"${s.faq.question}" (${s.score.toFixed(2)})`)
+            .join(', ');
+          response += ` Also related: ${alsoStr}`;
+        }
+
+        return new SwaigFunctionResult(response);
+      },
+    });
+
+    // Tool: escalate (only if escalation number is configured)
+    if (this.escalationNumber) {
+      this.defineTool({
+        name: 'escalate',
+        description: 'Transfer the caller to a live agent when the FAQ knowledge base cannot answer their question.',
+        parameters: {
+          type: 'object',
+          properties: {
+            reason: {
+              type: 'string',
+              description: 'The reason for escalation.',
+            },
+          },
+        },
+        handler: (_args: Record<string, unknown>) => {
+          const reason = (_args['reason'] as string) || 'Caller needs assistance beyond FAQ';
+          const result = new SwaigFunctionResult(
+            `Transferring caller to a live agent. Reason: ${reason}`,
+          );
+          result.connect(this.escalationNumber!);
+          return result;
+        },
+      });
+    }
+  }
+}
+
+// ── Common English stop words filtered from matching ────────────────────────
+
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'is', 'it', 'to', 'in', 'of', 'and', 'or', 'for',
+  'on', 'at', 'by', 'do', 'if', 'my', 'so', 'up', 'am', 'as', 'be',
+  'he', 'me', 'we', 'no', 'not', 'are', 'was', 'has', 'had', 'how',
+  'its', 'can', 'did', 'get', 'but', 'you', 'her', 'him', 'his', 'she',
+  'our', 'who', 'this', 'that', 'what', 'with', 'have', 'from', 'will',
+  'your', 'they', 'them', 'been', 'does', 'just', 'than', 'when', 'which',
+  'would', 'could', 'should', 'about', 'their', 'there', 'these', 'those',
+]);
+
+// ── Factory function ────────────────────────────────────────────────────────
+
+/**
+ * Factory function that creates and returns a new FAQBotAgent.
+ * @param config - Configuration for the FAQ bot agent.
+ * @returns A configured FAQBotAgent instance.
+ */
+export function createFAQBotAgent(config: FAQBotConfig): FAQBotAgent {
+  return new FAQBotAgent(config);
+}
+
+export default FAQBotAgent;