elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/integrations/ai/ai.interface.ts

@@ -0,0 +1,74 @@
+/* ------------------------------------------------------------------ */
+/*  Single-turn (existing)                                             */
+/* ------------------------------------------------------------------ */
+
+export interface AIGenerateTextParams {
+  prompt: string;
+  systemPrompt?: string;
+  maxTokens?: number;
+  temperature?: number;
+}
+
+export interface AIGenerateJsonParams<T = unknown> extends AIGenerateTextParams {
+  /** Description of expected JSON shape, used in the system prompt. */
+  schema?: string;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Conversational agent (new)                                         */
+/* ------------------------------------------------------------------ */
+
+export interface AIMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool_result';
+  content: string;
+  /** For tool_result messages */
+  toolCallId?: string;
+}
+
+export interface AIToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, any>; // JSON Schema
+}
+
+export interface AIToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, any>;
+}
+
+export interface AIAgentResponse {
+  /** Final text response (if any) */
+  text: string | null;
+  /** Tool calls requested by the model (if any) */
+  toolCalls: AIToolCall[];
+  /** Stop reason: 'end_turn' | 'tool_use' | 'max_tokens' */
+  stopReason: string;
+  /** Token usage */
+  usage: { inputTokens: number; outputTokens: number };
+}
+
+export interface AIAgentParams {
+  messages: AIMessage[];
+  systemPrompt?: string;
+  tools?: AIToolDefinition[];
+  maxTokens?: number;
+  temperature?: number;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Provider interface                                                 */
+/* ------------------------------------------------------------------ */
+
+export interface AIProvider {
+  readonly name: string;
+
+  /** Single-turn text generation */
+  generateText(params: AIGenerateTextParams): Promise<string>;
+
+  /** Single-turn JSON generation */
+  generateJson<T = unknown>(params: AIGenerateJsonParams<T>): Promise<T>;
+
+  /** Multi-turn conversational agent with tool calling */
+  converse(params: AIAgentParams): Promise<AIAgentResponse>;
+}

package/nestjs/src/integrations/ai/ai.module.ts

@@ -0,0 +1,11 @@
+import { Global, Module } from '@nestjs/common';
+import { OpenAIProvider } from './providers/openai.provider';
+import { AnthropicProvider } from './providers/anthropic.provider';
+import { AIService } from './ai.service';
+
+@Global()
+@Module({
+  providers: [OpenAIProvider, AnthropicProvider, AIService],
+  exports: [AIService],
+})
+export class AIModule {}

package/nestjs/src/integrations/ai/ai.service.ts

@@ -0,0 +1,148 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { OpenAIProvider } from './providers/openai.provider';
+import { AnthropicProvider } from './providers/anthropic.provider';
+import type { AIProvider, AIGenerateTextParams, AIAgentParams, AIAgentResponse, AIMessage, AIToolDefinition } from './ai.interface';
+
+export interface ProviderContext {
+  agentAiProvider?: string | null;
+  clinicAiProvider?: string | null;
+}
+
+export interface SessionLabels {
+  sentiment: string;
+  categories: string[];
+}
+
+@Injectable()
+export class AIService {
+  private readonly logger = new Logger(AIService.name);
+  private readonly providers: Map<string, AIProvider>;
+  private readonly defaultProvider: string;
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly openaiProvider: OpenAIProvider,
+    private readonly anthropicProvider: AnthropicProvider,
+  ) {
+    this.providers = new Map<string, AIProvider>([
+      ['openai', this.openaiProvider],
+      ['anthropic', this.anthropicProvider],
+    ]);
+    this.defaultProvider = this.config.get<string>(
+      'DEFAULT_AI_PROVIDER',
+      'openai',
+    );
+  }
+
+  /** Resolve a provider by name, falling back to DEFAULT_AI_PROVIDER env. */
+  getProvider(providerName?: string): AIProvider {
+    const name = providerName ?? this.defaultProvider;
+    const provider = this.providers.get(name);
+    if (!provider) {
+      this.logger.warn(
+        `Unknown AI provider "${name}", falling back to "${this.defaultProvider}"`,
+      );
+      return this.providers.get(this.defaultProvider)!;
+    }
+    return provider;
+  }
+
+  /** Resolve provider from agent > clinic > env chain. */
+  getProviderForContext(ctx: ProviderContext): AIProvider {
+    const name =
+      ctx.agentAiProvider ?? ctx.clinicAiProvider ?? this.defaultProvider;
+    return this.getProvider(name);
+  }
+
+  /** Generate a call/session summary from a transcript. */
+  async generateSummary(
+    transcript: string,
+    options?: { providerName?: string } & Partial<AIGenerateTextParams>,
+  ): Promise<string> {
+    const provider = this.getProvider(options?.providerName);
+    return provider.generateText({
+      systemPrompt:
+        options?.systemPrompt ??
+        'You are a medical clinic assistant. Summarize the following call transcript concisely in Turkish. Focus on key points: patient concerns, agreed actions, and next steps.',
+      prompt: transcript,
+      maxTokens: options?.maxTokens ?? 1024,
+      temperature: options?.temperature ?? 0.3,
+    });
+  }
+
+  /**
+   * Multi-turn conversational agent with tool calling.
+   * Handles the tool call loop automatically — calls tools and re-submits until
+   * the model produces a final text response or hits maxIterations.
+   */
+  async converse(
+    params: AIAgentParams & {
+      providerName?: string;
+      /** Called when the model requests a tool call. Return the result string. */
+      onToolCall?: (name: string, args: Record<string, any>) => Promise<string>;
+      /** Max tool call iterations before forcing a response (default 10) */
+      maxIterations?: number;
+    },
+  ): Promise<AIAgentResponse> {
+    const provider = this.getProvider(params.providerName);
+    const maxIter = params.maxIterations ?? 10;
+    const messages = [...params.messages];
+    let iteration = 0;
+    let lastResponse: AIAgentResponse;
+
+    do {
+      lastResponse = await provider.converse({
+        ...params,
+        messages,
+      });
+
+      // If no tool calls or no handler, return immediately
+      if (lastResponse.toolCalls.length === 0 || !params.onToolCall) {
+        return lastResponse;
+      }
+
+      // Process each tool call
+      for (const tc of lastResponse.toolCalls) {
+        this.logger.debug(`Tool call: ${tc.name}(${JSON.stringify(tc.arguments).substring(0, 200)})`);
+
+        let result: string;
+        try {
+          result = await params.onToolCall(tc.name, tc.arguments);
+        } catch (err: any) {
+          result = JSON.stringify({ error: err.message });
+        }
+
+        // Add assistant's tool call + result to conversation
+        // For Anthropic: the assistant message with tool_use is implicit
+        // We need to add the tool result
+        messages.push({
+          role: 'tool_result',
+          content: result,
+          toolCallId: tc.id,
+        });
+      }
+
+      iteration++;
+    } while (iteration < maxIter);
+
+    this.logger.warn(`Converse hit max iterations (${maxIter})`);
+    return lastResponse;
+  }
+
+  /** Extract sentiment and categories from text. */
+  async generateSessionLabels(
+    text: string,
+    options?: { providerName?: string },
+  ): Promise<SessionLabels> {
+    const provider = this.getProvider(options?.providerName);
+    return provider.generateJson<SessionLabels>({
+      systemPrompt:
+        'Analyze the following conversation text and extract sentiment and topic categories.',
+      prompt: text,
+      schema:
+        '{ "sentiment": "positive" | "neutral" | "negative", "categories": string[] }',
+      temperature: 0.1,
+    });
+  }
+}

