@providerprotocol/ai 0.0.17 → 0.0.19

package/README.md

@@ -1,117 +1,130 @@
 # @providerprotocol/ai
 
-Unified Provider Protocol (UPP-1.2) implementation for AI inference across multiple providers.
-
-## Install
+A unified TypeScript SDK for AI inference across multiple providers. One API for LLMs, embeddings, and image generation.
 
 ```bash
 bun add @providerprotocol/ai
 ```
 
-## Usage
+## Quick Start
 
 ```typescript
 import { llm } from '@providerprotocol/ai';
 import { anthropic } from '@providerprotocol/ai/anthropic';
-import { openai } from '@providerprotocol/ai/openai';
-import { google } from '@providerprotocol/ai/google';
-import { ollama } from '@providerprotocol/ai/ollama';
-import { openrouter } from '@providerprotocol/ai/openrouter';
-import { xai } from '@providerprotocol/ai/xai';
 
-// Simple generation
 const claude = llm({ model: anthropic('claude-sonnet-4-20250514') });
 const turn = await claude.generate('Hello!');
 console.log(turn.response.text);
+```
+
+## Providers
+
+| Provider | Import | LLM | Embedding | Image |
+|----------|--------|:---:|:---------:|:-----:|
+| Anthropic | `@providerprotocol/ai/anthropic` | ✓ | | |
+| OpenAI | `@providerprotocol/ai/openai` | ✓ | ✓ | ✓ |
+| Google | `@providerprotocol/ai/google` | ✓ | ✓ | ✓ |
+| xAI | `@providerprotocol/ai/xai` | ✓ | | ✓ |
+| Ollama | `@providerprotocol/ai/ollama` | ✓ | ✓ | |
+| OpenRouter | `@providerprotocol/ai/openrouter` | ✓ | ✓ | |
+
+API keys are loaded automatically from environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.).
+
+## LLM
 
-// Streaming
+### Streaming
+
+```typescript
 const stream = claude.stream('Count to 5');
 for await (const event of stream) {
-  if (event.type === 'text_delta') process.stdout.write(event.delta.text);
+  if (event.type === 'text_delta') {
+    process.stdout.write(event.delta.text);
+  }
 }
+const turn = await stream.turn;
+```
+
+### Multi-turn Conversations
+
+```typescript
+const history: Message[] = [];
 
-// Multi-turn
-const history = [];
 const t1 = await claude.generate(history, 'My name is Alice');
 history.push(...t1.messages);
+
 const t2 = await claude.generate(history, 'What is my name?');
+// Response: "Your name is Alice"
+```
+
+### Tools
 
-// Tools
+```typescript
 const turn = await claude.generate({
   tools: [{
     name: 'getWeather',
     description: 'Get weather for a location',
-    parameters: { type: 'object', properties: { location: { type: 'string' } } },
-    run: async ({ location }) => `Sunny in ${location}`,
+    parameters: {
+      type: 'object',
+      properties: { location: { type: 'string' } },
+      required: ['location'],
+    },
+    run: async ({ location }) => ({ temp: 72, conditions: 'sunny' }),
   }],
-}, 'Weather in Tokyo?');
+}, 'What is the weather in Tokyo?');
+```
+
+### Structured Output
 
-// Structured output
-const turn = await llm({
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
+
+const extractor = llm({
   model: openai('gpt-4o'),
   structure: {
     type: 'object',
-    properties: { name: { type: 'string' }, age: { type: 'number' } },
+    properties: {
+      name: { type: 'string' },
+      age: { type: 'number' },
+    },
+    required: ['name', 'age'],
   },
-}).generate('Extract: John is 30 years old');
+});
+
+const turn = await extractor.generate('John is 30 years old');
 console.log(turn.data); // { name: 'John', age: 30 }
 ```
 
-## Embeddings
+### Multimodal Input
 
-Generate vector embeddings from text using the unified `embedding()` interface.
+```typescript
+import { Image } from '@providerprotocol/ai';
+
+const img = await Image.fromPath('./photo.png');
+const turn = await claude.generate([img, 'What is in this image?']);
+```
+
+## Embeddings
 
 ```typescript
 import { embedding } from '@providerprotocol/ai';
 import { openai } from '@providerprotocol/ai/openai';
