extrait 0.5.3 → 0.5.4

package/README.md

@@ -15,6 +15,7 @@ Structured JSON extraction from LLMs with validation, repair, and streaming.
 - Optional self-healing for validation failures
 - Streaming support
 - MCP tools
+- Vector embeddings (OpenAI-compatible + Voyage AI)
 
 ## Installation
 
@@ -282,6 +283,64 @@ try {
 }
 ```
 
+### Embeddings
+
+Generate vector embeddings using `llm.embed()`. It always returns `number[][]` — one vector per input string.
+
+```typescript
+// Create a dedicated embedder client (recommended)
+const embedder = createLLM({
+  provider: "openai-compatible",
+  model: "text-embedding-3-small",
+  transport: { apiKey: process.env.OPENAI_API_KEY },
+});
+
+// Single string
+const { embeddings, model, usage } = await embedder.embed("Hello world");
+const vector: number[] = embeddings[0];
+
+// Multiple strings in one request
+const { embeddings } = await embedder.embed(["text one", "text two", "text three"]);
+// embeddings[0], embeddings[1], embeddings[2] — one vector each
+
+// Optional: override model or request extra options per call
+const { embeddings } = await embedder.embed("Hello", {
+  model: "text-embedding-ada-002",
+  dimensions: 512,              // supported by text-embedding-3-* models
+  body: { user: "user-id" },    // pass-through to provider
+});
+```
+
+**Result shape:**
+
+```typescript
+{
+  embeddings: number[][];  // one vector per input
+  model: string;
+  usage?: { inputTokens?: number; totalTokens?: number };
+  raw?: unknown;           // full provider response
+}
+```
+
+**Anthropic / Voyage AI**
+
+Anthropic does not provide a native embedding API. Their recommended solution is [Voyage AI](https://api.voyageai.com), which uses the same OpenAI-compatible format:
+
+```typescript
+const embedder = createLLM({
+  provider: "openai-compatible",
+  model: "voyage-3",
+  transport: {
+    baseURL: "https://api.voyageai.com",
+    apiKey: process.env.VOYAGE_API_KEY,
+  },
+});
+
+const { embeddings } = await embedder.embed(["query", "document"]);
+```
+
+Calling `llm.embed()` on an `anthropic-compatible` adapter throws a descriptive error pointing to Voyage AI.
+
 ### MCP Tools
 
 ```typescript
@@ -370,6 +429,7 @@ Available examples:
 - `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))
+- `embeddings` - Vector embeddings, cosine similarity, and semantic comparison ([embeddings.ts](examples/embeddings.ts))
 
 Pass arguments after the example name:
 ```bash
