extrait 0.5.2 → 0.5.3

package/README.md

@@ -175,19 +175,27 @@ const result = await llm.structured(
 Use `images()` to build base64 image content blocks for vision-capable models.
 
 ```typescript
-import { images } from "extrait";
+import { images, prompt } from "extrait";
 import { readFileSync } from "fs";
 
 const base64 = readFileSync("photo.png").toString("base64");
+const img = { base64, mimeType: "image/png" };
 
-// Single image
+// 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({ base64, mimeType: "image/png" }),
+        ...images(img),
       ],
     },
   ],
@@ -205,6 +213,38 @@ const content = [
 
 `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
 
 ```typescript
@@ -329,6 +369,7 @@ Available examples:
 - `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

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/index.cjs

@@ -64,6 +64,7 @@ __export(exports_src, {
   createLLM: () => createLLM,
   createDefaultProviderRegistry: () => createDefaultProviderRegistry,
   createAnthropicCompatibleAdapter: () => createAnthropicCompatibleAdapter,
+  conversation: () => conversation,
   buildSelfHealPrompt: () => buildSelfHealPrompt,
   buildDefaultStructuredPrompt: () => buildDefaultStructuredPrompt,
   StructuredParseError: () => StructuredParseError,
@@ -4950,6 +4951,16 @@ async function resizeImage(source, size, mimeType) {
   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) {
@@ -5024,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

@@ -6,6 +6,7 @@ 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";

package/dist/index.js

@@ -4866,6 +4866,16 @@ async function resizeImage(source, size, mimeType) {
   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) {
@@ -4940,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 });
@@ -5170,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extrait",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tterrasson/extrait.git"