extrait 0.4.0 → 0.5.2

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
   },
 });
 ```
@@ -128,6 +129,16 @@ const result = await llm.structured(
     .user`Analyze: """${input}"""`
 );
 
+// Multi-turn conversation
+const conversationResult = await llm.structured(
+  Schema,
+  prompt()
+    .system`You are an expert assistant.`
+    .user`Hello`
+    .assistant`Hi, how can I help?`
+    .user`Analyze: """${input}"""`
+);
+
 // With options
 const result = await llm.structured(
   Schema,
@@ -136,6 +147,7 @@ const result = await llm.structured(
     mode: "loose",
     selfHeal: 1,
     debug: true,
+    systemPrompt: "You are a helpful assistant.",
     stream: {
       to: "stdout",
       onData: (event) => {
@@ -145,10 +157,54 @@ 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.
+
+### Images (multimodal)
+
+Use `images()` to build base64 image content blocks for vision-capable models.
+
+```typescript
+import { images } from "extrait";
+import { readFileSync } from "fs";
+
+const base64 = readFileSync("photo.png").toString("base64");
+
+// Single image
+const result = await llm.structured(Schema, {
+  messages: [
+    {
+      role: "user",
+      content: [
+        { type: "text", text: "Describe this image." },
+        ...images({ base64, mimeType: "image/png" }),
+      ],
+    },
+  ],
+});
+
+// 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.
+
 ### Result Object
 
 ```typescript
@@ -219,6 +275,10 @@ const result = await llm.structured(
       transformToolOutput: (output, execution) => {
         return { ...output, source: execution.name };
       },
+      // Optional: transform tool arguments before the tool is called
+      transformToolArguments: (args, call) => args,
+      // Optional: custom error message when an unknown tool is called
+      unknownToolError: (toolName) => `Tool "${toolName}" is not available.`,
     },
   }
 );
@@ -226,6 +286,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>`
@@ -234,17 +322,20 @@ 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))
 
 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/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>;