courier-encode 0.1.0__py3-none-any.whl

encode/_streaming.py

@@ -0,0 +1,97 @@
+"""SSE accumulators for /v1/chat/completions and /v1/responses streaming."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Iterator
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+
+@dataclass
+class StreamEvent:
+    type: str
+    data: Any
+    raw: dict[str, Any] | None = None
+
+
+def _iter_sse_lines(resp: httpx.Response) -> Iterator[str]:
+    for raw in resp.iter_lines():
+        if not raw:
+            continue
+        line = raw if isinstance(raw, str) else raw.decode("utf-8", errors="replace")
+        if line.startswith(":"):
+            continue
+        if line.startswith("data:"):
+            payload = line[5:].lstrip()
+            if payload == "[DONE]":
+                return
+            yield payload
+
+
+async def _aiter_sse_lines(resp: httpx.Response) -> AsyncIterator[str]:
+    async for raw in resp.aiter_lines():
+        if not raw:
+            continue
+        line = raw if isinstance(raw, str) else raw.decode("utf-8", errors="replace")
+        if line.startswith(":"):
+            continue
+        if line.startswith("data:"):
+            payload = line[5:].lstrip()
+            if payload == "[DONE]":
+                return
+            yield payload
+
+
+def iter_chat_completions(resp: httpx.Response) -> Iterator[StreamEvent]:
+    for payload in _iter_sse_lines(resp):
+        try:
+            chunk = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+        delta = (chunk.get("choices") or [{}])[0].get("delta") or {}
+        if "content" in delta and delta["content"] is not None:
+            yield StreamEvent(type="content.delta", data=delta["content"], raw=chunk)
+        if "tool_calls" in delta and delta["tool_calls"]:
+            yield StreamEvent(type="tool_calls.delta", data=delta["tool_calls"], raw=chunk)
+        finish = (chunk.get("choices") or [{}])[0].get("finish_reason")
+        if finish:
+            yield StreamEvent(type="finish", data=finish, raw=chunk)
+
+
+def iter_responses(resp: httpx.Response) -> Iterator[StreamEvent]:
+    for payload in _iter_sse_lines(resp):
+        try:
+            event = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+        etype = event.get("type", "unknown")
+        yield StreamEvent(type=etype, data=event, raw=event)
+
+
+async def aiter_chat_completions(resp: httpx.Response) -> AsyncIterator[StreamEvent]:
+    async for payload in _aiter_sse_lines(resp):
+        try:
+            chunk = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+        delta = (chunk.get("choices") or [{}])[0].get("delta") or {}
+        if "content" in delta and delta["content"] is not None:
+            yield StreamEvent(type="content.delta", data=delta["content"], raw=chunk)
+        if "tool_calls" in delta and delta["tool_calls"]:
+            yield StreamEvent(type="tool_calls.delta", data=delta["tool_calls"], raw=chunk)
+        finish = (chunk.get("choices") or [{}])[0].get("finish_reason")
+        if finish:
+            yield StreamEvent(type="finish", data=finish, raw=chunk)
+
+
+async def aiter_responses(resp: httpx.Response) -> AsyncIterator[StreamEvent]:
+    async for payload in _aiter_sse_lines(resp):
+        try:
+            event = json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+        etype = event.get("type", "unknown")
+        yield StreamEvent(type=etype, data=event, raw=event)

encode/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

encode/client.py

@@ -0,0 +1,138 @@
+"""Client / AsyncClient — thin wrappers around httpx with config resolution."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from . import _config, _http
+from ._version import __version__
+
+
+class Client:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.Client | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        _config.load_dotenv_once()
+        self._api_key = _config.resolve_api_key(api_key)
+        self._base_url = _config.resolve_base_url(base_url)
+        self._timeout = _http.build_timeout(timeout)
+        self.max_retries = max_retries
+        headers = _http.default_headers(self._api_key, version=__version__)
+        if default_headers:
+            headers.update(default_headers)
+        self._owns_client = http_client is None
+        self._http: httpx.Client = http_client or httpx.Client(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers=headers,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def api_key(self) -> str:
+        return self._api_key
+
+    def relay(self, **kwargs: Any) -> Any:
+        from .relay import relay
+
+        return relay(client=self, **kwargs)
+
+    def whisper(self, **kwargs: Any) -> Any:
+        from .whisper import whisper
+
+        return whisper(client=self, **kwargs)
+
+    def close(self) -> None:
+        if self._owns_client:
+            self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+class AsyncClient:
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = 60.0,
+        max_retries: int = 2,
+        http_client: httpx.AsyncClient | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> None:
+        _config.load_dotenv_once()
+        self._api_key = _config.resolve_api_key(api_key)
+        self._base_url = _config.resolve_base_url(base_url)
+        self._timeout = _http.build_timeout(timeout)
+        self.max_retries = max_retries
+        headers = _http.default_headers(self._api_key, version=__version__)
+        if default_headers:
+            headers.update(default_headers)
+        self._owns_client = http_client is None
+        self._http: httpx.AsyncClient = http_client or httpx.AsyncClient(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            headers=headers,
+        )
+
+    @property
+    def base_url(self) -> str:
+        return self._base_url
+
+    @property
+    def api_key(self) -> str:
+        return self._api_key
+
+    def relay(self, **kwargs: Any) -> Any:
+        from .relay import relay_async
+
+        return relay_async(client=self, **kwargs)
+
+    async def whisper(self, **kwargs: Any) -> Any:
+        from .whisper import whisper_async
+
+        return await whisper_async(client=self, **kwargs)
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+_default_client: Client | None = None
+_default_async_client: AsyncClient | None = None
+
+
+def get_default_client() -> Client:
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def get_default_async_client() -> AsyncClient:
+    global _default_async_client
+    if _default_async_client is None:
+        _default_async_client = AsyncClient()
+    return _default_async_client

encode/errors.py

@@ -0,0 +1,169 @@
+"""Typed exception hierarchy for encode.
+
+Maps the OpenAI-compatible error envelope ``{"error": {"message", "type", "code"}}``
+to specific exception classes. Falls back to ``CourierError`` for non-envelope bodies
+(some compatible servers return ``{"detail": "..."}`` or plain text).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CourierError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        type: str | None = None,
+        code: str | None = None,
+        status: int | None = None,
+        raw: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.type = type
+        self.code = code
+        self.status = status
+        self.raw = raw
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        parts = [f"message={self.message!r}"]
+        if self.type:
+            parts.append(f"type={self.type!r}")
+        if self.code:
+            parts.append(f"code={self.code!r}")
+        if self.status is not None:
+            parts.append(f"status={self.status}")
+        return f"{type(self).__name__}({', '.join(parts)})"
+
+
+class AuthError(CourierError):
+    """401 / missing credentials."""
+
+
+class InvalidRequestError(CourierError):
+    """400-level client error."""
+
+
+class InvalidToolCallError(InvalidRequestError):
+    """code=invalid_tool_call — arguments failed strict JSON validation."""
+
+
+class InvalidToolChoiceError(InvalidRequestError):
+    """code=invalid_tool_choice — forced tool name not in tools list."""
+
+
+class InvalidResponseFormatError(InvalidRequestError):
+    """type=invalid_response_format — unsupported response_format."""
+
+
+class InvalidAudioError(InvalidRequestError):
+    """type=invalid_audio — bad multipart upload, unsupported format, etc."""
+
+
+class RateLimitError(CourierError):
+    """429."""
+
+
+class ServerError(CourierError):
+    """5xx."""
+
+
+class TransportError(CourierError):
+    """Network / timeout failure that exhausted retries."""
+
+
+class MaxToolIterationsError(CourierError):
+    """SDK-side: tool loop exceeded max_tool_iterations.
+
+    Carries the partial RelayResponse so callers can inspect what happened.
+    """
+
+    def __init__(self, message: str, *, partial: Any = None, **kw: Any) -> None:
+        super().__init__(message, **kw)
+        self.partial = partial
+
+
+class SessionError(CourierError):
+    """Persistent shell session failure (spawn, dead process, unsupported platform)."""
+
+
+class SessionTimeoutError(SessionError):
+    """A session command exceeded its timeout.
+
+    Carries ``partial_output`` (whatever was emitted before the cutoff) and
+    ``command`` so callers can salvage what happened.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        partial_output: str = "",
+        command: str = "",
+        **kw: Any,
+    ) -> None:
+        super().__init__(message, **kw)
+        self.partial_output = partial_output
+        self.command = command
+
+
+_CODE_MAP: dict[str, type[CourierError]] = {
+    "invalid_tool_call": InvalidToolCallError,
+    "invalid_tool_choice": InvalidToolChoiceError,
+    "invalid_response_format": InvalidResponseFormatError,
+    "invalid_audio": InvalidAudioError,
+}
+
+_TYPE_MAP: dict[str, type[CourierError]] = {
+    "invalid_request_error": InvalidRequestError,
+    "invalid_audio": InvalidAudioError,
+    "invalid_response_format": InvalidResponseFormatError,
+}
+
+
+def from_envelope(
+    body: Any, status: int | None = None
+) -> CourierError:
+    """Build a typed exception from a parsed response body and HTTP status.
+
+    Tries the OpenAI envelope first, then falls back to ``{"detail": ...}``,
+    then to a plain string body.
+    """
+    err: dict[str, Any] | None = None
+    detail: str | None = None
+    if isinstance(body, dict):
+        if isinstance(body.get("error"), dict):
+            err = body["error"]
+        elif "detail" in body:
+            detail = str(body["detail"])
+
+    if err is not None:
+        message = str(err.get("message") or "request failed")
+        code = err.get("code")
+        type_ = err.get("type")
+        cls = (
+            _CODE_MAP.get(str(code) if code else "")
+            or _TYPE_MAP.get(str(type_) if type_ else "")
+            or _from_status(status)
+        )
+        return cls(message, type=type_, code=code, status=status, raw=body)
+
+    message = detail or (body if isinstance(body, str) else f"HTTP {status}")
+    cls = _from_status(status)
+    return cls(message, status=status, raw=body)
+
+
+def _from_status(status: int | None) -> type[CourierError]:
+    if status is None:
+        return CourierError
+    if status == 401 or status == 403:
+        return AuthError
+    if status == 429:
+        return RateLimitError
+    if 400 <= status < 500:
+        return InvalidRequestError
+    if 500 <= status < 600:
+        return ServerError
+    return CourierError