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
11.0 KB
Raw Blame
"""Groq chat-completions provider with per-model reasoning negotiation."""

import json
import re
from collections.abc import Iterator, Mapping
from dataclasses import dataclass
from typing import Any

import openai
from loguru import logger

from free_claude_code.core.anthropic import ReasoningReplayMode
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.json_types import JsonObject
from free_claude_code.core.reasoning import (
    ReasoningEffort,
    ReasoningPolicy,
)
from free_claude_code.providers.admission import ProviderAdmissionController
from free_claude_code.providers.base import ProviderConfig
from free_claude_code.providers.openai_chat import (
    NamedEffortReasoning,
    OpenAIChatBehavior,
    OpenAIChatProfile,
    OpenAIChatProvider,
    OpenAIChatRequestPolicy,
    OpenAIModelListing,
    validate_extra_body_does_not_override_reasoning_fields,
)

from .tpm import correct_tpm_completion_budget, token_limit_message

_GROQ_EFFORTS = (
    (ReasoningEffort.MINIMAL, "low"),
    (ReasoningEffort.LOW, "low"),
    (ReasoningEffort.MEDIUM, "medium"),
    (ReasoningEffort.HIGH, "high"),
    (ReasoningEffort.XHIGH, "high"),
    (ReasoningEffort.MAX, "high"),
)
_REQUEST_POLICY = OpenAIChatRequestPolicy(
    provider_name="GROQ",
    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",
    strip_message_names=True,
    unsupported_body_keys=frozenset({"logprobs", "logit_bias", "top_logprobs"}),
    normalize_n_to_one=True,
)
_PROFILE = OpenAIChatProfile(
    _REQUEST_POLICY,
    NamedEffortReasoning(
        _GROQ_EFFORTS,
        disabled_value="none",
        enabled_value="medium",
    ),
    model_listing=OpenAIModelListing(
        context_window_tokens_path=("context_window",),
        max_output_tokens_path=("max_completion_tokens",),
    ),
)

_REASONING_FIELD = "reasoning_effort"
_KNOWN_VALUES = frozenset({"none", "default", "low", "medium", "high"})
_FIELD_PATTERN = re.compile(r"(?<![a-z0-9_])reasoning_effort(?![a-z0-9_])", re.I)
_VALUE_PATTERN = re.compile(
    r"(?<![a-z0-9_])(none|default|low|medium|high)(?![a-z0-9_])",
    re.I,
)
_ALLOWED_MARKER = re.compile(
    r"(?:"
    r"(?:must|should|needs?\s+to)\s+be\s+one\s+of"
    r"|expected(?:\s+to\s+be)?\s+one\s+of"
    r"|(?:allowed|valid|accepted)\s+(?:values?|options?)"
    r")",
    re.I,
)
_CLAUSE_END = re.compile(r"(?:\r?\n|;|[.!?](?:\s|$))")
_UNSUPPORTED_PHRASE = re.compile(
    r"(?:"
    r"unsupported\s+(?:parameter|field)"
    r"|(?:parameter|field)(?:\s+\S+){0,3}\s+is\s+not\s+supported"
    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,
)


@dataclass(frozen=True, slots=True)
class _ErrorCandidate:
    text: str
    field_context: bool = False


class GroqChatBehavior(OpenAIChatBehavior):
    """Groq Chat adaptation without HTTP ownership."""

    def __init__(self) -> None:
        super().__init__(_PROFILE)
        self._model_reasoning_vocabularies: dict[str, frozenset[str]] = {}

    def failure_override(self, error: Exception) -> ExecutionFailure | None:
        if token_limit_message(error) is None:
            return None
        return ExecutionFailure(
            FailureKind.INVALID_REQUEST,
            400,
            "Groq rejected this request because it exceeds the account's token-rate "
            "allowance. Reduce the request's token budget or use a model/provider "
            "with a higher allowance.",
            False,
        )

    def finalize_chat_body(
        self,
        body: dict[str, Any],
        *,
        reasoning: ReasoningPolicy,
    ) -> dict[str, Any]:
        model = body.get("model")
        if not isinstance(model, str):
            return body
        accepted = self._model_reasoning_vocabularies.get(model)
        if accepted is None:
            return body
        return _rewrite_reasoning_effort(body, accepted) or body

    def reasoning_disable_rejected(self, error: Exception) -> bool:
        accepted = _parse_reasoning_vocabulary(error)
        return accepted is not None and "none" not in accepted

    def retry_request_body(
        self, error: Exception, body: dict[str, Any]
    ) -> dict[str, Any] | None:
        accepted = _parse_reasoning_vocabulary(error)
        model = body.get("model")
        if accepted is None or not isinstance(model, str):
            return None

        retry_body = _rewrite_reasoning_effort(body, accepted)
        if retry_body is None:
            return None

        self._model_reasoning_vocabularies[model] = accepted
        action = (
            "omitting reasoning_effort"
            if _REASONING_FIELD not in retry_body
            else "adjusting reasoning_effort"
        )
        logger.warning("GROQ_STREAM: {} after upstream rejection", action)
        return retry_body

    def retry_after_standard_corrections(
        self,
        error: Exception,
        body: JsonObject,
        used_retry_kinds: set[str],
    ) -> JsonObject | None:
        if "groq_tpm" in used_retry_kinds:
            return None

        correction = correct_tpm_completion_budget(error, body)
        if correction is None:
            return None
        used_retry_kinds.add("groq_tpm")
        logger.warning(
            "GROQ_STREAM: TPM limit={} requested={}; retrying "
            "max_completion_tokens {} -> {}",
            correction.limit,
            correction.requested,
            correction.previous_max_completion_tokens,
            correction.corrected_max_completion_tokens,
        )
        return correction.body


