feat: add OrcaRouter inference provider

Register a named remote::orcarouter inference provider that mirrors the
existing OpenAI-compatible adapters (deepseek, groq, together). The
adapter extends OpenAIMixin and only requires get_base_url(), targeting
the OrcaRouter aggregation gateway at https://api.orcarouter.ai/v1.

- src/ogx/providers/remote/inference/orcarouter/: config + adapter
- src/ogx/providers/registry/inference.py: RemoteProviderSpec entry
- docs/docs/providers/inference/remote_orcarouter.mdx: generated docs
- tests/unit/providers/inference/test_orcarouter_config.py: unit tests

Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: XiaoHuo888 <sjh00112233@outlook.com>

Author: XiaoHuo888-hue

docs/docs/providers/inference/remote_orcarouter.mdx

@@ -0,0 +1,48 @@
+---
+description: "OrcaRouter inference provider for accessing aggregated frontier and open models via the OrcaRouter gateway."
+sidebar_label: Remote - Orcarouter
+title: remote::orcarouter
+---
+
+# remote::orcarouter
+
+## Description
+
+OrcaRouter inference provider for accessing aggregated frontier and open models via the OrcaRouter gateway.
+
+## Configuration
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `allowed_models` | `list[str] \| None` | No |  | List of models that should be registered with the model registry. If None, all models are allowed. |
+| `refresh_models` | `bool` | No | False | Whether to refresh models periodically from the provider |
+| `api_key` | `SecretStr \| None` | No |  | Authentication credential for the provider |
+| `network` | `NetworkConfig \| None` | No |  | Network configuration including TLS, proxy, and timeout settings. |
+| `network.tls` | `TLSConfig \| None` | No |  | TLS/SSL configuration for secure connections. |
+| `network.tls.verify` | `bool \| Path` | No | True | Whether to verify TLS certificates. Can be a boolean or a path to a CA certificate file. |
+| `network.tls.min_version` | `Literal[TLSv1.2, TLSv1.3] \| None` | No |  | Minimum TLS version to use. Defaults to system default if not specified. |
+| `network.tls.ciphers` | `list[str] \| None` | No |  | List of allowed cipher suites (e.g., ['ECDHE+AESGCM', 'DHE+AESGCM']). |
+| `network.tls.client_cert` | `Path \| None` | No |  | Path to client certificate file for mTLS authentication. |
+| `network.tls.client_key` | `Path \| None` | No |  | Path to client private key file for mTLS authentication. |
+| `network.proxy` | `ProxyConfig \| None` | No |  | Proxy configuration for HTTP connections. |
+| `network.proxy.url` | `HttpUrl \| None` | No |  | Single proxy URL for all connections (e.g., 'http://proxy.example.com:8080'). |
+| `network.proxy.http` | `HttpUrl \| None` | No |  | Proxy URL for HTTP connections. |
+| `network.proxy.https` | `HttpUrl \| None` | No |  | Proxy URL for HTTPS connections. |
+| `network.proxy.cacert` | `Path \| None` | No |  | Path to CA certificate file for verifying the proxy's certificate. Required for proxies in interception mode. |
+| `network.proxy.no_proxy` | `list[str] \| None` | No |  | List of hosts that should bypass the proxy (e.g., ['localhost', '127.0.0.1', '.internal.corp']). |
+| `network.timeout` | `float \| TimeoutConfig \| None` | No |  | Timeout configuration. Can be a float (for both connect and read) or a TimeoutConfig object with separate connect and read timeouts. |
+| `network.timeout.connect` | `float \| None` | No |  | Connection timeout in seconds. |
+| `network.timeout.read` | `float \| None` | No |  | Read timeout in seconds. |
+| `network.headers` | `dict[str, str] \| None` | No |  | Additional HTTP headers to include in all requests. |
+| `network.limits` | `LimitsConfig \| None` | No |  | HTTP connection pool limits (max connections, keepalive connections, keepalive expiry). None uses httpx's own defaults. |
+| `network.limits.max_connections` | `int \| None` | No | 100 | Maximum number of concurrent connections in the pool. None means no limit. Values must be >= 1 if set. |
+| `network.limits.max_keepalive_connections` | `int \| None` | No | 20 | Maximum number of idle keep-alive connections to retain. None means no limit. Values must be >= 0 if set. |
+| `network.limits.keepalive_expiry` | `float \| None` | No | 5.0 | Time in seconds to keep idle keep-alive connections open before closing them. None means no expiry. Values must be >= 0 if set. |
+| `base_url` | `HttpUrl \| None` | No | https://api.orcarouter.ai/v1 | Base URL for the OrcaRouter API |
+
+## Sample Configuration
+
+```yaml
+base_url: https://api.orcarouter.ai/v1
+api_key: ${env.ORCAROUTER_API_KEY:=}
+```

