@contentgrowth/llm-service 1.2.4 → 1.3.1

package/README.md

@@ -81,6 +81,238 @@ ConfigManager.setConfigProvider(new MyDatabaseConfigProvider());
 const service = new LLMService(env);
 ```
 
+### Google Gemini & Vertex AI Configuration
+
+The service provides unified support for Google's AI platforms through the `@google/genai` SDK:
+
+#### 1. Gemini AI Studio (Consumer API)
+Uses your AI Studio API key directly.
+```env
+LLM_PROVIDER=gemini
+GEMINI_API_KEY=your-api-key-from-ai-studio
+GEMINI_MODEL=gemini-3.5-flash
+```
+
+#### 2. Vertex AI (Enterprise) — Two Authentication Modes
+
+| Mode | Use Case | Required Config |
+|------|----------|-----------------|
+| **ADC / IAM (Default)** | Production, service accounts, Workload Identity | `VERTEX_PROJECT`, `VERTEX_LOCATION` |
+| **Express Mode (API Key)** | Quick setup, dev/test, no service account | `VERTEX_API_KEY` (project auto-resolved) |
+
+**Vertex Express Mode (API Key)** — Recommended for quick setup:
+```env
+LLM_PROVIDER=vertex
+VERTEX_API_KEY=AIza...   # API key from Vertex AI Studio
+# VERTEX_PROJECT and VERTEX_LOCATION are OPTIONAL — SDK resolves project from key
+```
+
+**Vertex ADC/IAM Mode** — For production with service accounts:
+```env
+LLM_PROVIDER=vertex
+VERTEX_PROJECT=your-gcp-project-id
+VERTEX_LOCATION=us-central1
+# VERTEX_API_KEY is NOT needed (uses Application Default Credentials)
+```
+
+**Legacy aliases** (also supported):
+- `GOOGLE_CLOUD_PROJECT` → `VERTEX_PROJECT`
+- `GOOGLE_CLOUD_LOCATION` → `VERTEX_LOCATION`
+
+#### Model Overrides (All Providers)
+```env
+VERTEX_MODEL=gemini-3.5-flash
+VERTEX_MODEL_EDGE=gemini-3.5-pro
+VERTEX_MODEL_FAST=gemini-3.5-flash
+VERTEX_IMAGE_MODEL=gemini-3.5-pro-image-preview
+VERTEX_VIDEO_MODEL=veo
+```
+
+---
+
+### Programmatic Configuration (No Environment Variables)
+
+You can configure the provider directly via code by implementing a custom `ConfigProvider`. This is useful when you don't want to rely on environment variables or need dynamic configuration.
+
+#### Vertex Express Mode (API Key) — Programmatic
+
+```javascript
+import { LLMService, ConfigManager, BaseConfigProvider } from '@contentgrowth/llm-service';
+
+class VertexExpressConfigProvider extends BaseConfigProvider {
+  constructor(apiKey) {
+    super();
+    this.apiKey = apiKey;
+  }
+
+  async getConfig(tenantId, env) {
+    return {
+      provider: 'vertex',
+      apiKey: this.apiKey,
+      // project & location are OPTIONAL — SDK resolves from API key
+      models: {
+        default: 'gemini-3.5-flash',
+        edge: 'gemini-3.5-pro',
+        fast: 'gemini-3.5-flash',
+        image: 'gemini-3.5-pro-image-preview',
+        video: 'veo',
+      },
+      temperature: 0.7,
+      maxTokens: 65536,
+      capabilities: { chat: true, image: true, video: true },
+    };
+  }
+}
+
+// Register once at startup
+ConfigManager.setConfigProvider(new VertexExpressConfigProvider('AIza...'));
+
+// Use normally
+const service = new LLMService(env);
+const response = await service.chat('Hello Vertex!', 'tenant-id');
+```
+
+#### Vertex ADC/IAM Mode — Programmatic
+
+```javascript
+class VertexADCConfigProvider extends BaseConfigProvider {
+  constructor(project, location = 'us-central1') {
+    super();
+    this.project = project;
+    this.location = location;
+  }
+
+  async getConfig(tenantId, env) {
+    return {
+      provider: 'vertex',
+      project: this.project,
+      location: this.location,
+      // apiKey NOT needed — uses Application Default Credentials
+      models: {
+        default: 'gemini-3.5-flash',
+        edge: 'gemini-3.5-pro',
+        fast: 'gemini-3.5-flash',
+        image: 'gemini-3.5-pro-image-preview',
+        video: 'veo',
+      },
+      temperature: 0.7,
+      maxTokens: 65536,
+      capabilities: { chat: true, image: true, video: true },
+    };
+  }
+}
+
+ConfigManager.setConfigProvider(new VertexADCConfigProvider('my-gcp-project', 'us-central1'));
+```
+
+#### Gemini AI Studio — Programmatic
+
+```javascript
+class GeminiStudioConfigProvider extends BaseConfigProvider {
+  constructor(apiKey) {
+    super();
+    this.apiKey = apiKey;
+  }
+
+  async getConfig(tenantId, env) {
+    return {
+      provider: 'gemini',
+      apiKey: this.apiKey,
+      models: {
+        default: 'gemini-3.5-flash',
+        edge: 'gemini-3.5-pro',
+        fast: 'gemini-3.5-flash',
+        image: 'gemini-3.5-pro-image-preview',
+        video: 'veo',
+      },
+      temperature: 0.7,
+      maxTokens: 65536,
+      capabilities: { chat: true, image: true, video: true },
+    };
+  }
+}
+
+ConfigManager.setConfigProvider(new GeminiStudioConfigProvider('your-gemini-api-key'));
+```
+
+---
+
+### Custom & OpenAI-Compatible Providers
+
+Many third-party LLM proxies and gateways (LiteLLM, OpenRouter, custom corporate proxies) expose an OpenAI-compatible API. Because the OpenAI provider in this library accepts a `baseURL` override, you can point it at any of these services and use any model they expose — including Gemini, Claude, or your own fine-tuned models — without writing a custom provider.
+
+#### How it works
+
+Set `LLM_PROVIDER=openai`, point `OPENAI_BASE_URL` at your proxy, and set `OPENAI_MODEL` to whatever model name your proxy advertises. The library sends standard OpenAI-format requests; your proxy handles the translation.
+
+#### Example: Gemini via an OpenAI-compatible proxy
+
+```env
+LLM_PROVIDER=openai
+OPENAI_API_KEY=your-proxy-api-key
+OPENAI_BASE_URL=https://your-proxy.example.com/v1
+OPENAI_MODEL=gemini-3.5-flash
+```
+
+No code changes needed. All features — chat, tool calling, JSON mode — work through the proxy using the OpenAI wire format.
+
+#### Example: Programmatic configuration
+
+```javascript
+import { LLMService, ConfigManager, BaseConfigProvider } from '@contentgrowth/llm-service';
+
+class ProxyConfigProvider extends BaseConfigProvider {
+  async getConfig(tenantId, env) {
+    return {
+      provider: 'openai',
+      apiKey: 'your-proxy-api-key',
+      baseURL: 'https://your-proxy.example.com/v1',
+      models: {
+        default: 'gemini-3.5-flash',
+        fast: 'gemini-3.5-flash',
+        edge: 'gemini-3.5-pro',
+      },
+      temperature: 0.7,
+      maxTokens: 65536,
+    };
+  }
+}
+
+ConfigManager.setConfigProvider(new ProxyConfigProvider());
+const service = new LLMService(env);
+```
+
+#### BYOK tenants via proxy
+
+For multi-tenant setups, tenants can supply their own proxy endpoint alongside their API key:
+
+```json
+{
+  "provider": "openai",
+  "api_key": "tenant-proxy-key",
+  "baseURL": "https://tenant-proxy.example.com/v1"
+}
+```
+
+#### baseURL support across all providers
+
+Every provider respects a `baseURL` override, both from environment variables and from the tenant config object:
+
+| Provider | Env var | Shared fallback |
+|----------|---------|-----------------|
+| `openai` | `OPENAI_BASE_URL` | `LLM_BASE_URL` |
+| `gemini` | `GEMINI_BASE_URL` | `LLM_BASE_URL` |
+| `anthropic` | `ANTHROPIC_BASE_URL` | `LLM_BASE_URL` |
+| `vertex` | `VERTEX_BASE_URL` | `LLM_BASE_URL` |
+
+`LLM_BASE_URL` applies to whichever provider is active, useful when routing all traffic through a single proxy regardless of provider.
+
+#### Caveat: JSON schema mode
+
+If your proxy doesn't natively support OpenAI's `response_format: { type: 'json_schema' }` for the model it's proxying, strict schema mode may fall back to `json_object` or return an error. Proxies like LiteLLM handle this by translating to the target model's native format, but not all do. Test with a `chatCompletionJson` call first to confirm schema mode works end-to-end.
+
+---
+
 ### JSON Mode & Structured Outputs
 
 The service supports native JSON mode for OpenAI and Gemini, guaranteeing valid JSON responses without escaping issues.

package/dist/index.cjs

@@ -125,6 +125,7 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
       models: MODEL_CONFIGS[tenantConfig.provider],
       // for backward compatibility, api_key is deprecated and shall never be used!!
       apiKey: tenantConfig.apiKey || tenantConfig.api_key,
+      baseURL: tenantConfig.baseURL || tenantConfig.base_url || void 0,
       project: tenantConfig.project,
       location: tenantConfig.location,
       temperature: parseFloat(env.DEFAULT_TEMPERATURE || "0.7"),
@@ -138,9 +139,11 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
     const provider = ((_a = env.LLM_PROVIDER) == null ? void 0 : _a.toLowerCase()) || "openai";
     const providerDefaults = MODEL_CONFIGS[provider] || MODEL_CONFIGS["openai"];
     let apiKey;
+    let baseURL;
     let models = { ...providerDefaults };
     if (provider === "openai") {
       apiKey = env.OPENAI_API_KEY;
+      baseURL = env.OPENAI_BASE_URL || env.LLM_BASE_URL || void 0;
       models = {
         default: env.OPENAI_MODEL || providerDefaults.default,
         edge: env.OPENAI_MODEL_EDGE || providerDefaults.edge,
@@ -150,6 +153,7 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
       };
     } else if (provider === "gemini") {
       apiKey = env.GEMINI_API_KEY;
+      baseURL = env.GEMINI_BASE_URL || env.LLM_BASE_URL || void 0;
       models = {
         default: env.GEMINI_MODEL || providerDefaults.default,
         edge: env.GEMINI_MODEL_EDGE || providerDefaults.edge,
@@ -159,8 +163,19 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
         image: env.GEMINI_IMAGE_MODEL || providerDefaults.image,
         video: env.GEMINI_VIDEO_MODEL || providerDefaults.video
       };
+    } else if (provider === "anthropic") {
+      apiKey = env.ANTHROPIC_API_KEY;
+      baseURL = env.ANTHROPIC_BASE_URL || env.LLM_BASE_URL || void 0;
+      models = {
+        default: env.ANTHROPIC_MODEL || providerDefaults.default,
+        edge: env.ANTHROPIC_MODEL_EDGE || providerDefaults.edge,
+        fast: env.ANTHROPIC_MODEL_FAST || providerDefaults.fast,
+        cost: env.ANTHROPIC_MODEL_COST || providerDefaults.cost,
+        free: env.ANTHROPIC_MODEL_FREE || providerDefaults.free
+      };
     } else if (provider === "vertex") {
       apiKey = env.VERTEX_API_KEY;
+      baseURL = env.VERTEX_BASE_URL || env.LLM_BASE_URL || void 0;
       const project = env.VERTEX_PROJECT || env.GOOGLE_CLOUD_PROJECT;
       const location = env.VERTEX_LOCATION || env.GOOGLE_CLOUD_LOCATION || "us-central1";
       models = {
@@ -175,6 +190,7 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
       return {
         provider,
         apiKey,
+        baseURL,
         project,
         location,
         models,
@@ -185,6 +201,7 @@ var DefaultConfigProvider = class extends BaseConfigProvider {
     return {
       provider,
       apiKey,
+      baseURL,
       models,
       temperature: parseFloat(env.DEFAULT_TEMPERATURE || "0.7"),
       maxTokens: parseInt(env.DEFAULT_MAX_TOKENS || "65536")
@@ -448,7 +465,11 @@ function extractTextAndJson(input) {
 var OpenAIProvider = class extends BaseLLMProvider {
   constructor(config) {
     super(config);
-    this.client = new import_openai.default({ apiKey: config.apiKey });
+    const clientOptions = { apiKey: config.apiKey };
+    if (config.baseURL) {
+      clientOptions.baseURL = config.baseURL;
+    }
+    this.client = new import_openai.default(clientOptions);
     this.models = config.models;
     this.defaultModel = config.models.default;
   }
@@ -630,11 +651,13 @@ var GoogleProvider = class extends BaseLLMProvider {
     this.models = config.models;
     this.defaultModel = config.models.default;
     this._pendingOperations = /* @__PURE__ */ new Map();
+    const httpOptions = config.baseURL ? { baseUrl: config.baseURL } : void 0;
     if (config.provider === "vertex") {
       if (config.apiKey) {
         this.client = new import_genai.GoogleGenAI({
           vertexai: true,
-          apiKey: config.apiKey
+          apiKey: config.apiKey,
+          ...httpOptions ? { httpOptions } : {}
         });
       } else {
         if (!config.project) {
@@ -643,12 +666,14 @@ var GoogleProvider = class extends BaseLLMProvider {
         this.client = new import_genai.GoogleGenAI({
           vertexai: true,
           project: config.project,
-          location: config.location || "us-central1"
+          location: config.location || "us-central1",
+          ...httpOptions ? { httpOptions } : {}
         });
       }
     } else {
       this.client = new import_genai.GoogleGenAI({
-        apiKey: config.apiKey
+        apiKey: config.apiKey,
+        ...httpOptions ? { httpOptions } : {}
       });
     }
   }
@@ -1197,14 +1222,66 @@ ${prompt}` : prompt;
       throw error;
     }
   }
