ai-providers 2.0.2 → 2.1.3

package/.turbo/turbo-build.log

@@ -1,5 +1,4 @@
-
-
-> ai-providers@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-providers
-> tsc -p tsconfig.json
-
+
+> ai-providers@2.1.3 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-providers
+> tsc -p tsconfig.json
+

package/.turbo/turbo-test.log

@@ -0,0 +1,58 @@
+
+> ai-providers@2.1.1 test /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-providers
+> vitest
+
+
+ DEV  v2.1.9 /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-providers
+
+ ✓ src/llm.do.test.ts (42 tests) 29ms
+ ❯ src/providers/cloudflare.test.ts (45 tests | 2 failed) 10ms
+   × cloudflareEmbedding > model properties > has correct specification version 4ms
+     → expected 'v2' to be 'v1' // Object.is equality
+   × type safety > returns EmbeddingModel interface 0ms
+     → expected 'v2' to be 'v1' // Object.is equality
+ ✓ src/registry.test.ts (51 tests) 47ms
+ ✓ src/index.test.ts (37 tests) 5ms
+ ✓ src/integration.test.ts (26 tests | 6 skipped) 6ms
+
+⎯⎯⎯⎯⎯⎯⎯ Failed Tests 2 ⎯⎯⎯⎯⎯⎯⎯
+
+ FAIL  src/providers/cloudflare.test.ts > cloudflareEmbedding > model properties > has correct specification version
+AssertionError: expected 'v2' to be 'v1' // Object.is equality
+
+Expected: "v1"
+Received: "v2"
+
+ ❯ src/providers/cloudflare.test.ts:58:42
+     56|     it('has correct specification version', () => {
+     57|       const model = cloudflareEmbedding()
+     58|       expect(model.specificationVersion).toBe('v1')
+       |                                          ^
+     59|     })
+     60| 
+
+⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[1/2]⎯
+
+ FAIL  src/providers/cloudflare.test.ts > type safety > returns EmbeddingModel interface
+AssertionError: expected 'v2' to be 'v1' // Object.is equality
+
+Expected: "v1"
+Received: "v2"
+
+ ❯ src/providers/cloudflare.test.ts:559:40
+    557|   it('returns EmbeddingModel interface', () => {
+    558|     const model = cloudflareEmbedding()
+    559|     expect(model.specificationVersion).toBe('v1')
+       |                                        ^
+    560|     expect(typeof model.doEmbed).toBe('function')
+    561|   })
+
+⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯[2/2]⎯
+
+ Test Files  1 failed | 4 passed (5)
+      Tests  2 failed | 193 passed | 6 skipped (201)
+   Start at  06:45:31
+   Duration  438ms (transform 81ms, setup 0ms, collect 155ms, tests 97ms, environment 0ms, prepare 38ms)
+
+ FAIL  Tests failed. Watching for file changes...
+       press h to show help, press q to quit

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # ai-providers
 
+## 2.1.3
+
+### Patch Changes
+
+- Documentation and testing improvements
+  - Add deterministic AI testing suite with self-validating patterns
+  - Apply StoryBrand narrative to all package READMEs
+  - Update TESTING.md with four principles of deterministic AI testing
+  - Fix duplicate examples package name conflict
+
+- Updated dependencies
+  - language-models@2.1.3
+
+## 2.1.1
+
+### Patch Changes
+
+- language-models@2.1.1
+
+## 2.0.3
+
+### Patch Changes
+
+- Updated dependencies
+  - rpc.do@0.2.0
+  - language-models@2.0.3
+
 ## 2.0.2
 
 ### Patch Changes

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 .org.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,112 +1,157 @@
 # ai-providers
 
-Unified AI provider registry with Cloudflare AI Gateway support.
+**Stop juggling API keys. Start building.**
 
-## Installation
+You're building AI features, not managing provider configurations. But every model needs its own SDK, its own API key, its own quirks. OpenAI, Anthropic, Google, Llama, Mistral... each one is another dependency to install, another secret to manage, another authentication pattern to remember.
 
