@contentgrowth/llm-service 0.3.0

package/README.md

@@ -0,0 +1,114 @@
+# @contentgrowth/llm-service
+
+Unified LLM Service for Content Growth applications. This package provides a standardized interface for interacting with various LLM providers (OpenAI, Gemini) and supports "Bring Your Own Key" (BYOK) functionality via pluggable configuration.
+
+## Installation
+
+```bash
+npm install @contentgrowth/llm-service
+```
+
+## Usage
+
+### Basic Usage
+
+The service requires an environment object (usually from Cloudflare Workers) to access bindings.
+
+```javascript
+import { LLMService } from '@contentgrowth/llm-service';
+
+// In your Worker
+export default {
+  async fetch(request, env, ctx) {
+    const llmService = new LLMService(env);
+    
+    // Chat
+    const response = await llmService.chat('Hello, how are you?', 'tenant-id');
+    console.log(response.text);
+    
+    // Chat Completion (with system prompt)
+    const result = await llmService.chatCompletion(
+      [{ role: 'user', content: 'Write a poem' }],
+      'tenant-id',
+      'You are a poetic assistant'
+    );
+    console.log(result.content);
+  }
+}
+```
+
+### Configuration & BYOK
+
+The service uses a `ConfigManager` to determine which LLM provider and API key to use for a given tenant.
+
+#### Default Behavior (Cloudflare KV + Durable Objects)
+By default, the service expects the `env` object passed to the constructor to contain:
+- `TENANT_LLM_CONFIG`: A KV Namespace binding.
+- `TENANT_DO`: A Durable Object Namespace binding.
+
+It uses these to fetch tenant-specific configurations.
+
+#### Custom Configuration (Pluggable Providers)
+If your project stores tenant keys differently (e.g., in a SQL database, environment variables, or a different service), you can implement a custom `ConfigProvider`.
+
+```javascript
+import { LLMService, ConfigManager, BaseConfigProvider } from '@contentgrowth/llm-service';
+
+// 1. Define your custom provider
+class MyDatabaseConfigProvider extends BaseConfigProvider {
+  async getConfig(tenantId, env) {
+    // Fetch config from your database or other source
+    // You can use 'env' here if you need access to bindings
+    const apiKey = await getApiKeyFromDB(tenantId);
+    
+    return {
+      provider: 'openai', // or 'gemini'
+      apiKey: apiKey,
+      models: { 
+        default: 'gpt-4o',
+        // ... optional overrides
+      },
+      // Optional capabilities
+      capabilities: { chat: true, image: true }
+    };
+  }
+}
+
+// 2. Register the provider at application startup
+ConfigManager.setConfigProvider(new MyDatabaseConfigProvider());
+
+// 3. Use LLMService as normal - it will now use your provider
+const service = new LLMService(env);
+```
+
+## Publishing
+
+To publish this package to NPM:
+
+1.  **Update Version**:
+    Update the `version` in `package.json`.
+
+2.  **Login to NPM**:
+    ```bash
+    npm login
+    ```
+
+3.  **Publish**:
+    ```bash
+    # For public access
+    npm publish --access public
+    ```
+
+## Development
+
+### Directory Structure
+- `src/llm-service.js`: Main service class.
+- `src/llm/config-manager.js`: Configuration resolution logic.
+- `src/llm/config-provider.js`: Abstract provider interfaces.
+- `src/llm/providers/`: Individual LLM provider implementations.
+
+### Testing
+Run the local test script to verify imports and configuration:
+```bash
+node test-custom-config.js
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@contentgrowth/llm-service",
+  "version": "0.3.0",
+  "description": "Unified LLM Service for Content Growth",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "test:live": "node test-live.js"
+  },
+  "author": "Content Growth",
+  "license": "MIT",
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "openai": "^6.9.1"
+  },
+  "devDependencies": {
+    "dotenv": "^17.2.3"
+  },
+  "files": [
+    "src"
+  ]
+}

package/src/index.js

@@ -0,0 +1,6 @@
+export { LLMService, LLMServiceException } from './llm-service.js';
+export { ConfigManager } from './llm/config-manager.js';
+export { BaseConfigProvider, DefaultConfigProvider } from './llm/config-provider.js';
+export { MODEL_CONFIGS } from './llm/config-manager.js';
+export { OpenAIProvider } from './llm/providers/openai-provider.js';
+export { GeminiProvider } from './llm/providers/gemini-provider.js';

package/src/llm/config-manager.js

@@ -0,0 +1,42 @@
+/**
+ * Manages LLM configuration resolution.
+ * Prioritizes Tenant KV config over System Environment config.
+ */
+
+
+
+import { DefaultConfigProvider } from './config-provider.js';
+
+export const MODEL_CONFIGS = {
+    openai: {
+        default: 'gpt-4o',
+        edge: 'gpt-4o',
+        fast: 'gpt-4o-mini',
+        cost: 'gpt-4o-mini',
+        free: 'gpt-4o-mini',
+    },
+    gemini: {
+        default: 'gemini-2.5-flash',
+        edge: 'gemini-2.5-pro',
+        fast: 'gemini-2.5-flash-lite',
+        cost: 'gemini-2.5-flash-lite',
+        free: 'gemini-2.0-flash-lite',
+    },
+};
+
+export class ConfigManager {
+    static _provider = new DefaultConfigProvider();
+
+    /**
+     * Set a custom configuration provider.
+     * @param {BaseConfigProvider} provider 
+     */
+    static setConfigProvider(provider) {
+        this._provider = provider;
+    }
+
+    static async getConfig(tenantId, env) {
+        return this._provider.getConfig(tenantId, env);
+    }
+}
+

package/src/llm/config-provider.js

@@ -0,0 +1,138 @@
+import { MODEL_CONFIGS } from './config-manager.js';
+
+/**
+ * Abstract base class for Config Providers.
+ */
+export class BaseConfigProvider {
+    /**
+     * Retrieve configuration for a specific tenant.
+     * @param {string} tenantId 
+     * @param {Object} env 
+     * @returns {Promise<Object>} Configuration object
+     */
+    async getConfig(tenantId, env) {
+        throw new Error('Method not implemented');
+    }
+}
+
+/**
+ * Default implementation using Cloudflare KV and Durable Objects.
+ */
+export class DefaultConfigProvider extends BaseConfigProvider {
+    async getConfig(tenantId, env) {
+        if (!tenantId) {
+            return this._getSystemConfig(env);
+        }
+
+        // Layer 1: Try KV cache first (1hr TTL)
+        const cacheKey = `tenant:${tenantId}:llm_config`;
+        const cached = await env.TENANT_LLM_CONFIG?.get(cacheKey);
+
+        if (cached !== null && cached !== undefined) {
+            // Negative cache: empty object means "no BYOK"
+            if (cached === '{}') {
+                // console.log(`[ConfigManager] KV negative cache hit for tenant ${tenantId}`);
+                return this._getSystemConfig(env);
+            }
+
+            const config = JSON.parse(cached);
+            // console.log(`[ConfigManager] KV cache hit for tenant ${tenantId}`);
+            return this._buildTenantConfig(config, env);
+        }
+
+        // Layer 2: KV miss - load from TenantDO (which loads from D1 if needed)
+        // console.log(`[ConfigManager] KV miss, loading from TenantDO for tenant ${tenantId}`);
+        const tenantConfig = await this._loadFromTenantDO(tenantId, env);
+
+        if (tenantConfig && tenantConfig.enabled && tenantConfig.api_key) {
+            // Cache the config with 1hr TTL
+            if (env.TENANT_LLM_CONFIG) {
+                await env.TENANT_LLM_CONFIG.put(
+                    cacheKey,
+                    JSON.stringify(tenantConfig),
+                    { expirationTtl: 3600 } // 1 hour
+                );
+            }
+            // console.log(`[ConfigManager] Using BYOK for tenant ${tenantId} (${tenantConfig.provider})`);
+            return this._buildTenantConfig(tenantConfig, env);
+        } else {
+            // Negative cache: user doesn't have BYOK
+            if (env.TENANT_LLM_CONFIG) {
+                await env.TENANT_LLM_CONFIG.put(
+                    cacheKey,
+                    '{}',
+                    { expirationTtl: 3600 } // 1 hour
+                );
+            }
+            // console.log(`[ConfigManager] No BYOK for tenant ${tenantId}, using system config`);
+            return this._getSystemConfig(env);
+        }
+    }
+
+    async _loadFromTenantDO(tenantId, env) {
+        try {
+            if (!env.TENANT_DO) return null;
+
+            const doId = env.TENANT_DO.idFromName(tenantId);
+            const stub = env.TENANT_DO.get(doId);
+            const response = await stub.fetch(new Request(`http://do/llm-config/${tenantId}`));
+
+            if (response.ok) {
+                const config = await response.json();
+                return config; // May be null if no config
+            }
+            return null;
+        } catch (error) {
+            console.error(`[ConfigManager] Failed to load from TenantDO for tenant ${tenantId}:`, error);
+            return null;
+        }
+    }
+
+    _buildTenantConfig(tenantConfig, env) {
+        return {
+            provider: tenantConfig.provider,
+            apiKey: tenantConfig.api_key,
+            models: MODEL_CONFIGS[tenantConfig.provider],
+            temperature: parseFloat(env.DEFAULT_TEMPERATURE || '0.7'),
+            maxTokens: parseInt(env.DEFAULT_MAX_TOKENS || '4096'),
+            capabilities: tenantConfig.capabilities || { chat: true, image: false, video: false },
+            isTenantOwned: true
+        };
+    }
+
+    _getSystemConfig(env) {
+        const provider = env.LLM_PROVIDER?.toLowerCase() || 'openai';
+        const providerDefaults = MODEL_CONFIGS[provider] || MODEL_CONFIGS['openai'];
+
+        let apiKey;
+        let models = { ...providerDefaults };
+
+        if (provider === 'openai') {
+            apiKey = env.OPENAI_API_KEY;
+            models = {
+                default: env.OPENAI_MODEL || providerDefaults.default,
+                edge: env.OPENAI_MODEL_EDGE || providerDefaults.edge,
+                fast: env.OPENAI_MODEL_FAST || providerDefaults.fast,
+                cost: env.OPENAI_MODEL_COST || providerDefaults.cost,
+                free: env.OPENAI_MODEL_FREE || providerDefaults.free,
+            };
+        } else if (provider === 'gemini') {
+            apiKey = env.GEMINI_API_KEY;
+            models = {
+                default: env.GEMINI_MODEL || providerDefaults.default,
+                edge: env.GEMINI_MODEL_EDGE || providerDefaults.edge,
+                fast: env.GEMINI_MODEL_FAST || providerDefaults.fast,
+                cost: env.GEMINI_MODEL_COST || providerDefaults.cost,
+                free: env.GEMINI_MODEL_FREE || providerDefaults.free,
+            };
+        }
+
+        return {
+            provider,
+            apiKey,
+            models,
+            temperature: parseFloat(env.DEFAULT_TEMPERATURE || '0.7'),
+            maxTokens: parseInt(env.DEFAULT_MAX_TOKENS || '4096'),
+        };
+    }
+}