class GroqProvider(OpenAIChatProvider):
    """Groq API with model-agnostic reasoning-vocabulary learning."""

    def __init__(
        self, config: ProviderConfig, *, admission: ProviderAdmissionController
    ) -> None:
        super().__init__(config, behavior=GroqChatBehavior(), admission=admission)


def _parse_reasoning_vocabulary(error: Exception) -> frozenset[str] | None:
    """Return Groq's accepted known values, or an understood empty vocabulary."""
    if not _is_bad_request(error):
        return None

    candidates = _error_candidates(error)
    for candidate in candidates:
        for marker in _ALLOWED_MARKER.finditer(candidate.text):
            if not _marker_targets_reasoning(candidate, marker):
                continue
            tail = candidate.text[marker.end() : marker.end() + 512]
            clause = _CLAUSE_END.split(tail, maxsplit=1)[0]
            return frozenset(
                match.group(1).lower()
                for match in _VALUE_PATTERN.finditer(clause)
                if match.group(1).lower() in _KNOWN_VALUES
            )

    for candidate in candidates:
        for phrase in _UNSUPPORTED_PHRASE.finditer(candidate.text):
            if _marker_targets_reasoning(candidate, phrase):
                return frozenset()

    return None


def _rewrite_reasoning_effort(
    body: dict[str, Any], accepted: frozenset[str]
) -> dict[str, Any] | None:
    """Clone ``body`` with a compatible known effort, or omit the field."""
    current = body.get(_REASONING_FIELD)
    if not isinstance(current, str):
        return None

    normalized = current.lower()
    if normalized in accepted:
        return None

    rewritten = dict(body)
    if normalized in {"low", "medium", "high"} and "default" in accepted:
        rewritten[_REASONING_FIELD] = "default"
    else:
        rewritten.pop(_REASONING_FIELD, None)
    return rewritten


def _is_bad_request(error: Exception) -> bool:
    if isinstance(error, openai.BadRequestError):
        return True
    if getattr(error, "status_code", None) == 400:
        return True
    response = getattr(error, "response", None)
    return getattr(response, "status_code", None) == 400


def _error_candidates(error: Exception) -> tuple[_ErrorCandidate, ...]:
    body = getattr(error, "body", None)
    if body is not None:
        return _payload_error_candidates(body)

    response = getattr(error, "response", None)
    try:
        response_text = getattr(response, "text", None)
    except Exception:
        response_text = None
    if isinstance(response_text, str) and response_text.strip():
        return _payload_error_candidates(response_text)

    try:
        error_text = str(error)
    except Exception:
        error_text = ""
    return _payload_error_candidates(error_text)


def _payload_error_candidates(value: Any) -> tuple[_ErrorCandidate, ...]:
    if isinstance(value, str):
        parsed = _parse_json_container(value)
        if parsed is not None:
            value = parsed
    return _deduplicate_candidates(_body_error_candidates(value))


def _deduplicate_candidates(
    candidates: Iterator[_ErrorCandidate],
) -> tuple[_ErrorCandidate, ...]:
    result: list[_ErrorCandidate] = []
    positions: dict[str, int] = {}
    for candidate in candidates:
        text = candidate.text.strip()
        if not text:
            continue
        normalized = _ErrorCandidate(text, candidate.field_context)
        position = positions.get(text)
        if position is None:
            positions[text] = len(result)
            result.append(normalized)
        elif candidate.field_context and not result[position].field_context:
            result[position] = normalized
    return tuple(result)


def _parse_json_container(text: str) -> Mapping[Any, Any] | list[Any] | None:
    try:
        parsed = json.loads(text)
    except json.JSONDecodeError:
        return None
    return parsed if isinstance(parsed, (Mapping, list)) else None


def _body_error_candidates(value: Any) -> Iterator[_ErrorCandidate]:
    if isinstance(value, str):
        yield _ErrorCandidate(value)
        return

    if isinstance(value, Mapping):
        local_context = _mapping_names_reasoning_field(value)
        for key, child in value.items():
            if str(key).lower() in {"message", "detail"} and isinstance(child, str):
                yield _ErrorCandidate(child, local_context)
        for child in value.values():
            if isinstance(child, (Mapping, list, tuple)):
                yield from _body_error_candidates(child)
        return

    if isinstance(value, (list, tuple)):
        for child in value:
            yield from _body_error_candidates(child)


def _mapping_names_reasoning_field(value: Mapping[Any, Any]) -> bool:
    for key, parameter in value.items():
        if (
            str(key).lower() in {"param", "parameter"}
            and isinstance(parameter, str)
            and parameter.strip().lower() == _REASONING_FIELD
        ):
            return True
    return False


def _marker_targets_reasoning(
    candidate: _ErrorCandidate, marker: re.Match[str]
) -> bool:
    if candidate.field_context:
        return True
    for field in _FIELD_PATTERN.finditer(candidate.text):
        start = min(field.start(), marker.start())
        end = max(field.end(), marker.end())
        between = candidate.text[start:end]
        if len(between) <= 128 and _CLAUSE_END.search(between) is None:
            return True
    return False