+  /**
+   * Text-to-Speech synthesis using Gemini TTS models
+   * @param {string} text - Text to synthesize
+   * @param {Object} options - TTS options
+   * @param {string} options.voice - Voice name (default: 'Aoede')
+   * @param {string} options.model - Model to use (default: from config)
+   * @returns {Promise<Buffer>} Audio data as Buffer
+   */
+  async textToSpeech(text, options = {}) {
+    var _a, _b, _c, _d, _e;
+    const voice = options.voice || "Aoede";
+    const modelName = options.model || this.models.tts || "gemini-3.1-flash-tts-preview";
+    const requestOptions = {
+      model: modelName,
+      contents: [{
+        role: "user",
+        parts: [{ text }]
+      }],
+      config: {
+        responseModalities: ["AUDIO"],
+        speechConfig: {
+          voiceConfig: {
+            prebuiltVoiceConfig: {
+              voiceName: voice
+            }
+          }
+        }
+      }
+    };
+    try {
+      const response = await this._generateContent(requestOptions);
+      const candidate = (_a = response.candidates) == null ? void 0 : _a[0];
+      if (!candidate) {
+        throw new LLMServiceException("No candidates returned from TTS model", 500);
+      }
+      const audioPart = (_c = (_b = candidate.content) == null ? void 0 : _b.parts) == null ? void 0 : _c.find((p) => p.inlineData || p.inline_data);
+      const audioB64 = ((_d = audioPart == null ? void 0 : audioPart.inlineData) == null ? void 0 : _d.data) || ((_e = audioPart == null ? void 0 : audioPart.inline_data) == null ? void 0 : _e.data);
+      if (!audioB64) {
+        throw new LLMServiceException("No audio data returned from TTS model", 500);
+      }
+      return Buffer.from(audioB64, "base64");
+    } catch (error) {
+      console.error(`[${this.constructor.name}] textToSpeech failed (API Key: ${this._getMaskedApiKey()}):`, error);
+      throw error;
+    }
+  }
 };
 
 // src/llm/providers/anthropic-provider.js