package/src/llm/providers/base-provider.js

@@ -0,0 +1,48 @@
+/**
+ * Abstract base class for LLM Providers.
+ * Defines the standard interface that all providers must implement.
+ */
+export class BaseLLMProvider {
+    constructor(config) {
+        this.config = config;
+    }
+
+    /**
+     * Simple chat interface for single-turn conversations
+     * @param {string} userMessage 
+     * @param {string} systemPrompt 
+     * @param {Object} options 
+     */
+    async chat(userMessage, systemPrompt, options) {
+        throw new Error('Method not implemented');
+    }
+
+    /**
+     * Advanced chat completion with tool support
+     * @param {Array} messages 
+     * @param {string} systemPrompt 
+     * @param {Array} tools 
+     */
+    async chatCompletion(messages, systemPrompt, tools) {
+        throw new Error('Method not implemented');
+    }
+
+    /**
+     * Execute tools requested by the LLM
+     * @param {Array} toolCalls 
+     * @param {Array} messages 
+     * @param {string} tenantId 
+     * @param {Object} toolImplementations 
+     * @param {Object} env 
+     */
+    async executeTools(toolCalls, messages, tenantId, toolImplementations, env) {
+        throw new Error('Method not implemented');
+    }
+
+    /**
+     * Generate image (optional support)
+     */
+    async imageGeneration(prompt, modelName, systemPrompt, options) {
+        throw new Error('Image generation not supported by this provider');
+    }
+}

