@contentgrowth/llm-service 0.8.0 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentgrowth/llm-service",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "Unified LLM Service for Content Growth",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -6,4 +6,4 @@ export { OpenAIProvider } from './llm/providers/openai-provider.js';
 export { GeminiProvider } from './llm/providers/gemini-provider.js';
 export { extractJsonFromResponse, extractTextAndJson } from './llm/json-utils.js';
 export { FINISH_REASONS } from './llm/providers/base-provider.js';
-
+export { handleApiError, sanitizeError } from './utils/error-handler.js';

package/src/llm/config-manager.js

@@ -22,9 +22,11 @@ export const MODEL_CONFIGS = {
         cost: 'gemini-3-flash-preview', // 'gemini-2.5-flash-lite',
         free: 'gemini-3-flash-preview', // 'gemini-2.0-flash-lite',
         video: 'veo',
+        image: 'gemini-3-pro-image-preview', // Default image generation model
     },
 };
 
+
 export class ConfigManager {
     static _provider = new DefaultConfigProvider();
 

package/src/llm/config-provider.js

@@ -124,6 +124,8 @@ export class DefaultConfigProvider extends BaseConfigProvider {
                 fast: env.GEMINI_MODEL_FAST || providerDefaults.fast,
                 cost: env.GEMINI_MODEL_COST || providerDefaults.cost,
                 free: env.GEMINI_MODEL_FREE || providerDefaults.free,
+                image: env.GEMINI_IMAGE_MODEL || providerDefaults.image,
+                video: env.GEMINI_VIDEO_MODEL || providerDefaults.video,
             };
         }
 

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

@@ -86,12 +86,19 @@ export class BaseLLMProvider {
     }
 
     /**
-     * Generate image (optional support)
+     * Generate image
+     * Subclasses should override this method.
+     * Model can be overridden via options.model, otherwise uses config.models.image
+     * @param {string} prompt - Text description of the image
+     * @param {string} systemPrompt - System instructions for generation
+     * @param {Object} options - Generation options (aspectRatio, images, model, etc.)
+     * @returns {Promise<{imageData: string, mimeType: string}>}
      */
