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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.4.1
+Version: 0.5.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.5.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.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "saia-python"
-version = "0.4.1"
+version = "0.5.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.5.0}/saia_python/_http.py

@@ -14,6 +14,15 @@ from ._streaming import SSEStream
 from .exceptions import raise_for_status
 from .rate_limits import parse_rate_limits
 
+# 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)
+
 
 def new_session_like(template: requests.Session) -> requests.Session:
     """Return a fresh :class:`requests.Session` mirroring ``template``'s headers.

{saia_python-0.4.1 → saia_python-0.5.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()

{saia_python-0.4.1 → saia_python-0.5.0}/saia_python/arcana.py

@@ -11,7 +11,7 @@ from urllib.parse import quote
 
 import requests
 
-from ._http import new_session_like, post_chat_completion
+from ._http import DEFAULT_TIMEOUT, new_session_like, post_chat_completion
 from ._streaming import SSEStream
 from ._util import progress_iter
 from .exceptions import APIError, raise_for_status
@@ -61,17 +61,52 @@ class ArcanaService:
         session: A :class:`requests.Session` (auth header will be overridden per-request).
         base_url: The SAIA API base URL (e.g. ``https://chat-ai.academiccloud.de/v1``).
         api_key: The raw API key (needed because ARCANA omits the ``Bearer`` prefix).
+        timeout: Default ``(connect, read)`` timeout in seconds applied to every
+            ARCANA management request that does not set its own. Guards against
+            the server accepting a request but never responding (e.g. while an
+            arcana is locked mid-(re)index), which would otherwise block forever
+            on the socket read. A single ``float`` applies to both phases; pass
+            ``None`` to disable. Defaults to ``(10, 60)``. The long-running chat
+            path (:meth:`chat`) is exempt.
     """
 
-    def __init__(self, session: requests.Session, base_url: str, api_key: str):
+    def __init__(
+        self,
+        session: requests.Session,
+        base_url: str,
+        api_key: str,
+        *,
+        timeout: float | tuple[float, float] | None = DEFAULT_TIMEOUT,
+    ):
         self._session = session
         self._base_url = base_url
         self._arcana_base = f"{self._base_url}{_ARCANA_PATH}"
         self._api_key = api_key
+        self._timeout = timeout
 
     def _headers(self, **extra) -> dict:
         return {"Authorization": self._api_key, "Accept": "application/json", **extra}
 
+    def _request(self, method: str, url: str, **kwargs) -> requests.Response:
+        """Issue a request on the shared session with a default timeout.
+
+        A plain :class:`requests.Session` has no default timeout, so any ARCANA
+        management call that forgets ``timeout=`` blocks forever on the socket
+        read when the server accepts the request but never responds — common
+        while an arcana is locked mid-(re)index. Routing every such call through
+        here injects :attr:`_timeout` unless an explicit ``timeout`` was passed
+        (so :meth:`heartbeat` and :meth:`generate_index` keep their own), so
+        calls fail fast with :class:`requests.Timeout` instead of hanging. That
+        error is *not* swallowed here — it propagates to the caller (the batch
+        helpers record it per file and carry on).
+
+        ``method`` is the lowercase HTTP verb (``"get"``, ``"post"``, ``"put"``,
+        ``"delete"``); dispatching through the verb attribute keeps the call
+        shape the rest of the code — and the tests — already rely on.
+        """
+        kwargs.setdefault("timeout", self._timeout)
+        return getattr(self._session, method)(url, **kwargs)
+
     @staticmethod
     def _format_arcana_line(a: dict, *, with_owner: bool = False) -> str:
         """Format one arcana as a one-line summary (shared by the summary views)."""
@@ -113,14 +148,21 @@ class ArcanaService:
         verb: str,
         desc: str,
         verbose: bool,