-import { google } from '@providerprotocol/ai/google';
-import { ollama } from '@providerprotocol/ai/ollama';
-import { openrouter } from '@providerprotocol/ai/openrouter';
 
-// Single text embedding
 const embedder = embedding({ model: openai('text-embedding-3-small') });
-const result = await embedder.embed('Hello world');
-console.log(result.embeddings[0].vector); // [0.123, -0.456, ...]
-console.log(result.embeddings[0].dimensions); // 1536
 
-// Batch embedding
+// Single or batch
+const result = await embedder.embed('Hello world');
 const batch = await embedder.embed(['doc1', 'doc2', 'doc3']);
-console.log(batch.embeddings.length); // 3
 
-// Custom dimensions (OpenAI text-embedding-3 models)
-const smallEmbed = embedding({
-  model: openai('text-embedding-3-small'),
-  params: { dimensions: 256 },
-});
-
-// Google with task type optimization
-const googleEmbed = embedding({
-  model: google('text-embedding-004'),
-  params: {
-    taskType: 'RETRIEVAL_DOCUMENT',
-    title: 'Important Document',
-  },
-});
-
-// Ollama local embeddings
-const localEmbed = embedding({
-  model: ollama('qwen3-embedding:4b'),
-});
-
-// OpenRouter (access multiple providers)
-const routerEmbed = embedding({
-  model: openrouter('openai/text-embedding-3-small'),
-});
+console.log(result.embeddings[0].vector);     // [0.123, -0.456, ...]
+console.log(result.embeddings[0].dimensions); // 1536
 ```
 
-### Chunked Streaming
+### Chunked Processing
 
-For large document sets, use chunked mode for progress tracking:
+For large datasets with progress tracking:
 
 ```typescript