package/nestjs/src/integrations/ai/providers/anthropic.provider.ts

@@ -0,0 +1,146 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import Anthropic from '@anthropic-ai/sdk';
+import type {
+  AIProvider,
+  AIGenerateTextParams,
+  AIGenerateJsonParams,
+  AIAgentParams,
+  AIAgentResponse,
+  AIToolCall,
+} from '../ai.interface';
+
+@Injectable()
+export class AnthropicProvider implements AIProvider {
+  readonly name = 'anthropic';
+  private readonly logger = new Logger(AnthropicProvider.name);
+  private readonly client: Anthropic;
+  private readonly model: string;
+
+  constructor(private readonly config: ConfigService) {
+    this.client = new Anthropic({
+      apiKey: this.config.get<string>('ANTHROPIC_API_KEY', ''),
+    });
+    this.model = this.config.get<string>('ANTHROPIC_MODEL', 'claude-sonnet-4-20250514');
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Single-turn text                                                   */
+  /* ------------------------------------------------------------------ */
+
+  async generateText(params: AIGenerateTextParams): Promise<string> {
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: params.maxTokens ?? 2048,
+      ...(params.systemPrompt ? { system: params.systemPrompt } : {}),
+      messages: [{ role: 'user', content: params.prompt }],
+    });
+
+    const block = response.content[0];
+    return block?.type === 'text' ? block.text : '';
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Single-turn JSON                                                   */
+  /* ------------------------------------------------------------------ */
+
+  async generateJson<T = unknown>(params: AIGenerateJsonParams<T>): Promise<T> {
+    const systemParts: string[] = [];
+    if (params.systemPrompt) systemParts.push(params.systemPrompt);
+    systemParts.push('Respond ONLY with valid JSON, no markdown fences.');
+    if (params.schema) systemParts.push(`Expected JSON shape: ${params.schema}`);
+
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: params.maxTokens ?? 2048,
+      system: systemParts.join('\n'),
+      messages: [{ role: 'user', content: params.prompt }],
+    });
+
+    const block = response.content[0];
+    const raw = block?.type === 'text' ? block.text : '{}';
+    return JSON.parse(raw) as T;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Multi-turn conversational agent with tool calling                  */
+  /* ------------------------------------------------------------------ */
+
+  async converse(params: AIAgentParams): Promise<AIAgentResponse> {
+    // Build Anthropic messages from our generic format
+    const messages: Anthropic.MessageParam[] = [];
+
+    for (const msg of params.messages) {
+      if (msg.role === 'system') continue; // system goes in the system param
+
+      if (msg.role === 'user') {
+        messages.push({ role: 'user', content: msg.content });
+      } else if (msg.role === 'assistant') {
+        messages.push({ role: 'assistant', content: msg.content });
+      } else if (msg.role === 'tool_result') {
+        messages.push({
+          role: 'user',
+          content: [
+            {
+              type: 'tool_result',
+              tool_use_id: msg.toolCallId!,
+              content: msg.content,
+            },
+          ],
+        });
+      }
+    }
+
+    // Build tool definitions
+    const tools: Anthropic.Tool[] | undefined = params.tools?.map((t) => ({
+      name: t.name,
+      description: t.description,
+      input_schema: t.parameters as Anthropic.Tool.InputSchema,
+    }));
+
+    // Build system prompt from explicit param + any system messages
+    const systemMessages = params.messages
+      .filter((m) => m.role === 'system')
+      .map((m) => m.content);
+    const systemParts = [
+      params.systemPrompt,
+      ...systemMessages,
+    ].filter(Boolean);
+    const system = systemParts.length > 0 ? systemParts.join('\n\n') : undefined;
+
+    const response = await this.client.messages.create({
+      model: this.model,
+      max_tokens: params.maxTokens ?? 4096,
+      temperature: params.temperature ?? 0.3,
+      ...(system ? { system } : {}),
+      messages,
+      ...(tools?.length ? { tools } : {}),
+    });
+
+    // Parse response
+    let text: string | null = null;
+    const toolCalls: AIToolCall[] = [];
+
+    for (const block of response.content) {
+      if (block.type === 'text') {
+        text = block.text;
+      } else if (block.type === 'tool_use') {
+        toolCalls.push({
+          id: block.id,
+          name: block.name,
+          arguments: block.input as Record<string, any>,
+        });
+      }
+    }
+
+    return {
+      text,
+      toolCalls,
+      stopReason: response.stop_reason ?? 'end_turn',
+      usage: {
+        inputTokens: response.usage.input_tokens,
+        outputTokens: response.usage.output_tokens,
+      },
+    };
+  }
+}

