@llumiverse/drivers 1.0.0-dev.20260202.145450Z → 1.0.0

package/src/bedrock/index.ts

@@ -10,22 +10,26 @@ import {
     BedrockClaudeOptions,
     BedrockGptOssOptions,
     BedrockPalmyraOptions,
-    Completion, CompletionChunkObject, DataSource, DriverOptions, EmbeddingsOptions, EmbeddingsResult,
+    Completion, CompletionChunkObject,
+    CompletionResult,
+    DataSource,
+    deserializeBinaryFromStorage,
+    DriverOptions, EmbeddingsOptions, EmbeddingsResult,
     ExecutionOptions, ExecutionTokenUsage,
+    getConversationMeta,
     getMaxTokensLimitBedrock,
     getModelCapabilities,
+    incrementConversationTurn,
+    LlumiverseError, LlumiverseErrorContext,
     modelModalitiesToArray,
     ModelOptions,
     NovaCanvasOptions,
     PromptSegment,
     StatelessExecutionOptions,
     stripBinaryFromConversation,
-    truncateLargeTextInConversation,
-    deserializeBinaryFromStorage,
-    getConversationMeta,
-    incrementConversationTurn,
+    stripHeartbeatsFromConversation,
     TextFallbackOptions, ToolDefinition, ToolUse, TrainingJob, TrainingJobStatus, TrainingOptions,
-    CompletionResult
+    truncateLargeTextInConversation
 } from "@llumiverse/core";
 import { transformAsyncIterator } from "@llumiverse/core/async";
 import { formatNovaPrompt, NovaMessagesPrompt } from "@llumiverse/core/formatters";
@@ -93,14 +97,49 @@ function maxTokenFallbackClaude(option: StatelessExecutionOptions): number {
     if (modelOptions && typeof modelOptions.max_tokens === "number") {
         return modelOptions.max_tokens;
     } else {
-        const thinking_budget = modelOptions?.thinking_budget_tokens ?? 0;
         let maxSupportedTokens = getMaxTokensLimitBedrock(option.model) ?? 8192; // Should always return a number for claude, 8192 is to satisfy the TypeScript type checker;
         // Fallback to the default max tokens limit for the model
         if (option.model.includes('claude-3-7-sonnet') && (modelOptions?.thinking_budget_tokens ?? 0) < 48000) {
             maxSupportedTokens = 64000; // Claude 3.7 can go up to 128k with a beta header, but when no max tokens is specified, we default to 64k.
         }
-        return Math.min(16000 + thinking_budget, maxSupportedTokens); // Cap to 16k, to avoid taking up too much context window and quota.
+        return maxSupportedTokens;
+    }
+}
+
+/**
+ * Parse Claude model version from model string.
+ * @param modelString - The model identifier string
+ * @returns An object with major and minor version numbers, or null if not parseable
+ */
+function parseClaudeVersion(modelString: string): { major: number; minor: number } | null {
+    // Match pattern: claude-[optional variant]-{major}-[optional 1-2 digit minor]
+    // The minor version is limited to 1-2 digits to avoid matching dates (YYYYMMDD format)
+    const match = modelString.match(/claude-(?:[a-z]+-)?(\d+)(?:-(\d{1,2}))?(?:-|\b)/);
+    if (match) {
+        return {
+            major: parseInt(match[1], 10),
+            minor: match[2] ? parseInt(match[2], 10) : 0
+        };
     }
+    return null;
+}
+
+/**
+ * Check if a Claude model version is greater than or equal to a target version.
+ * @returns true if the model version is >= target version, false otherwise
+ */
+function isClaudeVersionGTE(modelString: string, targetMajor: number, targetMinor: number): boolean {
+    const version = parseClaudeVersion(modelString);
+    if (!version) {
+        return false;
+    }
+    if (version.major > targetMajor) {
+        return true;
+    }
+    if (version.major === targetMajor && version.minor >= targetMinor) {
+        return true;
+    }
+    return false;
 }
 
 export type BedrockPrompt = NovaMessagesPrompt | ConverseRequest | TwelvelabsPegasusRequest;
@@ -153,6 +192,143 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         return await formatConversePrompt(segments, opts);
     }
 
