@providerprotocol/ai 0.0.18 → 0.0.20

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
 
-// Streaming
+| 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
+
+```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
+
+```typescript
+import { Image } from '@providerprotocol/ai';
+
+const img = await Image.fromPath('./photo.png');
+const turn = await claude.generate([img, 'What is in this image?']);
+```
 
-Generate vector embeddings from text using the unified `embedding()` interface.
+## 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,89 +133,329 @@ 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;
+```
+
+## Image Generation
+
+```typescript
+import { image } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
+
+const dalle = image({ model: openai('dall-e-3') });
+const result = await dalle.generate('A sunset over mountains');
+
+console.log(result.images[0].image.toBase64());
 ```
 
-### Provider-Specific Parameters
+### With Parameters
+
+```typescript
+const hd = image({
+  model: openai('dall-e-3'),
+  params: { size: '1792x1024', quality: 'hd', style: 'natural' },
+});
+```
 
-Each provider supports its native parameters passed through unchanged:
+### Image Editing
 
 ```typescript
-// OpenAI: dimensions, encoding_format, user
-embedding({
-  model: openai('text-embedding-3-large'),
-  params: { dimensions: 1024, encoding_format: 'float' },
+import { image, Image } from '@providerprotocol/ai';
+
+const editor = image({ model: openai('dall-e-2') });
+
+const source = await Image.fromPath('./photo.png');
+const mask = await Image.fromPath('./mask.png');
+
+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';
 
-// Google: taskType, title, outputDimensionality
-embedding({
-  model: google('text-embedding-004'),
+const instance = llm({
+  model: openai('gpt-4o'),
+  config: {
+    apiKey: new RoundRobinKeys(['sk-key1', 'sk-key2']),
+    timeout: 30000,
+    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
+  },
   params: {
-    taskType: 'SEMANTIC_SIMILARITY',
-    outputDimensionality: 256,
+    temperature: 0.7,
+    max_tokens: 1000,
   },
+  system: 'You are a helpful assistant.',
 });
+```
 
-// Ollama: truncate, keep_alive, options
-embedding({
-  model: ollama('nomic-embed-text'),
-  params: { truncate: true, keep_alive: '5m' },
-});
+### Key Strategies
 
-// OpenRouter: dimensions, encoding_format, input_type
-embedding({
-  model: openrouter('openai/text-embedding-3-small'),
-  params: { dimensions: 512 },
-});
+```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())
 ```
 
-## Providers
+### Retry Strategies
+
+```typescript
+import {
+  ExponentialBackoff,
+  LinearBackoff,
+  NoRetry,
+  TokenBucket,
+  RetryAfterStrategy,
+} from '@providerprotocol/ai/http';
 
-| 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 | - |
+// Exponential: 1s, 2s, 4s... (default)
+new ExponentialBackoff({ maxAttempts: 5, baseDelay: 1000, maxDelay: 30000 })
 
-### xAI API Modes
+// Linear: 1s, 2s, 3s...
+new LinearBackoff({ maxAttempts: 3, delay: 1000 })
 
-xAI supports three API modes:
+// 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
-import { xai } from '@providerprotocol/ai/xai';
+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');
+```
 
-// Chat Completions API (OpenAI-compatible, default)
-const grok = llm({ model: xai('grok-3-fast') });
+## Thread Management
 
-// Responses API (stateful, OpenAI Responses-compatible)
-const grok = llm({ model: xai('grok-3-fast', { api: 'responses' }) });
+```typescript
+import { Thread } from '@providerprotocol/ai';
 
-// Messages API (Anthropic-compatible)
-const grok = llm({ model: xai('grok-3-fast', { api: 'messages' }) });
+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')));
 ```
 
-## Configuration
+## 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`
+
+## API Gateway / Proxy
+
+Build AI API gateways with your own authentication. Users authenticate with your platform - AI provider keys stay hidden on the server.
+
+> **Security Note:** The proxy works without any configuration, but this means **no authentication by default**. Always add your own auth layer in production - the examples below show how.
+
+### Server (Bun/Deno/Cloudflare Workers)
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
 import { ExponentialBackoff, RoundRobinKeys } from '@providerprotocol/ai/http';
+import { parseBody, toJSON, toSSE, toError } from '@providerprotocol/ai/proxy';
 
-const instance = llm({
-  model: openai('gpt-4o'),
+// Server manages AI provider keys - users never see them
+const claude = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
   config: {
-    apiKey: 'sk-...',
-    timeout: 30000,
+    apiKey: new RoundRobinKeys([process.env.ANTHROPIC_KEY_1!, process.env.ANTHROPIC_KEY_2!]),
+    retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
+  },
+});
+
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    // Authenticate with YOUR platform credentials
+    const token = req.headers.get('Authorization')?.replace('Bearer ', '');
+    const user = await validatePlatformToken(token ?? '');
+    if (!user) return toError('Unauthorized', 401);
+
+    // Rate limit, track usage, bill user, etc.
+    await trackUsage(user.id);
+
+    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
+
+Clients authenticate with your platform token. They get automatic retry on network failures to your proxy.
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { proxy } from '@providerprotocol/ai/proxy';
+import { ExponentialBackoff } from '@providerprotocol/ai/http';
+
+const claude = llm({
+  model: proxy('https://api.yourplatform.com/ai'),
+  config: {
+    headers: { 'Authorization': 'Bearer user-platform-token' },
     retryStrategy: new ExponentialBackoff({ maxAttempts: 3 }),
+    timeout: 30000,
   },
-  params: { temperature: 0.7, max_tokens: 1000 },
-  system: 'You are helpful.',
 });
+
+const turn = await claude.generate('Hello!');
+```
+
+### Framework Adapters
+
+Server adapters for Express, Fastify, and Nuxt/H3:
+
+```typescript
+// Express
+import { express as expressAdapter } from '@providerprotocol/ai/proxy/server';
+app.post('/ai', authMiddleware, async (req, res) => {
+  const { messages, system, params } = parseBody(req.body);
+  if (params?.stream) {
+    expressAdapter.streamSSE(claude.stream(messages, { system }), res);
+  } else {
+    expressAdapter.sendJSON(await claude.generate(messages, { system }), res);
+  }
+});
+
+// Fastify
+import { fastify as fastifyAdapter } from '@providerprotocol/ai/proxy/server';
+app.post('/ai', async (request, reply) => {
+  const { messages, system, params } = parseBody(request.body);
+  if (params?.stream) {
+    return fastifyAdapter.streamSSE(claude.stream(messages, { system }), reply);
+  }
+  return fastifyAdapter.sendJSON(await claude.generate(messages, { system }), reply);
+});
+
+// Nuxt/H3 (server/api/ai.post.ts)
+import { h3 as h3Adapter } from '@providerprotocol/ai/proxy/server';
+export default defineEventHandler(async (event) => {
+  const { messages, system, params } = parseBody(await readBody(event));
+  if (params?.stream) {
+    return h3Adapter.streamSSE(claude.stream(messages, { system }), event);
+  }
+  return h3Adapter.sendJSON(await claude.generate(messages, { system }), event);
+});
+```
+
+**What this enables:**
+- Users auth with your platform credentials (JWT, API keys, sessions)
+- You manage/rotate AI provider keys centrally
+- Per-user rate limiting, usage tracking, billing
+- Model access control (different users get different models)
+- Request/response logging, content filtering
+- Double-layer retry: client retries to proxy, server retries to AI provider
+
+## 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

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

@@ -11,14 +11,14 @@ import {
   parseSSEStream
 } from "../chunk-Z7RBRCRN.js";
 import {
-  doFetch,
-  doStreamFetch,
-  normalizeHttpError,
   resolveApiKey
-} from "../chunk-5FEAOEXV.js";
+} from "../chunk-P5IRTEM5.js";
 import {
-  UPPError
-} from "../chunk-DZQHVGNV.js";
+  UPPError,
+  doFetch,
+  doStreamFetch,
+  normalizeHttpError
+} from "../chunk-U3FZWV4U.js";
 
 // src/providers/anthropic/transform.ts
 function transformRequest(request, modelId) {