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 ZenMux provider (#1188) (#1388)

Tanishq-1c589610a9cd2
diff --git a/.env.example b/.env.example
index eed486a5..7432a266 100644
--- a/.env.example
+++ b/.env.example
@@ -77,7 +77,6 @@ TOKENROUTER_BASE_URL="https://api.tokenrouter.com/v1"
NARAROUTE_API_KEY=""
NARAROUTE_BASE_URL="https://router.bynara.id/v1"
-
# Fireworks AI Config (OpenAI-compatible Chat Completions at api.fireworks.ai/inference/v1)
FIREWORKS_API_KEY=""
@@ -125,6 +124,10 @@ DEEPINFRA_API_KEY=""
AGNES_API_KEY=""
+# ZenMux (OpenAI-compatible Chat Completions gateway at zenmux.ai/api/v1)
+ZENMUX_API_KEY=""
+
+
# SambaNova Cloud (OpenAI-compatible Chat Completions at api.sambanova.ai/v1)
SAMBANOVA_API_KEY=""
@@ -155,7 +158,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" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "xai" | "qwencloud" | "together" | "deepinfra" | "agnes" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"
+# Valid providers: "nvidia_nim" | "openai" | "azure_openai" | "open_router" | "gemini" | "vertex" | "deepseek" | "mistral" | "mistral_codestral" | "opencode_zen" | "opencode_go" | "vercel" | "bedrock" | "huggingface" | "cohere" | "github_models" | "wafer" | "kimi" | "kimi_code" | "minimax" | "cerebras" | "groq" | "xai" | "qwencloud" | "together" | "deepinfra" | "agnes" | "zenmux" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"
MODEL_FABLE=
MODEL_OPUS=
MODEL_SONNET=
@@ -201,6 +204,7 @@ FCC_SMOKE_MODEL_QWENCLOUD=
FCC_SMOKE_MODEL_TOGETHER=
FCC_SMOKE_MODEL_DEEPINFRA=
FCC_SMOKE_MODEL_AGNES=
+FCC_SMOKE_MODEL_ZENMUX=
FCC_SMOKE_MODEL_SAMBANOVA=
FCC_SMOKE_MODEL_KILO=
FCC_SMOKE_MODEL_CEREBRAS=
@@ -229,6 +233,7 @@ QWENCLOUD_PROXY=""
TOGETHER_PROXY=""
DEEPINFRA_PROXY=""
AGNES_PROXY=""
+ZENMUX_PROXY=""
AZURE_OPENAI_PROXY=""
NVIDIA_NIM_PROXY=""
OPENROUTER_PROXY=""
diff --git a/README.md b/README.md
index ae820ea1..4581de4e 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,7 @@ fcc-codex exec "hello"
| [Together AI](https://api.together.ai/settings/api-keys) | `TOGETHER_API_KEY` | `together/zai-org/GLM-5.2` |
| [DeepInfra](https://deepinfra.com/dash/api_keys) | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V4-Flash` |
| [Agnes AI](https://agnes-ai.com/) | `AGNES_API_KEY` | `agnes/agnes-2.0-flash` |
+| [ZenMux](https://zenmux.ai/platform/pay-as-you-go) | `ZENMUX_API_KEY` | `zenmux/deepseek/deepseek-v4-flash-free` |
| [Azure OpenAI](https://learn.microsoft.com/azure/foundry/openai/how-to/chatgpt) | `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_BASE_URL` | `azure_openai/<deployment-name>` |
| [Google AI Studio (Gemini)](https://aistudio.google.com/apikey) | `GEMINI_API_KEY` | `gemini/models/gemini-3.1-flash-lite` |
| [Google Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/start/openai) | `VERTEX_PROJECT_ID` + ADC | `vertex/google/gemini-3.5-flash` |
diff --git a/pyproject.toml b/pyproject.toml
index 01983cbb..b2f27d5e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.25.0"
+version = "4.26.0"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/lib/config.py b/smoke/lib/config.py
index 0783b80e..698a4c39 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -82,6 +82,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"tokenrouter": "tokenrouter/moonshotai/kimi-k3-free",
"nararoute": "nararoute/kimi-k3-free",
"agnes": "agnes/agnes-2.0-flash",
+ "zenmux": "zenmux/deepseek/deepseek-v4-flash-free",
}
MISTRAL_REASONING_SMOKE_DEFAULT_MODEL = "mistral/mistral-medium-3-5"
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index b9d508a4..547ba3f6 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -216,6 +216,13 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
"Agnes AI OpenAI-compatible API key for apihub.agnes-ai.com/v1."
),
},
+ "ZENMUX_API_KEY": {
+ "label": "ZenMux API Key",
+ "description": (
+ "ZenMux OpenAI-compatible gateway API key for zenmux.ai/api/v1. "
+ "Create one at zenmux.ai/platform/pay-as-you-go."
+ ),
+ },
}
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index 1852c8fc..b47d49cd 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -66,6 +66,8 @@ TOKENROUTER_DEFAULT_BASE = "https://api.tokenrouter.com/v1"
NARAROUTE_DEFAULT_BASE = "https://router.bynara.id/v1"
# Agnes AI OpenAI-compatible Chat Completions API.
AGNES_DEFAULT_BASE = "https://apihub.agnes-ai.com/v1"
+# ZenMux OpenAI-compatible Chat Completions gateway.
+ZENMUX_DEFAULT_BASE = "https://zenmux.ai/api/v1"
class ProviderAuthKind(StrEnum):
@@ -183,6 +185,15 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=AGNES_DEFAULT_BASE,
proxy_attr="agnes_proxy",
),
+ "zenmux": ProviderDescriptor(
+ provider_id="zenmux",
+ display_name="ZenMux",
+ credential_env="ZENMUX_API_KEY",
+ credential_url="https://zenmux.ai/platform/pay-as-you-go",
+ credential_attr="zenmux_api_key",
+ default_base_url=ZENMUX_DEFAULT_BASE,
+ proxy_attr="zenmux_proxy",
+ ),
"azure_openai": ProviderDescriptor(
provider_id="azure_openai",
display_name="Azure OpenAI",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index ad0bebad..08cc014b 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -146,6 +146,9 @@ class Settings(BaseSettings):
# ==================== Agnes AI (OpenAI-compatible) ====================
agnes_api_key: str = Field(default="", validation_alias="AGNES_API_KEY")
+ # ==================== ZenMux (OpenAI-compatible) ====================
+ zenmux_api_key: str = Field(default="", validation_alias="ZENMUX_API_KEY")
+
# ==================== Cerebras Inference (OpenAI-compatible) ====================
cerebras_api_key: str = Field(default="", validation_alias="CEREBRAS_API_KEY")
@@ -204,6 +207,7 @@ class Settings(BaseSettings):
together_proxy: str = Field(default="", validation_alias="TOGETHER_PROXY")
deepinfra_proxy: str = Field(default="", validation_alias="DEEPINFRA_PROXY")
agnes_proxy: str = Field(default="", validation_alias="AGNES_PROXY")
+ zenmux_proxy: str = Field(default="", validation_alias="ZENMUX_PROXY")
azure_openai_proxy: str = Field(default="", validation_alias="AZURE_OPENAI_PROXY")
nvidia_nim_proxy: str = Field(default="", validation_alias="NVIDIA_NIM_PROXY")
open_router_proxy: str = Field(default="", validation_alias="OPENROUTER_PROXY")
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index 0620cdfd..af077578 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -36,9 +36,11 @@ def extract_openai_model_infos(
aliases_field: str | None = None,
field_equals: tuple[str, str] | None = None,
required_null_field: str | None = None,
+ required_sequence_items: tuple[tuple[str, str], ...] = (),
tags_field: str | None = None,
thinking_tag: str = "reasoning",
non_thinking_tag: str | None = None,
+ thinking_boolean_path: tuple[str, ...] | None = None,
) -> frozenset[_ProviderModelInfo]:
"""Extract routable IDs from an OpenAI-compatible model-list response."""
model_infos: set[_ProviderModelInfo] = set()
@@ -77,6 +79,19 @@ def extract_openai_model_infos(
if _field(item, required_null_field) is not None:
included = False
+ for field_name, required_item in required_sequence_items:
+ values = _field(item, field_name)
+ if not _is_sequence(values) or any(
+ not isinstance(value, str) or not value.strip() for value in values
+ ):
+ raise _malformed(
+ provider_name,
+ f"expected every {item_location} item to include "
+ f"{field_name} string array",
+ )
+ if required_item not in values:
+ included = False
+
supports_thinking: bool | None = None
if tags_field is not None:
tags_value = _field(item, tags_field)
@@ -94,6 +109,16 @@ def extract_openai_model_infos(
elif non_thinking_tag is not None and non_thinking_tag in tags:
supports_thinking = False
+ if thinking_boolean_path is not None:
+ capability = _path(item, thinking_boolean_path)
+ if capability is not _MISSING:
+ if not isinstance(capability, bool):
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(thinking_boolean_path)} to be boolean",
+ )
+ supports_thinking = capability
+
if not included:
continue
@@ -192,6 +217,18 @@ def _has_field(item: Any, name: str) -> bool:
return hasattr(item, name)
+_MISSING = object()
+
+
+def _path(item: Any, path: tuple[str, ...]) -> Any:
+ current = item
+ for name in path:
+ if not _has_field(current, name):
+ return _MISSING
+ current = _field(current, name)
+ return current
+
+
def _is_sequence(value: Any) -> bool:
return isinstance(value, Sequence) and not isinstance(
value, str | bytes | bytearray
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 92863399..4fe5cba4 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -26,6 +26,7 @@ from .reasoning import (
ReasoningObject,
ThinkingObjectReasoning,
)
+from .reasoning_details import apply_reasoning_details_replay
from .request_policy import OpenAIChatPostprocessor, OpenAIChatRequestPolicy
_ALL_EFFORTS = tuple((effort, effort.value) for effort in ReasoningEffort)
@@ -37,6 +38,14 @@ _LOW_MEDIUM_HIGH = (
(ReasoningEffort.XHIGH, "high"),
(ReasoningEffort.MAX, "high"),
)
+_MINIMAL_TO_XHIGH = (
+ (ReasoningEffort.MINIMAL, "minimal"),
+ (ReasoningEffort.LOW, "low"),
+ (ReasoningEffort.MEDIUM, "medium"),
+ (ReasoningEffort.HIGH, "high"),
+ (ReasoningEffort.XHIGH, "xhigh"),
+ (ReasoningEffort.MAX, "xhigh"),
+)
_LOW_TO_MAX = (
(ReasoningEffort.MINIMAL, "low"),
(ReasoningEffort.LOW, "low"),
@@ -65,9 +74,11 @@ class OpenAIModelListing:
aliases_field: str | None = None
field_equals: tuple[str, str] | None = None
required_null_field: str | None = None
+ required_sequence_items: tuple[tuple[str, str], ...] = ()
tags_field: str | None = None
thinking_tag: str = "reasoning"
non_thinking_tag: str | None = None
+ thinking_boolean_path: tuple[str, ...] | None = None
@dataclass(frozen=True, slots=True)
@@ -83,6 +94,9 @@ class OpenAIChatProfile:
reasoning_delta_field: Literal["reasoning_content", "reasoning"] = (
"reasoning_content"
)
+ reasoning_delta_fallback_field: Literal["reasoning_content", "reasoning"] | None = (
+ None
+ )
structured_reasoning_details: bool = False
user_agent: str | None = None
@@ -95,6 +109,14 @@ class OpenAIChatProfile:
def reasoning_delta(self, delta: Any) -> str | None:
value = getattr(delta, self.reasoning_delta_field, None)
+ if isinstance(value, str) and value:
+ return value
+ fallback = self.reasoning_delta_fallback_field
+ if fallback is None:
+ return value if isinstance(value, str) else None
+ fallback_value = getattr(delta, fallback, None)
+ if isinstance(fallback_value, str):
+ return fallback_value
return value if isinstance(value, str) else None
def apply_reasoning(
@@ -225,6 +247,28 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
),
ChatTemplateReasoning(field="enable_thinking"),
),
+ "zenmux": OpenAIChatProfile(
+ _policy(
+ "ZENMUX",
+ ReasoningReplayMode.REASONING,
+ include_extra_body=True,
+ extra_body_validator=validate_extra_body_does_not_override_canonical_fields,
+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+ max_tokens_field="max_completion_tokens",
+ ),
+ ReasoningObject(_MINIMAL_TO_XHIGH),
+ postprocessors=(apply_reasoning_details_replay,),
+ model_listing=OpenAIModelListing(
+ required_sequence_items=(
+ ("input_modalities", "text"),
+ ("output_modalities", "text"),
+ ),
+ thinking_boolean_path=("capabilities", "reasoning"),
+ ),
+ reasoning_delta_field="reasoning",
+ reasoning_delta_fallback_field="reasoning_content",
+ structured_reasoning_details=True,
+ ),
"azure_openai": OpenAIChatProfile(
_policy(
"AZURE_OPENAI",
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index aaf32d41..0ee30c85 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -152,9 +152,11 @@ class OpenAIChatProvider(BaseProvider):
aliases_field=listing.aliases_field,
field_equals=listing.field_equals,
required_null_field=listing.required_null_field,
+ required_sequence_items=listing.required_sequence_items,
tags_field=listing.tags_field,
thinking_tag=listing.thinking_tag,
non_thinking_tag=listing.non_thinking_tag,
+ thinking_boolean_path=listing.thinking_boolean_path,
)
async def _list_models_payload(self) -> Any:
diff --git a/src/free_claude_code/providers/openai_chat/reasoning_details.py b/src/free_claude_code/providers/openai_chat/reasoning_details.py
index be576681..fa7852cb 100644
--- a/src/free_claude_code/providers/openai_chat/reasoning_details.py
+++ b/src/free_claude_code/providers/openai_chat/reasoning_details.py
@@ -68,6 +68,12 @@ class StructuredReasoningStream:
yield ledger.emit_thinking_delta(native_reasoning)
for detail in details:
+ if self._text_source == "details":
+ text = _reasoning_detail_text(detail)
+ if text:
+ yield from ledger.ensure_thinking_block()
+ yield ledger.emit_thinking_delta(text)
+
preserved = _preserved_reasoning_detail(detail)
if preserved:
yield from ledger.close_content_blocks()
@@ -78,14 +84,6 @@ class StructuredReasoningStream:
data=preserved,
)
yield ledger.content_block_stop(index)
- continue
- if self._text_source != "details":
- continue
- text = _reasoning_detail_text(detail)
- if not text:
- continue
- yield from ledger.ensure_thinking_block()
- yield ledger.emit_thinking_delta(text)
def _reasoning_details(delta: Any) -> Sequence[Any]:
@@ -145,10 +143,12 @@ def _preserved_reasoning_detail(detail: Any) -> str | None:
if not isinstance(detail, Mapping):
return None
kind = str(_field(detail, "type") or "").lower()
+ signature = _field(detail, "signature")
if (
"encrypted" in kind
or "redacted" in kind
or "summary" in kind
+ or isinstance(signature, str)
or _reasoning_detail_text(detail) is None
):
return json.dumps(dict(detail), separators=(",", ":"))
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 6edda527..70175584 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -15,6 +15,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"together",
"deepinfra",
"agnes",
+ "zenmux",
"azure_openai",
"gemini",
"vertex",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index d917ff75..0f076890 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -240,6 +240,23 @@ def test_agnes_provider_smoke_uses_documented_model(monkeypatch) -> None:
assert models[0].source == "provider_default"
+def test_zenmux_provider_smoke_uses_current_free_model(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_ZENMUX", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ zenmux_api_key="zenmux-key",
+ )
+ )
+
+ models = config.provider_smoke_models()
+
+ assert [model.provider for model in models] == ["zenmux"]
+ assert models[0].full_model == "zenmux/deepseek/deepseek-v4-flash-free"
+ assert models[0].source == "provider_default"
+
+
def test_connected_account_provider_smoke_requires_explicit_model(
monkeypatch,
) -> None:
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 0513262e..d21e5f2e 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -29,6 +29,7 @@ from free_claude_code.config.provider_catalog import (
VERCEL_AI_GATEWAY_DEFAULT_BASE,
XAI_DEFAULT_BASE,
ZAI_DEFAULT_BASE,
+ ZENMUX_DEFAULT_BASE,
)
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.cloudflare import CloudflareProvider
@@ -87,6 +88,7 @@ def _make_settings(**overrides):
mock.nararoute_api_key = "test_nararoute_key"
mock.nararoute_base_url = NARAROUTE_DEFAULT_BASE
mock.agnes_api_key = "test_agnes_key"
+ mock.zenmux_api_key = "test_zenmux_key"
mock.lm_studio_base_url = "http://localhost:1234/v1"
mock.llamacpp_base_url = "http://localhost:8080/v1"
mock.ollama_base_url = "http://localhost:11434"
@@ -114,6 +116,7 @@ def _make_settings(**overrides):
mock.tokenrouter_proxy = ""
mock.nararoute_proxy = ""
mock.agnes_proxy = ""
+ mock.zenmux_proxy = ""
mock.fireworks_proxy = ""
mock.fireworks_api_key = "test_fireworks_key"
mock.novita_proxy = ""
@@ -303,6 +306,26 @@ def test_agnes_provider_config_uses_key_base_and_proxy() -> None:
assert isinstance(provider, OpenAIChatProvider)
+def test_zenmux_provider_config_uses_key_base_and_proxy() -> None:
+ descriptor = PROVIDER_CATALOG["zenmux"]
+ settings = _make_settings(
+ zenmux_api_key="zenmux-token",
+ zenmux_proxy="http://proxy.test:8080",
+ )
+
+ config = build_provider_config(descriptor, settings)
+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
+ provider = create_provider("zenmux", settings)
+
+ assert descriptor.display_name == "ZenMux"
+ assert descriptor.credential_env == "ZENMUX_API_KEY"
+ assert descriptor.base_url_attr is None
+ assert config.api_key == "zenmux-token"
+ assert config.base_url == ZENMUX_DEFAULT_BASE
+ assert config.proxy == "http://proxy.test:8080"
+ assert isinstance(provider, OpenAIChatProvider)
+
+
def test_bedrock_provider_config_uses_regional_base_key_and_proxy() -> None:
descriptor = PROVIDER_CATALOG["bedrock"]
settings = _make_settings(
@@ -625,6 +648,7 @@ def test_create_provider_instantiates_each_builtin():
"tokenrouter": OpenAIChatProvider,
"nararoute": OpenAIChatProvider,
"agnes": OpenAIChatProvider,
+ "zenmux": OpenAIChatProvider,
"gemini": GeminiProvider,
"vertex": VertexProvider,
"groq": GroqProvider,
diff --git a/tests/providers/test_zenmux.py b/tests/providers/test_zenmux.py
new file mode 100644
index 00000000..ef41489e
--- /dev/null
+++ b/tests/providers/test_zenmux.py
@@ -0,0 +1,512 @@
+"""Tests for the ZenMux OpenAI-chat provider profile."""
+
+import json
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+from openai import AsyncOpenAI
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.model_metadata import ProviderModelInfo
+from free_claude_code.config.provider_catalog import ZENMUX_DEFAULT_BASE
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.anthropic.stream_contracts import (
+ parse_sse_text,
+ text_content,
+ thinking_content,
+)
+from free_claude_code.core.reasoning import ReasoningEffort, ReasoningPolicy
+from free_claude_code.providers.base import ProviderConfig
+from free_claude_code.providers.model_listing import ModelListResponseError
+from free_claude_code.providers.openai_chat import OpenAIChatProvider
+from tests.providers.support import (
+ immediate_admission,
+ profiled_provider,
+ reasoning_for,
+)
+
+
+def zenmux_provider() -> OpenAIChatProvider:
+ return profiled_provider(
+ "zenmux",
+ ProviderConfig(
+ api_key="test-zenmux-key",
+ base_url=ZENMUX_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ ),
+ admission=immediate_admission(provider_name="zenmux"),
+ )
+
+
+def _request(**overrides: Any) -> MessagesRequest:
+ payload: dict[str, Any] = {
+ "model": "deepseek/deepseek-v4-flash-free",
+ "messages": [{"role": "user", "content": "Hello"}],
+ }
+ payload.update(overrides)
+ return MessagesRequest.model_validate(payload)
+
+
+class AsyncStream:
+ def __init__(self, chunks: list[Any]) -> None:
+ self._chunks = chunks
+ self.closed = False
+
+ def __aiter__(self):
+ return self._iter()
+
+ async def _iter(self):
+ for chunk in self._chunks:
+ yield chunk
+
+ async def aclose(self) -> None:
+ self.closed = True
+
+
+def _chunk(
+ *,
+ content: str | None = None,
+ reasoning: str | None = None,
+ reasoning_content: str | None = None,
+ reasoning_details: list[dict[str, Any]] | None = None,
+ finish_reason: str | None = None,
+) -> Any:
+ delta = SimpleNamespace(
+ content=content,
+ reasoning=reasoning,
+ reasoning_content=reasoning_content,
+ reasoning_details=reasoning_details,
+ tool_calls=None,
+ )
+ choice = SimpleNamespace(delta=delta, finish_reason=finish_reason)
+ return SimpleNamespace(choices=[choice], usage=None)
+
+
+def test_init_uses_documented_endpoint(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ assert zenmux_provider._api_key == "test-zenmux-key"
+ assert zenmux_provider._base_url == ZENMUX_DEFAULT_BASE
+ assert zenmux_provider._provider_name == "ZENMUX"
+
+
+def test_build_request_body_uses_supported_output_field_tools_and_images(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ request = _request(
+ max_tokens=100,
+ system="Be concise.",
+ messages=[
+ {
+ "role": "user",
+ "content": [
+ {"type": "text", "text": "Inspect this image."},
+ {
+ "type": "image",
+ "source": {
+ "type": "base64",
+ "media_type": "image/png",
+ "data": "aW1hZ2U=",
+ },
+ },
+ ],
+ }
+ ],
+ tools=[
+ {
+ "name": "inspect_image",
+ "description": "Inspect an image",
+ "input_schema": {
+ "type": "object",
+ "properties": {"detail": {"type": "string"}},
+ },
+ }
+ ],
+ )
+
+ body = zenmux_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["model"] == "deepseek/deepseek-v4-flash-free"
+ assert body["max_completion_tokens"] == 100
+ assert "max_tokens" not in body
+ assert body["messages"][0] == {"role": "system", "content": "Be concise."}
+ assert body["messages"][1]["content"][1] == {
+ "type": "image_url",
+ "image_url": {"url": "data:image/png;base64,aW1hZ2U="},
+ }
+ assert body["tools"][0]["function"]["name"] == "inspect_image"
+
+
+ ("effort", "expected"),
+ [
+ (ReasoningEffort.MINIMAL, "minimal"),
+ (ReasoningEffort.LOW, "low"),
+ (ReasoningEffort.MEDIUM, "medium"),
+ (ReasoningEffort.HIGH, "high"),
+ (ReasoningEffort.XHIGH, "xhigh"),
+ (ReasoningEffort.MAX, "xhigh"),
+ ],
+)
+def test_build_request_body_maps_reasoning_effort_to_documented_vocabulary(
+ zenmux_provider: OpenAIChatProvider,
+ effort: ReasoningEffort,
+ expected: str,
+) -> None:
+ body = zenmux_provider._build_request_body(
+ _request(),
+ reasoning=ReasoningPolicy.on(effort=effort),
+ )
+
+ assert body["extra_body"]["reasoning"] == {"effort": expected}
+
+
+ ("reasoning", "expected"),
+ [
+ (ReasoningPolicy.off(), {"enabled": False}),
+ (ReasoningPolicy.on(), {"enabled": True}),
+ (ReasoningPolicy.on(budget_tokens=2048), {"max_tokens": 2048}),
+ ],
+)
+def test_build_request_body_maps_reasoning_control_and_budget(
+ zenmux_provider: OpenAIChatProvider,
+ reasoning: ReasoningPolicy,
+ expected: dict[str, Any],
+) -> None:
+ body = zenmux_provider._build_request_body(_request(), reasoning=reasoning)
+
+ assert body["extra_body"]["reasoning"] == expected
+
+
+def test_build_request_body_leaves_reasoning_to_provider_by_default(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ body = zenmux_provider._build_request_body(
+ _request(),
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+ assert "reasoning" not in body.get("extra_body", {})
+
+
+def test_build_request_body_preserves_unrelated_gateway_options(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ request = _request(extra_body={"provider": {"fallback": "true"}})
+
+ body = zenmux_provider._build_request_body(
+ request,
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+ assert body["extra_body"] == {"provider": {"fallback": "true"}}
+
+
+ "field",
+ ["model", "messages", "max_completion_tokens", "reasoning", "reasoning_effort"],
+)
+def test_build_request_body_rejects_caller_canonical_override(
+ zenmux_provider: OpenAIChatProvider,
+ field: str,
+) -> None:
+ request = _request(extra_body={field: "caller-owned"})
+
+ with pytest.raises(InvalidRequestError, match="must not override canonical"):
+ zenmux_provider._build_request_body(
+ request,
+ reasoning=ReasoningPolicy.on(),
+ )
+
+
+def test_build_request_body_replays_reasoning_and_signed_details_unchanged(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ detail = {
+ "type": "reasoning.text",
+ "text": "Need a tool.",
+ "signature": "signed-opaque-value",
+ "format": "anthropic-claude-v1",
+ "index": 0,
+ }
+ request = _request(
+ messages=[
+ {"role": "user", "content": "Inspect the repository."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Need a tool."},
+ {"type": "redacted_thinking", "data": json.dumps(detail)},
+ {
+ "type": "tool_use",
+ "id": "call_read",
+ "name": "Read",
+ "input": {},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "call_read",
+ "content": "contents",
+ }
+ ],
+ },
+ ]
+ )
+
+ body = zenmux_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assistant = next(
+ message for message in body["messages"] if message["role"] == "assistant"
+ )
+ assert assistant["reasoning"] == "Need a tool."
+ assert assistant["reasoning_details"] == [detail]
+
+
+def test_reasoning_delta_prefers_reasoning_and_falls_back_to_reasoning_content(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ profile = zenmux_provider._profile
+
+ assert (
+ profile.reasoning_delta(
+ SimpleNamespace(reasoning="primary", reasoning_content="fallback")
+ )
+ == "primary"
+ )
+ assert (
+ profile.reasoning_delta(
+ SimpleNamespace(reasoning=None, reasoning_content="fallback")
+ )
+ == "fallback"
+ )
+ assert (
+ profile.reasoning_delta(
+ SimpleNamespace(reasoning="", reasoning_content="fallback")
+ )
+ == "fallback"
+ )
+
+
[email protected]("native_reasoning", ["plan ", None])
+async def test_stream_preserves_signed_details_without_duplicating_reasoning(
+ zenmux_provider: OpenAIChatProvider,
+ native_reasoning: str | None,
+) -> None:
+ detail = {
+ "type": "reasoning.text",
+ "text": "plan ",
+ "signature": "signed-opaque-value",
+ "format": "anthropic-claude-v1",
+ "index": 0,
+ }
+ stream = AsyncStream(
+ [
+ _chunk(
+ reasoning=native_reasoning,
+ reasoning_details=[detail],
+ ),
+ _chunk(content="done", finish_reason="stop"),
+ ]
+ )
+ with patch.object(
+ zenmux_provider._client.chat.completions,
+ "create",
+ new_callable=AsyncMock,
+ return_value=stream,
+ ):
+ event_text = "".join(
+ [event async for event in zenmux_provider.stream_response(_request())]
+ )
+
+ events = parse_sse_text(event_text)
+ assert thinking_content(events) == "plan "
+ assert text_content(events) == "done"
+ redacted_blocks = [
+ event.data["content_block"]
+ for event in events
+ if event.event == "content_block_start"
+ and event.data.get("content_block", {}).get("type") == "redacted_thinking"
+ ]
+ assert len(redacted_blocks) == 1
+ assert json.loads(redacted_blocks[0]["data"]) == detail
+ assert stream.closed
+
+
+async def test_model_catalog_filters_modalities_and_maps_reasoning_capability(
+ zenmux_provider: OpenAIChatProvider,
+) -> None:
+ payload = SimpleNamespace(
+ data=[
+ {
+ "id": "reasoning-chat",
+ "input_modalities": ["text", "image"],
+ "output_modalities": ["text"],
+ "capabilities": {"reasoning": True},
+ },
+ {
+ "id": "plain-chat",
+ "input_modalities": ["text"],
+ "output_modalities": ["text"],
+ "capabilities": {"reasoning": False},
+ },
+ {
+ "id": "unknown-chat",
+ "input_modalities": ["text"],
+ "output_modalities": ["text"],
+ },
+ {
+ "id": "image-generator",
+ "input_modalities": ["text"],
+ "output_modalities": ["image"],
+ "capabilities": {"reasoning": False},
+ },
+ ]
+ )
+
+ with patch.object(
+ zenmux_provider._client.models,
+ "list",
+ new_callable=AsyncMock,
+ return_value=payload,
+ ):
+ model_infos = await zenmux_provider.list_model_infos()
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo("reasoning-chat", supports_thinking=True),
+ ProviderModelInfo("plain-chat", supports_thinking=False),
+ ProviderModelInfo("unknown-chat"),
+ }
+ )
+
+
+async def test_model_catalog_uses_documented_endpoint_and_auth() -> None:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ return httpx.Response(
+ 200,
+ json={
+ "object": "list",
+ "data": [
+ {
+ "id": "deepseek/deepseek-v4-flash-free",
+ "object": "model",
+ "created": 0,
+ "owned_by": "deepseek",
+ "input_modalities": ["text"],
+ "output_modalities": ["text"],
+ "capabilities": {"reasoning": True},
+ }
+ ],
+ },
+ )
+
+ http_client = httpx.AsyncClient(transport=httpx.MockTransport(handler))
+
+ def build_client(*args: Any, **kwargs: Any) -> AsyncOpenAI:
+ kwargs["http_client"] = http_client
+ return AsyncOpenAI(*args, **kwargs)
+
+ with patch(
+ "free_claude_code.providers.openai_chat.provider.AsyncOpenAI",
+ side_effect=build_client,
+ ):
+ provider = profiled_provider(
+ "zenmux",
+ ProviderConfig(
+ api_key="wire-zenmux-key",
+ base_url=ZENMUX_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ ),
+ admission=immediate_admission(provider_name="zenmux"),
+ )
+ try:
+ model_infos = await provider.list_model_infos()
+ finally:
+ await provider.cleanup()
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo(
+ "deepseek/deepseek-v4-flash-free",
+ supports_thinking=True,
+ )
+ }
+ )
+ assert len(requests) == 1
+ assert str(requests[0].url) == "https://zenmux.ai/api/v1/models"
+ assert requests[0].headers["authorization"] == "Bearer wire-zenmux-key"
+
+
+ ("model", "message"),
+ [
+ (
+ {
+ "id": "missing-input-modalities",
+ "output_modalities": ["text"],
+ "capabilities": {"reasoning": True},
+ },
+ "input_modalities string array",
+ ),
+ (
+ {
+ "id": "bad-output-modalities",
+ "input_modalities": ["text"],
+ "output_modalities": [7],
+ "capabilities": {"reasoning": True},
+ },
+ "output_modalities string array",
+ ),
+ (
+ {
+ "id": "bad-reasoning-capability",
+ "input_modalities": ["text"],
+ "output_modalities": ["text"],
+ "capabilities": {"reasoning": "yes"},
+ },
+ "capabilities.reasoning to be boolean",
+ ),
+ ],
+)
+async def test_model_catalog_rejects_malformed_documented_fields(
+ zenmux_provider: OpenAIChatProvider,
+ model: dict[str, Any],
+ message: str,
+) -> None:
+ payload = SimpleNamespace(data=[model])
+
+ with (
+ patch.object(
+ zenmux_provider._client.models,
+ "list",
+ new_callable=AsyncMock,
+ return_value=payload,
+ ),
+ pytest.raises(ModelListResponseError, match=message),
+ ):
+ await zenmux_provider.list_model_infos()
diff --git a/uv.lock b/uv.lock
index c89c0448..1fdd2931 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.25.0"
+version = "4.26.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },