feat: add @cloudflare/tanstack-ai package

.changeset/bright-doors-march.md

@@ -0,0 +1,48 @@
+---
+"workers-ai-provider": minor
+---
+
+Add transcription, text-to-speech, and reranking support to the Workers AI provider.
+
+### New capabilities
+
+- **Transcription** (`provider.transcription(model)`) — implements `TranscriptionModelV3`. Supports Whisper models (`@cf/openai/whisper`, `whisper-tiny-en`, `whisper-large-v3-turbo`) and Deepgram Nova-3 (`@cf/deepgram/nova-3`). Handles model-specific input formats: number arrays for basic Whisper, base64 for v3-turbo via REST, and `{ body, contentType }` for Nova-3 via binding or raw binary upload for Nova-3 via REST.
+
+- **Speech / TTS** (`provider.speech(model)`) — implements `SpeechModelV3`. Supports Workers AI TTS models including Deepgram Aura-1 (`@cf/deepgram/aura-1`). Accepts `text`, `voice`, and `speed` options. Returns audio as `Uint8Array`. Uses `returnRawResponse` to handle binary audio from the REST path without JSON parsing.
+
+- **Reranking** (`provider.reranking(model)`) — implements `RerankingModelV3`. Supports BGE reranker models (`@cf/baai/bge-reranker-base`, `bge-reranker-v2-m3`). Converts AI SDK's document format to Workers AI's `{ query, contexts, top_k }` input. Handles both text and JSON object documents.
+
+### Bug fixes
+
+- **AbortSignal passthrough** — `createRun` REST shim now passes the abort signal to `fetch`, enabling request cancellation and timeout handling. Previously the signal was silently dropped.
+- **Nova-3 REST support** — Added `createRunBinary` utility for models that require raw binary upload instead of JSON (used by Nova-3 transcription via REST).
+
+### Usage
+
+```typescript
+import { createWorkersAI } from "workers-ai-provider";
+import { experimental_transcribe, experimental_generateSpeech, rerank } from "ai";
+
+const workersai = createWorkersAI({ binding: env.AI });
+
+// Transcription
+const transcript = await experimental_transcribe({
+	model: workersai.transcription("@cf/openai/whisper-large-v3-turbo"),
+	audio: audioData,
+	mediaType: "audio/wav",
+});
+
+// Speech
+const speech = await experimental_generateSpeech({
+	model: workersai.speech("@cf/deepgram/aura-1"),
+	text: "Hello world",
+	voice: "asteria",
+});
+
+// Reranking
+const ranked = await rerank({
+	model: workersai.reranking("@cf/baai/bge-reranker-base"),
+	query: "What is machine learning?",
+	documents: ["ML is a branch of AI.", "The weather is sunny."],
+});
+```

.changeset/wide-knives-strive.md

@@ -0,0 +1,45 @@
+---
+"@cloudflare/tanstack-ai": minor
+---
+
+Add `@cloudflare/tanstack-ai` — adapters for using TanStack AI with Cloudflare Workers AI and AI Gateway.
+
+### Workers AI adapters
+
+All Workers AI adapters support four configuration modes: plain binding (`env.AI`), plain REST (account ID + API key), AI Gateway binding (`env.AI.gateway(id)`), and AI Gateway REST (account ID + gateway ID).
+
+- **Chat** (`createWorkersAiChat`) — Streaming chat completions via the OpenAI-compatible API. Includes tool calling with full round-trip support, structured output via `json_schema`, and reasoning text streaming (`STEP_STARTED`/`STEP_FINISHED` AG-UI events) for models like QwQ, DeepSeek R1, and Kimi K2.5. A custom fetch shim translates OpenAI SDK calls to `env.AI.run()` for binding mode, with a stream transformer that handles both Workers AI native format and OpenAI-compatible format.
+- **Image generation** (`createWorkersAiImage`) — Stable Diffusion and other text-to-image models.
+- **Transcription** (`createWorkersAiTranscription`) — Speech-to-text via Whisper and Deepgram Nova-3.
+- **Text-to-speech** (`createWorkersAiTts`) — Audio generation via Deepgram Aura-1.
+- **Summarization** (`createWorkersAiSummarize`) — Text summarization via BART-large-CNN.
+- **Embeddings** (`createWorkersAiEmbedding`) — Text embeddings (implemented but not yet exported, pending TanStack AI's `BaseEmbeddingAdapter`).
+
+### AI Gateway adapters (third-party providers)
+
+Route requests through Cloudflare AI Gateway for caching, rate limiting, and unified billing. Each adapter injects a custom `fetch` (or `httpOptions` for Gemini) that handles both binding and credential-based gateway configurations.
+
+- **OpenAI** — Chat, summarize, image, transcription, TTS, video (`createOpenAi*`)
+- **Anthropic** — Chat, summarize (`createAnthropic*`)
+- **Gemini** — Chat, summarize, image, TTS (`createGemini*`). Credentials-only (Google GenAI SDK lacks custom fetch support).
+- **Grok** — Chat, summarize, image (`createGrok*`)
+- **OpenRouter** — Chat, summarize, image (`createOpenRouter*`). Accepts any model string.
+
+### Utilities
+
+- `createGatewayFetch` — Shared fetch factory that routes requests through AI Gateway (binding or REST), with support for cache control headers (`skipCache`, `cacheTtl`, `customCacheKey`, `metadata`).
+- `createWorkersAiBindingFetch` — Fetch shim that makes `env.AI` look like an OpenAI endpoint, including stream transformation and tool call ID sanitization for the binding's strict `[a-zA-Z0-9]{9}` validation.
+- Config detection helpers (`isDirectBindingConfig`, `isDirectCredentialsConfig`, `isGatewayConfig`) using structural typing to discriminate `env.AI` from `env.AI.gateway(id)`.
+- Shared binary utilities for normalizing Workers AI responses (Uint8Array, ArrayBuffer, ReadableStream, JSON wrapper) to base64.
+
+### Robustness
+
+- Premature stream termination detection — if Workers AI truncates a response or the connection drops (no `finish_reason`), the adapter emits proper closing events so consumers don't hang.
+- Graceful non-streaming fallback — if a model returns a complete response despite `stream: true`, the binding shim wraps it into a valid response.
+- Deepgram Nova-3 transcription uses raw binary audio via REST (not JSON), automatically detected by model name.
+
+### Testing
+
+- Comprehensive unit tests (186 tests) covering all adapters, config modes, stream transformation, message building, tool calling, reasoning events, premature termination, and public API surface.
+- E2E integration tests against real Workers AI APIs (both binding and REST paths) across 12 chat models + 4 transcription models + image/TTS/summarize, validating chat, multi-turn, tool calling, tool round-trips, structured output, reasoning, and all non-chat capabilities.
+- Tree-shakeable package exports with per-adapter entry points for ESM and CJS.

.github/workflows/release.yml

@@ -35,6 +35,7 @@ jobs:
               run: |
                   pnpm nx build workers-ai-provider
                   pnpm nx build ai-gateway-provider
+                  pnpm nx build @cloudflare/tanstack-ai
 
             - id: changesets
               uses: changesets/action@v1

README.md

@@ -1,115 +1,53 @@
 # Cloudflare AI
 
-This repository contains various packages and demo apps related consuming Cloudflare's AI offerings on the client-side. It is a monorepo powered by [Nx](https://nx.dev/) and [Changesets](https://github.com/changesets/changesets).
+Packages and examples for building AI-powered applications on Cloudflare. Includes providers for the [Vercel AI SDK](https://sdk.vercel.ai/) and [TanStack AI](https://tanstack.com/ai), with support for [Workers AI](https://ai.cloudflare.com/) and [AI Gateway](https://developers.cloudflare.com/ai-gateway/).
 
 ## Packages
 
-- [`workers-ai-provider`](./packages/workers-ai-provider/README.md): A custom provider that enables [Workers AI](https://ai.cloudflare.com/)'s models for the [Vercel AI SDK](https://sdk.vercel.ai/).
-- [`ai-gateway-provider`](./packages/ai-gateway-provider/README.md): [AI Gateway](https://developers.cloudflare.com/ai-gateway/) Provider for [Vercel AI SDK](https://sdk.vercel.ai/).
+| Package                                                  | Description                                                                                                                                                                   | npm                                                                                                                   |
+| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| [`workers-ai-provider`](./packages/workers-ai-provider/) | Workers AI provider for the Vercel AI SDK. Chat, image generation, embeddings, transcription, text-to-speech, and reranking.                                                  | [![npm](https://img.shields.io/npm/v/workers-ai-provider)](https://www.npmjs.com/package/workers-ai-provider)         |
+| [`@cloudflare/tanstack-ai`](./packages/tanstack-ai/)     | Workers AI and AI Gateway adapters for TanStack AI. Chat, image, transcription, TTS, summarization, plus gateway routing for OpenAI, Anthropic, Gemini, Grok, and OpenRouter. | [![npm](https://img.shields.io/npm/v/@cloudflare/tanstack-ai)](https://www.npmjs.com/package/@cloudflare/tanstack-ai) |
+| [`ai-gateway-provider`](./packages/ai-gateway-provider/) | AI Gateway provider for the Vercel AI SDK. Route requests through Cloudflare's AI Gateway for caching, rate limiting, and observability.                                      | [![npm](https://img.shields.io/npm/v/ai-gateway-provider)](https://www.npmjs.com/package/ai-gateway-provider)         |
 
-## Local Development
-
-1. Clone the repository.
-
-    ```bash
-    git clone git@github.com:cloudflare/ai.git
-    ```
-
-2. Install Dependencies.
-
-    From the root directory, run:
-
-    ```bash
-    cd ai
-    pnpm install
-    ```
-
-3. Develop.
-
-    To start a development server for a specific app (for instance, `tool-calling`):
-
-    ```bash
-    pnpm nx dev tool-calling
-    ```
-
-    _Ideally all commands should be executed from the repository root with the `pnpm nx` prefix. This will ensure that the dependency graph is managed correctly, e.g. if one package relies on the output of an other._
-
-4. Testing and Linting.
-
-- To execute your continuous integration tests for a specific project (e.g., `workers-ai-provider`):
-
-    ```bash
-    pnpm nx test:ci workers-ai-provider
-    ```
-
-- To lint a specific project:
-
-    ```bash
-    pnpm nx lint my-project
-    ```
-
-- To run a more comprehensive sweep of tasks (lint, tests, type checks, build) against one or more projects:
+## Examples
 
-    ```bash
-    pnpm nx run-many -t lint test:ci type-check build -p "my-project other-project"
-    ```
+| Example                                           | Description                                                                                                                                                                                                                                                 |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`examples/workers-ai`](./examples/workers-ai/)   | Full-featured Workers AI playground using the Vercel AI SDK. Demonstrates all 6 capabilities: chat (with tool calling and reasoning), image generation, embeddings, transcription, text-to-speech, and reranking. Supports both binding and REST API modes. |
+| [`examples/tanstack-ai`](./examples/tanstack-ai/) | Multi-provider demo using TanStack AI. Provider-first UI with Workers AI (binding and gateway), OpenAI, Anthropic, Gemini, Grok, and OpenRouter — each with capability sub-tabs for chat, image, summarize, transcription, and TTS.                         |
 
-5. Other Nx Tasks.
+## Demos
 
-- `build`: Compiles a project or a set of projects.
-- `test`: Runs project tests in watch mode.
-- `test:ci`: Runs tests in CI mode (no watch).
-- `test:smoke`: Runs smoke tests.
-- `type-check`: Performs TypeScript type checks.
+The [`demos/`](./demos/) directory contains additional focused demos for specific patterns — tool calling, structured output, agents, MCP servers, and more. See [demos.json](./demos.json) for the full list.
 
-## Creating a New Demo App
-
-In order to scaffold a new demo app, you can use the `create-demo` script. This script will create a new demo app in the `demos` directory.
+## Local Development
 
 ```bash
-pnpm create-demo <demo-name>
-```
+# Clone and install
+git clone git@github.com:cloudflare/ai.git
+cd ai
+pnpm install
 
-After creating the app, `pnpm install` will be run to install the dependencies, and `pnpm nx cf-typegen <demo-name>` will be run to generate the types for the demo app. Then it's simply a case of starting the app with:
+# Run an example
+cd examples/workers-ai
+pnpm dev
 
-```bash
-pnpm nx dev <demo-name>
+# Run tests for a package
+cd packages/workers-ai-provider
+pnpm test
+
+# Run E2E tests (requires Cloudflare credentials)
+pnpm test:e2e
 ```
 
 ## Contributing
 
-We appreciate contributions and encourage pull requests. Please follow these guidelines:
-
-1. Project Setup: After forking or cloning, install dependencies with `pnpm install`.
-2. Branching: Create a new branch for your feature or fix.
-3. Making Changes:
-
-- Add or update relevant tests.
-- On pushing your changes, automated tasks will be run (courtesy of a Husky pre-push hook).
-
-4. Changesets: If your changes affect a published package, run `pnpm changeset` to create a changeset. Provide a concise summary of your changes in the changeset prompt.
-5. Pull Request: Submit a pull request to the `main` branch. The team will review it and merge if everything is in order.
+1. Fork or clone the repo, then `pnpm install` from the root.
+2. Create a branch for your change.
+3. If your change affects a published package, run `pnpm changeset` and describe what changed.
+4. Submit a PR to `main`.
 
 ## Release Process
 
-This repository uses [Changesets](https://github.com/changesets/changesets) to manage versioning and publication:
-
-1. **Changeset Creation**: Whenever a change is made that warrants a new release (e.g., bug fixes, new features), run:
-
-    ```bash
-    pnpm changeset
-    ```
-
-    Provide a clear description of the changes.
-
-2. **Merging**: Once the changeset is merged into `main`, our GitHub Actions workflows will:
-
-- Detect the changed packages, and create a Version Packages PR.
-- Increment versions automatically (via Changesets).
-- Publish any package that has a version number to npm. (Demos and other internal items do not require versioning.)
-
-3. **Publication**: The release workflow (`.github/workflows/release.yml`) will run on every push to `main`. It ensures each published package is tagged and released on npm. Any package with a version field in its `package.json` will be included in this process.
-
----
-
-For any queries or guidance, kindly open an issue or submit a pull request. We hope this structure and process help you to contribute effectively.
+This repo uses [Changesets](https://github.com/changesets/changesets). When a PR with changesets merges to `main`, a "Version Packages" PR is created automatically. Merging that PR bumps versions and publishes to npm.

examples/tanstack-ai/.dev.vars.example

@@ -0,0 +1,11 @@
+# Cloudflare credentials (required for Workers AI and AI Gateway routing)
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_AI_GATEWAY_ID=
+CLOUDFLARE_API_TOKEN=
+
+# Provider API keys can also be entered in the browser UI at runtime.
+# These env vars serve as fallbacks for local development.
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# GEMINI_API_KEY=
+# GROK_API_KEY=

examples/tanstack-ai/.gitignore

@@ -0,0 +1,31 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# wrangler files
+.wrangler
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example

examples/tanstack-ai/README.md

@@ -0,0 +1,81 @@
+# @cloudflare/tanstack-ai demo
+
+Multi-provider AI demo showcasing [`@cloudflare/tanstack-ai`](../../packages/tanstack-ai). Features **Chat**, **Image Generation**, and **Summarization** across Workers AI and third-party providers (OpenAI, Anthropic, Gemini, Grok) through Cloudflare AI Gateway.
+
+## Features
+
+### Chat
+
+| Provider              | Model                                     | Config Mode               |
+| --------------------- | ----------------------------------------- | ------------------------- |
+| **Llama 4 Scout**     | `@cf/meta/llama-4-scout-17b-16e-instruct` | Workers AI direct         |
+| **Qwen3 30B**         | `@cf/qwen/qwen3-30b-a3b-fp8`              | Workers AI via AI Gateway |
+| **GPT-5.2**           | `gpt-5.2`                                 | OpenAI via AI Gateway     |
+| **Claude Sonnet 4.5** | `claude-sonnet-4-5`                       | Anthropic via AI Gateway  |
+| **Gemini 2.5 Flash**  | `gemini-2.5-flash`                        | Gemini via AI Gateway     |
+| **Grok 4**            | `grok-4-1-fast-reasoning`                 | Grok via AI Gateway       |
+
+### Image Generation
+
+| Provider   | Model                     |
+| ---------- | ------------------------- |
+| **OpenAI** | `gpt-image-1`             |
+| **Gemini** | `imagen-4.0-generate-001` |
+| **Grok**   | `grok-2-image-1212`       |
+
+### Summarization
+
+| Provider      | Model               |
+| ------------- | ------------------- |
+| **OpenAI**    | `gpt-5.2`           |
+| **Anthropic** | `claude-sonnet-4-5` |
+| **Gemini**    | `gemini-2.0-flash`  |
+
+## Setup
+
+### Option 1: Enter credentials in the UI (recommended for trying it out)
+
+1. Install and run:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+2. Click **"Add API keys"** in the top-right corner and enter your Cloudflare Account ID, AI Gateway ID, and API Token. Credentials are stored in your browser's localStorage and sent as request headers -- never persisted on the server.
+
+### Option 2: Use environment variables (recommended for deploying)
+
+1. Copy the environment variables template:
+
+```bash
+cp .dev.vars.example .dev.vars
+```
+
+2. Fill in your `.dev.vars`:
+
+```
+CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
+CLOUDFLARE_AI_GATEWAY_ID=your-ai-gateway-id
+CLOUDFLARE_API_TOKEN=your-cloudflare-api-token
+```
+
+3. Install and run:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+> When both are present, user-provided credentials (from the UI) take precedence over environment variables.
+
+## What It Demonstrates
+
+- **Workers AI direct** -- `createWorkersAiChat(model, { binding: env.AI })` or REST API with `{ accountId, apiKey }`
+- **Workers AI through AI Gateway** -- `createWorkersAiChat(model, { binding: env.AI.gateway(id) })` or credentials mode
+- **Third-party providers through AI Gateway** -- `createOpenAiChat`, `createAnthropicChat`, `createGeminiChat`, `createGrokChat`
+- **Image generation** -- `generateImage()` with `createOpenAiImage`, `createGeminiImage`, `createGrokImage`
+- **Summarization** -- `summarize()` with `createOpenAiSummarize`, `createAnthropicSummarize`, `createGeminiSummarize`
+- **Streaming** -- chat providers stream responses via TanStack AI's `chat()` + `toHttpResponse()`
+- **Tool calling** -- server-side tools (math, time, web scrape) work across all chat providers
+- **Dynamic credentials** -- user-provided API keys passed via request headers, with env var fallback

examples/tanstack-ai/eslint.config.js

@@ -0,0 +1,16 @@
+import js from "@eslint/js";
+import globals from "globals";
+import tseslint from "typescript-eslint";
+import { globalIgnores } from "eslint/config";
+
+export default tseslint.config([
+	globalIgnores(["dist", "worker-configuration.d.ts"]),
+	{
+		files: ["**/*.{ts,tsx}"],
+		extends: [js.configs.recommended, tseslint.configs.recommended],
+		languageOptions: {
+			ecmaVersion: 2020,
+			globals: globals.browser,
+		},
+	},
+]);