+    /**
+     * Format AWS Bedrock errors into LlumiverseError with proper status codes and retryability.
+     * 
+     * AWS SDK errors provide:
+     * - error.name: The exception type (e.g., "ThrottlingException")
+     * - error.$metadata.httpStatusCode: The HTTP status code
+     * - error.$metadata.requestId: The AWS request ID for tracking
+     * - error.$fault: "client" or "server" indicating error category
+     * 
+     * @param error - The AWS SDK error
+     * @param context - Context about where the error occurred
+     * @returns A standardized LlumiverseError
+     */
+    public formatLlumiverseError(
+        error: unknown,
+        context: LlumiverseErrorContext
+    ): LlumiverseError {
+        // Check if it's an AWS SDK error with $metadata
+        const awsError = error as any;
+        const hasMetadata = awsError?.$metadata !== undefined;
+
+        if (!hasMetadata) {
+            // Not an AWS SDK error, use default handling
+            return super.formatLlumiverseError(error, context);
+        }
+
+        // Extract AWS-specific fields
+        const errorName = awsError.name || 'UnknownError';
+        const httpStatusCode = awsError.$metadata?.httpStatusCode;
+        const requestId = awsError.$metadata?.requestId;
+        const fault = awsError.$fault; // "client" or "server"
+
+        // Extract error message - handle both Error instances and plain objects
+        let message: string;
+        if (error instanceof Error) {
+            message = error.message;
+        } else if (typeof awsError.message === 'string') {
+            message = awsError.message;
+        } else {
+            message = String(error);
+        }
+
+        // Build user-facing message with error name and status code
+        let userMessage = message;
+
+        // Include status code in message if available (for end-user visibility)
+        if (httpStatusCode) {
+            userMessage = `[${httpStatusCode}] ${userMessage}`;
+        }
+
+        // Prefix with error name if it's meaningful (not just "Error")
+        if (errorName && errorName !== 'Error' && errorName !== 'UnknownError') {
+            userMessage = `${errorName}: ${userMessage}`;
+        }
+
+        // Add request ID if available (useful for AWS support)
+        if (requestId) {
+            userMessage += ` (Request ID: ${requestId})`;
+        }
+
+        // Determine retryability based on AWS error types
+        const retryable = this.isBedrockErrorRetryable(errorName, httpStatusCode, fault);
+
+        return new LlumiverseError(
+            `[${this.provider}] ${userMessage}`,
+            retryable,
+            context,
+            error,
+            httpStatusCode, // Only set code if we have numeric status code
+            errorName       // Preserve AWS error name
+        );
+    }
+
+    /**
+     * Determine if a Bedrock error is retryable based on error type and status.
+     * 
+     * Retryable errors:
+     * - ThrottlingException: Rate limit exceeded, retry with backoff
+     * - ServiceUnavailableException: Service temporarily down
+     * - InternalServerException: Server-side error
+     * - ServiceQuotaExceededException: Quota exhausted, may recover
+     * - 5xx status codes: Server errors
+     * - 429, 408 status codes: Rate limit, timeout
+     * 
+     * Non-retryable errors:
+     * - ValidationException: Invalid request parameters
+     * - AccessDeniedException: Authentication/authorization failure
+     * - ResourceNotFoundException: Resource doesn't exist
+     * - ConflictException: Resource state conflict
+     * - ResourceInUseException: Resource locked by another operation
+     * - 4xx status codes (except 429, 408): Client errors
+     * 
+     * @param errorName - The AWS error name (e.g., "ThrottlingException")
+     * @param httpStatusCode - The HTTP status code if available
+     * @param fault - The fault type ("client" or "server")
+     * @returns True if retryable, false if not retryable, undefined if unknown
+     */
+    private isBedrockErrorRetryable(
+        errorName: string,
+        httpStatusCode: number | undefined,
+        fault: string | undefined
+    ): boolean | undefined {
+        // Check specific AWS error types first
+        switch (errorName) {
+            // Retryable errors
+            case 'ThrottlingException':
+            case 'ServiceUnavailableException':
+            case 'InternalServerException':
+            case 'ServiceQuotaExceededException':
+                return true;
+
+            // Non-retryable errors
+            case 'ValidationException':
+            case 'AccessDeniedException':
+            case 'ResourceNotFoundException':
+            case 'ConflictException':
+            case 'ResourceInUseException':
+            case 'TooManyTagsException':
+                return false;
+        }
+
+        // If we have HTTP status code, use it
+        if (httpStatusCode !== undefined) {
+            if (httpStatusCode === 429 || httpStatusCode === 408) return true; // Rate limit, timeout
+            if (httpStatusCode === 529) return true; // Overloaded
+            if (httpStatusCode >= 500 && httpStatusCode < 600) return true; // Server errors
+            if (httpStatusCode >= 400 && httpStatusCode < 500) return false; // Client errors
+        }
+
+        // Fall back to fault type
+        if (fault === 'server') return true;
+        if (fault === 'client') return false;
+
+        // Unknown error type - let consumer decide retry strategy
+        return undefined;
+    }
+
     getExtractedExecution(result: ConverseResponse, _prompt?: BedrockPrompt, options?: ExecutionOptions): CompletionChunkObject {
         let resultText = "";
         let reasoning = "";
@@ -163,9 +339,11 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
                 if (content.text) {
                     resultText += content.text;
                 } else if (content.reasoningContent) {
-                    // Get reasoning content only if include_thoughts is true
+                    // Extract reasoning content if include_thoughts is true, or if it's a
+                    // reasoning-only model (e.g. DeepSeek R1) that returns no text blocks
                     const claudeOptions = options?.model_options as BedrockClaudeOptions;
-                    if (claudeOptions?.include_thoughts) {
+                    const isReasoningModel = options?.model?.includes('deepseek') && options?.model?.includes('r1');
+                    if (claudeOptions?.include_thoughts || isReasoningModel) {
                         if (content.reasoningContent.reasoningText) {
                             reasoning += content.reasoningContent.reasoningText.text;
                         } else if (content.reasoningContent.redactedContent) {
@@ -210,8 +388,9 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         let stop_reason = "";
         let token_usage: ExecutionTokenUsage | undefined;
 
-        // Check if we should include thoughts
-        const shouldIncludeThoughts = options && (options.model_options as BedrockClaudeOptions)?.include_thoughts;
+        // Check if we should include thoughts (always true for reasoning-only models like DeepSeek R1)
+        const isReasoningModel = options?.model?.includes('deepseek') && options?.model?.includes('r1');
+        const shouldIncludeThoughts = isReasoningModel || (options && (options.model_options as BedrockClaudeOptions)?.include_thoughts);
 
         // Handle content block start events (for reasoning blocks)
         if (result.contentBlockStart) {
@@ -443,6 +622,10 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         };
         let processedConversation = stripBinaryFromConversation(conversation, stripOptions);
         processedConversation = truncateLargeTextInConversation(processedConversation, stripOptions);
+        processedConversation = stripHeartbeatsFromConversation(processedConversation, {
+            keepForTurns: options.stripHeartbeatsAfterTurns ?? 1,
+            currentTurn,
+        });
 
         return processedConversation as ConverseRequest;
     }
@@ -467,8 +650,15 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
             ...payload,
         });
 
+        // Strip reasoningContent from assistant messages before storing in conversation
+        // (DeepSeek R1 returns reasoning blocks but rejects them in subsequent user turns)
+        const assistantMsg = res.output?.message ?? { content: [{ text: "" }], role: "assistant" };
+        if (assistantMsg.content) {
+            assistantMsg.content = assistantMsg.content.filter((c: any) => !c.reasoningContent);
+        }
+
         conversation = updateConversation(conversation, {
-            messages: [res.output?.message ?? { content: [{ text: "" }], role: "assistant" }],
+            messages: [assistantMsg],
             modelId: conversePrompt.modelId,
         });
 
@@ -504,6 +694,12 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         // Truncate large text content if configured
         processedConversation = truncateLargeTextInConversation(processedConversation, stripOptions);
 
+        // Strip old heartbeat status messages
+        processedConversation = stripHeartbeatsFromConversation(processedConversation, {
+            keepForTurns: options.stripHeartbeatsAfterTurns ?? 1,
+            currentTurn,
+        });
+
         const completion = {
             ...this.getExtractedExecution(res, conversePrompt, options),
             original_response: options.include_original_response ? res : undefined,
@@ -671,6 +867,10 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
                     };
                 }
             }
