devcopilot 0.2.0__py3-none-any.whl

providers/error_mapping.py

@@ -0,0 +1,309 @@
+"""Provider-specific exception mapping and user-visible diagnostics."""
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+import openai
+
+from config.constants import PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
+from core.anthropic import get_user_facing_error_message
+from providers.exceptions import (
+    APIError,
+    AuthenticationError,
+    InvalidRequestError,
+    OverloadedError,
+    RateLimitError,
+)
+from providers.rate_limit import GlobalRateLimiter
+
+_BODY_ATTR = "_fcc_provider_error_body"
+_BODY_TRUNCATED_ATTR = "_fcc_provider_error_body_truncated"
+
+
+@dataclass(frozen=True)
+class ProviderErrorDetail:
+    """Structured upstream error detail surfaced directly to users."""
+
+    status_code: int | None = None
+    body_text: str | None = None
+    exception_text: str | None = None
+    error_type_hint: str | None = None
+    body_truncated: bool = False
+
+
+def attach_provider_error_body(
+    exc: Exception, body: bytes | str, *, truncated: bool = False
+) -> None:
+    """Attach a streamed HTTP error body to an exception for later formatting."""
+    setattr(exc, _BODY_ATTR, body)
+    setattr(exc, _BODY_TRUNCATED_ATTR, truncated)
+
+
+def _status_code_from_exception(exc: Exception) -> int | None:
+    status = getattr(exc, "status_code", None)
+    if isinstance(status, int):
+        return status
+    response = getattr(exc, "response", None)
+    response_status = getattr(response, "status_code", None)
+    if isinstance(response_status, int):
+        return response_status
+    return None
+
+
+def _body_from_response(exc: Exception) -> Any:
+    response = getattr(exc, "response", None)
+    if response is None:
+        return None
+    try:
+        return response.json()
+    except ValueError, RuntimeError:
+        pass
+    try:
+        return response.text
+    except httpx.ResponseNotRead, RuntimeError:
+        return None
+
+
+def _normalize_body_text(body: Any) -> str | None:
+    if body is None:
+        return None
+    if isinstance(body, bytes):
+        text = body.decode("utf-8", errors="replace")
+    elif isinstance(body, str):
+        text = body
+    else:
+        try:
+            return json.dumps(body, ensure_ascii=False, separators=(",", ":"))
+        except TypeError:
+            text = str(body)
+    stripped = text.strip()
+    if not stripped:
+        return None
+    try:
+        parsed = json.loads(stripped)
+    except ValueError:
+        return stripped
+    return json.dumps(parsed, ensure_ascii=False, separators=(",", ":"))
+
+
+def _cap_text_bytes(text: str, max_bytes: int) -> tuple[str, bool]:
+    encoded = text.encode("utf-8", errors="replace")
+    if len(encoded) <= max_bytes:
+        return text, False
+    capped = encoded[:max_bytes].decode("utf-8", errors="replace")
+    return f"{capped}\n... [truncated after {max_bytes} bytes]", True
+
+
+def _error_type_hint_from_body(body: Any, body_text: str | None) -> str | None:
+    parsed = body
+    if isinstance(parsed, bytes):
+        text = parsed.decode("utf-8", errors="replace")
+        try:
+            parsed = json.loads(text)
+        except ValueError:
+            parsed = None
+    elif isinstance(parsed, str):
+        try:
+            parsed = json.loads(parsed)
+        except ValueError:
+            parsed = None
+    if isinstance(parsed, dict):
+        error = parsed.get("error")
+        if isinstance(error, dict):
+            for key in ("type", "code"):
+                value = error.get(key)
+                if isinstance(value, str) and value.strip():
+                    return value.strip()
+        for key in ("type", "code"):
+            value = parsed.get(key)
+            if isinstance(value, str) and value.strip():
+                return value.strip()
+    if (
+        body_text
+        and "model" in body_text.lower()
+        and "unsupported" in body_text.lower()
+    ):
+        return "upstream_model_error"
+    return None
+
+
+def extract_provider_error_detail(exc: Exception) -> ProviderErrorDetail:
+    """Extract copyable upstream status/body/exception detail from provider errors."""
+    raw_body = getattr(exc, _BODY_ATTR, None)
+    raw_body_truncated = bool(getattr(exc, _BODY_TRUNCATED_ATTR, False))
+    if raw_body is None:
+        raw_body = getattr(exc, "body", None)
+    if raw_body is None:
+        raw_body = _body_from_response(exc)
+
+    body_text = _normalize_body_text(raw_body)
+    display_truncated = raw_body_truncated
+    if body_text is not None:
+        body_text, cap_truncated = _cap_text_bytes(
+            body_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
+        )
+        display_truncated = display_truncated or cap_truncated
+
+    exception_text = str(exc).strip() or None
+    if exception_text is not None:
+        exception_text, _ = _cap_text_bytes(
+            exception_text, PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES
+        )
+
+    return ProviderErrorDetail(
+        status_code=_status_code_from_exception(exc),
+        body_text=body_text,
+        exception_text=exception_text,
+        error_type_hint=_error_type_hint_from_body(raw_body, body_text),
+        body_truncated=display_truncated,
+    )
+
+
+def _provider_error_category(mapped: Exception) -> str | None:
+    error_type = getattr(mapped, "error_type", None)
+    if isinstance(error_type, str) and error_type.strip():
+        return error_type.strip()
+    return None
+
+
+def _append_request_id_lines(lines: list[str], request_id: str | None) -> None:
+    if request_id:
+        lines.extend(("", f"Request ID: {request_id}"))
+
+
+def format_provider_error_message(
+    mapped: Exception,
+    detail: ProviderErrorDetail,
+    *,
+    provider_name: str,
+    read_timeout_s: float | None,
+    request_id: str | None = None,
+) -> str:
+    """Return a copyable user-facing provider error including upstream detail."""
+    stable_message = get_user_facing_error_message(
+        mapped, read_timeout_s=read_timeout_s
+    )
+    has_upstream_detail = detail.status_code is not None or detail.body_text is not None
+    if not has_upstream_detail:
+        lines = [stable_message]
+        if detail.exception_text and detail.exception_text != stable_message:
+            lines.extend(("", "Provider exception:", detail.exception_text))
+        _append_request_id_lines(lines, request_id)
+        return "\n".join(lines)
+
+    if detail.status_code == 405:
+        lines = [
+            f"Upstream provider {provider_name} rejected the request method "
+            "or endpoint (HTTP 405)."
+        ]
+    elif detail.status_code is not None:
+        lines = [
+            f"Upstream provider {provider_name} returned HTTP {detail.status_code}."
+        ]
+    else:
+        lines = [f"Upstream provider {provider_name} returned an error."]
+
+    category = detail.error_type_hint or _provider_error_category(mapped)
+    if category:
+        lines.append(f"Category: {category}")
+    if stable_message and stable_message != lines[0]:
+        lines.append(f"Mapped message: {stable_message}")
+
+    lines.extend(("", "Upstream error:"))
+    if detail.body_text:
+        lines.append(detail.body_text)
+    else:
+        lines.append("(empty upstream error body)")
+    if detail.body_truncated and (
+        detail.body_text is None
+        or f"truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes"
+        not in detail.body_text
+    ):
+        lines.append(
+            f"... [truncated after {PROVIDER_ERROR_BODY_DISPLAY_CAP_BYTES} bytes]"
+        )
+
+    _append_request_id_lines(lines, request_id)
+    return "\n".join(lines)
+
+
+def user_visible_message_for_mapped_provider_error(
+    mapped: Exception,
+    *,
+    provider_name: str,
+    read_timeout_s: float | None,
+    detail: ProviderErrorDetail | None = None,
+    request_id: str | None = None,
+) -> str:
+    """Return the user-visible string after :func:`map_error` (405 + mapped types)."""
+    if detail is not None:
+        return format_provider_error_message(
+            mapped,
+            detail,
+            provider_name=provider_name,
+            read_timeout_s=read_timeout_s,
+            request_id=request_id,
+        )
+    if getattr(mapped, "status_code", None) == 405:
+        return (
+            f"Upstream provider {provider_name} rejected the request method "
+            "or endpoint (HTTP 405)."
+        )
+    return get_user_facing_error_message(mapped, read_timeout_s=read_timeout_s)
+
+
+def map_error(
+    e: Exception, *, rate_limiter: GlobalRateLimiter | None = None
+) -> Exception:
+    """Map OpenAI or HTTPX exception to specific ProviderError.
+
+    Streaming transports should pass their scoped limiter (``self._global_rate_limiter``)
+    so reactive 429 handling applies to the correct provider. Tests may omit
+    ``rate_limiter`` to use the process-wide singleton.
+    """
+    message = get_user_facing_error_message(e)
+    limiter = rate_limiter or GlobalRateLimiter.get_instance()
+
+    if isinstance(e, openai.AuthenticationError):
+        return AuthenticationError(message, raw_error=str(e))
+    if isinstance(e, openai.RateLimitError):
+        limiter.set_blocked(60)
+        return RateLimitError(message, raw_error=str(e))
+    if isinstance(e, openai.BadRequestError):
+        return InvalidRequestError(message, raw_error=str(e))
+    if isinstance(e, openai.InternalServerError):
+        raw_message = str(e)
+        sdk_status = getattr(e, "status_code", None)
+        if "overloaded" in raw_message.lower() or "capacity" in raw_message.lower():
+            return OverloadedError(message, raw_error=raw_message)
+        if isinstance(sdk_status, int) and 500 <= sdk_status <= 599:
+            stable = APIError("_", status_code=sdk_status)
+            return APIError(
+                get_user_facing_error_message(stable),
+                status_code=sdk_status,
+                raw_error=str(e),
+            )
+        return APIError(message, status_code=500, raw_error=str(e))
+    if isinstance(e, openai.APIError):
+        return APIError(
+            message, status_code=getattr(e, "status_code", 500), raw_error=str(e)
+        )
+
+    if isinstance(e, httpx.HTTPStatusError):
+        status = e.response.status_code
+        if status in (401, 403):
+            return AuthenticationError(message, raw_error=str(e))
+        if status == 429:
+            limiter.set_blocked(60)
+            return RateLimitError(message, raw_error=str(e))
+        if status == 400:
+            return InvalidRequestError(message, raw_error=str(e))
+        if status >= 500:
+            if status in (502, 503, 504):
+                return OverloadedError(message, raw_error=str(e))
+            return APIError(message, status_code=status, raw_error=str(e))
+        return APIError(message, status_code=status, raw_error=str(e))
+
+    return e

