ai-sdk-provider-env 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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

@@ -0,0 +1,275 @@
+> [中文](./README_zh.md)
+
+# ai-sdk-provider-env
+
+A dynamic, environment-variable-driven provider for [Vercel AI SDK](https://sdk.vercel.ai/). Resolves AI provider configuration from env var conventions at runtime, so you can switch models without touching code.
+
+[![npm version](https://img.shields.io/npm/v/ai-sdk-provider-env)](https://www.npmjs.com/package/ai-sdk-provider-env)
+[![license](https://img.shields.io/npm/l/ai-sdk-provider-env)](./LICENSE)
+
+## Motivation
+
+Using multiple AI providers with Vercel AI SDK means importing each SDK, configuring API keys and base URLs, and wiring everything together — per provider, per project. Switching providers requires code changes.
+
+`ai-sdk-provider-env` eliminates this boilerplate. Define provider configurations through environment variables, resolve them at runtime. Add a new provider by setting env vars, switch models by changing a string — no code changes needed.
+
+## Features
+
+- Resolve provider config (base URL, API key, compatibility mode) from environment variables automatically
+- Built-in presets for popular providers, so you only need to set an API key
+- Supports OpenAI, Anthropic, and any OpenAI-compatible API
+- Implements `ProviderV3`, plugs directly into `createProviderRegistry`
+- Provider instances are cached, no redundant initialization
+- Fully customizable: custom fetch, env-based headers, custom separator, code-based configs
+
+## Installation
+
+```bash
+pnpm add ai-sdk-provider-env
+```
+
+Install provider SDKs as needed:
+
+```bash
+pnpm add @ai-sdk/openai            # for OpenAI and OpenAI-compatible
+pnpm add @ai-sdk/anthropic         # for Anthropic
+pnpm add @ai-sdk/openai-compatible # for generic OpenAI-compatible APIs
+```
+
+## Quick Start
+
+```ts
+import { createProviderRegistry, generateText } from 'ai'
+import { envProvider } from 'ai-sdk-provider-env'
+
+const registry = createProviderRegistry({
+  env: envProvider(),
+})
+
+// Use a preset: only API_KEY is required
+// OPENAI_PRESET=openai
+// OPENAI_API_KEY=sk-xxx
+const model = registry.languageModel('env:openai/gpt-4o')
+
+const { text } = await generateText({ model, prompt: 'Hello!' })
+```
+
+Any env var prefix is a config set. Two endpoints? Two prefixes, zero code changes:
+
+```bash
+# .env
+FAST_BASE_URL=https://fast-api.example.com/v1
+FAST_API_KEY=key-fast
+
+SMART_BASE_URL=https://smart-api.example.com/v1
+SMART_API_KEY=key-smart
+```
+
+```ts
+const draft = await generateText({
+  model: registry.languageModel('env:fast/llama-3-8b'),
+  prompt: 'Write a story',
+})
+
+const review = await generateText({
+  model: registry.languageModel('env:smart/gpt-4o'),
+  prompt: `Review this: ${draft.text}`,
+})
+```
+
+## Environment Variable Convention
+
+The model ID format is `{configSet}/{modelId}`. The config set name maps to an env var prefix (uppercased).
+
+With the default separator `_`, a config set reads these variables (`[MYAI]` = your config set name, uppercased):
+
+| Variable | Required | Description |
+|---|---|---|
+| `[MYAI]_API_KEY` | Yes | API key |
+| `[MYAI]_BASE_URL` | Yes (unless preset is set) | API base URL |
+| `[MYAI]_PRESET` | No | Built-in preset name (e.g. `openai`) |
+| `[MYAI]_COMPATIBLE` | No | Compatibility mode (default: `openai`) |
+| `[MYAI]_HEADERS` | No | Custom HTTP headers (JSON format) |
+
+When `PRESET` is set, `BASE_URL` and `COMPATIBLE` become optional and fall back to the preset's values.
+
+**Compatibility modes:**
+
+| Value | Behavior |
+|---|---|
+| `openai` | Uses `@ai-sdk/openai` (default) |
+| `anthropic` | Uses `@ai-sdk/anthropic` |
+| any other string | Uses `@ai-sdk/openai-compatible` with that string as the provider name |
+
+## Built-in Presets
+
+| Preset name | Base URL | Compatible |
+|---|---|---|
+| `openai` | `https://api.openai.com/v1` | `openai` |
+| `anthropic` | `https://api.anthropic.com` | `anthropic` |
+| `deepseek` | `https://api.deepseek.com` | `openai` |
+| `zhipu` | `https://open.bigmodel.cn/api/paas/v4` | `openai` |
+| `groq` | `https://api.groq.com/openai/v1` | `openai` |
+| `together` | `https://api.together.xyz/v1` | `openai` |
+| `fireworks` | `https://api.fireworks.ai/inference/v1` | `openai` |
+| `mistral` | `https://api.mistral.ai/v1` | `openai` |
+| `moonshot` | `https://api.moonshot.cn/v1` | `openai` |
+| `perplexity` | `https://api.perplexity.ai` | `openai` |
+| `openrouter` | `https://openrouter.ai/api/v1` | `openai` |
+| `siliconflow` | `https://api.siliconflow.cn/v1` | `openai` |
+
+## API Reference
+
+### `envProvider(options?)`
+
+Returns a `ProviderV3` instance.
+
+```ts
+import { envProvider } from 'ai-sdk-provider-env'
+
+const provider = envProvider(options)
+```
+
+**Options** (`EnvProviderOptions`):
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `separator` | `string` | `'_'` | Separator between the prefix and the variable name |
+| `configs` | `Record<string, ConfigSetEntry>` | `undefined` | Explicit config sets (takes precedence over env vars) |
+| `defaults` | `EnvProviderDefaults` | `undefined` | Global defaults applied to all providers (can be overridden per config set) |
+
+**`EnvProviderDefaults`:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `fetch` | `typeof globalThis.fetch` | `undefined` | Custom fetch implementation passed to all created providers |
+| `headers` | `Record<string, string>` | `undefined` | Default HTTP headers for all providers (overridden by config-set headers) |
+
+**`ConfigSetEntry`:**
+
+```ts
+interface ConfigSetEntry {
+  apiKey: string
+  preset?: string
+  baseURL?: string
+  compatible?: string // 'openai' | 'anthropic' | any string (default: 'openai')
+  headers?: Record<string, string>
+}
+```
+
+**Model ID format:**
+
+```
+{configSet}/{modelId}
+```
+
+Examples: `openai/gpt-4o`, `anthropic/claude-sonnet-4-20250514`, `myapi/some-model`.
+
+## Advanced Usage
+
+### Custom separator
+
+If single underscores conflict with your naming scheme, use double underscores or any other string:
+
+```ts
+const provider = envProvider({ separator: '__' })
+
+// Now reads: OPENAI__BASE_URL, OPENAI__API_KEY, OPENAI__PRESET, OPENAI__COMPATIBLE
+```
+
+### Code-based configs
+
+Skip env vars entirely and pass config directly. This takes the highest precedence:
+
+```ts
+const provider = envProvider({
+  configs: {
+    openai: {
+      baseURL: 'https://api.openai.com/v1',
+      apiKey: process.env.OPENAI_KEY!,
+      compatible: 'openai',
+    },
+    claude: {
+      baseURL: 'https://api.anthropic.com',
+      apiKey: process.env.ANTHROPIC_KEY!,
+      compatible: 'anthropic',
+    },
+    deepseek: {
+      preset: 'deepseek',
+      apiKey: process.env.DEEPSEEK_KEY!,
+    },
+  },
+})
+
+const model = provider.languageModel('openai/gpt-4o')
+```
+
+### Custom fetch
+
+Pass a custom fetch implementation to all providers. Useful for proxies, logging, or test mocks:
+
+```ts
+const provider = envProvider({ defaults: { fetch: myCustomFetch } })
+```
+
+### Default headers
+
+Set HTTP headers that apply to all providers. Per-config-set headers (from env vars or code configs) override defaults with the same key:
+
+```ts
+const provider = envProvider({
+  defaults: {
+    headers: { 'X-App-Name': 'my-app', 'X-Request-Source': 'server' },
+  },
+})
+```
+
+### Custom headers via env vars
+
+Set per-config-set HTTP headers using the `HEADERS` env var. The value must be valid JSON:
+
+```bash
+OPENAI_HEADERS={"X-Custom":"value","X-Request-Source":"my-app"}
+```
+
+These headers are merged into every request made by that config set's provider. When combined with `defaults.headers`, config-set headers take precedence for the same key.
+
+### Using with `createProviderRegistry`
+
+`envProvider()` implements `ProviderV3`, so it works directly with `createProviderRegistry`:
+
+```ts
+import { createProviderRegistry, generateText } from 'ai'
+import { envProvider } from 'ai-sdk-provider-env'
+
+const registry = createProviderRegistry({
+  env: envProvider(),
+})
+
+// Language model
+const model = registry.languageModel('env:openai/gpt-4o')
+
+// Embedding model
+const embedder = registry.embeddingModel('env:openai/text-embedding-3-small')
+
+// Image model
+const imageModel = registry.imageModel('env:openai/dall-e-3')
+
+const { text } = await generateText({
+  model,
+  prompt: 'Hello!',
+})
+```
+
+The model ID format inside the registry is `{registryKey}:{configSet}/{modelId}`. With the setup above, `env:openai/gpt-4o` means config set `openai`, model `gpt-4o`.
+
+You can also mount multiple providers side by side:
+
+```ts
+import { createOpenAI } from '@ai-sdk/openai'
+
+const registry = createProviderRegistry({
+  env: envProvider(),
+  openai: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+})
+```

package/dist/index.cjs

@@ -0,0 +1,359 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let node_process = require("node:process");
+node_process = __toESM(node_process);
+let _ai_sdk_provider = require("@ai-sdk/provider");
+
+//#region src/factories.ts
+/**
+* Create an OpenAI provider.
+*
+* Dynamically requires `@ai-sdk/openai`, so it only needs to be installed when actually used.
+*/
+function createOpenAIProvider(opts) {
+	try {
+		const { createOpenAI } = require("@ai-sdk/openai");
+		return createOpenAI(opts);
+	} catch {
+		throw new Error("[ai-sdk-provider-env] openai compatibility mode requires @ai-sdk/openai. Run: npm install @ai-sdk/openai");
+	}
+}
+/**
+* Create an Anthropic provider.
+*
+* Dynamically requires `@ai-sdk/anthropic`, so it only needs to be installed when actually used.
+*/
+function createAnthropicProvider(opts) {
+	try {
+		const { createAnthropic } = require("@ai-sdk/anthropic");
+		return createAnthropic(opts);
+	} catch {
+		throw new Error("[ai-sdk-provider-env] anthropic compatibility mode requires @ai-sdk/anthropic. Run: npm install @ai-sdk/anthropic");
+	}
+}
+/**
+* Create an OpenAI Compatible provider.
+*
+* Dynamically requires `@ai-sdk/openai-compatible`, so it only needs to be installed when actually used.
+*/
+function createOpenAICompatibleProvider(opts) {
+	try {
+		const { createOpenAICompatible } = require("@ai-sdk/openai-compatible");
+		return createOpenAICompatible(opts);
+	} catch {
+		throw new Error("[ai-sdk-provider-env] openai-compatible mode requires @ai-sdk/openai-compatible. Run: npm install @ai-sdk/openai-compatible");
+	}
+}
+
+//#endregion
+//#region src/presets.ts
+/**
+* Built-in preset configurations for common providers.
+*
+* When using a preset, only `{PREFIX}__PRESET` and `{PREFIX}__API_KEY`
+* are required; `BASE_URL` and `COMPATIBLE` are provided by the preset.
+*/
+const builtinPresets = {
+	openai: {
+		baseURL: "https://api.openai.com/v1",
+		compatible: "openai"
+	},
+	anthropic: {
+		baseURL: "https://api.anthropic.com",
+		compatible: "anthropic"
+	},
+	deepseek: {
+		baseURL: "https://api.deepseek.com",
+		compatible: "openai"
+	},
+	zhipu: {
+		baseURL: "https://open.bigmodel.cn/api/paas/v4",
+		compatible: "openai"
+	},
+	groq: {
+		baseURL: "https://api.groq.com/openai/v1",
+		compatible: "openai"
+	},
+	together: {
+		baseURL: "https://api.together.xyz/v1",
+		compatible: "openai"
+	},
+	fireworks: {
+		baseURL: "https://api.fireworks.ai/inference/v1",
+		compatible: "openai"
+	},
+	mistral: {
+		baseURL: "https://api.mistral.ai/v1",
+		compatible: "openai"
+	},
+	moonshot: {
+		baseURL: "https://api.moonshot.cn/v1",
+		compatible: "openai"
+	},
+	perplexity: {
+		baseURL: "https://api.perplexity.ai",
+		compatible: "openai"
+	},
+	openrouter: {
+		baseURL: "https://openrouter.ai/api/v1",
+		compatible: "openai"
+	},
+	siliconflow: {
+		baseURL: "https://api.siliconflow.cn/v1",
+		compatible: "openai"
+	}
+};
+
+//#endregion
+//#region src/env-provider.ts
+/**
+* Default factories that delegate to the real implementations in `factories.ts`.
+*/
+const defaultFactories = {
+	createOpenAI: createOpenAIProvider,
+	createAnthropic: createAnthropicProvider,
+	createOpenAICompatible: createOpenAICompatibleProvider
+};
+/**
+* Testable core implementation that accepts injected provider factories.
+*
+* In tests, call this function directly with fake factories
+* to avoid module mocking entirely.
+*/
+function createEnvProvider(factories, options = {}) {
+	const separator = options.separator ?? "_";
+	const defaultFetch = options.defaults?.fetch;
+	const defaultHeaders = options.defaults?.headers;
+	const cache = /* @__PURE__ */ new Map();
+	/**
+	* Resolve baseURL and compatible from a preset name.
+	*/
+	function resolvePreset(presetName) {
+		const preset = builtinPresets[presetName];
+		if (!preset) {
+			const available = Object.keys(builtinPresets).join(", ");
+			throw new Error(`[ai-sdk-provider-env] Unknown preset "${presetName}". Available presets: ${available}`);
+		}
+		return {
+			baseURL: preset.baseURL,
+			compatible: preset.compatible ?? "openai"
+		};
+	}
+	/**
+	* Resolve config set configuration from explicit configs, presets, or environment variables.
+	*/
+	function resolveConfig(configSet) {
+		if (options.configs?.[configSet]) {
+			const config = options.configs[configSet];
+			if (config.preset) {
+				const preset = resolvePreset(config.preset);
+				return {
+					baseURL: config.baseURL ?? preset.baseURL,
+					apiKey: config.apiKey,
+					compatible: config.compatible ?? preset.compatible,
+					...config.headers && { headers: config.headers }
+				};
+			}
+			if (!config.baseURL) throw new Error(`[ai-sdk-provider-env] Missing baseURL in config for "${configSet}" (or set preset to use a built-in preset)`);
+			return {
+				baseURL: config.baseURL,
+				apiKey: config.apiKey,
+				compatible: config.compatible ?? "openai",
+				...config.headers && { headers: config.headers }
+			};
+		}
+		const prefix = configSet.toUpperCase();
+		const env = (key) => node_process.default.env[`${prefix}${separator}${key}`];
+		const apiKey = env("API_KEY");
+		if (!apiKey) throw new Error(`[ai-sdk-provider-env] Missing env var ${prefix}${separator}API_KEY`);
+		const headersRaw = env("HEADERS");
+		let headers;
+		if (headersRaw) try {
+			headers = JSON.parse(headersRaw);
+		} catch {
+			throw new Error(`[ai-sdk-provider-env] Invalid JSON in ${prefix}${separator}HEADERS: ${headersRaw}`);
+		}
+		const presetName = env("PRESET");
+		if (presetName) {
+			const preset = resolvePreset(presetName);
+			return {
+				baseURL: env("BASE_URL") ?? preset.baseURL,
+				apiKey,
+				compatible: env("COMPATIBLE") ?? preset.compatible,
+				...headers && { headers }
+			};
+		}
+		const baseURL = env("BASE_URL");
+		if (!baseURL) throw new Error(`[ai-sdk-provider-env] Missing env var ${prefix}${separator}BASE_URL (or set ${prefix}${separator}PRESET to use a preset)`);
+		return {
+			baseURL,
+			apiKey,
+			compatible: env("COMPATIBLE") ?? "openai",
+			...headers && { headers }
+		};
+	}
+	/**
+	* Create the underlying provider based on the compatibility mode.
+	*/
+	function createUnderlying(config) {
+		const { baseURL, apiKey, compatible, headers } = config;
+		const mergedHeaders = defaultHeaders || headers ? {
+			...defaultHeaders,
+			...headers
+		} : void 0;
+		const baseOpts = {
+			baseURL,
+			apiKey,
+			...mergedHeaders && { headers: mergedHeaders },
+			...defaultFetch && { fetch: defaultFetch }
+		};
+		switch (compatible) {
+			case "openai": return factories.createOpenAI(baseOpts);
+			case "anthropic": return factories.createAnthropic(baseOpts);
+			default: return factories.createOpenAICompatible({
+				name: compatible,
+				...baseOpts
+			});
+		}
+	}
+	/**
+	* Get or create a cached provider for the given config set.
+	*/
+	function getProvider(configSet) {
+		const key = configSet.toUpperCase();
+		const cached = cache.get(key);
+		if (cached) return cached;
+		const provider = createUnderlying(resolveConfig(configSet));
+		cache.set(key, provider);
+		return provider;
+	}
+	/**
+	* Parse a model ID. The first `/` separates the config set name from the actual model ID.
+	*/
+	function parseModelId(modelId) {
+		const slashIndex = modelId.indexOf("/");
+		if (slashIndex === -1) throw new Error(`[ai-sdk-provider-env] Invalid model ID "${modelId}". Expected format: "{configSet}/{modelId}", e.g. "zhipu/glm-4"`);
+		return {
+			configSet: modelId.slice(0, slashIndex),
+			model: modelId.slice(slashIndex + 1)
+		};
+	}
+	return {
+		specificationVersion: "v3",
+		languageModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			return getProvider(configSet).languageModel(model);
+		},
+		embeddingModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			return getProvider(configSet).embeddingModel(model);
+		},
+		imageModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			return getProvider(configSet).imageModel(model);
+		},
+		textEmbeddingModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			const provider = getProvider(configSet);
+			if (!provider.textEmbeddingModel) throw new _ai_sdk_provider.NoSuchModelError({
+				modelId,
+				modelType: "embeddingModel"
+			});
+			return provider.textEmbeddingModel(model);
+		},
+		transcriptionModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			const provider = getProvider(configSet);
+			if (!provider.transcriptionModel) throw new _ai_sdk_provider.NoSuchModelError({
+				modelId,
+				modelType: "transcriptionModel"
+			});
+			return provider.transcriptionModel(model);
+		},
+		speechModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			const provider = getProvider(configSet);
+			if (!provider.speechModel) throw new _ai_sdk_provider.NoSuchModelError({
+				modelId,
+				modelType: "speechModel"
+			});
+			return provider.speechModel(model);
+		},
+		rerankingModel(modelId) {
+			const { configSet, model } = parseModelId(modelId);
+			const provider = getProvider(configSet);
+			if (!provider.rerankingModel) throw new _ai_sdk_provider.NoSuchModelError({
+				modelId,
+				modelType: "rerankingModel"
+			});
+			return provider.rerankingModel(model);
+		}
+	};
+}
+/**
+* Create a dynamic, environment-variable-driven AI SDK provider.
+*
+* Automatically resolves provider configurations from env var naming conventions,
+* with built-in preset support for quick setup.
+*
+* Env var convention (using config set `ZHIPU` with default separator `_` as example):
+* - `ZHIPU_PRESET`     — use a built-in preset (BASE_URL and COMPATIBLE become optional)
+* - `ZHIPU_BASE_URL`   — API base URL
+* - `ZHIPU_API_KEY`    — API key (required)
+* - `ZHIPU_COMPATIBLE` — compatibility mode (defaults to `'openai'`)
+* - `ZHIPU_HEADERS`    — custom HTTP headers (JSON format)
+*
+* @example
+* ```ts
+* import { createProviderRegistry } from 'ai'
+* import { envProvider } from 'ai-sdk-provider-env'
+*
+* const registry = createProviderRegistry({
+*   env: envProvider(),
+* })
+*
+* // Use a preset (only API_KEY is required)
+* // DEEPSEEK_PRESET=deepseek
+* // DEEPSEEK_API_KEY=sk-xxx
+* const model = registry.languageModel('env:deepseek/deepseek-chat')
+*
+* // Specify all parameters manually
+* // MYAPI_BASE_URL=https://api.example.com/v1
+* // MYAPI_API_KEY=xxx
+* const model2 = registry.languageModel('env:myapi/some-model')
+* ```
+*/
+function envProvider(options = {}) {
+	return createEnvProvider(defaultFactories, options);
+}
+
+//#endregion
+exports.builtinPresets = builtinPresets;
+exports.envProvider = envProvider;
+//# sourceMappingURL=index.cjs.map