+            // Claude 4.6 and later versions don't support JSON prefill
+            if (isClaudeVersionGTE(options.model, 4, 6)) {
+                supportsJSONPrefill = false;
+            }
             //Needs max_tokens to be set
             if (!model_options.max_tokens) {
                 model_options.max_tokens = maxTokenFallbackClaude(options);
@@ -735,7 +935,9 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
                 min_tokens: palmyraOptions?.min_tokens,
             }
         } else if (options.model.includes("deepseek")) {
-            //DeepSeek models support no additional options
+            // DeepSeek models: no additional options, no stopSequences, only one of temperature/top_p
+            model_options.stop_sequence = undefined;
+            model_options.top_p = undefined;
         } else if (options.model.includes("gpt-oss")) {
             const gptOssOptions = model_options as ModelOptions as BedrockGptOssOptions;
             additionalField = {
@@ -769,7 +971,7 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         const cleanedModelOptions = removeUndefinedValues({
             maxTokens: model_options.max_tokens,
             temperature: model_options.temperature,
-            topP: model_options.top_p,
+            topP: model_options.temperature != null ? undefined : model_options.top_p,
             stopSequences: model_options.stop_sequence,
         } satisfies InferenceConfiguration);
 
@@ -799,6 +1001,12 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
             request.toolConfig = {
                 tools: tool_defs,
             }
+        } else if (request.messages && messagesContainToolBlocks(request.messages)) {
+            // Bedrock requires toolConfig when conversation contains toolUse/toolResult blocks.
+            // When no tools are provided (e.g. checkpoint summary calls), convert tool blocks
+            // to text representations so the conversation data is preserved while satisfying
+            // Bedrock's API requirements without making tools callable.
+            request.messages = convertToolBlocksToText(request.messages);
         }
 
         return request;
@@ -1142,7 +1350,7 @@ export class BedrockDriver extends AbstractDriver<BedrockDriverOptions, BedrockP
         const executor = this.getExecutor();
 
         // Prepare the request payload for TwelveLabs Marengo
-        let invokeBody: TwelvelabsMarengoRequest = {
+        const invokeBody: TwelvelabsMarengoRequest = {
             inputType: "text"
         };
 
@@ -1232,6 +1440,75 @@ function getToolDefinition(tool: ToolDefinition): Tool.ToolSpecMember {
     }
 }
 
+/**
+ * Checks whether any message contains toolUse or toolResult content blocks.
+ */
+export function messagesContainToolBlocks(messages: Message[]): boolean {
+    for (const msg of messages) {
+        if (!msg.content) continue;
+        for (const block of msg.content) {
+            if ((block as ContentBlock.ToolUseMember).toolUse ||
+                (block as ContentBlock.ToolResultMember).toolResult) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+
+/**
+ * Converts toolUse and toolResult content blocks to text representations.
+ * This preserves the tool call information in the conversation while removing
+ * the structured tool blocks that require Bedrock's toolConfig to be set.
+ *
+ * Used when no tools are provided (e.g. checkpoint summary calls) but the
+ * conversation history contains tool interactions from prior turns.
+ */
+export function convertToolBlocksToText(messages: Message[]): Message[] {
+    return messages.map(msg => {
+        if (!msg.content) return msg;
+        let hasToolBlocks = false;
+        for (const block of msg.content) {
+            if ((block as ContentBlock.ToolUseMember).toolUse ||
+                (block as ContentBlock.ToolResultMember).toolResult) {
+                hasToolBlocks = true;
+                break;
+            }
+        }
+        if (!hasToolBlocks) return msg;
+
+        const newContent: ContentBlock[] = [];
+        for (const block of msg.content) {
+            const toolUse = (block as ContentBlock.ToolUseMember).toolUse;
+            const toolResult = (block as ContentBlock.ToolResultMember).toolResult;
+            if (toolUse) {
+                const inputStr = toolUse.input ? JSON.stringify(toolUse.input) : '';
+                const truncatedInput = inputStr.length > 500 ? inputStr.substring(0, 500) + '...' : inputStr;
+                newContent.push({
+                    text: `[Tool call: ${toolUse.name}(${truncatedInput})]`,
+                } as ContentBlock.TextMember);
+            } else if (toolResult) {
+                const resultTexts: string[] = [];
+                if (toolResult.content) {
+                    for (const c of toolResult.content) {
+                        if ((c as any).text) {
+                            const text = (c as any).text as string;
+                            resultTexts.push(text.length > 500 ? text.substring(0, 500) + '...' : text);
+                        }
+                    }
+                }
+                const resultStr = resultTexts.length > 0 ? resultTexts.join('\n') : 'No text content';
+                newContent.push({
+                    text: `[Tool result: ${resultStr}]`,
+                } as ContentBlock.TextMember);
+            } else {
+                newContent.push(block);
+            }
+        }
+        return { ...msg, content: newContent };
+    });
+}
+
 /**
  * Recursively removes undefined values from an object.
  * AWS Bedrock's additionalModelRequestFields must be valid JSON, and undefined is not valid JSON.

package/src/groq/index.ts

@@ -299,12 +299,17 @@ function convertResponseItemsToGroqMessages(items: ResponseInputItem[]): ChatCom
                         } else if (part.type === 'input_image') {
                             const imgPart = part as OpenAI.Responses.ResponseInputImage;
                             if (imgPart.image_url) {
+                                const image_url: { url: string; detail?: 'auto' | 'low' | 'high' } = {
+                                    url: imgPart.image_url
+                                };
+
+                                if (imgPart.detail) {
+                                    image_url.detail = imgPart.detail as 'auto' | 'low' | 'high';
+                                }
+
                                 parts.push({
                                     type: 'image_url',
-                                    image_url: {
-                                        url: imgPart.image_url,
-                                        ...(imgPart.detail && { detail: imgPart.detail })
-                                    }
+                                    image_url
                                 });
                             }
                         }

package/src/mistral/index.ts

@@ -68,14 +68,17 @@ export class MistralAIDriver extends AbstractDriver<MistralAIDriverOptions, Open
         }
         options.model_options = options.model_options as TextFallbackOptions;
 
+        const requestPayload = _makeChatCompletionRequest({
+            model: options.model,
+            messages: messages,
+            maxTokens: options.model_options?.max_tokens,
+            temperature: options.model_options?.temperature,
+            responseFormat: this.getResponseFormat(options),
+        });
+        this.logger.debug({ payload: JSON.stringify(requestPayload) }, "Mistral request payload");
+
         const res = await this.client.post('/v1/chat/completions', {
-            payload: _makeChatCompletionRequest({
-                model: options.model,
-                messages: messages,
-                maxTokens: options.model_options?.max_tokens,
-                temperature: options.model_options?.temperature,
-                responseFormat: this.getResponseFormat(options),
-            })
+            payload: requestPayload,
         }) as ChatCompletionResponse;
 
         const choice = res.choices[0];
@@ -99,17 +102,20 @@ export class MistralAIDriver extends AbstractDriver<MistralAIDriverOptions, Open
         }
         options.model_options = options.model_options as TextFallbackOptions;
 
+        const streamPayload = _makeChatCompletionRequest({
+            model: options.model,
+            messages: messages,
+            maxTokens: options.model_options?.max_tokens,
+            temperature: options.model_options?.temperature,
+            topP: options.model_options?.top_p,
+            responseFormat: this.getResponseFormat(options),
+            stream: true,
+            stopSequences: options.model_options?.stop_sequence,
+        });
+        this.logger.debug({ payload: JSON.stringify(streamPayload) }, "Mistral stream request payload");
+
         const stream = await this.client.post('/v1/chat/completions', {
-            payload: _makeChatCompletionRequest({
-                model: options.model,
-                messages: messages,
-                maxTokens: options.model_options?.max_tokens,
-                temperature: options.model_options?.temperature,
-                topP: options.model_options?.top_p,
-                responseFormat: this.getResponseFormat(options),
-                stream: true,
-                stopSequences: options.model_options?.stop_sequence,
-            }),
+            payload: streamPayload,
             reader: 'sse'
         });
 
@@ -191,22 +197,19 @@ function _makeChatCompletionRequest({
     topP,
     randomSeed,
     stream,
-    safeMode,
-    safePrompt,
     toolChoice,
     responseFormat,
     stopSequences,
 }: CompletionRequestParams) {
     return {
-        model: model,
-        messages: messages,
+        model,
+        messages,
         tools: tools ?? undefined,
         temperature: temperature ?? undefined,
         max_tokens: maxTokens ?? undefined,
         top_p: topP ?? undefined,
         random_seed: randomSeed ?? undefined,
         stream: stream ?? undefined,
-        safe_prompt: (safeMode || safePrompt) ?? undefined,
         tool_choice: toolChoice ?? undefined,
         response_format: responseFormat ?? undefined,
         stop: stopSequences ?? undefined,

package/src/mistral/types.ts

@@ -132,11 +132,6 @@ export interface CompletionRequestParams {
     topP?: number,
     randomSeed?: number,
     stream?: boolean,
-    /**
-     * @deprecated use safePrompt instead
-     */
-    safeMode?: boolean,
-    safePrompt?: boolean,
     toolChoice?: ToolChoice,
     responseFormat?: ResponseFormat,
     stopSequences?: string[],