@llumiverse/core 0.23.0 → 0.24.0

package/lib/types/conversation-utils.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Utilities for cleaning up conversation objects before storage.
+ *
+ * These functions strip binary data (Uint8Array) and large base64 strings
+ * from conversation objects to prevent JSON.stringify corruption and reduce
+ * storage bloat.
+ *
+ * IMPORTANT: These functions replace entire image/document/video BLOCKS with
+ * text placeholders, not just the data. This ensures the conversation remains
+ * valid for subsequent API calls.
+ */
+/**
+ * Metadata stored in conversation objects to track turn numbers for deferred image stripping.
+ */
+export interface ConversationMeta {
+    /** Current turn number (incremented each time a message is added) */
+    turnNumber: number;
+}
+/**
+ * Options for stripping functions
+ */
+export interface StripOptions {
+    /**
+     * Number of turns to keep images before stripping.
+     * - 0 or undefined: Strip immediately (default)
+     * - N > 0: Keep images for N turns, then strip
+     */
+    keepForTurns?: number;
+    /**
+     * Current turn number. Used with keepForTurns to determine when to strip.
+     * If not provided, will be read from conversation metadata.
+     */
+    currentTurn?: number;
+    /**
+     * Maximum tokens for text content in tool results.
+     * Text exceeding this limit will be truncated.
+     * - undefined/0: No truncation (default)
+     * - N > 0: Truncate text to approximately N tokens (~4 chars/token)
+     */
+    textMaxTokens?: number;
+}
+/**
+ * Get metadata from a conversation object, or return defaults.
+ */
+export declare function getConversationMeta(conversation: unknown): ConversationMeta;
+/**
+ * Set metadata on a conversation object.
+ * Arrays are wrapped in an object to preserve their type through JSON serialization.
+ */
+export declare function setConversationMeta(conversation: unknown, meta: ConversationMeta): unknown;
+/**
+ * Unwrap a conversation array that was wrapped by setConversationMeta.
+ * If the conversation is not a wrapped array, returns undefined.
+ * Use this to extract the actual message array from a conversation object.
+ */
+export declare function unwrapConversationArray<T = unknown>(conversation: unknown): T[] | undefined;
+/**
+ * Increment the turn number in a conversation and return the updated conversation.
+ */
+export declare function incrementConversationTurn(conversation: unknown): unknown;
+/**
+ * Strip binary data (Uint8Array) from conversation to prevent JSON.stringify corruption.
+ *
+ * When Uint8Array is passed through JSON.stringify, it gets corrupted into an object
+ * like { "0": 137, "1": 80, ... } instead of proper binary data. This breaks
+ * subsequent API calls that expect binary data.
+ *
+ * This function either:
+ * - Strips images immediately (keepForTurns = 0, default)
+ * - Serializes images to base64 for safe storage, then strips after N turns
+ *
+ * @param obj The conversation object to strip binary data from
+ * @param options Optional settings for turn-based stripping
+ * @returns A new object with binary content handled appropriately
+ */
+export declare function stripBinaryFromConversation(obj: unknown, options?: StripOptions): unknown;
+/**
+ * Restore Uint8Array from base64 serialization.
+ * Call this before sending conversation to API if images were preserved.
+ */
+export declare function deserializeBinaryFromStorage(obj: unknown): unknown;
+/**
+ * Strip large base64 image data from conversation to reduce storage bloat.
+ *
+ * While base64 strings survive JSON.stringify (unlike Uint8Array), they can
+ * significantly bloat conversation storage. This function replaces entire
+ * image blocks with text placeholders:
+ * - OpenAI: { type: "image_url", image_url: { url: "data:..." } } → { type: "text", text: "[placeholder]" }
+ * - Gemini: { inlineData: { data: "...", mimeType: "..." } } → { text: "[placeholder]" }
+ *
+ * @param obj The conversation object to strip base64 images from
+ * @param options Optional settings for turn-based stripping
+ * @returns A new object with image blocks replaced with text placeholders
+ */
+export declare function stripBase64ImagesFromConversation(obj: unknown, options?: StripOptions): unknown;
+/**
+ * Truncate large text content in conversation to reduce storage and context bloat.
+ *
+ * This function finds text strings in tool results and truncates them if they
+ * exceed the specified token limit (using ~4 chars/token estimate).
+ *
+ * Works with:
+ * - Bedrock: toolResult.content[].text
+ * - OpenAI: tool message content (string)
+ * - Gemini: function response content
+ *
+ * @param obj The conversation object to truncate text in
+ * @param options Options including textMaxTokens
+ * @returns A new object with large text content truncated
+ */
+export declare function truncateLargeTextInConversation(obj: unknown, options?: StripOptions): unknown;
+//# sourceMappingURL=conversation-utils.d.ts.map