-const embedder = embedding({ model: openai('text-embedding-3-small') });
-const documents = Array.from({ length: 1000 }, (_, i) => `Document ${i}`);
-
 const stream = embedder.embed(documents, {
   chunked: true,
   batchSize: 100,
@@ -120,91 +133,258 @@ const stream = embedder.embed(documents, {
 
 for await (const progress of stream) {
   console.log(`${progress.percent.toFixed(1)}% complete`);
-  console.log(`Processed ${progress.completed} of ${progress.total}`);
 }
 
-const finalResult = await stream.result;
-console.log(`Total embeddings: ${finalResult.embeddings.length}`);
+const result = await stream.result;
 ```
 
-### Provider-Specific Parameters
-
-Each provider supports its native parameters passed through unchanged:
+## Image Generation
 
 ```typescript
-// OpenAI: dimensions, encoding_format, user
-embedding({
-  model: openai('text-embedding-3-large'),
-  params: { dimensions: 1024, encoding_format: 'float' },
-});
-
-// Google: taskType, title, outputDimensionality
-embedding({
-  model: google('text-embedding-004'),
-  params: {
-    taskType: 'SEMANTIC_SIMILARITY',
-    outputDimensionality: 256,
-  },
-});
+import { image } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
 
-// Ollama: truncate, keep_alive, options
-embedding({
-  model: ollama('nomic-embed-text'),
-  params: { truncate: true, keep_alive: '5m' },
-});
+const dalle = image({ model: openai('dall-e-3') });
+const result = await dalle.generate('A sunset over mountains');
 
-// OpenRouter: dimensions, encoding_format, input_type
-embedding({
-  model: openrouter('openai/text-embedding-3-small'),
-  params: { dimensions: 512 },
-});
+console.log(result.images[0].image.toBase64());
 ```
 
-## Providers
-
-| Provider | Import | LLM | Embedding |
-|----------|--------|-----|-----------|
-| Anthropic | `@providerprotocol/ai/anthropic` | Yes | - |
-| OpenAI | `@providerprotocol/ai/openai` | Yes | Yes |
-| Google | `@providerprotocol/ai/google` | Yes | Yes |
-| Ollama | `@providerprotocol/ai/ollama` | Yes | Yes |
-| OpenRouter | `@providerprotocol/ai/openrouter` | Yes | Yes |
-| xAI (Grok) | `@providerprotocol/ai/xai` | Yes | - |
+### With Parameters
 
-### xAI API Modes
+```typescript
+const hd = image({
+  model: openai('dall-e-3'),
+  params: { size: '1792x1024', quality: 'hd', style: 'natural' },
+});
+```
 
-xAI supports three API modes:
+### Image Editing
 
 ```typescript
-import { xai } from '@providerprotocol/ai/xai';
+import { image, Image } from '@providerprotocol/ai';
 
-// Chat Completions API (OpenAI-compatible, default)
-const grok = llm({ model: xai('grok-3-fast') });
+const editor = image({ model: openai('dall-e-2') });
 
-// Responses API (stateful, OpenAI Responses-compatible)
-const grok = llm({ model: xai('grok-3-fast', { api: 'responses' }) });
+const source = await Image.fromPath('./photo.png');
+const mask = await Image.fromPath('./mask.png');
 
-// Messages API (Anthropic-compatible)
-const grok = llm({ model: xai('grok-3-fast', { api: 'messages' }) });
+const result = await editor.edit({
+  image: source,
+  mask,
+  prompt: 'Add a rainbow in the sky',
+});
 ```
 
 ## Configuration
 
 ```typescript
+import { llm } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
 import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
 
 const instance = llm({
   model: openai('gpt-4o'),
   config: {
-    apiKey: 'sk-...',
+    apiKey: new RoundRobinKeys(['sk-key1', 'sk-key2']),
     timeout: 30000,
     retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
   },
-  params: { temperature: 0.7, max_tokens: 1000 },
-  system: 'You are helpful.',
+  params: {
+    temperature: 0.7,
+    max_tokens: 1000,
+  },
+  system: 'You are a helpful assistant.',
+});
+```
+
+### Key Strategies
+
+```typescript
+import { RoundRobinKeys, WeightedKeys, DynamicKey } from '@providerprotocol/ai/http';
+
+// Cycle through keys evenly
+new RoundRobinKeys(['sk-1', 'sk-2', 'sk-3'])
+
+// Weighted selection (70% key1, 30% key2)
+new WeightedKeys([
+  { key: 'sk-1', weight: 70 },
+  { key: 'sk-2', weight: 30 },
+])
+
+// Dynamic fetching (secrets manager, etc.)
+new DynamicKey(async () => fetchKeyFromVault())
+```
+
+### Retry Strategies
+
+```typescript
+import {
+  ExponentialBackoff,
+  LinearBackoff,
+  NoRetry,
+  TokenBucket,
+  RetryAfterStrategy,
+} from '@providerprotocol/ai/http';
+
+// Exponential: 1s, 2s, 4s... (default)
+new ExponentialBackoff({ maxAttempts: 5, baseDelay: 1000, maxDelay: 30000 })
+
+// Linear: 1s, 2s, 3s...
+new LinearBackoff({ maxAttempts: 3, delay: 1000 })
+
+// Rate limiting with token bucket
+new TokenBucket({ maxTokens: 10, refillRate: 1 })
+
+// Respect server Retry-After headers
+new RetryAfterStrategy({ maxAttempts: 3, fallbackDelay: 5000 })
+
+// No retries
+new NoRetry()
+```
+
+## Tool Execution Control
+
+```typescript
+const turn = await claude.generate({
+  tools: [weatherTool, searchTool],
+  toolStrategy: {
+    maxIterations: 5,
+    onBeforeCall: (tool, params) => {
+      if (tool.name === 'dangerousTool') return false; // Block execution
+      return true;
+    },
+    onAfterCall: (tool, params, result) => {
+      console.log(`${tool.name} returned:`, result);
+    },
+    onError: (tool, params, error) => {
+      console.error(`${tool.name} failed:`, error);
+    },
+  },
+}, 'Search for recent news about AI');
+```
+
+## Thread Management
+
+```typescript
+import { Thread } from '@providerprotocol/ai';
+
+const thread = new Thread();
+
+thread.user('Hello!');
+const turn = await claude.generate(thread.toMessages(), 'How are you?');
+thread.append(turn);
+
+// Serialize for storage
+const json = thread.toJSON();
+localStorage.setItem('conversation', JSON.stringify(json));
+
+// Restore later
+const restored = Thread.fromJSON(JSON.parse(localStorage.getItem('conversation')));
+```
+
+## Error Handling
+
+All errors are normalized to `UPPError` with consistent error codes:
+
+```typescript
+import { UPPError } from '@providerprotocol/ai';
+
+try {
+  await claude.generate('Hello');
+} catch (error) {
+  if (error instanceof UPPError) {
+    switch (error.code) {
+      case 'RATE_LIMITED':
+        // Wait and retry
+        break;
+      case 'CONTEXT_LENGTH_EXCEEDED':
+        // Reduce input size
+        break;
+      case 'AUTHENTICATION_FAILED':
+        // Check API key
+        break;
+      case 'CONTENT_FILTERED':
+        // Content policy violation
+        break;
+    }
+  }
+}
+```
+
+**Error Codes:** `AUTHENTICATION_FAILED`, `RATE_LIMITED`, `CONTEXT_LENGTH_EXCEEDED`, `MODEL_NOT_FOUND`, `INVALID_REQUEST`, `INVALID_RESPONSE`, `CONTENT_FILTERED`, `QUOTA_EXCEEDED`, `PROVIDER_ERROR`, `NETWORK_ERROR`, `TIMEOUT`, `CANCELLED`
+
+## Proxy Server
+
+Build backend proxies to hide API keys from clients.
+
+### Server
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { webapi, parseBody, toJSON, toSSE } from '@providerprotocol/ai/proxy';
+
+const claude = llm({ model: anthropic('claude-sonnet-4-20250514') });
+
+Bun.serve({
+  port: 3000,
+  fetch: webapi(async (req) => {
+    const { messages, system, params } = parseBody(await req.json());
+
+    if (params?.stream) {
+      return toSSE(claude.stream(messages, { system }));
+    }
+
+    return toJSON(await claude.generate(messages, { system }));
+  }),
 });
 ```
 
+### Client
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { proxy } from '@providerprotocol/ai/proxy';
+
+const claude = llm({ model: proxy('http://localhost:3000') });
+const turn = await claude.generate('Hello!');
+```
+
+## xAI API Modes
+
+xAI supports multiple API compatibility modes:
+
+```typescript
+import { xai } from '@providerprotocol/ai/xai';
+
+// Chat Completions (OpenAI-compatible, default)
+xai('grok-3-fast')
+
+// Responses API (stateful)
+xai('grok-3-fast', { api: 'responses' })
+
+// Messages API (Anthropic-compatible)
+xai('grok-3-fast', { api: 'messages' })
+```
+
+## TypeScript
+
+Full type safety with no `any` types. All provider parameters are typed:
+
+```typescript
+import type {
+  Turn,
+  Message,
+  Tool,
+  UPPError,
+  TokenUsage,
+  StreamEvent,
+  EmbeddingResult,
+  ImageResult,
+} from '@providerprotocol/ai';
+```
+
 ## License
 
 MIT

package/dist/anthropic/index.d.ts

@@ -1,4 +1,4 @@
-import { d as Provider } from '../provider-D5MO3-pS.js';
+import { d as Provider } from '../provider-BBMBZuGn.js';
 
 /**
  * @fileoverview Anthropic API type definitions.

package/dist/anthropic/index.js

@@ -6,17 +6,19 @@ import {
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-SVYROCLD.js";
+} from "../chunk-UMKWXGO3.js";
 import {
   parseSSEStream
 } from "../chunk-Z7RBRCRN.js";
 import {
-  UPPError,
   doFetch,
   doStreamFetch,
   normalizeHttpError,
   resolveApiKey
-} from "../chunk-MOU4U3PO.js";
+} from "../chunk-5FEAOEXV.js";
+import {
+  UPPError
+} from "../chunk-DZQHVGNV.js";
 
 // src/providers/anthropic/transform.ts
 function transformRequest(request, modelId) {