@@ -380,6 +440,7 @@ 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?"
+bun run dev embeddings "the cat sat on the mat" "a feline rested on the rug"
 ```
 
 ## Environment Variables

package/dist/conversation.d.ts

@@ -1,8 +1,21 @@
 import { type ImageInput } from "./image";
 import type { LLMMessage } from "./types";
-export interface ConversationEntry {
-    role: "user" | "assistant";
+export type ConversationEntry = {
+    role: "user";
     text: string;
     images?: ImageInput[];
-}
+} | {
+    role: "assistant";
+    text: string;
+    images?: ImageInput[];
+} | {
+    role: "tool_call";
+    id: string;
+    name: string;
+    arguments?: Record<string, unknown>;
+} | {
+    role: "tool_result";
+    id: string;
+    output: unknown;
+};
 export declare function conversation(systemPrompt: string, entries: ConversationEntry[]): LLMMessage[];

package/dist/index.cjs

@@ -1606,6 +1606,7 @@ function createOpenAICompatibleAdapter(options) {
   const fetcher = options.fetcher ?? fetch;
   const path = options.path ?? "/v1/chat/completions";
   const responsesPath = options.responsesPath ?? "/v1/responses";
+  const embeddingPath = options.embeddingPath ?? "/v1/embeddings";
   return {
     provider: "openai-compatible",
     model: options.model,
@@ -1678,6 +1679,36 @@ function createOpenAICompatibleAdapter(options) {
       const out = { text, usage, finishReason };
       callbacks.onComplete?.(out);
       return out;
+    },
+    async embed(request) {
+      const body = cleanUndefined({
+        ...options.defaultBody,
+        ...request.body,
+        model: request.model ?? options.model,
+        input: request.input,
+        dimensions: request.dimensions,
+        encoding_format: "float"
+      });
+      const response = await fetcher(buildURL(options.baseURL, embeddingPath), {
+        method: "POST",
+        headers: buildHeaders(options),
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const message = await response.text();
+        throw new Error(`HTTP ${response.status}: ${message}`);
+      }
+      const json = await response.json();
+      const data = json.data;
+      if (!Array.isArray(data)) {
+        throw new Error("Unexpected embedding response: missing data array");
+      }
+      return {
+        embeddings: data.map((d) => isRecord2(d) && Array.isArray(d.embedding) ? d.embedding : []),
+        model: pickString(json.model) ?? body.model,
+        usage: pickUsage(json),
+        raw: json
+      };
     }
   };
 }
@@ -2266,10 +2297,7 @@ function buildResponsesInput(request) {
   return buildMessages(request);
 }
 function toOpenAIMessage(message) {
-  return {
-    role: message.role,
-    content: message.content
-  };
+  return { ...message };
 }
 function toResponsesTools(tools) {
   if (!Array.isArray(tools) || tools.length === 0) {
@@ -2737,6 +2765,9 @@ function createAnthropicCompatibleAdapter(options) {
       const out = { text, usage, finishReason };
       callbacks.onComplete?.(out);
       return out;
+    },
+    async embed() {
+      throw new Error("Anthropic does not provide a native embedding API. " + "Use the openai-compatible provider with Voyage AI (https://api.voyageai.com) — " + "Anthropic's recommended embedding solution, which uses the same request format.");
     }
   };
 }
@@ -3015,6 +3046,23 @@ function toAnthropicInput(messages) {
       continue;
     }
     sawNonSystem = true;
+    if (message.role === "assistant" && Array.isArray(message.tool_calls)) {
+      const parts = [];
+      if (message.content)
+        parts.push({ type: "text", text: message.content });
+      for (const tc of message.tool_calls) {
+        parts.push({ type: "tool_use", id: tc.id, name: tc.function.name, input: JSON.parse(tc.function.arguments) });
+      }
+      normalizedMessages.push({ role: "assistant", content: parts });
+      continue;
+    }
+    if (message.role === "tool") {
+      normalizedMessages.push({
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: message.tool_call_id, content: message.content }]
+      });
+      continue;
+    }
     normalizedMessages.push({
       role: message.role,
       content: message.content
@@ -4794,6 +4842,12 @@ function createLLM(config, registry = createDefaultProviderRegistry()) {
     async structured(schema, prompt, options) {
       const merged = mergeStructuredOptions(defaults, options);
       return structured(adapter, schema, prompt, merged);
+    },
+    async embed(input, options = {}) {
+      if (!adapter.embed) {
+        throw new Error(`Provider "${adapter.provider ?? "unknown"}" does not support embeddings.`);
+      }
+      return adapter.embed({ ...options, input });
     }
   };
 }
@@ -4955,10 +5009,32 @@ async function resizeImage(source, size, mimeType) {
 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
-    }))
+    ...entries.map((entry) => {
+      if (entry.role === "tool_call") {
+        return {
+          role: "assistant",
+          content: "",
+          tool_calls: [
+            {
+              id: entry.id,
+              type: "function",
+              function: { name: entry.name, arguments: JSON.stringify(entry.arguments ?? {}) }
+            }
+          ]
+        };
+      }
+      if (entry.role === "tool_result") {
+        return {
+          role: "tool",
+          content: typeof entry.output === "string" ? entry.output : JSON.stringify(entry.output),
+          tool_call_id: entry.id
+        };
+      }
+      return {
+        role: entry.role,
+        content: entry.images && entry.images.length > 0 ? [{ type: "text", text: entry.text }, ...images(entry.images)] : entry.text
+      };
+    })
   ];
 }
 // src/prompt.ts

package/dist/index.d.ts

@@ -14,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, 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";
+export type { CandidateDiagnostics, EmbeddingRequest, EmbeddingResult, LLMImageContent, LLMMessageContent, LLMTextContent, ExtractJsonCandidatesOptions, ExtractionCandidate, ExtractionHeuristicsOptions, ExtractionParseHint, HTTPHeaders, LLMAdapter, LLMMessage, LLMRequest, LLMResponse, LLMStreamCallbacks, LLMStreamChunk, LLMToolCall, LLMToolCallRef, 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

@@ -1517,6 +1517,7 @@ function createOpenAICompatibleAdapter(options) {
   const fetcher = options.fetcher ?? fetch;
   const path = options.path ?? "/v1/chat/completions";
   const responsesPath = options.responsesPath ?? "/v1/responses";
+  const embeddingPath = options.embeddingPath ?? "/v1/embeddings";
   return {
     provider: "openai-compatible",
     model: options.model,
@@ -1589,6 +1590,36 @@ function createOpenAICompatibleAdapter(options) {
       const out = { text, usage, finishReason };
       callbacks.onComplete?.(out);
       return out;
+    },
+    async embed(request) {
+      const body = cleanUndefined({
+        ...options.defaultBody,
+        ...request.body,
+        model: request.model ?? options.model,
+        input: request.input,
+        dimensions: request.dimensions,
+        encoding_format: "float"
+      });
+      const response = await fetcher(buildURL(options.baseURL, embeddingPath), {
+        method: "POST",
+        headers: buildHeaders(options),
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const message = await response.text();
+        throw new Error(`HTTP ${response.status}: ${message}`);
+      }
+      const json = await response.json();
+      const data = json.data;
+      if (!Array.isArray(data)) {
+        throw new Error("Unexpected embedding response: missing data array");
+      }
+      return {
+        embeddings: data.map((d) => isRecord2(d) && Array.isArray(d.embedding) ? d.embedding : []),
+        model: pickString(json.model) ?? body.model,
+        usage: pickUsage(json),
+        raw: json
+      };
     }
   };
 }
@@ -2177,10 +2208,7 @@ function buildResponsesInput(request) {
   return buildMessages(request);
 }
 function toOpenAIMessage(message) {
-  return {
-    role: message.role,
-    content: message.content
-  };
+  return { ...message };
 }
 function toResponsesTools(tools) {
   if (!Array.isArray(tools) || tools.length === 0) {
@@ -2648,6 +2676,9 @@ function createAnthropicCompatibleAdapter(options) {
       const out = { text, usage, finishReason };
       callbacks.onComplete?.(out);
       return out;
+    },
+    async embed() {
+      throw new Error("Anthropic does not provide a native embedding API. " + "Use the openai-compatible provider with Voyage AI (https://api.voyageai.com) — " + "Anthropic's recommended embedding solution, which uses the same request format.");
     }
   };
 }
@@ -2926,6 +2957,23 @@ function toAnthropicInput(messages) {
       continue;
     }
     sawNonSystem = true;
+    if (message.role === "assistant" && Array.isArray(message.tool_calls)) {
+      const parts = [];
+      if (message.content)
+        parts.push({ type: "text", text: message.content });
+      for (const tc of message.tool_calls) {
+        parts.push({ type: "tool_use", id: tc.id, name: tc.function.name, input: JSON.parse(tc.function.arguments) });
+      }
+      normalizedMessages.push({ role: "assistant", content: parts });
+      continue;
+    }
+    if (message.role === "tool") {
+      normalizedMessages.push({
+        role: "user",
+        content: [{ type: "tool_result", tool_use_id: message.tool_call_id, content: message.content }]
+      });
+      continue;
+    }
     normalizedMessages.push({
       role: message.role,
       content: message.content
@@ -4705,6 +4753,12 @@ function createLLM(config, registry = createDefaultProviderRegistry()) {
     async structured(schema, prompt, options) {
       const merged = mergeStructuredOptions(defaults, options);
       return structured(adapter, schema, prompt, merged);
+    },
+    async embed(input, options = {}) {
+      if (!adapter.embed) {
+        throw new Error(`Provider "${adapter.provider ?? "unknown"}" does not support embeddings.`);
+      }
+      return adapter.embed({ ...options, input });
     }
   };
 }
@@ -4870,10 +4924,32 @@ async function resizeImage(source, size, mimeType) {
 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
-    }))
+    ...entries.map((entry) => {
+      if (entry.role === "tool_call") {
+        return {
+          role: "assistant",
+          content: "",
+          tool_calls: [
+            {
+              id: entry.id,
+              type: "function",
+              function: { name: entry.name, arguments: JSON.stringify(entry.arguments ?? {}) }
+            }
+          ]
+        };
+      }
+      if (entry.role === "tool_result") {
+        return {
+          role: "tool",
+          content: typeof entry.output === "string" ? entry.output : JSON.stringify(entry.output),
+          tool_call_id: entry.id
+        };
+      }
+      return {
+        role: entry.role,
+        content: entry.images && entry.images.length > 0 ? [{ type: "text", text: entry.text }, ...images(entry.images)] : entry.text
+      };
+    })
   ];
 }
 // src/prompt.ts

package/dist/llm.d.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 import { type ModelAdapterConfig, type ProviderRegistry } from "./providers/registry";
-import type { LLMAdapter, StructuredCallOptions, StructuredPromptBuilder, StructuredResult } from "./types";
+import type { EmbeddingRequest, EmbeddingResult, LLMAdapter, StructuredCallOptions, StructuredPromptBuilder, StructuredResult } from "./types";
 export interface CreateLLMOptions extends ModelAdapterConfig {
     defaults?: StructuredCallOptions<z.ZodTypeAny>;
 }
@@ -9,5 +9,6 @@ export interface LLMClient {
     provider?: string;
     model?: string;
     structured<TSchema extends z.ZodTypeAny>(schema: TSchema, prompt: StructuredPromptBuilder, options?: StructuredCallOptions<TSchema>): Promise<StructuredResult<z.infer<TSchema>>>;
+    embed(input: string | string[], options?: Omit<EmbeddingRequest, "input">): Promise<EmbeddingResult>;
 }
 export declare function createLLM(config: CreateLLMOptions, registry?: ProviderRegistry): LLMClient;

package/dist/providers/openai-compatible.d.ts

@@ -5,6 +5,7 @@ export interface OpenAICompatibleAdapterOptions {
     apiKey?: string;
     path?: string;
     responsesPath?: string;
+    embeddingPath?: string;
     defaultMaxToolRounds?: number;
     headers?: HTTPHeaders;
     defaultBody?: Record<string, unknown>;

package/dist/types.d.ts

@@ -130,9 +130,18 @@ export interface LLMImageContent {
     };
 }
 export type LLMMessageContent = string | (LLMTextContent | LLMImageContent)[];
+export interface LLMToolCallRef {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
 export interface LLMMessage {
     role: "system" | "user" | "assistant" | "tool";
     content: LLMMessageContent;
+    [key: string]: unknown;
 }
 export interface LLMRequest {
     prompt?: string;
@@ -179,11 +188,24 @@ export interface LLMStreamCallbacks {
     onChunk?: (chunk: LLMStreamChunk) => void;
     onComplete?: (response: LLMResponse) => void;
 }
+export interface EmbeddingRequest {
+    input: string | string[];
+    model?: string;
+    dimensions?: number;
+    body?: Record<string, unknown>;
+}
+export interface EmbeddingResult {
+    embeddings: number[][];
+    model: string;
+    usage?: LLMUsage;
+    raw?: unknown;
+}
 export interface LLMAdapter {
     provider?: string;
     model?: string;
     complete(request: LLMRequest): Promise<LLMResponse>;
     stream?(request: LLMRequest, callbacks?: LLMStreamCallbacks): Promise<LLMResponse>;
+    embed?(request: EmbeddingRequest): Promise<EmbeddingResult>;
 }
 export interface LLMToolCall {
     id: string;

package/package.json

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