package/lib/types/conversation-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-utils.d.ts","sourceRoot":"","sources":["../../src/conversation-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAUH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAyID;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,OAAO,GAAG,gBAAgB,CAQ3E;AAKD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,OAAO,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAS1F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,GAAG,OAAO,EAAE,YAAY,EAAE,OAAO,GAAG,CAAC,EAAE,GAAG,SAAS,CAQ3F;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,YAAY,EAAE,OAAO,GAAG,OAAO,CAGxE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAYzF;AA2BD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAwBlE;AAkDD;;;;;;;;;;;;GAYG;AACH,wBAAgB,iCAAiC,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAW/F;AA2CD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,+BAA+B,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAU7F"}

package/lib/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./Driver.js";
 export * from "./json.js";
 export * from "./stream.js";
+export * from "./conversation-utils.js";
 export * from "@llumiverse/common";
 //# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC"}

package/lib/types/stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AACA,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAkBxF"}
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../../src/stream.ts"],"names":[],"mappings":"AACA,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAGhF;AAED,wBAAsB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,CAAC,CAmBxF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llumiverse/core",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "type": "module",
   "description": "Provide an universal API to LLMs. Support for existing LLMs can be added by writing a driver.",
   "files": [
@@ -67,14 +67,14 @@
     "rimraf": "^6.1.2",
     "ts-dual-module": "^0.6.3",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.0.16"
   },
   "dependencies": {
     "@types/node": "^22.19.1",
     "ajv": "^8.17.1",
     "ajv-formats": "^3.0.1",
     "jsonrepair": "^3.13.1",
-    "@llumiverse/common": "0.23.0"
+    "@llumiverse/common": "0.24.0"
   },
   "ts_dual_module": {
     "outDir": "lib",

package/src/CompletionStream.ts

@@ -1,4 +1,4 @@
-import { CompletionStream, DriverOptions, ExecutionOptions, ExecutionResponse, ExecutionTokenUsage } from "@llumiverse/common";
+import { CompletionStream, DriverOptions, ExecutionOptions, ExecutionResponse, ExecutionTokenUsage, ToolUse } from "@llumiverse/common";
 import { AbstractDriver } from "./Driver.js";
 
 export class DefaultCompletionStream<PromptT = any> implements CompletionStream<PromptT> {
@@ -17,6 +17,7 @@ export class DefaultCompletionStream<PromptT = any> implements CompletionStream<
         this.completion = undefined;
         this.chunks = 0;
         const accumulatedResults: any[] = []; // Accumulate CompletionResult[] from chunks
+        const accumulatedToolUse: Map<string, ToolUse> = new Map(); // Accumulate tool_use by id
 
         this.driver.logger.debug(
             `[${this.driver.provider}] Streaming Execution of ${this.options.model} with prompt`,
@@ -45,6 +46,40 @@ export class DefaultCompletionStream<PromptT = any> implements CompletionStream<
                             promptTokens = Math.max(promptTokens, chunk.token_usage.prompt ?? 0);
                             resultTokens = Math.max(resultTokens ?? 0, chunk.token_usage.result ?? 0);
                         }
+                        // Accumulate tool_use from chunks
+                        // Note: During streaming, tool_input comes as string chunks that need concatenation
+                        if (chunk.tool_use && chunk.tool_use.length > 0) {
+                            for (const tool of chunk.tool_use) {
+                                const existing = accumulatedToolUse.get(tool.id);
+                                if (existing) {
+                                    // Merge tool input (for streaming where arguments come as string pieces)
+                                    if (tool.tool_input !== null && tool.tool_input !== undefined) {
+                                        const existingInput = existing.tool_input as unknown;
+                                        const newInput = tool.tool_input as unknown;
+                                        if (typeof existingInput === 'string' && typeof newInput === 'string') {
+                                            // Concatenate string arguments
+                                            (existing as any).tool_input = existingInput + newInput;
+                                        } else if (existingInput && typeof existingInput === 'object' && newInput && typeof newInput === 'object') {
+                                            // Merge objects
+                                            existing.tool_input = { ...(existingInput as object), ...(newInput as object) } as any;
+                                        } else {
+                                            existing.tool_input = tool.tool_input;
+                                        }
+                                    }
+                                    // Update tool name if provided (might come in later chunk)
+                                    if (tool.tool_name) {
+                                        existing.tool_name = tool.tool_name;
+                                    }
+                                    // Update actual ID if provided (OpenAI sends id only in first chunk)
+                                    if ((tool as any)._actual_id) {
+                                        (existing as any)._actual_id = (tool as any)._actual_id;
+                                    }
+                                } else {
+                                    // New tool call
+                                    accumulatedToolUse.set(tool.id, { ...tool });
+                                }
+                            }
+                        }
                         if (Array.isArray(chunk.result) && chunk.result.length > 0) {
                             // Process each result in the chunk, combining consecutive text/JSON
                             for (const result of chunk.result) {
@@ -118,6 +153,28 @@ export class DefaultCompletionStream<PromptT = any> implements CompletionStream<
         const tokens: ExecutionTokenUsage | undefined = resultTokens ?
             { prompt: promptTokens, result: resultTokens, total: resultTokens + promptTokens, } : undefined
 
+        // Convert accumulated tool_use Map to array
+        const toolUseArray = accumulatedToolUse.size > 0 ? Array.from(accumulatedToolUse.values()) : undefined;
+
+        // Finalize tool calls: restore actual IDs and parse JSON arguments
+        if (toolUseArray) {
+            for (const tool of toolUseArray) {
+                // Restore actual ID from OpenAI (was stored in _actual_id during streaming)
+                if ((tool as any)._actual_id) {
+                    tool.id = (tool as any)._actual_id;
+                    delete (tool as any)._actual_id;
+                }
+                // Parse tool_input strings as JSON if needed (streaming sends arguments as string chunks)
+                if (typeof tool.tool_input === 'string') {
+                    try {
+                        tool.tool_input = JSON.parse(tool.tool_input);
+                    } catch {
+                        // Keep as string if not valid JSON
+                    }
+                }
+            }
+        }
+
         this.completion = {
             result: accumulatedResults, // Return the accumulated CompletionResult[] instead of text
             prompt: this.prompt,
@@ -125,6 +182,18 @@ export class DefaultCompletionStream<PromptT = any> implements CompletionStream<
             token_usage: tokens,
             finish_reason: finish_reason,
             chunks: this.chunks,
+            tool_use: toolUseArray,
+        }
+
+        // Build conversation context for multi-turn support
+        const conversation = this.driver.buildStreamingConversation(
+            this.prompt,
+            accumulatedResults,
+            toolUseArray,
+            this.options
+        );
+        if (conversation !== undefined) {
+            this.completion.conversation = conversation;
         }
 
         try {

package/src/Driver.ts

@@ -242,6 +242,26 @@ export abstract class AbstractDriver<OptionsT extends DriverOptions = DriverOpti
         return [];
     }
 
+    /**
+     * Build the conversation context after streaming completion.
+     * Override this in driver implementations that support multi-turn conversations.
+     *
+     * @param prompt - The prompt that was sent (includes prior conversation context)
+     * @param result - The completion results from the streamed response
+     * @param toolUse - The tool calls from the streamed response (if any)
+     * @param options - The execution options
+     * @returns The updated conversation context, or undefined if not supported
+     */
+    buildStreamingConversation(
+        _prompt: PromptT,
+        _result: unknown[],
+        _toolUse: unknown[] | undefined,
+        _options: ExecutionOptions
+    ): unknown | undefined {
+        // Default implementation returns undefined - drivers can override
+        return undefined;
+    }
+
     abstract requestTextCompletion(prompt: PromptT, options: ExecutionOptions): Promise<Completion>;
 
     abstract requestTextCompletionStream(prompt: PromptT, options: ExecutionOptions): Promise<AsyncIterable<CompletionChunkObject>>;