src/ogx/providers/registry/inference.py

@@ -237,6 +237,16 @@ def available_providers() -> list[ProviderSpec]:
             provider_data_validator="ogx.providers.remote.inference.groq.config.GroqProviderDataValidator",
             description="Groq inference provider for ultra-fast inference using Groq's LPU technology.",
         ),
+        RemoteProviderSpec(
+            api=Api.inference,
+            adapter_type="orcarouter",
+            provider_type="remote::orcarouter",
+            pip_packages=[],
+            module="ogx.providers.remote.inference.orcarouter",
+            config_class="ogx.providers.remote.inference.orcarouter.OrcaRouterImplConfig",
+            provider_data_validator="ogx.providers.remote.inference.orcarouter.config.OrcaRouterProviderDataValidator",
+            description="OrcaRouter inference provider for accessing aggregated frontier and open models via the OrcaRouter gateway.",
+        ),
         RemoteProviderSpec(
             api=Api.inference,
             adapter_type="llama-openai-compat",

src/ogx/providers/remote/inference/README.md

@@ -19,6 +19,7 @@ inference/
   oci/                 # Oracle Cloud Infrastructure GenAI
   ollama/              # Ollama (local model serving)
   openai/              # OpenAI API
+  orcarouter/          # OrcaRouter (aggregation gateway)
   runpod/              # RunPod cloud GPU
   sambanova/           # SambaNova
   tgi/                 # HuggingFace TGI and Inference API

src/ogx/providers/remote/inference/orcarouter/__init__.py

@@ -0,0 +1,19 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from .config import OrcaRouterImplConfig
+
+
+async def get_adapter_impl(config: OrcaRouterImplConfig, _deps):
+    from .orcarouter import OrcaRouterInferenceAdapter
+
+    assert isinstance(config, OrcaRouterImplConfig), f"Unexpected config type: {type(config)}"
+
+    impl = OrcaRouterInferenceAdapter(config=config)
+
+    await impl.initialize()
+
+    return impl

src/ogx/providers/remote/inference/orcarouter/config.py

@@ -0,0 +1,40 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from typing import Any
+
+from pydantic import BaseModel, Field, HttpUrl, SecretStr
+
+from ogx.providers.utils.inference.model_registry import RemoteInferenceProviderConfig
+from ogx_api import json_schema_type
+
+DEFAULT_BASE_URL = "https://api.orcarouter.ai/v1"
+
+
+class OrcaRouterProviderDataValidator(BaseModel):
+    """Validates provider-specific request data for OrcaRouter inference."""
+
+    orcarouter_api_key: SecretStr | None = Field(
+        default=None,
+        description="API key for OrcaRouter models",
+    )
+
+
+@json_schema_type
+class OrcaRouterImplConfig(RemoteInferenceProviderConfig):
+    """Configuration for the OrcaRouter inference provider."""
+
+    base_url: HttpUrl | None = Field(
+        default=HttpUrl(DEFAULT_BASE_URL),
+        description="Base URL for the OrcaRouter API",
+    )
+
+    @classmethod
+    def sample_run_config(cls, api_key: str = "${env.ORCAROUTER_API_KEY:=}", **kwargs) -> dict[str, Any]:
+        return {
+            "base_url": DEFAULT_BASE_URL,
+            "api_key": api_key,
+        }

src/ogx/providers/remote/inference/orcarouter/orcarouter.py

@@ -0,0 +1,41 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+from collections.abc import AsyncIterator
+
+from ogx.providers.remote.inference.orcarouter.config import OrcaRouterImplConfig
+from ogx.providers.utils.inference.openai_mixin import OpenAIMixin
+from ogx_api import OpenAICompletion, OpenAICompletionRequestWithExtraBody
+
+
+class OrcaRouterInferenceAdapter(OpenAIMixin):
+    """Inference adapter for the OrcaRouter gateway platform.
+
+    OrcaRouter is an OpenAI-compatible aggregation gateway that routes requests
+    to a range of frontier and open models through a single endpoint. The shared
+    `OpenAIMixin` handles chat completions and embeddings once pointed at
+    OrcaRouter's base URL. See https://www.orcarouter.ai.
+    """
+
+    config: OrcaRouterImplConfig
+
+    provider_data_api_key_field: str = "orcarouter_api_key"
+
+    def get_base_url(self) -> str:
+        return str(self.config.base_url)
+
+    async def openai_completion(
+        self,
+        params: OpenAICompletionRequestWithExtraBody,
+    ) -> OpenAICompletion | AsyncIterator[OpenAICompletion]:
+        """OrcaRouter does not support the legacy /v1/completions endpoint.
+
+        OrcaRouter is a chat-first aggregation gateway, so the legacy
+        OpenAI completions endpoint is not part of its API surface.
+        """
+        raise NotImplementedError(
+            "OrcaRouter does not support /v1/completions endpoint. Only /v1/chat/completions is supported."
+        )

tests/unit/providers/inference/test_orcarouter_config.py

@@ -0,0 +1,58 @@
+# Copyright (c) The OGX Contributors.
+# All rights reserved.
+#
+# This source code is licensed under the terms described in the LICENSE file in
+# the root directory of this source tree.
+
+import pytest
+
+from ogx.core.stack import replace_env_vars
+from ogx.providers.remote.inference.orcarouter.config import OrcaRouterImplConfig
+from ogx.providers.remote.inference.orcarouter.orcarouter import OrcaRouterInferenceAdapter
+from ogx_api import OpenAICompletionRequestWithExtraBody
+
+
+class TestOrcaRouterConfig:
+    """Tests for the OrcaRouter inference provider config and adapter wiring."""
+
+    def test_default_base_url(self):
+        config = OrcaRouterImplConfig(api_key="test-key")
+        adapter = OrcaRouterInferenceAdapter(config=config)
+        adapter.provider_data_api_key_field = None
+
+        assert adapter.get_base_url() == "https://api.orcarouter.ai/v1"
+
+    def test_custom_base_url_from_config(self):
+        custom_url = "https://custom.orcarouter.ai/v1"
+        config = OrcaRouterImplConfig(api_key="test-key", base_url=custom_url)
+        adapter = OrcaRouterInferenceAdapter(config=config)
+        adapter.provider_data_api_key_field = None
+
+        assert adapter.get_base_url() == custom_url
+
+    def test_sample_run_config_uses_env_placeholder(self):
+        cfg = OrcaRouterImplConfig.sample_run_config()
+        assert cfg["base_url"] == "https://api.orcarouter.ai/v1"
+        assert cfg["api_key"] == "${env.ORCAROUTER_API_KEY:=}"
+
+    def test_sample_run_config_env_expansion(self):
+        config_data = OrcaRouterImplConfig.sample_run_config(api_key="test-key")
+        processed_config = replace_env_vars(config_data)
+        config = OrcaRouterImplConfig.model_validate(processed_config)
+
+        assert str(config.base_url) == "https://api.orcarouter.ai/v1"
+
+    def test_provider_data_api_key_field(self):
+        config = OrcaRouterImplConfig(api_key="test-key")
+        adapter = OrcaRouterInferenceAdapter(config=config)
+        assert adapter.provider_data_api_key_field == "orcarouter_api_key"
+
+    async def test_legacy_completions_endpoint_not_supported(self):
+        """OrcaRouter does not support the legacy /v1/completions endpoint."""
+        config = OrcaRouterImplConfig(api_key="test-key")
+        adapter = OrcaRouterInferenceAdapter(config=config)
+
+        params = OpenAICompletionRequestWithExtraBody(model="anthropic/claude-sonnet-4.6", prompt="Hello")
+
+        with pytest.raises(NotImplementedError, match="does not support /v1/completions endpoint"):
+            await adapter.openai_completion(params)