Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Add Cereberas Provider

Alishahryar1ab842fd92085
diff --git a/.env.example b/.env.example
index b18def1c..a28bde22 100644
--- a/.env.example
+++ b/.env.example
@@ -42,6 +42,10 @@ GEMINI_API_KEY=""
GROQ_API_KEY=""
+# Cerebras Inference (OpenAI-compatible Chat Completions; see https://inference-docs.cerebras.ai/resources/openai)
+CEREBRAS_API_KEY=""
+
+
# LM Studio Config (local provider, no API key required)
LM_STUDIO_BASE_URL="http://localhost:1234/v1"
@@ -56,7 +60,7 @@ OLLAMA_BASE_URL="http://localhost:11434"
# All Claude model requests are mapped to these models, plain model is fallback
# Format: provider_type/model/name
-# Valid providers: "nvidia_nim" | "open_router" | "mistral" | "deepseek" | "kimi" | "wafer" | "lmstudio" | "llamacpp" | "ollama" | "opencode" | "opencode_go" | "zai" | "fireworks" | "gemini" | "groq"
+# Valid providers: "nvidia_nim" | "open_router" | "mistral" | "deepseek" | "kimi" | "wafer" | "lmstudio" | "llamacpp" | "ollama" | "opencode" | "opencode_go" | "zai" | "fireworks" | "gemini" | "groq" | "cerebras"
MODEL_OPUS=
MODEL_SONNET=
MODEL_HAIKU=
@@ -80,6 +84,7 @@ FCC_SMOKE_MODEL_ZAI=
FCC_SMOKE_MODEL_FIREWORKS=
FCC_SMOKE_MODEL_GEMINI=
FCC_SMOKE_MODEL_GROQ=
+FCC_SMOKE_MODEL_CEREBRAS=
FCC_SMOKE_NIM_MODELS=
FCC_SMOKE_NIM_EXTRA_MODELS=
FCC_SMOKE_OPENROUTER_FREE_MODELS=
@@ -110,6 +115,7 @@ ZAI_PROXY=""
FIREWORKS_PROXY=""
GEMINI_PROXY=""
GROQ_PROXY=""
+CEREBRAS_PROXY=""
PROVIDER_RATE_LIMIT=1
PROVIDER_RATE_WINDOW=3
diff --git a/README.md b/README.md
index f25fafcf..872742c8 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ Free Claude Code routes Anthropic Messages API traffic from Claude Code to any p
## What You Get
- Drop-in proxy for Claude Code's Anthropic API calls.
-- Fifteen provider backends: NVIDIA NIM, OpenRouter, Mistral La Plateforme, DeepSeek, Kimi, Wafer, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, Z.ai, Fireworks AI, Google AI Studio (Gemini), and Groq.
+- Sixteen provider backends: NVIDIA NIM, OpenRouter, Mistral La Plateforme, DeepSeek, Kimi, Wafer, LM Studio, llama.cpp, Ollama, OpenCode Zen, OpenCode Go, Z.ai, Fireworks AI, Google AI Studio (Gemini), Groq, and Cerebras Inference.
- Per-model routing: send Opus, Sonnet, Haiku, and fallback traffic to different providers.
- Native Claude Code `/model` picker support through the proxy's `/v1/models` endpoint (Claude Code must opt in to Gateway model discovery; see [Model Picker](#model-picker)).
- Streaming, tool use, reasoning/thinking block handling, and local request optimizations.
@@ -283,7 +283,15 @@ Reasoning-heavy models expose extra knobs documented under [Groq reasoning](http
Browse models at [console.groq.com/docs/models](https://console.groq.com/docs/models).
-### 16. Mix Providers By Model Tier
+### 16. [Cerebras Inference](https://inference-docs.cerebras.ai/quickstart)
+
+Sign up and create an API key in the [Cerebras Cloud Console](https://cloud.cerebras.ai) (see [Quickstart](https://inference-docs.cerebras.ai/quickstart)).
+
+In the Admin UI, set `CEREBRAS_API_KEY`, then route with `MODEL` such as `cerebras/llama3.1-8b` or `cerebras/gpt-oss-120b` (ids from [List models](https://inference-docs.cerebras.ai/api-reference/models/list-models)).
+
+Cerebras exposes an OpenAI-compatible API at `https://api.cerebras.ai/v1` ([OpenAI compatibility](https://inference-docs.cerebras.ai/resources/openai)). Non-standard request fields should go in `extra_body` when using the OpenAI client; see the same page. For reasoning models and parameters, see [Reasoning](https://inference-docs.cerebras.ai/capabilities/reasoning). This proxy follows other OpenAI-compat adapters for thinking via `reasoning_content` when Claude-style thinking is enabled.
+
+### 17. Mix Providers By Model Tier
Each model tier can use a different provider by setting `MODEL_OPUS`, `MODEL_SONNET`, and `MODEL_HAIKU` in the Admin UI. Leave a tier blank to inherit `MODEL`.
diff --git a/api/admin_config.py b/api/admin_config.py
index 7049db29..9a7b5ae6 100644
--- a/api/admin_config.py
+++ b/api/admin_config.py
@@ -226,6 +226,19 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
"[OpenAI compatibility docs](https://console.groq.com/docs/openai)."
),
),
+ ConfigFieldSpec(
+ "CEREBRAS_API_KEY",
+ "Cerebras API Key",
+ "providers",
+ "secret",
+ settings_attr="cerebras_api_key",
+ secret=True,
+ description=(
+ "Cerebras Inference API key (create in [Cloud Console](https://cloud.cerebras.ai)); "
+ "see [Quickstart](https://inference-docs.cerebras.ai/quickstart) and "
+ "[OpenAI compatibility](https://inference-docs.cerebras.ai/resources/openai)."
+ ),
+ ),
ConfigFieldSpec(
"LM_STUDIO_BASE_URL",
"LM Studio Base URL",
@@ -364,6 +377,15 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
secret=True,
advanced=True,
),
+ ConfigFieldSpec(
+ "CEREBRAS_PROXY",
+ "Cerebras Proxy",
+ "providers",
+ "secret",
+ settings_attr="cerebras_proxy",
+ secret=True,
+ advanced=True,
+ ),
ConfigFieldSpec(
"MODEL",
"Default Model",
@@ -842,6 +864,12 @@ FIELDS: tuple[ConfigFieldSpec, ...] = (
"smoke",
advanced=True,
),
+ ConfigFieldSpec(
+ "FCC_SMOKE_MODEL_CEREBRAS",
+ "Smoke Cerebras Model",
+ "smoke",
+ advanced=True,
+ ),
ConfigFieldSpec(
"FCC_SMOKE_NIM_MODELS",
"Smoke NIM Models",
diff --git a/config/provider_catalog.py b/config/provider_catalog.py
index 6e45b610..f26b806f 100644
--- a/config/provider_catalog.py
+++ b/config/provider_catalog.py
@@ -31,6 +31,7 @@ ZAI_DEFAULT_BASE = "https://api.z.ai/api/coding/paas/v4"
# Google AI Studio Gemini API OpenAI-compat layer (not Vertex AI).
GEMINI_DEFAULT_BASE = "https://generativelanguage.googleapis.com/v1beta/openai/"
GROQ_DEFAULT_BASE = "https://api.groq.com/openai/v1"
+CEREBRAS_DEFAULT_BASE = "https://api.cerebras.ai/v1"
@dataclass(frozen=True, slots=True)
@@ -201,6 +202,16 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
proxy_attr="groq_proxy",
capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
),
+ "cerebras": ProviderDescriptor(
+ provider_id="cerebras",
+ transport_type="openai_chat",
+ credential_env="CEREBRAS_API_KEY",
+ credential_url="https://cloud.cerebras.ai",
+ credential_attr="cerebras_api_key",
+ default_base_url=CEREBRAS_DEFAULT_BASE,
+ proxy_attr="cerebras_proxy",
+ capabilities=("chat", "streaming", "tools", "thinking", "rate_limit"),
+ ),
}
# Order matches docs / historical error text; must match PROVIDER_CATALOG keys.
diff --git a/config/settings.py b/config/settings.py
index 1873c6ea..415f0eb7 100644
--- a/config/settings.py
+++ b/config/settings.py
@@ -138,6 +138,9 @@ class Settings(BaseSettings):
# ==================== Groq (OpenAI-compatible) ====================
groq_api_key: str = Field(default="", validation_alias="GROQ_API_KEY")
+ # ==================== Cerebras Inference (OpenAI-compatible) ====================
+ cerebras_api_key: str = Field(default="", validation_alias="CEREBRAS_API_KEY")
+
# ==================== Messaging Platform Selection ====================
# Valid: "telegram" | "discord" | "none"
messaging_platform: str = Field(
@@ -196,6 +199,7 @@ class Settings(BaseSettings):
fireworks_proxy: str = Field(default="", validation_alias="FIREWORKS_PROXY")
gemini_proxy: str = Field(default="", validation_alias="GEMINI_PROXY")
groq_proxy: str = Field(default="", validation_alias="GROQ_PROXY")
+ cerebras_proxy: str = Field(default="", validation_alias="CEREBRAS_PROXY")
# ==================== Provider Rate Limiting ====================
provider_rate_limit: int = Field(default=40, validation_alias="PROVIDER_RATE_LIMIT")
diff --git a/providers/cerebras/__init__.py b/providers/cerebras/__init__.py
new file mode 100644
index 00000000..4efd14db
--- /dev/null
+++ b/providers/cerebras/__init__.py
@@ -0,0 +1,7 @@
+"""Cerebras Inference (OpenAI-compatible) adapter."""
+
+from providers.defaults import CEREBRAS_DEFAULT_BASE
+
+from .client import CerebrasProvider
+
+__all__ = ["CEREBRAS_DEFAULT_BASE", "CerebrasProvider"]
diff --git a/providers/cerebras/client.py b/providers/cerebras/client.py
new file mode 100644
index 00000000..6cc3758f
--- /dev/null
+++ b/providers/cerebras/client.py
@@ -0,0 +1,31 @@
+"""Cerebras Inference provider (OpenAI-compatible chat completions)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.defaults import CEREBRAS_DEFAULT_BASE
+from providers.openai_compat import OpenAIChatTransport
+
+from .request import build_request_body
+
+
+class CerebrasProvider(OpenAIChatTransport):
+ """Cerebras API at ``https://api.cerebras.ai/v1/chat/completions``."""
+
+ def __init__(self, config: ProviderConfig):
+ super().__init__(
+ config,
+ provider_name="CEREBRAS",
+ base_url=config.base_url or CEREBRAS_DEFAULT_BASE,
+ api_key=config.api_key,
+ )
+
+ def _build_request_body(
+ self, request: Any, thinking_enabled: bool | None = None
+ ) -> dict:
+ return build_request_body(
+ request,
+ thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+ )
diff --git a/providers/cerebras/request.py b/providers/cerebras/request.py
new file mode 100644
index 00000000..bd2c8976
--- /dev/null
+++ b/providers/cerebras/request.py
@@ -0,0 +1,55 @@
+"""Request builder for Cerebras Inference (OpenAI-compatible chat completions).
+
+Docs: https://inference-docs.cerebras.ai/resources/openai — use ``max_completion_tokens``
+in API examples; non-standard fields via ``extra_body`` with the OpenAI client.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+from core.anthropic import ReasoningReplayMode, build_base_request_body
+from core.anthropic.conversion import OpenAIConversionError
+from providers.exceptions import InvalidRequestError
+
+
+def _normalize_max_completion_tokens(body: dict[str, Any]) -> None:
+ if "max_completion_tokens" in body:
+ body.pop("max_tokens", None)
+ return
+ if "max_tokens" in body and body["max_tokens"] is not None:
+ body["max_completion_tokens"] = body.pop("max_tokens")
+
+
+def build_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
+ """Build OpenAI-format request body from an Anthropic request for Cerebras."""
+ logger.debug(
+ "CEREBRAS_REQUEST: conversion start model={} msgs={}",
+ getattr(request_data, "model", "?"),
+ len(getattr(request_data, "messages", [])),
+ )
+ try:
+ body = build_base_request_body(
+ request_data,
+ reasoning_replay=ReasoningReplayMode.REASONING_CONTENT
+ if thinking_enabled
+ else ReasoningReplayMode.DISABLED,
+ )
+ except OpenAIConversionError as exc:
+ raise InvalidRequestError(str(exc)) from exc
+
+ request_extra = getattr(request_data, "extra_body", None)
+ if isinstance(request_extra, dict) and request_extra:
+ body["extra_body"] = dict(request_extra)
+
+ _normalize_max_completion_tokens(body)
+
+ logger.debug(
+ "CEREBRAS_REQUEST: conversion done model={} msgs={} tools={}",
+ body.get("model"),
+ len(body.get("messages", [])),
+ len(body.get("tools", [])),
+ )
+ return body
diff --git a/providers/defaults.py b/providers/defaults.py
index 3842db55..c53b0e2a 100644
--- a/providers/defaults.py
+++ b/providers/defaults.py
@@ -1,6 +1,7 @@
"""Re-exports default upstream base URLs from the config provider catalog."""
from config.provider_catalog import (
+ CEREBRAS_DEFAULT_BASE,
DEEPSEEK_ANTHROPIC_DEFAULT_BASE,
DEEPSEEK_DEFAULT_BASE,
GEMINI_DEFAULT_BASE,
@@ -19,6 +20,7 @@ from config.provider_catalog import (
)
__all__ = (
+ "CEREBRAS_DEFAULT_BASE",
"DEEPSEEK_ANTHROPIC_DEFAULT_BASE",
"DEEPSEEK_DEFAULT_BASE",
"GEMINI_DEFAULT_BASE",
diff --git a/providers/registry.py b/providers/registry.py
index f9cc9874..a8f88546 100644
--- a/providers/registry.py
+++ b/providers/registry.py
@@ -122,6 +122,12 @@ def _create_groq(config: ProviderConfig, _settings: Settings) -> BaseProvider:
return GroqProvider(config)
+def _create_cerebras(config: ProviderConfig, _settings: Settings) -> BaseProvider:
+ from providers.cerebras import CerebrasProvider
+
+ return CerebrasProvider(config)
+
+
PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"nvidia_nim": _create_nvidia_nim,
"open_router": _create_open_router,
@@ -138,6 +144,7 @@ PROVIDER_FACTORIES: dict[str, ProviderFactory] = {
"fireworks": _create_fireworks,
"gemini": _create_gemini,
"groq": _create_groq,
+ "cerebras": _create_cerebras,
}
if set(PROVIDER_DESCRIPTORS) != set(SUPPORTED_PROVIDER_IDS) or set(
diff --git a/smoke/README.md b/smoke/README.md
index 28b531e5..121430a8 100644
--- a/smoke/README.md
+++ b/smoke/README.md
@@ -120,8 +120,8 @@ uv run pytest smoke/product -n 0 -s --tb=short
- `FCC_SMOKE_MODEL_NVIDIA_NIM`, `FCC_SMOKE_MODEL_OPEN_ROUTER`,
`FCC_SMOKE_MODEL_MISTRAL`, `FCC_SMOKE_MODEL_DEEPSEEK`, `FCC_SMOKE_MODEL_KIMI`,
`FCC_SMOKE_MODEL_WAFER`, `FCC_SMOKE_MODEL_OPENCODE`, `FCC_SMOKE_MODEL_OPENCODE_GO`,
- `FCC_SMOKE_MODEL_ZAI`, `FCC_SMOKE_MODEL_FIREWORKS`, `FCC_SMOKE_MODEL_GEMINI`,
- `FCC_SMOKE_MODEL_GROQ`,
+ `FCC_SMOKE_MODEL_ZAI`, `FCC_SMOKE_MODEL_FIREWORKS`, `FCC_SMOKE_MODEL_GEMINI`,
+ `FCC_SMOKE_MODEL_GROQ`, `FCC_SMOKE_MODEL_CEREBRAS`,
`FCC_SMOKE_MODEL_LMSTUDIO`,
`FCC_SMOKE_MODEL_LLAMACPP`, `FCC_SMOKE_MODEL_OLLAMA`: optional per-provider
smoke model overrides. Values may include the provider prefix or just the model
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 4fa56ca9..71c98af2 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -55,6 +55,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"zai": "zai/glm-5.1",
"gemini": "gemini/gemini-2.5-flash",
"groq": "groq/llama-3.3-70b-versatile",
+ "cerebras": "cerebras/llama3.1-8b",
}
NVIDIA_NIM_CLI_DEFAULT_MODELS: tuple[str, ...] = (
@@ -253,6 +254,8 @@ class SmokeConfig:
return bool(self.settings.gemini_api_key.strip())
if provider == "groq":
return bool(self.settings.groq_api_key.strip())
+ if provider == "cerebras":
+ return bool(self.settings.cerebras_api_key.strip())
return False
diff --git a/tests/api/test_admin.py b/tests/api/test_admin.py
index 896a4292..67d5017e 100644
--- a/tests/api/test_admin.py
+++ b/tests/api/test_admin.py
@@ -105,6 +105,7 @@ def test_admin_config_masks_secrets_and_exposes_manifest(monkeypatch, tmp_path):
assert "FIREWORKS_API_KEY" in keys
assert "GEMINI_API_KEY" in keys
assert "GROQ_API_KEY" in keys
+ assert "CEREBRAS_API_KEY" in keys
assert "ZAI_BASE_URL" not in keys
assert "CLAUDE_WORKSPACE" not in keys
assert "CLAUDE_CLI_BIN" not in keys
@@ -259,6 +260,31 @@ def test_admin_apply_writes_groq_key_and_masks_preview(monkeypatch, tmp_path):
assert "GROQ_API_KEY=gq-secret" in text
+def test_admin_apply_writes_cerebras_key_and_masks_preview(monkeypatch, tmp_path):
+ _set_home(monkeypatch, tmp_path)
+ _clear_process_config(monkeypatch)
+ app = create_app(lifespan_enabled=False)
+
+ response = _local_client(app).post(
+ "/admin/api/config/apply",
+ json={
+ "values": {
+ "MODEL": "cerebras/llama3.1-8b",
+ "CEREBRAS_API_KEY": "cb-secret",
+ }
+ },
+ )
+
+ assert response.status_code == 200
+ body = response.json()
+ assert body["applied"] is True
+ assert "CEREBRAS_API_KEY=********" in body["env_preview"]
+ env_file = tmp_path / ".fcc" / ".env"
+ text = env_file.read_text(encoding="utf-8")
+ assert "MODEL=cerebras/llama3.1-8b" in text
+ assert "CEREBRAS_API_KEY=cb-secret" in text
+
+
def test_admin_apply_preserves_hidden_diagnostics_and_smoke_values(
monkeypatch, tmp_path
):
diff --git a/tests/api/test_dependencies.py b/tests/api/test_dependencies.py
index 71dde718..00269cdb 100644
--- a/tests/api/test_dependencies.py
+++ b/tests/api/test_dependencies.py
@@ -15,6 +15,7 @@ from api.dependencies import (
resolve_provider,
)
from config.nim import NimSettings
+from providers.cerebras import CerebrasProvider
from providers.deepseek import DeepSeekProvider
from providers.exceptions import ServiceUnavailableError, UnknownProviderTypeError
from providers.gemini import GeminiProvider
@@ -62,6 +63,8 @@ def _make_mock_settings(**overrides):
mock.gemini_proxy = ""
mock.groq_api_key = ""
mock.groq_proxy = ""
+ mock.cerebras_api_key = ""
+ mock.cerebras_proxy = ""
mock.nim = NimSettings()
mock.http_read_timeout = 300.0
mock.http_write_timeout = 10.0
@@ -294,6 +297,39 @@ async def test_get_provider_groq_missing_api_key():
assert "console.groq.com" in exc_info.value.detail
+async def test_get_provider_cerebras():
+ """Test that provider_type=cerebras returns CerebrasProvider."""
+ with patch("api.dependencies.get_settings") as mock_settings:
+ mock_settings.return_value = _make_mock_settings(
+ provider_type="cerebras",
+ cerebras_api_key="secret",
+ )
+
+ provider = get_provider()
+
+ assert isinstance(provider, CerebrasProvider)
+ assert provider._base_url == "https://api.cerebras.ai/v1"
+ assert provider._api_key == "secret"
+
+
+async def test_get_provider_cerebras_missing_api_key():
+ """Cerebras with empty API key raises HTTPException 503."""
+ with patch("api.dependencies.get_settings") as mock_settings:
+ mock_settings.return_value = _make_mock_settings(
+ provider_type="cerebras",
+ cerebras_api_key="",
+ )
+
+ with pytest.raises(HTTPException) as exc_info:
+ get_provider()
+
+ assert exc_info.value.status_code == 503
+ assert "CEREBRAS_API_KEY" in exc_info.value.detail
+ assert "cloud.cerebras.ai" in exc_info.value.detail
+
+
@pytest.mark.asyncio
async def test_get_provider_wafer():
"""Test that provider_type=wafer returns WaferProvider."""
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index ce5237a9..dcc45a26 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -768,6 +768,7 @@ class TestPerModelMapping:
assert Settings.parse_provider_type("wafer/DeepSeek-V4-Pro") == "wafer"
assert Settings.parse_provider_type("gemini/gemini-2.5-flash") == "gemini"
assert Settings.parse_provider_type("groq/llama-3.3-70b-versatile") == "groq"
+ assert Settings.parse_provider_type("cerebras/llama3.1-8b") == "cerebras"
def test_parse_model_name(self):
"""parse_model_name extracts model name from model string."""
@@ -790,6 +791,7 @@ class TestPerModelMapping:
Settings.parse_model_name("groq/llama-3.3-70b-versatile")
== "llama-3.3-70b-versatile"
)
+ assert Settings.parse_model_name("cerebras/llama3.1-8b") == "llama3.1-8b"
def test_configured_chat_model_refs_collects_unique_models_with_sources(
self, monkeypatch
diff --git a/tests/contracts/test_feature_manifest.py b/tests/contracts/test_feature_manifest.py
index c5a3f57c..29a17a2b 100644
--- a/tests/contracts/test_feature_manifest.py
+++ b/tests/contracts/test_feature_manifest.py
@@ -5,6 +5,7 @@ from pathlib import Path
from messaging.platforms.factory import create_messaging_platform
from providers.base import BaseProvider
+from providers.cerebras import CerebrasProvider
from providers.deepseek import DeepSeekProvider
from providers.gemini import GeminiProvider
from providers.groq import GroqProvider
@@ -86,6 +87,7 @@ def test_provider_and_platform_registries_include_advertised_builtins() -> None:
"zai": ZaiProvider,
"gemini": GeminiProvider,
"groq": GroqProvider,
+ "cerebras": CerebrasProvider,
}
for provider_class in provider_classes.values():
assert issubclass(provider_class, BaseProvider)
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 218db5fc..2485f1ab 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -33,6 +33,7 @@ def _settings(**overrides):
"zai_api_key": "",
"gemini_api_key": "",
"groq_api_key": "",
+ "cerebras_api_key": "",
"fireworks_api_key": "",
"lm_studio_base_url": "",
"llamacpp_base_url": "",
diff --git a/tests/providers/test_cerebras.py b/tests/providers/test_cerebras.py
new file mode 100644
index 00000000..24bdcd5f
--- /dev/null
+++ b/tests/providers/test_cerebras.py
@@ -0,0 +1,221 @@
+"""Tests for Cerebras Inference (OpenAI-compatible) provider."""
+
+from contextlib import asynccontextmanager
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from providers.base import ProviderConfig
+from providers.cerebras import CEREBRAS_DEFAULT_BASE, CerebrasProvider
+
+
+class MockMessage:
+ def __init__(self, role, content):
+ self.role = role
+ self.content = content
+
+
+class MockRequest:
+ def __init__(self, **kwargs):
+ self.model = "llama3.1-8b"
+ self.messages = [MockMessage("user", "Hello")]
+ self.max_tokens = 100
+ self.temperature = 0.5
+ self.top_p = 0.9
+ self.system = "System prompt"
+ self.stop_sequences = None
+ self.tools = []
+ self.thinking = MagicMock()
+ self.thinking.enabled = True
+ for key, value in kwargs.items():
+ setattr(self, key, value)
+
+
+def cerebras_config():
+ return ProviderConfig(
+ api_key="test_cerebras_key",
+ base_url=CEREBRAS_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ enable_thinking=True,
+ )
+
+
[email protected](autouse=True)
+def mock_rate_limiter():
+ """Mock the global rate limiter to prevent waiting."""
+
+ @asynccontextmanager
+ async def _slot():
+ yield
+
+ with patch("providers.openai_compat.GlobalRateLimiter") as mock:
+ instance = mock.get_scoped_instance.return_value
+
+ async def _passthrough(fn, *args, **kwargs):
+ return await fn(*args, **kwargs)
+
+ instance.execute_with_retry = AsyncMock(side_effect=_passthrough)
+ instance.concurrency_slot.side_effect = _slot
+ yield instance
+
+
+def cerebras_provider(cerebras_config):
+ return CerebrasProvider(cerebras_config)
+
+
+def test_init(cerebras_config):
+ """Test provider initialization."""
+ with patch("providers.openai_compat.AsyncOpenAI") as mock_openai:
+ provider = CerebrasProvider(cerebras_config)
+ assert provider._api_key == "test_cerebras_key"
+ assert provider._base_url == CEREBRAS_DEFAULT_BASE
+ mock_openai.assert_called_once()
+
+
+def test_default_base_url_constant():
+ assert CEREBRAS_DEFAULT_BASE == "https://api.cerebras.ai/v1"
+
+
+def test_build_request_body_basic(cerebras_provider):
+ """Basic request body conversion attaches system message from Claude request."""
+ req = MockRequest()
+ body = cerebras_provider._build_request_body(req)
+
+ assert body["model"] == "llama3.1-8b"
+ assert body["messages"][0]["role"] == "system"
+ assert "max_completion_tokens" in body
+
+
+def test_build_request_body_global_disable_blocks_reasoning_mapping():
+ provider = CerebrasProvider(
+ ProviderConfig(
+ api_key="test_cerebras_key",
+ base_url=CEREBRAS_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ enable_thinking=False,
+ )
+ )
+ req = MockRequest()
+ body = provider._build_request_body(req)
+
+ roles = [m.get("role") for m in body.get("messages", [])]
+ assert "assistant_reasoning_content" not in roles
+
+
+def test_build_request_body_remaps_max_tokens_preserves_message_name(cerebras_provider):
+ """Cerebras does not strip message ``name``; ``max_tokens`` maps to completion field."""
+ with patch("providers.cerebras.request.build_base_request_body") as mock_convert:
+ mock_convert.return_value = {
+ "model": "llama3.1-8b",
+ "messages": [{"role": "user", "name": "alice", "content": "hi"}],
+ "max_tokens": 42,
+ }
+ req = MockRequest()
+ body = cerebras_provider._build_request_body(req)
+
+ assert body["messages"][0].get("name") == "alice"
+ assert body.get("max_tokens") is None
+ assert body["max_completion_tokens"] == 42
+
+
+def test_build_request_body_prefers_existing_max_completion_tokens(cerebras_provider):
+ with patch("providers.cerebras.request.build_base_request_body") as mock_convert:
+ mock_convert.return_value = {
+ "model": "llama3.1-8b",
+ "messages": [{"role": "user", "content": "x"}],
+ "max_completion_tokens": 77,
+ "max_tokens": 999,
+ }
+ body = cerebras_provider._build_request_body(MockRequest())
+
+ assert body["max_completion_tokens"] == 77
+ assert "max_tokens" not in body
+
+
+def test_build_request_body_preserves_caller_extra_body(cerebras_provider):
+ req = MockRequest(extra_body={"clear_thinking": False})
+
+ body = cerebras_provider._build_request_body(req)
+
+ eb = body.get("extra_body")
+ assert isinstance(eb, dict)
+ assert eb.get("clear_thinking") is False
+
+
+async def test_stream_response_text(cerebras_provider):
+ """Text content deltas are emitted as text blocks."""
+ req = MockRequest()
+
+ mock_chunk = MagicMock()
+ mock_chunk.choices = [
+ MagicMock(
+ delta=MagicMock(
+ content="Hello back!",
+ reasoning_content=None,
+ tool_calls=None,
+ ),
+ finish_reason="stop",
+ )
+ ]
+ mock_chunk.usage = MagicMock(completion_tokens=5, prompt_tokens=10)
+
+ async def mock_stream():
+ yield mock_chunk
+
+ with patch.object(
+ cerebras_provider._client.chat.completions, "create", new_callable=AsyncMock
+ ) as mock_create:
+ mock_create.return_value = mock_stream()
+
+ events = [event async for event in cerebras_provider.stream_response(req)]
+
+ assert any(
+ '"text_delta"' in event and "Hello back!" in event for event in events
+ )
+
+
+async def test_stream_response_reasoning_content(cerebras_provider):
+ """reasoning_content deltas are emitted as thinking blocks."""
+ req = MockRequest()
+
+ mock_chunk = MagicMock()
+ mock_chunk.choices = [
+ MagicMock(
+ delta=MagicMock(
+ content=None,
+ reasoning_content="Thinking...",
+ tool_calls=None,
+ ),
+ finish_reason="stop",
+ )
+ ]
+ mock_chunk.usage = MagicMock(completion_tokens=2, prompt_tokens=10)
+
+ async def mock_stream():
+ yield mock_chunk
+
+ with patch.object(
+ cerebras_provider._client.chat.completions, "create", new_callable=AsyncMock
+ ) as mock_create:
+ mock_create.return_value = mock_stream()
+
+ events = [event async for event in cerebras_provider.stream_response(req)]
+
+ assert any(
+ '"thinking_delta"' in event and "Thinking..." in event for event in events
+ )
+
+
+async def test_cleanup(cerebras_provider):
+ cerebras_provider._client = AsyncMock()
+
+ await cerebras_provider.cleanup()
+
+ cerebras_provider._client.close.assert_called_once()
diff --git a/tests/providers/test_registry.py b/tests/providers/test_registry.py
index 6e3aeba6..2620a560 100644
--- a/tests/providers/test_registry.py
+++ b/tests/providers/test_registry.py
@@ -7,6 +7,7 @@ import pytest
from config.nim import NimSettings
from config.provider_catalog import PROVIDER_CATALOG, ZAI_DEFAULT_BASE
from config.provider_ids import SUPPORTED_PROVIDER_IDS
+from providers.cerebras import CerebrasProvider
from providers.deepseek import DeepSeekProvider
from providers.exceptions import UnknownProviderTypeError
from providers.gemini import GeminiProvider
@@ -58,6 +59,8 @@ def _make_settings(**overrides):
mock.gemini_proxy = ""
mock.groq_api_key = ""
mock.groq_proxy = ""
+ mock.cerebras_api_key = ""
+ mock.cerebras_proxy = ""
mock.provider_rate_limit = 40
mock.provider_rate_window = 60
mock.provider_max_concurrency = 5
@@ -158,6 +161,7 @@ def test_create_provider_instantiates_each_builtin():
settings = _make_settings(
gemini_api_key="test_gemini_key",
groq_api_key="test_groq_key",
+ cerebras_api_key="test_cerebras_key",
)
cases = {
"nvidia_nim": NvidiaNimProvider,
@@ -172,6 +176,7 @@ def test_create_provider_instantiates_each_builtin():
"zai": ZaiProvider,
"gemini": GeminiProvider,
"groq": GroqProvider,
+ "cerebras": CerebrasProvider,
}
with (