minimalcode 1.5.2__py3-none-any.whl

minimalcode/provider/client.py

@@ -0,0 +1,243 @@
+"""Provider client shared by the Chat, Responses, Anthropic, and web mixins."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx2
+
+from ..config import provider_api_key
+from ..errors import ProviderError
+from ..httpclient import build_client, build_headers
+from .anthropic import AnthropicProtocolMixin
+from .chat import ChatProtocolMixin
+from .deepseek_web import CHAT_PATH, DeepSeekWebProtocolMixin
+from .responses import ResponsesProtocolMixin
+from .transport import TransportMixin
+from .types import ProviderReply
+
+
+class OpenAICompatibleProvider(
+    TransportMixin,
+    ChatProtocolMixin,
+    ResponsesProtocolMixin,
+    AnthropicProtocolMixin,
+    DeepSeekWebProtocolMixin,
+):
+    """HTTP client for OpenAI Chat/Responses and Anthropic Messages APIs."""
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        config: dict[str, Any],
+        model: str,
+        thinking: str,
+        transport: httpx2.BaseTransport | None = None,
+    ):
+        protocol = str(config.get("protocol", "openai_chat"))
+        # Unknown names are rejected rather than defaulted to Chat: the dialects
+        # need different payload keys and parsers, so a fallback would send a
+        # request the server rejects or we misparse.
+        if protocol not in {
+            "openai_chat",
+            "openai_responses",
+            "anthropic_messages",
+            "deepseek_web",
+        }:
+            raise ProviderError(
+                f"provider {name!r} uses unsupported protocol {protocol!r}; "
+                "expected 'openai_chat', 'openai_responses', "
+                "'anthropic_messages', or 'deepseek_web'"
+            )
+        self.name = name
+        self.config = config
+        self.model = model
+        self.thinking = thinking
+        self.protocol = protocol
+        # `_endpoint` appends the protocol path, so a trailing slash here would
+        # produce `//chat/completions` on servers that keep the path verbatim.
+        self.base_url = str(config.get("base_url", "")).rstrip("/")
+        if not self.base_url:
+            raise ProviderError(f"provider {name!r} requires base_url")
+        try:
+            parsed_base = urlsplit(self.base_url)
+            hostname = parsed_base.hostname
+            # Reading `.port` is deliberate: it raises on a malformed port here,
+            # at construction, instead of on every request that follows.
+            _ = parsed_base.port
+        except ValueError as exc:
+            raise ProviderError(f"provider {name!r} has an invalid base_url") from exc
+        if parsed_base.scheme not in {"http", "https"} or not hostname:
+            raise ProviderError(f"provider {name!r} has an invalid base_url")
+        try:
+            self.context_window = int(config.get("context_window", 128_000))
+            self.timeout_seconds = float(config.get("timeout_seconds", 120))
+            self.max_tokens = int(config.get("max_tokens", 8192))
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ProviderError(
+                f"provider {name!r} has invalid numeric settings"
+            ) from exc
+        if self.context_window < 1:
+            raise ProviderError(f"provider {name!r} requires a positive context_window")
+        if not math.isfinite(self.timeout_seconds) or self.timeout_seconds <= 0:
+            raise ProviderError(
+                f"provider {name!r} requires a positive timeout_seconds"
+            )
+        if self.max_tokens < 1:
+            raise ProviderError(f"provider {name!r} requires a positive max_tokens")
+        self.stream_enabled = bool(config.get("stream", True))
+        self.include_usage = bool(config.get("include_usage", True))
+        self.send_reasoning_effort = bool(config.get("send_reasoning_effort", False))
+        # Optional sink for retry notices; the agent points this at its activity
+        # stream so ten silent retries do not look like a hang.
+        self.notify: Callable[[str], None] | None = None
+
+        api_key = provider_api_key(config)
+        key_env = config.get("api_key_env")
+        if not api_key and key_env and config.get("require_api_key", True):
+            raise ProviderError(
+                f"provider {name!r} requires API key in environment variable {key_env}"
+            )
+
+        if protocol == "deepseek_web" and api_key:
+            # The browser sends `Bearer <token>`, but people paste the whole
+            # header value into DEEPSEEK_WEB_TOKEN, which produced
+            # `Authorization: Bearer Bearer <token>` and a 401.
+            stripped = api_key.strip()
+            if stripped.lower().startswith("bearer "):
+                stripped = stripped[len("bearer ") :].strip()
+            api_key = stripped or None
+        custom_headers = config.get("headers")
+        custom_names = (
+            {str(key).lower() for key in custom_headers}
+            if isinstance(custom_headers, dict)
+            else set()
+        )
+        headers = build_headers(api_key, custom_headers)
+        if protocol == "anthropic_messages":
+            # Anthropic authenticates with x-api-key; Authorization is accepted
+            # only by some gateways (DeepSeek accepts both). A caller-supplied
+            # auth header always wins over the one derived from api_key.
+            if (
+                api_key
+                and "x-api-key" not in custom_names
+                and "authorization" not in custom_names
+            ):
+                headers["x-api-key"] = api_key
+            if "authorization" not in custom_names:
+                headers.pop("Authorization", None)
+            if "anthropic-version" not in custom_names:
+                headers["anthropic-version"] = "2023-06-01"
+        self.headers = headers
+        self._client = build_client(
+            base_url=self.base_url,
+            headers=headers,
+            timeout=self.timeout_seconds,
+            transport=transport,
+            trust_env=config.get("trust_env"),
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and its connection pool."""
+        self._client.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
+    def _endpoint(self) -> str:
+        """Return the full protocol endpoint, accepting a full URL as-is.
+
+        A manually configured endpoint may carry a query string (Azure OpenAI's
+        ``api-version`` is the common case). Appending a path with plain string
+        concatenation would put it after the query, so path and query are
+        joined separately.
+        """
+        parsed = urlsplit(self.base_url)
+        path = parsed.path.rstrip("/")
+        if self.protocol == "deepseek_web":
+            new_path = path if path.endswith(CHAT_PATH) else f"{path}{CHAT_PATH}"
+            return urlunsplit(
+                (parsed.scheme, parsed.netloc, new_path, parsed.query, parsed.fragment)
+            )
+        if self.protocol == "anthropic_messages":
+            if path.endswith("/messages"):
+                new_path = path
+            elif path.endswith("/v1"):
+                new_path = f"{path}/messages"
+            else:
+                # DeepSeek's Anthropic base is https://api.deepseek.com/anthropic,
+                # so the version segment is appended unless the caller supplied it.
+                new_path = f"{path}/v1/messages"
+        elif self.protocol == "openai_responses":
+            new_path = path if path.endswith("/responses") else f"{path}/responses"
+        else:
+            new_path = (
+                path
+                if path.endswith("/chat/completions")
+                else f"{path}/chat/completions"
+            )
+        return urlunsplit(
+            (parsed.scheme, parsed.netloc, new_path, parsed.query, parsed.fragment)
+        )
+
+    def stream_chat(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        tools: list[dict[str, Any]] | None = None,
+        on_text: Callable[[str], None] | None = None,
+        on_thinking: Callable[[str], None] | None = None,
+    ) -> ProviderReply:
+        """Send one conversation turn using the configured wire protocol."""
+        if self.protocol == "deepseek_web":
+            return self._ds_web_turn(
+                messages, tools, on_text=on_text, on_thinking=on_thinking
+            )
+        if self.protocol == "anthropic_messages":
+            payload = self._anthropic_payload(messages, tools)
+            if self.stream_enabled:
+                return self._anthropic_stream_request(
+                    payload, on_text=on_text, on_thinking=on_thinking
+                )
+            return self._anthropic_regular_request(
+                payload, on_text=on_text, on_thinking=on_thinking
+            )
+        if self.protocol == "openai_responses":
+            payload = self._responses_payload(messages, tools)
+            if self.stream_enabled:
+                return self._responses_stream_request(
+                    payload, on_text=on_text, on_thinking=on_thinking
+                )
+            return self._responses_regular_request(
+                payload, on_text=on_text, on_thinking=on_thinking
+            )
+        payload = self._chat_payload(messages, tools)
+        if self.stream_enabled:
+            return self._chat_stream_request(
+                payload, on_text=on_text, on_thinking=on_thinking
+            )
+        return self._chat_regular_request(
+            payload, on_text=on_text, on_thinking=on_thinking
+        )
+
+    def complete(self, messages: list[dict[str, Any]]) -> ProviderReply:
+        """Request one plain-text completion and reject abnormal finish reasons."""
+        reply = self.stream_chat(messages, tools=None, on_text=None)
+        if reply.finish_reason not in {None, "stop", "completed"}:
+            raise ProviderError(
+                "provider stopped the summary with finish reason "
+                f"{reply.finish_reason!r}"
+            )
+        return reply
+
+    def complete_text(self, messages: list[dict[str, Any]]) -> str:
+        """Request a plain text completion, returning only its content."""
+        return self.complete(messages).content

