@providerprotocol/ai 0.0.21 → 0.0.23

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-DGQHYE6I.js';
+import { g as Provider } from '../provider-DR1yins0.js';
 
 /**
  * @fileoverview Anthropic API type definitions.

package/dist/anthropic/index.js

@@ -1,22 +1,32 @@
+import {
+  parseJsonResponse
+} from "../chunk-Z6DKC37J.js";
+import {
+  StreamEventType
+} from "../chunk-73IIE3QT.js";
 import {
   AssistantMessage,
   createProvider,
+  generateId,
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-M4BMM5IB.js";
+} from "../chunk-MF5ETY5O.js";
 import {
   parseSSEStream
-} from "../chunk-Z7RBRCRN.js";
+} from "../chunk-NWS5IKNR.js";
 import {
   resolveApiKey
-} from "../chunk-Y3GBJNA2.js";
+} from "../chunk-55X3W2MN.js";
 import {
+  ErrorCode,
+  ModalityType,
   UPPError,
   doFetch,
   doStreamFetch,
-  normalizeHttpError
-} from "../chunk-EDENPF3E.js";
+  normalizeHttpError,
+  toError
+} from "../chunk-QNJO7DSD.js";
 
 // src/providers/anthropic/types.ts
 var betas = {
@@ -151,8 +161,9 @@ function transformRequest(request, modelId, useNativeStructuredOutput = false) {
     model: modelId,
     messages: request.messages.map(transformMessage)
   };
-  if (request.system) {
-    anthropicRequest.system = request.system;
+  const normalizedSystem = normalizeSystem(request.system);
+  if (normalizedSystem !== void 0) {
+    anthropicRequest.system = normalizedSystem;
   }
   const allTools = [];
   if (request.tools && request.tools.length > 0) {
@@ -184,7 +195,8 @@ function transformRequest(request, modelId, useNativeStructuredOutput = false) {
         input_schema: {
           type: "object",
           properties: request.structure.properties,
-          required: request.structure.required
+          required: request.structure.required,
+          ...request.structure.additionalProperties !== void 0 ? { additionalProperties: request.structure.additionalProperties } : {}
         }
       };
       anthropicRequest.tools = [...anthropicRequest.tools ?? [], structuredTool];
@@ -193,6 +205,57 @@ function transformRequest(request, modelId, useNativeStructuredOutput = false) {
   }
   return anthropicRequest;
 }
+function normalizeSystem(system) {
+  if (system === void 0 || system === null) return void 0;
+  if (typeof system === "string") return system;
+  if (!Array.isArray(system)) {
+    throw new UPPError(
+      "System prompt must be a string or an array of text blocks",
+      ErrorCode.InvalidRequest,
+      "anthropic",
+      ModalityType.LLM
+    );
+  }
+  const blocks = [];
+  for (const block of system) {
+    if (!block || typeof block !== "object") {
+      throw new UPPError(
+        'System prompt array must contain objects with type "text"',
+        ErrorCode.InvalidRequest,
+        "anthropic",
+        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',
+        ErrorCode.InvalidRequest,
+        "anthropic",
+        ModalityType.LLM
+      );
+    }
+    if (candidate.cache_control !== void 0 && !isValidCacheControl(candidate.cache_control)) {
+      throw new UPPError(
+        "Invalid cache_control for Anthropic system prompt",
+        ErrorCode.InvalidRequest,
+        "anthropic",
+        ModalityType.LLM
+      );
+    }
+    blocks.push(block);
+  }
+  return blocks.length > 0 ? blocks : void 0;
+}
+function isValidCacheControl(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  if (candidate.type !== "ephemeral") return false;
+  if (candidate.ttl !== void 0 && candidate.ttl !== "5m" && candidate.ttl !== "1h") {
+    return false;
+  }
+  return true;
+}
 function filterValidContent(content) {
   return content.filter((c) => c && typeof c.type === "string");
 }
@@ -312,7 +375,8 @@ function transformTool(tool) {
     input_schema: {
       type: "object",
       properties: tool.parameters.properties,
-      required: tool.parameters.required
+      required: tool.parameters.required,
+      ...tool.parameters.additionalProperties !== void 0 ? { additionalProperties: tool.parameters.additionalProperties } : {}
     },
     ...cacheControl ? { cache_control: cacheControl } : {}
   };
@@ -396,6 +460,7 @@ function createStreamState() {
   };
 }
 function transformStreamEvent(event, state) {
+  const events = [];
   switch (event.type) {
     case "message_start":
       state.messageId = event.message.id;
@@ -403,7 +468,8 @@ 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;
-      return { 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") {
         state.content[event.index] = { type: "text", text: "" };
@@ -436,56 +502,63 @@ function transformStreamEvent(event, state) {
           fileContent: resultBlock.content?.content ?? ""
         };
       }
-      return { 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;
       if (delta.type === "text_delta") {
         if (state.content[event.index]) {
           state.content[event.index].text = (state.content[event.index].text ?? "") + delta.text;
         }
-        return {
-          type: "text_delta",
+        events.push({
+          type: StreamEventType.TextDelta,
           index: event.index,
           delta: { text: delta.text }
-        };
+        });
+        break;
       }
       if (delta.type === "input_json_delta") {
         if (state.content[event.index]) {
           state.content[event.index].input = (state.content[event.index].input ?? "") + delta.partial_json;
         }
-        return {
-          type: "tool_call_delta",
+        events.push({
+          type: StreamEventType.ToolCallDelta,
           index: event.index,
           delta: {
             argumentsJson: delta.partial_json,
             toolCallId: state.content[event.index]?.id,
             toolName: state.content[event.index]?.name
           }
-        };
+        });
+        break;
       }
       if (delta.type === "thinking_delta") {
-        return {
-          type: "reasoning_delta",
+        events.push({
+          type: StreamEventType.ReasoningDelta,
           index: event.index,
           delta: { text: delta.thinking }
-        };
+        });
+        break;
       }
-      return null;
+      break;
     }
     case "content_block_stop":
-      return { 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 null;
+      return [];
     case "message_stop":
-      return { type: "message_stop", index: 0, delta: {} };
+      events.push({ type: StreamEventType.MessageStop, index: 0, delta: {} });
+      break;
     case "ping":
     case "error":
-      return null;
+      return [];
     default:
-      return null;
+      break;
   }
+  return events;
 }
 function buildResponseFromState(state, useNativeStructuredOutput = false) {
   const textContent = [];
@@ -529,11 +602,12 @@ ${block.fileContent}\`\`\`
 ` });
     }
   }
+  const messageId = state.messageId || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: state.messageId,
+      id: messageId,
       metadata: {
         anthropic: {
           stop_reason: state.stopReason,
@@ -588,9 +662,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 = {
@@ -636,7 +710,7 @@ function createLLMHandler() {
             "anthropic",
             "llm"
           );
-          const data = await response.json();
+          const data = await parseJsonResponse(response, "anthropic", "llm");
           return transformResponse(data, useNativeStructuredOutput);
         },
         stream(request) {
@@ -665,7 +739,8 @@ function createLLMHandler() {
               const headers = {
                 "Content-Type": "application/json",
                 "x-api-key": apiKey,
-                "anthropic-version": request.config.apiVersion ?? ANTHROPIC_VERSION
+                "anthropic-version": request.config.apiVersion ?? ANTHROPIC_VERSION,
+                Accept: "text/event-stream"
               };
               if (request.config.headers) {
                 for (const [key, value] of Object.entries(request.config.headers)) {
@@ -694,9 +769,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;
@@ -707,23 +782,24 @@ 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;
                   }
-                  const uppEvent = transformStreamEvent(event, state);
-                  if (uppEvent) {
+                  const uppEvents = transformStreamEvent(event, state);
+                  for (const uppEvent of uppEvents) {
                     yield uppEvent;
                   }
                 }
               }
               responseResolve(buildResponseFromState(state, useNativeStructuredOutput));
             } catch (error) {
-              responseReject(error);
-              throw error;
+              const err = toError(error);
+              responseReject(err);
+              throw err;
             }
           }
           return {