-```bash
-pnpm add ai-providers
+What if you could just say `model('sonnet')` and it worked?
+
+## The Problem
+
+```typescript
+// Before: Provider chaos
+import Anthropic from '@anthropic-ai/sdk'
+import OpenAI from 'openai'
+import { GoogleGenerativeAI } from '@google/generative-ai'
+
+const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY })
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
+const google = new GoogleGenerativeAI(process.env.GOOGLE_API_KEY)
+
+// Different APIs, different patterns, different headaches
 ```
 
-## Quick Start
+## The Solution
 
 ```typescript
+// After: One import, any model
 import { model } from 'ai-providers'
 import { generateText } from 'ai'
 
-// Simple aliases - just works
 const { text } = await generateText({
-  model: await model('sonnet'),  // → anthropic/claude-sonnet-4.5
+  model: await model('sonnet'),  // Just works
   prompt: 'Hello!'
 })
 
-// All these work too
-await model('opus')        // → anthropic/claude-opus-4.5
-await model('gpt-4o')      // → openai/gpt-4o
-await model('gemini')      // → google/gemini-2.5-flash
-await model('llama-70b')   // → meta-llama/llama-3.3-70b-instruct
-await model('mistral')     // → mistralai/mistral-large-2411
-await model('deepseek')    // → deepseek/deepseek-chat
+// Switch models in seconds
+await model('opus')        // Anthropic Claude Opus 4.5
+await model('gpt-4o')      // OpenAI GPT-4o
+await model('gemini')      // Google Gemini 2.5 Flash
+await model('llama-70b')   // Meta Llama 3.3 70B
+await model('deepseek')    // DeepSeek Chat
+await model('mistral')     // Mistral Large
 ```
 
-## How It Works
-
-### Smart Routing
-
-The `model()` function uses intelligent routing based on model data from OpenRouter:
-
-1. **Direct Provider Routing** - When `provider_model_id` is available and the provider matches (openai, anthropic, google), routes directly to the provider's native SDK. This enables provider-specific features like:
-   - Anthropic: MCP (Model Context Protocol), extended thinking
-   - OpenAI: Function calling, JSON mode, vision
-   - Google: Grounding, code execution
+## Quick Start
 
-2. **OpenRouter Fallback** - All other models route through OpenRouter, which provides:
-   - 200+ models from all major providers
-   - Unified API with consistent model ID format
-   - Automatic model ID translation
-   - Fallback routing if a provider is down
+### 1. Install
 
-Model aliases are resolved by the `language-models` package, which includes `provider_model_id` data from OpenRouter's API for direct routing when available.
+```bash
+pnpm add ai-providers ai
+```
 
-## Configuration
+### 2. Configure (choose one)
 
-### Cloudflare AI Gateway (Recommended)
+**Option A: Cloudflare AI Gateway (Recommended)**
 
-Set up a Cloudflare AI Gateway with stored secrets for each provider:
+One gateway, all providers, zero API key management:
 
 ```bash
 export AI_GATEWAY_URL=https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_name}
 export AI_GATEWAY_TOKEN=your-gateway-auth-token
 ```
 
-The gateway handles authentication - you don't need individual API keys.
+**Option B: Direct API Keys**
 
-### Direct API Keys (Fallback)
+```bash
+export OPENROUTER_API_KEY=sk-or-...  # Access 200+ models
+```
 
-If not using a gateway:
+### 3. Build
 
-```bash
-export OPENROUTER_API_KEY=sk-or-...
-export OPENAI_API_KEY=sk-...           # for embeddings
-export CLOUDFLARE_ACCOUNT_ID=...       # for CF embeddings
-export CLOUDFLARE_API_TOKEN=...        # for CF embeddings
+```typescript
+import { model } from 'ai-providers'
+import { generateText } from 'ai'
+
+const { text } = await generateText({
+  model: await model('sonnet'),
+  prompt: 'What is the meaning of life?'
+})
 ```
 
-## API
+That's it. No provider-specific SDKs. No authentication dance. Just AI.
 
-### `model(id: string)`
+## How It Works
 
-Get a language model by alias or full ID.
+`ai-providers` is your guide through the AI provider landscape:
 
-```typescript
-import { model } from 'ai-providers'
+```
+Your Code
+    │
+    ▼
+┌─────────────────┐
+│   ai-providers  │  Resolves aliases, routes intelligently
+└────────┬────────┘
+         │
+    ┌────┴────┐
+    ▼         ▼
+┌───────┐ ┌──────────┐
+│Direct │ │OpenRouter│
+│SDK    │ │          │
+└───────┘ └──────────┘
+    │         │
+    ▼         ▼
+Anthropic   200+ models
+OpenAI      from any
+Google      provider
+```
 
-// Aliases (requires language-models package)
-await model('opus')        // anthropic/claude-opus-4.5
-await model('sonnet')      // anthropic/claude-sonnet-4.5
-await model('gpt-4o')      // openai/gpt-4o
-await model('llama')       // meta-llama/llama-4-maverick
+**Smart routing** gives you the best of both worlds:
+- **Direct SDK access** for OpenAI, Anthropic, and Google - enabling provider-specific features like MCP, extended thinking, and structured outputs
+- **OpenRouter fallback** for everything else - 200+ models with automatic failover
 
-// Full IDs always work
+## Model Aliases
+
+Simple names that just work:
+
+| Alias | Model |
+|-------|-------|
+| `opus` | Claude Opus 4.5 |
+| `sonnet` | Claude Sonnet 4.5 |
+| `haiku` | Claude Haiku 4.5 |
+| `gpt-4o` | GPT-4o |
+| `o1`, `o3` | OpenAI o1, o3 |
+| `gemini` | Gemini 2.5 Flash |
+| `llama` | Llama 4 Maverick |
+| `deepseek`, `r1` | DeepSeek Chat, R1 |
+| `mistral` | Mistral Large |
+| `qwen` | Qwen3 235B |
+| `grok` | Grok 3 |
+
+Or use full model IDs:
+
+```typescript
 await model('anthropic/claude-opus-4.5')
 await model('mistralai/codestral-2501')
 await model('meta-llama/llama-3.3-70b-instruct')
 ```
 
-### `embeddingModel(id: string)`
-
-Get an embedding model.
+## Embeddings
 
 ```typescript
 import { embeddingModel } from 'ai-providers'
+import { embed } from 'ai'
 
-await embeddingModel('openai:text-embedding-3-small')
-await embeddingModel('cloudflare:@cf/baai/bge-m3')
+const model = await embeddingModel('openai:text-embedding-3-small')
+const { embedding } = await embed({ model, value: 'Hello world' })
+
+// Or use Cloudflare Workers AI
+const cfModel = await embeddingModel('cloudflare:@cf/baai/bge-m3')
 ```
 
-### `createRegistry(config?)`
+## Advanced Usage
 
-Create a custom provider registry.
+### Custom Registry
 
 ```typescript
 import { createRegistry } from 'ai-providers'
@@ -116,89 +161,42 @@ const registry = await createRegistry({
   gatewayToken: 'your-token'
 })
 
-// Use registry directly
-const model = registry.languageModel('openrouter:anthropic/claude-sonnet-4.5')
+const model = registry.languageModel('anthropic:claude-sonnet-4-5-20251101')
 ```
 
-### `getRegistry()`
+### Direct Provider Access
 
-Get the default singleton registry (lazily created).
+When you need provider-specific features:
 
 ```typescript
-import { getRegistry } from 'ai-providers'
+// Bedrock with bearer token auth
+await model('bedrock:us.anthropic.claude-3-5-sonnet-20241022-v2:0')
 