-    async imageGeneration(prompt, modelName, systemPrompt, options) {
+    async imageGeneration(prompt, systemPrompt, options = {}) {
         throw new Error('Image generation not supported by this provider');
     }
 
+
     /**
      * Start video generation (returns operation name for polling)
      * @param {string} prompt

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

@@ -113,18 +113,32 @@ export class GeminiProvider extends BaseLLMProvider {
                     break;
                 case 'assistant':
                     role = 'model';
+
+                    // Find if this is the LAST assistant message in the conversation
+                    // Only the last assistant message should carry the thought_signature to avoid token bloat
+                    const isLastAssistantMessage = index === geminiMessages.map((m, i) => m.role === 'assistant' ? i : -1).filter(i => i >= 0).pop();
+
                     if (msg.tool_calls) {
                         parts = msg.tool_calls.map(tc => {
                             const part = {
                                 functionCall: { name: tc.function.name, args: tc.function.arguments || tc.function.args }
                             };
-                            if (tc.thought_signature) {
-                                part.thought_signature = tc.thought_signature;
+                            // Only attach signature for the last assistant message
+                            if (isLastAssistantMessage && tc.thought_signature) {
+                                console.log(`[GeminiProvider] Sending thought_signature in tool_call (${tc.thought_signature.length} chars)`);
+                                part.thoughtSignature = tc.thought_signature; // camelCase for SDK
                             }
                             return part;
                         });
                     } else {
-                        parts = [{ text: msg.content || '' }];
+                        // Handle text content with optional thought signature
+                        const part = { text: msg.content || '' };
+                        // Only attach signature for the last assistant message
+                        if (isLastAssistantMessage && msg.thought_signature) {
+                            console.log(`[GeminiProvider] Sending thought_signature in text message (${msg.thought_signature.length} chars)`);
+                            part.thoughtSignature = msg.thought_signature;
+                        }
+                        parts = [part];
                     }
                     break;
                 case 'tool':
@@ -207,22 +221,35 @@ export class GeminiProvider extends BaseLLMProvider {
 
         const parts = candidate.content?.parts || [];
 
-        // Extract text and function calls
+        // Extract text, function calls, and thought signatures
         let textContent = '';
         let toolCalls = null;
+        let responseThoughtSignature = null;
 
         for (const part of parts) {
             if (part.text) {
                 textContent += part.text;
+                // Capture thought signature attached to text part if present
+                if (part.thought_signature || part.thoughtSignature) {
+                    responseThoughtSignature = part.thought_signature || part.thoughtSignature;
+                }
             }
             if (part.functionCall) {
                 if (!toolCalls) toolCalls = [];
                 // Preserve thought_signature if present (Gemini 3 requirement)
-                if (part.thought_signature) {
-                    part.functionCall.thought_signature = part.thought_signature;
+                // Check both snake_case (API) and camelCase (SDK convention)
+                const sig = part.thought_signature || part.thoughtSignature;
+                if (sig) {
+                    part.functionCall.thought_signature = sig;
+                    // Also capture as top-level if not already set (though tool calls might have their own)
+                    if (!responseThoughtSignature) responseThoughtSignature = sig;
                 }
                 toolCalls.push(part.functionCall);
             }
+            // Fallback for standalone thought signature parts if they exist (hypothetical)
+            if (!part.text && !part.functionCall && (part.thought_signature || part.thoughtSignature)) {
+                responseThoughtSignature = part.thought_signature || part.thoughtSignature;
+            }
         }
 
         // Validate that we have EITHER content OR tool calls
@@ -238,6 +265,9 @@ export class GeminiProvider extends BaseLLMProvider {
             );
         }
 
+        // Detailed logging as requested
+        // console.log('[GeminiProvider] generateContent response candidate:', JSON.stringify(candidate, null, 2));
+
         // console.log('Gemini returns:', textContent);
         // Return with parsed JSON if applicable
         // Normalize the finish reason to standard value for consistent handling
@@ -245,6 +275,7 @@ export class GeminiProvider extends BaseLLMProvider {
 
         return {
             content: textContent,
+            thought_signature: responseThoughtSignature, // Return signature to caller
             tool_calls: toolCalls ? (Array.isArray(toolCalls) ? toolCalls : [toolCalls]).map(fc => ({
                 type: 'function',
                 function: fc,
@@ -390,7 +421,11 @@ export class GeminiProvider extends BaseLLMProvider {
         toolResults.forEach(result => messages.push({ role: 'tool', tool_call_id: result.tool_call_id, content: result.output }));
     }
 
-    async imageGeneration(prompt, modelName, systemPrompt, options = {}) {
+    async imageGeneration(prompt, systemPrompt, options = {}) {
+        // Allow model override via options.model, otherwise use default from config
+        const modelName = options.model || this.models.image || 'gemini-3-pro-image-preview';
+        console.log(`[GeminiProvider] Generating image with model: ${modelName}`);
+
         const generationConfig = {
             responseModalities: ["IMAGE"],
         };
@@ -454,9 +489,29 @@ export class GeminiProvider extends BaseLLMProvider {
             throw new Error(`No image data in response. Finish Reason: ${candidate?.finishReason}`);
         }
 
+        // Check for thought signature in the image part or any other part
+        let thoughtSignature = null;
+        if (imagePart.thought_signature || imagePart.thoughtSignature) {
+            thoughtSignature = imagePart.thought_signature || imagePart.thoughtSignature;
+        } else {
+            // Check other parts for standalone thought signature
+            const signaturePart = response.candidates?.[0]?.content?.parts?.find(p => p.thought_signature || p.thoughtSignature);
+            if (signaturePart) {
+                thoughtSignature = signaturePart.thought_signature || signaturePart.thoughtSignature;
+            }
+        }
+
+        // Safety: If thought signature is abnormally large (>50KB), replace with bypass token
+        // to prevent massive context usage (User reported 1.5MB signatures in some cases).
+        if (thoughtSignature && thoughtSignature.length > 50000) {
+            console.warn(`[GeminiProvider] ⚠️  Thought signature is abnormally large (${thoughtSignature.length} chars). Replacing with bypass token to save context.`);
+            thoughtSignature = "skip_thought_signature_validator";
+        }
+
         return {
             imageData: imagePart.inlineData.data,
             mimeType: imagePart.inlineData.mimeType,
+            thought_signature: thoughtSignature
         };
     }
 

package/src/llm-service.js

@@ -251,8 +251,12 @@ export class LLMService {
     /**
      * Generate an image
      * Falls back to system keys if tenant doesn't have image capability enabled
+     * @param {string} prompt - Text description of the image
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions for generation
+     * @param {Object} options - Generation options (aspectRatio, images, etc.)
      */
-    async imageGeneration(prompt, tenantId, modelName, systemPrompt, options = {}) {
+    async imageGeneration(prompt, tenantId, systemPrompt, options = {}) {
         // Check if tenant has image capability enabled
         if (tenantId) {
             const config = await ConfigManager.getConfig(tenantId, this.env);
@@ -263,7 +267,7 @@ export class LLMService {
         }
 
         const provider = await this._getProvider(tenantId);
-        return provider.imageGeneration(prompt, modelName, systemPrompt, options);
+        return provider.imageGeneration(prompt, systemPrompt, options);
     }
 }
 

package/src/utils/error-handler.js

@@ -0,0 +1,117 @@
+/**
+ * Error Handling Utility for LLM Service
+ * Provides centralized error parsing and user-friendly message generation.
+ * Returns plain objects - framework-specific response handling is done by consumers.
+ */
+
+/**
+ * Parse an error and return a standardized error response object.
+ * Detects specific error types like service overload, rate limits, and input issues.
+ * 
+ * @param {Error} error - The caught error
+ * @param {string} operation - The operation being performed (e.g., 'generate image', 'edit article')
+ * @param {string} context - Context for logging (e.g., 'image_generation', 'ai_edit')
+ * @returns {{ message: string, error: string, retryable: boolean, statusCode: number }}
+ */
+export function handleApiError(error, operation = 'complete this operation', context = 'api') {
+  console.error(`[${context}] Error:`, error);
+
+  const errorMessage = error.message?.toLowerCase() || '';
+  const errorString = JSON.stringify(error).toLowerCase();
+
+  // Check for model overload (503)
+  if (errorMessage.includes('overloaded') || errorMessage.includes('503') ||
+    errorString.includes('unavailable') || errorString.includes('overloaded')) {
+    return {
+      message: 'AI service is busy. Please try again.',
+      error: 'service_overloaded',
+      retryable: true,
+      statusCode: 503
+    };
+  }
+
+  // Check for rate limiting (429)
+  if (errorMessage.includes('quota') || errorMessage.includes('429') ||
+    errorMessage.includes('too many requests') || errorMessage.includes('rate limit') ||
+    errorString.includes('resource_exhausted')) {
+    return {
+      message: 'Too many requests. Please try again later.',
+      error: 'rate_limited',
+      retryable: true,
+      statusCode: 429
+    };
+  }
+
+  // Check for context length / input too long
+  if (errorMessage.includes('context length') || errorMessage.includes('too long') ||
+    errorString.includes('invalid_argument')) {
+    return {
+      message: 'Content too big. Try making focused edits.',
+      error: 'input_too_long',
+      retryable: false,
+      statusCode: 422
+    };
+  }
+
+  // Check for user quota exceeded (from our own quota system)
+  if (errorMessage.includes('quotaerror') || errorMessage.includes('quota_exceeded')) {
+    return {
+      message: 'You have reached your usage limit for this month. Please upgrade your plan to continue.',
+      error: 'user_quota_exceeded',
+      retryable: false,
+      statusCode: 402
+    };
+  }
+
+  // Check for trial limitation errors
+  if (errorMessage.includes('trial')) {
+    return {
+      message: 'This feature is not available during the free trial. Please upgrade to use this feature.',
+      error: 'trial_limitation',
+      retryable: false,
+      statusCode: 402
+    };
+  }
+
+  // Check for authentication/configuration errors
+  if (errorMessage.includes('api key') || errorMessage.includes('authentication') || errorMessage.includes('unauthorized')) {
+    return {
+      message: 'Service is not available at this time. Please contact support.',
+      error: 'not_configured',
+      retryable: false,
+      statusCode: 503
+    };
+  }
+
+  // Check for invalid input errors
+  if (errorMessage.includes('invalid') || errorMessage.includes('bad request')) {
+    return {
+      message: 'Invalid request. Please check your input and try again.',
+      error: 'invalid_input',
+      retryable: false,
+      statusCode: 400
+    };
+  }
+
+  // Default error
+  return {
+    message: `An error occurred while trying to ${operation}. Please try again.`,
+    error: 'operation_failed',
+    retryable: true,
+    statusCode: 500
+  };
+}
+
+/**
+ * Sanitize error messages to prevent leaking technical details.
+ * Returns an Error with a clean error code that can be handled by the API layer.
+ * Use this when you want to throw an error rather than return a JSON response.
+ * 
+ * @param {Error} error - The original error
+ * @param {string} context - Context of where error occurred (e.g., 'image_generation', 'ai_edit')
+ * @returns {Error} - Sanitized error with clean message code
+ */
+export function sanitizeError(error, context = 'general') {
+  const result = handleApiError(error, 'complete this operation', context);
+  return new Error(result.error);
+}