🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org
Python agentai-societiesartificial-intelligencecommunicative-aicooperative-aideep-learninglarge-language-modelsmulti-agent-systemsnatural-language-processing
feat: add OrcaRouter as a dedicated model platform (#4048)
zhenjunchen-png0a41603d4a3f
diff --git a/camel/configs/__init__.py b/camel/configs/__init__.pyindex e28814c5e..1b8719910 100644--- a/camel/configs/__init__.py+++ b/camel/configs/__init__.py@@ -44,6 +44,7 @@ from .nvidia_config import NVIDIA_API_PARAMS, NvidiaConfigfrom .ollama_config import OLLAMA_API_PARAMS, OllamaConfigfrom .openai_config import OPENAI_API_PARAMS, ChatGPTConfigfrom .openrouter_config import OPENROUTER_API_PARAMS, OpenRouterConfig+from .orcarouter_config import ORCAROUTER_API_PARAMS, OrcaRouterConfigfrom .ppio_config import PPIO_API_PARAMS, PPIOConfigfrom .qianfan_config import QIANFAN_API_PARAMS, QianfanConfigfrom .qwen_config import QWEN_API_PARAMS, QwenConfig@@ -65,93 +66,95 @@ from .yi_config import YI_API_PARAMS, YiConfigfrom .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.pynew file mode 100644index 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__.pyindex f6c6a0ff3..5be1852ac 100644--- a/camel/models/__init__.py+++ b/camel/models/__init__.py@@ -50,6 +50,7 @@ from .openai_audio_models import OpenAIAudioModelsfrom .openai_compatible_model import OpenAICompatibleModelfrom .openai_model import OpenAIModelfrom .openrouter_model import OpenRouterModel+from .orcarouter_model import OrcaRouterModelfrom .ppio_model import PPIOModelfrom .qianfan_model import QianfanModelfrom .qwen_model import QwenModel@@ -67,59 +68,60 @@ from .yi_model import YiModelfrom .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.pyindex 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 OllamaModelfrom camel.models.openai_compatible_model import OpenAICompatibleModelfrom camel.models.openai_model import OpenAIModelfrom camel.models.openrouter_model import OpenRouterModel+from camel.models.orcarouter_model import OrcaRouterModelfrom camel.models.ppio_model import PPIOModelfrom camel.models.qianfan_model import QianfanModelfrom 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.pynew file mode 100644index 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.pyindex 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 modelsLMSTUDIO_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,+ }+@propertydef 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_000elif 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_000elif 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_576elif 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_000elif 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+@propertydef 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.pyindex 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+@propertydef 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.pyindex 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.mdindex 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.jsonindex 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.mdxindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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++[email protected]_backend+ "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++[email protected]_backend+ "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()++[email protected]_backend+def test_orcarouter_model_stream_property():+ model = OrcaRouterModel(ModelType.ORCAROUTER_AUTO, api_key="test-key")+ assert model.stream is False++[email protected]_backend+def test_orcarouter_model_default_url():+ model = OrcaRouterModel(ModelType.ORCAROUTER_AUTO, api_key="test-key")+ assert str(model._url) == "https://api.orcarouter.ai/v1"++[email protected]_backend+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",+ }++[email protected]_backend+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)++[email protected]_backend+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