@llumiverse/drivers 1.3.0 → 1.4.0

package/src/bedrock/streaming-tool-use.test.ts

@@ -1,18 +1,19 @@
 import {
-    AIModel,
-    Completion,
-    CompletionChunkObject,
-    DriverOptions,
-    EmbeddingsOptions,
-    EmbeddingsResult,
-    ExecutionOptions,
-    ModelSearchPayload,
+    type AIModel,
+    type Completion,
+    type CompletionChunkObject,
+    type DriverOptions,
+    type EmbeddingsOptions,
+    type EmbeddingsResult,
+    type ExecutionOptions,
+    type ModelSearchPayload,
     PromptRole,
-    PromptSegment,
+    type PromptSegment,
 } from '@llumiverse/common';
-import { AbstractDriver } from '@llumiverse/core';
+import { AbstractDriver } from '@llumiverse/core/driver';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { BedrockDriver } from './index.js';
+import type { Tree } from '../../test/__helpers__/test-utils.js';
+import { BedrockDriver, type BedrockPrompt } from './index.js';
 
 // ---------------------------------------------------------------------------
 // Unit tests: getExtractedStream tool use handling
@@ -28,7 +29,7 @@ describe('BedrockDriver getExtractedStream — tool use', () => {
     });
 
     it('emits an initial tool_use chunk on contentBlockStart', () => {
-        const chunk = driver['getExtractedStream'](
+        const chunk = driver.getExtractedStream(
             {
                 contentBlockStart: {
                     contentBlockIndex: 1,
@@ -37,18 +38,18 @@ describe('BedrockDriver getExtractedStream — tool use', () => {
             },
             undefined,
             undefined,
-            toolBlocks
+            toolBlocks,
         );
 
         expect(chunk.tool_use).toHaveLength(1);
-        expect(chunk.tool_use![0]).toMatchObject({ id: 'tool-abc', tool_name: 'my_tool', tool_input: '' });
+        expect(chunk.tool_use?.[0]).toMatchObject({ id: 'tool-abc', tool_name: 'my_tool', tool_input: '' });
         expect(toolBlocks.get(1)).toEqual({ id: 'tool-abc', name: 'my_tool' });
     });
 
     it('emits a delta tool_use chunk on contentBlockDelta', () => {
         toolBlocks.set(1, { id: 'tool-abc', name: 'my_tool' });
 
-        const chunk = driver['getExtractedStream'](
+        const chunk = driver.getExtractedStream(
             {
                 contentBlockDelta: {
                     contentBlockIndex: 1,
@@ -57,52 +58,53 @@ describe('BedrockDriver getExtractedStream — tool use', () => {
             },
             undefined,
             undefined,
-            toolBlocks
+            toolBlocks,
         );
 
         expect(chunk.tool_use).toHaveLength(1);
-        expect(chunk.tool_use![0]).toMatchObject({ id: 'tool-abc', tool_name: '', tool_input: '{"key":' });
+        expect(chunk.tool_use?.[0]).toMatchObject({ id: 'tool-abc', tool_name: '', tool_input: '{"key":' });
     });
 
     it('removes the block from the map on contentBlockStop', () => {
         toolBlocks.set(1, { id: 'tool-abc', name: 'my_tool' });
 
-        driver['getExtractedStream'](
-            { contentBlockStop: { contentBlockIndex: 1 } },
-            undefined,
-            undefined,
-            toolBlocks
-        );
+        driver.getExtractedStream({ contentBlockStop: { contentBlockIndex: 1 } }, undefined, undefined, toolBlocks);
 
         expect(toolBlocks.has(1)).toBe(false);
     });
 
     it('tracks two interleaved tool calls by independent contentBlockIndex', () => {
-        driver['getExtractedStream'](
+        driver.getExtractedStream(
             { contentBlockStart: { contentBlockIndex: 1, start: { toolUse: { toolUseId: 'id-1', name: 'tool_a' } } } },
-            undefined, undefined, toolBlocks
+            undefined,
+            undefined,
+            toolBlocks,
         );
-        driver['getExtractedStream'](
+        driver.getExtractedStream(
             { contentBlockStart: { contentBlockIndex: 3, start: { toolUse: { toolUseId: 'id-2', name: 'tool_b' } } } },
-            undefined, undefined, toolBlocks
+            undefined,
+            undefined,
+            toolBlocks,
         );
 
         expect(toolBlocks.get(1)).toEqual({ id: 'id-1', name: 'tool_a' });
         expect(toolBlocks.get(3)).toEqual({ id: 'id-2', name: 'tool_b' });
 
-        const chunk = driver['getExtractedStream'](
+        const chunk = driver.getExtractedStream(
             { contentBlockDelta: { contentBlockIndex: 3, delta: { toolUse: { input: '"val"' } } } },
-            undefined, undefined, toolBlocks
+            undefined,
+            undefined,
+            toolBlocks,
         );
-        expect(chunk.tool_use![0].id).toBe('id-2');
+        expect(chunk.tool_use?.[0].id).toBe('id-2');
     });
 
     it('still extracts text deltas when no tool use is present', () => {
-        const chunk = driver['getExtractedStream'](
+        const chunk = driver.getExtractedStream(
             { contentBlockDelta: { contentBlockIndex: 0, delta: { text: 'hello' } } },
             undefined,
             undefined,
-            toolBlocks
+            toolBlocks,
         );
 
         expect(chunk.result).toEqual([{ type: 'text', value: 'hello' }]);
@@ -110,11 +112,11 @@ describe('BedrockDriver getExtractedStream — tool use', () => {
     });
 
     it('emits finish_reason "tool_use" from messageStop', () => {
-        const chunk = driver['getExtractedStream'](
+        const chunk = driver.getExtractedStream(
             { messageStop: { stopReason: 'tool_use' } },
             undefined,
             undefined,
-            toolBlocks
+            toolBlocks,
         );
 
         expect(chunk.finish_reason).toBe('tool_use');
@@ -133,13 +135,22 @@ class FakeDriver extends AbstractDriver<DriverOptions, string> {
         throw new Error('not implemented');
     }
 
-    async requestTextCompletionStream(_prompt: string, _options: ExecutionOptions): Promise<AsyncIterable<CompletionChunkObject>> {
+    async requestTextCompletionStream(
+        _prompt: string,
+        _options: ExecutionOptions,
+    ): Promise<AsyncIterable<CompletionChunkObject>> {
         const chunks = this.chunks;
-        return (async function* () { for (const c of chunks) yield c; })();
+        return (async function* () {
+            for (const c of chunks) yield c;
+        })();
     }
 
-    async listModels(_params?: ModelSearchPayload): Promise<AIModel[]> { return []; }
-    async validateConnection(): Promise<boolean> { return true; }
+    async listModels(_params?: ModelSearchPayload): Promise<AIModel[]> {
+        return [];
+    }
+    async validateConnection(): Promise<boolean> {
+        return true;
+    }
     async generateEmbeddings(_options: EmbeddingsOptions): Promise<EmbeddingsResult> {
         throw new Error('not implemented');
     }
@@ -154,18 +165,20 @@ describe('driver.stream() — Bedrock tool use accumulation', () => {
 
         // Simulate what the fixed getExtractedStream emits for one tool call
         driver.chunks = [
-            { result: [], tool_use: [{ id: 'tool-1', tool_name: 'do_thing', tool_input: '' as any }] },
-            { result: [], tool_use: [{ id: 'tool-1', tool_name: '', tool_input: '{"param"' as any }] },
-            { result: [], tool_use: [{ id: 'tool-1', tool_name: '', tool_input: ':"hello"}' as any }] },
+            { result: [], tool_use: [{ id: 'tool-1', tool_name: 'do_thing', tool_input: '' as unknown }] },
+            { result: [], tool_use: [{ id: 'tool-1', tool_name: '', tool_input: '{"param"' as unknown }] },
+            { result: [], tool_use: [{ id: 'tool-1', tool_name: '', tool_input: ':"hello"}' as unknown }] },
             { result: [], finish_reason: 'tool_use' },
         ];
 
         const stream = await driver.stream(FAKE_SEGMENTS, options);
-        for await (const _ of stream) { /* drain */ }
+        for await (const _ of stream) {
+            /* drain */
+        }
 
-        expect(stream.completion!.finish_reason).toBe('tool_use');
-        expect(stream.completion!.tool_use).toHaveLength(1);
-        expect(stream.completion!.tool_use![0]).toMatchObject({
+        expect(stream.completion?.finish_reason).toBe('tool_use');
+        expect(stream.completion?.tool_use).toHaveLength(1);
+        expect(stream.completion?.tool_use?.[0]).toMatchObject({
             id: 'tool-1',
             tool_name: 'do_thing',
             tool_input: { param: 'hello' },
@@ -177,20 +190,22 @@ describe('driver.stream() — Bedrock tool use accumulation', () => {
         const options: ExecutionOptions = { model: 'test-model' };
 
         driver.chunks = [
-            { result: [], tool_use: [{ id: 'id-a', tool_name: 'tool_a', tool_input: '' as any }] },
-            { result: [], tool_use: [{ id: 'id-b', tool_name: 'tool_b', tool_input: '' as any }] },
-            { result: [], tool_use: [{ id: 'id-a', tool_name: '', tool_input: '{"x":1}' as any }] },
-            { result: [], tool_use: [{ id: 'id-b', tool_name: '', tool_input: '{"y":2}' as any }] },
+            { result: [], tool_use: [{ id: 'id-a', tool_name: 'tool_a', tool_input: '' as unknown }] },
+            { result: [], tool_use: [{ id: 'id-b', tool_name: 'tool_b', tool_input: '' as unknown }] },
+            { result: [], tool_use: [{ id: 'id-a', tool_name: '', tool_input: '{"x":1}' as unknown }] },
+            { result: [], tool_use: [{ id: 'id-b', tool_name: '', tool_input: '{"y":2}' as unknown }] },
             { result: [], finish_reason: 'tool_use' },
         ];
 
         const stream = await driver.stream(FAKE_SEGMENTS, options);
-        for await (const _ of stream) { /* drain */ }
+        for await (const _ of stream) {
+            /* drain */
+        }
 
-        const toolUse = stream.completion!.tool_use!;
+        const toolUse = stream.completion?.tool_use ?? [];
         expect(toolUse).toHaveLength(2);
-        expect(toolUse.find(t => t.id === 'id-a')!.tool_input).toEqual({ x: 1 });
-        expect(toolUse.find(t => t.id === 'id-b')!.tool_input).toEqual({ y: 2 });
+        expect(toolUse.find((t) => t.id === 'id-a')?.tool_input).toEqual({ x: 1 });
+        expect(toolUse.find((t) => t.id === 'id-b')?.tool_input).toEqual({ y: 2 });
     });
 
     it('drops truncated tool calls when finish_reason is length', async () => {
@@ -198,15 +213,17 @@ describe('driver.stream() — Bedrock tool use accumulation', () => {
         const options: ExecutionOptions = { model: 'test-model' };
 
         driver.chunks = [
-            { result: [], tool_use: [{ id: 'trunc', tool_name: 'tool_c', tool_input: '' as any }] },
-            { result: [], tool_use: [{ id: 'trunc', tool_name: '', tool_input: '{"incomplete' as any }] },
+            { result: [], tool_use: [{ id: 'trunc', tool_name: 'tool_c', tool_input: '' as unknown }] },
+            { result: [], tool_use: [{ id: 'trunc', tool_name: '', tool_input: '{"incomplete' as unknown }] },
             { result: [], finish_reason: 'length' },
         ];
 
         const stream = await driver.stream(FAKE_SEGMENTS, options);
-        for await (const _ of stream) { /* drain */ }
+        for await (const _ of stream) {
+            /* drain */
+        }
 
-        expect(stream.completion!.tool_use).toBeUndefined();
+        expect(stream.completion?.tool_use).toBeUndefined();
     });
 });
 
@@ -215,21 +232,21 @@ describe('BedrockDriver buildStreamingConversation', () => {
         const driver = new BedrockDriver({ region: 'us-east-1' });
         const prompt = {
             modelId: 'anthropic.claude-sonnet',
-            messages: [
-                { role: 'user', content: [{ text: 'What is the weather in Paris?' }] },
-            ],
+            messages: [{ role: 'user', content: [{ text: 'What is the weather in Paris?' }] }],
         };
 
         const conversation = driver.buildStreamingConversation(
-            prompt as any,
-            [{ type: 'text', value: 'Let me check.' }] as any,
-            [{
-                id: 'tool-1',
-                tool_name: 'get_weather',
-                tool_input: { location: 'Paris' },
-            }],
-            { model: 'anthropic.claude-sonnet' } as ExecutionOptions
-        ) as any;
+            prompt as unknown as BedrockPrompt,
+            [{ type: 'text', value: 'Let me check.' }],
+            [
+                {
+                    id: 'tool-1',
+                    tool_name: 'get_weather',
+                    tool_input: { location: 'Paris' },
+                },
+            ],
+            { model: 'anthropic.claude-sonnet' } as ExecutionOptions,
+        ) as unknown as Tree;
 
         expect(conversation.messages).toHaveLength(2);
         expect(conversation.messages[0]).toEqual(prompt.messages[0]);

package/src/bedrock/twelvelabs.ts

@@ -1,15 +1,23 @@
-import { DataSource, ExecutionOptions, readStreamAsBase64 } from "@llumiverse/core";
-import { PromptSegment, PromptRole } from "@llumiverse/core";
+import {
+    type DataSource,
+    type ExecutionOptions,
+    type JSONSchema,
+    PromptRole,
+    type PromptSegment,
+    readStreamAsBase64,
+    type TextFallbackOptions,
+} from '@llumiverse/core';
+import { isAmazonS3Hostname, parseS3UrlToUri } from './s3.js';
 
 // TwelveLabs Pegasus Request/Response Types
 export interface TwelvelabsPegasusRequest {
     inputPrompt: string;
     temperature?: number;
     responseFormat?: {
-        type: "json_schema";
+        type: 'json_schema';
         json_schema: {
             name: string;
-            schema: any;
+            schema: JSONSchema;
         };
     };
     mediaSource: {
@@ -24,14 +32,14 @@ export interface TwelvelabsPegasusRequest {
 
 export interface TwelvelabsPegasusResponse {
     message: string;
-    finishReason: "stop" | "length";
+    finishReason: 'stop' | 'length';
 }
 
 // TwelveLabs Marengo Request/Response Types
 export interface TwelvelabsMarengoRequest {
-    inputType: "text" | "image" | "video" | "audio";
+    inputType: 'text' | 'image' | 'video' | 'audio';
     inputText?: string;
-    textTruncate?: "start" | "end";
+    textTruncate?: 'start' | 'end';
     mediaSource?: {
         base64String?: string;
         s3Location?: {
@@ -39,7 +47,7 @@ export interface TwelvelabsMarengoRequest {
             bucketOwner?: string;
         };
     };
-    embeddingOption?: "visual-text" | "visual-image" | "audio";
+    embeddingOption?: 'visual-text' | 'visual-image' | 'audio';
     startSec?: number;
     lengthSec?: number;
     useFixedLengthSec?: boolean;
@@ -48,7 +56,7 @@ export interface TwelvelabsMarengoRequest {
 
 export interface TwelvelabsMarengoResponse {
     embedding: number[];
-    embeddingOption: "visual-text" | "visual-image" | "audio";
+    embeddingOption: 'visual-text' | 'visual-image' | 'audio';
     startSec: number;
     endSec: number;
 }
@@ -56,21 +64,21 @@ export interface TwelvelabsMarengoResponse {
 // Convert prompt segments to TwelveLabs Pegasus request
 export async function formatTwelvelabsPegasusPrompt(
     segments: PromptSegment[],
-    options: ExecutionOptions
+    options: ExecutionOptions,
 ): Promise<TwelvelabsPegasusRequest> {
-    let inputPrompt = "";
+    let inputPrompt = '';
     let videoFile: DataSource | undefined;
 
     // Extract text content and video files from segments
     for (const segment of segments) {
         if (segment.role === PromptRole.system || segment.role === PromptRole.user) {
             if (segment.content) {
-                inputPrompt += segment.content + "\n";
+                inputPrompt += `${segment.content}\n`;
             }
 
             // Look for video files
             for (const file of segment.files ?? []) {
-                if (file.mime_type && file.mime_type.startsWith("video/")) {
+                if (file.mime_type?.startsWith('video/')) {
                     videoFile = file;
                     break; // Use the first video file found
                 }
@@ -79,28 +87,23 @@ export async function formatTwelvelabsPegasusPrompt(
     }
 
     if (!videoFile) {
-        throw new Error("TwelveLabs Pegasus requires a video file input");
+        throw new Error('TwelveLabs Pegasus requires a video file input');
     }
 
     // Prepare media source
-    let mediaSource: TwelvelabsPegasusRequest["mediaSource"];
+    let mediaSource: TwelvelabsPegasusRequest['mediaSource'];
 
     try {
         // Try to get S3 URL first
         const url = await videoFile.getURL();
         const parsedUrl = new URL(url);
 
-        if (parsedUrl.hostname.endsWith("amazonaws.com") &&
-            (parsedUrl.hostname.startsWith("s3.") || parsedUrl.hostname.includes(".s3."))) {
+        if (parsedUrl.protocol === 's3:' || isAmazonS3Hostname(parsedUrl.hostname)) {
             // Convert S3 URL to s3:// format
-            const bucketMatch = parsedUrl.hostname.match(/^(?:s3\.)?([^.]+)\.s3\./);
-            const bucket = bucketMatch ? bucketMatch[1] : parsedUrl.hostname.split('.')[0];
-            const key = parsedUrl.pathname.substring(1); // Remove leading slash
-
             mediaSource = {
                 s3Location: {
-                    uri: `s3://${bucket}/${key}`,
-                }
+                    uri: parsedUrl.protocol === 's3:' ? url : parseS3UrlToUri(parsedUrl),
+                },
             };
         } else {
             // Fall back to base64 encoding
@@ -108,26 +111,26 @@ export async function formatTwelvelabsPegasusPrompt(
             const base64String = await readStreamAsBase64(stream);
 
             mediaSource = {
-                base64String
+                base64String,
             };
         }
-    } catch (error) {
+    } catch {
         // If getting URL fails, use base64 encoding
         const stream = await videoFile.getStream();
         const base64String = await readStreamAsBase64(stream);
 
         mediaSource = {
-            base64String
+            base64String,
         };
     }
 
     const request: TwelvelabsPegasusRequest = {
         inputPrompt: inputPrompt.trim(),
-        mediaSource
+        mediaSource,
     };
 
     // Add optional parameters from model options
-    const modelOptions = options.model_options as any;
+    const modelOptions = options.model_options as TextFallbackOptions | undefined;
     if (modelOptions?.temperature !== undefined) {
         request.temperature = modelOptions.temperature;
     }
@@ -138,11 +141,11 @@ export async function formatTwelvelabsPegasusPrompt(
     // Add response format if result schema is specified
     if (options.result_schema) {
         request.responseFormat = {
-            type: "json_schema",
+            type: 'json_schema',
             json_schema: {
-                name: "response",
-                schema: options.result_schema
-            }
+                name: 'response',
+                schema: options.result_schema,
+            },
         };
     }