providers/exceptions.py

@@ -0,0 +1,113 @@
+"""Unified exception hierarchy for providers."""
+
+from typing import Any
+
+
+class ProviderError(Exception):
+    """Base exception for all provider errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 500,
+        error_type: str = "api_error",
+        raw_error: Any = None,
+    ):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_type = error_type
+        self.raw_error = raw_error
+
+    def to_anthropic_format(self) -> dict:
+        """Convert to Anthropic-compatible error response."""
+        return {
+            "type": "error",
+            "error": {
+                "type": self.error_type,
+                "message": self.message,
+            },
+        }
+
+
+class AuthenticationError(ProviderError):
+    """Raised when API key is invalid or missing."""
+
+    def __init__(self, message: str, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=401,
+            error_type="authentication_error",
+            raw_error=raw_error,
+        )
+
+
+class InvalidRequestError(ProviderError):
+    """Raised when the request parameters are invalid."""
+
+    def __init__(self, message: str, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=400,
+            error_type="invalid_request_error",
+            raw_error=raw_error,
+        )
+
+
+class RateLimitError(ProviderError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=429,
+            error_type="rate_limit_error",
+            raw_error=raw_error,
+        )
+
+
+class OverloadedError(ProviderError):
+    """Raised when the provider is overloaded."""
+
+    def __init__(self, message: str, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=529,
+            error_type="overloaded_error",
+            raw_error=raw_error,
+        )
+
+
+class APIError(ProviderError):
+    """Raised when the provider returns a generic API error."""
+
+    def __init__(self, message: str, status_code: int = 500, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_type="api_error",
+            raw_error=raw_error,
+        )
+
+
+class UnknownProviderTypeError(InvalidRequestError):
+    """Raised when ``provider_id`` is not registered in the provider map."""
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+
+
+class ServiceUnavailableError(ProviderError):
+    """Raised when the server is not ready (e.g. app lifespan did not wire state)."""
+
+    def __init__(self, message: str, raw_error: Any = None):
+        super().__init__(
+            message,
+            status_code=503,
+            error_type="api_error",
+            raw_error=raw_error,
+        )
+
+
+class ModelListResponseError(ServiceUnavailableError):
+    """Raised when a provider model-list response cannot be parsed safely."""

providers/fireworks/__init__.py

@@ -0,0 +1,5 @@
+"""Fireworks AI provider exports."""
+
+from .client import FIREWORKS_BASE_URL, FireworksProvider
+
+__all__ = ["FIREWORKS_BASE_URL", "FireworksProvider"]

providers/fireworks/client.py

@@ -0,0 +1,45 @@
+"""Fireworks AI provider using native Anthropic-compatible Messages."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.transports.anthropic_messages import AnthropicMessagesTransport
+
+from .request import build_request_body
+
+FIREWORKS_BASE_URL = "https://api.fireworks.ai/inference/v1"
+_ANTHROPIC_VERSION = "2023-06-01"
+
+
+class FireworksProvider(AnthropicMessagesTransport):
+    """Fireworks AI using Anthropic-compatible Messages."""
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(
+            config,
+            provider_name="FIREWORKS",
+            default_base_url=FIREWORKS_BASE_URL,
+        )
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        if thinking_enabled is None:
+            thinking_enabled = self._is_thinking_enabled(request)
+        return build_request_body(
+            request,
+            thinking_enabled=thinking_enabled,
+        )
+
+    def _request_headers(self) -> dict[str, str]:
+        return {
+            "Accept": "text/event-stream",
+            "Authorization": f"Bearer {self._api_key}",
+            "Content-Type": "application/json",
+            "anthropic-version": _ANTHROPIC_VERSION,
+        }
+
+    def _model_list_headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}

