TanStack · AlemTuzlak · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/.changeset/add-ai-utils-package.md b/.changeset/add-ai-utils-package.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-utils': minor
+---
+
+New package: shared provider-agnostic utilities for TanStack AI adapters. Includes `generateId`, `getApiKeyFromEnv`, `transformNullsToUndefined`, and `ModelMeta` types with `defineModelMeta` validation helper. Zero runtime dependencies.
diff --git a/.changeset/add-openai-base-package.md b/.changeset/add-openai-base-package.md
@@ -0,0 +1,5 @@
+---
+'@tanstack/openai-base': minor
+---
+
+New package: shared base adapters and utilities for OpenAI-compatible providers. Includes Chat Completions and Responses API text adapter base classes, image/summarize/transcription/TTS/video adapter base classes, schema converter, 15 tool converters, and shared types. Providers extend these base classes to reduce duplication and ensure consistent behavior.
diff --git a/.changeset/refactor-providers-to-shared-packages.md b/.changeset/refactor-providers-to-shared-packages.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-openai': patch
+'@tanstack/ai-grok': patch
+'@tanstack/ai-groq': patch
+'@tanstack/ai-openrouter': patch
+'@tanstack/ai-ollama': patch
+'@tanstack/ai-anthropic': patch
+'@tanstack/ai-gemini': patch
+'@tanstack/ai-fal': patch
+'@tanstack/ai-elevenlabs': patch
+---
+
+Internal refactor: every provider now delegates `getApiKeyFromEnv` / `generateId` / `transformNullsToUndefined` / `ModelMeta` helpers to the new `@tanstack/ai-utils` package. `ai-openai` and `ai-grok` additionally inherit OpenAI-compatible adapter base classes (Chat Completions / Responses text, image, summarize, transcription, TTS, video) from the new `@tanstack/openai-base` package; `ai-groq` keeps its own `BaseTextAdapter`-derived text adapter (Groq uses the `groq-sdk`, not the OpenAI SDK) but consumes `@tanstack/openai-base`'s schema converter and tool converters. The remaining providers (`ai-anthropic`, `ai-gemini`, `ai-ollama`, `ai-openrouter`, `ai-fal`, `ai-elevenlabs`) only consume `@tanstack/ai-utils` because they speak provider-native protocols, not OpenAI-compatible ones. No breaking changes — all public APIs remain identical.
diff --git a/examples/ts-react-chat/src/lib/model-selection.ts b/examples/ts-react-chat/src/lib/model-selection.ts
@@ -15,37 +15,48 @@ export interface ModelOption {
 
 export const MODEL_OPTIONS: Array<ModelOption> = [
   // OpenAI
+  { provider: 'openai', model: 'gpt-5.2', label: 'OpenAI - GPT-5.2' },
+  { provider: 'openai', model: 'gpt-5.2-pro', label: 'OpenAI - GPT-5.2 Pro' },
+  { provider: 'openai', model: 'gpt-5.1', label: 'OpenAI - GPT-5.1' },
+  { provider: 'openai', model: 'gpt-5', label: 'OpenAI - GPT-5' },
+  { provider: 'openai', model: 'gpt-5-mini', label: 'OpenAI - GPT-5 Mini' },
+  { provider: 'openai', model: 'gpt-5-nano', label: 'OpenAI - GPT-5 Nano' },
+  { provider: 'openai', model: 'gpt-4.1', label: 'OpenAI - GPT-4.1' },
   { provider: 'openai', model: 'gpt-4o', label: 'OpenAI - GPT-4o' },
   { provider: 'openai', model: 'gpt-4o-mini', label: 'OpenAI - GPT-4o Mini' },
-  { provider: 'openai', model: 'gpt-5', label: 'OpenAI - GPT-5' },
 
   // Anthropic
   {
     provider: 'anthropic',
-    model: 'claude-sonnet-4-6',
-    label: 'Anthropic - Claude Sonnet 4.6',
+    model: 'claude-opus-4-7',
+    label: 'Anthropic - Claude Opus 4.7',
   },
   {
     provider: 'anthropic',
-    model: 'claude-sonnet-4-5-20250929',
-    label: 'Anthropic - Claude Sonnet 4.5',
+    model: 'claude-opus-4-6',
+    label: 'Anthropic - Claude Opus 4.6',
   },
   {
     provider: 'anthropic',
-    model: 'claude-opus-4-5-20251101',
-    label: 'Anthropic - Claude Opus 4.5',
+    model: 'claude-sonnet-4-6',
+    label: 'Anthropic - Claude Sonnet 4.6',
+  },
+  {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-5',
+    label: 'Anthropic - Claude Sonnet 4.5',
   },
   {
     provider: 'anthropic',
-    model: 'claude-haiku-4-0-20250514',
-    label: 'Anthropic - Claude Haiku 4.0',
+    model: 'claude-haiku-4-5',
+    label: 'Anthropic - Claude Haiku 4.5',
   },
 
   // Gemini
   {
     provider: 'gemini',
-    model: 'gemini-2.0-flash',
-    label: 'Gemini - 2.0 Flash',
+    model: 'gemini-2.5-pro',
+    label: 'Gemini - 2.5 Pro',
   },
   {
     provider: 'gemini',
@@ -54,20 +65,60 @@ export const MODEL_OPTIONS: Array<ModelOption> = [
   },
   {
     provider: 'gemini',
-    model: 'gemini-2.5-pro',
-    label: 'Gemini - 2.5 Pro',
+    model: 'gemini-2.0-flash',
+    label: 'Gemini - 2.0 Flash',
   },
 
-  // Openrouter
+  // Openrouter — multi-provider via OpenRouter's unified API
+  {
+    provider: 'openrouter',
+    model: 'openai/gpt-5.2',
+    label: 'OpenRouter - OpenAI GPT-5.2',
+  },
+  {
+    provider: 'openrouter',
+    model: 'openai/gpt-5.1',
+    label: 'OpenRouter - OpenAI GPT-5.1',
+  },
+  {
+    provider: 'openrouter',
+    model: 'openai/gpt-5',
+    label: 'OpenRouter - OpenAI GPT-5',
+  },
+  {
+    provider: 'openrouter',
+    model: 'openai/gpt-4o',
+    label: 'OpenRouter - OpenAI GPT-4o',
+  },
+  {
+    provider: 'openrouter',
+    model: 'anthropic/claude-opus-4.7',
+    label: 'OpenRouter - Anthropic Claude Opus 4.7',
+  },
+  {
+    provider: 'openrouter',
+    model: 'anthropic/claude-sonnet-4.6',
+    label: 'OpenRouter - Anthropic Claude Sonnet 4.6',
+  },
+  {
+    provider: 'openrouter',
+    model: 'anthropic/claude-haiku-4.5',
+    label: 'OpenRouter - Anthropic Claude Haiku 4.5',
+  },
+  {
+    provider: 'openrouter',
+    model: 'google/gemini-2.5-pro',
+    label: 'OpenRouter - Google Gemini 2.5 Pro',
+  },
   {
     provider: 'openrouter',
-    model: 'openai/chatgpt-4o-latest',
-    label: 'Openrouter - ChatGPT 4o Latest',
+    model: 'x-ai/grok-4',
+    label: 'OpenRouter - xAI Grok 4',
   },
   {
     provider: 'openrouter',
-    model: 'openai/chatgpt-4o-mini',
-    label: 'Openrouter - ChatGPT 4o Mini',
+    model: 'meta-llama/llama-3.3-70b-instruct',
+    label: 'OpenRouter - Meta Llama 3.3 70B (Groq-routed)',
   },
 
   // Ollama

diff --git a/packages/typescript/ai-anthropic/package.json b/packages/typescript/ai-anthropic/package.json
@@ -44,7 +44,8 @@
     "test:types": "tsc"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.71.2"
+    "@anthropic-ai/sdk": "^0.71.2",
+    "@tanstack/ai-utils": "workspace:*"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",

diff --git a/packages/typescript/ai-anthropic/src/utils/client.ts b/packages/typescript/ai-anthropic/src/utils/client.ts
@@ -1,4 +1,5 @@
 import Anthropic_SDK from '@anthropic-ai/sdk'
+import { generateId as _generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'
 import type { ClientOptions } from '@anthropic-ai/sdk'
 
 export interface AnthropicClientConfig extends ClientOptions {
@@ -22,26 +23,12 @@ export function createAnthropicClient(
  * @throws Error if ANTHROPIC_API_KEY is not found
  */
 export function getAnthropicApiKeyFromEnv(): string {
-  const env =
-    typeof globalThis !== 'undefined' && (globalThis as any).window?.env
-      ? (globalThis as any).window.env
-      : typeof process !== 'undefined'
-        ? process.env
-        : undefined
-  const key = env?.ANTHROPIC_API_KEY
-
-  if (!key) {
-    throw new Error(
-      'ANTHROPIC_API_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
-    )
-  }
-
-  return key
+  return getApiKeyFromEnv('ANTHROPIC_API_KEY')
 }
 
 /**
  * Generates a unique ID with a prefix
  */
 export function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  return _generateId(prefix)
 }
diff --git a/packages/typescript/ai-elevenlabs/package.json b/packages/typescript/ai-elevenlabs/package.json
@@ -49,7 +49,8 @@
   },
   "dependencies": {
     "@elevenlabs/client": "^1.3.1",
-    "@elevenlabs/elevenlabs-js": "^2.44.0"
+    "@elevenlabs/elevenlabs-js": "^2.44.0",
+    "@tanstack/ai-utils": "workspace:*"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",

diff --git a/packages/typescript/ai-elevenlabs/src/utils/client.ts b/packages/typescript/ai-elevenlabs/src/utils/client.ts
@@ -1,4 +1,8 @@
 import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js'
+import {
+  getApiKeyFromEnv,
+  generateId as sharedGenerateId,
+} from '@tanstack/ai-utils'
 import type { ElevenLabsOutputFormat } from '../model-meta'
 
 /**
@@ -39,14 +43,7 @@ function getEnvironment(): EnvObject | undefined {
 }
 
 export function getElevenLabsApiKeyFromEnv(): string {
-  const key = getEnvironment()?.ELEVENLABS_API_KEY
-  if (!key) {
-    throw new Error(
-      'ELEVENLABS_API_KEY is required. Please set it in your environment ' +
-        'variables or pass it explicitly to the adapter factory.',
-    )
-  }
-  return key
+  return getApiKeyFromEnv('ELEVENLABS_API_KEY')
 }
 
 export function getElevenLabsAgentIdFromEnv(): string {
@@ -80,9 +77,9 @@ export function createElevenLabsClient(
   })
 }
 
-export function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2)}`
-}
+// Re-exported from `@tanstack/ai-utils` so existing callers keep working
+// while the implementation stays deduped across provider packages.
+export const generateId = sharedGenerateId
 
 /**
  * Convert an ArrayBuffer to base64 in a cross-runtime way.

diff --git a/packages/typescript/ai-fal/package.json b/packages/typescript/ai-fal/package.json
@@ -46,7 +46,8 @@
     "transcription"
   ],
   "dependencies": {
-    "@fal-ai/client": "^1.9.4"
+    "@fal-ai/client": "^1.9.4",
+    "@tanstack/ai-utils": "workspace:*"
   },
   "devDependencies": {
     "@tanstack/ai": "workspace:*",

diff --git a/packages/typescript/ai-fal/src/utils/client.ts b/packages/typescript/ai-fal/src/utils/client.ts
@@ -1,42 +1,13 @@
 import { fal } from '@fal-ai/client'
+import { generateId as _generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'
 
 export interface FalClientConfig {
   apiKey: string
   proxyUrl?: string
 }
 
-interface EnvObject {
-  FAL_KEY?: string
-}
-
-interface WindowWithEnv {
-  env?: EnvObject
-}
-
-function getEnvironment(): EnvObject | undefined {
-  if (typeof globalThis !== 'undefined') {
-    const win = (globalThis as { window?: WindowWithEnv }).window
-    if (win?.env) {
-      return win.env
-    }
-  }
-  if (typeof process !== 'undefined') {
-    return process.env as EnvObject
-  }
-  return undefined
-}
-
 export function getFalApiKeyFromEnv(): string {
-  const env = getEnvironment()
-  const key = env?.FAL_KEY
-
-  if (!key) {
-    throw new Error(
-      'FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
-    )
-  }
-
-  return key
+  return getApiKeyFromEnv('FAL_KEY')
 }
 
 export function configureFalClient(config?: FalClientConfig): void {
@@ -48,7 +19,7 @@ export function configureFalClient(config?: FalClientConfig): void {
 }
 
 export function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(2)}`
+  return _generateId(prefix)
 }
 
 /**

diff --git a/packages/typescript/ai-gemini/package.json b/packages/typescript/ai-gemini/package.json
@@ -44,7 +44,8 @@
     "adapter"
   ],
   "dependencies": {
-    "@google/genai": "^1.43.0"
+    "@google/genai": "^1.43.0",
+    "@tanstack/ai-utils": "workspace:*"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^"

diff --git a/packages/typescript/ai-gemini/src/utils/client.ts b/packages/typescript/ai-gemini/src/utils/client.ts
@@ -1,4 +1,5 @@
 import { GoogleGenAI } from '@google/genai'
+import { generateId as _generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'
 import type { GoogleGenAIOptions } from '@google/genai'
 
 export interface GeminiClientConfig extends GoogleGenAIOptions {
@@ -20,26 +21,22 @@ export function createGeminiClient(config: GeminiClientConfig): GoogleGenAI {
  * @throws Error if GOOGLE_API_KEY or GEMINI_API_KEY is not found
  */
 export function getGeminiApiKeyFromEnv(): string {
-  const env =
-    typeof globalThis !== 'undefined' && (globalThis as any).window?.env
-      ? (globalThis as any).window.env
-      : typeof process !== 'undefined'
-        ? process.env
-        : undefined
-  const key = env?.GOOGLE_API_KEY || env?.GEMINI_API_KEY
-
-  if (!key) {
-    throw new Error(
-      'GOOGLE_API_KEY or GEMINI_API_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
-    )
+  try {
+    return getApiKeyFromEnv('GOOGLE_API_KEY')
+  } catch {
+    try {
+      return getApiKeyFromEnv('GEMINI_API_KEY')
+    } catch {
+      throw new Error(
+        'GOOGLE_API_KEY or GEMINI_API_KEY is not set. Please set one of these environment variables or pass the API key directly.',
+      )
+    }
   }
-
-  return key
 }
 
 /**
  * Generates a unique ID with a prefix
  */
 export function generateId(prefix: string): string {
-  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+  return _generateId(prefix)
 }
diff --git a/packages/typescript/ai-grok/package.json b/packages/typescript/ai-grok/package.json
@@ -44,6 +44,8 @@
     "adapter"
   ],
   "dependencies": {
+    "@tanstack/ai-utils": "workspace:*",
+    "@tanstack/openai-base": "workspace:*",
     "openai": "^6.9.1"
   },
   "devDependencies": {