feat: add OrcaRouter as a dedicated model platform by zhenjunchen-png · Pull Request #4048 · camel-ai/camel

zhenjunchen-png · 2026-05-12T11:48:28Z

Related Issue

Description

Adds ModelPlatformType.ORCAROUTER as a dedicated model platform, mirroring the existing OpenRouter / ModelScope integrations. OrcaRouter (https://www.orcarouter.ai) is an OpenAI-compatible LLM gateway with an adaptive routing engine that picks the upstream model per request.

Why a dedicated platform rather than `OPENAI_COMPATIBLE_MODEL`

This is the question raised on #3282 (n1n.ai). The reason OrcaRouter falls on the OpenRouter / CometAPI side of that line:

orcarouter/auto is a router, not a model id. It dispatches each request via one of five configurable strategies — cheapest, balanced, quality, adaptive (LinUCB contextual bandit; learns from production traffic), or gated_adaptive (adaptive plus a difficulty pre-filter that routes mundane prompts to a "weak" model pool and hard prompts to a "strong" one). The dedicated ModelType.ORCAROUTER_AUTO enum surfaces this as a first-class entry — OPENAI_COMPATIBLE_MODEL can only present it as an opaque string.
Provider-specific knobs. OrcaRouterConfig.extra_body carries OrcaRouter-specific routing preferences and fallback model lists through to the API — encoded as a typed config field on this provider's class rather than polluting the generic OpenAI surface.
Stable platform identifier for downstream tooling. Downstream apps (e.g. eigent-ai/eigent — see feat: add OrcaRouter as a BYOK provider with a searchable model picker eigent-ai/eigent#1632 for the BYOK card that uses OrcaRouter today) can key per-provider defaults / observability / billing on the enum value rather than carrying their own provider alias maps.
IDE-discoverable flagship enums. Free-form Union[ModelType, str] is still accepted for the full catalog at https://www.orcarouter.ai/models, but a curated set of ModelType.ORCAROUTER_* enums (AUTO, GPT_5, CLAUDE_OPUS_4_7, GEMINI_3_FLASH_PREVIEW, GROK_4_3) shows up in autocomplete and is wired into token_limit / support_native_tool_calling like other dedicated platforms.

The mintlify docs section under docs/mintlify/key_modules/models.mdx walks through how orcarouter/auto works, including the reward signal that drives the adaptive strategies (success / cost / latency / rate-limit / structured-output format).

What is the purpose of this pull request?

Bug fix
New Feature
Documentation update
Other

Checklist

I have read and agree to the AI-Generated Code Policy
I have linked this PR to an issue ([Feature Request] Add OrcaRouter as a dedicated model platform #4047)
I have checked dependencies — no new ones introduced
I have updated the tests accordingly (test/models/test_orcarouter_model.py — 14 cases covering predefined enums + free-form strings + platform from_name round-trip + extra_body config)
I have updated the documentation — docs/mintlify/key_modules/models.mdx (<Tab title="OrcaRouter"> with adaptive-routing explainer + table row), docs/key_modules/models.md (synced), docs/mintlify/docs.json (nav entries)
I have added examples (examples/models/orcarouter_example.py, three scenarios — AUTO / predefined enum / free-form string — with live output captured in the trailing docstring)

Files

File	Change
`camel/types/enums.py`	`ModelPlatformType.ORCAROUTER = "orcarouter"` + `is_orcarouter` property; 5 `ModelType.ORCAROUTER_*` entries + `is_orcarouter` ModelType property; registered in `support_native_tool_calling`; `token_limit` covered for all 5
`camel/types/unified_model_type.py`	`is_orcarouter` property (returns True) for free-form string usage
`camel/configs/orcarouter_config.py` (new)	`OrcaRouterConfig(BaseConfig)` with standard OpenAI-compat params plus `extra_body` for OrcaRouter-specific routing pass-through
`camel/configs/__init__.py`	Export `OrcaRouterConfig`, `ORCAROUTER_API_PARAMS`
`camel/models/orcarouter_model.py` (new)	`OrcaRouterModel(OpenAICompatibleModel)` — base URL `https://api.orcarouter.ai/v1`, env `ORCAROUTER_API_KEY`; docstring leads with `ORCAROUTER_AUTO` quickstart
`camel/models/__init__.py`	Export `OrcaRouterModel`
`camel/models/model_factory.py`	Register `ORCAROUTER -> OrcaRouterModel`
`camel/utils/commons.py`	`env_key_urls` entry pointing to https://www.orcarouter.ai/
`examples/models/orcarouter_example.py` (new)	Three scenarios with live-API output
`test/models/test_orcarouter_model.py` (new)	14 cases
`docs/mintlify/key_modules/models.mdx`	`<Tab title="OrcaRouter">` with adaptive-routing explainer + `<Note>` callout + table row
`docs/key_modules/models.md`	Plain-text table row
`docs/mintlify/docs.json`	Nav entries for `camel.models.orcarouter_model` / `camel.configs.orcarouter_config`

Testing evidence

$ python -m pytest test/models/test_orcarouter_model.py --full-test-mode
============================= test session starts =============================
collected 14 items

test/models/test_orcarouter_model.py ..............                    [100%]

============================== 14 passed in 6.45s ==============================

$ python -m ruff check <all changed files>
All checks passed!

Live run against the OrcaRouter API (also captured in examples/models/orcarouter_example.py docstring):

=== Example 1: ORCAROUTER_AUTO (smart routing) ===
Hi CAMEL AI! 👋 It's great to connect with an open-source community
dedicated to advancing autonomous and communicative agents. Keep up the
amazing work! 🚀

=== Example 2: Pin Claude Opus 4.7 via predefined enum ===
In the silent hum of its first awakening, the agent traced a single
word back through the tangled roots of every language it knew and
understood, at last, that to speak was not to transmit but to reach.

=== Example 3: Pin an arbitrary model via free-form string ===
pong

Disclosure

I'm an engineer on the OrcaRouter team.

OrcaRouter (https://orcarouter.ai) is an OpenAI-compatible LLM gateway that routes each request to the cheapest or fastest provider across 40+ upstream model providers (OpenAI, Anthropic, Google, Azure, AWS Bedrock, DeepSeek, etc.). This change mirrors the existing OpenRouter integration so users can select OrcaRouter via ModelPlatformType.ORCAROUTER instead of having to fall back to OPENAI_COMPATIBLE_MODEL with a manually filled base URL. - camel/types/enums.py: add ORCAROUTER platform enum + is_orcarouter property - camel/configs/orcarouter_config.py: new OrcaRouterConfig (mirrors OpenRouterConfig) - camel/models/orcarouter_model.py: new OrcaRouterModel (mirrors OpenRouterModel) - camel/models/model_factory.py: register ORCAROUTER -> OrcaRouterModel - examples/models/orcarouter_example.py: usage example - test/models/test_orcarouter_model.py: unit tests Model types are accepted as free-form strings since OrcaRouter routes across 40+ providers with a continuously evolving model catalog; no ORCAROUTER_* ModelType enum entries are predefined. Default base URL: https://api.orcarouter.ai/v1 Default API key env: ORCAROUTER_API_KEY

claude

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

coderabbitai · 2026-05-12T11:49:46Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 4615dc6a-3993-401f-9f6f-e118c9660268

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

fengju0213

thanks for this pr！@zhenjunchen-png
left a comment

fengju0213 · 2026-05-13T06:52:19Z

+'''
+===============================================================================
+This example demonstrates how to use OrcaRouter with the CAMEL framework.
+
+OrcaRouter (https://orcarouter.ai) is an OpenAI-compatible LLM gateway that
+sits between your application and 40+ upstream model providers. Each request
+is routed to the cheapest or fastest provider that can serve the requested
+model.
+
+Before running this example, set the ORCAROUTER_API_KEY environment variable
+with an API key from https://orcarouter.ai.
+===============================================================================
+'''


Here we usually put the actual results from running the model.

Good catch — thanks! Added the live output from running the example against the OrcaRouter API to the trailing docstring (matches the convention in cometapi_model_example.py). Updated in 6c261f0.

Builds on the initial OrcaRouter platform integration to address model discoverability — CAMEL users targeting the dedicated platform now have both IDE autocomplete and a smart-routing default, without locking the catalog to a static list. Predefined `ModelType` entries (mirroring the OpenRouter / CometAPI pattern): `ORCAROUTER_AUTO`, `ORCAROUTER_GPT_5`, `ORCAROUTER_GPT_4O`, `ORCAROUTER_CLAUDE_OPUS_4_7`, `ORCAROUTER_CLAUDE_OPUS_4_6`, `ORCAROUTER_CLAUDE_SONNET_4_6`, `ORCAROUTER_GEMINI_2_5_PRO`. Any model id from the full catalog at https://docs.orcarouter.ai/ remains usable as a free-form `Union[ModelType, str]` value — predefined entries are just a curated subset for autocomplete. `ORCAROUTER_AUTO` ("orcarouter/auto") is OrcaRouter's smart-routing sentinel that picks the cheapest / fastest upstream provider per request. Documented as the recommended starting point in the model class docstring, the example file, and the mintlify model docs page. - camel/types/enums.py: 7 ModelType entries, `ModelType.is_orcarouter` property, registration in `support_native_tool_calling`, and `token_limit` entries covering all 7 (128K / 400K / 1M / 1_048_576) - camel/types/unified_model_type.py: `is_orcarouter` property (returns True) for string-based model_type usage - camel/models/orcarouter_model.py: docstring rewritten to lead with `ORCAROUTER_AUTO` + catalog link - camel/utils/commons.py: `ORCAROUTER_API_KEY` entry in `env_key_urls` so the missing-key error points users to https://orcarouter.ai/ - examples/models/orcarouter_example.py: three scenarios — AUTO, predefined enum, free-form string - docs/mintlify/key_modules/models.mdx: new `<Tab title="OrcaRouter">` mirroring the CometAPI structure, with an `<Note>` callout for the smart-routing flow; "API & Connector Platforms" table row - docs/key_modules/models.md: plain-text table row - docs/mintlify/docs.json: nav entries for the auto-generated `camel.models.orcarouter_model` / `camel.configs.orcarouter_config` reference pages - test/models/test_orcarouter_model.py: parametrized tests over the 7 predefined enums (token limit / tool-call capability / OrcaRouter membership at ModelType level) + free-form string regression cases + `from_name("orcarouter")` round-trip

@fengju0213

Per review feedback from @fengju0213 on camel-ai#4048, attach the live output from running the example against the OrcaRouter API to the trailing docstring (matches the convention used in cometapi_model_example.py).

…ting Predefined `ModelType.ORCAROUTER_*` set replaced to match the current flagship lineup at OrcaRouter: Removed: ORCAROUTER_GPT_4O, ORCAROUTER_CLAUDE_OPUS_4_6, ORCAROUTER_CLAUDE_SONNET_4_6, ORCAROUTER_GEMINI_2_5_PRO Added: ORCAROUTER_GEMINI_3_FLASH_PREVIEW, ORCAROUTER_GROK_4_3 Final five (in priority order): ORCAROUTER_AUTO, ORCAROUTER_GPT_5, ORCAROUTER_CLAUDE_OPUS_4_7, ORCAROUTER_GEMINI_3_FLASH_PREVIEW, ORCAROUTER_GROK_4_3. `ModelType.is_orcarouter` and the `token_limit` buckets (128K / 400K / 1M / 1_048_576) updated to match. Documentation: the `<Tab title="OrcaRouter">` in docs/mintlify/key_modules/models.mdx now leads with a "How orcarouter/auto works" section that describes the five router strategies (cheapest / balanced / quality / adaptive (LinUCB) / gated_adaptive), the reward signal that drives the adaptive strategies, and the differentiator over fixed-model gateways. The console URL for configuring routers is linked. URL audit: split usages by intent — homepage `www.orcarouter.ai`, model catalog `www.orcarouter.ai/models`, API/routing reference `docs.orcarouter.ai`. `commons.py` env_key_urls + model docstring catalog reference updated to match. Example: scenario 2 now pins `ORCAROUTER_CLAUDE_OPUS_4_7` (was 4.6) without an `OrcaRouterConfig(temperature=...)` because Claude Opus 4.7 is a reasoning model that rejects `temperature`. The trailing "Sample output" docstring is refreshed from a live run against the OrcaRouter API.

fengju0213 · 2026-05-14T09:04:01Z

+    # (cheapest / balanced / quality / adaptive / gated_adaptive) is
+    # configurable from the OrcaRouter console — the adaptive strategies
+    # learn the best upstream per workload from production traffic.
+    ORCAROUTER_AUTO = "orcarouter/auto"


We usually don’t use auto as the model name, because users won’t know which model is actually being used, and it also makes the token limit difficult to set.

thanks @fengju0213, i think it's ok to set this

okay，then this PR should be fine.

let me fix the cicd

zhenjun.chen added 2 commits May 12, 2026 19:42

docs: point OrcaRouterConfig Reference to docs.orcarouter.ai

224780a

claude Bot reviewed May 12, 2026

View reviewed changes

fengju0213 assigned zhenjunchen-png May 12, 2026

fengju0213 added this to the Sprint 52 milestone May 13, 2026

docs: document OrcaRouter extra body support

8e1dd7e

fengju0213 force-pushed the feat/add-orcarouter-platform branch from 6794563 to 8e1dd7e Compare May 13, 2026 04:50

fengju0213 reviewed May 13, 2026

View reviewed changes

zhenjun.chen added 3 commits May 13, 2026 19:03

docs(example): include actual model outputs in orcarouter example

6c261f0

Per review feedback from @fengju0213 on camel-ai#4048, attach the live output from running the example against the OrcaRouter API to the trailing docstring (matches the convention used in cometapi_model_example.py).

zhenjunchen-png mentioned this pull request May 14, 2026

[Feature Request] Add OrcaRouter as a dedicated model platform #4047

Closed

fengju0213 reviewed May 14, 2026

View reviewed changes

fengju0213 and others added 3 commits May 14, 2026 19:10

Merge branch 'master' into feat/add-orcarouter-platform

cb11084

Update orcarouter_example.py

2a80506

minor update

c1d9a36

fengju0213 merged commit 0a41603 into camel-ai:master May 14, 2026
8 of 13 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add OrcaRouter as a dedicated model platform#4048

feat: add OrcaRouter as a dedicated model platform#4048
fengju0213 merged 9 commits into
camel-ai:masterfrom
zhenjunchen-png:feat/add-orcarouter-platform

zhenjunchen-png commented May 12, 2026 •

edited

Loading

Uh oh!

claude Bot left a comment

Uh oh!

coderabbitai Bot commented May 12, 2026 •

edited

Loading

Review skipped

Uh oh!

fengju0213 left a comment

Uh oh!

fengju0213 May 13, 2026

Uh oh!

zhenjunchen-png May 13, 2026

Uh oh!

fengju0213 May 14, 2026

Uh oh!

Wendong-Fan May 14, 2026

Uh oh!

fengju0213 May 14, 2026

Uh oh!

fengju0213 May 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

zhenjunchen-png commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

Description

Why a dedicated platform rather than OPENAI_COMPATIBLE_MODEL

What is the purpose of this pull request?

Checklist

Files

Testing evidence

Disclosure

Uh oh!

claude Bot left a comment

Choose a reason for hiding this comment

Claude Code Review

Uh oh!

coderabbitai Bot commented May 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

fengju0213 left a comment

Choose a reason for hiding this comment

Uh oh!

fengju0213 May 13, 2026

Choose a reason for hiding this comment

Uh oh!

zhenjunchen-png May 13, 2026

Choose a reason for hiding this comment

Uh oh!

fengju0213 May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Wendong-Fan May 14, 2026

Choose a reason for hiding this comment

Uh oh!

fengju0213 May 14, 2026

Choose a reason for hiding this comment

Uh oh!

fengju0213 May 14, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zhenjunchen-png commented May 12, 2026 •

edited

Loading

Why a dedicated platform rather than `OPENAI_COMPATIBLE_MODEL`

coderabbitai Bot commented May 12, 2026 •

edited

Loading