-const registry = await getRegistry()
+// Direct provider routing
+await model('openai:gpt-4o')
+await model('anthropic:claude-sonnet-4-5-20251101')
+await model('google:gemini-2.5-flash')
 ```
 
-## Model Aliases
-
-When `language-models` is installed, these aliases work:
-
-| Alias | Model ID |
-|-------|----------|
-| `opus` | anthropic/claude-opus-4.5 |
-| `sonnet` | anthropic/claude-sonnet-4.5 |
-| `haiku` | anthropic/claude-haiku-4.5 |
-| `gpt`, `gpt-4o` | openai/gpt-4o |
-| `o1`, `o3` | openai/o1, openai/o3 |
-| `gemini`, `flash` | google/gemini-2.5-flash |
-| `llama`, `llama-4` | meta-llama/llama-4-maverick |
-| `mistral` | mistralai/mistral-large-2411 |
-| `deepseek`, `r1` | deepseek/deepseek-chat, deepseek/deepseek-r1 |
-| `qwen` | qwen/qwen3-235b-a22b |
-| `grok` | x-ai/grok-3 |
-
-## Cloudflare Embeddings
-
-The package includes a Cloudflare Workers AI embedding provider:
-
-```typescript
-import { cloudflareEmbedding } from 'ai-providers/cloudflare'
-import { embed } from 'ai'
-
-const model = cloudflareEmbedding('@cf/baai/bge-m3')
-const { embedding } = await embed({ model, value: 'Hello world' })
-```
+## Why Cloudflare AI Gateway?
 
-Available models:
-- `@cf/baai/bge-m3` (default, multilingual)
-- `@cf/baai/bge-base-en-v1.5`
-- `@cf/baai/bge-large-en-v1.5`
-- `@cf/baai/bge-small-en-v1.5`
+When configured with AI Gateway:
 
-## Architecture
+1. **One token** authenticates everything - gateway injects provider keys from its secrets
+2. **Unified logging** - see all AI calls in one dashboard
+3. **Rate limiting** - protect your budget across providers
+4. **Caching** - reduce costs with intelligent response caching
+5. **Fallback routing** - automatic failover if a provider is down
 
-```
-┌─────────────────┐
-│   ai-functions  │  Uses model() for generation
-└────────┬────────┘
-         │
-┌────────▼────────┐
-│   ai-providers  │  Resolves aliases, smart routing
-└────────┬────────┘
-         │
-┌────────▼────────┐
-│ language-models │  Model data with provider_model_id
-└────────┬────────┘
-         │
-    ┌────┴────┐
-    │         │
-┌───▼───┐ ┌───▼───┐
-│Direct │ │OpenRou│  Direct: openai, anthropic, google
-│SDK    │ │ter    │  OpenRouter: all other providers
-└───────┘ └───────┘
-```
+No gateway? No problem. Set individual API keys and `ai-providers` works the same way.
 
-## Gateway Authentication
+## What You Get
 
-When using Cloudflare AI Gateway with stored secrets:
+With `ai-providers`, you can:
 
-1. Gateway URL points to your gateway endpoint
-2. `AI_GATEWAY_TOKEN` authenticates with the gateway
-3. Gateway injects provider API keys from its stored secrets
-4. No individual API keys needed in your app
+- **Ship faster** - one import, any model, zero config
+- **Stay flexible** - switch providers without code changes
+- **Build with confidence** - production-ready with Cloudflare AI Gateway
+- **Access everything** - 200+ models through OpenRouter, native SDK features through direct routing
 
-The package automatically:
-- Strips SDK-added API key headers
-- Adds `cf-aig-authorization` header for gateway auth
-- Lets the gateway inject the real API keys
+Stop wrestling with provider APIs. Start building AI features.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-providers",
-  "version": "2.0.2",
+  "version": "2.1.3",
   "description": "Unified AI provider registry with Cloudflare AI Gateway support",
   "type": "module",
   "main": "dist/index.js",
@@ -15,18 +15,9 @@
       "types": "./dist/providers/cloudflare.d.ts"
     }
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "dev": "tsc -p tsconfig.json --watch",
-    "test": "vitest",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint .",
-    "clean": "rm -rf dist"
-  },
   "dependencies": {
     "ai": "^5.0.0",
-    "language-models": "2.0.2",
-    "rpc.do": "^0.1.0"
+    "language-models": "2.1.3"
   },
   "optionalDependencies": {
     "@ai-sdk/amazon-bedrock": "^3.0.0",
@@ -49,5 +40,13 @@
     "gateway",
     "primitives"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist"
+  }
+}

package/src/index.js

@@ -0,0 +1,11 @@
+/**
+ * ai-providers - Unified AI Provider Registry
+ *
+ * Access multiple AI providers via simple string identifiers.
+ * Supports Cloudflare AI Gateway for unified routing and auth.
+ *
+ * @packageDocumentation
+ */
+export { createRegistry, getRegistry, configureRegistry, model, embeddingModel, DIRECT_PROVIDERS } from './registry.js';
+// Export llm.do WebSocket transport
+export { LLM, getLLM, createLLMFetch } from './llm.do.js';