providers/fireworks/request.py

@@ -0,0 +1,48 @@
+"""Native Anthropic Messages request builder for Fireworks AI."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loguru import logger
+
+from config.constants import ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS
+from core.anthropic.native_messages_request import (
+    OpenRouterExtraBodyError,
+    build_base_native_anthropic_request_body,
+    validate_openrouter_extra_body,
+)
+from providers.exceptions import InvalidRequestError
+
+
+def build_request_body(request_data: Any, *, thinking_enabled: bool) -> dict:
+    """Build JSON for Fireworks Anthropic-compat ``POST …/messages``."""
+    logger.debug(
+        "FIREWORKS_REQUEST: native build model={} msgs={}",
+        getattr(request_data, "model", "?"),
+        len(getattr(request_data, "messages", [])),
+    )
+
+    body = build_base_native_anthropic_request_body(
+        request_data,
+        default_max_tokens=ANTHROPIC_DEFAULT_MAX_OUTPUT_TOKENS,
+        thinking_enabled=thinking_enabled,
+    )
+
+    extra = getattr(request_data, "extra_body", None)
+    if isinstance(extra, dict) and extra:
+        try:
+            validate_openrouter_extra_body(extra)
+        except OpenRouterExtraBodyError as exc:
+            raise InvalidRequestError(str(exc)) from exc
+        body.update(extra)
+
+    body["stream"] = True
+
+    logger.debug(
+        "FIREWORKS_REQUEST: build done model={} msgs={} tools={}",
+        body.get("model"),
+        len(body.get("messages", [])),
+        len(body.get("tools", [])),
+    )
+    return body

providers/gemini/__init__.py

@@ -0,0 +1,7 @@
+"""Google AI Studio Gemini (OpenAI-compat) adapter."""
+
+from providers.defaults import GEMINI_DEFAULT_BASE
+
+from .client import GeminiProvider
+
+__all__ = ["GEMINI_DEFAULT_BASE", "GeminiProvider"]

providers/gemini/client.py

@@ -0,0 +1,49 @@
+"""Google AI Studio Gemini provider (OpenAI-compatible chat completions)."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+from providers.base import ProviderConfig
+from providers.defaults import GEMINI_DEFAULT_BASE
+from providers.transports.openai_chat import OpenAIChatTransport
+
+from .request import build_request_body
+
+_MAX_TOOL_CALL_EXTRA_CONTENT_CACHE = 4096
+
+
+class GeminiProvider(OpenAIChatTransport):
+    """Gemini API using ``https://generativelanguage.googleapis.com/v1beta/openai/``."""
+
+    def __init__(self, config: ProviderConfig):
+        super().__init__(
+            config,
+            provider_name="GEMINI",
+            base_url=config.base_url or GEMINI_DEFAULT_BASE,
+            api_key=config.api_key,
+        )
+        self._tool_call_extra_content_by_id: dict[str, dict[str, Any]] = {}
+
+    def _record_tool_call_extra_content(
+        self, tool_call_id: str, extra_content: dict[str, Any]
+    ) -> None:
+        if (
+            tool_call_id not in self._tool_call_extra_content_by_id
+            and len(self._tool_call_extra_content_by_id)
+            >= _MAX_TOOL_CALL_EXTRA_CONTENT_CACHE
+        ):
+            self._tool_call_extra_content_by_id.pop(
+                next(iter(self._tool_call_extra_content_by_id))
+            )
+        self._tool_call_extra_content_by_id[tool_call_id] = deepcopy(extra_content)
+
+    def _build_request_body(
+        self, request: Any, thinking_enabled: bool | None = None
+    ) -> dict:
+        return build_request_body(
+            request,
+            thinking_enabled=self._is_thinking_enabled(request, thinking_enabled),
+            tool_call_extra_content_by_id=self._tool_call_extra_content_by_id,
+        )