bedrock-wrapper 2.4.5 → 2.5.0

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 All notable changes to this project will be documented in this file.
 
+## [2.5.0] - 2025-08-12 (Converse API)
+### Added
+- Support for Converse API (streaming and non-streaming)
+
+### Technical Details
+- **Model Configuration**: All models use standard messages API format
+- **API Compatibility**: Supports OpenAI-style requests
+- **Response Processing**: Automatic reasoning tag handling based on model variant
+- **Streaming Fallback**: Automatic detection and fallback to non-streaming for unsupported models
+- **Testing Coverage**: Full integration with existing test suites and interactive example
+
 ## [2.4.5] - 2025-08-06 (GPT-OSS Models)
 ### Added
 - Support for OpenAI GPT-OSS models on AWS Bedrock

package/README.md

@@ -48,7 +48,7 @@ Bedrock Wrapper is an npm package that simplifies the integration of existing Op
     };
     ```
 
-    the `messages` variable should be in openai's role/content format  
+    the `messages` variable should be in openai's role/content format (not all models support system prompts)
     ```javascript
     messages = [
         {
@@ -98,6 +98,24 @@ Bedrock Wrapper is an npm package that simplifies the integration of existing Op
         console.log(`\n\completeResponse:\n${completeResponse}\n`); // ⇠ do stuff with the complete response
     }
 
+5. **NEW: Using the Converse API (optional)**
+    
+    You can now optionally use AWS Bedrock's Converse API instead of the Invoke API by passing `useConverseAPI: true` in the options parameter:
+    ```javascript
+    // Use the Converse API for unified request/response format across all models
+    for await (const chunk of bedrockWrapper(awsCreds, openaiChatCompletionsCreateObject, { useConverseAPI: true })) {
+        completeResponse += chunk;
+        process.stdout.write(chunk);
+    }
+    ```
+    
+    The Converse API provides:
+    - **Consistent API**: Single request/response format across all models
+    - **Simplified conversation management**: Better handling of multi-turn conversations
+    - **System prompts**: Cleaner separation of system instructions
+    - **Tool use support**: Native support for function calling (where supported)
+    - **Unified multimodal**: Consistent handling of text and image inputs
+
 ---
 
 ### Supported Models
@@ -150,7 +168,7 @@ Please modify the `bedrock_models.js` file and submit a PR 🏆 or create an Iss
 
 ### Image Support
 
-For models with image support (Claude 4 series, Claude 3.7 Sonnet, Claude 3.5 Sonnet, Claude 3 Haiku, Nova Pro, and Nova Lite), you can include images in your messages using the following format:
+For models with image support (Claude 4 series, Claude 3.7 Sonnet, Claude 3.5 Sonnet, Claude 3 Haiku, Nova Pro, and Nova Lite), you can include images in your messages using the following format (not all models support system prompts):
 
 ```javascript
 messages = [
@@ -239,6 +257,44 @@ const result = await bedrockWrapper(awsCreds, {
 
 ---
 
+### 🧪 Testing
+
+The package includes comprehensive test suites to verify functionality:
+
+```bash
+# Test all models with the Both APIs (Comparison)
+npm run test
+
+# Test all models with the Invoke API
+npm run test:invoke
+
+# Test all models with the Converse API
+npm run test:converse
+
+# Test vision/multimodal capabilities with Both APIs (Comparison)
+npm run test-vision
+
+# Test vision/multimodal capabilities with Invoke API
+npm run test-vision:invoke
+
+# Test vision/multimodal capabilities with Converse API
+npm run test-vision:converse
+
+# Test stop sequences functionality with Both APIs (Comparison)
+npm run test-stop
+
+# Test stop sequences functionality with Invoke API
+npm run test-stop:invoke
+
+# Test stop sequences functionality with Converse API
+npm run test-stop:converse
+
+# Interactive testing
+npm run interactive
+```
+
+---
+
 ### 📢 P.S.
 
 In case you missed it at the beginning of this doc, for an even easier setup, use the 🔀 [Bedrock Proxy Endpoint](https://github.com/jparkerweb/bedrock-proxy-endpoint) project to spin up your own custom OpenAI server endpoint (using the standard `baseUrl`, and `apiKey` params).

package/bedrock-wrapper.js

@@ -15,6 +15,7 @@ import { bedrock_models } from "./bedrock-models.js";
 import {
     BedrockRuntimeClient,
     InvokeModelCommand, InvokeModelWithResponseStreamCommand,
+    ConverseCommand, ConverseStreamCommand,
 } from "@aws-sdk/client-bedrock-runtime";
 // helper functions
 import {
@@ -81,14 +82,82 @@ function processReasoningTags(text, awsModel) {
     return text.replace(/<reasoning>[\s\S]*?<\/reasoning>/g, '').trim();
 }
 
-export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObject, { logging = false } = {} ) {
-    const { region, accessKeyId, secretAccessKey } = awsCreds;
-    let { messages, model, max_tokens, stream, temperature, top_p, include_thinking_data, stop, stop_sequences } = openaiChatCompletionsCreateObject;
-
-
-  let {awsModelId, awsModel} = findAwsModelWithId(model);
+// Convert messages to Converse API format
+async function convertToConverseFormat(messages) {
+    const converseMessages = [];
+    let systemPrompts = [];
+    
+    for (const msg of messages) {
+        if (msg.role === "system") {
+            // System messages are handled separately in Converse API
+            if (typeof msg.content === 'string') {
+                systemPrompts.push({ text: msg.content });
+            } else if (Array.isArray(msg.content)) {
+                // Extract text from content array
+                const textContent = msg.content
+                    .filter(item => item.type === 'text')
+                    .map(item => item.text || item)
+                    .join('\n');
+                if (textContent) {
+                    systemPrompts.push({ text: textContent });
+                }
+            }
+        } else {
+            // Convert user and assistant messages
+            let content = [];
+            
+            if (typeof msg.content === 'string') {
+                content = [{ text: msg.content }];
+            } else if (Array.isArray(msg.content)) {
+                for (const item of msg.content) {
+                    if (item.type === 'text') {
+                        content.push({ text: item.text || item });
+                    } else if (item.type === 'image') {
+                        // Handle image content
+                        if (item.source && item.source.data) {
+                            content.push({
+                                image: {
+                                    format: 'jpeg',
+                                    source: {
+                                        bytes: Buffer.from(item.source.data, 'base64')
+                                    }
+                                }
+                            });
+                        }
+                    } else if (item.type === 'image_url') {
+                        // Process image URL to base64
+                        const processedImage = await processImage(
+                            typeof item.image_url === 'string' ? 
+                            item.image_url : 
+                            item.image_url.url
+                        );
+                        content.push({
+                            image: {
+                                format: 'jpeg',
+                                source: {
+                                    bytes: Buffer.from(processedImage, 'base64')
+                                }
+                            }
+                        });
+                    }
+                }
+            }
+            
+            // Only add messages with actual content (Converse API doesn't allow empty content)
+            if (content.length > 0) {
+                converseMessages.push({
+                    role: msg.role,
+                    content: content
+                });
+            }
+        }
+    }
+    
+    return { messages: converseMessages, system: systemPrompts };
+}
 
-    // cleanup message content before formatting prompt message
+// Process messages for Invoke API (complex model-specific formatting)
+async function processMessagesForInvoke(messages, awsModel) {
     let message_cleaned = [];
     let system_message = "";
 
@@ -149,15 +218,17 @@ export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObjec
             message_cleaned.push({role: "assistant", content: ""});
         }
     }
+    
+    return { message_cleaned, system_message };
+}
 
-    let prompt;
-
-    // format prompt message from message array
+// Build prompt for Invoke API (model-specific formatting)
+function buildInvokePrompt(message_cleaned, awsModel) {
     if (awsModel.messages_api) {
         // convert message array to prompt object if model supports messages api
-        prompt = message_cleaned;
+        return message_cleaned;
     } else {
-        prompt = awsModel.bos_text;
+        let prompt = awsModel.bos_text;
         let eom_text_inserted = false;
         
         for (let i = 0; i < message_cleaned.length; i++) {
@@ -213,45 +284,13 @@ export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObjec
                 prompt += `\n${awsModel.eom_text}`;
             }
         }
+        return prompt;
     }
+}
 
-    // Add logging to see the final prompt
-    if (logging) {
-        console.log("\nFinal formatted prompt:", prompt);
-    }
-
-    let max_gen_tokens = max_tokens <= awsModel.max_supported_response_tokens ? max_tokens : awsModel.max_supported_response_tokens;
-
-    if (awsModel.special_request_schema?.thinking?.type === "enabled") {
-        // temperature may only be set to 1 when thinking is enabled
-        temperature = 1;
-        // top_p must be unset when thinking is enabled
-        top_p = undefined;
-        // bugget_tokens can not be greater than 80% of max_gen_tokens
-        let budget_tokens = awsModel.special_request_schema?.thinking?.budget_tokens;
-        if (budget_tokens > (max_gen_tokens * 0.8)) {
-            budget_tokens = Math.floor(max_gen_tokens * 0.8);
-        }
-        if (budget_tokens < 1024) {
-            budget_tokens = 1024;
-        }
-        // if awsModel.special_request_schema?.thinking?.budget_tokens, set it to budget_tokens
-        if (awsModel.special_request_schema?.thinking?.budget_tokens) {
-            awsModel.special_request_schema.thinking.budget_tokens = budget_tokens;
-            // max_gen_tokens has to be greater than budget_tokens
-            if (max_gen_tokens <= budget_tokens) {
-                // make max_gen_tokens 20% greater than budget_tokens
-                max_gen_tokens = Math.floor(budget_tokens * 1.2);
-            }
-        }
-    }
-
-    // if (logging) {
-    //     console.log("\nMax tokens:", max_gen_tokens);
-    // }
-
-    // Format the request payload using the model's native structure.
-    const request = awsModel.messages_api ? (() => {
+// Build request object for Invoke API (model-specific)
+function buildInvokeRequest(prompt, awsModel, max_gen_tokens, temperature, top_p, stop_sequences, stop, system_message) {
+    if (awsModel.messages_api) {
         // Check if this is a Nova model (has schemaVersion in special_request_schema)
         if (awsModel.special_request_schema?.schemaVersion === "messages-v1") {
             // Nova model format - convert messages to Nova's expected format
@@ -323,47 +362,35 @@ export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObjec
                 ...awsModel.special_request_schema
             };
         }
-    })() : {
-        prompt: typeof prompt === 'string' ? prompt : {
-            messages: prompt.map(msg => ({
-                role: msg.role,
-                content: Array.isArray(msg.content) ? 
-                    msg.content.map(item => 
-                        item.type === 'text' ? item.text : item
-                    ).join('\n') : 
-                    msg.content
-            }))
-        },
-        // Optional inference parameters:
-        [awsModel.max_tokens_param_name]: max_gen_tokens,
-        temperature: temperature,
-        top_p: top_p,
-        ...(() => {
-            const stopSequencesValue = stop_sequences || stop;
-            return awsModel.stop_sequences_param_name && stopSequencesValue ? {
-                [awsModel.stop_sequences_param_name]: Array.isArray(stopSequencesValue) ? stopSequencesValue : [stopSequencesValue]
-            } : {};
-        })(),
-        ...awsModel.special_request_schema
-    };
-    
-    // Create a Bedrock Runtime client in the AWS Region of your choice
-    const client = new BedrockRuntimeClient({
-        region: region,
-        credentials: {
-            accessKeyId: accessKeyId,
-            secretAccessKey: secretAccessKey,
-        },
-    });
-
-    if (logging) {
-        console.log("\nFinal request:", JSON.stringify(request, null, 2));
+    } else {
+        return {
+            prompt: typeof prompt === 'string' ? prompt : {
+                messages: prompt.map(msg => ({
+                    role: msg.role,
+                    content: Array.isArray(msg.content) ? 
+                        msg.content.map(item => 
+                            item.type === 'text' ? item.text : item
+                        ).join('\n') : 
+                        msg.content
+                }))
+            },
+            // Optional inference parameters:
+            [awsModel.max_tokens_param_name]: max_gen_tokens,
+            temperature: temperature,
+            top_p: top_p,
+            ...(() => {
+                const stopSequencesValue = stop_sequences || stop;
+                return awsModel.stop_sequences_param_name && stopSequencesValue ? {
+                    [awsModel.stop_sequences_param_name]: Array.isArray(stopSequencesValue) ? stopSequencesValue : [stopSequencesValue]
+                } : {};
+            })(),
+            ...awsModel.special_request_schema
+        };
     }
+}
 
-    // Check if model supports streaming, override stream parameter if not
-    const modelSupportsStreaming = awsModel.streaming_supported !== false;
-    const shouldStream = stream && modelSupportsStreaming;
-
+// Execute Invoke API call (streaming and non-streaming)
+async function* executeInvokeAPI(client, request, awsModelId, shouldStream, awsModel, include_thinking_data) {
     if (shouldStream) {
         const responseStream = await client.send(
             new InvokeModelWithResponseStreamCommand({
@@ -452,7 +479,245 @@ export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObjec
             result = "";
         }
         yield result;
-    }    
+    }
+}
+
+export async function* bedrockWrapper(awsCreds, openaiChatCompletionsCreateObject, { logging = false, useConverseAPI = false } = {} ) {
+    const { region, accessKeyId, secretAccessKey } = awsCreds;
+    let { messages, model, max_tokens, stream, temperature, top_p, include_thinking_data, stop, stop_sequences } = openaiChatCompletionsCreateObject;
+
+    let {awsModelId, awsModel} = findAwsModelWithId(model);
+    
+    // Create a Bedrock Runtime client 
+    const client = new BedrockRuntimeClient({
+        region: region,
+        credentials: {
+            accessKeyId: accessKeyId,
+            secretAccessKey: secretAccessKey,
+        },
+    });
+
+    // Calculate max tokens (shared between both APIs)
+    let max_gen_tokens = max_tokens <= awsModel.max_supported_response_tokens ? max_tokens : awsModel.max_supported_response_tokens;
+    
+    // Check if model supports streaming
+    const modelSupportsStreaming = awsModel.streaming_supported !== false;
+    const shouldStream = stream && modelSupportsStreaming;
+
+    // ============================
+    // CONVERSE API PATH (SIMPLIFIED)
+    // ============================
+    if (useConverseAPI) {
+        // Convert messages to Converse API format (no model-specific complexity)
+        const { messages: converseMessages, system: systemPrompts } = await convertToConverseFormat(messages);
+        
+        // Build inference configuration (handle thinking mode for Claude models)
+        const inferenceConfig = {
+            maxTokens: max_gen_tokens,
+            temperature: temperature,
+            ...(top_p !== undefined && { topP: top_p })
+        };
+        
+        // Handle thinking mode for Claude models
+        let budget_tokens;
+        if (awsModel.special_request_schema?.thinking?.type === "enabled") {
+            // Apply thinking mode constraints for Converse API
+            inferenceConfig.temperature = 1; // temperature must be 1 for thinking
+            delete inferenceConfig.topP; // top_p must be unset for thinking
+            
+            // Calculate thinking budget configuration
+            budget_tokens = awsModel.special_request_schema?.thinking?.budget_tokens;
+            if (budget_tokens > (max_gen_tokens * 0.8)) {
+                budget_tokens = Math.floor(max_gen_tokens * 0.8);
+            }
+            if (budget_tokens < 1024) {
+                budget_tokens = 1024;
+            }
+            
+            // Ensure max tokens is sufficient for thinking
+            if (inferenceConfig.maxTokens <= budget_tokens) {
+                inferenceConfig.maxTokens = Math.floor(budget_tokens * 1.2);
+            }
+        }
+        
+        // Add stop sequences if provided (unified format)
+        const stopSequencesValue = stop_sequences || stop;
+        if (stopSequencesValue) {
+            inferenceConfig.stopSequences = Array.isArray(stopSequencesValue) ? 
+                stopSequencesValue : [stopSequencesValue];
+        }
+        
+        // Build the Converse API request (simple, unified format)
+        const converseRequest = {
+            modelId: awsModelId,
+            messages: converseMessages,
+            inferenceConfig: inferenceConfig
+        };
+        
+        // Add system prompts if any
+        if (systemPrompts.length > 0) {
+            converseRequest.system = systemPrompts;
+        }
+        
+        // Add thinking configuration for Claude models
+        if (awsModel.special_request_schema?.thinking?.type === "enabled") {
+            converseRequest.additionalModelRequestFields = {
+                thinking: {
+                    type: "enabled",
+                    budget_tokens: budget_tokens
+                }
+            };
+            
+            if (awsModel.special_request_schema?.anthropic_beta) {
+                converseRequest.additionalModelRequestFields.anthropic_beta = awsModel.special_request_schema.anthropic_beta;
+            }
+        }
+        
+        if (logging) {
+            console.log("\nConverse API request:", JSON.stringify(converseRequest, null, 2));
+        }
+        
+        if (shouldStream) {
+            // Use ConverseStream for streaming responses
+            const responseStream = await client.send(new ConverseStreamCommand(converseRequest));
+            
+            let is_thinking = false;
+            let should_think = include_thinking_data && awsModel.special_request_schema?.thinking?.type === "enabled";
+            
+            for await (const event of responseStream.stream) {
+                if (event.contentBlockDelta) {
+                    const text = event.contentBlockDelta.delta?.text;
+                    const thinking = event.contentBlockDelta.delta?.thinking;
+                    const reasoningContent = event.contentBlockDelta.delta?.reasoningContent;
+                    
+                    // Handle Claude thinking data (streaming) - check both reasoningContent and thinking
+                    const thinkingText = reasoningContent?.reasoningText?.text || thinking;
+                    if (should_think && thinkingText) {
+                        if (!is_thinking) {
+                            is_thinking = true;
+                            yield `<think>${thinkingText}`;
+                        } else {
+                            yield thinkingText;
+                        }
+                    }
+                    // Handle regular text content
+                    else if (text) {
+                        // End thinking mode if we were in it
+                        if (is_thinking) {
+                            is_thinking = false;
+                            yield `</think>\n\n${text}`;
+                        } else {
+                            // Process reasoning tags for GPT-OSS models only
+                            const processedText = processReasoningTags(text, awsModel);
+                            if (processedText) {
+                                yield processedText;
+                            }
+                        }
+                    }
+                }
+            }
+            
+            // Close thinking tag if still open
+            if (is_thinking) {
+                yield "</think>";
+            }
+        } else {
+            // Use Converse for non-streaming responses
+            const response = await client.send(new ConverseCommand(converseRequest));
+            
+            if (logging) {
+                console.log("\nConverse API response:", JSON.stringify(response, null, 2));
+            }
+            
+            // Extract text and thinking from response (handle Claude thinking)
+            if (response.output && response.output.message && response.output.message.content) {
+                let thinking_result = "";
+                let text_result = "";
+                
+                for (const contentBlock of response.output.message.content) {
+                    // Extract thinking data for Claude models (from reasoningContent)
+                    if (include_thinking_data && contentBlock.reasoningContent && 
+                        awsModel.special_request_schema?.thinking?.type === "enabled") {
+                        const reasoningText = contentBlock.reasoningContent.reasoningText?.text;
+                        if (reasoningText) {
+                            thinking_result += reasoningText;
+                        }
+                    }
+                    
+                    // Also check for legacy thinking field format
+                    if (include_thinking_data && contentBlock.thinking && 
+                        awsModel.special_request_schema?.thinking?.type === "enabled") {
+                        thinking_result += contentBlock.thinking;
+                    }
+                    
+                    // Extract regular text content
+                    if (contentBlock.text) {
+                        text_result += contentBlock.text;
+                    }
+                }
+                
+                // Process reasoning tags for GPT-OSS models
+                text_result = processReasoningTags(text_result, awsModel);
+                
+                // Combine thinking and text for Claude models
+                let result = thinking_result ? `<think>${thinking_result}</think>\n\n${text_result}` : text_result;
+                
+                if (result) {
+                    yield result;
+                }
+            }
+        }
+        return; // Exit early when using Converse API
+    }
+
+    // ============================
+    // INVOKE API PATH (COMPLEX, MODEL-SPECIFIC)
+    // ============================
+    
+    // Process messages for Invoke API (complex, model-specific)
+    const { message_cleaned, system_message } = await processMessagesForInvoke(messages, awsModel);
+    
+    // Build prompt for Invoke API (complex, model-specific)
+    const prompt = buildInvokePrompt(message_cleaned, awsModel);
+    
+    if (logging) {
+        console.log("\nFinal formatted prompt:", prompt);
+    }
+
+    // Handle thinking mode adjustments (Invoke API specific)
+    if (awsModel.special_request_schema?.thinking?.type === "enabled") {
+        // temperature may only be set to 1 when thinking is enabled
+        temperature = 1;
+        // top_p must be unset when thinking is enabled
+        top_p = undefined;
+        // budget_tokens can not be greater than 80% of max_gen_tokens
+        let budget_tokens = awsModel.special_request_schema?.thinking?.budget_tokens;
+        if (budget_tokens > (max_gen_tokens * 0.8)) {
+            budget_tokens = Math.floor(max_gen_tokens * 0.8);
+        }
+        if (budget_tokens < 1024) {
+            budget_tokens = 1024;
+        }
+        // if awsModel.special_request_schema?.thinking?.budget_tokens, set it to budget_tokens
+        if (awsModel.special_request_schema?.thinking?.budget_tokens) {
+            awsModel.special_request_schema.thinking.budget_tokens = budget_tokens;
+            // max_gen_tokens has to be greater than budget_tokens
+            if (max_gen_tokens <= budget_tokens) {
+                // make max_gen_tokens 20% greater than budget_tokens
+                max_gen_tokens = Math.floor(budget_tokens * 1.2);
+            }
+        }
+    }
+    
+    // Build request for Invoke API (complex, model-specific)
+    const request = buildInvokeRequest(prompt, awsModel, max_gen_tokens, temperature, top_p, stop_sequences, stop, system_message);
+    
+    if (logging) {
+        console.log("\nFinal request:", JSON.stringify(request, null, 2));
+    }
+    
+    // Execute Invoke API call (complex, model-specific response parsing)
+    yield* executeInvokeAPI(client, request, awsModelId, shouldStream, awsModel, include_thinking_data);
 }