+var import_sdk = __toESM(require("@anthropic-ai/sdk"), 1);
 var AnthropicProvider = class extends BaseLLMProvider {
   constructor(config) {
     super(config);
     this.models = config.models || {};
     this.defaultModel = this.models.default || "claude-3-5-sonnet-20241022";
+    const clientOptions = { apiKey: config.apiKey || "" };
+    if (config.baseURL) {
+      clientOptions.baseURL = config.baseURL;
+    }
+    this.client = new import_sdk.default(clientOptions);
   }
   async chat(userMessage, systemPrompt = "", options = {}) {
     var _a;
@@ -1241,82 +1318,69 @@ var AnthropicProvider = class extends BaseLLMProvider {
     );
   }
   async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature, options = {}) {
-    const baseURL = this.config.baseURL || "https://api.anthropic.com";
-    const url = `${baseURL.replace(/\/$/, "")}/v1/messages`;
-    const formattedMessages = messages.map((m) => ({
-      role: m.role === "assistant" ? "assistant" : "user",
-      content: m.content
-    }));
-    const headers = {
-      "Content-Type": "application/json",
-      "x-api-key": this.config.apiKey || "",
-      "anthropic-version": "2023-06-01"
-    };
-    const payload = {
-      model: modelName,
-      messages: formattedMessages,
-      max_tokens: maxTokens,
-      temperature
-    };
-    if (systemPrompt) {
-      payload.system = systemPrompt;
-    }
+    var _a, _b, _c, _d;
+    let effectiveSystem = systemPrompt || void 0;
     if (options.responseFormat) {
       const formatType = typeof options.responseFormat === "string" ? options.responseFormat : options.responseFormat.type;
       if (formatType === "json" || formatType === "json_schema") {
-        const schemaText = options.responseFormat.schema || options.responseSchema ? `
+        const schema = options.responseFormat.schema || options.responseSchema;
+        const schemaText = schema ? `
 
-Your output must comply strictly with this JSON Schema: ${JSON.stringify(options.responseFormat.schema || options.responseSchema)}` : "";
+Your output must comply strictly with this JSON Schema: ${JSON.stringify(schema)}` : "";
         const jsonPrompt = `IMPORTANT: You must respond ONLY in raw JSON format. Do not write any conversational text, explanations, or markdown code blocks (e.g. do NOT wrap your answer in \`\`\`json ... \`\`\`). Your response must start with '{' and end with '}'.${schemaText}`;
-        if (payload.system) {
-          payload.system = `${payload.system}
+        effectiveSystem = effectiveSystem ? `${effectiveSystem}
 
-${jsonPrompt}`;
-        } else {
-          payload.system = jsonPrompt;
-        }
+${jsonPrompt}` : jsonPrompt;
       }
     }
-    let responseText;
-    let responseData;
+    const anthropicMessages = this._formatMessages(messages);
+    const anthropicTools = tools ? this._formatTools(tools) : void 0;
+    const requestParams = {
+      model: modelName,
+      max_tokens: maxTokens,
+      temperature,
+      messages: anthropicMessages,
+      ...effectiveSystem ? { system: effectiveSystem } : {},
+      ...anthropicTools ? { tools: anthropicTools } : {}
+    };
+    let response;
     try {
-      const res = await fetch(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(payload)
-      });
-      responseText = await res.text();
-      if (!res.ok) {
-        console.error(`[AnthropicProvider] API request failed with status ${res.status}:`, responseText);
-        throw new LLMServiceException(`Anthropic API Error: ${responseText}`, res.status);
-      }
-      responseData = JSON.parse(responseText);
+      response = await this.client.messages.create(requestParams);
     } catch (error) {
       console.error(`[AnthropicProvider] request failed (API Key: ${this._getMaskedApiKey()}):`, error);
       throw error;
     }
-    const contentBlock = responseData.content && responseData.content[0];
-    const contentText = contentBlock ? contentBlock.text : "";
-    if (!contentText) {
-      console.error("[AnthropicProvider] Model returned empty response content");
+    const textBlocks = response.content.filter((b) => b.type === "text");
+    const toolUseBlocks = response.content.filter((b) => b.type === "tool_use");
+    const contentText = textBlocks.map((b) => b.text).join("");
+    if (!contentText && toolUseBlocks.length === 0) {
+      console.error("[AnthropicProvider] Model returned empty response (no text, no tool calls)");
       throw new LLMServiceException(
         "Model returned empty response. This usually means the prompt or schema is confusing the model.",
         500
       );
     }
-    const rawFinishReason = responseData.stop_reason;
+    const toolCalls = toolUseBlocks.length > 0 ? toolUseBlocks.map((block) => ({
+      id: block.id,
+      type: "function",
+      function: {
+        name: block.name,
+        // Anthropic returns args as a parsed object; serialize to string to match OpenAI shape
+        arguments: JSON.stringify(block.input || {})
+      }
+    })) : null;
+    const rawFinishReason = response.stop_reason;
     const normalizedFinishReason = this.normalizeFinishReason(rawFinishReason);
     const result = {
       content: contentText,
-      tool_calls: null,
-      // REST client tool calls mapping not required for playbook studio
+      tool_calls: toolCalls,
       finishReason: normalizedFinishReason,
       _rawFinishReason: rawFinishReason,
       _responseFormat: options.responseFormat,
       usage: {
-        prompt_tokens: responseData.usage ? responseData.usage.input_tokens : 0,
-        completion_tokens: responseData.usage ? responseData.usage.output_tokens : 0,
-        total_tokens: responseData.usage ? responseData.usage.input_tokens + responseData.usage.output_tokens : 0
+        prompt_tokens: ((_a = response.usage) == null ? void 0 : _a.input_tokens) || 0,
+        completion_tokens: ((_b = response.usage) == null ? void 0 : _b.output_tokens) || 0,
+        total_tokens: (((_c = response.usage) == null ? void 0 : _c.input_tokens) || 0) + (((_d = response.usage) == null ? void 0 : _d.output_tokens) || 0)
       },
       model: modelName
     };
@@ -1325,11 +1389,110 @@ ${jsonPrompt}`;
     }
     return result;
   }
-  _getModelForTier(tier) {
-    if (this.models[tier]) {
-      return this.models[tier];
+  /**
+   * Convert standard {role, content, tool_calls, tool_call_id} messages
+   * to Anthropic's message format.
+   *
+   * Key differences from OpenAI:
+   * - No 'system' role in messages array (handled via top-level `system` param)
+   * - Tool results go as role:'user' with content type:'tool_result'
+   * - Assistant messages with tool calls use an array of content blocks
+   * - Roles must strictly alternate user/assistant
+   */
+  _formatMessages(messages) {
+    const result = [];
+    for (const msg of messages) {
+      if (msg.role === "system") {
+        continue;
+      }
+      if (msg.role === "tool") {
+        const toolResultBlock = {
+          type: "tool_result",
+          tool_use_id: msg.tool_call_id,
+          content: typeof msg.content === "string" ? msg.content : JSON.stringify(msg.content)
+        };
+        const last = result[result.length - 1];
+        if (last && last.role === "user" && Array.isArray(last.content)) {
+          last.content.push(toolResultBlock);
+        } else {
+          result.push({ role: "user", content: [toolResultBlock] });
+        }
+        continue;
+      }
+      if (msg.role === "assistant") {
+        if (msg.tool_calls && msg.tool_calls.length > 0) {
+          const contentBlocks = [];
+          if (msg.content) {
+            contentBlocks.push({ type: "text", text: msg.content });
+          }
+          for (const tc of msg.tool_calls) {
+            let inputArgs = tc.function.arguments;
+            if (typeof inputArgs === "string") {
+              try {
+                inputArgs = JSON.parse(inputArgs);
+              } catch (_) {
+                inputArgs = {};
+              }
+            }
+            contentBlocks.push({
+              type: "tool_use",
+              id: tc.id,
+              name: tc.function.name,
+              input: inputArgs
+            });
+          }
+          result.push({ role: "assistant", content: contentBlocks });
+        } else {
+          result.push({ role: "assistant", content: msg.content || "" });
+        }
+        continue;
+      }
+      result.push({ role: "user", content: msg.content || "" });
     }
-    return this.defaultModel;
+    return result;
+  }
+  /**
+   * Convert OpenAI-style tool definitions to Anthropic format.
+   * OpenAI:    { type: 'function', function: { name, description, parameters } }
+   * Anthropic: { name, description, input_schema }
+   */
+  _formatTools(tools) {
+    return tools.map((tool) => {
+      const fn = tool.function || tool;
+      return {
+        name: fn.name,
+        description: fn.description || "",
+        input_schema: fn.parameters || fn.input_schema || { type: "object", properties: {} }
+      };
+    });
+  }
+  async executeTools(tool_calls, messages, tenantId, toolImplementations, env) {
+    const toolResults = await Promise.all(
+      tool_calls.map(async (toolCall) => {
+        const toolName = toolCall.function.name;
+        const tool = toolImplementations[toolName];
+        console.log(`[Tool Call] ${toolName} with arguments:`, toolCall.function.arguments);
+        if (!tool) {
+          console.error(`[Tool Error] Tool '${toolName}' not found`);
+          return { tool_call_id: toolCall.id, output: JSON.stringify({ error: `Tool '${toolName}' not found.` }) };
+        }
+        try {
+          const output = await tool(toolCall.function.arguments, { env, tenantId });
+          const preview = typeof output === "string" ? output.length > 200 ? output.substring(0, 200) + "..." : output : JSON.stringify(output).substring(0, 200) + "...";
+          console.log(`[Tool Result] ${toolName} returned:`, preview);
+          return { tool_call_id: toolCall.id, output };
+        } catch (error) {
+          console.error(`[Tool Error] ${toolName} failed:`, error.message);
+          return { tool_call_id: toolCall.id, output: JSON.stringify({ error: `Error executing tool '${toolName}': ${error.message}` }) };
+        }
+      })
+    );
+    toolResults.forEach(
+      (result) => messages.push({ role: "tool", tool_call_id: result.tool_call_id, content: result.output })
+    );
+  }
+  _getModelForTier(tier) {
+    return this.models[tier] || this.defaultModel;
   }
   _shouldAutoParse(options) {
     if (!options.responseFormat) return false;
@@ -1350,15 +1513,10 @@ ${jsonPrompt}`;
   }
   normalizeFinishReason(providerReason) {
     const lower = (providerReason || "").toLowerCase();
-    if (lower === "end_turn") {
-      return "completed";
-    }
-    if (lower === "max_tokens") {
-      return "truncated";
-    }
-    if (lower === "stop_sequence") {
-      return "completed";
-    }
+    if (lower === "end_turn") return "completed";
+    if (lower === "max_tokens") return "truncated";
+    if (lower === "stop_sequence") return "completed";
+    if (lower === "tool_use") return "tool_call";
     return super.normalizeFinishReason(providerReason);
   }
 };