+        on_result: Callable[[Path, dict], None] | None = None,
     ) -> list[dict]:
         """Run ``action(path)`` over each file, tallying per-file status.
 
-        The shared skeleton behind :meth:`upload_directory` and
-        :meth:`delete_directory`: an optionally tqdm-wrapped loop that records
-        a ``{"file", "status", ["error"]}`` dict per item and prints a tally
-        when ``verbose``. Only the per-file ``action`` and the past-tense
-        ``verb`` (``"uploaded"`` / ``"deleted"``) differ between callers.
+        The shared skeleton behind :meth:`upload_directory`,
+        :meth:`upload_files`, and :meth:`delete_directory`: an optionally
+        tqdm-wrapped loop that records a ``{"file", "status", ["error"]}`` dict
+        per item and prints a tally when ``verbose``. Only the per-file
+        ``action`` and the past-tense ``verb`` (``"uploaded"`` / ``"deleted"``)
+        differ between callers.
+
+        If ``on_result`` is given it is called as ``on_result(path, entry)``
+        immediately after each file is processed (``entry`` is that file's
+        result dict), so callers can stream per-file provenance / transaction
+        logging without reimplementing the loop.
         """
         results = []
         for fp in progress_iter(files, desc=desc, unit="file"):
@@ -134,6 +176,8 @@ class ArcanaService:
             if verbose:
                 label = verb.capitalize() if entry["status"] == verb else "FAILED"
                 print(f"  {fp.name}  {label}")
+            if on_result is not None:
+                on_result(fp, entry)
             results.append(entry)
 
         succeeded = sum(1 for r in results if r["status"] == verb)
@@ -153,8 +197,8 @@ class ArcanaService:
         Returns:
             The version string (e.g. ``"0.4.16"``).
         """
-        resp = self._session.get(
-            f"{self._arcana_base}/version", headers=self._headers()
+        resp = self._request(
+            "get", f"{self._arcana_base}/version", headers=self._headers()
         )
         raise_for_status(resp)
         return resp.json().get("version", "")
@@ -167,7 +211,8 @@ class ArcanaService:
         errors — it never raises).
         """
         try:
