ai-providers 0.2.0 → 0.3.0

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> ai-providers@0.3.0 build /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-providers
+> tsc -p tsconfig.json
+

package/.turbo/turbo-test.log

@@ -0,0 +1,47 @@
+
+> ai-providers@0.0.1 test /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-providers
+> vitest
+
+
+ DEV  v2.1.9 /Users/nathanclevenger/projects/mdx.org.ai/primitives/packages/ai-providers
+
+ ✓ src/llm.do.test.ts (42 tests) 44ms
+ ✓ src/providers/cloudflare.test.ts (45 tests) 7ms
+ ✓ src/registry.test.ts (51 tests) 37ms
+ ✓ src/index.test.ts (37 tests) 4ms
+ ✓ src/integration.test.ts (26 tests | 6 skipped) 8ms
+
+ Test Files  5 passed (5)
+      Tests  195 passed | 6 skipped (201)
+   Start at  14:14:37
+   Duration  786ms (transform 114ms, setup 0ms, collect 245ms, tests 101ms, environment 0ms, prepare 45ms)
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  ../language-models/dist/aliases.js 
+
+ ✓ src/registry.test.ts (51 tests) 116ms
+ ✓ src/integration.test.ts (26 tests | 6 skipped) 10ms
+ ✓ src/index.test.ts (37 tests) 7ms
+
+ Test Files  3 passed (3)
+      Tests  108 passed | 6 skipped (114)
+   Start at  14:22:55
+   Duration  436ms
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+c RERUN  ../language-models/dist/aliases.js 
+
+ ✓ src/registry.test.ts (51 tests) 36ms
+ ✓ src/integration.test.ts (26 tests | 6 skipped) 6ms
+ ✓ src/index.test.ts (37 tests) 5ms
+
+ Test Files  3 passed (3)
+      Tests  108 passed | 6 skipped (114)
+   Start at  14:31:30
+   Duration  121ms
+
+ PASS  Waiting for file changes...
+       press h to show help, press q to quit
+ ELIFECYCLE  Test failed. See above for more details.

package/README.md

@@ -0,0 +1,204 @@
+# ai-providers
+
+Unified AI provider registry with Cloudflare AI Gateway support.
+
+## Installation
+
+```bash
+pnpm add ai-providers
+```
+
+## Quick Start
+
+```typescript
+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
+  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
+```
+
+## 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
+
+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
+
+Model aliases are resolved by the `language-models` package, which includes `provider_model_id` data from OpenRouter's API for direct routing when available.
+
+## Configuration
+
+### Cloudflare AI Gateway (Recommended)
+
+Set up a Cloudflare AI Gateway with stored secrets for each provider:
+
+```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.
+
+### Direct API Keys (Fallback)
+
+If not using a gateway:
+
+```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
+```
+
+## API
+
+### `model(id: string)`
+
+Get a language model by alias or full ID.
+
+```typescript
+import { model } from 'ai-providers'
+
+// 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
+
+// Full IDs always work
+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.
+
+```typescript
+import { embeddingModel } from 'ai-providers'
+
+await embeddingModel('openai:text-embedding-3-small')
+await embeddingModel('cloudflare:@cf/baai/bge-m3')
+```
+
+### `createRegistry(config?)`
+
+Create a custom provider registry.
+
+```typescript
+import { createRegistry } from 'ai-providers'
+
+const registry = await createRegistry({
+  gatewayUrl: 'https://gateway.ai.cloudflare.com/v1/...',
+  gatewayToken: 'your-token'
+})
+
+// Use registry directly
+const model = registry.languageModel('openrouter:anthropic/claude-sonnet-4.5')
+```
+
+### `getRegistry()`
+
+Get the default singleton registry (lazily created).
+
+```typescript
+import { getRegistry } from 'ai-providers'
+
+const registry = await getRegistry()
+```
+
+## 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' })
+```
+
+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`
+
+## Architecture
+
+```
+┌─────────────────┐
+│   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
+└───────┘ └───────┘
+```
+
+## Gateway Authentication
+
+When using Cloudflare AI Gateway with stored secrets:
+
+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
+
+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

package/dist/index.d.ts