package/src/llm/providers/gemini-provider.js

@@ -0,0 +1,195 @@
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { BaseLLMProvider } from './base-provider.js';
+import { LLMServiceException } from '../../llm-service.js';
+
+export class GeminiProvider extends BaseLLMProvider {
+    constructor(config) {
+        super(config);
+        this.client = new GoogleGenerativeAI(config.apiKey);
+        this.models = config.models;
+        this.defaultModel = config.models.default;
+    }
+
+    async chat(userMessage, systemPrompt = '', options = {}) {
+        const messages = [{ role: 'user', content: userMessage }];
+        const tier = options.tier || 'default';
+        const effectiveModel = this._getModelForTier(tier);
+        const effectiveMaxTokens = options.maxTokens || this.config.maxTokens;
+        const effectiveTemperature = options.temperature !== undefined ? options.temperature : this.config.temperature;
+
+        const response = await this._chatCompletionWithModel(
+            messages,
+            systemPrompt,
+            null,
+            effectiveModel,
+            effectiveMaxTokens,
+            effectiveTemperature
+        );
+        return { text: response.content };
+    }
+
+    async chatCompletion(messages, systemPrompt, tools = null) {
+        return this._chatCompletionWithModel(
+            messages,
+            systemPrompt,
+            tools,
+            this.defaultModel,
+            this.config.maxTokens,
+            this.config.temperature
+        );
+    }
+
+    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature) {
+        const modelConfig = {
+            model: modelName,
+            systemInstruction: systemPrompt,
+            tools: tools ? [{ functionDeclarations: tools.map(t => t.function) }] : undefined,
+        };
+
+        const model = this.client.getGenerativeModel(modelConfig);
+
+        // Pre-process messages to handle the 'system' role for Gemini
+        const geminiMessages = [];
+        let systemContentBuffer = [];
+
+        for (const msg of messages) {
+            if (msg.role === 'system') {
+                systemContentBuffer.push(msg.content);
+            } else {
+                if (msg.role === 'user' && systemContentBuffer.length > 0) {
+                    const fullContent = `${systemContentBuffer.join('\n')}\n\n${msg.content}`;
+                    geminiMessages.push({ ...msg, content: fullContent });
+                    systemContentBuffer = [];
+                } else {
+                    geminiMessages.push(msg);
+                }
+            }
+        }
+
+        const history = geminiMessages.map((msg, index) => {
+            let role = '';
+            let parts;
+
+            switch (msg.role) {
+                case 'user':
+                    role = 'user';
+                    parts = [{ text: msg.content }];
+                    break;
+                case 'assistant':
+                    role = 'model';
+                    if (msg.tool_calls) {
+                        parts = msg.tool_calls.map(tc => ({
+                            functionCall: { name: tc.function.name, args: tc.function.arguments }
+                        }));
+                    } else {
+                        parts = [{ text: msg.content || '' }];
+                    }
+                    break;
+                case 'tool':
+                    role = 'function';
+                    const preceding_message = messages[index - 1];
+                    const tool_call = preceding_message?.tool_calls?.find(tc => tc.id === msg.tool_call_id);
+                    parts = [{
+                        functionResponse: {
+                            name: tool_call?.function?.name || 'unknown_tool',
+                            response: { content: msg.content },
+                        }
+                    }];
+                    break;
+                default:
+                    return null;
+            }
+            return { role, parts };
+        }).filter(Boolean);
+
+        while (history.length > 0 && history[0].role !== 'user') {
+            history.shift();
+        }
+
+        if (history.length === 0) {
+            throw new LLMServiceException('Cannot process a conversation with no user messages.', 400);
+        }
+
+        const lastMessage = history.pop();
+        const chat = model.startChat({ history });
+
+        const result = await chat.sendMessage(lastMessage.parts);
+        const response = result.response;
+        const toolCalls = response.functionCalls();
+
+        return {
+            content: response.text(),
+            tool_calls: toolCalls ? toolCalls.map(fc => ({ type: 'function', function: fc })) : null,
+        };
+    }
+
+    async executeTools(tool_calls, messages, tenantId, toolImplementations, env) {
+        const toolResults = await Promise.all(
+            tool_calls.map(async (toolCall, index) => {
+                const toolName = toolCall.function.name;
+                const tool = toolImplementations[toolName];
+                const tool_call_id = `gemini-tool-call-${index}`;
+                toolCall.id = tool_call_id;
+
+                console.log(`[Tool Call] ${toolName} with arguments:`, toolCall.function.args);
+
+                if (!tool) {
+                    console.error(`[Tool Error] Tool '${toolName}' not found`);
+                    return { tool_call_id, output: JSON.stringify({ error: `Tool '${toolName}' not found.` }) };
+                }
+                try {
+                    const output = await tool(toolCall.function.args, { env, tenantId });
+                    console.log(`[Tool Result] ${toolName} returned:`, output.substring(0, 200) + (output.length > 200 ? '...' : ''));
+                    return { tool_call_id, output };
+                } catch (error) {
+                    console.error(`[Tool Error] ${toolName} failed:`, error.message);
+                    return { tool_call_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 }));
+    }
+
+    async imageGeneration(prompt, modelName, systemPrompt, options = {}) {
+        const model = this.client.getGenerativeModel({
+            model: modelName,
+            systemInstruction: systemPrompt,
+        });
+
+        const generationConfig = {
+            responseModalities: ["IMAGE"],
+        };
+
+        if (options.aspectRatio) {
+            generationConfig.imageConfig = {
+                aspectRatio: options.aspectRatio
+            };
+        }
+
+        const result = await model.generateContent({
+            contents: [{
+                role: "user",
+                parts: [{ text: prompt }]
+            }],
+            generationConfig
+        });
+
+        const response = result.response;
+        const imagePart = response.candidates?.[0]?.content?.parts?.find(
+            part => part.inlineData && part.inlineData.mimeType?.startsWith('image/')
+        );
+
+        if (!imagePart || !imagePart.inlineData) {
+            throw new Error('No image data in response');
+        }
+
+        return {
+            imageData: imagePart.inlineData.data,
+            mimeType: imagePart.inlineData.mimeType,
+        };
+    }
+
+    _getModelForTier(tier) {
+        return this.models[tier] || this.models.default;
+    }
+}

package/src/llm/providers/openai-provider.js

@@ -0,0 +1,88 @@
+import OpenAI from 'openai';
+import { BaseLLMProvider } from './base-provider.js';
+
+export class OpenAIProvider extends BaseLLMProvider {
+    constructor(config) {
+        super(config);
+        this.client = new OpenAI({ apiKey: config.apiKey });
+        this.models = config.models;
+        this.defaultModel = config.models.default;
+    }
+
+    async chat(userMessage, systemPrompt = '', options = {}) {
+        const messages = [{ role: 'user', content: userMessage }];
+        const tier = options.tier || 'default';
+        const effectiveModel = this._getModelForTier(tier);
+        const effectiveMaxTokens = options.maxTokens || this.config.maxTokens;
+        const effectiveTemperature = options.temperature !== undefined ? options.temperature : this.config.temperature;
+
+        const response = await this._chatCompletionWithModel(
+            messages,
+            systemPrompt,
+            null,
+            effectiveModel,
+            effectiveMaxTokens,
+            effectiveTemperature
+        );
+        return { text: response.content };
+    }
+
+    async chatCompletion(messages, systemPrompt, tools = null) {
+        return this._chatCompletionWithModel(
+            messages,
+            systemPrompt,
+            tools,
+            this.defaultModel,
+            this.config.maxTokens,
+            this.config.temperature
+        );
+    }
+
+    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature) {
+        const requestPayload = {
+            model: modelName,
+            temperature: temperature,
+            max_tokens: maxTokens,
+            messages: [{ role: 'system', content: systemPrompt }, ...messages],
+            tools: tools,
+            tool_choice: tools ? 'auto' : undefined,
+        };
+
+        const response = await this.client.chat.completions.create(requestPayload);
+        const message = response.choices[0].message;
+
+        return {
+            content: message.content,
+            tool_calls: message.tool_calls,
+        };
+    }
+
+    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 });
+                    console.log(`[Tool Result] ${toolName} returned:`, output.substring(0, 200) + (output.length > 200 ? '...' : ''));
+                    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.models.default;
+    }
+}