-            resp = self._session.get(
+            resp = self._request(
+                "get",
                 f"{self._arcana_base}/heartbeat",
                 headers=self._headers(),
                 timeout=10,
@@ -185,7 +230,8 @@ class ArcanaService:
         Returns:
             A dict with user profile fields.
         """
-        resp = self._session.get(
+        resp = self._request(
+            "get",
             f"{self._arcana_base}/user/me",
             headers=self._headers(),
         )
@@ -251,7 +297,8 @@ class ArcanaService:
         if append_uuid:
             name = f"{name}-{_uuid.uuid4()}"
 
-        resp = self._session.post(
+        resp = self._request(
+            "post",
             f"{self._arcana_base}/arcana/",
             headers={**self._headers(), "Content-Type": "application/json"},
             json={"name": name},
@@ -295,7 +342,8 @@ class ArcanaService:
         full_id = name
         name = extract_arcana_name(name)
 
-        resp = self._session.delete(
+        resp = self._request(
+            "delete",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}",
             headers=self._headers(),
         )
@@ -317,7 +365,8 @@ class ArcanaService:
         Returns:
             A list of arcana dicts.
         """
-        resp = self._session.get(
+        resp = self._request(
+            "get",
             f"{self._arcana_base}/arcana/",
             headers=self._headers(),
         )
@@ -384,7 +433,8 @@ class ArcanaService:
             Arcana details dict.
         """
         name = extract_arcana_name(name)
-        resp = self._session.get(
+        resp = self._request(
+            "get",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}",
             headers=self._headers(),
         )
@@ -469,13 +519,15 @@ class ArcanaService:
         base = f"{self._arcana_base}/arcana/{quote(name, safe='')}/files"
         with open(file_path, "rb") as f:
             if overwrite:
-                resp = self._session.put(
+                resp = self._request(
+                    "put",
                     f"{base}/{quote(file_path.name, safe='')}",
                     headers=self._headers(),
                     files={"file": (file_path.name, f)},
                 )
             else:
-                resp = self._session.post(
+                resp = self._request(
+                    "post",
                     f"{base}/",
                     headers=self._headers(),
                     files={"file": (file_path.name, f)},
@@ -492,6 +544,7 @@ class ArcanaService:
         recursive: bool = False,
         overwrite: bool = False,
         verbose: bool = False,
+        on_result: Callable[[Path, dict], None] | None = None,
     ) -> list[dict]:
         """Upload all files in a directory to an arcana.
 
@@ -504,6 +557,10 @@ class ArcanaService:
                 (uses ``**/<pattern>``).
             overwrite: If ``True``, replace existing files with the same name.
             verbose: If ``True``, print per-file upload status.
+            on_result: Optional callback invoked as ``on_result(local_path,
+                entry)`` after each file (``entry`` is that file's
+                ``{"file", "status", ["error"]}`` dict), for inline per-file
+                provenance / transaction logging.
 
         Returns:
             A list of dicts with keys ``"file"`` (filename only),
@@ -517,6 +574,7 @@ class ArcanaService:
             verb="uploaded",
             desc="Uploading",
             verbose=verbose,
+            on_result=on_result,
         )
 
     def upload_files(
@@ -526,6 +584,7 @@ class ArcanaService:
         *,
         overwrite: bool = True,
         verbose: bool = False,
+        on_result: Callable[[Path, dict], None] | None = None,
     ) -> list[dict]:
         """Upload an explicit, caller-chosen list of files to an arcana.
 
@@ -544,6 +603,11 @@ class ArcanaService:
                 the typical caller has already decided these files are new or
                 changed.
             verbose: If ``True``, print per-file upload status.
+            on_result: Optional callback invoked as ``on_result(local_path,
+                entry)`` after each file (``entry`` is that file's
+                ``{"file", "status", ["error"]}`` dict). Lets a caller record
+                per-file provenance (e.g. a git SHA) or a transaction-log entry
+                as each upload completes, without reimplementing this loop.
 
         Returns:
             A list of ``{"file", "status", ["error"]}`` dicts — the same shape
@@ -556,6 +620,7 @@ class ArcanaService:
             verb="uploaded",
             desc="Uploading",
             verbose=verbose,
+            on_result=on_result,
         )
 
     def list_files(self, name: str) -> list[dict]:
@@ -588,7 +653,8 @@ class ArcanaService:
             has no per-file index call.
         """
         name = extract_arcana_name(name)
-        resp = self._session.get(
+        resp = self._request(
+            "get",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}/files/",
             headers=self._headers(),
         )
@@ -609,7 +675,8 @@ class ArcanaService:
             The API response, or ``None`` if the response has no body.
         """
         name = extract_arcana_name(name)
-        resp = self._session.delete(
+        resp = self._request(
+            "delete",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}/files/{quote(file_name, safe='')}",
             headers=self._headers(),
         )
@@ -631,7 +698,8 @@ class ArcanaService:
             The path the file was written to.
         """
         name = extract_arcana_name(name)
-        resp = self._session.get(
+        resp = self._request(
+            "get",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}/files/{quote(file_name, safe='')}/download",
             headers=self._headers(),
             stream=True,
@@ -651,6 +719,7 @@ class ArcanaService:
         pattern: str = "*",
         recursive: bool = False,
         verbose: bool = False,
+        on_result: Callable[[Path, dict], None] | None = None,
     ) -> list[dict]:
         """Delete files from an arcana that match filenames in a local directory.
 
@@ -665,6 +734,10 @@ class ArcanaService:
             pattern: Glob pattern to filter files (default ``"*"``).
             recursive: If ``True``, search subdirectories recursively.
             verbose: If ``True``, print per-file deletion status.
+            on_result: Optional callback invoked as ``on_result(local_path,
+                entry)`` after each file (``entry`` is that file's
+                ``{"file", "status", ["error"]}`` dict), for inline per-file
+                logging.
 
         Returns:
             A list of dicts with keys ``"file"`` (filename only),
@@ -678,6 +751,7 @@ class ArcanaService:
             verb="deleted",
             desc="Deleting",
             verbose=verbose,
+            on_result=on_result,
         )
 
     def sync_directory(
@@ -692,6 +766,7 @@ class ArcanaService:
         index: bool = True,
         index_wait: bool = True,
         verbose: bool = False,
+        on_result: Callable[[Path, dict], None] | None = None,
     ) -> dict:
         """Sync a local directory into an arcana under caller-defined rules.
 
@@ -703,6 +778,9 @@ class ArcanaService:
         detection (e.g. SHA-256 against your own manifest) belongs in
         ``select``.
 
+        The single index pass is efficient because the server only (re)embeds
+        files that are not already ``INDEXED`` — see :meth:`generate_index`.
+
         Args:
             name: The arcana name or full ``owner/name`` ID.
             directory: Local directory to sync from.
@@ -721,6 +799,14 @@ class ArcanaService:
                 the sync — but only when something actually changed.
             index_wait: Forwarded to :meth:`generate_index` as ``wait``.
             verbose: If ``True``, print per-file actions and a summary.
+            on_result: Optional callback invoked as ``on_result(local_path,
+                entry)`` for each *local* file as it is uploaded, replaced, or
+                skipped (``entry`` mirrors the batch-helper shape:
+                ``{"file", "status", ["error"]}``, where ``status`` is one of
+                ``"uploaded"`` / ``"replaced"`` / ``"skipped"`` / ``"failed"``).
+                Lets callers record per-file provenance / transaction logs
+                inline. Not called for ``prune`` deletions (those are
+                remote-only).
 
         Returns:
             A report ``dict`` with keys ``"uploaded"``, ``"replaced"``,
@@ -764,18 +850,26 @@ class ArcanaService:
         for path, action in plan:
             if action == "skip":
                 report["skipped"].append(path.name)
+                if on_result is not None:
+                    on_result(path, {"file": path.name, "status": "skipped"})
                 continue
             overwrite = action == "replace"
             bucket = "replaced" if overwrite else "uploaded"
+            entry: dict = {"file": path.name}
             try:
                 self.upload(name, path, overwrite=overwrite)
                 report[bucket].append(path.name)
+                entry["status"] = bucket
                 if verbose:
                     print(f"  {path.name}  {bucket}")
             except Exception as e:
+                entry["status"] = "failed"
+                entry["error"] = str(e)
                 report["failed"].append({"file": path.name, "error": str(e)})
                 if verbose:
                     print(f"  {path.name}  FAILED ({e})")
+            if on_result is not None:
+                on_result(path, entry)
 
         if prune:
             local_names = {p.name for p in local_files}
@@ -835,6 +929,16 @@ class ArcanaService:
         Raises:
             TimeoutError: If ``wait=True`` and indexing does not complete
                 within ``timeout`` seconds.
+
+        Note:
+            Indexing is incremental on the server: files already at
+            ``index_status == "INDEXED"`` are skipped, so only files added or
+            replaced since the last index (an upload resets a file to
+            ``NOT_INDEXED``) are (re)embedded. This is why the efficient pattern
+            is *upload only the changed files, then call this once* — the single
+            whole-arcana trigger re-embeds just those. The library relies on
+            this skip-``INDEXED`` behavior; if the server ever stops skipping,
+            the call stays correct but re-embeds the whole arcana.
         """
         import threading
         import time
@@ -861,7 +965,7 @@ class ArcanaService:
 
         # Synchronous: fire the request, tolerate transport-level failures, then poll
         try:
-            resp = self._session.post(url, headers=self._headers(), timeout=30)
+            resp = self._request("post", url, headers=self._headers(), timeout=30)
             raise_for_status(resp)
         except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
             # The trigger almost certainly reached the server (the body
@@ -879,23 +983,45 @@ class ArcanaService:
             if e.status_code != 504:
                 raise
 
-        # Poll until indexing finishes
+        # Poll until indexing finishes. Tolerate transient transport failures on
+        # an individual poll (the index keeps building server-side) so a slow or
+        # dropped poll GET — now that control-plane calls carry a default
+        # timeout — cannot abort a long, still-progressing reindex. Only the
+        # overall ``timeout`` deadline ends the wait; each retry is paced by the
+        # poll_interval sleep, so a genuinely-down server still gives up at the
+        # deadline.
         deadline = time.monotonic() + timeout
         terminal = {"INDEXED", "ERROR", "NOT_INDEXED"}
         status = ""
+        last_error: Exception | None = None
 
         while time.monotonic() < deadline:
             time.sleep(poll_interval)
-            data = self.get(name)
+            try:
+                data = self.get(name)
+            except (
+                requests.exceptions.Timeout,
+                requests.exceptions.ConnectionError,
+            ) as e:
+                last_error = e  # transient — remember it, retry on the next poll
+                continue
+            last_error = None  # a successful poll clears any prior transient error
             idx = data.get("index_info") or {}
             status = idx.get("index_status", "")
             if status in terminal:
                 return data
 
-        raise TimeoutError(
-            f"Indexing did not complete within {timeout}s. "
-            f"Last status: {status}. Check with client.arcana.info(...)."
-        )
+        # Deadline exhausted. Surface whichever signal we actually have — the
+        # last-seen status (slow indexing) and/or the last transport error
+        # (polls that kept failing) — so the timeout is diagnosable rather than
+        # reporting an empty status.
+        msg = f"Indexing did not complete within {timeout}s."
+        if status:
+            msg += f" Last status: {status}."
+        if last_error is not None:
+            msg += f" Last poll error: {last_error!r}."
+        msg += " Check with client.arcana.info(...)."
+        raise TimeoutError(msg)
 
     def delete_index(self, name: str) -> dict | None:
         """Delete the index of an arcana.
@@ -909,7 +1035,8 @@ class ArcanaService:
             The API response, or ``None`` if the response has no body.
         """
         name = extract_arcana_name(name)
-        resp = self._session.delete(
+        resp = self._request(
+            "delete",
             f"{self._arcana_base}/arcana/{quote(name, safe='')}/delete-index",
             headers=self._headers(),
         )

{saia_python-0.4.1 → saia_python-0.5.0}/saia_python/client.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import requests as _requests
 
+from ._http import DEFAULT_TIMEOUT
 from .arcana import ArcanaService
 from .auth import resolve_credentials
 from .chat import ChatService
@@ -30,6 +31,12 @@ class SAIAClient:
             hardcoded default (``https://chat-ai.academiccloud.de/v1``).
         key_file: Explicit path to a ``.saia_api`` or ``.env`` file.
             Ignored when ``api_key`` is provided.
+        timeout: Default ``(connect, read)`` timeout in seconds for ARCANA
+            management calls, forwarded to :class:`~saia_python.arcana.ArcanaService`.
+            Stops those calls from hanging forever when the server accepts a
+            request but never responds (e.g. while an arcana is locked
+            mid-(re)index). A single ``float`` applies to both phases; pass
+            ``None`` to disable. Defaults to ``(10, 60)``.
 
     Example::
 
@@ -48,8 +55,11 @@ class SAIAClient:
         api_key: str | None = None,
         base_url: str | None = None,
         key_file: str | None = None,
+        *,
+        timeout: float | tuple[float, float] | None = DEFAULT_TIMEOUT,
     ):
         self._api_key, self._base_url = resolve_credentials(api_key, base_url, key_file)
+        self._timeout = timeout
         self._session = _requests.Session()
         self._session.headers.update(
             {
@@ -84,14 +94,21 @@ class SAIAClient:
     def models(self) -> ModelsService:
         """Model listing service."""
         if self._models is None:
-            self._models = ModelsService(self._session, self._base_url)
+            self._models = ModelsService(
+                self._session, self._base_url, timeout=self._timeout
+            )
         return self._models
 
     @property
     def arcana(self) -> ArcanaService:
         """ARCANA/RAG service."""
         if self._arcana is None:
-            self._arcana = ArcanaService(self._session, self._base_url, self._api_key)
+            self._arcana = ArcanaService(
+                self._session,
+                self._base_url,
+                self._api_key,
+                timeout=self._timeout,
+            )
         return self._arcana
 
     @property
@@ -156,7 +173,9 @@ class SAIAClient:
                 (401/403). Other non-2xx statuses (notably the expected
                 400) are tolerated since they still carry the headers.
         """
-        resp = self._session.get(f"{self._base_url}/chat/completions")
+        resp = self._session.get(
+            f"{self._base_url}/chat/completions", timeout=self._timeout
+        )
         if resp.status_code in (401, 403):
             # The probe is *expected* to 400 (missing request body) but still
             # carries rate-limit headers. A 401/403 means the key is bad, so

{saia_python-0.4.1 → saia_python-0.5.0}/saia_python/models.py

@@ -2,8 +2,9 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
+from ._http import DEFAULT_TIMEOUT
 from ._util import progress_iter
 from .exceptions import raise_for_status
 
@@ -17,11 +18,24 @@ class ModelsService:
     Args:
         session: A :class:`requests.Session` with auth headers configured.
         base_url: The SAIA API base URL (e.g. ``https://chat-ai.academiccloud.de/v1``).
+        timeout: Default ``(connect, read)`` timeout in seconds for the
+            ``GET /models`` listing call, so it fails fast instead of hanging
+            forever when the server accepts the request but never responds. A
+            single ``float`` applies to both phases; pass ``None`` to disable.
+            Defaults to ``(10, 60)``. (The tool-capability probe keeps its own
+            per-request ``timeout``.)
     """
 
-    def __init__(self, session: requests.Session, base_url: str):
+    def __init__(
+        self,
+        session: requests.Session,
+        base_url: str,
+        *,
+        timeout: float | tuple[float, float] | None = DEFAULT_TIMEOUT,
+    ):
         self._session = session
         self._base_url = base_url
+        self._timeout = timeout
 
     def list_raw(self) -> dict:
         """Return the raw ``/models`` response envelope, as the API sent it.
@@ -39,7 +53,7 @@ class ModelsService:
             this is a dict of the form
             ``{"object": "list", "data": [...]}``.
         """
-        resp = self._session.get(f"{self._base_url}/models")
+        resp = self._session.get(f"{self._base_url}/models", timeout=self._timeout)
         raise_for_status(resp)
         return resp.json()
 
@@ -117,15 +131,16 @@ class ModelsService:
         for mid in progress_iter(
             model_ids, desc="Probing models", unit="model", enabled=not verbose
         ):
+            body: dict[str, Any] = {
+                "model": mid,
+                "messages": _PROBE_MESSAGES,
+                "tools": _PROBE_TOOLS,
+                "max_tokens": 50,
+            }
             try:
                 resp = self._session.post(
                     f"{self._base_url}/chat/completions",
-                    json={
-                        "model": mid,
-                        "messages": _PROBE_MESSAGES,
-                        "tools": _PROBE_TOOLS,
-                        "max_tokens": 50,
-                    },
+                    json=body,
                     timeout=30,
                 )
                 data = resp.json()

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.4.1
+Version: 0.5.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.5.0}/tests/test_arcana.py

@@ -17,6 +17,7 @@ def _make_service() -> ArcanaService:
     svc._base_url = "https://example.com/v1"
     svc._arcana_base = "https://example.com/v1/arcanas/api/v1"
     svc._api_key = "test"
+    svc._timeout = (10.0, 60.0)
     return svc
 
 
@@ -154,6 +155,41 @@ class TestGenerateIndexTransportErrors:
         with pytest.raises(TimeoutError, match="did not complete"):
             svc.generate_index("my-arcana", poll_interval=0, timeout=0)
 
+    def test_transient_poll_timeout_is_tolerated(self):
+        """A dropped/slow individual poll GET must not abort a still-building
+        reindex — retry on the next poll, bounded by the overall timeout."""
+        svc = _make_service()
+        post_resp = MagicMock()
+        post_resp.status_code = 200
+        post_resp.ok = True
+        svc._session.post.return_value = post_resp
+        svc._session.get.side_effect = [
+            requests.exceptions.ReadTimeout("transient poll blip"),  # tolerated
+            _get_response("PENDING"),
+            _get_response("INDEXED"),
+        ]
+        result = svc.generate_index("my-arcana", poll_interval=0, timeout=10)
+        assert result["index_info"]["index_status"] == "INDEXED"
+        assert svc._session.get.call_count == 3
+
+    def test_persistent_poll_timeout_reports_last_error(self):
+        """If polls keep timing out until the deadline, the TimeoutError surfaces
+        the transport error instead of a misleading empty 'Last status'."""
+        svc = _make_service()
+        post_resp = MagicMock()
+        post_resp.status_code = 200
+        post_resp.ok = True
+        svc._session.post.return_value = post_resp
+        svc._session.get.side_effect = requests.exceptions.ReadTimeout(
+            "poll read timed out"
+        )
+        with pytest.raises(TimeoutError) as exc_info:
+            svc.generate_index("my-arcana", poll_interval=0.01, timeout=0.05)
+        msg = str(exc_info.value)
+        assert "did not complete" in msg
+        assert "poll read timed out" in msg  # the transport error is surfaced
+        assert "Last status" not in msg  # never got a successful status read
+
 
 def test_generate_index_wait_false_uses_dedicated_session(monkeypatch):
     """wait=False fires the trigger on its OWN Session (not the shared one)
@@ -326,3 +362,104 @@ class TestSyncDirectory:
         svc.list_files = MagicMock(return_value=[])
         with pytest.raises(ValueError, match="select"):
             svc.sync_directory("my-arcana", tmp_path, select=lambda p, r: "bogus")
+
+
+class TestDefaultTimeout:
+    """Every ARCANA control-plane call must carry a timeout so a server that
+    accepts a request but never responds raises instead of hanging forever
+    (``requests.Session`` has no native default timeout)."""
+
+    def test_default_timeout_injected_when_unset(self):
+        svc = _make_service()
+        svc._session.delete.return_value = _ok_response()
+        svc.delete_file("my-arcana", "f.txt")
+        assert svc._session.delete.call_args.kwargs["timeout"] == (10.0, 60.0)
+
+    def test_explicit_call_timeout_is_preserved(self):
+        # heartbeat passes its own timeout=10; the default must not clobber it.
+        svc = _make_service()
+        resp = MagicMock()
+        resp.status_code = 204
+        svc._session.get.return_value = resp
+        assert svc.heartbeat() is True
+        assert svc._session.get.call_args.kwargs["timeout"] == 10
+
+    def test_configured_timeout_is_used(self):
+        svc = _make_service()
+        svc._timeout = (3.0, 12.0)
+        svc._session.get.return_value = _ok_response()
+        svc.list_files("my-arcana")
+        assert svc._session.get.call_args.kwargs["timeout"] == (3.0, 12.0)
+
+    def test_timeout_propagates_from_single_call(self):
+        """A single-file method does not swallow the timeout — it propagates."""
+        svc = _make_service()
+        svc._session.delete.side_effect = requests.exceptions.ReadTimeout(
+            "read timed out"
+        )
+        with pytest.raises(requests.exceptions.ReadTimeout):
+            svc.delete_file("my-arcana", "f.txt")
+
+    def test_batch_records_timeout_per_file_and_continues(self, tmp_path):
+        """In a batch, a per-file timeout is recorded and the loop carries on —
+        it neither hangs nor aborts the whole batch (the reported repro)."""
+        svc = _make_service()
+        (tmp_path / "a.txt").write_text("a")
+        (tmp_path / "b.txt").write_text("b")
+        svc._session.delete.side_effect = [
+            requests.exceptions.ReadTimeout("read timed out"),
+            _ok_response(),
+        ]
+        results = svc.delete_directory("my-arcana", tmp_path)
+        by_file = {r["file"]: r["status"] for r in results}
+        assert by_file == {"a.txt": "failed", "b.txt": "deleted"}
+        failed = next(r for r in results if r["status"] == "failed")
+        assert "read timed out" in failed["error"]
+
+
+class TestOnResultHook:
+    """The per-file callback lets callers record provenance / transaction logs
+    without reimplementing the upload loop (downstream consumer feedback)."""
+
+    def test_upload_files_invokes_on_result_per_file_in_order(self, tmp_path):
+        svc = _make_service()
+        svc._session.put.return_value = _ok_response()
+        f1 = tmp_path / "a.txt"
+        f1.write_text("a")
+        f2 = tmp_path / "b.txt"
+        f2.write_text("b")
+        seen = []
+        svc.upload_files(
+            "kb", [f1, f2], on_result=lambda p, e: seen.append((p, e["status"]))
+        )
+        assert seen == [(f1, "uploaded"), (f2, "uploaded")]
+
+    def test_on_result_reports_failure_with_error(self, tmp_path):
+        svc = _make_service()
+        svc._session.put.return_value = _ok_response()
+        seen = []
+        svc.upload_files(
+            "kb", [tmp_path / "missing.txt"], on_result=lambda p, e: seen.append(e)
+        )
+        assert seen[0]["status"] == "failed"
+        assert "error" in seen[0]
+
+    def test_sync_directory_invokes_on_result_for_local_files(self, tmp_path):
+        svc = _make_service()
+        (tmp_path / "new.txt").write_text("n")
+        (tmp_path / "keep.txt").write_text("k")
+        svc.list_files = MagicMock(return_value=[{"name": "keep.txt"}])
+        svc.upload = MagicMock(return_value={"status": "ok"})
+        svc.generate_index = MagicMock(return_value=None)
+        seen = {}
+
+        def select(path, remote):
+            return "upload" if remote is None else "skip"
+
+        svc.sync_directory(
+            "kb",
+            tmp_path,
+            select=select,
+            on_result=lambda p, e: seen.__setitem__(p.name, e["status"]),
+        )
+        assert seen == {"new.txt": "uploaded", "keep.txt": "skipped"}

{saia_python-0.4.1 → saia_python-0.5.0}/tests/test_auth.py

@@ -330,6 +330,7 @@ class TestArcanaSummary:
         svc._base_url = "https://example.com/v1"
         svc._arcana_base = "https://example.com/v1/arcanas/api/v1"
         svc._api_key = "test"
+        svc._timeout = (10.0, 60.0)
 
         mock_resp = MagicMock()
         mock_resp.status_code = 200

{saia_python-0.4.1 → saia_python-0.5.0}/tests/test_client.py

@@ -17,6 +17,7 @@ def _make_client() -> SAIAClient:
     client = SAIAClient.__new__(SAIAClient)
     client._base_url = "https://example.com/v1"
     client._session = MagicMock()
+    client._timeout = (10.0, 60.0)
     return client
 
 
@@ -57,3 +58,11 @@ def test_get_rate_limits_raises_on_403():
     client._session.get.return_value = _resp(403, text="Forbidden")
     with pytest.raises(AuthenticationError):
         client.get_rate_limits()
+
+
+def test_get_rate_limits_probe_carries_timeout():
+    """The probe GET must carry a timeout so a stalled server can't hang it."""
+    client = _make_client()
+    client._session.get.return_value = _resp(400)
+    client.get_rate_limits()
+    assert client._session.get.call_args.kwargs["timeout"] == (10.0, 60.0)

{saia_python-0.4.1 → saia_python-0.5.0}/tests/test_models.py

@@ -30,7 +30,10 @@ def test_list_raw_returns_envelope_not_unwrapped():
     result = svc.list_raw()
     assert result["object"] == "list"  # envelope preserved, not unwrapped
     assert result["data"] == _ENVELOPE["data"]
-    session.get.assert_called_once_with("https://example.com/v1/models")
+    # GET /models (not POST), and carries the default timeout so it can't hang.
+    session.get.assert_called_once_with(
+        "https://example.com/v1/models", timeout=(10.0, 60.0)
+    )
 
 
 def test_list_unwraps_data_from_envelope():
@@ -48,3 +51,15 @@ def test_list_handles_bare_list_response():
     svc, _ = _service(bare)
     assert svc.list() == bare
     assert svc.list_raw() == bare
+
+
+def test_configured_timeout_is_forwarded():
+    """A custom timeout passed to the constructor reaches the GET /models call."""
+    session = MagicMock()
+    resp = MagicMock()
+    resp.ok = True
+    resp.json.return_value = _ENVELOPE
+    session.get.return_value = resp
+    svc = ModelsService(session, "https://example.com/v1", timeout=(3.0, 9.0))
+    svc.list_raw()
+    assert session.get.call_args.kwargs["timeout"] == (3.0, 9.0)