@@ -1 +1,12 @@
-export * from './provider';
+/**
+ * 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, type ProviderId, type DirectProvider, type ProviderConfig } from './registry.js';
+export { LLM, getLLM, createLLMFetch, type LLMConfig, type UniversalRequest, type UniversalCreated, type UniversalStream, type UniversalDone, type UniversalError, type GatewayMessage } from './llm.do.js';
+export type { Provider, ProviderRegistryProvider } from 'ai';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,KAAK,EACL,cAAc,EACd,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAA;AAGtB,OAAO,EACL,GAAG,EACH,MAAM,EACN,cAAc,EACd,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,aAAa,CAAA;AAGpB,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,MAAM,IAAI,CAAA"}

package/dist/index.js

@@ -1 +1,12 @@
-export * from './provider';
+/**
+ * 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';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,KAAK,EACL,cAAc,EACd,gBAAgB,EAIjB,MAAM,eAAe,CAAA;AAEtB,oCAAoC;AACpC,OAAO,EACL,GAAG,EACH,MAAM,EACN,cAAc,EAQf,MAAM,aAAa,CAAA"}

package/dist/llm.do.d.ts

@@ -0,0 +1,209 @@
+/**
+ * llm.do - Universal LLM Gateway WebSocket Transport
+ *
+ * Provides a persistent WebSocket connection to llm.do gateway
+ * that replaces repeated fetch calls with multiplexed requests.
+ *
+ * Benefits:
+ * - Persistent connection (no repeated handshakes)
+ * - Lower latency for multiple requests
+ * - Unified authentication across all providers
+ * - Automatic provider routing
+ *
+ * @packageDocumentation
+ */
+/**
+ * WebSocket message types (Cloudflare AI Gateway protocol)
+ */
+export interface UniversalRequest {
+    type: 'universal.create';
+    request: {
+        eventId: string;
+        provider: string;
+        endpoint: string;
+        headers?: Record<string, string>;
+        query?: Record<string, unknown>;
+    };
+}
+export interface UniversalCreated {
+    type: 'universal.created';
+    eventId: string;
+    metadata?: {
+        cacheStatus?: string;
+        requestId?: string;
+    };
+    response: {
+        status: number;
+        headers?: Record<string, string>;
+        body: unknown;
+    };
+}
+export interface UniversalStream {
+    type: 'universal.stream';
+    eventId: string;
+    chunk: string | unknown;
+}
+export interface UniversalDone {
+    type: 'universal.done';
+    eventId: string;
+    metadata?: {
+        cacheStatus?: string;
+        requestId?: string;
+        usage?: {
+            promptTokens?: number;
+            completionTokens?: number;
+            totalTokens?: number;
+        };
+    };
+}
+export interface UniversalError {
+    type: 'universal.error';
+    eventId: string;
+    error: {
+        message: string;
+        code?: string;
+    };
+}
+export type GatewayMessage = UniversalCreated | UniversalStream | UniversalDone | UniversalError;
+/**
+ * Connection state
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'closed';
+/**
+ * llm.do configuration
+ */
+export interface LLMConfig {
+    /** llm.do WebSocket URL (default: wss://llm.do/ws) */
+    url?: string;
+    /** Authentication token (DO_TOKEN) */
+    token: string;
+    /** Auto-reconnect on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Max reconnect attempts (default: 5) */
+    maxReconnectAttempts?: number;
+    /** Reconnect delay in ms (default: 1000) */
+    reconnectDelay?: number;
+}
+/**
+ * llm.do WebSocket client
+ *
+ * Maintains a persistent WebSocket connection and provides a fetch-compatible
+ * interface that routes requests through llm.do gateway.
+ *
+ * @example
+ * ```ts
+ * const llm = new LLM({ token: process.env.DO_TOKEN })
+ *
+ * await llm.connect()
+ *
+ * // Use as fetch replacement
+ * const response = await llm.fetch('https://api.openai.com/v1/chat/completions', {
+ *   method: 'POST',
+ *   body: JSON.stringify({ ... })
+ * })
+ * ```
+ */
+export declare class LLM {
+    private ws;
+    private state;
+    private pendingRequests;
+    private connectPromise;
+    private reconnectAttempts;
+    private eventIdCounter;
+    readonly config: Required<LLMConfig>;
+    constructor(config: LLMConfig);
+    /**
+     * Get the WebSocket URL
+     */
+    get wsUrl(): string;
+    /**
+     * Get current connection state
+     */
+    get connectionState(): ConnectionState;
+    /**
+     * Check if connected
+     */
+    get isConnected(): boolean;
+    /**
+     * Connect to llm.do
+     */
+    connect(): Promise<void>;
+    private doConnect;
+    private handleDisconnect;
+    private handleMessage;
+    /**
+     * Generate a unique event ID
+     */
+    private generateEventId;
+    /**
+     * Detect provider from URL
+     */
+    private detectProvider;
+    /**
+     * Extract endpoint path from URL
+     */
+    private extractEndpoint;
+    /**
+     * Fetch-compatible interface that routes through llm.do
+     *
+     * @example
+     * ```ts
+     * const response = await llm.fetch('https://api.openai.com/v1/chat/completions', {
+     *   method: 'POST',
+     *   headers: { 'Content-Type': 'application/json' },
+     *   body: JSON.stringify({
+     *     model: 'gpt-4o',
+     *     messages: [{ role: 'user', content: 'Hello!' }]
+     *   })
+     * })
+     * ```
+     */
+    fetch(url: string | URL, init?: RequestInit): Promise<Response>;
+    /**
+     * Create a fetch function bound to this connection
+     *
+     * Returns a function that can be used as a drop-in replacement for fetch
+     * in AI SDK provider configurations.
+     */
+    createFetch(): typeof fetch;
+    /**
+     * Close the WebSocket connection
+     */
+    close(): void;
+}
+/**
+ * Get or create the default llm.do connection
+ *
+ * Uses environment variables for configuration:
+ * - LLM_URL: WebSocket URL (default: wss://llm.do/ws)
+ * - DO_TOKEN: Authentication token
+ *
+ * @example
+ * ```ts
+ * const llm = getLLM()
+ * await llm.connect()
+ * const response = await llm.fetch(url, options)
+ * ```
+ */
+export declare function getLLM(config?: LLMConfig): LLM;
+/**
+ * Create a fetch function that uses llm.do WebSocket
+ *
+ * Drop-in replacement for the custom fetch in provider configuration.
+ * Automatically connects on first use.
+ *
+ * @example
+ * ```ts
+ * import { createOpenAI } from '@ai-sdk/openai'
+ * import { createLLMFetch } from 'ai-providers'
+ *
+ * const openai = createOpenAI({
+ *   apiKey: 'llm.do', // Placeholder - llm.do handles auth
+ *   baseURL: 'https://api.openai.com/v1',
+ *   fetch: createLLMFetch()
+ * })
+ * ```
+ */
+export declare function createLLMFetch(config?: LLMConfig): typeof fetch;
+export {};
+//# sourceMappingURL=llm.do.d.ts.map

package/dist/llm.do.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.do.d.ts","sourceRoot":"","sources":["../src/llm.do.ts"],"names":[],"mappings":"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"}