You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by gi...@apache.org on 2026/08/30 04:22:54 UTC
(seatunnel) branch gh-readonly-queue/dev/pr-11997-ffdffb98290f20f8a1b5725e72d3c31bb7a9c253 created (now fa66cce415)
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a change to branch gh-readonly-queue/dev/pr-11997-ffdffb98290f20f8a1b5725e72d3c31bb7a9c253
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
at fa66cce415 [Feature][CLI] Add OrcaRouter AI gateway LLM provider (#11997)
This branch includes the following new commits:
new fa66cce415 [Feature][CLI] Add OrcaRouter AI gateway LLM provider (#11997)
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
(seatunnel) 01/01: [Feature][CLI] Add OrcaRouter AI gateway LLM provider (#11997)
Posted by gi...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
github-merge-queue[bot] pushed a commit to branch gh-readonly-queue/dev/pr-11997-ffdffb98290f20f8a1b5725e72d3c31bb7a9c253
in repository https://gitbox.apache.org/repos/asf/seatunnel.git
commit fa66cce41587838581014dca039e8c249adeb219
Author: kuswardhanietidims-svg <ku...@gmail.com>
AuthorDate: Sun Aug 30 04:22:32 2026 +0000
[Feature][CLI] Add OrcaRouter AI gateway LLM provider (#11997)
Co-authored-by: kuswardhanietidims-svg <ku...@users.noreply.github.com>
Co-authored-by: Claude <no...@anthropic.com>
---
docs/en/ai-cli/overview.md | 2 +-
docs/en/ai-cli/quickstart.md | 37 ++++
docs/zh/ai-cli/overview.md | 2 +-
docs/zh/ai-cli/quickstart.md | 34 ++++
seatunnel-cli/README.md | 37 +++-
seatunnel-cli/README.zh-CN.md | 32 +++-
seatunnel-cli/env.example.sh | 11 ++
seatunnel-cli/seatunnel_cli/cli.py | 59 +++++-
seatunnel-cli/seatunnel_cli/llm_provider.py | 96 ++++++++--
seatunnel-cli/setup.sh | 4 +
seatunnel-cli/tests/test_cli_provider_routing.py | 13 +-
.../tests/test_llm_provider_orcarouter.py | 200 +++++++++++++++++++++
12 files changed, 498 insertions(+), 29 deletions(-)
diff --git a/docs/en/ai-cli/overview.md b/docs/en/ai-cli/overview.md
index bd505651be..6ebd1c1208 100644
--- a/docs/en/ai-cli/overview.md
+++ b/docs/en/ai-cli/overview.md
@@ -21,7 +21,7 @@ The AI CLI ships as the `seatunnel-cli` module inside the main SeaTunnel reposit
## Key Capabilities
- **Natural language to config** — English or Chinese input, complete HOCON output
-- **Multi-provider LLM** — AWS Bedrock (including OpenAI-family models via the `bedrock-mantle` endpoint), Anthropic API, OpenAI and compatible APIs
+- **Multi-provider LLM** — AWS Bedrock (including OpenAI-family models via the `bedrock-mantle` endpoint), Anthropic API, OpenAI and compatible APIs, OrcaRouter AI gateway
- **Multi-agent pipeline** — Planner → Config Generator → Validator → auto-fix, with up to 3 correction rounds
- **Connector knowledge** — 150+ connectors with full option rules and value constraints, resolved from a live engine or bundled metadata
- **Validation & repair** — local checks, engine `--check`/dry-run, and LLM-powered diagnosis-and-repair when `/check` or `/run` fails
diff --git a/docs/en/ai-cli/quickstart.md b/docs/en/ai-cli/quickstart.md
index a1ea10f88f..a513ec07b9 100644
--- a/docs/en/ai-cli/quickstart.md
+++ b/docs/en/ai-cli/quickstart.md
@@ -12,6 +12,7 @@ sidebar_position: 2
- **AWS Bedrock** — AWS credentials (profile, env vars, or IAM role)
- **Anthropic API** — `ANTHROPIC_API_KEY`
- **OpenAI API** (or compatible) — `OPENAI_API_KEY`
+ - **OrcaRouter** — `ORCAROUTER_API_KEY`
- (Optional) a SeaTunnel installation for engine-level validation and job execution
## Install
@@ -58,8 +59,44 @@ export ANTHROPIC_API_KEY=sk-ant-...
export AI_PROVIDER=openai
export OPENAI_API_KEY=sk-...
# export OPENAI_BASE_URL=https://... # Azure OpenAI, DeepSeek, local vLLM, ...
+
+# Option D: OrcaRouter AI gateway
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+# Model IDs use a provider/model namespace (e.g. deepseek/deepseek-v4-pro);
+# `orcarouter/auto` auto-grades and auto-routes each request.
+# export ORCAROUTER_MODEL=orcarouter/auto
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # optional: replay reasoning_content for reasoning models
+```
+
+### OrcaRouter AI gateway
+
+[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible AI gateway
+that exposes many models — Claude, GPT, Gemini, DeepSeek, Qwen and more —
+behind a single endpoint (`https://api.orcarouter.ai/v1`). Model IDs follow a
+`provider/model` namespace, and the special `orcarouter/auto` model
+automatically selects the best model per request. Configure it as a
+first-class provider:
+
+```bash
+# Requires the openai package (shares the ".[openai]" extra)
+pip install -e ".[openai]"
+
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+# export ORCAROUTER_MODEL=deepseek/deepseek-v4-pro # optional override
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto # optional override
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # optional: replay reasoning_content
+
+seatunnel "Sync MySQL users table to S3 Parquet"
```
+The provider speaks the OpenAI Chat Completions protocol, so it fully supports
+the CLI's internal tool-calling loop (connector lookups during planning),
+streaming output, multi-turn sessions, and reasoning-content replay for
+compatible reasoning models.
+
### bedrock-mantle: OpenAI-family models on Bedrock
Some OpenAI models on Bedrock (e.g. `openai.gpt-5.6-terra`, `openai.gpt-5.6-sol`)
diff --git a/docs/zh/ai-cli/overview.md b/docs/zh/ai-cli/overview.md
index e53961264d..e09faf64b5 100644
--- a/docs/zh/ai-cli/overview.md
+++ b/docs/zh/ai-cli/overview.md
@@ -21,7 +21,7 @@ AI CLI 以 `seatunnel-cli` 模块的形式内置在 SeaTunnel 主仓库中,并
## 核心能力
- **自然语言生成配置** —— 中英文输入,输出完整 HOCON 配置
-- **多 LLM 提供商** —— AWS Bedrock(含通过 `bedrock-mantle` 端点接入的 OpenAI 系模型)、Anthropic API、OpenAI 及兼容 API
+- **多 LLM 提供商** —— AWS Bedrock(含通过 `bedrock-mantle` 端点接入的 OpenAI 系模型)、Anthropic API、OpenAI 及兼容 API、OrcaRouter AI 网关
- **多智能体流水线** —— Planner → 配置生成 → 校验 → 自动修复,最多 3 轮纠错
- **连接器知识库** —— 150+ 连接器的完整选项规则与取值约束,来自运行中引擎或内置元数据
- **校验与修复** —— 本地检查、引擎 `--check`/dry-run,`/check` 或 `/run` 失败时由 LLM 自动诊断修复
diff --git a/docs/zh/ai-cli/quickstart.md b/docs/zh/ai-cli/quickstart.md
index d7b722e982..02806de4bc 100644
--- a/docs/zh/ai-cli/quickstart.md
+++ b/docs/zh/ai-cli/quickstart.md
@@ -12,6 +12,7 @@ sidebar_position: 2
- **AWS Bedrock** —— AWS 凭证(profile、环境变量或 IAM 角色)
- **Anthropic API** —— `ANTHROPIC_API_KEY`
- **OpenAI API**(或兼容 API)—— `OPENAI_API_KEY`
+ - **OrcaRouter** —— `ORCAROUTER_API_KEY`
- (可选)SeaTunnel 安装目录,用于引擎级校验和作业执行
## 安装
@@ -57,8 +58,41 @@ export ANTHROPIC_API_KEY=sk-ant-...
export AI_PROVIDER=openai
export OPENAI_API_KEY=sk-...
# export OPENAI_BASE_URL=https://... # Azure OpenAI、DeepSeek、本地 vLLM 等
+
+# 方式 D:OrcaRouter AI 网关
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+# 模型 ID 使用 provider/model 命名空间(如 deepseek/deepseek-v4-pro);
+# `orcarouter/auto` 会自动评级并路由每个请求。
+# export ORCAROUTER_MODEL=orcarouter/auto
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # 可选:保留并回传推理模型的 reasoning_content
+```
+
+### OrcaRouter AI 网关
+
+[OrcaRouter](https://www.orcarouter.ai) 是一个 OpenAI 兼容的 AI 网关,在单个端点
+(`https://api.orcarouter.ai/v1`)之后暴露众多模型——Claude、GPT、Gemini、
+DeepSeek、Qwen 等。模型 ID 使用 `provider/model` 命名空间,特殊的
+`orcarouter/auto` 模型会自动为每个请求选择最佳模型。作为一等提供商配置:
+
+```bash
+# 需要 openai 包(复用 ".[openai]" extra)
+pip install -e ".[openai]"
+
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+# export ORCAROUTER_MODEL=deepseek/deepseek-v4-pro # 可选覆盖
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto # 可选覆盖
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # 可选:回传 reasoning_content
+
+seatunnel "Sync MySQL users table to S3 Parquet"
```
+该提供商使用 OpenAI Chat Completions 协议,因此完全支持 CLI 内部的工具调用循环
+(规划期间的连接器查询)、流式输出、多轮会话,以及兼容推理模型的
+reasoning_content 回放。
+
### bedrock-mantle:Bedrock 上的 OpenAI 系模型
Bedrock 上的部分 OpenAI 模型(如 `openai.gpt-5.6-terra`、`openai.gpt-5.6-sol`)
diff --git a/seatunnel-cli/README.md b/seatunnel-cli/README.md
index de890b0964..97b8772665 100644
--- a/seatunnel-cli/README.md
+++ b/seatunnel-cli/README.md
@@ -7,7 +7,7 @@ Describe your data synchronization task in English or Chinese, and the CLI gener
## Features
- **Natural Language to Config** -- Describe what you want in plain English or Chinese, get a valid SeaTunnel config
-- **Multi-Provider LLM** -- AWS Bedrock, Anthropic API, OpenAI (and compatible APIs like Azure OpenAI)
+- **Multi-Provider LLM** -- AWS Bedrock, Anthropic API, OpenAI (and compatible APIs like Azure OpenAI), OrcaRouter AI gateway
- **Multi-Agent Pipeline** -- Planner -> Generator -> Validator -> Auto-fix, up to 3 correction rounds
- **100+ Connectors** -- Full coverage of SeaTunnel's connector ecosystem with runtime metadata reflection
- **Transform Metadata** -- Source, sink, and transform plugins use full option rules and value constraints during generation
@@ -27,6 +27,7 @@ Describe your data synchronization task in English or Chinese, and the CLI gener
- **AWS Bedrock** -- requires AWS credentials and `boto3`
- **Anthropic API** -- requires `ANTHROPIC_API_KEY` and `anthropic` package
- **OpenAI API** -- requires `OPENAI_API_KEY` and `openai` package
+ - **OrcaRouter** -- requires `ORCAROUTER_API_KEY` and `openai` package
- (Optional) Running Apache SeaTunnel engine for live metadata and job execution
> **Note:** When launched via `bin/seatunnel-ai.sh`, Python dependencies are installed automatically on first run. No manual `pip install` needed.
@@ -67,7 +68,7 @@ seatunnel --init
```bash
pip install -e ".[bedrock]" # AWS Bedrock
pip install -e ".[anthropic]" # Anthropic API
-pip install -e ".[openai]" # OpenAI API
+pip install -e ".[openai]" # OpenAI API / OrcaRouter
pip install -e ".[all]" # All providers
pip install -e ".[dev]" # Development (all providers + pytest, ruff)
```
@@ -165,6 +166,30 @@ export OPENAI_SMALL_FAST_MODEL=gpt-4o-mini
# export OPENAI_ECHO_REASONING_CONTENT=true
```
+#### Option D: OrcaRouter AI Gateway
+
+```bash
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+
+# Model overrides (optional) — OrcaRouter model IDs use a provider/model namespace,
+# e.g. openai/gpt-5.5-pro, deepseek/deepseek-v4-pro, anthropic/claude-fable-5.
+# The special model `orcarouter/auto` auto-grades and auto-routes each request.
+# export ORCAROUTER_MODEL=orcarouter/auto
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # optional: replay reasoning_content for reasoning models
+```
+
+Requires: `pip install -e ".[openai]"` (the `openai` package).
+
+[OrcaRouter](https://www.orcarouter.ai) is an OpenAI-compatible AI gateway
+that exposes many models — including Claude, GPT, Gemini, DeepSeek and Qwen —
+behind a single endpoint (`https://api.orcarouter.ai/v1`). Model IDs follow a
+`provider/model` namespace, and the `orcarouter/auto` model automatically
+selects the best model per request. The OrcaRouter provider speaks the OpenAI
+Chat Completions protocol, so it inherits the same reasoning-content replay,
+streaming and tool-calling support as the `openai` provider.
+
### SEATUNNEL_HOME
`SEATUNNEL_HOME` is the path to your Apache SeaTunnel engine installation. The CLI uses it to:
@@ -207,16 +232,20 @@ When the engine is running, the CLI operates in **cluster mode** with live conne
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
-| `AI_PROVIDER` | No | `bedrock` | LLM provider: `bedrock`, `bedrock-mantle`, `anthropic`, or `openai` |
+| `AI_PROVIDER` | No | `bedrock` | LLM provider: `bedrock`, `bedrock-mantle`, `anthropic`, `openai`, or `orcarouter` |
| `AWS_REGION` | Bedrock | `us-east-1` | AWS region for Bedrock |
| `ANTHROPIC_API_KEY` | Anthropic | -- | Anthropic API key |
| `OPENAI_API_KEY` | OpenAI | -- | OpenAI API key |
| `OPENAI_BASE_URL` | No | -- | Custom endpoint for OpenAI-compatible APIs |
| `OPENAI_ECHO_REASONING_CONTENT` | No | `true` | Preserve and replay `reasoning_content` for OpenAI-compatible reasoning models such as DeepSeek or GLM thinking mode |
+| `ORCAROUTER_API_KEY` | OrcaRouter | -- | OrcaRouter API key |
| `ANTHROPIC_MODEL` | No | Provider default | Override primary model ID |
| `ANTHROPIC_SMALL_FAST_MODEL` | No | Provider default | Override fast model ID |
| `OPENAI_MODEL` | No | `gpt-4o` | Primary model for OpenAI provider |
| `OPENAI_SMALL_FAST_MODEL` | No | `gpt-4o-mini` | Fast model for OpenAI provider |
+| `ORCAROUTER_MODEL` | No | `orcarouter/auto` | Primary model for OrcaRouter provider (provider/model namespace) |
+| `ORCAROUTER_SMALL_FAST_MODEL` | No | `orcarouter/auto` | Fast model for OrcaRouter provider |
+| `ORCAROUTER_ECHO_REASONING_CONTENT` | No | `true` | Preserve and replay `reasoning_content` for OpenAI-compatible reasoning models (parity with `OPENAI_ECHO_REASONING_CONTENT`) |
| `SEATUNNEL_HOME` | No | Auto-detect | SeaTunnel installation directory. Auto-detected in distribution tarball; set manually for source install |
| `SEATUNNEL_API_BASE` | No | `http://localhost:5801` | SeaTunnel REST API endpoint |
| `SEATUNNEL_CLI_DATA` | No | `<cli-package>/.data/` | Override CLI data directory (sessions, memory, config) |
@@ -256,7 +285,7 @@ Positional:
Options:
-o, --output PATH Save generated config to file
- --provider PROVIDER LLM provider: bedrock | anthropic | openai
+ --provider PROVIDER LLM provider: bedrock | bedrock-mantle | anthropic | openai | orcarouter
--model MODEL Override primary model ID
--fast-model MODEL Override fast model ID
--sync-catalog PATH Regenerate connector catalog from SeaTunnel source
diff --git a/seatunnel-cli/README.zh-CN.md b/seatunnel-cli/README.zh-CN.md
index 0b0f97f57b..54d68339e1 100644
--- a/seatunnel-cli/README.zh-CN.md
+++ b/seatunnel-cli/README.zh-CN.md
@@ -7,7 +7,7 @@
## 功能特性
- **自然语言转配置** -- 用中文或英文描述需求,即可获得有效的 SeaTunnel 配置
-- **多 LLM 提供商** -- 支持 AWS Bedrock、Anthropic API、OpenAI(及兼容 API,如 Azure OpenAI)
+- **多 LLM 提供商** -- 支持 AWS Bedrock、Anthropic API、OpenAI(及兼容 API,如 Azure OpenAI)、OrcaRouter AI 网关
- **多智能体流水线** -- 规划器 -> 生成器 -> 校验器 -> 自动修复,最多 3 轮纠错
- **100+ 连接器** -- 全面覆盖 SeaTunnel 连接器生态,支持运行时元数据反射
- **Transform 元数据** -- Source、Sink 和 Transform 插件在生成配置时都支持完整选项规则和值约束
@@ -136,6 +136,28 @@ export OPENAI_SMALL_FAST_MODEL=gpt-4o-mini
# export OPENAI_ECHO_REASONING_CONTENT=true
```
+#### 方案 D:OrcaRouter AI 网关
+
+```bash
+export AI_PROVIDER=orcarouter
+export ORCAROUTER_API_KEY=orc_...
+
+# 模型覆盖(可选)——OrcaRouter 模型 ID 使用 provider/model 命名空间,
+# 例如 openai/gpt-5.5-pro、deepseek/deepseek-v4-pro、anthropic/claude-fable-5。
+# 特殊模型 `orcarouter/auto` 会自动评级并路由每个请求。
+# export ORCAROUTER_MODEL=orcarouter/auto
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # 可选:保留并回传推理模型的 reasoning_content
+```
+
+需要:`pip install -e ".[openai]"`(`openai` 包)。
+
+[OrcaRouter](https://www.orcarouter.ai) 是一个 OpenAI 兼容的 AI 网关,在单个端点
+(`https://api.orcarouter.ai/v1`)之后暴露众多模型——Claude、GPT、Gemini、
+DeepSeek、Qwen 等。模型 ID 使用 `provider/model` 命名空间,`orcarouter/auto`
+模型会自动为每个请求选择最佳模型。OrcaRouter 提供商使用 OpenAI Chat Completions
+协议,因此与 `openai` 提供商一样支持 reasoning_content 回放、流式输出和工具调用。
+
### SEATUNNEL_HOME
`SEATUNNEL_HOME` 是 Apache SeaTunnel 引擎的安装路径。CLI 使用它来:
@@ -178,16 +200,20 @@ export SEATUNNEL_API_BASE=http://localhost:5801 # 默认值
| 变量 | 是否必需 | 默认值 | 说明 |
|------|---------|--------|------|
-| `AI_PROVIDER` | 否 | `bedrock` | LLM 提供商:`bedrock`、`anthropic` 或 `openai` |
+| `AI_PROVIDER` | 否 | `bedrock` | LLM 提供商:`bedrock`、`bedrock-mantle`、`anthropic`、`openai` 或 `orcarouter` |
| `AWS_REGION` | Bedrock 必需 | `us-east-1` | Bedrock 使用的 AWS 区域 |
| `ANTHROPIC_API_KEY` | Anthropic 必需 | -- | Anthropic API 密钥 |
| `OPENAI_API_KEY` | OpenAI 必需 | -- | OpenAI API 密钥 |
| `OPENAI_BASE_URL` | 否 | -- | OpenAI 兼容 API 的自定义端点 |
| `OPENAI_ECHO_REASONING_CONTENT` | 否 | `true` | 为 DeepSeek、GLM 思考模式等 OpenAI 兼容推理模型保留并回传 `reasoning_content` |
+| `ORCAROUTER_API_KEY` | OrcaRouter 必需 | -- | OrcaRouter API 密钥 |
| `ANTHROPIC_MODEL` | 否 | 提供商默认值 | 覆盖主模型 ID |
| `ANTHROPIC_SMALL_FAST_MODEL` | 否 | 提供商默认值 | 覆盖快速模型 ID |
| `OPENAI_MODEL` | 否 | `gpt-4o` | OpenAI 提供商的主模型 |
| `OPENAI_SMALL_FAST_MODEL` | 否 | `gpt-4o-mini` | OpenAI 提供商的快速模型 |
+| `ORCAROUTER_MODEL` | 否 | `orcarouter/auto` | OrcaRouter 提供商的主模型(provider/model 命名空间) |
+| `ORCAROUTER_SMALL_FAST_MODEL` | 否 | `orcarouter/auto` | OrcaRouter 提供商的快速模型 |
+| `ORCAROUTER_ECHO_REASONING_CONTENT` | 否 | `true` | 保留并回传 `reasoning_content`(与 `OPENAI_ECHO_REASONING_CONTENT` 对齐) |
| `SEATUNNEL_HOME` | 否 | 自动检测 | SeaTunnel 安装目录。发行版压缩包中自动检测;源码安装需手动设置 |
| `SEATUNNEL_API_BASE` | 否 | `http://localhost:5801` | SeaTunnel REST API 端点 |
| `SEATUNNEL_CLI_DATA` | 否 | `<cli-package>/.data/` | 覆盖 CLI 数据目录(会话、记忆、配置) |
@@ -227,7 +253,7 @@ seatunnel [request] [options]
选项:
-o, --output PATH 将生成的配置保存到文件
- --provider PROVIDER LLM 提供商:bedrock | anthropic | openai
+ --provider PROVIDER LLM 提供商:bedrock | bedrock-mantle | anthropic | openai | orcarouter
--model MODEL 覆盖主模型 ID
--fast-model MODEL 覆盖快速模型 ID
--sync-catalog PATH 从 SeaTunnel 源码重新生成连接器目录
diff --git a/seatunnel-cli/env.example.sh b/seatunnel-cli/env.example.sh
index c684257df4..c53c4e5f57 100755
--- a/seatunnel-cli/env.example.sh
+++ b/seatunnel-cli/env.example.sh
@@ -29,6 +29,7 @@
# export AI_PROVIDER=bedrock-mantle # Option C2: OpenAI-family models on Bedrock
# # (GPT-5.6 Terra/Sol; needs ".[bedrock-mantle]" extra;
# # model via OPENAI_MODEL, e.g. openai.gpt-5.6-terra)
+# export AI_PROVIDER=orcarouter # Option D: OrcaRouter AI gateway (needs ".[openai]" extra)
# ─── Option A: Anthropic API (AI_PROVIDER=anthropic) ───
# export ANTHROPIC_API_KEY=sk-ant-...
@@ -49,6 +50,16 @@
# export AWS_ACCESS_KEY_ID=...
# export AWS_SECRET_ACCESS_KEY=...
+# ─── Option D: OrcaRouter AI gateway (AI_PROVIDER=orcarouter) ───
+# OpenAI-compatible gateway: many models behind one endpoint, model IDs use a
+# provider/model namespace (e.g. deepseek/deepseek-v4-pro, openai/gpt-5.5-pro).
+# The special model `orcarouter/auto` auto-grades and auto-routes each request.
+# Requires: pip install -e ".[openai]"
+# export ORCAROUTER_API_KEY=orc_...
+# export ORCAROUTER_MODEL=orcarouter/auto # optional override
+# export ORCAROUTER_SMALL_FAST_MODEL=orcarouter/auto # optional override
+# export ORCAROUTER_ECHO_REASONING_CONTENT=true # optional: keep true to replay reasoning_content for reasoning models
+
# ─── SeaTunnel Engine (optional) ───
# export SEATUNNEL_HOME=/path/to/seatunnel
# export SEATUNNEL_API_BASE=http://localhost:5801
diff --git a/seatunnel-cli/seatunnel_cli/cli.py b/seatunnel-cli/seatunnel_cli/cli.py
index 61988744af..89f8d7c028 100644
--- a/seatunnel-cli/seatunnel_cli/cli.py
+++ b/seatunnel-cli/seatunnel_cli/cli.py
@@ -514,20 +514,23 @@ class SeaTunnelCLI:
console.print(" [bold]4[/bold]. bedrock-mantle — OpenAI-family models on Bedrock (GPT-5.6 Terra/Sol)")
console.print(" Requires: AWS credentials + pip install \".[bedrock-mantle]\"")
console.print(" Note: Responses-API-only models on the bedrock-mantle endpoint\n")
+ console.print(" [bold]5[/bold]. orcarouter — OrcaRouter AI gateway (OpenAI-compatible)")
+ console.print(" Requires: ORCAROUTER_API_KEY + pip install \".[openai]\"")
+ console.print(" Note: many models behind one endpoint, e.g. orcarouter/auto\n")
try:
- choice = pt_prompt(" Enter your choice (1/2/3/4): ").strip().lower()
+ choice = pt_prompt(" Enter your choice (1/2/3/4/5): ").strip().lower()
except (EOFError, KeyboardInterrupt):
console.print("\n Setup cancelled.", style="warning")
return
choice_map = {"1": "anthropic", "2": "openai", "3": "bedrock",
- "4": "bedrock-mantle"}
+ "4": "bedrock-mantle", "5": "orcarouter"}
choice = choice_map.get(choice, choice)
if not choice or choice not in _PROVIDERS:
console.print(
- f" [error]Invalid choice: '{choice}'. Please enter 1, 2, 3, or 4.[/error]"
+ f" [error]Invalid choice: '{choice}'. Please enter 1, 2, 3, 4, or 5.[/error]"
)
return
@@ -603,6 +606,30 @@ class SeaTunnelCLI:
config.setdefault("settings", {})["openai_base_url"] = base_url
console.print(f" Base URL set: [bold]{base_url}[/bold]")
+ elif choice == "orcarouter":
+ existing = os.environ.get("ORCAROUTER_API_KEY")
+ if existing:
+ masked = existing[:7] + "..." + existing[-4:] if len(existing) > 15 else "***"
+ console.print(f" ORCAROUTER_API_KEY: [bold green]detected[/bold green] ({masked})")
+ else:
+ console.print(" ORCAROUTER_API_KEY not found in environment.\n")
+ console.print(
+ " [dim]Persistent (recommended): add to ~/.zshrc or ~/.bashrc:[/dim]\n"
+ " export ORCAROUTER_API_KEY=orc_...\n"
+ " [dim]Get a key: https://www.orcarouter.ai[/dim]\n",
+ )
+ try:
+ key_input = pt_prompt(
+ " Enter API key for this session (or Enter to skip): ",
+ ).strip()
+ except (EOFError, KeyboardInterrupt):
+ key_input = ""
+ if key_input:
+ os.environ["ORCAROUTER_API_KEY"] = key_input
+ console.print(
+ " [success]Key set for this session (NOT saved to disk).[/success]"
+ )
+
elif choice in ("bedrock", "bedrock-mantle"):
console.print(" AWS Bedrock requires AWS credentials.\n")
if choice == "bedrock-mantle":
@@ -665,6 +692,11 @@ class SeaTunnelCLI:
default_fast = "gpt-4o-mini"
model_env = "OPENAI_MODEL"
fast_env = "OPENAI_SMALL_FAST_MODEL"
+ elif choice == "orcarouter":
+ default_model = "orcarouter/auto"
+ default_fast = "orcarouter/auto"
+ model_env = "ORCAROUTER_MODEL"
+ fast_env = "ORCAROUTER_SMALL_FAST_MODEL"
elif choice == "bedrock-mantle":
default_model = "openai.gpt-5.6-terra"
default_fast = "openai.gpt-5.6-terra"
@@ -881,6 +913,15 @@ class SeaTunnelCLI:
base_url = os.environ.get("OPENAI_BASE_URL")
if base_url:
self.console.print(f" Base URL: [bold]{base_url}[/bold]", style="info")
+ elif provider_name == "orcarouter":
+ if os.environ.get("ORCAROUTER_API_KEY"):
+ self.console.print(" API key: [bold green]configured[/bold green]", style="info")
+ else:
+ creds_ok = False
+ self.console.print("[error]ORCAROUTER_API_KEY not set.[/error]")
+ self.console.print(
+ " Base URL: [bold]https://api.orcarouter.ai/v1[/bold]", style="info"
+ )
self.console.print(f" Model: [bold]{provider.model_id}[/bold]", style="info")
self.console.print(f" Fast model: [bold]{provider.fast_model_id}[/bold]", style="info")
@@ -1527,7 +1568,7 @@ def main():
)
parser.add_argument(
"--provider",
- choices=["bedrock", "bedrock-mantle", "anthropic", "openai"],
+ choices=["bedrock", "bedrock-mantle", "anthropic", "openai", "orcarouter"],
help="LLM provider (overrides AI_PROVIDER env var and config.json)",
)
parser.add_argument(
@@ -1579,17 +1620,21 @@ def main():
if args.provider:
os.environ["AI_PROVIDER"] = args.provider
# Providers speaking the OpenAI protocol read OPENAI_MODEL*;
- # bedrock/anthropic read ANTHROPIC_MODEL*.
+ # bedrock/anthropic read ANTHROPIC_MODEL*; orcarouter has its own.
_OPENAI_FAMILY = ("openai", "bedrock-mantle")
if args.model:
provider = os.environ.get("AI_PROVIDER", "").lower()
- if provider in _OPENAI_FAMILY:
+ if provider == "orcarouter":
+ os.environ["ORCAROUTER_MODEL"] = args.model
+ elif provider in _OPENAI_FAMILY:
os.environ["OPENAI_MODEL"] = args.model
else:
os.environ["ANTHROPIC_MODEL"] = args.model
if args.fast_model:
provider = os.environ.get("AI_PROVIDER", "").lower()
- if provider in _OPENAI_FAMILY:
+ if provider == "orcarouter":
+ os.environ["ORCAROUTER_SMALL_FAST_MODEL"] = args.fast_model
+ elif provider in _OPENAI_FAMILY:
os.environ["OPENAI_SMALL_FAST_MODEL"] = args.fast_model
else:
os.environ["ANTHROPIC_SMALL_FAST_MODEL"] = args.fast_model
diff --git a/seatunnel-cli/seatunnel_cli/llm_provider.py b/seatunnel-cli/seatunnel_cli/llm_provider.py
index 29a5c13384..a15fb43dfe 100644
--- a/seatunnel-cli/seatunnel_cli/llm_provider.py
+++ b/seatunnel-cli/seatunnel_cli/llm_provider.py
@@ -21,6 +21,7 @@ Supports multiple backends while presenting a unified interface:
- bedrock : AWS Bedrock Converse API (Claude models)
- anthropic: Anthropic Messages API (direct)
- openai : OpenAI Chat Completions API
+ - orcarouter: OrcaRouter AI gateway (OpenAI Chat Completions API)
All providers normalize their responses to a common internal format
so that the agent layer (agents.py) needs no provider-specific code.
@@ -1250,6 +1251,66 @@ class BedrockMantleProvider(LLMProvider):
}
+# ─── OrcaRouter Provider ───
+
+class OrcaRouterProvider(OpenAIProvider):
+ """OrcaRouter AI gateway provider (OpenAI Chat Completions API).
+
+ OrcaRouter is an OpenAI-compatible gateway that exposes many models (and
+ provider/model routing namespaces) behind one endpoint. Models are
+ addressed as ``provider/model``, e.g. ``orcarouter/auto`` routes and
+ grades automatically. Defaults to the ``orcarouter/auto`` model, which
+ automatically selects the best model for each request.
+
+ Since OrcaRouter speaks the OpenAI Chat Completions protocol, this
+ provider mirrors :class:`OpenAIProvider` and only customizes the base
+ URL, the API key environment variable, and the default model.
+ """
+
+ #: OrcaRouter's OpenAI-compatible base URL.
+ DEFAULT_BASE_URL = "https://api.orcarouter.ai/v1"
+ #: Default model: auto-routes to the best model for the request.
+ DEFAULT_MODEL = "orcarouter/auto"
+
+ def __init__(self):
+ try:
+ import openai
+ except ImportError:
+ raise ImportError(
+ "openai package required for AI_PROVIDER=orcarouter. "
+ "Install it: pip install openai"
+ )
+
+ api_key = os.environ.get("ORCAROUTER_API_KEY")
+ if not api_key:
+ raise ValueError(
+ "ORCAROUTER_API_KEY environment variable is required for "
+ "AI_PROVIDER=orcarouter"
+ )
+
+ self._model_id = os.environ.get(
+ "ORCAROUTER_MODEL",
+ os.environ.get("OPENAI_MODEL", self.DEFAULT_MODEL))
+ self._fast_model_id = os.environ.get(
+ "ORCAROUTER_SMALL_FAST_MODEL",
+ os.environ.get("OPENAI_SMALL_FAST_MODEL", self._model_id))
+ self._client = openai.OpenAI(api_key=api_key, base_url=self.DEFAULT_BASE_URL)
+ self._echo_reasoning_content = _env_bool(
+ "ORCAROUTER_ECHO_REASONING_CONTENT", True)
+
+ @property
+ def provider_name(self) -> str:
+ return "orcarouter"
+
+ @property
+ def model_id(self) -> str:
+ return self._model_id
+
+ @property
+ def fast_model_id(self) -> str:
+ return self._fast_model_id
+
+
# ─── Config file ───
@@ -1286,11 +1347,15 @@ def _auto_detect_provider() -> str | None:
if os.environ.get("ANTHROPIC_API_KEY"):
return "anthropic"
- # 2. OpenAI API key
+ # 2. OrcaRouter gateway key
+ if os.environ.get("ORCAROUTER_API_KEY"):
+ return "orcarouter"
+
+ # 3. OpenAI API key
if os.environ.get("OPENAI_API_KEY"):
return "openai"
- # 3. AWS credentials (for Bedrock)
+ # 4. AWS credentials (for Bedrock)
if os.environ.get("AWS_ACCESS_KEY_ID") or os.environ.get("AWS_PROFILE"):
return "bedrock"
try:
@@ -1312,6 +1377,7 @@ _PROVIDERS = {
"bedrock-mantle": BedrockMantleProvider,
"anthropic": AnthropicProvider,
"openai": OpenAIProvider,
+ "orcarouter": OrcaRouterProvider,
}
@@ -1354,16 +1420,22 @@ def create_provider(provider: str | None = None) -> LLMProvider:
# Apply model overrides from config file
if name and "models" in config:
model_config = config["models"].get(name, {})
- if model_config.get("model") and not os.environ.get("ANTHROPIC_MODEL") and not os.environ.get("OPENAI_MODEL"):
- if name in ("openai", "bedrock-mantle"):
- os.environ.setdefault("OPENAI_MODEL", model_config["model"])
- else:
- os.environ.setdefault("ANTHROPIC_MODEL", model_config["model"])
- if model_config.get("fast_model") and not os.environ.get("ANTHROPIC_SMALL_FAST_MODEL") and not os.environ.get("OPENAI_SMALL_FAST_MODEL"):
- if name in ("openai", "bedrock-mantle"):
- os.environ.setdefault("OPENAI_SMALL_FAST_MODEL", model_config["fast_model"])
- else:
- os.environ.setdefault("ANTHROPIC_SMALL_FAST_MODEL", model_config["fast_model"])
+ if model_config.get("model"):
+ if name == "orcarouter":
+ os.environ.setdefault("ORCAROUTER_MODEL", model_config["model"])
+ elif not os.environ.get("ANTHROPIC_MODEL") and not os.environ.get("OPENAI_MODEL"):
+ if name in ("openai", "bedrock-mantle"):
+ os.environ.setdefault("OPENAI_MODEL", model_config["model"])
+ else:
+ os.environ.setdefault("ANTHROPIC_MODEL", model_config["model"])
+ if model_config.get("fast_model"):
+ if name == "orcarouter":
+ os.environ.setdefault("ORCAROUTER_SMALL_FAST_MODEL", model_config["fast_model"])
+ elif not os.environ.get("ANTHROPIC_SMALL_FAST_MODEL") and not os.environ.get("OPENAI_SMALL_FAST_MODEL"):
+ if name in ("openai", "bedrock-mantle"):
+ os.environ.setdefault("OPENAI_SMALL_FAST_MODEL", model_config["fast_model"])
+ else:
+ os.environ.setdefault("ANTHROPIC_SMALL_FAST_MODEL", model_config["fast_model"])
# 4. Auto-detect
if not name:
diff --git a/seatunnel-cli/setup.sh b/seatunnel-cli/setup.sh
index 833d045d18..07703bdde6 100644
--- a/seatunnel-cli/setup.sh
+++ b/seatunnel-cli/setup.sh
@@ -73,6 +73,10 @@ echo " # AWS Bedrock"
echo " export AI_PROVIDER=bedrock"
echo " export AWS_REGION=us-east-1"
echo ""
+echo " # OrcaRouter AI gateway (OpenAI-compatible)"
+echo " export AI_PROVIDER=orcarouter"
+echo " export ORCAROUTER_API_KEY=orc_..."
+echo ""
echo " 3. Run the CLI:"
echo ""
echo " seatunnel # Interactive mode"
diff --git a/seatunnel-cli/tests/test_cli_provider_routing.py b/seatunnel-cli/tests/test_cli_provider_routing.py
index 39531fdbbc..1b459c9606 100644
--- a/seatunnel-cli/tests/test_cli_provider_routing.py
+++ b/seatunnel-cli/tests/test_cli_provider_routing.py
@@ -40,6 +40,7 @@ def _run_main_until_provider(argv):
captured["AI_PROVIDER"] = os.environ.get("AI_PROVIDER")
captured["OPENAI_MODEL"] = os.environ.get("OPENAI_MODEL")
captured["ANTHROPIC_MODEL"] = os.environ.get("ANTHROPIC_MODEL")
+ captured["ORCAROUTER_MODEL"] = os.environ.get("ORCAROUTER_MODEL")
raise _Stop()
with mock.patch.object(sys, "argv", ["seatunnel"] + argv), \
@@ -53,7 +54,8 @@ def _run_main_until_provider(argv):
def _clean_env():
saved = {k: os.environ.pop(k, None) for k in
("AI_PROVIDER", "OPENAI_MODEL", "ANTHROPIC_MODEL",
- "OPENAI_SMALL_FAST_MODEL", "ANTHROPIC_SMALL_FAST_MODEL")}
+ "OPENAI_SMALL_FAST_MODEL", "ANTHROPIC_SMALL_FAST_MODEL",
+ "ORCAROUTER_MODEL", "ORCAROUTER_SMALL_FAST_MODEL")}
yield
for k, v in saved.items():
if v is None:
@@ -77,6 +79,15 @@ def test_bedrock_still_routes_anthropic_model():
assert captured["OPENAI_MODEL"] is None
+def test_orcarouter_accepted_by_argparse_and_routes_own_model():
+ captured = _run_main_until_provider(
+ ["--provider", "orcarouter", "--model", "deepseek/deepseek-v4-pro", "hi"])
+ assert captured["AI_PROVIDER"] == "orcarouter"
+ assert captured["ORCAROUTER_MODEL"] == "deepseek/deepseek-v4-pro"
+ assert captured["OPENAI_MODEL"] is None
+ assert captured["ANTHROPIC_MODEL"] is None
+
+
def test_unknown_provider_rejected():
from seatunnel_cli import cli
with mock.patch.object(sys, "argv",
diff --git a/seatunnel-cli/tests/test_llm_provider_orcarouter.py b/seatunnel-cli/tests/test_llm_provider_orcarouter.py
new file mode 100644
index 0000000000..50af2280d2
--- /dev/null
+++ b/seatunnel-cli/tests/test_llm_provider_orcarouter.py
@@ -0,0 +1,200 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+import unittest
+from types import SimpleNamespace
+from unittest import mock
+
+from seatunnel_cli.llm_provider import (
+ LLMProvider,
+ OrcaRouterProvider,
+)
+
+
+class _FakeOrcaRouterCompletions:
+ def __init__(self, stream):
+ self.stream = stream
+ self.kwargs = None
+
+ def create(self, **kwargs):
+ self.kwargs = kwargs
+ return self.stream
+
+
+class _FakeOrcaRouterClient:
+ def __init__(self, stream):
+ self.completions = _FakeOrcaRouterCompletions(stream)
+ self.chat = SimpleNamespace(completions=self.completions)
+
+
+def _chunk(delta, finish_reason=None):
+ return SimpleNamespace(
+ choices=[
+ SimpleNamespace(
+ delta=delta,
+ finish_reason=finish_reason,
+ )
+ ]
+ )
+
+
+class OrcaRouterProviderTest(unittest.TestCase):
+ def test_default_model_and_base_url(self):
+ provider = OrcaRouterProvider.__new__(OrcaRouterProvider)
+ self.assertEqual(provider.provider_name, "orcarouter")
+ self.assertEqual(OrcaRouterProvider.DEFAULT_BASE_URL, "https://api.orcarouter.ai/v1")
+ self.assertEqual(OrcaRouterProvider.DEFAULT_MODEL, "orcarouter/auto")
+
+ def test_init_requires_api_key(self):
+ with mock.patch.dict("os.environ", {}, clear=True):
+ from seatunnel_cli import llm_provider
+ with self.assertRaises(ValueError):
+ llm_provider.OrcaRouterProvider()
+
+ def test_echo_reasoning_content_env_override(self):
+ with mock.patch.dict(
+ "os.environ",
+ {"ORCAROUTER_API_KEY": "orc_test", "ORCAROUTER_ECHO_REASONING_CONTENT": "false"},
+ clear=False,
+ ):
+ from seatunnel_cli import llm_provider
+ provider = llm_provider.OrcaRouterProvider()
+ self.assertFalse(provider._echo_reasoning_content)
+
+ with mock.patch.dict(
+ "os.environ",
+ {"ORCAROUTER_API_KEY": "orc_test", "ORCAROUTER_ECHO_REASONING_CONTENT": "true"},
+ clear=False,
+ ):
+ from seatunnel_cli import llm_provider
+ provider = llm_provider.OrcaRouterProvider()
+ self.assertTrue(provider._echo_reasoning_content)
+
+ # Defaults to True when unset (parity with OPENAI_ECHO_REASONING_CONTENT).
+ with mock.patch.dict("os.environ", {"ORCAROUTER_API_KEY": "orc_test"}, clear=False):
+ from seatunnel_cli import llm_provider
+ provider = llm_provider.OrcaRouterProvider()
+ self.assertTrue(provider._echo_reasoning_content)
+
+ def test_stream_uses_openai_protocol_and_collects_text(self):
+ provider = OrcaRouterProvider.__new__(OrcaRouterProvider)
+ provider._model_id = "deepseek/deepseek-v4-pro"
+ provider._client = _FakeOrcaRouterClient(
+ [
+ _chunk(SimpleNamespace(content="Sync ", tool_calls=None)),
+ _chunk(SimpleNamespace(content="users to S3", tool_calls=None)),
+ _chunk(
+ SimpleNamespace(content=None, tool_calls=None),
+ finish_reason="stop",
+ ),
+ ]
+ )
+
+ events = list(
+ provider.chat_stream(
+ messages=[
+ {
+ "role": "user",
+ "content": [{"text": "sync mysql to s3"}],
+ }
+ ]
+ )
+ )
+ response = LLMProvider.collect_stream(events)
+
+ self.assertEqual(
+ response["output"]["message"]["content"],
+ [{"text": "Sync users to S3"}],
+ )
+ # The default model is used when no override is passed.
+ self.assertEqual(
+ provider._client.completions.kwargs["model"], "deepseek/deepseek-v4-pro"
+ )
+
+ def test_chat_round_trip(self):
+ provider = OrcaRouterProvider.__new__(OrcaRouterProvider)
+ provider._model_id = "orcarouter/auto"
+ response = SimpleNamespace(
+ choices=[
+ SimpleNamespace(
+ message=SimpleNamespace(
+ content="PLAN: use Jdbc",
+ tool_calls=None,
+ ),
+ finish_reason="stop",
+ )
+ ]
+ )
+ provider._client = _FakeOrcaRouterClient(response)
+
+ result = provider.chat(
+ messages=[
+ {
+ "role": "user",
+ "content": [{"text": "sync oracle to iceberg"}],
+ }
+ ]
+ )
+
+ self.assertEqual(
+ result["output"]["message"]["content"],
+ [{"text": "PLAN: use Jdbc"}],
+ )
+ self.assertEqual(result["stopReason"], "end_turn")
+
+ def test_config_model_override_is_independent(self):
+ """Config-file model overrides apply even when unrelated model env
+ vars (ANTHROPIC_MODEL/OPENAI_MODEL) are set elsewhere."""
+ import os
+ import tempfile
+
+ from seatunnel_cli import llm_provider
+
+ tmp = tempfile.TemporaryDirectory()
+ original = llm_provider.get_config_path
+
+ def fake_get_config_path():
+ return os.path.join(tmp.name, "config.json")
+
+ llm_provider.get_config_path = fake_get_config_path
+ try:
+ with mock.patch.dict(
+ "os.environ",
+ {"ORCAROUTER_API_KEY": "orc_test", "ANTHROPIC_MODEL": "claude-other"},
+ clear=False,
+ ):
+ llm_provider.save_config(
+ {
+ "provider": "orcarouter",
+ "models": {
+ "orcarouter": {
+ "model": "deepseek/deepseek-v4-pro",
+ "fast_model": "qwen/qwen3.8-flash",
+ }
+ },
+ }
+ )
+ provider = llm_provider.create_provider()
+ self.assertEqual(provider.model_id, "deepseek/deepseek-v4-pro")
+ self.assertEqual(provider.fast_model_id, "qwen/qwen3.8-flash")
+ finally:
+ llm_provider.get_config_path = original
+ tmp.cleanup()
+
+
+if __name__ == "__main__":
+ unittest.main()