@providerprotocol/ai 0.0.22 → 0.0.24

package/README.md

@@ -44,6 +44,31 @@ for await (const event of stream) {
 const turn = await stream.turn;
 ```
 
+**Stream Control:**
+
+```typescript
+const stream = claude.stream('Write a long story');
+
+// Abort the stream at any time
+setTimeout(() => stream.abort(), 5000);
+
+for await (const event of stream) {
+  // Process events until abort
+}
+```
+
+**Stream Events:**
+
+| Event | Description |
+|-------|-------------|
+| `text_delta` | Incremental text output |
+| `reasoning_delta` | Incremental reasoning/thinking output |
+| `tool_call_delta` | Tool call arguments being streamed |
+| `tool_execution_start` | Tool execution has started |
+| `tool_execution_end` | Tool execution has completed |
+| `message_start` / `message_stop` | Message boundaries |
+| `content_block_start` / `content_block_stop` | Content block boundaries |
+
 ### Multi-turn Conversations
 
 ```typescript
@@ -104,6 +129,60 @@ const img = await Image.fromPath('./photo.png');
 const turn = await claude.generate([img, 'What is in this image?']);
 ```
 
+## Anthropic Beta Features
+
+Anthropic provides beta features through the `betas` export. Enable them at the model level:
+
+```typescript
+import { anthropic, betas } from '@providerprotocol/ai/anthropic';
+import { llm } from '@providerprotocol/ai';
+
+// Native structured outputs with guaranteed JSON schema conformance
+const model = llm({
+  model: anthropic('claude-sonnet-4-20250514', {
+    betas: [betas.structuredOutputs],
+  }),
+  structure: {
+    type: 'object',
+    properties: { answer: { type: 'string' } },
+    required: ['answer'],
+  },
+});
+
+// Extended thinking with interleaved tool calls
+const thinker = llm({
+  model: anthropic('claude-sonnet-4-20250514', {
+    betas: [betas.interleavedThinking],
+  }),
+  params: {
+    thinking: { type: 'enabled', budget_tokens: 10000 },
+  },
+});
+```
+
+**Available Beta Features:**
+
+| Beta | Description |
+|------|-------------|
+| `structuredOutputs` | Guaranteed JSON schema conformance for responses |
+| `interleavedThinking` | Claude can think between tool calls |
+| `devFullThinking` | Developer mode for full thinking visibility |
+| `effort` | Control response thoroughness vs efficiency (Opus 4.5) |
+| `computerUse` | Mouse, keyboard, screenshot control (Claude 4) |
+| `codeExecution` | Python/Bash sandbox execution |
+| `tokenEfficientTools` | Up to 70% token reduction for tool calls |
+| `fineGrainedToolStreaming` | Stream tool args without buffering |
+| `output128k` | 128K token output length |
+| `context1m` | 1 million token context window (Sonnet 4) |
+| `promptCaching` | Reduced latency and costs via caching |
+| `extendedCacheTtl` | 1-hour cache TTL (vs 5-minute default) |
+| `advancedToolUse` | Tool Search, Programmatic Tool Calling |
+| `mcpClient` | Connect to remote MCP servers |
+| `filesApi` | Upload and manage files |
+| `pdfs` | PDF document support |
+| `messageBatches` | Async batch processing at 50% cost |
+| `skills` | Agent Skills (PowerPoint, Excel, Word, PDF) |
+
 ## Embeddings
 
 ```typescript
@@ -198,6 +277,51 @@ const instance = llm({
 });
 ```
 
+### System Prompts
+
+System prompts can be a simple string or a provider-specific array for advanced features:
+
+```typescript
+// Simple string (all providers)
+const simple = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  system: 'You are a helpful assistant.',
+});
+
+// Anthropic cache_control format
+import { anthropic, betas } from '@providerprotocol/ai/anthropic';
+
+const cached = llm({
+  model: anthropic('claude-sonnet-4-20250514', {
+    betas: [betas.promptCaching],
+  }),
+  system: [
+    { type: 'text', text: 'Large context document...', cache_control: { type: 'ephemeral' } },
+    { type: 'text', text: 'Instructions...' },
+  ],
+});
+```
+
+### Provider Config Options
+
+```typescript
+interface ProviderConfig {
+  apiKey?: string | (() => Promise<string>) | KeyStrategy; // API key, async getter, or strategy
+  baseUrl?: string;                 // Custom API endpoint
+  timeout?: number;                 // Per-attempt timeout (ms)
+  retryStrategy?: RetryStrategy;    // Retry behavior
+  headers?: Record<string, string>; // Custom headers (merged with provider defaults)
+  fetch?: typeof fetch;             // Custom fetch implementation
+  apiVersion?: string;              // API version override
+  retryAfterMaxSeconds?: number;    // Cap for Retry-After header (default: 3600)
+}
+```
+
+**Notes:**
+- `timeout` applies per attempt; total time can exceed this with retries
+- `headers` are merged with model-level headers (explicit config takes precedence)
+- `retryAfterMaxSeconds` prevents honoring excessively long Retry-After values
+
 ### Key Strategies
 
 ```typescript