package/nestjs/src/integrations/ai/providers/openai.provider.ts

@@ -0,0 +1,158 @@
+import { Injectable, Logger } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import OpenAI from 'openai';
+import type {
+  AIProvider,
+  AIGenerateTextParams,
+  AIGenerateJsonParams,
+  AIAgentParams,
+  AIAgentResponse,
+  AIToolCall,
+} from '../ai.interface';
+
+@Injectable()
+export class OpenAIProvider implements AIProvider {
+  readonly name = 'openai';
+  private readonly logger = new Logger(OpenAIProvider.name);
+  private readonly client: OpenAI;
+  private readonly model: string;
+
+  /** Models that don't support temperature / only accept default (1). */
+  private static readonly NO_TEMP_MODELS = /^(o[1-9]|gpt-5)/;
+
+  constructor(private readonly config: ConfigService) {
+    this.client = new OpenAI({
+      apiKey: this.config.get<string>('OPENAI_API_KEY', ''),
+    });
+    this.model = this.config.get<string>('OPENAI_MODEL', 'gpt-4o');
+  }
+
+  private supportsTemperature(): boolean {
+    return !OpenAIProvider.NO_TEMP_MODELS.test(this.model);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Single-turn text                                                   */
+  /* ------------------------------------------------------------------ */
+
+  async generateText(params: AIGenerateTextParams): Promise<string> {
+    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [];
+
+    if (params.systemPrompt) {
+      messages.push({ role: 'system', content: params.systemPrompt });
+    }
+    messages.push({ role: 'user', content: params.prompt });
+
+    const response = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      max_completion_tokens: params.maxTokens ?? 2048,
+      ...(this.supportsTemperature() ? { temperature: params.temperature ?? 0.3 } : {}),
+    });
+
+    return response.choices[0]?.message?.content ?? '';
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Single-turn JSON                                                   */
+  /* ------------------------------------------------------------------ */
+
+  async generateJson<T = unknown>(params: AIGenerateJsonParams<T>): Promise<T> {
+    const systemParts: string[] = [];
+    if (params.systemPrompt) systemParts.push(params.systemPrompt);
+    systemParts.push('Respond ONLY with valid JSON, no markdown fences.');
+    if (params.schema) systemParts.push(`Expected JSON shape: ${params.schema}`);
+
+    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+      { role: 'system', content: systemParts.join('\n') },
+      { role: 'user', content: params.prompt },
+    ];
+
+    const response = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      max_completion_tokens: params.maxTokens ?? 2048,
+      ...(this.supportsTemperature() ? { temperature: params.temperature ?? 0.1 } : {}),
+      response_format: { type: 'json_object' },
+    });
+
+    const raw = response.choices[0]?.message?.content ?? '{}';
+    return JSON.parse(raw) as T;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Multi-turn conversational agent with tool calling                  */
+  /* ------------------------------------------------------------------ */
+
+  async converse(params: AIAgentParams): Promise<AIAgentResponse> {
+    const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [];
+
+    // System prompt
+    const systemMessages = params.messages
+      .filter((m) => m.role === 'system')
+      .map((m) => m.content);
+    const systemParts = [params.systemPrompt, ...systemMessages].filter(Boolean);
+    if (systemParts.length > 0) {
+      messages.push({ role: 'system', content: systemParts.join('\n\n') });
+    }
+
+    // Conversation messages
+    for (const msg of params.messages) {
+      if (msg.role === 'system') continue;
+
+      if (msg.role === 'user') {
+        messages.push({ role: 'user', content: msg.content });
+      } else if (msg.role === 'assistant') {
+        messages.push({ role: 'assistant', content: msg.content });
+      } else if (msg.role === 'tool_result') {
+        messages.push({
+          role: 'tool',
+          tool_call_id: msg.toolCallId!,
+          content: msg.content,
+        });
+      }
+    }
+
+    // Build tools
+    const tools: OpenAI.Chat.ChatCompletionTool[] | undefined = params.tools?.map((t) => ({
+      type: 'function' as const,
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+
+    const response = await this.client.chat.completions.create({
+      model: this.model,
+      messages,
+      max_completion_tokens: params.maxTokens ?? 4096,
+      ...(this.supportsTemperature() ? { temperature: params.temperature ?? 0.3 } : {}),
+      ...(tools?.length ? { tools } : {}),
+    });
+
+    const choice = response.choices[0];
+    const text = choice?.message?.content ?? null;
+    const toolCalls: AIToolCall[] = (choice?.message?.tool_calls ?? [])
+      .filter((tc): tc is OpenAI.Chat.ChatCompletionMessageToolCall & { type: 'function' } => tc.type === 'function')
+      .map((tc) => ({
+        id: tc.id,
+        name: tc.function.name,
+        arguments: JSON.parse(tc.function.arguments || '{}'),
+      }));
+
+    const stopReason = choice?.finish_reason === 'tool_calls' ? 'tool_use'
+      : choice?.finish_reason === 'stop' ? 'end_turn'
+      : choice?.finish_reason ?? 'end_turn';
+
+    return {
+      text,
+      toolCalls,
+      stopReason,
+      usage: {
+        inputTokens: response.usage?.prompt_tokens ?? 0,
+        outputTokens: response.usage?.completion_tokens ?? 0,
+      },
+    };
+  }
+}

package/nestjs/src/integrations/elevenlabs/elevenlabs.module.ts

@@ -0,0 +1,8 @@
+import { Module } from '@nestjs/common';
+import { ElevenLabsService } from './elevenlabs.service';
+
+@Module({
+  providers: [ElevenLabsService],
+  exports: [ElevenLabsService],
+})
+export class ElevenLabsModule {}