@contentgrowth/llm-service 0.3.0 → 0.5.0

package/README.md

@@ -81,6 +81,126 @@ ConfigManager.setConfigProvider(new MyDatabaseConfigProvider());
 const service = new LLMService(env);
 ```
 
+### JSON Mode & Structured Outputs
+
+The service supports native JSON mode for OpenAI and Gemini, guaranteeing valid JSON responses without escaping issues.
+
+#### Basic JSON Mode
+
+```javascript
+const response = await llmService.chatCompletion(
+  messages,
+  tenantId,
+  'You are a helpful assistant. Always respond in JSON.',
+  { responseFormat: 'json' }  // ← Enable JSON mode
+);
+
+// Response includes auto-parsed JSON
+console.log(response.parsedContent); // Already parsed object
+console.log(response.content);       // Raw JSON string
+```
+
+#### JSON Mode with Schema Validation (Structured Outputs)
+
+Define a schema to guarantee the response structure:
+
+```javascript
+const schema = {
+  type: 'object',
+  properties: {
+    answer: { type: 'string' },
+    confidence: { type: 'number' },
+    sources: { 
+      type: 'array', 
+      items: { type: 'string' },
+      nullable: true 
+    }
+  },
+  required: ['answer', 'confidence']
+};
+
+const response = await llmService.chatCompletion(
+  messages,
+  tenantId,
+  systemPrompt,
+  {
+    responseFormat: 'json_schema',
+    responseSchema: schema,
+    schemaName: 'question_answer'
+  }
+);
+
+// Guaranteed to match schema
+const { answer, confidence, sources } = response.parsedContent;
+```
+
+#### Convenience Method
+
+For JSON-only responses, use `chatCompletionJson()` to get parsed objects directly:
+
+```javascript
+// Returns parsed object directly (not response wrapper)
+const data = await llmService.chatCompletionJson(
+  messages,
+  tenantId,
+  systemPrompt,
+  schema  // optional
+);
+
+console.log(data.answer);      // Direct access to fields
+console.log(data.confidence);  // No .parsedContent needed
+```
+
+#### Flexible Call Signatures
+
+The `chatCompletion()` method intelligently detects whether you're passing tools, options, or both:
+
+```javascript
+// All these work!
+await chatCompletion(messages, tenant, prompt);
+await chatCompletion(messages, tenant, prompt, tools);
+await chatCompletion(messages, tenant, prompt, { responseFormat: 'json' });
+await chatCompletion(messages, tenant, prompt, tools, { responseFormat: 'json' });
+```
+
+#### Supported Options
+
+- `responseFormat`: `'text'` (default), `'json'`, or `'json_schema'`
+- `responseSchema`: JSON schema object (required for `json_schema` mode)
+- `schemaName`: Name for the schema (optional, for `json_schema` mode)
+- `strictSchema`: Enforce strict validation (default: `true`)
+- `autoParse`: Auto-parse JSON responses (default: `true`)
+- `temperature`: Override temperature
+- `maxTokens`: Override max tokens
+- `tier`: Model tier (`'default'`, `'fast'`, `'smart'`)
+
+
+## Testing
+
+### Running JSON Mode Tests
+
+1. **Create `.env` file** (copy from `.env.example`):
+   ```bash
+   cp .env.example .env
+   ```
+
+2. **Add your API keys** to `.env`:
+   ```ini
+   LLM_PROVIDER=openai  # or gemini
+   OPENAI_API_KEY=sk-your-key-here
+   GEMINI_API_KEY=your-gemini-key-here
+   ```
+
+3. **Run tests**:
+   ```bash
+   npm run test:json      # Run comprehensive test suite
+   npm run examples:json  # Run interactive examples
+   ```
+
+See [TESTING.md](./TESTING.md) for detailed testing documentation.
+
+
+
 ## Publishing
 
 To publish this package to NPM:

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@contentgrowth/llm-service",
-  "version": "0.3.0",
+  "version": "0.5.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"
+    "test:live": "node test-live.js",
+    "test:json": "node test-json-mode.js",
+    "examples:json": "node examples-json-mode.js",
+    "prepublishOnly": "echo '\n📦 Package contents:\n' && npm pack --dry-run && echo '\n⚠️  Review the files above before publishing!\n'"
   },
   "author": "Content Growth",
   "license": "MIT",

package/src/llm/config-manager.js

@@ -21,6 +21,7 @@ export const MODEL_CONFIGS = {
         fast: 'gemini-2.5-flash-lite',
         cost: 'gemini-2.5-flash-lite',
         free: 'gemini-2.0-flash-lite',
+        video: 'veo',
     },
 };
 

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

@@ -22,8 +22,9 @@ export class BaseLLMProvider {
      * @param {Array} messages 
      * @param {string} systemPrompt 
      * @param {Array} tools 
+     * @param {Object} options - Generation options (responseFormat, temperature, etc.)
      */
-    async chatCompletion(messages, systemPrompt, tools) {
+    async chatCompletion(messages, systemPrompt, tools, options = {}) {
         throw new Error('Method not implemented');
     }
 

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

@@ -28,24 +28,36 @@ export class GeminiProvider extends BaseLLMProvider {
         return { text: response.content };
     }
 
-    async chatCompletion(messages, systemPrompt, tools = null) {
+    async chatCompletion(messages, systemPrompt, tools = null, options = {}) {
         return this._chatCompletionWithModel(
             messages,
             systemPrompt,
             tools,
             this.defaultModel,
             this.config.maxTokens,
-            this.config.temperature
+            this.config.temperature,
+            options
         );
     }
 
-    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature) {
+    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature, options = {}) {
         const modelConfig = {
             model: modelName,
             systemInstruction: systemPrompt,
             tools: tools ? [{ functionDeclarations: tools.map(t => t.function) }] : undefined,
         };
 
+        // Add JSON mode support for Gemini
+        if (options.responseFormat) {
+            modelConfig.generationConfig = this._buildGenerationConfig(options, maxTokens, temperature);
+        } else if (options.temperature !== undefined || options.maxTokens !== undefined) {
+            // Apply temperature/maxTokens overrides even without JSON mode
+            modelConfig.generationConfig = {
+                temperature: options.temperature ?? temperature,
+                maxOutputTokens: options.maxTokens ?? maxTokens,
+            };
+        }
+
         const model = this.client.getGenerativeModel(modelConfig);
 
         // Pre-process messages to handle the 'system' role for Gemini
@@ -117,12 +129,108 @@ export class GeminiProvider extends BaseLLMProvider {
         const response = result.response;
         const toolCalls = response.functionCalls();
 
+        // Return with parsed JSON if applicable
         return {
             content: response.text(),
             tool_calls: toolCalls ? toolCalls.map(fc => ({ type: 'function', function: fc })) : null,
+            _responseFormat: options.responseFormat,
+            ...(options.responseFormat && this._shouldAutoParse(options) ? {
+                parsedContent: this._safeJsonParse(response.text())
+            } : {})
         };
     }
 
+    _buildGenerationConfig(options, maxTokens, temperature) {
+        const config = {
+            temperature: options.temperature ?? temperature,
+            maxOutputTokens: options.maxTokens ?? maxTokens,
+        };
+
+        switch (options.responseFormat) {
+            case 'json':
+            case 'json_schema':
+                config.responseMimeType = 'application/json';
+
+                if (options.responseSchema) {
+                    config.responseSchema = this._convertToGeminiSchema(options.responseSchema);
+                }
+                break;
+        }
+
+        return config;
+    }
+
+    _convertToGeminiSchema(jsonSchema) {
+        // SchemaType constants for Gemini schema conversion
+        const SchemaType = {
+            STRING: 'STRING',
+            NUMBER: 'NUMBER',
+            INTEGER: 'INTEGER',
+            BOOLEAN: 'BOOLEAN',
+            ARRAY: 'ARRAY',
+            OBJECT: 'OBJECT'
+        };
+
+        const convertType = (type) => {
+            switch (type) {
+                case 'string': return SchemaType.STRING;
+                case 'number': return SchemaType.NUMBER;
+                case 'integer': return SchemaType.INTEGER;
+                case 'boolean': return SchemaType.BOOLEAN;
+                case 'array': return SchemaType.ARRAY;
+                case 'object': return SchemaType.OBJECT;
+                default: return SchemaType.STRING;
+            }
+        };
+
+        const convert = (schema) => {
+            const result = {
+                type: convertType(schema.type),
+            };
+
+            if (schema.properties) {
+                result.properties = {};
+                for (const [key, value] of Object.entries(schema.properties)) {
+                    result.properties[key] = convert(value);
+                }
+            }
+
+            if (schema.items) {
+                result.items = convert(schema.items);
+            }
+
+            if (schema.required) {
+                result.required = schema.required;
+            }
+
+            if (schema.nullable) {
+                result.nullable = schema.nullable;
+            }
+
+            if (schema.description) {
+                result.description = schema.description;
+            }
+
+            return result;
+        };
+
+        return convert(jsonSchema);
+    }
+
+    _shouldAutoParse(options) {
+        return options.autoParse !== false; // Default true
+    }
+
+    _safeJsonParse(content) {
+        if (!content) return null;
+        try {
+            return JSON.parse(content);
+        } catch (e) {
+            console.warn('[GeminiProvider] Failed to auto-parse JSON response:', e.message);
+            return null;
+        }
+    }
+
     async executeTools(tool_calls, messages, tenantId, toolImplementations, env) {
         const toolResults = await Promise.all(
             tool_calls.map(async (toolCall, index) => {
@@ -192,4 +300,48 @@ export class GeminiProvider extends BaseLLMProvider {
     _getModelForTier(tier) {
         return this.models[tier] || this.models.default;
     }
+
+    async videoGeneration(prompt, images, modelName, systemPrompt, options = {}) {
+        const model = this.client.getGenerativeModel({
+            model: modelName,
+            systemInstruction: systemPrompt,
+        });
+
+        // Prepare image parts
+        const imageParts = images.map(img => ({
+            inlineData: {
+                data: img.data, // Base64 string
+                mimeType: img.mimeType
+            }
+        }));
+
+        const result = await model.generateContent({
+            contents: [{
+                role: "user",
+                parts: [
+                    { text: prompt },
+                    ...imageParts
+                ]
+            }]
+        });
+
+        const response = result.response;
+
+        // Check for video attachment/URI in the response
+        // This structure depends on the specific API response for Veo
+        // Assuming it might return a file URI or a specific part type
+
+        // Fallback: Return text if no specific video part is found, 
+        // but try to find a URI in the text if possible.
+        const text = response.text();
+
+        // TODO: Update this once Veo API response structure is fully documented/available
+        // For now, we return the text which might contain the URI or status.
+
+        return {
+            content: text,
+            // potential video URI extraction
+            videoUri: text.match(/https?:\/\/[^\s]+/) ? text.match(/https?:\/\/[^\s]+/)[0] : null
+        };
+    }
 }

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

@@ -27,36 +27,86 @@ export class OpenAIProvider extends BaseLLMProvider {
         return { text: response.content };
     }
 
-    async chatCompletion(messages, systemPrompt, tools = null) {
+    async chatCompletion(messages, systemPrompt, tools = null, options = {}) {
         return this._chatCompletionWithModel(
             messages,
             systemPrompt,
             tools,
             this.defaultModel,
             this.config.maxTokens,
-            this.config.temperature
+            this.config.temperature,
+            options
         );
     }
 
-    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature) {
+    async _chatCompletionWithModel(messages, systemPrompt, tools, modelName, maxTokens, temperature, options = {}) {
         const requestPayload = {
             model: modelName,
-            temperature: temperature,
-            max_tokens: maxTokens,
+            temperature: options.temperature ?? temperature,
+            max_tokens: options.maxTokens ?? maxTokens,
             messages: [{ role: 'system', content: systemPrompt }, ...messages],
             tools: tools,
             tool_choice: tools ? 'auto' : undefined,
         };
 
+        // Add JSON mode support if requested
+        if (options.responseFormat) {
+            requestPayload.response_format = this._buildResponseFormat(options);
+        }
+
         const response = await this.client.chat.completions.create(requestPayload);
         const message = response.choices[0].message;
 
+        // Return with parsed JSON if applicable
         return {
             content: message.content,
             tool_calls: message.tool_calls,
+            // Add metadata about response format
+            _responseFormat: options.responseFormat,
+            // Auto-parse JSON if requested
+            ...(options.responseFormat && this._shouldAutoParse(options) ? {
+                parsedContent: this._safeJsonParse(message.content)
+            } : {})
         };
     }
 
+    _buildResponseFormat(options) {
+        switch (options.responseFormat) {
+            case 'json':
+                return { type: 'json_object' };
+
+            case 'json_schema':
+                if (!options.responseSchema) {
+                    throw new Error('responseSchema required when using json_schema format');
+                }
+                return {
+                    type: 'json_schema',
+                    json_schema: {
+                        name: options.schemaName || 'response_schema',
+                        strict: options.strictSchema ?? true,
+                        schema: options.responseSchema
+                    }
+                };
+
+            default:
+                return undefined;
+        }
+    }
+
+    _shouldAutoParse(options) {
+        return options.autoParse !== false; // Default true
+    }
+
+    _safeJsonParse(content) {
+        if (!content) return null;
+        try {
+            return JSON.parse(content);
+        } catch (e) {
+            console.warn('[OpenAIProvider] Failed to auto-parse JSON response:', e.message);
+            return null;
+        }
+    }
+
     async executeTools(tool_calls, messages, tenantId, toolImplementations, env) {
         const toolResults = await Promise.all(
             tool_calls.map(async (toolCall) => {
@@ -85,4 +135,8 @@ export class OpenAIProvider extends BaseLLMProvider {
     _getModelForTier(tier) {
         return this.models[tier] || this.models.default;
     }
+
+    async videoGeneration(prompt, images, modelName, systemPrompt, options = {}) {
+        throw new Error('Video generation is not supported by OpenAI provider yet.');
+    }
 }

package/src/llm-service.js

@@ -60,33 +60,129 @@ export class LLMService {
 
     /**
      * Interact with LLM for generation
+     * 
+     * Intelligent signature detection supports:
+     * - chatCompletion(messages, tenantId, systemPrompt)
+     * - chatCompletion(messages, tenantId, systemPrompt, tools)
+     * - chatCompletion(messages, tenantId, systemPrompt, options)
+     * - chatCompletion(messages, tenantId, systemPrompt, tools, options)
+     * 
+     * @param {Array} messages - Conversation messages
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions
+     * @param {Array|Object} toolsOrOptions - Tools array or options object
+     * @param {Object} optionsParam - Options object (if tools provided)
+     * @returns {Object} Response with content, tool_calls, and optionally parsedContent
      */
-    async chatCompletion(messages, tenantId, systemPrompt, tools = null) {
+    async chatCompletion(messages, tenantId, systemPrompt, toolsOrOptions = null, optionsParam = {}) {
         const provider = await this._getProvider(tenantId);
 
         if (!systemPrompt?.trim()) {
             throw new LLMServiceException('No prompt set for bot', 503);
         }
 
-        return provider.chatCompletion(messages, systemPrompt, tools);
+        // Intelligent parameter detection
+        const { tools, options } = this._parseToolsAndOptions(toolsOrOptions, optionsParam);
+
+        return provider.chatCompletion(messages, systemPrompt, tools, options);
+    }
+
+    /**
+     * Helper to intelligently detect tools vs options parameters
+     * @private
+     */
+    _parseToolsAndOptions(param1, param2) {
+        // If param1 is null/undefined, use defaults
+        if (param1 === null || param1 === undefined) {
+            return { tools: null, options: param2 || {} };
+        }
+
+        // If param1 is an array, it's tools
+        if (Array.isArray(param1)) {
+            return { tools: param1, options: param2 || {} };
+        }
+
+        // If param1 is an object, check if it looks like options or tools
+        if (typeof param1 === 'object') {
+            // Check for known options keys
+            const optionsKeys = ['responseFormat', 'responseSchema', 'temperature', 'maxTokens', 'tier', 'autoParse', 'strictSchema', 'schemaName'];
+            const hasOptionsKeys = optionsKeys.some(key => key in param1);
+
+            if (hasOptionsKeys) {
+                // param1 is options
+                return { tools: null, options: param1 };
+            }
+
+            // Could be tools in object format (legacy support)
+            // Treat as tools if it doesn't have options keys
+            return { tools: param1, options: param2 || {} };
+        }
+
+        // Default: treat as tools
+        return { tools: param1, options: param2 || {} };
+    }
+
+    /**
+     * Convenience method for JSON-only responses
+     * Automatically enables JSON mode and returns parsed object
+     * 
+     * @param {Array} messages - Conversation messages
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions
+     * @param {Object} schema - Optional JSON schema for validation
+     * @param {Array} tools - Optional tools array
+     * @returns {Object} Parsed JSON object
+     * @throws {LLMServiceException} If JSON parsing fails
+     */
+    async chatCompletionJson(messages, tenantId, systemPrompt, schema = null, tools = null) {
+        const options = {
+            responseFormat: schema ? 'json_schema' : 'json',
+            responseSchema: schema,
+            autoParse: true
+        };
+
+        const response = await this.chatCompletion(messages, tenantId, systemPrompt, tools, options);
+
+        // Return parsed content directly or throw if parsing failed
+        if (response.parsedContent !== null && response.parsedContent !== undefined) {
+            return response.parsedContent;
+        }
+
+        // Fallback: try to parse the raw content
+        try {
+            return JSON.parse(response.content);
+        } catch (e) {
+            throw new LLMServiceException(
+                'LLM returned invalid JSON despite JSON mode being enabled',
+                500,
+                { rawContent: response.content, parseError: e.message }
+            );
+        }
     }
 
     /**
      * Wrap of chatCompletion to handle toolcalls from LLM.
+     * @param {Array} messages - Conversation messages
+     * @param {string} tenantId - Tenant identifier
+     * @param {string} systemPrompt - System instructions
+     * @param {Array} tools - Tools array
+     * @param {Object} options - Options object (for responseFormat, etc.)
+     * @returns {Object} Response with content, tool_calls, and optionally parsedContent
      */
-    async chatWithTools(messages, tenantId, systemPrompt, tools = []) {
+    async chatWithTools(messages, tenantId, systemPrompt, tools = [], options = {}) {
         const provider = await this._getProvider(tenantId);
 
         let currentMessages = [...messages];
 
-        // Initial call
+        // Initial call - pass options to enable JSON mode, etc.
         const initialResponse = await provider.chatCompletion(
             currentMessages,
             systemPrompt,
-            tools
+            tools,
+            options
         );
 
-        let { content, tool_calls } = initialResponse;
+        let { content, tool_calls, parsedContent } = initialResponse;
 
         // Tool execution loop
         while (tool_calls) {
@@ -96,18 +192,29 @@ export class LLMService {
             // 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
+            // Next call - also pass options
             const nextResponse = await provider.chatCompletion(
                 currentMessages,
                 systemPrompt,
-                tools
+                tools,
+                options
             );
 
             content = nextResponse.content;
             tool_calls = nextResponse.tool_calls;
+            parsedContent = nextResponse.parsedContent; // Preserve parsedContent from final response
         }
 
-        return { content };
+        // Return both content and parsedContent (if available)
+        return { content, parsedContent, toolCalls: tool_calls };
+    }
+
+    /**
+     * Generate a video
+     */
+    async videoGeneration(prompt, images, tenantId, modelName, systemPrompt, options = {}) {
+        const provider = await this._getProvider(tenantId);
+        return provider.videoGeneration(prompt, images, modelName, systemPrompt, options);
     }
 
     /**