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

Fix Groq reasoning compatibility and rank it third (#1373)

Ali Khokhare1c684feb5d3
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index 060be0ef..4b82aa87 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -658,7 +658,10 @@ recognized pre-stream 400 can teach the adapter the accepted known vocabulary
and trigger one request-body correction through the shared provider attempt
budget. Later requests apply the same pure rewrite proactively. Unknown values
are never echoed, unrelated errors retain their normal failure path, and no
-separate retry loop or persisted capability registry exists.
+separate retry loop or persisted capability registry exists. Groq rejects
+structured assistant reasoning fields in replayed Chat Completions history, so
+the same provider policy preserves prior reasoning as ordinary tagged assistant
+content; this replay rule is provider-wide and never selected by model name.
[providers/openai_codex/](src/free_claude_code/providers/openai_codex/) owns
ChatGPT subscription authentication and the Codex backend's OpenAI Responses
diff --git a/README.md b/README.md
index 15ede56f..11353274 100644
--- a/README.md
+++ b/README.md
@@ -153,9 +153,10 @@ fcc-codex exec "hello"
| Provider | Admin UI setting | Example `MODEL` |
| --- | --- | --- |
| [NVIDIA NIM](https://build.nvidia.com/settings/api-keys) | `NVIDIA_NIM_API_KEY` | `nvidia_nim/nvidia/nemotron-3-super-120b-a12b` |
+| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
+| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [OpenAI / ChatGPT](https://learn.chatgpt.com/docs/auth) | Connect ChatGPT in the Admin UI | `openai/<model-id>` |
| [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>` |
-| [OpenRouter](https://openrouter.ai/keys) | `OPENROUTER_API_KEY` | `open_router/openrouter/free` |
| [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` |
| [DeepSeek](https://platform.deepseek.com/api_keys) | `DEEPSEEK_API_KEY` | `deepseek/deepseek-chat` |
@@ -173,7 +174,6 @@ fcc-codex exec "hello"
| [Kimi Code](https://www.kimi.com/code/console) | `KIMI_CODE_API_KEY` | `kimi_code/k3` |
| [MiniMax](https://platform.minimax.io/user-center/basic-information/interface-key) | `MINIMAX_API_KEY` | `minimax/MiniMax-M3` |
| [Cerebras Inference](https://cloud.cerebras.ai/) | `CEREBRAS_API_KEY` | `cerebras/gpt-oss-120b` |
-| [Groq](https://console.groq.com/keys) | `GROQ_API_KEY` | `groq/llama-3.3-70b-versatile` |
| [SambaNova](https://cloud.sambanova.ai/apis) | `SAMBANOVA_API_KEY` | `sambanova/Meta-Llama-3.3-70B-Instruct` |
| [Kilo.ai](https://kilo.ai) | `KILO_API_KEY` | `kilo/kilo-auto/free` |
| [Fireworks AI](https://fireworks.ai/account/api-keys) | `FIREWORKS_API_KEY` | `fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct` |
diff --git a/pyproject.toml b/pyproject.toml
index 5e1b1528..be986994 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "4.17.7"
+version = "4.17.8"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/smoke/lib/claude_cli_matrix.py b/smoke/lib/claude_cli_matrix.py
index 3767372a..5704466f 100644
--- a/smoke/lib/claude_cli_matrix.py
+++ b/smoke/lib/claude_cli_matrix.py
@@ -13,6 +13,7 @@ from typing import Any
from free_claude_code.cli.claude_env import build_claude_proxy_env
from smoke.lib.child_process import run_captured_text
from smoke.lib.config import ProviderModel, SmokeConfig, redacted
+from smoke.lib.outcomes import is_upstream_unavailable_text
from smoke.lib.server import RunningServer
REGRESSION_CLASSIFICATIONS = frozenset({"harness_bug", "product_failure"})
@@ -21,26 +22,6 @@ _HTTP_REGRESSION_PATTERNS = (
r'POST /v1/messages[^"\n]* HTTP/1\.1" 4(?!01|03|04|08|09)\d\d',
r'POST /v1/messages[^"\n]* HTTP/1\.1" 5\d\d',
)
-_UPSTREAM_UNAVAILABLE_MARKERS = (
- "upstream_unavailable",
- "readtimeout",
- "connecterror",
- "connection refused",
- "timed out",
- "rate limit",
- "overloaded",
- "capacity",
- "upstream provider",
- "provider api request failed",
- "httpstatuserror",
-)
-_HTTP_429_PATTERNS = (
- r'HTTP/1\.[01]" 429\b',
- r"\bHTTP/1\.[01] 429\b",
- r"\bstatus_code=429\b",
- r"\bstatus[=:]\s*429\b",
- r"\b429 Too Many Requests\b",
-)
_MISSING_ENV_MARKERS = (
"api key",
"not logged in",
@@ -320,7 +301,7 @@ def classify_probe(
if cli_ok and marker_ok and tool_ok and agent_ok and task_ok and compact_ok:
return "passed", "passed"
- if _has_upstream_unavailable_text(combined):
+ if is_upstream_unavailable_text(combined):
return "failed", "upstream_unavailable"
if not _has_proxy_request(log_delta):
return "failed", "harness_bug"
@@ -748,15 +729,6 @@ def _agent_result_count(text: str) -> int:
return text.count("agentId:") + text.count('"agentId"') + text.count("'agentId'")
-def _has_upstream_unavailable_text(text: str) -> bool:
- lower = text.lower()
- if any(marker_text in lower for marker_text in _UPSTREAM_UNAVAILABLE_MARKERS):
- return True
- return any(
- re.search(pattern, text, flags=re.IGNORECASE) for pattern in _HTTP_429_PATTERNS
- )
-
-
def _request_count(log_delta: str) -> int:
access_log_count = log_delta.count("POST /v1/messages")
service_log_count = log_delta.count("API_REQUEST:")
diff --git a/smoke/lib/outcomes.py b/smoke/lib/outcomes.py
new file mode 100644
index 00000000..cdd88c2b
--- /dev/null
+++ b/smoke/lib/outcomes.py
@@ -0,0 +1,66 @@
+"""Pure smoke outcome classification shared by runners and reports."""
+
+import re
+
+_UPSTREAM_UNAVAILABLE_MARKERS = (
+ "upstream_unavailable",
+ "connection refused",
+ "connecterror",
+ "connect timeout",
+ "connecttimeout",
+ "proxyerror",
+ "readtimeout",
+ "remoteprotocolerror",
+ "server disconnected",
+ "service unavailable",
+ "temporary failure",
+ "timed out",
+ "not reachable",
+ "rate limit exceeded",
+ "rate limited",
+ "overloaded",
+ "at capacity",
+)
+_RETRYABLE_HTTP_STATUS_PATTERNS = (
+ r"\bhttp(?:/1\.[01])?[\"']?\s+(?:429|5\d{2})\b",
+ r"\bstatus(?:_code| code)?(?:[=:]\s*|\s+)(?:429|5\d{2})\b",
+ r"\berror code:\s*(?:429|5\d{2})\b",
+ r"\b(?:client|server) error [\"'](?:429|5\d{2})\b",
+ r"\b429 too many requests\b",
+)
+
+
+def is_upstream_unavailable_text(text: str) -> bool:
+ """Return whether text contains a concrete transient-upstream signal."""
+ normalized = text.lower()
+ if any(marker in normalized for marker in _UPSTREAM_UNAVAILABLE_MARKERS):
+ return True
+ return any(
+ re.search(pattern, text, flags=re.IGNORECASE)
+ for pattern in _RETRYABLE_HTTP_STATUS_PATTERNS
+ )
+
+
+def classify_outcome(*, nodeid: str, outcome: str, detail: str) -> str:
+ """Classify one smoke outcome for triage reports."""
+ if outcome == "passed":
+ return "passed"
+
+ text = f"{nodeid}\n{detail}"
+ normalized = text.lower()
+ if outcome == "skipped":
+ if "smoke target disabled" in normalized:
+ return "target_disabled"
+ if "missing_env" in normalized:
+ return "missing_env"
+ if is_upstream_unavailable_text(text):
+ return "upstream_unavailable"
+ return "missing_env"
+
+ if "harness_bug" in normalized:
+ return "harness_bug"
+ if "missing_env" in normalized:
+ return "missing_env"
+ if is_upstream_unavailable_text(text):
+ return "upstream_unavailable"
+ return "product_failure"
diff --git a/smoke/lib/report.py b/smoke/lib/report.py
index 25860b7f..2ac4ceba 100644
--- a/smoke/lib/report.py
+++ b/smoke/lib/report.py
@@ -5,6 +5,7 @@ import time
from dataclasses import asdict, dataclass
from .config import SmokeConfig, redacted
+from .outcomes import classify_outcome
@dataclass(slots=True)
@@ -58,48 +59,3 @@ class SmokeReport:
"outcomes": [asdict(outcome) for outcome in self.outcomes],
}
path.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
-
-
-def classify_outcome(*, nodeid: str, outcome: str, detail: str) -> str:
- """Classify smoke outcomes for triage reports."""
- if outcome == "passed":
- return "passed"
-
- text = f"{nodeid}\n{detail}".lower()
- if outcome == "skipped":
- if "smoke target disabled" in text:
- return "target_disabled"
- if "missing_env" in text:
- return "missing_env"
- if any(
- marker in text
- for marker in (
- "upstream_unavailable",
- "connection refused",
- "connecterror",
- "readtimeout",
- "timed out",
- "not reachable",
- )
- ):
- return "upstream_unavailable"
- return "missing_env"
-
- if "harness_bug" in text:
- return "harness_bug"
- if "missing_env" in text:
- return "missing_env"
- if any(
- marker in text
- for marker in (
- "upstream_unavailable",
- "connection refused",
- "connecterror",
- "readtimeout",
- "timed out",
- "not reachable",
- "upstream provider",
- )
- ):
- return "upstream_unavailable"
- return "product_failure"
diff --git a/smoke/lib/skips.py b/smoke/lib/skips.py
index e8407fac..88aa7ea6 100644
--- a/smoke/lib/skips.py
+++ b/smoke/lib/skips.py
@@ -4,23 +4,7 @@ import httpx
import pytest
from free_claude_code.core.anthropic.stream_contracts import SSEEvent, text_content
-
-UPSTREAM_UNAVAILABLE_MARKERS = (
- "connection refused",
- "connecterror",
- "connect timeout",
- "readtimeout",
- "server disconnected",
- "service unavailable",
- "temporary failure",
- "timed out",
- "upstream provider",
-)
-
-
-def is_upstream_unavailable_text(text: str) -> bool:
- normalized = text.lower()
- return any(marker in normalized for marker in UPSTREAM_UNAVAILABLE_MARKERS)
+from smoke.lib.outcomes import is_upstream_unavailable_text
def skip_upstream_unavailable(reason: str) -> None:
diff --git a/src/free_claude_code/config/provider_catalog.py b/src/free_claude_code/config/provider_catalog.py
index b11f1fe3..7c38c1b3 100644
--- a/src/free_claude_code/config/provider_catalog.py
+++ b/src/free_claude_code/config/provider_catalog.py
@@ -96,6 +96,24 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=NVIDIA_NIM_DEFAULT_BASE,
proxy_attr="nvidia_nim_proxy",
),
+ "open_router": ProviderDescriptor(
+ provider_id="open_router",
+ display_name="OpenRouter",
+ credential_env="OPENROUTER_API_KEY",
+ credential_url="https://openrouter.ai/keys",
+ credential_attr="open_router_api_key",
+ default_base_url=OPENROUTER_DEFAULT_BASE,
+ proxy_attr="open_router_proxy",
+ ),
+ "groq": ProviderDescriptor(
+ provider_id="groq",
+ display_name="Groq",
+ credential_env="GROQ_API_KEY",
+ credential_url="https://console.groq.com/keys",
+ credential_attr="groq_api_key",
+ default_base_url=GROQ_DEFAULT_BASE,
+ proxy_attr="groq_proxy",
+ ),
"openai": ProviderDescriptor(
provider_id="openai",
display_name="OpenAI / ChatGPT",
@@ -116,15 +134,6 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
"azure_openai_base_url",
),
),
- "open_router": ProviderDescriptor(
- provider_id="open_router",
- display_name="OpenRouter",
- credential_env="OPENROUTER_API_KEY",
- credential_url="https://openrouter.ai/keys",
- credential_attr="open_router_api_key",
- default_base_url=OPENROUTER_DEFAULT_BASE,
- proxy_attr="open_router_proxy",
- ),
"gemini": ProviderDescriptor(
provider_id="gemini",
display_name="Gemini",
@@ -289,15 +298,6 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
default_base_url=CEREBRAS_DEFAULT_BASE,
proxy_attr="cerebras_proxy",
),
- "groq": ProviderDescriptor(
- provider_id="groq",
- display_name="Groq",
- credential_env="GROQ_API_KEY",
- credential_url="https://console.groq.com/keys",
- credential_attr="groq_api_key",
- default_base_url=GROQ_DEFAULT_BASE,
- proxy_attr="groq_proxy",
- ),
"sambanova": ProviderDescriptor(
provider_id="sambanova",
display_name="SambaNova",
@@ -375,7 +375,8 @@ PROVIDER_CATALOG: dict[str, ProviderDescriptor] = {
}
# Key order:
-# NVIDIA NIM first (README default), DeepSeek fourth, OpenCode gateways adjacent,
+# NVIDIA NIM, OpenRouter, and Groq lead the customer-facing ranking;
+# OpenCode gateways remain adjacent,
# Vercel / Hugging Face / Cohere / GitHub Models follow gateway-style remotes,
# then cloud gateways, Ollama Cloud, and local providers per project plan
# (github.com/cheahjs/free-llm-api-resources Free Providers TOC as rough guide
diff --git a/src/free_claude_code/providers/groq/client.py b/src/free_claude_code/providers/groq/client.py
index 77696e89..83aa9973 100644
--- a/src/free_claude_code/providers/groq/client.py
+++ b/src/free_claude_code/providers/groq/client.py
@@ -36,7 +36,7 @@ _GROQ_EFFORTS = (
)
_REQUEST_POLICY = OpenAIChatRequestPolicy(
provider_name="GROQ",
- reasoning_replay=ReasoningReplayMode.REASONING_CONTENT,
+ reasoning_replay=ReasoningReplayMode.THINK_TAGS,
include_extra_body=True,
extra_body_validator=validate_extra_body_does_not_override_reasoning_fields,
max_tokens_field="max_completion_tokens",
@@ -76,6 +76,7 @@ _UNSUPPORTED_PHRASE = re.compile(
r"|unknown\s+(?:parameter|field)"
r"|unrecognized\s+(?:parameter|field)"
r"|does\s+not\s+support"
+ r"|is\s+not\s+supported"
r")",
re.I,
)
diff --git a/tests/contracts/test_nvidia_nim_cli_matrix.py b/tests/contracts/test_nvidia_nim_cli_matrix.py
index 8030b0a5..d5d89a5b 100644
--- a/tests/contracts/test_nvidia_nim_cli_matrix.py
+++ b/tests/contracts/test_nvidia_nim_cli_matrix.py
@@ -386,7 +386,7 @@ def test_cli_matrix_agent_prompt_text_without_tool_evidence_does_not_pass(
assert outcome.token_evidence["agent_tool_count"] == 0
-def test_cli_matrix_structured_provider_error_is_upstream_unavailable(
+def test_cli_matrix_unclassified_provider_error_is_model_feature_failure(
tmp_path: Path,
) -> None:
run = ClaudeCliRun(
@@ -412,7 +412,7 @@ def test_cli_matrix_structured_provider_error_is_upstream_unavailable(
requires_tool_result=True,
)
- assert outcome.classification == "upstream_unavailable"
+ assert outcome.classification == "model_feature_failure"
assert outcome.request_count == 1
@@ -522,6 +522,33 @@ def test_cli_matrix_real_http_429_counts_as_upstream_unavailable(
assert outcome.classification == "upstream_unavailable"
+def test_cli_matrix_deterministic_provider_400_is_not_upstream_unavailable(
+ tmp_path: Path,
+) -> None:
+ run = ClaudeCliRun(
+ command=("claude", "-p", "x"),
+ returncode=1,
+ stdout="",
+ stderr=(
+ "Upstream provider GROQ returned HTTP 400: "
+ "property reasoning_content is unsupported"
+ ),
+ duration_s=0.1,
+ )
+ outcome = make_outcome(
+ model="openai/gpt-oss-120b",
+ full_model="groq/openai/gpt-oss-120b",
+ source="groq_cli_default",
+ feature="thinking",
+ marker="FCC_GROQ_THINK",
+ run=run,
+ log_delta="API_REQUEST: request_id=req_1 model=openai/gpt-oss-120b messages=2",
+ log_path=tmp_path / "server.log",
+ )
+
+ assert outcome.classification == "model_feature_failure"
+
+
def test_cli_matrix_default_command_uses_bare_mode() -> None:
command = _build_claude_cli_command(
claude_bin="claude",
diff --git a/tests/contracts/test_provider_catalog_order.py b/tests/contracts/test_provider_catalog_order.py
index 020d9604..1c80b1ca 100644
--- a/tests/contracts/test_provider_catalog_order.py
+++ b/tests/contracts/test_provider_catalog_order.py
@@ -7,9 +7,10 @@ from free_claude_code.config.provider_catalog import (
_EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"nvidia_nim",
+ "open_router",
+ "groq",
"openai",
"azure_openai",
- "open_router",
"gemini",
"vertex",
"deepseek",
@@ -28,7 +29,6 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
"kilo",
"minimax",
"cerebras",
- "groq",
"sambanova",
"fireworks",
"cloudflare",
@@ -41,7 +41,7 @@ _EXPECTED_PROVIDER_ORDER: tuple[str, ...] = (
def test_provider_catalog_key_order_matches_canonical_plan() -> None:
- """NIM first; OpenCode pair stays adjacent; gateways precede native remotes."""
+ """Lead with NIM, OpenRouter, and Groq while preserving catalog groupings."""
assert tuple(PROVIDER_CATALOG.keys()) == _EXPECTED_PROVIDER_ORDER
assert SUPPORTED_PROVIDER_IDS == _EXPECTED_PROVIDER_ORDER
diff --git a/tests/contracts/test_smoke_tiers.py b/tests/contracts/test_smoke_tiers.py
index 842b7f4f..c0ca1d4d 100644
--- a/tests/contracts/test_smoke_tiers.py
+++ b/tests/contracts/test_smoke_tiers.py
@@ -4,7 +4,7 @@ from pathlib import Path
import pytest
from free_claude_code.core.anthropic.stream_contracts import SSEEvent
-from smoke.lib.report import classify_outcome
+from smoke.lib.outcomes import classify_outcome, is_upstream_unavailable_text
from smoke.lib.report_summary import format_summary, summarize_reports
from smoke.lib.skips import skip_if_upstream_unavailable_events
@@ -77,3 +77,32 @@ def test_provider_error_text_stream_is_upstream_unavailable_skip() -> None:
skip_if_upstream_unavailable_events(events)
assert "upstream_unavailable" in str(excinfo.value)
+
+
+def test_deterministic_provider_error_is_not_upstream_unavailable() -> None:
+ detail = (
+ "Upstream provider GROQ returned HTTP 400: "
+ "property 'reasoning_content' is unsupported"
+ )
+
+ assert not is_upstream_unavailable_text(detail)
+ assert (
+ classify_outcome(nodeid="groq_reasoning", outcome="failed", detail=detail)
+ == "product_failure"
+ )
+
+
+ "detail",
+ (
+ "Upstream provider GROQ returned HTTP 429.",
+ "Upstream provider GROQ returned HTTP 529.",
+ "httpx.ConnectError: connection refused",
+ ),
+)
+def test_failed_transient_provider_errors_are_upstream_unavailable(detail: str) -> None:
+ assert is_upstream_unavailable_text(detail)
+ assert (
+ classify_outcome(nodeid="provider", outcome="failed", detail=detail)
+ == "upstream_unavailable"
+ )
diff --git a/tests/providers/test_groq.py b/tests/providers/test_groq.py
index f7528639..7d7e9b99 100644
--- a/tests/providers/test_groq.py
+++ b/tests/providers/test_groq.py
@@ -55,6 +55,56 @@ def test_build_request_body_basic(groq_provider):
assert "max_completion_tokens" in body
+def test_build_request_body_replays_reasoning_as_tagged_content(groq_provider):
+ request = make_request(
+ messages=[
+ {"role": "user", "content": "Inspect the file."},
+ {
+ "role": "assistant",
+ "content": [
+ {"type": "thinking", "thinking": "I need to read it first."},
+ {"type": "text", "text": "I will inspect the file."},
+ {
+ "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 = groq_provider._build_request_body(request)
+
+ assistant = next(
+ message for message in body["messages"] if message["role"] == "assistant"
+ )
+ assert assistant["content"] == (
+ "<think>\nI need to read it first.\n</think>\n\nI will inspect the file."
+ )
+ assert assistant["tool_calls"][0]["id"] == "toolu_1"
+ assert body["messages"][-1] == {
+ "role": "tool",
+ "tool_call_id": "toolu_1",
+ "content": "print('hello')",
+ }
+ assert all(
+ "reasoning_content" not in message and "reasoning" not in message
+ for message in body["messages"]
+ )
+
+
def test_build_request_body_global_disable_blocks_reasoning_mapping():
provider = GroqProvider(
ProviderConfig(
diff --git a/tests/providers/test_groq_reasoning.py b/tests/providers/test_groq_reasoning.py
index 54dab82f..6d0d6397 100644
--- a/tests/providers/test_groq_reasoning.py
+++ b/tests/providers/test_groq_reasoning.py
@@ -219,6 +219,7 @@ def test_parse_unknown_only_values_returns_understood_empty_vocabulary() -> None
"Unknown field `reasoning_effort`",
"Unrecognized parameter reasoning_effort",
"This model does not support reasoning_effort",
+ "`reasoning_effort` is not supported with this model",
],
)
def test_parse_explicit_unsupported_phrasings(message: str) -> None:
diff --git a/uv.lock b/uv.lock
index d95402d5..c300eeda 100644
--- a/uv.lock
+++ b/uv.lock
@@ -620,7 +620,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "4.17.7"
+version = "4.17.8"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },