Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat: add OrcaRouter as a dedicated model platform (#4048)

zhenjunchen-png0a41603d4a3f
diff --git a/camel/configs/__init__.py b/camel/configs/__init__.py
index e28814c5e..1b8719910 100644
--- a/camel/configs/__init__.py
+++ b/camel/configs/__init__.py
@@ -44,6 +44,7 @@ from .nvidia_config import NVIDIA_API_PARAMS, NvidiaConfig
from .ollama_config import OLLAMA_API_PARAMS, OllamaConfig
from .openai_config import OPENAI_API_PARAMS, ChatGPTConfig
from .openrouter_config import OPENROUTER_API_PARAMS, OpenRouterConfig
+from .orcarouter_config import ORCAROUTER_API_PARAMS, OrcaRouterConfig
from .ppio_config import PPIO_API_PARAMS, PPIOConfig
from .qianfan_config import QIANFAN_API_PARAMS, QianfanConfig
from .qwen_config import QWEN_API_PARAMS, QwenConfig
@@ -65,93 +66,95 @@ from .yi_config import YI_API_PARAMS, YiConfig
from .zhipuai_config import ZHIPUAI_API_PARAMS, ZhipuAIConfig
__all__ = [
- 'BaseConfig',
- 'ChatGPTConfig',
- 'OPENAI_API_PARAMS',
- 'AihubMixConfig',
'AIHUBMIX_API_PARAMS',
- 'AnthropicConfig',
+ 'AIML_API_PARAMS',
+ 'AMD_API_PARAMS',
'ANTHROPIC_API_PARAMS',
+ 'ATLASCLOUD_API_PARAMS',
+ 'AVIAN_API_PARAMS',
+ 'BEDROCK_API_PARAMS',
+ 'CEREBRAS_API_PARAMS',
+ 'COHERE_API_PARAMS',
+ 'COMETAPI_API_PARAMS',
+ 'CRYNUX_API_PARAMS',
+ 'DEEPSEEK_API_PARAMS',
+ 'FUNCTION_GEMMA_API_PARAMS',
'GROQ_API_PARAMS',
- 'GroqConfig',
- 'NEBIUS_API_PARAMS',
- 'NebiusConfig',
- 'LiteLLMConfig',
+ 'INTERNLM_API_PARAMS',
'LITELLM_API_PARAMS',
- 'NetmindConfig',
+ 'LMSTUDIO_API_PARAMS',
+ 'MINIMAX_API_PARAMS',
+ 'MISTRAL_API_PARAMS',
+ 'MODELSCOPE_API_PARAMS',
+ "MOONSHOT_API_PARAMS",
+ 'NEBIUS_API_PARAMS',
'NETMIND_API_PARAMS',
- 'NvidiaConfig',
+ 'NOVITA_API_PARAMS',
'NVIDIA_API_PARAMS',
- 'OllamaConfig',
'OLLAMA_API_PARAMS',
- 'ZhipuAIConfig',
- 'ZHIPUAI_API_PARAMS',
- 'GeminiConfig',
- 'Gemini_API_PARAMS',
- 'VLLMConfig',
- 'VLLM_API_PARAMS',
- 'SGLangConfig',
- 'SGLANG_API_PARAMS',
- 'MistralConfig',
- 'MISTRAL_API_PARAMS',
- 'RekaConfig',
+ 'OPENAI_API_PARAMS',
+ 'OPENROUTER_API_PARAMS',
+ 'ORCAROUTER_API_PARAMS',
+ 'PPIO_API_PARAMS',
+ 'QIANFAN_API_PARAMS',
+ 'QWEN_API_PARAMS',
'REKA_API_PARAMS',
- 'SambaVerseAPIConfig',
- 'SAMBA_VERSE_API_PARAMS',
- 'SambaCloudAPIConfig',
'SAMBA_CLOUD_API_PARAMS',
- 'TogetherAIConfig',
+ 'SAMBA_VERSE_API_PARAMS',
+ 'SGLANG_API_PARAMS',
+ 'SILICONFLOW_API_PARAMS',
'TOGETHERAI_API_PARAMS',
+ 'VLLM_API_PARAMS',
+ 'VOLCANO_API_PARAMS',
+ 'WATSONX_API_PARAMS',
+ 'XAI_API_PARAMS',
+ 'YI_API_PARAMS',
+ 'ZHIPUAI_API_PARAMS',
+ 'AIMLConfig',
+ 'AMDConfig',
+ 'AihubMixConfig',
+ 'AnthropicConfig',
+ 'AtlasCloudConfig',
+ 'AvianConfig',
+ 'BaseConfig',
+ 'BedrockConfig',
'CerebrasConfig',
- 'CEREBRAS_API_PARAMS',
+ 'ChatGPTConfig',
'CohereConfig',
- 'COHERE_API_PARAMS',
'CometAPIConfig',
- 'COMETAPI_API_PARAMS',
- 'YiConfig',
- 'YI_API_PARAMS',
- 'QwenConfig',
- 'QWEN_API_PARAMS',
- 'BedrockConfig',
- 'BEDROCK_API_PARAMS',
+ 'CrynuxConfig',
'DeepSeekConfig',
- 'DEEPSEEK_API_PARAMS',
- 'PPIOConfig',
- 'PPIO_API_PARAMS',
+ 'FunctionGemmaConfig',
+ 'GeminiConfig',
+ 'Gemini_API_PARAMS',
+ 'GroqConfig',
'InternLMConfig',
- 'INTERNLM_API_PARAMS',
- 'MoonshotConfig',
- "MOONSHOT_API_PARAMS",
+ 'LMStudioConfig',
+ 'LiteLLMConfig',
+ 'MinimaxConfig',
+ 'MistralConfig',
'ModelScopeConfig',
- 'MODELSCOPE_API_PARAMS',
+ 'MoonshotConfig',
+ 'NebiusConfig',
+ 'NetmindConfig',
'NovitaConfig',
- 'NOVITA_API_PARAMS',
- 'SiliconFlowConfig',
- 'SILICONFLOW_API_PARAMS',
- 'AIMLConfig',
- 'AIML_API_PARAMS',
- 'AMDConfig',
- 'AMD_API_PARAMS',
+ 'NvidiaConfig',
+ 'OllamaConfig',
'OpenRouterConfig',
- 'OPENROUTER_API_PARAMS',
- 'AtlasCloudConfig',
- 'ATLASCLOUD_API_PARAMS',
- 'LMSTUDIO_API_PARAMS',
- 'LMStudioConfig',
- 'MINIMAX_API_PARAMS',
- 'MinimaxConfig',
- 'WatsonXConfig',
- 'WATSONX_API_PARAMS',
+ 'OrcaRouterConfig',
+ 'PPIOConfig',
'QianfanConfig',
- 'QIANFAN_API_PARAMS',
- 'CrynuxConfig',
- 'CRYNUX_API_PARAMS',
- 'FunctionGemmaConfig',
- 'FUNCTION_GEMMA_API_PARAMS',
+ 'QwenConfig',
+ 'RekaConfig',
+ 'SGLangConfig',
+ 'SambaCloudAPIConfig',
+ 'SambaVerseAPIConfig',
+ 'SiliconFlowConfig',
+ 'TogetherAIConfig',
+ 'VLLMConfig',
'VolcanoConfig',
- 'VOLCANO_API_PARAMS',
- 'AvianConfig',
- 'AVIAN_API_PARAMS',
+ 'WatsonXConfig',
'XAIConfig',
- 'XAI_API_PARAMS',
+ 'YiConfig',
+ 'ZhipuAIConfig',
]
diff --git a/camel/configs/orcarouter_config.py b/camel/configs/orcarouter_config.py
new file mode 100644
index 000000000..024e409bb
--- /dev/null
+++ b/camel/configs/orcarouter_config.py
@@ -0,0 +1,112 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed 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.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+from __future__ import annotations
+
+from typing import Any, Dict, Optional, Sequence, Union
+
+from camel.configs.base_config import BaseConfig
+from camel.types import NotGiven
+
+
+class OrcaRouterConfig(BaseConfig):
+ r"""Defines the parameters for generating chat completions using OpenAI
+ compatibility via OrcaRouter.
+
+ Reference: https://docs.orcarouter.ai/
+
+ Args:
+ temperature (float, optional): Sampling temperature to use, between
+ :obj:`0` and :obj:`2`. Higher values make the output more random,
+ while lower values make it more focused and deterministic.
+ (default: :obj:`None`)
+ top_p (float, optional): An alternative to sampling with temperature,
+ called nucleus sampling, where the model considers the results of
+ the tokens with top_p probability mass. So :obj:`0.1` means only
+ the tokens comprising the top 10% probability mass are considered.
+ (default: :obj:`None`)
+ n (int, optional): How many chat completion choices to generate for
+ each input message. (default: :obj:`None`)
+ response_format (object, optional): An object specifying the format
+ that the model must output. Compatible with GPT-4 Turbo and all
+ GPT-3.5 Turbo models newer than gpt-3.5-turbo-1106. Setting to
+ {"type": "json_object"} enables JSON mode, which guarantees the
+ message the model generates is valid JSON. Important: when using
+ JSON mode, you must also instruct the model to produce JSON
+ yourself via a system or user message. Without this, the model
+ may generate an unending stream of whitespace until the generation
+ reaches the token limit, resulting in a long-running and seemingly
+ "stuck" request. Also note that the message content may be
+ partially cut off if finish_reason="length", which indicates the
+ generation exceeded max_tokens or the conversation exceeded the
+ max context length.
+ stream (bool, optional): If True, partial message deltas will be sent
+ as data-only server-sent events as they become available.
+ (default: :obj:`None`)
+ stop (str or list, optional): Up to :obj:`4` sequences where the API
+ will stop generating further tokens. (default: :obj:`None`)
+ max_tokens (int, optional): The maximum number of tokens to generate
+ in the chat completion. The total length of input tokens and
+ generated tokens is limited by the model's context length.
+ (default: :obj:`None`)
+ presence_penalty (float, optional): Number between :obj:`-2.0` and
+ :obj:`2.0`. Positive values penalize new tokens based on whether
+ they appear in the text so far, increasing the model's likelihood
+ to talk about new topics. See more information about frequency and
+ presence penalties. (default: :obj:`None`)
+ frequency_penalty (float, optional): Number between :obj:`-2.0` and
+ :obj:`2.0`. Positive values penalize new tokens based on their
+ existing frequency in the text so far, decreasing the model's
+ likelihood to repeat the same line verbatim. See more information
+ about frequency and presence penalties. (default: :obj:`None`)
+ user (str, optional): A unique identifier representing your end-user,
+ which can help OrcaRouter to monitor and detect abuse.
+ (default: :obj:`None`)
+ tools (list[FunctionTool], optional): A list of tools the model may
+ call. Currently, only functions are supported as a tool. Use this
+ to provide a list of functions the model may generate JSON inputs
+ for. A max of 128 functions are supported. (default: :obj:`None`)
+ tool_choice (Union[dict[str, str], str], optional): Controls which (if
+ any) tool is called by the model. :obj:`"none"` means the model
+ will not call any tool and instead generates a message.
+ :obj:`"auto"` means the model can pick between generating a
+ message or calling one or more tools. :obj:`"required"` means the
+ model must call one or more tools. Specifying a particular tool
+ via {"type": "function", "function": {"name": "my_function"}}
+ forces the model to call that tool. :obj:`"none"` is the default
+ when no tools are present. :obj:`"auto"` is the default if tools
+ are present. (default: :obj:`None`)
+ extra_body (Dict[str, Any], optional): Extra request body fields to
+ pass through to OrcaRouter, such as routing preferences or fallback
+ model lists. (default: :obj:`None`)
+ """
+
+ temperature: Optional[float] = None
+ top_p: Optional[float] = None
+ n: Optional[int] = None
+ stream: Optional[bool] = None
+ stop: Optional[Union[str, Sequence[str], NotGiven]] = None
+ max_tokens: Optional[Union[int, NotGiven]] = None
+ presence_penalty: Optional[float] = None
+ response_format: Optional[Union[dict, NotGiven]] = None
+ frequency_penalty: Optional[float] = None
+ user: Optional[str] = None
+ tool_choice: Optional[
+ Union[Dict[str, Union[str, Dict[str, str]]], str]
+ ] = None
+ extra_body: Optional[Dict[str, Any]] = None
+
+
+ORCAROUTER_API_PARAMS = {
+ param for param in OrcaRouterConfig.model_fields.keys()
+}
diff --git a/camel/models/__init__.py b/camel/models/__init__.py
index f6c6a0ff3..5be1852ac 100644
--- a/camel/models/__init__.py
+++ b/camel/models/__init__.py
@@ -50,6 +50,7 @@ from .openai_audio_models import OpenAIAudioModels
from .openai_compatible_model import OpenAICompatibleModel
from .openai_model import OpenAIModel
from .openrouter_model import OpenRouterModel
+from .orcarouter_model import OrcaRouterModel
from .ppio_model import PPIOModel
from .qianfan_model import QianfanModel
from .qwen_model import QwenModel
@@ -67,59 +68,60 @@ from .yi_model import YiModel
from .zhipuai_model import ZhipuAIModel
__all__ = [
- 'BaseModelBackend',
- 'OpenAIModel',
- 'OpenRouterModel',
+ 'AIMLModel',
+ 'AMDModel',
+ 'AWSBedrockConverseModel',
+ 'AWSBedrockModel',
+ 'AihubMixModel',
+ 'AnthropicModel',
'AtlasCloudModel',
+ 'AvianModel',
'AzureOpenAIModel',
- 'AnthropicModel',
- 'AMDModel',
- 'MistralModel',
- 'GroqModel',
- 'StubModel',
- 'ZhipuAIModel',
+ 'BaseAudioModel',
+ 'BaseModelBackend',
'CerebrasModel',
'CohereModel',
'CometAPIModel',
+ 'CrynuxModel',
+ 'DeepSeekModel',
+ 'FishAudioModel',
+ 'FunctionGemmaModel',
+ 'GeminiModel',
+ 'GroqModel',
+ 'InternLMModel',
+ 'LMStudioModel',
+ 'LiteLLMModel',
+ 'MinimaxModel',
+ 'MistralModel',
'ModelFactory',
'ModelManager',
- 'LiteLLMModel',
- 'OpenAIAudioModels',
- 'NetmindModel',
+ 'ModelProcessingError',
+ 'ModelScopeModel',
+ 'MoonshotModel',
+ 'NebiusModel',
'NemotronModel',
+ 'NetmindModel',
'NovitaModel',
'NvidiaModel',
'OllamaModel',
- 'VLLMModel',
- 'SGLangModel',
- 'GeminiModel',
+ 'OpenAIAudioModels',
'OpenAICompatibleModel',
- 'RekaModel',
- 'SambaModel',
- 'TogetherAIModel',
+ 'OpenAIModel',
+ 'OpenRouterModel',
+ 'OrcaRouterModel',
'PPIOModel',
- 'YiModel',
+ 'QianfanModel',
'QwenModel',
- 'AWSBedrockModel',
- 'AWSBedrockConverseModel',
- 'ModelProcessingError',
- 'NebiusModel',
- 'DeepSeekModel',
- 'FishAudioModel',
- 'InternLMModel',
- 'ModelScopeModel',
- 'MoonshotModel',
- 'AIMLModel',
- 'BaseAudioModel',
+ 'RekaModel',
+ 'SGLangModel',
+ 'SambaModel',
'SiliconFlowModel',
+ 'StubModel',
+ 'TogetherAIModel',
+ 'VLLMModel',
'VolcanoModel',
- 'LMStudioModel',
- 'MinimaxModel',
'WatsonXModel',
- 'QianfanModel',
- 'CrynuxModel',
- 'AihubMixModel',
- 'FunctionGemmaModel',
- 'AvianModel',
'XAIModel',
+ 'YiModel',
+ 'ZhipuAIModel',
]
diff --git a/camel/models/model_factory.py b/camel/models/model_factory.py
index fe4c5825b..5dc0aa2ca 100644
--- a/camel/models/model_factory.py
+++ b/camel/models/model_factory.py
@@ -48,6 +48,7 @@ from camel.models.ollama_model import OllamaModel
from camel.models.openai_compatible_model import OpenAICompatibleModel
from camel.models.openai_model import OpenAIModel
from camel.models.openrouter_model import OpenRouterModel
+from camel.models.orcarouter_model import OrcaRouterModel
from camel.models.ppio_model import PPIOModel
from camel.models.qianfan_model import QianfanModel
from camel.models.qwen_model import QwenModel
@@ -102,6 +103,7 @@ class ModelFactory:
ModelPlatformType.LMSTUDIO: LMStudioModel,
ModelPlatformType.MINIMAX: MinimaxModel,
ModelPlatformType.OPENROUTER: OpenRouterModel,
+ ModelPlatformType.ORCAROUTER: OrcaRouterModel,
ModelPlatformType.ATLASCLOUD: AtlasCloudModel,
ModelPlatformType.ZHIPU: ZhipuAIModel,
ModelPlatformType.GEMINI: GeminiModel,
diff --git a/camel/models/orcarouter_model.py b/camel/models/orcarouter_model.py
new file mode 100644
index 000000000..a78e6a4e0
--- /dev/null
+++ b/camel/models/orcarouter_model.py
@@ -0,0 +1,93 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed 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.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+import os
+from typing import Any, Dict, Optional, Union
+
+from camel.configs import OrcaRouterConfig
+from camel.models.openai_compatible_model import OpenAICompatibleModel
+from camel.types import ModelType
+from camel.utils import (
+ BaseTokenCounter,
+ api_keys_required,
+)
+
+
+class OrcaRouterModel(OpenAICompatibleModel):
+ r"""LLM API served by OrcaRouter in a unified OpenAICompatibleModel
+ interface.
+
+ OrcaRouter is an OpenAI-compatible LLM gateway that routes each request
+ to the cheapest or fastest upstream provider for the requested model.
+
+ Quickstart: pass ``ModelType.ORCAROUTER_AUTO`` to let OrcaRouter pick the
+ upstream for you — no need to know specific model ids. To pin a specific
+ model, use one of the predefined ``ModelType.ORCAROUTER_*`` enums
+ (discoverable in IDE autocomplete) or pass any model id from the full
+ catalog at https://www.orcarouter.ai/models as a free-form string (e.g.
+ ``"qwen/qwen3.5-flash"``).
+
+ Args:
+ model_type (Union[ModelType, str]): Model for which a backend is
+ created.
+ model_config_dict (Optional[Dict[str, Any]], optional): A dictionary
+ that will be fed into:obj:`openai.ChatCompletion.create()`.
+ If:obj:`None`, :obj:`OrcaRouterConfig().as_dict()` will be used.
+ (default: :obj:`None`)
+ api_key (Optional[str], optional): The API key for authenticating
+ with the OrcaRouter service. (default: :obj:`None`).
+ url (Optional[str], optional): The url to the OrcaRouter service.
+ (default: :obj:`None`)
+ token_counter (Optional[BaseTokenCounter], optional): Token counter to
+ use for the model. If not provided, :obj:`OpenAITokenCounter(
+ ModelType.GPT_4O_MINI)` will be used.
+ (default: :obj:`None`)
+ timeout (Optional[float], optional): The timeout value in seconds for
+ API calls. If not provided, will fall back to the MODEL_TIMEOUT
+ environment variable or default to 180 seconds.
+ (default: :obj:`None`)
+ max_retries (int, optional): Maximum number of retries for API calls.
+ (default: :obj:`3`)
+ **kwargs (Any): Additional arguments to pass to the client
+ initialization.
+ """
+
+ @api_keys_required([("api_key", "ORCAROUTER_API_KEY")])
+ def __init__(
+ self,
+ model_type: Union[ModelType, str],
+ model_config_dict: Optional[Dict[str, Any]] = None,
+ api_key: Optional[str] = None,
+ url: Optional[str] = None,
+ token_counter: Optional[BaseTokenCounter] = None,
+ timeout: Optional[float] = None,
+ max_retries: int = 3,
+ **kwargs: Any,
+ ) -> None:
+ if model_config_dict is None:
+ model_config_dict = OrcaRouterConfig().as_dict()
+ api_key = api_key or os.environ.get("ORCAROUTER_API_KEY")
+ url = url or os.environ.get(
+ "ORCAROUTER_API_BASE_URL", "https://api.orcarouter.ai/v1"
+ )
+ timeout = timeout or float(os.environ.get("MODEL_TIMEOUT", 180))
+ super().__init__(
+ model_type=model_type,
+ model_config_dict=model_config_dict,
+ api_key=api_key,
+ url=url,
+ token_counter=token_counter,
+ timeout=timeout,
+ max_retries=max_retries,
+ **kwargs,
+ )
diff --git a/camel/types/enums.py b/camel/types/enums.py
index 7d5cc69df..48f243628 100644
--- a/camel/types/enums.py
+++ b/camel/types/enums.py
@@ -173,6 +173,12 @@ class ModelType(UnifiedModelType, Enum):
OPENROUTER_OLYMPICODER_7B = "open-r1/olympiccoder-7b:free"
OPENROUTER_HORIZON_ALPHA = "openrouter/horizon-alpha"
+ ORCAROUTER_AUTO = "orcarouter/auto"
+ ORCAROUTER_GPT_5 = "openai/gpt-5"
+ ORCAROUTER_CLAUDE_OPUS_4_7 = "anthropic/claude-opus-4.7"
+ ORCAROUTER_GEMINI_3_FLASH_PREVIEW = "google/gemini-3-flash-preview"
+ ORCAROUTER_GROK_4_3 = "grok/grok-4.3"
+
# LMStudio models
LMSTUDIO_GEMMA_3_1B = "gemma-3-1b"
LMSTUDIO_GEMMA_3_4B = "gemma-3-4b"
@@ -604,6 +610,7 @@ class ModelType(UnifiedModelType, Enum):
self.is_groq,
self.is_cerebras,
self.is_openrouter,
+ self.is_orcarouter,
self.is_lmstudio,
self.is_sglang,
self.is_moonshot,
@@ -834,6 +841,17 @@ class ModelType(UnifiedModelType, Enum):
ModelType.OPENROUTER_HORIZON_ALPHA,
}
+ @property
+ def is_orcarouter(self) -> bool:
+ r"""Returns whether this type of models is served by OrcaRouter."""
+ return self in {
+ ModelType.ORCAROUTER_AUTO,
+ ModelType.ORCAROUTER_GPT_5,
+ ModelType.ORCAROUTER_CLAUDE_OPUS_4_7,
+ ModelType.ORCAROUTER_GEMINI_3_FLASH_PREVIEW,
+ ModelType.ORCAROUTER_GROK_4_3,
+ }
+
@property
def is_lmstudio(self) -> bool:
r"""Returns whether this type of models is served by LMStudio."""
@@ -1569,6 +1587,7 @@ class ModelType(UnifiedModelType, Enum):
ModelType.ERNIE_4_5_TURBO_VL,
ModelType.GLM_4_5_AIR,
ModelType.GLM_4_5_AIRX,
+ ModelType.ORCAROUTER_AUTO,
}:
return 128_000
elif self in {
@@ -1666,6 +1685,7 @@ class ModelType(UnifiedModelType, Enum):
ModelType.GPT_5_NANO,
ModelType.GPT_5_4_MINI,
ModelType.GPT_5_4_NANO,
+ ModelType.ORCAROUTER_GPT_5,
}:
return 400_000
elif self in {
@@ -1695,6 +1715,7 @@ class ModelType(UnifiedModelType, Enum):
ModelType.GPT_4_1_NANO,
ModelType.NOVITA_LLAMA_4_MAVERICK_17B,
ModelType.AVIAN_MINIMAX_M2_5,
+ ModelType.ORCAROUTER_GEMINI_3_FLASH_PREVIEW,
}:
return 1_048_576
elif self in {
@@ -1707,6 +1728,8 @@ class ModelType(UnifiedModelType, Enum):
ModelType.GPT_5_4_PRO,
ModelType.GPT_5_5,
ModelType.GPT_5_5_PRO,
+ ModelType.ORCAROUTER_CLAUDE_OPUS_4_7,
+ ModelType.ORCAROUTER_GROK_4_3,
}:
return 1_000_000
elif self in {
@@ -1925,6 +1948,7 @@ class ModelPlatformType(Enum):
NEBIUS = "nebius"
COMETAPI = "cometapi"
OPENROUTER = "openrouter"
+ ORCAROUTER = "orcarouter"
OLLAMA = "ollama"
LITELLM = "litellm"
LMSTUDIO = "lmstudio"
@@ -2005,6 +2029,11 @@ class ModelPlatformType(Enum):
r"""Returns whether this platform is openrouter."""
return self is ModelPlatformType.OPENROUTER
+ @property
+ def is_orcarouter(self) -> bool:
+ r"""Returns whether this platform is orcarouter."""
+ return self is ModelPlatformType.ORCAROUTER
+
@property
def is_lmstudio(self) -> bool:
r"""Returns whether this platform is lmstudio."""
diff --git a/camel/types/unified_model_type.py b/camel/types/unified_model_type.py
index 6dbfe71fa..fdf5e5c11 100644
--- a/camel/types/unified_model_type.py
+++ b/camel/types/unified_model_type.py
@@ -121,6 +121,11 @@ class UnifiedModelType(str):
r"""Returns whether the model is a OpenRouter served model."""
return True
+ @property
+ def is_orcarouter(self) -> bool:
+ r"""Returns whether the model is a OrcaRouter served model."""
+ return True
+
@property
def is_avian(self) -> bool:
r"""Returns whether the model is an Avian served model."""
diff --git a/camel/utils/commons.py b/camel/utils/commons.py
index a8a2a1ad7..39ca1661a 100644
--- a/camel/utils/commons.py
+++ b/camel/utils/commons.py
@@ -340,6 +340,7 @@ def api_keys_required(
'KLAVIS_API_KEY': "https://www.klavis.ai/docs",
'XAI_API_KEY': "https://docs.x.ai/docs/overview",
'AVIAN_API_KEY': "https://avian.io",
+ 'ORCAROUTER_API_KEY': "https://www.orcarouter.ai/",
'QUERIT_API_KEY': "https://www.querit.ai/en/dashboard/home",
}
key_way = env_key_urls.get(
diff --git a/docs/key_modules/models.md b/docs/key_modules/models.md
index 06f5d60bb..41d7bc28f 100644
--- a/docs/key_modules/models.md
+++ b/docs/key_modules/models.md
@@ -67,6 +67,7 @@ CAMEL supports a wide range of models, including [OpenAI’s GPT series](https:/
| **CometAPI** | [supported models](https://api.cometapi.com/pricing) |
| **Nebius** | [supported models](https://studio.nebius.com/) |
| **OpenRouter** | [supported models](https://openrouter.ai/models) |
+| **OrcaRouter** | [supported models](https://www.orcarouter.ai/models) |
| **PPIO** | [supported models](https://ppio.com/model-api/console) |
| **LiteLLM** | [supported models](https://docs.litellm.ai/docs/providers) |
| **OpenAI Compatible** | custom OpenAI-compatible endpoints via `OPENAI_COMPATIBLE_MODEL` |
diff --git a/docs/mintlify/docs.json b/docs/mintlify/docs.json
index eb3a86a47..d728e36f1 100644
--- a/docs/mintlify/docs.json
+++ b/docs/mintlify/docs.json
@@ -249,6 +249,7 @@
"reference/camel.configs.ollama_config",
"reference/camel.configs.openai_config",
"reference/camel.configs.openrouter_config",
+ "reference/camel.configs.orcarouter_config",
"reference/camel.configs.ppio_config",
"reference/camel.configs.qianfan_config",
"reference/camel.configs.qwen_config",
@@ -349,6 +350,7 @@
"reference/camel.models.openai_model",
"reference/camel.models.openai_responses_adapter",
"reference/camel.models.openrouter_model",
+ "reference/camel.models.orcarouter_model",
"reference/camel.models.ppio_model",
"reference/camel.models.qianfan_model",
"reference/camel.models.qwen_model",
diff --git a/docs/mintlify/key_modules/models.mdx b/docs/mintlify/key_modules/models.mdx
index 06f5d60bb..feb9a5122 100644
--- a/docs/mintlify/key_modules/models.mdx
+++ b/docs/mintlify/key_modules/models.mdx
@@ -67,6 +67,7 @@ CAMEL supports a wide range of models, including [OpenAI’s GPT series](https:/
| **CometAPI** | [supported models](https://api.cometapi.com/pricing) |
| **Nebius** | [supported models](https://studio.nebius.com/) |
| **OpenRouter** | [supported models](https://openrouter.ai/models) |
+| **OrcaRouter** | [supported models](https://www.orcarouter.ai/models) |
| **PPIO** | [supported models](https://ppio.com/model-api/console) |
| **LiteLLM** | [supported models](https://docs.litellm.ai/docs/providers) |
| **OpenAI Compatible** | custom OpenAI-compatible endpoints via `OPENAI_COMPATIBLE_MODEL` |
@@ -430,6 +431,91 @@ Integrate your favorite models into CAMEL-AI with straightforward Python calls.
</Tab>
+ <Tab title="OrcaRouter">
+
+ [OrcaRouter](https://www.orcarouter.ai/) is an OpenAI-compatible LLM gateway with an adaptive routing engine that picks the upstream model per request:
+
+ - **OrcaRouter Platform** ([www.orcarouter.ai](https://www.orcarouter.ai/)): Unified access across many upstream model providers.
+ - **API Key Setup**: Obtain your OrcaRouter API key from the dashboard at [www.orcarouter.ai](https://www.orcarouter.ai/).
+ - **Model Catalog** ([www.orcarouter.ai/models](https://www.orcarouter.ai/models)): Full list of supported upstream models.
+ - **OrcaRouter Docs** ([docs.orcarouter.ai](https://docs.orcarouter.ai/)): API and routing reference.
+
+ ```python
+ from camel.models import ModelFactory
+ from camel.types import ModelPlatformType, ModelType
+ from camel.configs import OrcaRouterConfig
+ from camel.agents import ChatAgent
+
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type=ModelType.ORCAROUTER_AUTO,
+ model_config_dict=OrcaRouterConfig(temperature=0.2).as_dict(),
+ )
+
+ agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=model
+ )
+
+ response = agent.step("Say hi to CAMEL AI community.")
+ print(response.msgs[0].content)
+ ```
+
+ ### How `orcarouter/auto` works
+
+ `orcarouter/auto` is **not a model id** — it's the default **router name** that OrcaRouter seeds for every workspace. The actual upstream model is chosen at runtime by the router's configured strategy:
+
+ | Strategy | Behavior |
+ |---|---|
+ | `cheapest` | Lowest-priced upstream that can serve the request (default) |
+ | `balanced` | Trades off price vs latency vs quality |
+ | `quality` | Highest-quality upstream |
+ | `adaptive` (LinUCB) | A linear contextual bandit (Li et al., WWW 2010) that picks among candidate upstreams from a learned weight vector over per-request features — prompt length, code/math/JSON density, declared `max_tokens` budget tier, and MinHash-LSH similarity to recent traffic |
+ | `gated_adaptive` | Layers a task-difficulty score on top of `adaptive` — mundane prompts are restricted to a "weak" model pool, hard prompts to a "strong" pool, and the bandit picks within each pool. Both the difficulty thresholds and the pool memberships are admin-configurable |
+
+ The adaptive strategies update each candidate's weights from a reward signal that combines success, cost, latency, rate-limit hits, and structured-output format compliance — so cost / quality / reliability tradeoffs are continuously tuned without manual intervention.
+
+ #### Why this matters
+
+ - **Self-tuning** — the adaptive strategies learn from your own traffic, so the routing improves as your workload mix shifts. No retraining scripts to babysit.
+ - **Microsecond overhead** — feature extraction and the bandit step are closed-form math; routing adds no measurable latency on top of the chosen upstream's response time.
+ - **Workload-aware in one call** — the same `orcarouter/auto` endpoint serves a 50-token summary and a 30K-token code refactor, picking the appropriate upstream for each. No client-side dispatch logic to maintain.
+ - **Cost & reliability guardrails by construction** — the reward signal explicitly penalises cost, latency, rate-limit hits, and structured-output format failures, so expensive / unreliable upstreams lose weight automatically.
+ - **Similarity-aware**, not just keyword-matched — MinHash-LSH clusters prompts by approximate Jaccard similarity, so the bandit learns from "prompts that look like this" rather than identical strings.
+ - **Admin-tunable without redeploys** — strategies, allowed-upstreams pools, difficulty thresholds, and reward weights are all configurable from the console without touching client code.
+ - **Per-router isolation** — you can run multiple named routers (`orcarouter/agent-cheap`, `orcarouter/agent-quality`, …) with different strategies side by side, all from the same API key.
+
+ Configure strategies, allowed upstreams, pools, and difficulty thresholds at [www.orcarouter.ai/console/routing](https://www.orcarouter.ai/console/routing). You can also create custom named routers and use them as `orcarouter/<router-name>`.
+
+ **Environment Variables:**
+ ```bash
+ export ORCAROUTER_API_KEY="your_orcarouter_api_key_here"
+ export ORCAROUTER_API_BASE_URL="https://api.orcarouter.ai/v1" # Optional
+ ```
+
+ **Model Support:**
+ - **Smart routing:** `ORCAROUTER_AUTO` targets the default router (see above).
+ - **Predefined enums:** Flagship models — `ORCAROUTER_GPT_5`, `ORCAROUTER_CLAUDE_OPUS_4_7`, `ORCAROUTER_GEMINI_3_FLASH_PREVIEW`, `ORCAROUTER_GROK_4_3` — discoverable in IDE autocomplete.
+ - **String-based access:** Pass any model id from [www.orcarouter.ai/models](https://www.orcarouter.ai/models) directly as a string for maximum flexibility.
+
+ **Example pinning a specific model via predefined enum:**
+ ```python
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type=ModelType.ORCAROUTER_CLAUDE_OPUS_4_7,
+ )
+ ```
+
+ **Example pinning an arbitrary model via free-form string:**
+ ```python
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type="qwen/qwen3.5-flash",
+ )
+ ```
+
+ </Tab>
+
<Tab title="Groq">
Using [Groq](https://groq.com/)'s powerful models (e.g., Llama 3.3-70B):
diff --git a/examples/models/orcarouter_example.py b/examples/models/orcarouter_example.py
new file mode 100644
index 000000000..4a752fa44
--- /dev/null
+++ b/examples/models/orcarouter_example.py
@@ -0,0 +1,119 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed 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.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from camel.agents import ChatAgent
+from camel.configs import OrcaRouterConfig
+from camel.models import ModelFactory
+from camel.types import ModelPlatformType, ModelType
+
+"""
+Set the ORCAROUTER_API_KEY environment variable before running this example:
+
+ export ORCAROUTER_API_KEY="your_orcarouter_api_key_here"
+
+OrcaRouter (https://www.orcarouter.ai) is an OpenAI-compatible LLM gateway
+whose adaptive routing engine picks the upstream model per request. The
+full model catalog is at https://www.orcarouter.ai/models.
+"""
+
+# ---------------------------------------------------------------------------
+# Example 1: ORCAROUTER_AUTO — let OrcaRouter's routing engine pick the
+# upstream automatically. This is the recommended starter: no model-id
+# lookup, the configured strategy (cheapest / balanced / quality / adaptive /
+# gated_adaptive) selects the upstream for each request.
+# ---------------------------------------------------------------------------
+print("=== Example 1: ORCAROUTER_AUTO (smart routing) ===")
+
+auto_model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type=ModelType.ORCAROUTER_AUTO,
+ model_config_dict=OrcaRouterConfig(temperature=0.2).as_dict(),
+)
+
+auto_agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=auto_model,
+)
+print(
+ auto_agent.step(
+ "Say hi to CAMEL AI, one open-source community dedicated to the "
+ "study of autonomous and communicative agents."
+ )
+ .msgs[0]
+ .content
+)
+
+# ---------------------------------------------------------------------------
+# Example 2: Pin a specific flagship model via a predefined enum.
+# Predefined enums show up in IDE autocomplete when you type
+# ``ModelType.ORCAROUTER_``. Some flagship reasoning models (e.g. Claude
+# Opus 4.7) reject ``temperature`` — leave OrcaRouterConfig at its
+# defaults here so this snippet stays portable across pinned models.
+# ---------------------------------------------------------------------------
+print("\n=== Example 2: Pin Claude Opus 4.7 via predefined enum ===")
+
+claude_model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type=ModelType.ORCAROUTER_CLAUDE_OPUS_4_7,
+)
+
+claude_agent = ChatAgent(
+ system_message="You are a creative writing assistant.",
+ model=claude_model,
+)
+print(
+ claude_agent.step(
+ "Write a one-sentence story about an AI agent discovering "
+ "communication."
+ )
+ .msgs[0]
+ .content
+)
+
+# ---------------------------------------------------------------------------
+# Example 3: Pin any model not in the predefined list — pass the id string
+# directly. The full catalog is at https://www.orcarouter.ai/models.
+# ---------------------------------------------------------------------------
+print("\n=== Example 3: Pin an arbitrary model via free-form string ===")
+
+custom_model = ModelFactory.create(
+ model_platform=ModelPlatformType.ORCAROUTER,
+ model_type="qwen/qwen3.5-flash",
+ model_config_dict=OrcaRouterConfig(temperature=0.2).as_dict(),
+)
+
+custom_agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=custom_model,
+)
+print(custom_agent.step("Reply with the single word: pong.").msgs[0].content)
+
+'''
+===============================================================================
+Sample output from a live run against the OrcaRouter API:
+
+=== 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
+===============================================================================
+'''
diff --git a/test/models/test_orcarouter_model.py b/test/models/test_orcarouter_model.py
new file mode 100644
index 000000000..bcca1e73d
--- /dev/null
+++ b/test/models/test_orcarouter_model.py
@@ -0,0 +1,105 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed 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.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+import pytest
+
+from camel.configs import OrcaRouterConfig
+from camel.models import OrcaRouterModel
+from camel.types import ModelPlatformType, ModelType
+from camel.utils import OpenAITokenCounter
+
+
+ "model_type",
+ [
+ ModelType.ORCAROUTER_AUTO,
+ ModelType.ORCAROUTER_GPT_5,
+ ModelType.ORCAROUTER_CLAUDE_OPUS_4_7,
+ ModelType.ORCAROUTER_GEMINI_3_FLASH_PREVIEW,
+ ModelType.ORCAROUTER_GROK_4_3,
+ ],
+)
+def test_orcarouter_predefined_models(model_type: ModelType):
+ model = OrcaRouterModel(model_type, api_key="test-key")
+ assert model.model_type == model_type
+ assert model.model_config_dict == OrcaRouterConfig().as_dict()
+ assert isinstance(model.token_counter, OpenAITokenCounter)
+ # Predefined entries should have a sensible token limit (not fall back
+ # to the 999_999_999 unknown-model warning).
+ assert model.model_type.token_limit < 999_999_999
+ # Predefined entries should report as OrcaRouter-served and as
+ # supporting native tool calling at the ModelType level.
+ assert model.model_type.is_orcarouter is True
+ assert model.model_type.support_native_tool_calling is True
+
+
+ "model_type",
+ [
+ "qwen/qwen3.5-flash",
+ "deepseek/deepseek-chat",
+ "grok/grok-4-0709",
+ "minimax/minimax-m2.7",
+ ],
+)
+def test_orcarouter_freeform_string_models(model_type: str):
+ """Non-predefined model ids should work via free-form string."""
+ model = OrcaRouterModel(model_type, api_key="test-key")
+ assert model.model_type == model_type
+ assert model.model_config_dict == OrcaRouterConfig().as_dict()
+
+
+def test_orcarouter_model_stream_property():
+ model = OrcaRouterModel(ModelType.ORCAROUTER_AUTO, api_key="test-key")
+ assert model.stream is False
+
+
+def test_orcarouter_model_default_url():
+ model = OrcaRouterModel(ModelType.ORCAROUTER_AUTO, api_key="test-key")
+ assert str(model._url) == "https://api.orcarouter.ai/v1"
+
+
+def test_orcarouter_config_extra_body():
+ config = OrcaRouterConfig(
+ extra_body={
+ "models": ["openai/gpt-4o-mini", "openai/gpt-4o"],
+ "route": "fallback",
+ }
+ ).as_dict()
+
+ assert config["extra_body"] == {
+ "models": ["openai/gpt-4o-mini", "openai/gpt-4o"],
+ "route": "fallback",
+ }
+
+
+def test_orcarouter_model_missing_api_key(monkeypatch):
+ monkeypatch.delenv("ORCAROUTER_API_KEY", raising=False)
+ with pytest.raises(ValueError, match="ORCAROUTER_API_KEY"):
+ OrcaRouterModel(ModelType.ORCAROUTER_AUTO, api_key=None)
+
+
+def test_orcarouter_platform_enum():
+ """`from_name` should resolve `'orcarouter'` to the dedicated platform."""
+ assert ModelPlatformType.from_name("orcarouter") is (
+ ModelPlatformType.ORCAROUTER
+ )
+ assert ModelPlatformType.ORCAROUTER.is_orcarouter is True