@llumiverse/core 1.3.0 → 1.4.0-dev.20260629.090753Z

package/src/conversation-utils.ts

@@ -49,6 +49,15 @@ export interface StripOptions {
      * - N > 0: Truncate text to approximately N tokens (~4 chars/token)
      */
     textMaxTokens?: number;
+    /**
+     * Number of most-recent messages to leave untouched when truncating large
+     * text (the active working set). Only messages OLDER than the last
+     * `keepRecentMessages` entries get their large strings truncated to
+     * `textMaxTokens`. Requires a conversation with a `messages` array.
+     * - undefined/0: No turn awareness — truncate every large string (legacy).
+     * - N > 0: Keep the last N messages full; truncate older ones.
+     */
+    keepRecentMessages?: number;
 }
 
 /**
@@ -147,9 +156,7 @@ function isOpenAIBase64ImageBlock(obj: unknown): boolean {
     if (o.type !== 'image_url') return false;
     if (!o.image_url || typeof o.image_url !== 'object') return false;
     const imgUrl = o.image_url as Record<string, unknown>;
-    return typeof imgUrl.url === 'string' &&
-        imgUrl.url.startsWith('data:image/') &&
-        imgUrl.url.includes(';base64,');
+    return typeof imgUrl.url === 'string' && imgUrl.url.startsWith('data:image/') && imgUrl.url.includes(';base64,');
 }
 
 /**
@@ -236,7 +243,7 @@ export function setConversationMeta(conversation: unknown, meta: ConversationMet
         return { [ARRAY_WRAPPER_KEY]: conversation, [META_KEY]: meta };
     }
     if (typeof conversation === 'object' && conversation !== null) {
-        return { ...conversation as object, [META_KEY]: meta };
+        return { ...(conversation as object), [META_KEY]: meta };
     }
     return conversation;
 }
@@ -305,7 +312,7 @@ function serializeBinaryForStorage(obj: unknown): unknown {
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => serializeBinaryForStorage(item));
+        return obj.map((item) => serializeBinaryForStorage(item));
     }
 
     if (typeof obj === 'object') {
@@ -335,7 +342,7 @@ export function deserializeBinaryFromStorage(obj: unknown): unknown {
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => deserializeBinaryFromStorage(item));
+        return obj.map((item) => deserializeBinaryFromStorage(item));
     }
 
     if (typeof obj === 'object') {
@@ -366,7 +373,7 @@ function stripBinaryFromConversationInternal(obj: unknown): unknown {
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => {
+        return obj.map((item) => {
             // Replace entire Bedrock image/document/video blocks with text blocks
             if (isBedrockImageBlock(item) || isSerializedBedrockImageBlock(item)) {
                 return { text: IMAGE_PLACEHOLDER };
@@ -432,7 +439,7 @@ function stripBase64ImagesFromConversationInternal(obj: unknown): unknown {
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => {
+        return obj.map((item) => {
             // Replace entire OpenAI image_url blocks with text blocks
             if (isOpenAIBase64ImageBlock(item)) {
                 return { type: 'text', text: IMAGE_PLACEHOLDER };
@@ -496,18 +503,72 @@ export function truncateLargeTextInConversation(obj: unknown, options?: StripOpt
     }
 
     const maxChars = maxTokens * CHARS_PER_TOKEN;
+    const keepRecent = options?.keepRecentMessages;
+
+    // Turn-aware path: keep the most recent `keepRecent` messages untouched (the
+    // agent's active working set — the file it just read/wrote, latest
+    // diagnostics) and truncate large strings only in older messages. This lets
+    // callers use an aggressive cap without blinding the model to current work.
+    if (keepRecent && keepRecent > 0) {
+        const messages = getConversationMessages(obj);
+        if (messages && messages.length > keepRecent) {
+            const cutoff = messages.length - keepRecent;
+            const truncated = messages.map((m, i) => (i < cutoff ? truncateLargeTextInternal(m, maxChars) : m));
+            return setConversationMessages(obj, truncated);
+        }
+        // No identifiable messages array, or short conversation: leave it full.
+        return obj;
+    }
+
+    // Legacy path: truncate every large string in the conversation.
     return truncateLargeTextInternal(obj, maxChars);
 }
 
+/**
+ * Extract the message history array from a conversation object, handling the
+ * `{ messages: [...] }` shape (Claude/OpenAI), the wrapped-array shape, and a
+ * plain array. Returns undefined when no message array is identifiable.
+ */
+function getConversationMessages(obj: unknown): unknown[] | undefined {
+    if (Array.isArray(obj)) return obj;
+    const wrapped = unwrapConversationArray(obj);
+    if (wrapped) return wrapped;
+    if (typeof obj === 'object' && obj !== null) {
+        const messages = (obj as Record<string, unknown>).messages;
+        if (Array.isArray(messages)) return messages;
+    }
+    return undefined;
+}
+
+/**
+ * Rebuild a conversation with a new message array, matching the shape returned
+ * by getConversationMessages.
+ */
+function setConversationMessages(obj: unknown, messages: unknown[]): unknown {
+    if (Array.isArray(obj)) return messages;
+    if (unwrapConversationArray(obj)) {
+        return { ...(obj as object), [ARRAY_WRAPPER_KEY]: messages };
+    }
+    if (typeof obj === 'object' && obj !== null) {
+        return { ...(obj as object), messages };
+    }
+    return obj;
+}
+
 function shouldPreserveMediaPayload(obj: unknown): boolean {
     if (typeof obj !== 'object' || obj === null) return false;
 
     const o = obj as Record<string, unknown>;
 
     // Preserved Bedrock binary blocks and their serialized storage wrapper.
-    if (isBedrockImageBlock(obj) || isSerializedBedrockImageBlock(obj) ||
-        isBedrockDocumentBlock(obj) || isSerializedBedrockDocumentBlock(obj) ||
-        isBedrockVideoBlock(obj) || isSerializedBedrockVideoBlock(obj)) {
+    if (
+        isBedrockImageBlock(obj) ||
+        isSerializedBedrockImageBlock(obj) ||
+        isBedrockDocumentBlock(obj) ||
+        isSerializedBedrockDocumentBlock(obj) ||
+        isBedrockVideoBlock(obj) ||
+        isSerializedBedrockVideoBlock(obj)
+    ) {
         return true;
     }
 
@@ -516,8 +577,12 @@ function shouldPreserveMediaPayload(obj: unknown): boolean {
     }
 
     // Preserved base64 media payloads for OpenAI, Gemini, and Anthropic/Claude.
-    if (isOpenAIBase64ImageBlock(obj) || isGeminiInlineDataBlock(obj) ||
-        isAnthropicBase64ImageBlock(obj) || isAnthropicBase64DocumentBlock(obj)) {
+    if (
+        isOpenAIBase64ImageBlock(obj) ||
+        isGeminiInlineDataBlock(obj) ||
+        isAnthropicBase64ImageBlock(obj) ||
+        isAnthropicBase64DocumentBlock(obj)
+    ) {
         return true;
     }
 
@@ -533,13 +598,24 @@ function truncateLargeTextInternal(obj: unknown, maxChars: number): unknown {
             return obj;
         }
         if (obj.length > maxChars) {
-            return obj.substring(0, maxChars) + TEXT_TRUNCATED_MARKER;
+            // Don't cut through a surrogate pair: substring() slices at a UTF-16
+            // code-unit index, so a boundary that lands between the two halves of
+            // a non-BMP character (emoji, CJK-ext, …) leaves a lone high surrogate.
+            // That is invalid Unicode — it can't be UTF-8 encoded losslessly and
+            // strict JSON parsers (e.g. Vertex/Gemini) reject the request body as
+            // "The input data is not valid json". Step back one unit in that case.
+            let end = maxChars;
+            const lastUnit = obj.charCodeAt(end - 1);
+            if (lastUnit >= 0xd800 && lastUnit <= 0xdbff) {
+                end -= 1;
+            }
+            return obj.substring(0, end) + TEXT_TRUNCATED_MARKER;
         }
         return obj;
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => truncateLargeTextInternal(item, maxChars));
+        return obj.map((item) => truncateLargeTextInternal(item, maxChars));
     }
 
     if (typeof obj === 'object') {
@@ -608,7 +684,7 @@ function stripHeartbeatsInternal(obj: unknown): unknown {
     }
 
     if (Array.isArray(obj)) {
-        return obj.map(item => stripHeartbeatsInternal(item));
+        return obj.map((item) => stripHeartbeatsInternal(item));
     }
 
     if (typeof obj === 'object') {

package/src/embeddings.ts

@@ -0,0 +1,157 @@
+import type {
+    DataSource,
+    EmbeddingInput,
+    EmbeddingResultItem,
+    EmbeddingsOptions,
+    EmbeddingsResult,
+    EmbeddingTaskType,
+    TextEmbeddingInput,
+} from '@llumiverse/common';
+import { readStreamAsBase64, readStreamAsUint8Array } from './stream.js';
+
+/** DataSource wrapping an in-memory base64 string. */
+export class Base64DataSource implements DataSource {
+    constructor(
+        public readonly name: string,
+        public readonly mime_type: string,
+        private readonly base64: string,
+    ) {}
+
+    async getStream(): Promise<ReadableStream<Uint8Array>> {
+        const bytes = Buffer.from(this.base64, 'base64');
+        return new ReadableStream<Uint8Array>({
+            start(controller) {
+                controller.enqueue(new Uint8Array(bytes));
+                controller.close();
+            },
+        });
+    }
+
+    async getURL(): Promise<string> {
+        return `data:${this.mime_type};base64,${this.base64}`;
+    }
+
+    async getURI(): Promise<string> {
+        return this.getURL();
+    }
+
+    /** Convenience accessor that avoids re-encoding via getStream. */
+    getBase64(): string {
+        return this.base64;
+    }
+}
+
+/**
+ * DataSource wrapping a remote URL. The URL is exposed via getURL() so
+ * drivers can pass it directly to providers that support URL inputs
+ * (gs://, s3://, https://). getStream() fetches the URL on demand.
+ */
+export class URLDataSource implements DataSource {
+    constructor(
+        public readonly name: string,
+        public readonly mime_type: string,
+        private readonly url: string,
+    ) {}
+
+    async getStream(): Promise<ReadableStream<Uint8Array>> {
+        const response = await fetch(this.url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch ${this.url}: ${response.status} ${response.statusText}`);
+        }
+        if (!response.body) {
+            throw new Error(`Response body is empty for ${this.url}`);
+        }
+        return response.body as ReadableStream<Uint8Array>;
+    }
+
+    async getURL(): Promise<string> {
+        return this.url;
+    }
+
+    async getURI(): Promise<string> {
+        return this.url;
+    }
+}
+
+/**
+ * Read a DataSource as a base64-encoded string. Equivalent to streaming the
+ * source and base64-encoding the bytes.
+ */
+export async function dataSourceToBase64(ds: DataSource): Promise<string> {
+    if (ds instanceof Base64DataSource) {
+        return ds.getBase64();
+    }
+    return readStreamAsBase64(await ds.getStream());
+}
+
+/**
+ * Read a DataSource fully into a Uint8Array.
+ */
+export async function dataSourceToBytes(ds: DataSource): Promise<Uint8Array> {
+    return readStreamAsUint8Array(await ds.getStream());
+}
+
+/** Returns the first vector from a single-input EmbeddingsResult. */
+export function firstVector(result: EmbeddingsResult): number[] {
+    const first = result.results[0]?.outputs[0]?.values;
+    if (!first) {
+        throw new Error('EmbeddingsResult contains no vectors');
+    }
+    return first;
+}
+
+/**
+ * Validate an EmbeddingsOptions object and return a normalized copy where:
+ * - request-level task_type is propagated to text inputs that don't define their own
+ * - inputs is guaranteed non-empty
+ *
+ * Drivers should call this before doing any provider-specific work.
+ */
+export function normalizeEmbeddingsOptions(options: EmbeddingsOptions): EmbeddingsOptions {
+    if (!options.inputs || options.inputs.length === 0) {
+        throw new Error('EmbeddingsOptions.inputs must contain at least one input');
+    }
+
+    const inputs: EmbeddingInput[] = options.inputs.map((input) => {
+        if (input.type === 'text') {
+            const text = input as TextEmbeddingInput;
+            return {
+                ...text,
+                task_type: text.task_type ?? options.task_type,
+            } satisfies TextEmbeddingInput;
+        }
+        return input;
+    });
+
+    return {
+        ...options,
+        inputs,
+    };
+}
+
+/**
+ * Apply a task-type prompt prefix to a text input. Used by drivers that need
+ * to pass task type through the prompt when the model does not accept it as
+ * an API parameter (e.g. Vertex AI gemini-embedding-2).
+ */
+export function applyTaskTypePrefix(
+    text: string,
+    taskType: EmbeddingTaskType | undefined,
+    mapping: Partial<Record<EmbeddingTaskType, string>>,
+): string {
+    if (!taskType) return text;
+    const prefix = mapping[taskType];
+    return prefix ? prefix + text : text;
+}
+
+/**
+ * Group result items so each item lines up with the corresponding input.
+ * Helper for drivers that fan out multiple provider calls.
+ */
+export function buildEmbeddingsResult(
+    model: string,
+    results: EmbeddingResultItem[],
+    usage?: EmbeddingsResult['usage'],
+): EmbeddingsResult {
+    return { model, results, usage };
+}

package/src/formatters/commons.ts

@@ -1,5 +1,5 @@
-import { JSONSchema } from "@llumiverse/common";
+import type { JSONSchema } from '@llumiverse/common';
 
 export function getJSONSafetyNotice(schema: JSONSchema) {
-    return "The answer must be a JSON object using the following JSON Schema:\n" + JSON.stringify(schema, undefined, 2);
+    return `The answer must be a JSON object using the following JSON Schema:\n${JSON.stringify(schema, undefined, 2)}`;
 }

package/src/formatters/generic.ts

@@ -1,24 +1,26 @@
-import { JSONSchema } from "@llumiverse/common";
-import { PromptRole, PromptSegment } from "@llumiverse/common";
-import { getJSONSafetyNotice } from "./commons.js";
+import type { JSONSchema } from '@llumiverse/common';
+import { PromptRole, type PromptSegment } from '@llumiverse/common';
+import { getJSONSafetyNotice } from './commons.js';
 
 interface Labels {
-    user: string,
-    system: string,
-    assistant: string,
-    safety: string,
-    instruction: string
+    user: string;
+    system: string;
+    assistant: string;
+    safety: string;
+    instruction: string;
 }
 
-export function createTextPromptFormatter(labels: Labels = {
-    user: "USER",
-    system: "CONTEXT",
-    assistant: "ASSISTANT",
-    safety: "IMPORTANT",
-    instruction: "INSTRUCTION"
-}) {
+export function createTextPromptFormatter(
+    labels: Labels = {
+        user: 'USER',
+        system: 'CONTEXT',
+        assistant: 'ASSISTANT',
+        safety: 'IMPORTANT',
+        instruction: 'INSTRUCTION',
+    },
+) {
     return function genericTextPrompt(segments: PromptSegment[], schema?: JSONSchema): string {
-        const isChat = segments.find(m => m.role === PromptRole.assistant);
+        const isChat = segments.find((m) => m.role === PromptRole.assistant);
         const context: string[] = [];
         const content: string[] = [];
         const safety: string[] = [];
@@ -59,8 +61,9 @@ export function createTextPromptFormatter(labels: Labels = {
             out.push(`${labels.safety}: ${safety.join('\n')}`);
         }
         return out.join('\n');
-    }
+    };
 }
 
 const formatTextPrompt = createTextPromptFormatter();
+
 export { formatTextPrompt };

package/src/formatters/index.ts

@@ -1,3 +1,3 @@
-export * from "./commons.js";
-export * from "./generic.js";
-export * from "./nova.js";
+export * from './commons.js';
+export * from './generic.js';
+export * from './nova.js';

package/src/formatters/nova.ts

@@ -1,37 +1,37 @@
-import { JSONSchema } from "@llumiverse/common";
-import { PromptRole, PromptSegment } from "@llumiverse/common";
-import { readStreamAsBase64 } from "../stream.js";
-import { getJSONSafetyNotice } from "./commons.js";
+import type { JSONSchema } from '@llumiverse/common';
+import { PromptRole, type PromptSegment } from '@llumiverse/common';
+import { readStreamAsBase64 } from '../stream.js';
+import { getJSONSafetyNotice } from './commons.js';
 
 export interface NovaMessage {
-    role: 'user' | 'assistant',
-    content: NovaMessagePart[]
+    role: 'user' | 'assistant';
+    content: NovaMessagePart[];
 }
 
 export interface NovaSystemMessage {
-    text: string
+    text: string;
 }
 
 interface NovaMessagePart {
-    text?: string // only set for text messages
+    text?: string; // only set for text messages
     image?: {
-        format: "jpeg" | "png" | "gif" | "webp",
+        format: 'jpeg' | 'png' | 'gif' | 'webp';
         source: {
-            bytes: string //"base64",
-        }
-    }
+            bytes: string; //"base64",
+        };
+    };
     video?: {
-        format: "mkv" | "mov" | "mp4" | "webm" | "three_gp" | "flv" | "mpeg" | "mpg" | "wmv",
+        format: 'mkv' | 'mov' | 'mp4' | 'webm' | 'three_gp' | 'flv' | 'mpeg' | 'mpg' | 'wmv';
         source: {
             //Option 1: sending a s3 location
             s3Location?: {
-                uri: string, // example: s3://my-bucket/object-key
-                bucketOwner: string // optional. example: "123456789012"
-            }
+                uri: string; // example: s3://my-bucket/object-key
+                bucketOwner: string; // optional. example: "123456789012"
+            };
             //Option 2: sending a base64 encoded video
-            bytes?: string //"base64",
-        }
-    }
+            bytes?: string; //"base64",
+        };
+    };
 }
 
 export interface NovaMessagesPrompt {
@@ -49,36 +49,36 @@ export async function formatNovaPrompt(segments: PromptSegment[], schema?: JSONS
     const system: string[] = [];
     const safety: string[] = [];
     const messages: NovaMessage[] = [];
-    let negative: string = "";
-    let mask: string = "";
+    let negative: string = '';
+    let mask: string = '';
 
     for (const segment of segments) {
-
         const parts: NovaMessagePart[] = [];
-        if (segment.files) for (const f of segment.files) {
-            //TODO add video support
-            if (!f.mime_type?.startsWith('image')) {
-                continue;
-            }
-
-            const source = await f.getStream();
-            const data = await readStreamAsBase64(source);
-            const format = f.mime_type?.split('/')[1] || 'png';
-
-            parts.push({
-                image: {
-                    format: format as "jpeg" | "png" | "gif" | "webp",
-                    source: {
-                        bytes: data
-                    }
+        if (segment.files)
+            for (const f of segment.files) {
+                //TODO add video support
+                if (!f.mime_type?.startsWith('image')) {
+                    continue;
                 }
-            })
-        }
+
+                const source = await f.getStream();
+                const data = await readStreamAsBase64(source);
+                const format = f.mime_type?.split('/')[1] || 'png';
+
+                parts.push({
+                    image: {
+                        format: format as 'jpeg' | 'png' | 'gif' | 'webp',
+                        source: {
+                            bytes: data,
+                        },
+                    },
+                });
+            }
 
         if (segment.content) {
             parts.push({
-                text: segment.content
-            })
+                text: segment.content,
+            });
         }
 
         if (segment.role === PromptRole.system) {
@@ -96,13 +96,13 @@ export async function formatNovaPrompt(segments: PromptSegment[], schema?: JSONS
         } else if (segment.role !== PromptRole.tool) {
             messages.push({
                 role: segment.role,
-                content: parts
+                content: parts,
             });
         }
     }
 
     if (schema) {
-        safety.push("IMPORTANT: " + getJSONSafetyNotice(schema));
+        safety.push(`IMPORTANT: ${getJSONSafetyNotice(schema)}`);
     }
 
     // messages must contains at least 1 item. If the prompt does not contains a user message (but only system messages)
@@ -116,7 +116,7 @@ export async function formatNovaPrompt(segments: PromptSegment[], schema?: JSONS
         messages.push({ content: [{ text: systemMessage }], role: 'user' });
         systemMessage = safety.join('\n');
     } else if (safety.length > 0) {
-        systemMessage = systemMessage + '\n\nIMPORTANT: ' + safety.join('\n');
+        systemMessage = `${systemMessage}\n\nIMPORTANT: ${safety.join('\n')}`;
     }
 
     /*start Nova's message to make sure it answers properly in JSON
@@ -124,18 +124,20 @@ export async function formatNovaPrompt(segments: PromptSegment[], schema?: JSONS
 
     if (schema) {
         messages.push({
-            role: "assistant",
-            content: [{
-                text: "{"
-            }]
+            role: 'assistant',
+            content: [
+                {
+                    text: '{',
+                },
+            ],
         });
     }
 
     // put system messages first and safety last
     return {
-        system: systemMessage ? [{ text: systemMessage }] : [{ text: "" }],
+        system: systemMessage ? [{ text: systemMessage }] : [{ text: '' }],
         messages: messages,
         negative: negative || undefined,
         mask: mask || undefined,
-    }
+    };
 }