package/src/llm-service.js

@@ -0,0 +1,139 @@
+import { ConfigManager } from './llm/config-manager.js';
+import { OpenAIProvider } from './llm/providers/openai-provider.js';
+import { GeminiProvider } from './llm/providers/gemini-provider.js';
+
+/**
+ * LLM Service Module
+ * 
+ * This module provides a unified interface for interacting with different LLM providers.
+ * It now supports BYOK (Bring Your Own Key) via Tenant Configuration.
+ */
+export class LLMService {
+    constructor(env, toolImplementations = {}) {
+        this.env = env;
+        this.toolImplementations = toolImplementations;
+        // Cache for provider instances to avoid recreation within the same request if possible
+        this.providerCache = new Map();
+    }
+
+    async _getProvider(tenantId) {
+        // Check cache first
+        const cacheKey = tenantId || 'system';
+        if (this.providerCache.has(cacheKey)) {
+            return this.providerCache.get(cacheKey);
+        }
+
+        const config = await ConfigManager.getConfig(tenantId, this.env);
+
+        if (!config.apiKey) {
+            throw new LLMServiceException(`LLM service is not configured for ${config.provider}. Missing API Key.`, 500);
+        }
+
+        let provider;
+        if (config.provider === 'openai') {
+            provider = new OpenAIProvider(config);
+        } else if (config.provider === 'gemini') {
+            provider = new GeminiProvider(config);
+        } else {
+            throw new LLMServiceException(`Unsupported LLM provider: ${config.provider}`, 500);
+        }
+
+        this.providerCache.set(cacheKey, provider);
+        return provider;
+    }
+
+    /**
+     * Check if LLM service is configured for a tenant (or system default)
+     */
+    async isConfigured(tenantId) {
+        const config = await ConfigManager.getConfig(tenantId, this.env);
+        return !!config.apiKey;
+    }
+
+    /**
+     * Simple chat interface for single-turn conversations
+     */
+    async chat(userMessage, tenantId, systemPrompt = '', options = {}) {
+        const provider = await this._getProvider(tenantId);
+        return provider.chat(userMessage, systemPrompt, options);
+    }
+
+    /**
+     * Interact with LLM for generation
+     */
+    async chatCompletion(messages, tenantId, systemPrompt, tools = null) {
+        const provider = await this._getProvider(tenantId);
+
+        if (!systemPrompt?.trim()) {
+            throw new LLMServiceException('No prompt set for bot', 503);
+        }
+
+        return provider.chatCompletion(messages, systemPrompt, tools);
+    }
+
+    /**
+     * Wrap of chatCompletion to handle toolcalls from LLM.
+     */
+    async chatWithTools(messages, tenantId, systemPrompt, tools = []) {
+        const provider = await this._getProvider(tenantId);
+
+        let currentMessages = [...messages];
+
+        // Initial call
+        const initialResponse = await provider.chatCompletion(
+            currentMessages,
+            systemPrompt,
+            tools
+        );
+
+        let { content, tool_calls } = initialResponse;
+
+        // Tool execution loop
+        while (tool_calls) {
+            console.log('[Tool Call] Assistant wants to use tools:', tool_calls);
+            currentMessages.push({ role: 'assistant', content: content || '', tool_calls });
+
+            // Execute tools using the provider's helper (which formats results for that provider)
+            await provider.executeTools(tool_calls, currentMessages, tenantId, this.toolImplementations, this.env);
+
+            // Next call
+            const nextResponse = await provider.chatCompletion(
+                currentMessages,
+                systemPrompt,
+                tools
+            );
+
+            content = nextResponse.content;
+            tool_calls = nextResponse.tool_calls;
+        }
+
+        return { content };
+    }
+
+    /**
+     * Generate an image
+     * Falls back to system keys if tenant doesn't have image capability enabled
+     */
+    async imageGeneration(prompt, tenantId, modelName, systemPrompt, options = {}) {
+        // Check if tenant has image capability enabled
+        if (tenantId) {
+            const config = await ConfigManager.getConfig(tenantId, this.env);
+            if (config.isTenantOwned && !config.capabilities?.image) {
+                console.log(`[LLMService] Tenant ${tenantId} BYOK doesn't have image capability. Using system keys.`);
+                tenantId = null; // Fall back to system
+            }
+        }
+
+        const provider = await this._getProvider(tenantId);
+        return provider.imageGeneration(prompt, modelName, systemPrompt, options);
+    }
+}
+
+export class LLMServiceException extends Error {
+    constructor(message, statusCode = 500, details = null) {
+        super(message);
+        this.name = 'LLMServiceException';
+        this.statusCode = statusCode;
+        this.details = details || {};
+    }
+}