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 Featherless AI provider (#1405)

Ali Khokhar79f354803fc3
diff --git a/.env.example b/.env.example
index d8007fea..ae3c6f7f 100644
--- a/.env.example
+++ b/.env.example
@@ -132,6 +132,10 @@ NEBIUS_API_KEY=""
CHUTES_API_KEY=""
+# Featherless AI (OpenAI-compatible Chat Completions at api.featherless.ai/v1)
+FEATHERLESS_API_KEY=""
+
+
# Agnes AI (OpenAI-compatible Chat Completions at apihub.agnes-ai.com/v1)
AGNES_API_KEY=""
@@ -170,7 +174,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" | "siliconflow" | "nebius" | "chutes" | "agnes" | "zenmux" | "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" | "siliconflow" | "nebius" | "chutes" | "featherless" | "agnes" | "zenmux" | "sambanova" | "kilo" | "fireworks" | "novita" | "cloudflare" | "zai" | "ollama_cloud" | "lmstudio" | "llamacpp" | "ollama" | "tokenrouter" | "nararoute"
MODEL_FABLE=
MODEL_OPUS=
MODEL_SONNET=
@@ -218,6 +222,7 @@ FCC_SMOKE_MODEL_DEEPINFRA=
FCC_SMOKE_MODEL_SILICONFLOW=
FCC_SMOKE_MODEL_NEBIUS=
FCC_SMOKE_MODEL_CHUTES=
+FCC_SMOKE_MODEL_FEATHERLESS=
FCC_SMOKE_MODEL_AGNES=
FCC_SMOKE_MODEL_ZENMUX=
FCC_SMOKE_MODEL_SAMBANOVA=
@@ -250,6 +255,7 @@ DEEPINFRA_PROXY=""
SILICONFLOW_PROXY=""
NEBIUS_PROXY=""
CHUTES_PROXY=""
+FEATHERLESS_PROXY=""
AGNES_PROXY=""
ZENMUX_PROXY=""
AZURE_OPENAI_PROXY=""
diff --git a/README.md b/README.md
index d1b7bd9a..8637a0c8 100644
--- a/README.md
+++ b/README.md
@@ -163,6 +163,7 @@ fcc-codex exec "hello"
| [SiliconFlow](https://cloud.siliconflow.com/account/ak) | `SILICONFLOW_API_KEY` | `siliconflow/Qwen/Qwen3-32B` |
| [Nebius Token Factory](https://tokenfactory.nebius.com/project/api-keys) | `NEBIUS_API_KEY` | `nebius/Qwen/Qwen3-30B-A3B` |
| [Chutes](https://chutes.ai/docs/getting-started/authentication) | `CHUTES_API_KEY` | `chutes/Qwen/Qwen3-32B-TEE` |
+| [Featherless AI](https://featherless.ai/account/api-keys) | `FEATHERLESS_API_KEY` | `featherless/Qwen/Qwen3-32B` |
| [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>` |
diff --git a/pyproject.toml b/pyproject.toml
index bb12e57a..fdf8f5e6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.29.0"
+version = "4.30.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 3a83fb04..7ba4ce89 100644
--- a/smoke/lib/config.py
+++ b/smoke/lib/config.py
@@ -77,6 +77,7 @@ PROVIDER_SMOKE_DEFAULT_MODELS: dict[str, str] = {
"siliconflow": "siliconflow/Qwen/Qwen3-32B",
"nebius": "nebius/Qwen/Qwen3-30B-A3B",
"chutes": "chutes/Qwen/Qwen3-32B-TEE",
+ "featherless": "featherless/Qwen/Qwen3-32B",
"sambanova": "sambanova/Meta-Llama-3.3-70B-Instruct",
"kilo": "kilo/kilo-auto/free",
"cerebras": "cerebras/llama3.1-8b",
diff --git a/src/free_claude_code/config/admin/provider_manifest.py b/src/free_claude_code/config/admin/provider_manifest.py
index e207dbcd..14ba4d96 100644
--- a/src/free_claude_code/config/admin/provider_manifest.py
+++ b/src/free_claude_code/config/admin/provider_manifest.py
@@ -186,6 +186,13 @@ _PROVIDER_FIELD_OVERRIDES: dict[str, dict[str, Any]] = {
"tool-capable models."
),
},
+ "FEATHERLESS_API_KEY": {
+ "label": "Featherless AI API Key",
+ "description": (
+ "Featherless AI API key for plan-available OpenAI-compatible chat, "
+ "reasoning, and tool-capable models."
+ ),
+ },
"SAMBANOVA_API_KEY": {
"label": "SambaNova API Key",
"description": (
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index b6af6114..0a317dd4 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -66,6 +66,8 @@ SILICONFLOW_DEFAULT_BASE = "https://api.siliconflow.com/v1"
NEBIUS_DEFAULT_BASE = "https://api.tokenfactory.nebius.com/v1"
# Chutes OpenAI-compatible Chat Completions API.
CHUTES_DEFAULT_BASE = "https://llm.chutes.ai/v1"
+# Featherless AI OpenAI-compatible Chat Completions API.
+FEATHERLESS_DEFAULT_BASE = "https://api.featherless.ai/v1"
# TokenRouter OpenAI-compatible Chat Completions gateway.
TOKENROUTER_DEFAULT_BASE = "https://api.tokenrouter.com/v1"
# NaraRoute OpenAI-compatible Chat Completions gateway.
@@ -209,6 +211,15 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=CHUTES_DEFAULT_BASE,
proxy_attr="chutes_proxy",
),
+ "featherless": ProviderDescriptor(
+ provider_id="featherless",
+ display_name="Featherless AI",
+ credential_env="FEATHERLESS_API_KEY",
+ credential_url="https://featherless.ai/account/api-keys",
+ credential_attr="featherless_api_key",
+ default_base_url=FEATHERLESS_DEFAULT_BASE,
+ proxy_attr="featherless_proxy",
+ ),
"agnes": ProviderDescriptor(
provider_id="agnes",
display_name="Agnes AI",
diff --git a/src/free_claude_code/config/settings.py b/src/free_claude_code/config/settings.py
index a65c54e0..b0dcc7b6 100644
--- a/src/free_claude_code/config/settings.py
+++ b/src/free_claude_code/config/settings.py
@@ -152,6 +152,9 @@ class Settings(BaseSettings):
# ==================== Chutes (OpenAI-compatible) ====================
chutes_api_key: str = Field(default="", validation_alias="CHUTES_API_KEY")
+ # ==================== Featherless AI (OpenAI-compatible) ====================
+ featherless_api_key: str = Field(default="", validation_alias="FEATHERLESS_API_KEY")
+
# ==================== Agnes AI (OpenAI-compatible) ====================
agnes_api_key: str = Field(default="", validation_alias="AGNES_API_KEY")
@@ -218,6 +221,7 @@ class Settings(BaseSettings):
siliconflow_proxy: str = Field(default="", validation_alias="SILICONFLOW_PROXY")
nebius_proxy: str = Field(default="", validation_alias="NEBIUS_PROXY")
chutes_proxy: str = Field(default="", validation_alias="CHUTES_PROXY")
+ featherless_proxy: str = Field(default="", validation_alias="FEATHERLESS_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")
diff --git a/src/free_claude_code/providers/model_listing.py b/src/free_claude_code/providers/model_listing.py
index 6793467a..d950f891 100644
--- a/src/free_claude_code/providers/model_listing.py
+++ b/src/free_claude_code/providers/model_listing.py
@@ -49,7 +49,7 @@ def extract_openai_model_infos(
thinking_boolean_path: tuple[str, ...] | None = None,
) -> frozenset[_ProviderModelInfo]:
"""Extract routable IDs from an OpenAI-compatible model-list response."""
- model_infos: set[_ProviderModelInfo] = set()
+ model_infos: dict[str, _ProviderModelInfo] = {}
item_location = collection_field or "root-array"
for item in model_list_items(
payload,
@@ -142,11 +142,9 @@ def extract_openai_model_infos(
if not included:
continue
- model_infos.add(
- _ProviderModelInfo(
- model_id=model_id,
- supports_thinking=supports_thinking,
- )
+ model_infos.setdefault(
+ model_id,
+ _ProviderModelInfo(model_id=model_id, supports_thinking=supports_thinking),
)
if aliases_field is not None:
aliases = _field(item, aliases_field)
@@ -162,16 +160,16 @@ def extract_openai_model_infos(
provider_name,
f"expected every {aliases_field} item to be a model id",
)
- model_infos.add(
+ model_infos.setdefault(
+ alias,
_ProviderModelInfo(
- model_id=alias,
- supports_thinking=supports_thinking,
- )
+ model_id=alias, supports_thinking=supports_thinking
+ ),
)
if not model_infos:
raise _malformed(provider_name, "response did not include any model ids")
- return frozenset(model_infos)
+ return frozenset(model_infos.values())
def extract_tool_capable_model_infos(
@@ -225,6 +223,71 @@ def model_list_items(
return tuple(data)
+def validate_model_list_page(
+ payload: Any,
+ *,
+ provider_name: str,
+ expected_page: int,
+ current_page_path: tuple[str, ...],
+ total_pages_path: tuple[str, ...],
+ max_pages: int,
+ expected_total_pages: int | None = None,
+) -> int:
+ """Validate numbered pagination metadata and return the total page count."""
+ current_page = _path(payload, current_page_path)
+ if type(current_page) is not int:
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(current_page_path)} to be an integer",
+ )
+ if current_page != expected_page:
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(current_page_path)} to be {expected_page}",
+ )
+
+ total_pages = _path(payload, total_pages_path)
+ if type(total_pages) is not int:
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(total_pages_path)} to be an integer",
+ )
+ if total_pages < 1 or total_pages > max_pages:
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(total_pages_path)} between 1 and {max_pages}",
+ )
+ if expected_total_pages is not None and total_pages != expected_total_pages:
+ raise _malformed(
+ provider_name,
+ f"expected {'.'.join(total_pages_path)} to remain {expected_total_pages}",
+ )
+ return total_pages
+
+
+def merge_model_list_pages(
+ payloads: Iterable[Any],
+ *,
+ provider_name: str,
+ collection_field: str | None,
+) -> tuple[Any, ...] | dict[str, tuple[Any, ...]]:
+ """Combine complete model-list pages before strict record parsing."""
+ merged: list[Any] = []
+ for payload in payloads:
+ merged.extend(
+ model_list_items(
+ payload,
+ provider_name=provider_name,
+ collection_field=collection_field,
+ )
+ )
+
+ items = tuple(merged)
+ if collection_field is None:
+ return items
+ return {collection_field: items}
+
+
def _field(item: Any, name: str) -> Any:
if isinstance(item, Mapping):
return item.get(name)
diff --git a/src/free_claude_code/providers/openai_chat/profiles.py b/src/free_claude_code/providers/openai_chat/profiles.py
index 3053ae25..0f5497d9 100644
--- a/src/free_claude_code/providers/openai_chat/profiles.py
+++ b/src/free_claude_code/providers/openai_chat/profiles.py
@@ -65,6 +65,17 @@ _KIMI_CODE_EFFORTS = (
)
+@dataclass(frozen=True, slots=True)
+class OpenAIModelPagination:
+ """Bounded numbered-pagination metadata for a model-list endpoint."""
+
+ page_param: str = "page"
+ first_page: int = 1
+ current_page_path: tuple[str, ...] = ("pagination", "current_page")
+ total_pages_path: tuple[str, ...] = ("pagination", "total_pages")
+ max_pages: int = 100
+
+
@dataclass(frozen=True, slots=True)
class OpenAIModelListing:
"""Declarative model-list endpoint and response shape."""
@@ -82,6 +93,7 @@ class OpenAIModelListing:
thinking_tag: str = "reasoning"
non_thinking_tag: str | None = None
thinking_boolean_path: tuple[str, ...] | None = None
+ pagination: OpenAIModelPagination | None = None
@dataclass(frozen=True, slots=True)
@@ -289,6 +301,31 @@ OPENAI_CHAT_PROFILES: dict[str, OpenAIChatProfile] = {
tags_field="supported_features",
),
),
+ "featherless": OpenAIChatProfile(
+ _policy(
+ "FEATHERLESS",
+ ReasoningReplayMode.REASONING_CONTENT,
+ include_extra_body=True,
+ extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
+ default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+ ),
+ ChatTemplateReasoning(field="enable_thinking"),
+ model_listing=OpenAIModelListing(
+ path="/models",
+ query_params=(
+ ("capabilities", "chat,tool-use"),
+ ("available_on_current_plan", "true"),
+ ("status", "active"),
+ ("per_page", "1000"),
+ ),
+ required_path_values=(
+ (("features", "tool_use"), (True,)),
+ (("is_gated",), (False,)),
+ (("available_on_current_plan",), (True,)),
+ ),
+ pagination=OpenAIModelPagination(),
+ ),
+ ),
"agnes": OpenAIChatProfile(
_policy(
"AGNES",
diff --git a/src/free_claude_code/providers/openai_chat/provider.py b/src/free_claude_code/providers/openai_chat/provider.py
index 594d9532..9e32d91c 100644
--- a/src/free_claude_code/providers/openai_chat/provider.py
+++ b/src/free_claude_code/providers/openai_chat/provider.py
@@ -48,7 +48,11 @@ from free_claude_code.providers.http import (
close_provider_stream,
maybe_await_aclose,
)
-from free_claude_code.providers.model_listing import extract_openai_model_infos
+from free_claude_code.providers.model_listing import (
+ extract_openai_model_infos,
+ merge_model_list_pages,
+ validate_model_list_page,
+)
from free_claude_code.providers.stream_recovery import (
RecoveryController,
RecoveryFailureAction,
@@ -174,6 +178,8 @@ class OpenAIChatProvider(BaseProvider):
path = listing.path
if path is None:
return await self._client.models.list()
+ if listing.pagination is not None:
+ return await self._fetch_paginated_models_payload(path)
if listing.query_params:
return await self._client.get(
path,
@@ -182,6 +188,42 @@ class OpenAIChatProvider(BaseProvider):
)
return await self._client.get(path, cast_to=object)
+ async def _fetch_paginated_models_payload(self, path: str) -> Any:
+ """Fetch one complete bounded model catalog within a retry attempt."""
+ listing = self._profile.model_listing
+ pagination = listing.pagination
+ if pagination is None:
+ raise RuntimeError("paginated model fetch requires a pagination policy")
+
+ payloads: list[Any] = []
+ total_pages: int | None = None
+ page = pagination.first_page
+ while total_pages is None or page < pagination.first_page + total_pages:
+ params = dict(listing.query_params)
+ params[pagination.page_param] = str(page)
+ payload = await self._client.get(
+ path,
+ cast_to=object,
+ options={"params": params},
+ )
+ total_pages = validate_model_list_page(
+ payload,
+ provider_name=self._provider_name,
+ expected_page=page,
+ current_page_path=pagination.current_page_path,
+ total_pages_path=pagination.total_pages_path,
+ max_pages=pagination.max_pages,
+ expected_total_pages=total_pages,
+ )
+ payloads.append(payload)
+ page += 1
+
+ return merge_model_list_pages(
+ payloads,
+ provider_name=self._provider_name,
+ collection_field=listing.collection_field,
+ )
+
def _build_request_body(
self,
request: MessagesRequest,
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 7946b0f8..bba0fe8d 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -17,6 +17,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"siliconflow",
"nebius",
"chutes",
+ "featherless",
"agnes",
"zenmux",
"azure_openai",
diff --git a/tests/contracts/test_smoke_config.py b/tests/contracts/test_smoke_config.py
index 60760dbd..58115287 100644
--- a/tests/contracts/test_smoke_config.py
+++ b/tests/contracts/test_smoke_config.py
@@ -60,6 +60,7 @@ def _settings(**overrides):
"siliconflow_api_key": "",
"nebius_api_key": "",
"chutes_api_key": "",
+ "featherless_api_key": "",
"sambanova_api_key": "",
"cerebras_api_key": "",
"ollama_api_key": "",
@@ -277,6 +278,23 @@ def test_chutes_provider_smoke_uses_documented_agent_model(monkeypatch) -> None:
assert models[0].source == "provider_default"
+def test_featherless_provider_smoke_uses_documented_agent_model(monkeypatch) -> None:
+ monkeypatch.delenv("FCC_SMOKE_MODEL_FEATHERLESS", raising=False)
+ config = _smoke_config(
+ settings=_settings(
+ model="ollama/llama3.1",
+ ollama_base_url="",
+ featherless_api_key="featherless-key",
+ )
+ )
+
+ models = config.provider_smoke_models()
+
+ assert [model.provider for model in models] == ["featherless"]
+ assert models[0].full_model == "featherless/Qwen/Qwen3-32B"
+ assert models[0].source == "provider_default"
+
+
def test_agnes_provider_smoke_uses_documented_model(monkeypatch) -> None:
monkeypatch.delenv("FCC_SMOKE_MODEL_AGNES", raising=False)
config = _smoke_config(
diff --git a/tests/providers/test_featherless.py b/tests/providers/test_featherless.py
new file mode 100644
index 00000000..dd6c8123
--- /dev/null
+++ b/tests/providers/test_featherless.py
@@ -0,0 +1,432 @@
+"""Tests for the Featherless AI OpenAI-chat provider profile."""
+
+from typing import Any
+from unittest.mock import AsyncMock
+
+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.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+from free_claude_code.config.provider_catalog import FEATHERLESS_DEFAULT_BASE
+from free_claude_code.core.anthropic.models import MessagesRequest
+from free_claude_code.core.reasoning import 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 (
+ REASONING_OFF,
+ REASONING_ON,
+ immediate_admission,
+ profiled_provider,
+ reasoning_for,
+)
+
+_MODEL = "Qwen/Qwen3-32B"
+
+
+def featherless_provider() -> OpenAIChatProvider:
+ return profiled_provider(
+ "featherless",
+ ProviderConfig(
+ api_key="test-featherless-key",
+ base_url=FEATHERLESS_DEFAULT_BASE,
+ rate_limit=10,
+ rate_window=60,
+ ),
+ admission=immediate_admission(
+ provider_name="featherless",
+ max_attempts=1,
+ ),
+ )
+
+
+def _request(**overrides: Any) -> MessagesRequest:
+ payload: dict[str, Any] = {
+ "model": _MODEL,
+ "messages": [{"role": "user", "content": "Hello"}],
+ }
+ payload.update(overrides)
+ return MessagesRequest.model_validate(payload)
+
+
+def _catalog_model(
+ model_id: str = _MODEL,
+ *,
+ tool_use: object = True,
+ gated: object = False,
+ available: object = True,
+) -> dict[str, object]:
+ return {
+ "id": model_id,
+ "features": {"tool_use": tool_use},
+ "is_gated": gated,
+ "available_on_current_plan": available,
+ }
+
+
+def _page(
+ page: object,
+ total_pages: object,
+ models: list[dict[str, object]],
+) -> dict[str, object]:
+ return {
+ "data": models,
+ "pagination": {
+ "current_page": page,
+ "total_pages": total_pages,
+ },
+ }
+
+
+def test_build_request_body_preserves_shared_chat_contract(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ request = _request(
+ 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 = featherless_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["model"] == _MODEL
+ assert body["max_tokens"] == ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+ assert body["messages"][0] == {"role": "system", "content": "Be concise."}
+ assert body["messages"][1]["content"] == [
+ {"type": "text", "text": "Inspect this image."},
+ {
+ "type": "image_url",
+ "image_url": {"url": "data:image/png;base64,aW1hZ2U="},
+ },
+ ]
+ assert body["tools"][0]["function"]["name"] == "inspect_image"
+
+
+ ("reasoning", "enabled"),
+ [(REASONING_OFF, False), (REASONING_ON, True)],
+)
+def test_build_request_body_encodes_documented_thinking_control(
+ featherless_provider: OpenAIChatProvider,
+ reasoning: ReasoningPolicy,
+ enabled: bool,
+) -> None:
+ body = featherless_provider._build_request_body(
+ _request(),
+ reasoning=reasoning,
+ )
+
+ assert body["extra_body"] == {"chat_template_kwargs": {"enable_thinking": enabled}}
+
+
+def test_build_request_body_omits_thinking_control_for_provider_default(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ body = featherless_provider._build_request_body(
+ _request(),
+ reasoning=ReasoningPolicy.provider_default(),
+ )
+
+ assert "extra_body" not in body
+
+
+ "field",
+ ["reasoning", "reasoning_effort", "thinking", "enable_thinking"],
+)
+def test_build_request_body_rejects_caller_reasoning_override(
+ featherless_provider: OpenAIChatProvider,
+ field: str,
+) -> None:
+ request = _request(extra_body={field: "caller-owned"})
+
+ with pytest.raises(InvalidRequestError, match="must not override reasoning"):
+ featherless_provider._build_request_body(request, reasoning=REASONING_ON)
+
+
+def test_build_request_body_replays_reasoning_and_tool_history(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ request = _request(
+ messages=[
+ {"role": "user", "content": "Inspect the file."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "Read it first."},
+ {"type": "text", "text": "I will inspect it."},
+ {
+ "type": "tool_use",
+ "id": "toolu_1",
+ "name": "read_file",
+ "input": {"path": "example.py"},
+ },
+ ],
+ },
+ {
+ "role": "user",
+ "content": [
+ {
+ "type": "tool_result",
+ "tool_use_id": "toolu_1",
+ "content": "print('hello')",
+ }
+ ],
+ },
+ ]
+ )
+
+ body = featherless_provider._build_request_body(
+ request,
+ reasoning=reasoning_for(request),
+ )
+
+ assert body["messages"][1] == {
+ "role": "assistant",
+ "content": "I will inspect it.",
+ "reasoning_content": "Read it first.",
+ "tool_calls": [
+ {
+ "id": "toolu_1",
+ "type": "function",
+ "function": {
+ "name": "read_file",
+ "arguments": '{"path": "example.py"}',
+ },
+ }
+ ],
+ }
+ assert body["messages"][2] == {
+ "role": "tool",
+ "tool_call_id": "toolu_1",
+ "content": "print('hello')",
+ }
+
+
+async def test_catalog_fetches_all_pages_filters_strictly_and_deduplicates_overlap(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ featherless_provider._client.get = AsyncMock(
+ side_effect=[
+ _page(
+ 1,
+ 2,
+ [
+ _catalog_model(),
+ _catalog_model("gated", gated=True),
+ _catalog_model("unavailable", available=False),
+ ],
+ ),
+ _page(
+ 2,
+ 2,
+ [
+ _catalog_model(),
+ _catalog_model("plain-agent"),
+ _catalog_model("no-tools", tool_use=False),
+ ],
+ ),
+ ]
+ )
+
+ model_infos = await featherless_provider.list_model_infos()
+
+ assert model_infos == frozenset(
+ {
+ ProviderModelInfo(_MODEL),
+ ProviderModelInfo("plain-agent"),
+ }
+ )
+ assert featherless_provider._client.get.await_count == 2
+ for index, call in enumerate(
+ featherless_provider._client.get.await_args_list,
+ start=1,
+ ):
+ assert call.args == ("/models",)
+ assert call.kwargs["cast_to"] is object
+ assert call.kwargs["options"]["params"] == {
+ "capabilities": "chat,tool-use",
+ "available_on_current_plan": "true",
+ "status": "active",
+ "per_page": "1000",
+ "page": str(index),
+ }
+
+
+ ("model", "message"),
+ [
+ ({"id": _MODEL}, "features.tool_use as bool"),
+ (_catalog_model(tool_use=1), "features.tool_use as bool"),
+ (_catalog_model(gated="false"), "is_gated as bool"),
+ (_catalog_model(available=None), "available_on_current_plan as bool"),
+ (_catalog_model(""), "include id"),
+ ],
+)
+async def test_catalog_rejects_missing_or_wrong_typed_metadata_atomically(
+ featherless_provider: OpenAIChatProvider,
+ model: dict[str, object],
+ message: str,
+) -> None:
+ featherless_provider._client.get = AsyncMock(return_value=_page(1, 1, [model]))
+
+ with pytest.raises(ModelListResponseError, match=message):
+ await featherless_provider.list_model_infos()
+
+
+async def test_catalog_validates_overlapping_records_before_deduplicating(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ featherless_provider._client.get = AsyncMock(
+ side_effect=[
+ _page(1, 2, [_catalog_model()]),
+ _page(2, 2, [{"id": _MODEL}]),
+ ]
+ )
+
+ with pytest.raises(ModelListResponseError, match=r"features\.tool_use as bool"):
+ await featherless_provider.list_model_infos()
+
+
+ ("current_page", "total_pages", "message"),
+ [
+ (False, 1, "current_page to be an integer"),
+ (1, True, "total_pages to be an integer"),
+ (1, 0, "total_pages between 1 and 100"),
+ (1, 101, "total_pages between 1 and 100"),
+ ],
+)
+async def test_catalog_rejects_invalid_pagination_metadata(
+ featherless_provider: OpenAIChatProvider,
+ current_page: object,
+ total_pages: object,
+ message: str,
+) -> None:
+ featherless_provider._client.get = AsyncMock(
+ return_value=_page(current_page, total_pages, [_catalog_model()])
+ )
+
+ with pytest.raises(ModelListResponseError, match=message):
+ await featherless_provider.list_model_infos()
+
+
+ ("second_page", "message"),
+ [
+ (_page(1, 2, [_catalog_model("second")]), "current_page to be 2"),
+ (_page(2, 3, [_catalog_model("second")]), "total_pages to remain 2"),
+ ],
+)
+async def test_catalog_rejects_inconsistent_later_page_metadata(
+ featherless_provider: OpenAIChatProvider,
+ second_page: dict[str, object],
+ message: str,
+) -> None:
+ featherless_provider._client.get = AsyncMock(
+ side_effect=[
+ _page(1, 2, [_catalog_model()]),
+ second_page,
+ ]
+ )
+
+ with pytest.raises(ModelListResponseError, match=message):
+ await featherless_provider.list_model_infos()
+
+
+async def test_later_page_failure_cannot_return_a_partial_catalog(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ featherless_provider._client.get = AsyncMock(
+ side_effect=[
+ _page(1, 2, [_catalog_model()]),
+ RuntimeError("page two failed"),
+ ]
+ )
+
+ with pytest.raises(RuntimeError, match="page two failed"):
+ await featherless_provider._fetch_models_payload()
+
+
+async def test_catalog_uses_documented_url_query_and_bearer_auth(
+ featherless_provider: OpenAIChatProvider,
+) -> None:
+ requests: list[httpx.Request] = []
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ requests.append(request)
+ page = int(request.url.params["page"])
+ return httpx.Response(
+ 200,
+ json=_page(
+ page,
+ 2,
+ [_catalog_model(_MODEL if page == 1 else "second-agent")],
+ ),
+ )
+
+ await featherless_provider._client.close()
+ featherless_provider._client = AsyncOpenAI(
+ api_key="wire-featherless-key",
+ base_url=FEATHERLESS_DEFAULT_BASE,
+ max_retries=0,
+ http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+ )
+ try:
+ model_infos = await featherless_provider.list_model_infos()
+ finally:
+ await featherless_provider.cleanup()
+
+ assert model_infos == frozenset(
+ {ProviderModelInfo(_MODEL), ProviderModelInfo("second-agent")}
+ )
+ assert len(requests) == 2
+ assert [request.url.params["page"] for request in requests] == ["1", "2"]
+ for request in requests:
+ assert str(request.url.copy_remove_param("page")).startswith(
+ "https://api.featherless.ai/v1/models?"
+ )
+ assert request.url.params["capabilities"] == "chat,tool-use"
+ assert request.url.params["available_on_current_plan"] == "true"
+ assert request.url.params["status"] == "active"
+ assert request.url.params["per_page"] == "1000"
+ assert "gated" not in request.url.params
+ assert request.headers["authorization"] == "Bearer wire-featherless-key"
diff --git a/tests/providers/test_openai_model_listing_filters.py b/tests/providers/test_openai_model_listing_filters.py
index 18f1931b..aef12129 100644
--- a/tests/providers/test_openai_model_listing_filters.py
+++ b/tests/providers/test_openai_model_listing_filters.py
@@ -68,3 +68,21 @@ def test_required_path_values_reject_an_empty_included_set() -> None:
provider_name="TEST",
required_path_values=((("type",), ("chat",)),),
)
+
+
+def test_duplicate_model_ids_preserve_first_validated_capability() -> None:
+ model_infos = extract_openai_model_infos(
+ {
+ "data": [
+ {"id": "overlap", "features": ["reasoning"]},
+ {"id": "overlap", "features": ["non-reasoning"]},
+ ]
+ },
+ provider_name="TEST",
+ tags_field="features",
+ non_thinking_tag="non-reasoning",
+ )
+
+ assert model_infos == frozenset(
+ {ProviderModelInfo("overlap", supports_thinking=True)}
+ )
diff --git a/tests/providers/test_provider_runtime.py b/tests/providers/test_provider_runtime.py
index 11b3b75e..b3087af9 100644
--- a/tests/providers/test_provider_runtime.py
+++ b/tests/providers/test_provider_runtime.py
@@ -16,6 +16,7 @@ from free_claude_code.config.provider_catalog import (
CHUTES_DEFAULT_BASE,
COHERE_DEFAULT_BASE,
DEEPINFRA_DEFAULT_BASE,
+ FEATHERLESS_DEFAULT_BASE,
GITHUB_MODELS_DEFAULT_BASE,
HUGGINGFACE_DEFAULT_BASE,
KIMI_CODE_DEFAULT_BASE,
@@ -76,6 +77,7 @@ def _make_settings(**overrides):
mock.siliconflow_api_key = "test_siliconflow_key"
mock.nebius_api_key = "test_nebius_key"
mock.chutes_api_key = "test_chutes_key"
+ mock.featherless_api_key = "test_featherless_key"
mock.mistral_api_key = "test_mistral_key"
mock.codestral_api_key = "test_codestral_key"
mock.deepseek_api_key = "test_deepseek_key"
@@ -150,6 +152,7 @@ def _make_settings(**overrides):
mock.siliconflow_proxy = ""
mock.nebius_proxy = ""
mock.chutes_proxy = ""
+ mock.featherless_proxy = ""
mock.azure_openai_proxy = ""
mock.provider_rate_limit = 40
mock.provider_rate_window = 60
@@ -361,6 +364,27 @@ def test_chutes_provider_config_uses_key_base_and_proxy() -> None:
assert isinstance(provider, OpenAIChatProvider)
+def test_featherless_provider_config_uses_key_base_and_proxy() -> None:
+ descriptor = PROVIDER_CATALOG["featherless"]
+ settings = _make_settings(
+ featherless_api_key="featherless-token",
+ featherless_proxy="http://proxy.test:8080",
+ )
+
+ config = build_provider_config(descriptor, settings)
+ with patch("free_claude_code.providers.openai_chat.provider.AsyncOpenAI"):
+ provider = create_provider("featherless", settings)
+
+ assert descriptor.display_name == "Featherless AI"
+ assert descriptor.credential_env == "FEATHERLESS_API_KEY"
+ assert descriptor.credential_url == "https://featherless.ai/account/api-keys"
+ assert descriptor.base_url_attr is None
+ assert config.api_key == "featherless-token"
+ assert config.base_url == FEATHERLESS_DEFAULT_BASE
+ assert config.proxy == "http://proxy.test:8080"
+ assert isinstance(provider, OpenAIChatProvider)
+
+
def test_agnes_provider_config_uses_key_base_and_proxy() -> None:
descriptor = PROVIDER_CATALOG["agnes"]
settings = _make_settings(
@@ -699,6 +723,7 @@ def test_create_provider_instantiates_each_builtin():
"siliconflow": OpenAIChatProvider,
"nebius": OpenAIChatProvider,
"chutes": OpenAIChatProvider,
+ "featherless": OpenAIChatProvider,
"azure_openai": OpenAIChatProvider,
"open_router": OpenRouterProvider,
"mistral": MistralProvider,
diff --git a/uv.lock b/uv.lock
index de37e004..7add6815 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.29.0"
+version = "4.30.0"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },