feat: add OrcaRouter provider adapter

.changeset/quick-kiwis-jump.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/ai-orcarouter': minor
+---
+
+Add OrcaRouter provider adapter
+
+New `@tanstack/ai-orcarouter` package with tree-shakeable `orcaRouterText` (chat) and `orcaRouterSummarize` adapters. OrcaRouter is an OpenAI-compatible gateway exposing a provider/model namespace across many models with adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance on the same endpoint.

README.md

@@ -205,6 +205,7 @@ Official adapters include:
 | Package                                                                              | Use it for                                                                     |
 | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ |
 | [`@tanstack/ai-openrouter`](https://tanstack.com/ai/latest/docs/adapters/openrouter) | 300+ models through one OpenRouter API, with per-request cost tracking         |
+| [`@tanstack/ai-orcarouter`](https://tanstack.com/ai/latest/docs/adapters/orcarouter) | OrcaRouter chat, tool calling, and structured outputs with adaptive routing, failover, and gateway security |
 | [`@tanstack/ai-openai`](https://tanstack.com/ai/latest/docs/adapters/openai)         | OpenAI chat, image, video, speech, transcription, realtime, and provider tools |
 | [`@tanstack/ai-anthropic`](https://tanstack.com/ai/latest/docs/adapters/anthropic)   | Anthropic Claude chat, thinking, tools, structured outputs, and Vertex Claude  |
 | [`@tanstack/ai-gemini`](https://tanstack.com/ai/latest/docs/adapters/gemini)         | Google Gemini chat, image, speech, and audio generation                        |

docs/adapters/orcarouter.md

@@ -0,0 +1,167 @@
+---
+title: OrcaRouter
+id: orcarouter-adapter
+description: "Route chat, tool calling, and structured outputs across many models with adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance through OrcaRouter's single OpenAI-compatible endpoint in TanStack AI."
+keywords:
+  - tanstack ai
+  - orcarouter
+  - ai gateway
+  - multi-provider
+  - unified api
+  - model router
+  - agent governance
+  - adapter
+---
+
+[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible AI gateway built for both models and agents. Like OpenRouter, it exposes a provider/model namespace across many models — but it also combines adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance behind the same endpoint. Use the hosted gateway at `api.orcarouter.ai` or point the adapter at your own deployment.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-orcarouter
+```
+
+## Basic Usage
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { orcaRouterText } from "@tanstack/ai-orcarouter";
+
+const stream = chat({
+  adapter: orcaRouterText("openai/gpt-5.5-pro"),
+  messages: [{ role: "user", content: "Hello!" }],
+});
+```
+
+`orcaRouterText` reads your API key from the `ORCAROUTER_API_KEY` environment variable. Use `createOrcaRouterText` to pass it explicitly.
+
+## Configuration
+
+```typescript
+import { createOrcaRouterText } from "@tanstack/ai-orcarouter";
+
+const adapter = createOrcaRouterText(
+  "openai/gpt-5.5-pro",
+  process.env.ORCAROUTER_API_KEY!,
+  {
+    baseURL: "https://api.orcarouter.ai/v1", // Optional — set for self-hosted deployments
+  },
+);
+```
+
+OrcaRouter is self-hostable; point `baseURL` at your own deployment to keep the same adapter surface.
+
+## Available Models
+
+Any model listed at [orcarouter.ai/models](https://www.orcarouter.ai) works — pass its id as the model name. Model ids use the `provider/model` prefix to pin routing to a specific provider, and the `orcarouter/fusion` family enables adaptive automatic routing across fallback models:
+
+```text
+model: "orcarouter/fusion"               // adaptive routing across fallback models
+model: "openai/gpt-5.5-pro"              // always routed to OpenAI
+model: "anthropic/claude-opus-4.8"       // always routed to Anthropic
+model: "deepseek/deepseek-v4-pro-0813"   // always routed to DeepSeek
+```
+
+A curated set of flagship models (see `ORCAROUTER_CHAT_MODELS`) additionally carries per-model type metadata — input modalities and provider options — with editor autocomplete. Uncurated ids still work and fall back to text-only input with the generic options.
+
+## Example: Chat Completion
+
+```typescript
+import { chat, toServerSentEventsResponse } from "@tanstack/ai";
+import { orcaRouterText } from "@tanstack/ai-orcarouter";
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  const stream = chat({
+    adapter: orcaRouterText("openai/gpt-5.5-pro"),
+    messages,
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+## Example: With Tools
+
+```typescript
+import { chat, toServerSentEventsResponse, toolDefinition } from "@tanstack/ai";
+import { orcaRouterText } from "@tanstack/ai-orcarouter";
+import { z } from "zod";
+
+const getWeatherDef = toolDefinition({
+  name: "get_weather",
+  description: "Get the current weather",
+  inputSchema: z.object({
+    location: z.string(),
+  }),
+});
+
+const getWeather = getWeatherDef.server(async ({ location }) => {
+  return { temperature: 72, conditions: "sunny" };
+});
+
+export async function POST(request: Request) {
+  const { messages } = await request.json();
+
+  const stream = chat({
+    adapter: orcaRouterText("openai/gpt-5.5-pro"),
+    messages,
+    tools: [getWeather],
+  });
+
+  return toServerSentEventsResponse(stream);
+}
+```
+
+## Model Options
+
+The gateway accepts the standard Chat Completions parameters and forwards them to the routed provider (parameters a provider doesn't support are stripped server-side). Sampling parameters live in `modelOptions`:
+
+```typescript
+import { chat } from "@tanstack/ai";
+import { orcaRouterText } from "@tanstack/ai-orcarouter";
+
+const stream = chat({
+  adapter: orcaRouterText("deepseek/deepseek-v4-pro-0813"),
+  messages: [{ role: "user", content: "Hello!" }],
+  modelOptions: {
+    temperature: 0.7,
+    max_completion_tokens: 4096,
+    reasoning_effort: "high",
+  },
+});
+```
+
+`reasoning_effort` accepts the extended scale `none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` in addition to OpenAI's standard tiers — which tiers a model honors depends on the model and provider it is routed to.
+
+Reasoning models stream their thinking as `reasoning_content` deltas, which the adapter surfaces as AG-UI `REASONING_*` events.
+
+## Summarization
+
+```typescript
+import { summarize } from "@tanstack/ai";
+import { orcaRouterSummarize } from "@tanstack/ai-orcarouter";
+
+const result = await summarize({
+  adapter: orcaRouterSummarize("openai/gpt-5.5-pro"),
+  text: "Long article text...",
+  stream: false,
+});
+
+console.log(result.summary);
+```
+
+## Gateway Security
+
+OrcaRouter also runs gateway-level, zero-trust security for AI agents on the same endpoint — screening every prompt/response and governing every tool call on a default-deny basis, with no application code changes.
+
+## Environment Variables
+
+Set your API key in environment variables:
+
+```bash
+ORCAROUTER_API_KEY=sk-orca_your-api-key
+```
+
+Get an API key from the [OrcaRouter dashboard](https://www.orcarouter.ai).

docs/config.json

@@ -928,6 +928,11 @@
           "to": "adapters/llmgateway",
           "addedAt": "2026-07-29"
         },
+        {
+          "label": "OrcaRouter Adapter",
+          "to": "adapters/orcarouter",
+          "addedAt": "2026-08-29"
+        },
         {
           "label": "Claude Code",
           "to": "adapters/claude-code",

docs/getting-started/overview.md

@@ -125,6 +125,7 @@ With the help of adapters, TanStack AI can connect to various LLM providers. Ava
 - **@tanstack/ai-byteplus** - BytePlus (Seed chat, Seedance video, Seedream image, Seed Speech)
 - **@tanstack/ai-fal** - fal (image & video generation)
 - **@tanstack/ai-llmgateway** - LLM Gateway (hundreds of models via one OpenAI-compatible endpoint, self-hostable)
+- **@tanstack/ai-orcarouter** - OrcaRouter (chat, tool calling, and structured outputs with adaptive routing, failover, and gateway security)
 - **@tanstack/ai-lovable** - Lovable AI Gateway (Google and OpenAI chat, image, video, embeddings, and speech via one project key)
 
 ## Next Steps

docs/structured-outputs/streaming.md

@@ -187,6 +187,7 @@ Streaming structured output works with **every adapter**, but only some support
 | `@tanstack/ai-bedrock` | Native stream through Converse or an OpenAI-compatible API |
 | `@tanstack/ai-byteplus` | Native single-request stream on supported models; unsupported models emit `RUN_ERROR` |
 | `@tanstack/ai-llmgateway` | Native single-request stream (Chat Completions, `response_format: json_schema`) |
+| `@tanstack/ai-orcarouter` | Native single-request stream (Chat Completions, `response_format: json_schema`) |
 | `@tanstack/ai-lovable` | Native single-request stream (Responses or Chat Completions) |
 | Other adapters (anthropic, gemini, ollama, …) | Fallback: runs non-streaming `structuredOutput` and emits the final object as one `structured-output.complete` event |
 

packages/ai-orcarouter/LICENSE

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

packages/ai-orcarouter/README.md

@@ -0,0 +1,95 @@
+# @tanstack/ai-orcarouter
+
+[OrcaRouter](https://www.orcarouter.ai) adapter for TanStack AI — one OpenAI-compatible endpoint that routes chat, tool calling, and structured outputs across many models with adaptive routing, automatic failover, zero-markup inference, observability, guardrails, and agent-tool governance.
+
+## Installation
+
+```bash
+npm install @tanstack/ai-orcarouter
+# or
+pnpm add @tanstack/ai-orcarouter
+# or
+yarn add @tanstack/ai-orcarouter
+```
+
+## Setup
+
+Get your API key from the [OrcaRouter dashboard](https://www.orcarouter.ai) and set it as an environment variable:
+
+```bash
+export ORCAROUTER_API_KEY="sk-orca_..."
+```
+
+## Usage
+
+### Text/Chat Adapter
+
+```typescript
+import { orcaRouterText } from '@tanstack/ai-orcarouter'
+import { chat } from '@tanstack/ai'
+
+const stream = chat({
+  adapter: orcaRouterText('openai/gpt-5.5-pro'),
+  messages: [
+    { role: 'user', content: 'Explain quantum computing in simple terms' },
+  ],
+})
+```
+
+### With Explicit API Key
+
+```typescript
+import { createOrcaRouterText } from '@tanstack/ai-orcarouter'
+
+const adapter = createOrcaRouterText('openai/gpt-5.5-pro', 'sk-orca_api_key')
+```
+
+### Self-Hosted Gateways
+
+OrcaRouter is self-hostable — point `baseURL` at your own deployment:
+
+```typescript
+import { createOrcaRouterText } from '@tanstack/ai-orcarouter'
+
+const adapter = createOrcaRouterText('openai/gpt-5.5-pro', 'sk-orca_api_key', {
+  baseURL: 'https://gateway.example.com/v1',
+})
+```
+
+## Models
+
+Any model listed on [orcarouter.ai/models](https://www.orcarouter.ai) works — pass its id as the model name. A curated set of flagship models additionally carries per-model type metadata (input modalities, provider options) with autocomplete, including `openai/gpt-5.5-pro`, `anthropic/claude-opus-4.8`, `google/gemini-3.1-pro-preview`, `deepseek/deepseek-v4-pro-0813`, and more (see `ORCAROUTER_CHAT_MODELS`).
+
+Model ids use the `provider/model` prefix to pin routing to a specific provider, and `orcarouter/fusion` enables adaptive automatic routing across fallback models:
+
+```typescript
+orcaRouterText('orcarouter/fusion') // adaptive routing across fallback models
+orcaRouterText('openai/gpt-5.5-pro') // pinned to OpenAI
+```
+
+## Features
+
+- ✅ Streaming chat completions
+- ✅ Structured output (JSON Schema)
+- ✅ Function/tool calling
+- ✅ Multimodal input (text + images for vision models)
+- ✅ Reasoning output (`reasoning_content` deltas from reasoning models)
+- ✅ Summarization (`orcaRouterSummarize`)
+- ✅ Adaptive routing, automatic failover, observability, guardrails, and agent-tool governance — applied gateway-side, no application code changes
+
+## Tree-Shakeable Adapters
+
+This package uses tree-shakeable adapters, so you only import what you need:
+
+```typescript
+// Text/chat only
+import { orcaRouterText } from '@tanstack/ai-orcarouter'
+
+// Summarization only
+import { orcaRouterSummarize } from '@tanstack/ai-orcarouter'
+```
+
+## Documentation
+
+- [TanStack AI Documentation](https://tanstack.com/ai)
+- [OrcaRouter Documentation](https://www.orcarouter.ai)