saia-python 0.4.1__tar.gz → 0.6.0__tar.gz

{saia_python-0.4.1/saia_python.egg-info → saia_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.4.1
+Version: 0.6.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only
@@ -57,9 +57,7 @@ Dynamic: license-file
 [![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](https://github.com/fschwar4/saia_python/blob/main/LICENSE)
 [![Tests](https://github.com/fschwar4/saia_python/actions/workflows/tests.yml/badge.svg)](https://github.com/fschwar4/saia_python/actions/workflows/tests.yml)
 [![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://fschwar4.github.io/saia_python/)
-<!-- After enabling Zenodo (Settings → Integrations → GitHub) and cutting a release,
-     paste the DOI badge Zenodo provides, e.g.:
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX) -->
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20480724.svg)](https://doi.org/10.5281/zenodo.20480724)
 
 A Python wrapper for the [GWDG SAIA (Scalable AI Accelerator) platform](https://docs.hpc.gwdg.de/services/ai-services/saia/index.html) REST API.
 

{saia_python-0.4.1 → saia_python-0.6.0}/README.md

@@ -5,9 +5,7 @@
 [![License: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-blue.svg)](https://github.com/fschwar4/saia_python/blob/main/LICENSE)
 [![Tests](https://github.com/fschwar4/saia_python/actions/workflows/tests.yml/badge.svg)](https://github.com/fschwar4/saia_python/actions/workflows/tests.yml)
 [![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://fschwar4.github.io/saia_python/)
-<!-- After enabling Zenodo (Settings → Integrations → GitHub) and cutting a release,
-     paste the DOI badge Zenodo provides, e.g.:
-[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.XXXXXXX.svg)](https://doi.org/10.5281/zenodo.XXXXXXX) -->
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20480724.svg)](https://doi.org/10.5281/zenodo.20480724)
 
 A Python wrapper for the [GWDG SAIA (Scalable AI Accelerator) platform](https://docs.hpc.gwdg.de/services/ai-services/saia/index.html) REST API.
 

{saia_python-0.4.1 → saia_python-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "saia-python"
-version = "0.4.1"
+version = "0.6.0"
 description = "Python wrapper for the GWDG SAIA platform REST API"
 readme = "README.md"
 requires-python = ">=3.10"

{saia_python-0.4.1 → saia_python-0.6.0}/saia_python/__init__.py

@@ -17,6 +17,7 @@ from __future__ import annotations
 import concurrent.futures
 from importlib.metadata import PackageNotFoundError, version
 
+from ._http import RetryPolicy
 from ._streaming import SSEStream
 from .arcana_references import (
     ArcanaReference,
@@ -36,7 +37,7 @@ from .auth import (
     resolve_base_url,
 )
 from .client import SAIAClient
-from .documents import ConversionResult
+from .documents import ConversionImage, ConversionResult
 from .exceptions import APIError, AuthenticationError, RateLimitError, SAIAError
 from .openai_compat import create_openai_client
 from .rate_limits import RateLimitInfo, parse_rate_limits
@@ -55,6 +56,7 @@ __all__ = [
     "resolve_base_url",
     "DEFAULT_BASE_URL",
     "create_openai_client",
+    "RetryPolicy",
     # Auth
     "load_api_key",
     "load_arcana_ids",
@@ -92,6 +94,7 @@ __all__ = [
     "get_rate_limits",
     "convert_document",
     "ConversionResult",
+    "ConversionImage",
 ]
 
 

saia_python-0.6.0/saia_python/_http.py

@@ -0,0 +1,243 @@
+"""Shared HTTP plumbing used by more than one service.
+
+Kept in one place so the chat-completion request shape and the
+background-thread ``Session`` helper each have a single implementation,
+rather than being copied across :mod:`saia_python.chat`,
+:mod:`saia_python.arcana`, and :mod:`saia_python.voice`.
+"""
+
+from __future__ import annotations
+
+import logging
+import random
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import requests
+
+from ._streaming import SSEStream
+from .exceptions import raise_for_status
+from .rate_limits import RateLimitInfo, parse_rate_limits
+
+log = logging.getLogger(__name__)
+
+# Default ``(connect, read)`` timeout in seconds for ARCANA management
+# ("control-plane") requests that do not pass their own. A plain
+# :class:`requests.Session` has NO default timeout, so a request the server
+# accepts but never answers — common while an arcana is locked mid-(re)index —
+# blocks forever on the socket read. Long-running "data-plane" calls (chat
+# completions, voice transcription, document conversion) deliberately do not
+# inherit this cap, since they can legitimately run for minutes.
+DEFAULT_TIMEOUT: tuple[float, float] = (10.0, 60.0)
+
+
+@dataclass
+class RetryPolicy:
+    """Transport-layer policy for HTTP 429 (rate-limit) responses.
+
+    Applied at the session dispatch seam (:func:`execute`); ON by default and
+    scoped to idempotent calls. See ``docs/proposals/rate-limit-handling.md``.
+
+    Attributes:
+        on_rate_limit: Master switch. When ``False`` a 429 is never retried —
+            it propagates as :class:`~saia_python.RateLimitError`, i.e. today's
+            behavior.
+        max_retries: Maximum reset-driven retries (the minute window).
+        max_waiting_time: The longest a single wait may block, in seconds
+            (default 60). A reset further out than this fails fast (raises)
+            rather than blocking; settable per client.
+        fallback_wait: Seconds to wait when the server sends no reset hint.
+        fallback_max_retries: How many times the blind fallback is tried.
+        jitter: ``(low, high)`` seconds added to each wait to avoid a
+            thundering herd across concurrent workers; ``(0, 0)`` disables it.
+        retry_mutations: If ``True``, non-idempotent calls are retried too
+            (off by default — replaying a mutation is unsafe in general).
+    """
+
+    on_rate_limit: bool = True
+    max_retries: int = 5
+    max_waiting_time: float = 60.0
+    fallback_wait: float = 31.0
+    fallback_max_retries: int = 2
+    jitter: tuple[float, float] = (0.0, 2.0)
+    retry_mutations: bool = False
+
+    def applies(self, idempotent: bool) -> bool:
+        """Whether a 429 on a call with this idempotency is eligible for retry."""
+        return self.on_rate_limit and (idempotent or self.retry_mutations)
+
+
+def coerce_retry(retry: RetryPolicy | bool | None) -> RetryPolicy:
+    """Normalise a ``retry`` argument into a :class:`RetryPolicy`.
+
+    A :class:`RetryPolicy` is returned unchanged; ``False`` disables retry;
+    ``None`` / ``True`` give the defaults (retry on).
+    """
+    if isinstance(retry, RetryPolicy):
+        return retry
+    if retry is False:
+        return RetryPolicy(on_rate_limit=False)
+    return RetryPolicy()
+
+
+def resolve_retry(
+    default: RetryPolicy, override: RetryPolicy | bool | None
+) -> RetryPolicy:
+    """Pick the policy for one call: the per-call ``override`` when given, else
+    the service ``default``. ``None`` means "use the default"."""
+    return default if override is None else coerce_retry(override)
+
+
+def _jitter(policy: RetryPolicy) -> float:
+    low, high = policy.jitter
+    return random.uniform(low, high) if high > low else low
+
+
+def _plan(info: RateLimitInfo, policy: RetryPolicy, attempt: int) -> float | None:
+    """Seconds to wait before the next attempt, or ``None`` to give up (→ raise).
+
+    Honest about the single ``reset_seconds`` spanning four windows: we wait out
+    the window we can time (the minute), but fail fast on a longer window whose
+    reset is unknowable — we will not block for ~an hour inside a call.
+    """
+    # A longer window is exhausted → its reset is not the (minute) reset_seconds.
+    for window in ("hour", "day", "month"):
+        if getattr(info, f"remaining_{window}") == 0:
+            return None
+    reset = info.reset_seconds
+    if isinstance(reset, (int, float)) and reset > 0:
+        if reset > policy.max_waiting_time:
+            return None
+        return None if attempt >= policy.max_retries else float(reset) + 1.0
+    # No usable reset hint → conservative, bounded blind fallback.
+    return None if attempt >= policy.fallback_max_retries else policy.fallback_wait
+
+
+def execute(
+    session: requests.Session,
+    method: str,
+    url: str,
+    *,
+    policy: RetryPolicy,
+    idempotent: bool,
+    sleep: Callable[[float], object] = time.sleep,
+    **kwargs,
+) -> requests.Response:
+    """Issue a request under a transport policy and return the response.
+
+    Dispatches ``getattr(session, method)(url, **kwargs)`` (``method`` is the
+    lowercase verb, matching the rest of the package). On HTTP 429 — when
+    ``policy`` permits (enabled, and the call is idempotent or
+    ``retry_mutations``) — it waits per :func:`_plan` and retries. It returns the
+    **raw response** unchanged on success *or* on give-up, so the caller's
+    :func:`~saia_python.exceptions.raise_for_status` still raises
+    :class:`~saia_python.RateLimitError` when retry is off, the budget is spent,
+    or the window must not be waited on.
+
+    Only the status code and headers are inspected — never the body — so
+    streaming and non-streaming requests behave identically and a streamed body
+    is never consumed. The (possibly streamed) connection is released with
+    ``close()`` before each wait.
+
+    Note:
+        A retry re-issues the request with the **same** ``kwargs``, so any file
+        payload must be retry-safe (``bytes``, not a one-shot file handle). The
+        file-upload callers (voice, documents) pass ``bytes``.
+    """
+    attempt = 0
+    while True:
+        resp = getattr(session, method)(url, **kwargs)
+        if resp.status_code != 429 or not policy.applies(idempotent):
+            return resp
+        wait = _plan(parse_rate_limits(resp.headers), policy, attempt)
+        if wait is None:
+            return resp
+        resp.close()
+        attempt += 1
+        wait += _jitter(policy)
+        log.info("SAIA rate limit (429) — waiting %.1fs before retry %d", wait, attempt)
+        sleep(wait)
+
+
+def new_session_like(template: requests.Session) -> requests.Session:
+    """Return a fresh :class:`requests.Session` mirroring ``template``'s headers.
+
+    Background-thread work must not reuse the caller's ``Session`` —
+    ``requests.Session`` is not guaranteed thread-safe, and sharing its
+    connection pool across threads can corrupt in-flight requests. Both the
+    non-blocking Voice path and the fire-and-forget ARCANA index trigger spin
+    up their own ``Session`` through this helper so they never race the
+    client's.
+    """
+    session = requests.Session()
+    session.headers.update(template.headers)
+    return session
+
+
+def post_chat_completion(
+    session: requests.Session,
+    url: str,
+    body: dict,
+    *,
+    headers: dict | None = None,
+    stream: bool = False,
+    policy: RetryPolicy | None = None,
+    sleep: Callable[[float], object] = time.sleep,
+) -> dict | SSEStream:
+    """POST a chat-completion request and normalise the response.
+
+    Shared by :meth:`ChatService.completions` and :meth:`ArcanaService.chat`:
+    both hit the same ``/chat/completions`` endpoint with identical
+    stream/non-stream handling and rate-limit surfacing — only the request
+    ``body`` fields and auth ``headers`` differ, so those stay with the caller.
+
+    Args:
+        session: The authenticated :class:`requests.Session`.
+        url: The fully-qualified ``/chat/completions`` URL.
+        body: The request JSON body (already assembled by the caller).
+        headers: Per-request headers. ``None`` uses the session defaults
+            (the Bearer auth + ``Accept: application/json``).
+        stream: When ``True``, request SSE and return an :class:`SSEStream`.
+        policy: Rate-limit :class:`RetryPolicy`; ``None`` uses the defaults
+            (retry on). Chat completions are idempotent, so an initial 429 is
+            retried per the policy — and for streaming the retry happens *before*
+            the stream is exposed (never mid-stream).
+        sleep: Injectable sleep hook (tests pass a recorder so they never block).
+
+    Returns:
+        When ``stream=False``: the response dict with an extra
+        ``"_rate_limits"`` key (a JSON-serializable dict). When ``stream=True``:
+        an :class:`SSEStream` whose ``rate_limits`` attribute holds the same dict.
+    """
+    policy = policy if policy is not None else RetryPolicy()
+    if stream:
+        stream_body = {**body, "stream": True}
+        stream_headers = {**(headers or {}), "Accept": "text/event-stream"}
+        resp = execute(
+            session,
+            "post",
+            url,
+            policy=policy,
+            idempotent=True,
+            sleep=sleep,
+            json=stream_body,
+            headers=stream_headers,
+            stream=True,
+        )
+        return SSEStream(resp)
+
+    resp = execute(
+        session,
+        "post",
+        url,
+        policy=policy,
+        idempotent=True,
+        sleep=sleep,
+        json=body,
+        headers=headers,
+    )
+    raise_for_status(resp)
+    result = resp.json()
+    result["_rate_limits"] = parse_rate_limits(resp.headers).to_dict()
+    return result

{saia_python-0.4.1 → saia_python-0.6.0}/saia_python/_streaming.py

@@ -27,7 +27,10 @@ def iter_sse(response: requests.Response) -> Generator[dict, None, None]:
     """
     raise_for_status(response)
     try:
-        for line in response.iter_lines(decode_unicode=True):
+        for raw in response.iter_lines(decode_unicode=True):
+            # decode_unicode=True yields str at runtime, but the requests type
+            # stub still types iter_lines as bytes — normalize for both.
+            line = raw.decode("utf-8") if isinstance(raw, bytes) else raw
             if not line or not line.startswith("data:"):
                 continue
             payload = line[len("data:") :].strip()