@@ -227,8 +351,13 @@ import {
   RetryAfterStrategy,
 } from '@providerprotocol/ai/http';
 
-// Exponential: 1s, 2s, 4s... (default)
-new ExponentialBackoff({ maxAttempts: 5, baseDelay: 1000, maxDelay: 30000 })
+// Exponential: 1s, 2s, 4s...
+new ExponentialBackoff({
+  maxAttempts: 5,
+  baseDelay: 1000,
+  maxDelay: 30000,
+  jitter: true,  // Randomize delays to prevent thundering herd (default: true)
+})
 
 // Linear: 1s, 2s, 3s...
 new LinearBackoff({ maxAttempts: 3, delay: 1000 })
@@ -243,6 +372,8 @@ new RetryAfterStrategy({ maxAttempts: 3, fallbackDelay: 5000 })
 new NoRetry()
 ```
 
+**Retryable Errors:** `RATE_LIMITED`, `NETWORK_ERROR`, `TIMEOUT`, `PROVIDER_ERROR`
+
 ## Tool Execution Control
 
 ```typescript
@@ -294,6 +425,12 @@ try {
   await claude.generate('Hello');
 } catch (error) {
   if (error instanceof UPPError) {
+    console.log(error.code);       // 'RATE_LIMITED'
+    console.log(error.provider);   // 'anthropic'
+    console.log(error.modality);   // 'llm'
+    console.log(error.statusCode); // 429
+    console.log(error.cause);      // Original error (if any)
+
     switch (error.code) {
       case 'RATE_LIMITED':
         // Wait and retry
@@ -385,7 +522,7 @@ Server adapters for Express, Fastify, and Nuxt/H3:
 
 ```typescript
 // Express
-import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
+import { express as expressAdapter, parseBody } from '@providerprotocol/ai/proxy';
 app.post('/ai', authMiddleware, async (req, res) => {
   const { messages, system, params } = parseBody(req.body);
   if (params?.stream) {
@@ -396,7 +533,7 @@ app.post('/ai', authMiddleware, async (req, res) => {
 });
 
 // Fastify
-import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
+import { fastify as fastifyAdapter, parseBody } from '@providerprotocol/ai/proxy';
 app.post('/ai', async (request, reply) => {
   const { messages, system, params } = parseBody(request.body);
   if (params?.stream) {
@@ -406,7 +543,7 @@ app.post('/ai', async (request, reply) => {
 });
 
 // Nuxt/H3 (server/api/ai.post.ts)
-import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
+import { h3 as h3Adapter, parseBody } from '@providerprotocol/ai/proxy';
 export default defineEventHandler(async (event) => {
   const { messages, system, params } = parseBody(await readBody(event));
   if (params?.stream) {
@@ -441,23 +578,68 @@ xai('grok-3-fast', { api: 'responses' })
 xai('grok-3-fast', { api: 'messages' })
 ```
 
+## Alternative Import Style
+
+Use the `ai` namespace for a grouped import style:
+
+```typescript
+import { ai } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
+
+const model = ai.llm({ model: openai('gpt-4o') });
+const embedder = ai.embedding({ model: openai('text-embedding-3-small') });
+const dalle = ai.image({ model: openai('dall-e-3') });
+```
+
 ## TypeScript
 
 Full type safety with no `any` types. All provider parameters are typed:
 
 ```typescript
 import type {
+  // Core types
   Turn,
   Message,
   Tool,
-  UPPError,
   TokenUsage,
+
+  // Streaming
   StreamEvent,
+  StreamResult,
+
+  // Modality results
   EmbeddingResult,
   ImageResult,
+
+  // Errors
+  UPPError,
+  ErrorCode,
+
+  // Configuration
+  ProviderConfig,
+  KeyStrategy,
+  RetryStrategy,
+  LLMCapabilities,
 } from '@providerprotocol/ai';
 ```
 
+### Custom Providers
+
+Build custom providers with `createProvider`:
+
+```typescript
+import { createProvider } from '@providerprotocol/ai';
+
+const myProvider = createProvider({
+  name: 'my-provider',
+  version: '1.0.0',
+  handlers: {
+    llm: myLLMHandler,
+    embedding: myEmbeddingHandler,
+  },
+});
+```
+
 ## License
 
 MIT

package/dist/anthropic/index.d.ts

@@ -1,4 +1,4 @@
-import { g as Provider } from '../provider-DWEAzeM5.js';
+import { g as Provider } from '../provider-x4RocsnK.js';
 
 /**
  * @fileoverview Anthropic API type definitions.

package/dist/anthropic/index.js

@@ -1,6 +1,9 @@
 import {
   parseJsonResponse
-} from "../chunk-I2VHCGQE.js";
+} from "../chunk-Z6DKC37J.js";
+import {
+  StreamEventType
+} from "../chunk-73IIE3QT.js";
 import {
   AssistantMessage,
   createProvider,
@@ -8,20 +11,22 @@ import {
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-M4BMM5IB.js";
+} from "../chunk-6AZVUI6H.js";
 import {
   parseSSEStream
-} from "../chunk-NWS5IKNR.js";
+} from "../chunk-TOJCZMVU.js";
 import {
   resolveApiKey
-} from "../chunk-7WYBJPJJ.js";
+} from "../chunk-55X3W2MN.js";
 import {
+  ErrorCode,
+  ModalityType,
   UPPError,
   doFetch,
   doStreamFetch,
   normalizeHttpError,
   toError
-} from "../chunk-RFWLEFAB.js";
+} from "../chunk-QNJO7DSD.js";
 
 // src/providers/anthropic/types.ts
 var betas = {
@@ -206,9 +211,9 @@ function normalizeSystem(system) {
   if (!Array.isArray(system)) {
     throw new UPPError(
       "System prompt must be a string or an array of text blocks",
-      "INVALID_REQUEST",
+      ErrorCode.InvalidRequest,
       "anthropic",
-      "llm"
+      ModalityType.LLM
     );
   }
   const blocks = [];
@@ -216,26 +221,26 @@ function normalizeSystem(system) {
     if (!block || typeof block !== "object") {
       throw new UPPError(
         'System prompt array must contain objects with type "text"',
-        "INVALID_REQUEST",
+        ErrorCode.InvalidRequest,
         "anthropic",
-        "llm"
+        ModalityType.LLM
       );
     }
     const candidate = block;
     if (candidate.type !== "text" || typeof candidate.text !== "string") {
       throw new UPPError(
         'Anthropic system blocks must be of type "text" with a string text field',
-        "INVALID_REQUEST",
+        ErrorCode.InvalidRequest,
         "anthropic",
-        "llm"
+        ModalityType.LLM
       );
     }
     if (candidate.cache_control !== void 0 && !isValidCacheControl(candidate.cache_control)) {
       throw new UPPError(
         "Invalid cache_control for Anthropic system prompt",
-        "INVALID_REQUEST",
+        ErrorCode.InvalidRequest,
         "anthropic",
-        "llm"
+        ModalityType.LLM
       );
     }
     blocks.push(block);
@@ -272,9 +277,26 @@ function transformMessage(message) {
   }
   if (isAssistantMessage(message)) {
     const validContent = filterValidContent(message.content);
-    const content = validContent.map(
-      (block, index, arr) => transformContentBlock(block, index === arr.length - 1 && !message.toolCalls?.length ? cacheControl : void 0)
-    );
+    const content = [];
+    const anthropicMeta = message.metadata?.anthropic;
+    const thinkingSignatures = anthropicMeta?.thinkingSignatures;
+    let reasoningIndex = 0;
+    for (let i = 0; i < validContent.length; i++) {
+      const block = validContent[i];
+      const isLastNonToolBlock = i === validContent.length - 1 && !message.toolCalls?.length;
+      if (block.type === "reasoning") {
+        const signatureFromArray = thinkingSignatures?.[reasoningIndex];
+        const signature = Array.isArray(thinkingSignatures) ? typeof signatureFromArray === "string" ? signatureFromArray : void 0 : anthropicMeta?.thinkingSignature;
+        reasoningIndex += 1;
+        content.push({
+          type: "thinking",
+          thinking: block.text,
+          ...signature ? { signature } : {}
+        });
+      } else {
+        content.push(transformContentBlock(block, isLastNonToolBlock ? cacheControl : void 0));
+      }
+    }
     if (message.toolCalls) {
       for (let i = 0; i < message.toolCalls.length; i++) {
         const call = message.toolCalls[i];
@@ -377,11 +399,20 @@ function transformTool(tool) {
   };
 }
 function transformResponse(data, useNativeStructuredOutput = false) {
+  const reasoningContent = [];
   const textContent = [];
   const toolCalls = [];
   let structuredData;
+  let thinkingSignature;
+  const thinkingSignatures = [];
   for (const block of data.content) {
-    if (block.type === "text") {
+    if (block.type === "thinking") {
+      reasoningContent.push({ type: "reasoning", text: block.thinking });
+      if (block.signature) {
+        thinkingSignature = block.signature;
+      }
+      thinkingSignatures.push(block.signature ?? null);
+    } else if (block.type === "text") {
       textContent.push({ type: "text", text: block.text });
       if (useNativeStructuredOutput && structuredData === void 0) {
         try {
@@ -414,8 +445,10 @@ ${block.content.content}\`\`\`
       }
     }
   }
+  const allContent = [...reasoningContent, ...textContent];
+  const hasThinkingSignatures = thinkingSignatures.some((signature) => signature);
   const message = new AssistantMessage(
-    textContent,
+    allContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
       id: data.id,
@@ -423,7 +456,9 @@ ${block.content.content}\`\`\`
         anthropic: {
           stop_reason: data.stop_reason,
           stop_sequence: data.stop_sequence,
-          model: data.model
+          model: data.model,
+          thinkingSignature,
+          ...hasThinkingSignatures ? { thinkingSignatures } : {}
         }
       }
     }
@@ -463,10 +498,12 @@ function transformStreamEvent(event, state) {
       state.inputTokens = event.message.usage.input_tokens;
       state.cacheReadTokens = event.message.usage.cache_read_input_tokens ?? 0;
       state.cacheWriteTokens = event.message.usage.cache_creation_input_tokens ?? 0;
-      events.push({ type: "message_start", index: 0, delta: {} });
+      events.push({ type: StreamEventType.MessageStart, index: 0, delta: {} });
       break;
     case "content_block_start":
-      if (event.content_block.type === "text") {
+      if (event.content_block.type === "thinking") {
+        state.content[event.index] = { type: "thinking", thinking: "" };
+      } else if (event.content_block.type === "text") {
         state.content[event.index] = { type: "text", text: "" };
       } else if (event.content_block.type === "tool_use") {
         state.content[event.index] = {
@@ -497,7 +534,7 @@ function transformStreamEvent(event, state) {
           fileContent: resultBlock.content?.content ?? ""
         };
       }
-      events.push({ type: "content_block_start", index: event.index, delta: {} });
+      events.push({ type: StreamEventType.ContentBlockStart, index: event.index, delta: {} });
       break;
     case "content_block_delta": {
       const delta = event.delta;
@@ -506,7 +543,7 @@ function transformStreamEvent(event, state) {
           state.content[event.index].text = (state.content[event.index].text ?? "") + delta.text;
         }
         events.push({
-          type: "text_delta",
+          type: StreamEventType.TextDelta,
           index: event.index,
           delta: { text: delta.text }
         });
@@ -517,7 +554,7 @@ function transformStreamEvent(event, state) {
           state.content[event.index].input = (state.content[event.index].input ?? "") + delta.partial_json;
         }
         events.push({
-          type: "tool_call_delta",
+          type: StreamEventType.ToolCallDelta,
           index: event.index,
           delta: {
             argumentsJson: delta.partial_json,
@@ -528,24 +565,33 @@ function transformStreamEvent(event, state) {
         break;
       }
       if (delta.type === "thinking_delta") {
+        if (state.content[event.index]) {
+          state.content[event.index].thinking = (state.content[event.index].thinking ?? "") + delta.thinking;
+        }
         events.push({
-          type: "reasoning_delta",
+          type: StreamEventType.ReasoningDelta,
           index: event.index,
           delta: { text: delta.thinking }
         });
         break;
       }
+      if (delta.type === "signature_delta") {
+        if (state.content[event.index]) {
+          state.content[event.index].signature = delta.signature;
+        }
+        break;
+      }
       break;
     }
     case "content_block_stop":
-      events.push({ type: "content_block_stop", index: event.index, delta: {} });
+      events.push({ type: StreamEventType.ContentBlockStop, index: event.index, delta: {} });
       break;
     case "message_delta":
       state.stopReason = event.delta.stop_reason;
       state.outputTokens = event.usage.output_tokens;
       return [];
     case "message_stop":
-      events.push({ type: "message_stop", index: 0, delta: {} });
+      events.push({ type: StreamEventType.MessageStop, index: 0, delta: {} });
       break;
     case "ping":
     case "error":
@@ -556,12 +602,21 @@ function transformStreamEvent(event, state) {
   return events;
 }
 function buildResponseFromState(state, useNativeStructuredOutput = false) {
+  const reasoningContent = [];
   const textContent = [];
   const toolCalls = [];
   let structuredData;
+  let thinkingSignature;
+  const thinkingSignatures = [];
   for (const block of state.content) {
     if (!block) continue;
-    if (block.type === "text" && block.text) {
+    if (block.type === "thinking" && block.thinking) {
+      reasoningContent.push({ type: "reasoning", text: block.thinking });
+      if (block.signature) {
+        thinkingSignature = block.signature;
+      }
+      thinkingSignatures.push(block.signature ?? null);
+    } else if (block.type === "text" && block.text) {
       textContent.push({ type: "text", text: block.text });
       if (useNativeStructuredOutput && structuredData === void 0) {
         try {
@@ -597,16 +652,20 @@ ${block.fileContent}\`\`\`
 ` });
     }
   }
+  const allContent = [...reasoningContent, ...textContent];
+  const hasThinkingSignatures = thinkingSignatures.some((signature) => signature);
   const messageId = state.messageId || generateId();
   const message = new AssistantMessage(
-    textContent,
+    allContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
       id: messageId,
       metadata: {
         anthropic: {
           stop_reason: state.stopReason,
-          model: state.model
+          model: state.model,
+          thinkingSignature,
+          ...hasThinkingSignatures ? { thinkingSignatures } : {}
         }
       }
     }
@@ -657,9 +716,9 @@ function createLLMHandler() {
       if (!providerRef) {
         throw new UPPError(
           "Provider reference not set. Handler must be used with createProvider().",
-          "INVALID_REQUEST",
+          ErrorCode.InvalidRequest,
           "anthropic",
-          "llm"
+          ModalityType.LLM
         );
       }
       const model = {
@@ -764,9 +823,9 @@ function createLLMHandler() {
               if (!response.body) {
                 const error = new UPPError(
                   "No response body for streaming request",
-                  "PROVIDER_ERROR",
+                  ErrorCode.ProviderError,
                   "anthropic",
-                  "llm"
+                  ModalityType.LLM
                 );
                 responseReject(error);
                 throw error;
@@ -777,9 +836,9 @@ function createLLMHandler() {
                   if (event.type === "error") {
                     const error = new UPPError(
                       event.error.message,
-                      "PROVIDER_ERROR",
+                      ErrorCode.ProviderError,
                       "anthropic",
-                      "llm"
+                      ModalityType.LLM
                     );
                     responseReject(error);
                     throw error;