minimalcode/provider/common.py

@@ -0,0 +1,176 @@
+"""Shared parsing helpers for OpenAI-compatible payloads and streams."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterable, Iterator
+from typing import Any
+
+import httpx2
+
+from ..errors import ProviderError
+
+
+def _is_json(text: str) -> bool:
+    """Return True when ``text`` is a complete JSON value."""
+    try:
+        json.loads(text)
+    except ValueError:
+        return False
+    return True
+
+
+def iter_sse_data(lines: Iterable[str]) -> Iterator[str]:
+    """Yield one payload per SSE event, joining multi-line `data:` fields.
+
+    The event stream format allows a single event's payload to be split across
+    several `data:` lines. Parsing one line at a time made `json.loads` fail on
+    every fragment and dropped the event silently, so a gateway that wraps long
+    JSON produced an empty reply with no error at all.
+
+    Two framings are in the wild: a blank line terminates the event, and some
+    gateways simply put one complete payload on each `data:` line with no blank
+    separator. A buffer that already parses as complete JSON is therefore
+    yielded before the next line is appended.
+    """
+    buffer = ""
+    for raw in lines:
+        line = strip_sse_bom(raw).rstrip("\r\n")
+        if not line.strip():
+            if buffer:
+                yield buffer
+                buffer = ""
+            continue
+        if not line.startswith("data:"):
+            # `event:`, `id:`, `retry:`, and comments carry no JSON payload.
+            continue
+        payload = line[5:].removeprefix(" ")
+        if not payload:
+            continue
+        if buffer and _is_json(buffer):
+            yield buffer
+            buffer = ""
+        buffer = f"{buffer}\n{payload}" if buffer else payload
+    if buffer:
+        yield buffer
+
+
+_USAGE_KEYS = frozenset(
+    {
+        "prompt_tokens",
+        "input_tokens",
+        "completion_tokens",
+        "output_tokens",
+        "total_tokens",
+    }
+)
+
+
+def normalize_usage(raw: Any) -> dict[str, int]:
+    """Normalize Chat and Responses usage objects to one stable key set."""
+    if not isinstance(raw, dict) or not any(key in raw for key in _USAGE_KEYS):
+        return {}
+    prompt = raw.get("prompt_tokens", raw.get("input_tokens", 0))
+    completion = raw.get("completion_tokens", raw.get("output_tokens", 0))
+    total = raw.get("total_tokens", 0)
+    prompt_details = raw.get("prompt_tokens_details") or raw.get("input_tokens_details")
+    completion_details = raw.get("completion_tokens_details") or raw.get(
+        "output_tokens_details"
+    )
+    cached = (
+        prompt_details.get("cached_tokens", 0)
+        if isinstance(prompt_details, dict)
+        else 0
+    )
+    reasoning = (
+        completion_details.get("reasoning_tokens", 0)
+        if isinstance(completion_details, dict)
+        else 0
+    )
+    try:
+        prompt_int = int(prompt or 0)
+        completion_int = int(completion or 0)
+        total_int = int(total or prompt_int + completion_int)
+        cached_int = int(cached or 0)
+        reasoning_int = int(reasoning or 0)
+    except (TypeError, ValueError, OverflowError):
+        # Usage is diagnostic only; a malformed object (including a non-finite
+        # JSON number such as Infinity) must not fail a turn.
+        return {}
+    return {
+        "prompt_tokens": prompt_int,
+        "completion_tokens": completion_int,
+        "total_tokens": total_int,
+        "cached_tokens": cached_int,
+        "reasoning_tokens": reasoning_int,
+    }
+
+
+def content_text(value: Any) -> str:
+    """Flatten string, object, or multimodal-part content into plain text."""
+    if isinstance(value, str):
+        return value
+    if isinstance(value, dict):
+        text = value.get("text")
+        if isinstance(text, str):
+            return text
+        refusal = value.get("refusal")
+        return refusal if isinstance(refusal, str) else ""
+    if isinstance(value, list):
+        parts: list[str] = []
+        for item in value:
+            if isinstance(item, str):
+                parts.append(item)
+            elif isinstance(item, dict):
+                if isinstance(item.get("text"), str):
+                    parts.append(item["text"])
+                elif isinstance(item.get("refusal"), str):
+                    parts.append(item["refusal"])
+        # No separator is inserted because this same helper flattens streaming
+        # deltas and finished messages; adding one would make the reassembled
+        # text differ from what the model actually produced.
+        return "".join(parts)
+    return ""
+
+
+def tool_arguments(value: Any) -> str:
+    """Return tool arguments as the JSON string the message format requires."""
+    # The wire format wants a JSON *string*, and "" is what models emit for a
+    # no-argument call; leaving it empty would fail json.loads on the next turn.
+    if isinstance(value, str):
+        return value or "{}"
+    if value is None:
+        return "{}"
+    try:
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    except (TypeError, ValueError):
+        return "{}"
+
+
+def strip_sse_bom(line: str) -> str:
+    """Remove a UTF-8 BOM that a gateway left at the start of an SSE line."""
+    return line.lstrip("\ufeff") if line else line
+
+
+def is_event_stream(response: httpx2.Response) -> bool:
+    """Return True when the response advertises server-sent events."""
+    content_type = response.headers.get("content-type", "").lower()
+    return "text/event-stream" in content_type
+
+
+def decode_json_body(body: bytes) -> tuple[bool, Any]:
+    """Attempt to decode a non-streaming response body."""
+    try:
+        return True, json.loads(body)
+    except ValueError:
+        return False, None
+
+
+def stream_event_error(event: dict[str, Any]) -> ProviderError:
+    """Build a ProviderError from an SSE ``error`` event."""
+    error = event.get("error")
+    if isinstance(error, dict):
+        message = error.get("message") or error.get("type") or error
+    else:
+        message = error or event
+    return ProviderError(f"provider stream returned an error: {message}")