extrait 0.5.1 → 0.5.3

package/README.md

@@ -70,6 +70,7 @@ const llm = createLLM({
     mode: "loose" | "strict",            // loose allows repair
     selfHeal: 0 | 1 | 2,                 // retry attempts
     debug: false,                        // show repair logs
+    timeout: { request: 30_000 },        // optional default timeouts
   },
 });
 ```
@@ -159,11 +160,90 @@ const result = await llm.structured(
     request: {
       signal: abortController.signal,  // optional AbortSignal
     },
+    timeout: {
+      request: 30_000,  // ms per LLM HTTP request
+      tool: 10_000,     // ms per MCP tool call
+    },
   }
 );
 ```
 
-`prompt()` builds an ordered `messages` payload. Use `prompt\`...\`` for a single string prompt, or the fluent builder for multi-turn conversations. The `LLMMessage` type is exported if you need to type your own message arrays.
+`prompt()` builds an ordered `messages` payload. Use ``prompt`...` `` for a single string prompt, or the fluent builder for multi-turn conversations. The `LLMMessage` type is exported if you need to type your own message arrays.
+
+### Images (multimodal)
+
+Use `images()` to build base64 image content blocks for vision-capable models.
+
+```typescript
+import { images, prompt } from "extrait";
+import { readFileSync } from "fs";
+
+const base64 = readFileSync("photo.png").toString("base64");
+const img = { base64, mimeType: "image/png" };
+
+// With prompt() builder — pass LLMMessageContent array to .user() or .assistant()
+const result = await llm.structured(Schema,
+  prompt()
+    .system`You are a vision assistant.`
+    .user([{ type: "text", text: "Describe this image." }, ...images(img)])
+);
+
+// With raw messages array
+const result = await llm.structured(Schema, {
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "Describe this image." },
+        ...images(img),
+      ],
+    },
+  ],
+});
+
+// Multiple images
+const content = [
+  { type: "text", text: "Compare these two images." },
+  ...images([
+    { base64: base64A, mimeType: "image/png" },
+    { base64: base64B, mimeType: "image/jpeg" },
+  ]),
+];
+```
+
+`images()` accepts a single `{ base64, mimeType }` object or an array, and always returns an `LLMImageContent[]` that spreads directly into a content array.
+
+### Conversations (multi-turn history)
+
+Use `conversation()` to build a `LLMMessage[]` from an existing conversation history. This is the idiomatic way to pass prior turns to the LLM.
+
+```typescript
+import { conversation } from "extrait";
+
+const messages = conversation("You are a helpful assistant.", [
+  { role: "user",      text: "What is the speed of light?" },
+  { role: "assistant", text: "Approximately 299,792 km/s in a vacuum." },
+  { role: "user",      text: "How long does light take to reach Earth from the Sun?" },
+]);
+
+// Pass to adapter directly
+const response = await llm.adapter.complete({ messages });
+
+// Or to structured extraction
+const result = await llm.structured(Schema, { messages });
+```
+
+Entries with `images` produce multimodal content automatically:
+
+```typescript
+const messages = conversation("You are a vision assistant.", [
+  {
+    role: "user",
+    text: "What is in this image?",
+    images: [{ base64, mimeType: "image/png" }],
+  },
+]);
+```
 
 ### Result Object
 
@@ -246,6 +326,34 @@ const result = await llm.structured(
 await mcpClient.close?.();
 ```
 
+### Timeouts
+
+Use `timeout` to set per-request and per-tool-call time limits without managing `AbortSignal` manually.
+
+```typescript
+const result = await llm.structured(Schema, prompt`...`, {
+  timeout: {
+    request: 30_000,  // abort the LLM HTTP request after 30s
+    tool: 5_000,      // abort each MCP tool call after 5s
+  },
+});
+```
+
+Both fields are optional. `timeout.request` creates an `AbortSignal.timeout` internally; it is ignored if you also pass `request.signal` (your signal takes precedence). `timeout.tool` wraps each MCP client transparently.
+
+You can also set defaults on the client:
+
+```typescript
+const llm = createLLM({
+  provider: "openai-compatible",
+  model: "gpt-5-nano",
+  transport: { apiKey: process.env.LLM_API_KEY },
+  defaults: {
+    timeout: { request: 60_000 },
+  },
+});
+```
+
 ## Examples
 
 Run examples with: `bun run dev <example-name>`
@@ -254,17 +362,21 @@ Available examples:
 - `streaming` - Real LLM streaming + snapshot self-check ([streaming.ts](examples/streaming.ts))
 - `streaming-with-tools` - Real text streaming with MCP tools + self-check ([streaming-with-tools.ts](examples/streaming-with-tools.ts))
 - `abort-signal` - Start a generation then cancel quickly with `AbortSignal` ([abort-signal.ts](examples/abort-signal.ts))
+- `timeout` - Set per-request and per-tool timeouts via the `timeout` option ([timeout.ts](examples/timeout.ts))
 - `simple` - Basic structured output with streaming ([simple.ts](examples/simple.ts))
 - `sentiment-analysis` - Enum validation, strict mode ([sentiment-analysis.ts](examples/sentiment-analysis.ts))
 - `data-extraction` - Complex nested schemas, self-healing ([data-extraction.ts](examples/data-extraction.ts))
 - `multi-step-reasoning` - Chained structured calls ([multi-step-reasoning.ts](examples/multi-step-reasoning.ts))
 - `calculator-tool` - MCP tool integration ([calculator-tool.ts](examples/calculator-tool.ts))
+- `image-analysis` - Multimodal structured extraction from an image file ([image-analysis.ts](examples/image-analysis.ts))
+- `conversation` - Multi-turn conversation history and inline image messages ([conversation.ts](examples/conversation.ts))
 
 Pass arguments after the example name:
 ```bash
 bun run dev streaming
 bun run dev streaming-with-tools
 bun run dev abort-signal 120 "JSON cancellation demo"
+bun run dev timeout 5000
 bun run dev simple "Bun.js runtime"
 bun run dev sentiment-analysis "I love this product."
 bun run dev multi-step-reasoning "Why is the sky blue?"

package/dist/conversation.d.ts

@@ -0,0 +1,8 @@
+import { type ImageInput } from "./image";
+import type { LLMMessage } from "./types";
+export interface ConversationEntry {
+    role: "user" | "assistant";
+    text: string;
+    images?: ImageInput[];
+}
+export declare function conversation(systemPrompt: string, entries: ConversationEntry[]): LLMMessage[];

package/dist/image.d.ts

@@ -0,0 +1,8 @@
+import type { LLMImageContent } from "./types";
+export interface ImageInput {
+    base64: string;
+    mimeType: string;
+}
+export type ImageSize = "low" | "mid" | "high" | "xhigh" | "raw" | number;
+export declare function images(input: ImageInput | ImageInput[]): LLMImageContent[];
+export declare function resizeImage(source: string | Uint8Array | ArrayBuffer, size: ImageSize, mimeType?: string): Promise<ImageInput>;

package/dist/index.cjs

@@ -45,11 +45,13 @@ __export(exports_src, {
   sanitizeThink: () => sanitizeThink,
   s: () => s,
   resolveSchemaInstruction: () => resolveSchemaInstruction,
+  resizeImage: () => resizeImage,
   registerBuiltinProviders: () => registerBuiltinProviders,
   prompt: () => prompt,
   parseLLMOutput: () => parseLLMOutput,
   inspectSchemaMetadata: () => inspectSchemaMetadata,
   inferSchemaExample: () => inferSchemaExample,
+  images: () => images,
   formatZodIssues: () => formatZodIssues,
   formatPrompt: () => formatPrompt,
   extractMarkdownCodeBlocks: () => extractMarkdownCodeBlocks,
@@ -62,6 +64,7 @@ __export(exports_src, {
   createLLM: () => createLLM,
   createDefaultProviderRegistry: () => createDefaultProviderRegistry,
   createAnthropicCompatibleAdapter: () => createAnthropicCompatibleAdapter,
+  conversation: () => conversation,
   buildSelfHealPrompt: () => buildSelfHealPrompt,
   buildDefaultStructuredPrompt: () => buildDefaultStructuredPrompt,
   StructuredParseError: () => StructuredParseError,
@@ -3927,19 +3930,24 @@ async function structured(adapter, schemaOrOptions, promptInput, callOptions) {
   const resolvedPrompt = applyPromptOutdent(resolvePrompt(normalized.prompt, { mode }), useOutdent);
   const resolvedSystemPrompt = applyOutdentToOptionalPrompt(normalized.systemPrompt, useOutdent);
   const preparedPrompt = prepareStructuredPromptPayload(resolvedPrompt, resolvedSystemPrompt, normalized.schema, normalized.schemaInstruction);
+  const resolvedRequest = normalized.timeout?.tool !== undefined && normalized.request?.mcpClients !== undefined ? {
+    ...normalized.request,
+    mcpClients: applyToolTimeout(normalized.request.mcpClients, normalized.timeout.tool)
+  } : normalized.request;
   const first = await executeAttempt(adapter, {
     prompt: preparedPrompt.prompt,
     messages: preparedPrompt.messages,
     schema: normalized.schema,
     parseOptions,
     stream: streamConfig,
-    request: normalized.request,
+    request: resolvedRequest,
     systemPrompt: preparedPrompt.systemPrompt,
     observe: normalized.observe,
     debug: debugConfig,
     attemptNumber: 1,
     selfHeal: false,
-    selfHealEnabled: selfHealConfig.enabled
+    selfHealEnabled: selfHealConfig.enabled,
+    timeout: normalized.timeout
   });
   attempts.push(first.trace);
   if (first.trace.success) {
@@ -3993,13 +4001,14 @@ async function structured(adapter, schemaOrOptions, promptInput, callOptions) {
       schema: normalized.schema,
       parseOptions,
       stream: streamConfig,
-      request: normalized.request,
+      request: resolvedRequest,
       systemPrompt: preparedPrompt.systemPrompt,
       observe: normalized.observe,
       debug: debugConfig,
       attemptNumber,
       selfHeal: true,
-      selfHealEnabled: selfHealConfig.enabled
+      selfHealEnabled: selfHealConfig.enabled,
+      timeout: normalized.timeout
     });
     attempts.push(healed.trace);
     if (healed.trace.success) {
@@ -4131,6 +4140,19 @@ function injectStructuredFormatIntoMessages(messages, schema, schemaInstruction)
     throw new Error("Structured prompts with messages must include at least one user message.");
   }
   const target = messages[lastUserIndex];
+  if (Array.isArray(target?.content)) {
+    const parts = target.content;
+    const textIndex = parts.findIndex((p) => p.type === "text");
+    const existingText = textIndex !== -1 ? (parts[textIndex]?.text ?? "").trim() : "";
+    const formatted2 = shouldInjectFormat(existingText, schemaInstruction) ? formatPrompt(schema, existingText, { schemaInstruction }) : existingText;
+    let newParts;
+    if (textIndex !== -1) {
+      newParts = parts.map((p, i) => i === textIndex ? { ...p, text: formatted2 } : p);
+    } else {
+      newParts = [{ type: "text", text: formatted2 }, ...parts];
+    }
+    return messages.map((message, index) => index === lastUserIndex ? { ...message, content: newParts } : message);
+  }
   const content = typeof target?.content === "string" ? target.content.trim() : stringifyPromptContent(target?.content);
   const formatted = shouldInjectFormat(content, schemaInstruction) ? formatPrompt(schema, content, { schemaInstruction }) : content.trim();
   return messages.map((message, index) => index === lastUserIndex ? {
@@ -4345,7 +4367,8 @@ async function executeAttempt(adapter, input) {
     debug: input.debug,
     attempt: input.attemptNumber,
     selfHeal: input.selfHeal,
-    selfHealEnabled: input.selfHealEnabled
+    selfHealEnabled: input.selfHealEnabled,
+    timeout: input.timeout
   });
   const parsed = parseWithObserve(response.text, input.schema, input.parseOptions, {
     observe: input.observe,
@@ -4372,7 +4395,29 @@ async function executeAttempt(adapter, input) {
     trace
   };
 }
+function withToolTimeout(client, toolTimeoutMs) {
+  return {
+    id: client.id,
+    listTools: client.listTools.bind(client),
+    close: client.close?.bind(client),
+    async callTool(params) {
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`Tool call timed out after ${toolTimeoutMs}ms`)), toolTimeoutMs);
+      });
+      try {
+        return await Promise.race([client.callTool(params), timeoutPromise]);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  };
+}
+function applyToolTimeout(clients, toolTimeoutMs) {
+  return clients.map((client) => withToolTimeout(client, toolTimeoutMs));
+}
 async function callModel(adapter, options) {
+  const requestSignal = options.request?.signal ?? (options.timeout?.request !== undefined ? AbortSignal.timeout(options.timeout.request) : undefined);
   const requestPayload = {
     prompt: options.prompt,
     messages: options.messages,
@@ -4386,7 +4431,7 @@ async function callModel(adapter, options) {
     onToolExecution: options.request?.onToolExecution,
     toolDebug: options.request?.toolDebug,
     body: options.request?.body,
-    signal: options.request?.signal
+    signal: requestSignal
   };
   emitDebugRequest(options.debug, {
     provider: adapter.provider,
@@ -4769,7 +4814,8 @@ function mergeStructuredOptions(defaults, overrides) {
     },
     stream: mergeObjectLike(defaults?.stream, overrides?.stream),
     selfHeal: mergeObjectLike(defaults?.selfHeal, overrides?.selfHeal),
-    debug: mergeObjectLike(defaults?.debug, overrides?.debug)
+    debug: mergeObjectLike(defaults?.debug, overrides?.debug),
+    timeout: mergeObjectLike(defaults?.timeout, overrides?.timeout)
   };
 }
 function mergeObjectLike(defaults, overrides) {
@@ -4858,6 +4904,63 @@ function toImplementation(clientInfo) {
     version: clientInfo?.version ?? "0.1.0"
   };
 }
+// src/image.ts
+var import_path = require("path");
+var IMAGE_SIZE_MAP = {
+  low: 256,
+  mid: 512,
+  high: 1024,
+  xhigh: 1280
+};
+var IMAGE_MIME_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp"
+};
+var MIME_TO_SHARP_FORMAT = {
+  "image/jpeg": "jpeg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif"
+};
+function images(input) {
+  const inputs = Array.isArray(input) ? input : [input];
+  return inputs.map(({ base64, mimeType }) => ({
+    type: "image_url",
+    image_url: { url: `data:${mimeType};base64,${base64}` }
+  }));
+}
+async function resizeImage(source, size, mimeType) {
+  const resolvedMime = mimeType ?? (typeof source === "string" ? IMAGE_MIME_TYPES[import_path.extname(source).toLowerCase()] ?? "image/jpeg" : "image/jpeg");
+  let sharp;
+  try {
+    sharp = (await import("sharp")).default;
+  } catch {
+    throw new Error('resizeImage() requires "sharp" to be installed. Run: bun add sharp');
+  }
+  const input = source instanceof ArrayBuffer ? Buffer.from(source) : source;
+  let img = sharp(input);
+  if (size !== "raw") {
+    const targetPx = typeof size === "number" ? size : IMAGE_SIZE_MAP[size];
+    img = img.resize(targetPx, targetPx, { fit: "inside", withoutEnlargement: true });
+  }
+  const sharpFormat = MIME_TO_SHARP_FORMAT[resolvedMime] ?? "jpeg";
+  const outputMime = MIME_TO_SHARP_FORMAT[resolvedMime] ? resolvedMime : "image/jpeg";
+  const buf = await img.toFormat(sharpFormat).toBuffer();
+  return { base64: buf.toString("base64"), mimeType: outputMime };
+}
+// src/conversation.ts
+function conversation(systemPrompt, entries) {
+  return [
+    { role: "system", content: systemPrompt },
+    ...entries.map((entry) => ({
+      role: entry.role,
+      content: entry.images && entry.images.length > 0 ? [{ type: "text", text: entry.text }, ...images(entry.images)] : entry.text
+    }))
+  ];
+}
 // src/prompt.ts
 function toPromptString(value) {
   if (value === null || value === undefined) {
@@ -4932,6 +5035,12 @@ class PromptMessageBuilderImpl {
     return this.pushMessage("assistant", input, values);
   }
   pushMessage(role, input, values) {
+    if (Array.isArray(input) && !isTemplateStringsArray(input)) {
+      if (input.length > 0) {
+        this.messages.push({ role, content: input });
+      }
+      return this;
+    }
     const message = toPromptMessage(input, values);
     if (message.length > 0) {
       this.messages.push({ role, content: message });

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export { sanitizeThink } from "./think";
 export { createLLM, type CreateLLMOptions, type LLMClient } from "./llm";
 export { formatZodIssues, parseLLMOutput } from "./parse";
 export { createMCPClient, wrapMCPClient, type CreateMCPClientOptions, type MCPClientInfo, type MCPInMemoryTransportConfig, type MCPStdioTransportConfig, type MCPStreamableHTTPTransportConfig, type MCPTransportConfig, type ManagedMCPToolClient, } from "./mcp";
+export { images, resizeImage, type ImageInput, type ImageSize } from "./image";
+export { conversation, type ConversationEntry } from "./conversation";
 export { prompt, type PromptMessageBuilder } from "./prompt";
 export { s, inspectSchemaMetadata, inferSchemaExample } from "./schema-builder";
 export { buildDefaultStructuredPrompt, DEFAULT_LOOSE_PARSE_OPTIONS, DEFAULT_SELF_HEAL_BY_MODE, DEFAULT_SELF_HEAL_CONTEXT_LABEL, DEFAULT_SELF_HEAL_FIX_INSTRUCTION, DEFAULT_SELF_HEAL_MAX_CONTEXT_CHARS, DEFAULT_SELF_HEAL_NO_ISSUES_MESSAGE, DEFAULT_SELF_HEAL_PROTOCOL, DEFAULT_SELF_HEAL_RAW_OUTPUT_LABEL, DEFAULT_SELF_HEAL_RETURN_INSTRUCTION, DEFAULT_SELF_HEAL_STOP_ON_NO_PROGRESS, DEFAULT_SELF_HEAL_VALIDATION_LABEL, DEFAULT_STRICT_PARSE_OPTIONS, DEFAULT_STRUCTURED_OBJECT_INSTRUCTION, DEFAULT_STRUCTURED_STYLE_INSTRUCTION, buildSelfHealPrompt, structured, StructuredParseError, type BuildDefaultStructuredPromptOptions, type SelfHealPromptTextOptions, } from "./structured";
@@ -12,4 +14,4 @@ export { createOpenAICompatibleAdapter, type OpenAICompatibleAdapterOptions, } f
 export { createAnthropicCompatibleAdapter, DEFAULT_ANTHROPIC_MAX_TOKENS, DEFAULT_ANTHROPIC_VERSION, type AnthropicCompatibleAdapterOptions, } from "./providers/anthropic-compatible";
 export { DEFAULT_MAX_TOOL_ROUNDS } from "./providers/mcp-runtime";
 export { createDefaultProviderRegistry, createModelAdapter, createProviderRegistry, registerBuiltinProviders, type BuiltinProviderKind, type ModelAdapterConfig, type ProviderFactory, type ProviderRegistry, type ProviderTransportConfig, } from "./providers/registry";
-export type { CandidateDiagnostics, ExtractJsonCandidatesOptions, ExtractionCandidate, ExtractionHeuristicsOptions, ExtractionParseHint, HTTPHeaders, LLMAdapter, LLMMessage, LLMRequest, LLMResponse, LLMStreamCallbacks, LLMStreamChunk, LLMToolCall, LLMToolDebugOptions, LLMToolExecution, LLMToolOutputTransformer, LLMToolArgumentsTransformer, LLMToolChoice, MCPCallToolParams, MCPListToolsResult, MCPToolClient, MCPToolDescriptor, MCPToolSchema, LLMUsage, MarkdownCodeBlock, MarkdownCodeOptions, ParseLLMOutputOptions, ParseLLMOutputResult, ParseTraceEvent, PipelineError, StructuredAttempt, StructuredCallOptions, StructuredDebugOptions, StructuredError, StructuredMode, StructuredOptions, StructuredPromptBuilder, StructuredPromptContext, StructuredPromptPayload, StructuredPromptResolver, StructuredPromptValue, StructuredResult, StructuredStreamData, StructuredStreamEvent, StructuredStreamInput, StructuredStreamOptions, StructuredSelfHealInput, ThinkDiagnostics, ThinkBlock, StructuredTraceEvent, } from "./types";
+export type { CandidateDiagnostics, LLMImageContent, LLMMessageContent, LLMTextContent, ExtractJsonCandidatesOptions, ExtractionCandidate, ExtractionHeuristicsOptions, ExtractionParseHint, HTTPHeaders, LLMAdapter, LLMMessage, LLMRequest, LLMResponse, LLMStreamCallbacks, LLMStreamChunk, LLMToolCall, LLMToolDebugOptions, LLMToolExecution, LLMToolOutputTransformer, LLMToolArgumentsTransformer, LLMToolChoice, MCPCallToolParams, MCPListToolsResult, MCPToolClient, MCPToolDescriptor, MCPToolSchema, LLMUsage, MarkdownCodeBlock, MarkdownCodeOptions, ParseLLMOutputOptions, ParseLLMOutputResult, ParseTraceEvent, PipelineError, StructuredAttempt, StructuredCallOptions, StructuredDebugOptions, StructuredError, StructuredMode, StructuredOptions, StructuredPromptBuilder, StructuredPromptContext, StructuredPromptPayload, StructuredPromptResolver, StructuredPromptValue, StructuredResult, StructuredStreamData, StructuredStreamEvent, StructuredStreamInput, StructuredStreamOptions, StructuredSelfHealInput, StructuredTimeoutOptions, ThinkDiagnostics, ThinkBlock, StructuredTraceEvent, } from "./types";

package/dist/index.js

@@ -1,3 +1,6 @@
+import { createRequire } from "node:module";
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
 // src/extract.ts
 import { jsonrepair } from "jsonrepair";
 
@@ -3838,19 +3841,24 @@ async function structured(adapter, schemaOrOptions, promptInput, callOptions) {
   const resolvedPrompt = applyPromptOutdent(resolvePrompt(normalized.prompt, { mode }), useOutdent);
   const resolvedSystemPrompt = applyOutdentToOptionalPrompt(normalized.systemPrompt, useOutdent);
   const preparedPrompt = prepareStructuredPromptPayload(resolvedPrompt, resolvedSystemPrompt, normalized.schema, normalized.schemaInstruction);
+  const resolvedRequest = normalized.timeout?.tool !== undefined && normalized.request?.mcpClients !== undefined ? {
+    ...normalized.request,
+    mcpClients: applyToolTimeout(normalized.request.mcpClients, normalized.timeout.tool)
+  } : normalized.request;
   const first = await executeAttempt(adapter, {
     prompt: preparedPrompt.prompt,
     messages: preparedPrompt.messages,
     schema: normalized.schema,
     parseOptions,
     stream: streamConfig,
-    request: normalized.request,
+    request: resolvedRequest,
     systemPrompt: preparedPrompt.systemPrompt,
     observe: normalized.observe,
     debug: debugConfig,
     attemptNumber: 1,
     selfHeal: false,
-    selfHealEnabled: selfHealConfig.enabled
+    selfHealEnabled: selfHealConfig.enabled,
+    timeout: normalized.timeout
   });
   attempts.push(first.trace);
   if (first.trace.success) {
@@ -3904,13 +3912,14 @@ async function structured(adapter, schemaOrOptions, promptInput, callOptions) {
       schema: normalized.schema,
       parseOptions,
       stream: streamConfig,
-      request: normalized.request,
+      request: resolvedRequest,
       systemPrompt: preparedPrompt.systemPrompt,
       observe: normalized.observe,
       debug: debugConfig,
       attemptNumber,
       selfHeal: true,
-      selfHealEnabled: selfHealConfig.enabled
+      selfHealEnabled: selfHealConfig.enabled,
+      timeout: normalized.timeout
     });
     attempts.push(healed.trace);
     if (healed.trace.success) {
@@ -4042,6 +4051,19 @@ function injectStructuredFormatIntoMessages(messages, schema, schemaInstruction)
     throw new Error("Structured prompts with messages must include at least one user message.");
   }
   const target = messages[lastUserIndex];
+  if (Array.isArray(target?.content)) {
+    const parts = target.content;
+    const textIndex = parts.findIndex((p) => p.type === "text");
+    const existingText = textIndex !== -1 ? (parts[textIndex]?.text ?? "").trim() : "";
+    const formatted2 = shouldInjectFormat(existingText, schemaInstruction) ? formatPrompt(schema, existingText, { schemaInstruction }) : existingText;
+    let newParts;
+    if (textIndex !== -1) {
+      newParts = parts.map((p, i) => i === textIndex ? { ...p, text: formatted2 } : p);
+    } else {
+      newParts = [{ type: "text", text: formatted2 }, ...parts];
+    }
+    return messages.map((message, index) => index === lastUserIndex ? { ...message, content: newParts } : message);
+  }
   const content = typeof target?.content === "string" ? target.content.trim() : stringifyPromptContent(target?.content);
   const formatted = shouldInjectFormat(content, schemaInstruction) ? formatPrompt(schema, content, { schemaInstruction }) : content.trim();
   return messages.map((message, index) => index === lastUserIndex ? {
@@ -4256,7 +4278,8 @@ async function executeAttempt(adapter, input) {
     debug: input.debug,
     attempt: input.attemptNumber,
     selfHeal: input.selfHeal,
-    selfHealEnabled: input.selfHealEnabled
+    selfHealEnabled: input.selfHealEnabled,
+    timeout: input.timeout
   });
   const parsed = parseWithObserve(response.text, input.schema, input.parseOptions, {
     observe: input.observe,
@@ -4283,7 +4306,29 @@ async function executeAttempt(adapter, input) {
     trace
   };
 }
+function withToolTimeout(client, toolTimeoutMs) {
+  return {
+    id: client.id,
+    listTools: client.listTools.bind(client),
+    close: client.close?.bind(client),
+    async callTool(params) {
+      let timeoutId;
+      const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(`Tool call timed out after ${toolTimeoutMs}ms`)), toolTimeoutMs);
+      });
+      try {
+        return await Promise.race([client.callTool(params), timeoutPromise]);
+      } finally {
+        clearTimeout(timeoutId);
+      }
+    }
+  };
+}
+function applyToolTimeout(clients, toolTimeoutMs) {
+  return clients.map((client) => withToolTimeout(client, toolTimeoutMs));
+}
 async function callModel(adapter, options) {
+  const requestSignal = options.request?.signal ?? (options.timeout?.request !== undefined ? AbortSignal.timeout(options.timeout.request) : undefined);
   const requestPayload = {
     prompt: options.prompt,
     messages: options.messages,
@@ -4297,7 +4342,7 @@ async function callModel(adapter, options) {
     onToolExecution: options.request?.onToolExecution,
     toolDebug: options.request?.toolDebug,
     body: options.request?.body,
-    signal: options.request?.signal
+    signal: requestSignal
   };
   emitDebugRequest(options.debug, {
     provider: adapter.provider,
@@ -4680,7 +4725,8 @@ function mergeStructuredOptions(defaults, overrides) {
     },
     stream: mergeObjectLike(defaults?.stream, overrides?.stream),
     selfHeal: mergeObjectLike(defaults?.selfHeal, overrides?.selfHeal),
-    debug: mergeObjectLike(defaults?.debug, overrides?.debug)
+    debug: mergeObjectLike(defaults?.debug, overrides?.debug),
+    timeout: mergeObjectLike(defaults?.timeout, overrides?.timeout)
   };
 }
 function mergeObjectLike(defaults, overrides) {
@@ -4773,6 +4819,63 @@ function toImplementation(clientInfo) {
     version: clientInfo?.version ?? "0.1.0"
   };
 }
+// src/image.ts
+import { extname } from "path";
+var IMAGE_SIZE_MAP = {
+  low: 256,
+  mid: 512,
+  high: 1024,
+  xhigh: 1280
+};
+var IMAGE_MIME_TYPES = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp"
+};
+var MIME_TO_SHARP_FORMAT = {
+  "image/jpeg": "jpeg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif"
+};
+function images(input) {
+  const inputs = Array.isArray(input) ? input : [input];
+  return inputs.map(({ base64, mimeType }) => ({
+    type: "image_url",
+    image_url: { url: `data:${mimeType};base64,${base64}` }
+  }));
+}
+async function resizeImage(source, size, mimeType) {
+  const resolvedMime = mimeType ?? (typeof source === "string" ? IMAGE_MIME_TYPES[extname(source).toLowerCase()] ?? "image/jpeg" : "image/jpeg");
+  let sharp;
+  try {
+    sharp = (await import("sharp")).default;
+  } catch {
+    throw new Error('resizeImage() requires "sharp" to be installed. Run: bun add sharp');
+  }
+  const input = source instanceof ArrayBuffer ? Buffer.from(source) : source;
+  let img = sharp(input);
+  if (size !== "raw") {
+    const targetPx = typeof size === "number" ? size : IMAGE_SIZE_MAP[size];
+    img = img.resize(targetPx, targetPx, { fit: "inside", withoutEnlargement: true });
+  }
+  const sharpFormat = MIME_TO_SHARP_FORMAT[resolvedMime] ?? "jpeg";
+  const outputMime = MIME_TO_SHARP_FORMAT[resolvedMime] ? resolvedMime : "image/jpeg";
+  const buf = await img.toFormat(sharpFormat).toBuffer();
+  return { base64: buf.toString("base64"), mimeType: outputMime };
+}
+// src/conversation.ts
+function conversation(systemPrompt, entries) {
+  return [
+    { role: "system", content: systemPrompt },
+    ...entries.map((entry) => ({
+      role: entry.role,
+      content: entry.images && entry.images.length > 0 ? [{ type: "text", text: entry.text }, ...images(entry.images)] : entry.text
+    }))
+  ];
+}
 // src/prompt.ts
 function toPromptString(value) {
   if (value === null || value === undefined) {
@@ -4847,6 +4950,12 @@ class PromptMessageBuilderImpl {
     return this.pushMessage("assistant", input, values);
   }
   pushMessage(role, input, values) {
+    if (Array.isArray(input) && !isTemplateStringsArray(input)) {
+      if (input.length > 0) {
+        this.messages.push({ role, content: input });
+      }
+      return this;
+    }
     const message = toPromptMessage(input, values);
     if (message.length > 0) {
       this.messages.push({ role, content: message });
@@ -5058,11 +5167,13 @@ export {
   sanitizeThink,
   s,
   resolveSchemaInstruction,
+  resizeImage,
   registerBuiltinProviders,
   prompt,
   parseLLMOutput,
   inspectSchemaMetadata,
   inferSchemaExample,
+  images,
   formatZodIssues,
   formatPrompt,
   extractMarkdownCodeBlocks,
@@ -5075,6 +5186,7 @@ export {
   createLLM,
   createDefaultProviderRegistry,
   createAnthropicCompatibleAdapter,
+  conversation,
   buildSelfHealPrompt,
   buildDefaultStructuredPrompt,
   StructuredParseError,

package/dist/prompt.d.ts

@@ -1,11 +1,13 @@
-import type { StructuredPromptPayload, StructuredPromptResolver } from "./types";
+import type { LLMMessageContent, StructuredPromptPayload, StructuredPromptResolver } from "./types";
 export interface PromptMessageBuilder extends StructuredPromptResolver {
     system(input: string): PromptMessageBuilder;
     system(strings: TemplateStringsArray, ...values: unknown[]): PromptMessageBuilder;
     user(input: string): PromptMessageBuilder;
     user(strings: TemplateStringsArray, ...values: unknown[]): PromptMessageBuilder;
+    user(content: LLMMessageContent): PromptMessageBuilder;
     assistant(input: string): PromptMessageBuilder;
     assistant(strings: TemplateStringsArray, ...values: unknown[]): PromptMessageBuilder;
+    assistant(content: LLMMessageContent): PromptMessageBuilder;
     build(): StructuredPromptPayload;
 }
 export declare function prompt(strings: TemplateStringsArray, ...values: unknown[]): string;

package/dist/types.d.ts

@@ -119,9 +119,20 @@ export interface MCPToolClient {
     callTool(params: MCPCallToolParams): Promise<unknown>;
     close?(): Promise<void>;
 }
+export interface LLMTextContent {
+    type: "text";
+    text: string;
+}
+export interface LLMImageContent {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export type LLMMessageContent = string | (LLMTextContent | LLMImageContent)[];
 export interface LLMMessage {
     role: "system" | "user" | "assistant" | "tool";
-    content: unknown;
+    content: LLMMessageContent;
 }
 export interface LLMRequest {
     prompt?: string;
@@ -250,6 +261,12 @@ export interface StructuredSelfHealOptions {
     maxContextChars?: number;
 }
 export type StructuredSelfHealInput = boolean | number | StructuredSelfHealOptions;
+export interface StructuredTimeoutOptions {
+    /** Timeout in ms for each LLM HTTP request. Creates an AbortSignal.timeout internally if no signal is already provided. */
+    request?: number;
+    /** Timeout in ms for each MCP tool call. */
+    tool?: number;
+}
 export type StructuredStreamData<T> = T extends Array<infer TItem> ? Array<StructuredStreamData<TItem>> : T extends object ? {
     [K in keyof T]?: StructuredStreamData<T[K]> | null;
 } : T | null;
@@ -277,6 +294,7 @@ export interface StructuredCallOptions<TSchema extends z.ZodTypeAny> {
     systemPrompt?: string;
     request?: Omit<LLMRequest, "prompt" | "systemPrompt" | "messages">;
     schemaInstruction?: string;
+    timeout?: StructuredTimeoutOptions;
 }
 export interface StructuredOptions<TSchema extends z.ZodTypeAny> extends StructuredCallOptions<TSchema> {
     schema: TSchema;

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "extrait",
-  "version": "0.5.1",
-  "license": "MIT",
+  "version": "0.5.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tterrasson/extrait.git"
   },
-  "bugs": {
-    "url": "https://github.com/tterrasson/extrait/issues"
-  },
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "jsonrepair": "^3.13.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.10",
+    "@types/sharp": "^0.32.0",
+    "typescript": "^5.9.3"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -20,12 +25,29 @@
       "default": "./dist/index.js"
     }
   },
+  "bugs": {
+    "url": "https://github.com/tterrasson/extrait/issues"
+  },
   "files": [
     "dist",
     "README.md",
     "LICENSE"
   ],
-  "type": "module",
+  "license": "MIT",
+  "overrides": {
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "sharp": "^0.34.5"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
+  "resolutions": {
+    "zod": "^4.3.6"
+  },
   "scripts": {
     "dev": "bun run examples/runner.ts",
     "build": "bun run build:esm && bun run build:cjs",
@@ -38,19 +60,6 @@
     "typecheck": "bunx tsc --noEmit",
     "pack": "bun run build:types && bun run build && npm pack"
   },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "jsonrepair": "^3.13.2",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@types/bun": "^1.3.10",
-    "typescript": "^5.9.3"
-  },
-  "overrides": {
-    "zod": "^4.3.6"
-  },
-  "resolutions": {
-    "zod": "^4.3.6"
-  }
+  "type": "module",
+  "types": "./dist/index.d.ts"
 }