saia-python 0.8.0__tar.gz → 0.10.0__tar.gz

{saia_python-0.8.0/saia_python.egg-info → saia_python-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.8.0
+Version: 0.10.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only
@@ -22,6 +22,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Framework :: AsyncIO
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
@@ -31,6 +32,8 @@ Requires-Dist: tqdm>=4.60
 Requires-Dist: tomlkit>=0.12
 Provides-Extra: openai
 Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
 Provides-Extra: tokenizer
 Requires-Dist: transformers>=4.40; extra == "tokenizer"
 Requires-Dist: huggingface-hub>=0.20; extra == "tokenizer"
@@ -39,7 +42,8 @@ Requires-Dist: sentencepiece>=0.1.99; extra == "tokenizer"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov>=4.0; extra == "test"
-Requires-Dist: saia-python[openai]; extra == "test"
+Requires-Dist: pydantic>=2; extra == "test"
+Requires-Dist: saia-python[async,openai]; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0; extra == "docs"
 Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
@@ -113,11 +117,57 @@ list_model_ids()
 chat_completion(model="meta-llama-3.1-8b-instruct", messages=[...])
 ```
 
+### Async
+
+For concurrent workloads (e.g. an ASGI service), install the `[async]` extra and
+use `AsyncSAIAClient` — the `httpx.AsyncClient` twin of the data plane, carrying
+the **same** `RetryPolicy` and rate-limit handling as the sync client (not the
+`openai_async` shim, which bypasses them):
+
+```bash
+pip install saia-python[async]
+```
+
+```python
+import asyncio
+from saia_python.aio import AsyncSAIAClient
+
+
+async def main():
+    async with AsyncSAIAClient() as client:
+        # Non-streaming RAG chat
+        answer = await client.arcana.chat(
+            model="openai-gpt-oss-120b",
+            messages=[{"role": "user", "content": "Summarise the DLBCL first line."}],
+            arcana_id="owner/kb",
+        )
+        print(answer["choices"][0]["message"]["content"])
+
+        # Streaming plain chat — retry=False fails fast with an informative 429
+        stream = await client.chat.completions(
+            model="meta-llama-3.1-8b-instruct",
+            messages=[{"role": "user", "content": "Hello!"}],
+            stream=True,
+            retry=False,
+        )
+        async for chunk in stream:
+            ...
+
+
+asyncio.run(main())
+```
+
+Async covers the data plane (chat, ARCANA RAG chat, streaming) plus the
+read-only control-plane calls (`models`, arcana `version`/`heartbeat`/`list`/
+`get`, `health_check`). File upload/index/sync, voice, and document conversion
+remain synchronous on `SAIAClient` — see
+[ADR-0007](docs/adr/0007-native-async-transport.md).
+
 ## Supported Services
 
 | Service | Description | GWDG Docs |
 |---------|-------------|-----------|
-| **Chat AI** | Chat completions with streaming and tool calling | [Chat AI](https://docs.hpc.gwdg.de/services/ai-services/chat-ai/index.html) |
+| **Chat AI** | Chat completions with streaming, tool calling, and structured output (Pydantic) | [Chat AI](https://docs.hpc.gwdg.de/services/ai-services/chat-ai/index.html) |
 | **Voice AI** | Audio transcription and translation (Whisper) | [Voice AI](https://docs.hpc.gwdg.de/services/ai-services/voice-ai/index.html) |
 | **ARCANA** | RAG — knowledge base management and retrieval-augmented chat | [ARCANA](https://docs.hpc.gwdg.de/services/ai-services/arcana/index.html) |
 | **Documents** | PDF/document conversion via Docling | [SAIA API](https://docs.hpc.gwdg.de/services/ai-services/saia/index.html) |

{saia_python-0.8.0 → saia_python-0.10.0}/README.md

@@ -56,11 +56,57 @@ list_model_ids()
 chat_completion(model="meta-llama-3.1-8b-instruct", messages=[...])
 ```
 
+### Async
+
+For concurrent workloads (e.g. an ASGI service), install the `[async]` extra and
+use `AsyncSAIAClient` — the `httpx.AsyncClient` twin of the data plane, carrying
+the **same** `RetryPolicy` and rate-limit handling as the sync client (not the
+`openai_async` shim, which bypasses them):
+
+```bash
+pip install saia-python[async]
+```
+
+```python
+import asyncio
+from saia_python.aio import AsyncSAIAClient
+
+
+async def main():
+    async with AsyncSAIAClient() as client:
+        # Non-streaming RAG chat
+        answer = await client.arcana.chat(
+            model="openai-gpt-oss-120b",
+            messages=[{"role": "user", "content": "Summarise the DLBCL first line."}],
+            arcana_id="owner/kb",
+        )
+        print(answer["choices"][0]["message"]["content"])
+
+        # Streaming plain chat — retry=False fails fast with an informative 429
+        stream = await client.chat.completions(
+            model="meta-llama-3.1-8b-instruct",
+            messages=[{"role": "user", "content": "Hello!"}],
+            stream=True,
+            retry=False,
+        )
+        async for chunk in stream:
+            ...
+
+
+asyncio.run(main())
+```
+
+Async covers the data plane (chat, ARCANA RAG chat, streaming) plus the
+read-only control-plane calls (`models`, arcana `version`/`heartbeat`/`list`/
+`get`, `health_check`). File upload/index/sync, voice, and document conversion
+remain synchronous on `SAIAClient` — see
+[ADR-0007](docs/adr/0007-native-async-transport.md).
+
 ## Supported Services
 
 | Service | Description | GWDG Docs |
 |---------|-------------|-----------|
-| **Chat AI** | Chat completions with streaming and tool calling | [Chat AI](https://docs.hpc.gwdg.de/services/ai-services/chat-ai/index.html) |
+| **Chat AI** | Chat completions with streaming, tool calling, and structured output (Pydantic) | [Chat AI](https://docs.hpc.gwdg.de/services/ai-services/chat-ai/index.html) |
 | **Voice AI** | Audio transcription and translation (Whisper) | [Voice AI](https://docs.hpc.gwdg.de/services/ai-services/voice-ai/index.html) |
 | **ARCANA** | RAG — knowledge base management and retrieval-augmented chat | [ARCANA](https://docs.hpc.gwdg.de/services/ai-services/arcana/index.html) |
 | **Documents** | PDF/document conversion via Docling | [SAIA API](https://docs.hpc.gwdg.de/services/ai-services/saia/index.html) |

{saia_python-0.8.0 → saia_python-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "saia-python"
-version = "0.8.0"
+version = "0.10.0"
 description = "Python wrapper for the GWDG SAIA platform REST API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -37,6 +37,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
     "Topic :: Software Development :: Libraries :: Python Modules",
+    "Framework :: AsyncIO",
     "Typing :: Typed",
 ]
 dependencies = [
@@ -62,6 +63,11 @@ saia_python = ["py.typed"]
 openai = [
     "openai>=1.0",
 ]
+async = [
+    # httpx.AsyncClient backs the native async transport (saia_python.aio).
+    # requests stays the sync core; httpx is pulled only when you want async.
+    "httpx>=0.27",
+]
 tokenizer = [
     # AutoTokenizer + chat-template (apply_chat_template) engine
     "transformers>=4.40",
@@ -75,7 +81,9 @@ tokenizer = [
 test = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
-    "saia-python[openai]",
+    # the structured-output tests define Pydantic v2 models
+    "pydantic>=2",
+    "saia-python[openai,async]",
 ]
 docs = [
     "sphinx>=7.0",
@@ -119,9 +127,15 @@ module = "saia_python.auth"
 disable_error_code = ["index", "operator", "union-attr", "call-arg"]
 
 [[tool.mypy.overrides]]
-# `ModelsService.list` / `ArcanaService.list` shadow the builtin `list`, so
-# `list[...]` annotations inside these classes resolve to the method rather than
-# the type. Renaming would break the public API; scoped out until the
-# annotations are qualified (e.g. `builtins.list`).
-module = ["saia_python.models", "saia_python.arcana"]
+# `ModelsService.list` / `ArcanaService.list` (and their async twins in
+# `saia_python.aio`) shadow the builtin `list`, so `list[...]` annotations inside
+# these classes resolve to the method rather than the type. Renaming would break
+# the public API; scoped out until the annotations are qualified (e.g.
+# `builtins.list`).
+module = ["saia_python.models", "saia_python.arcana", "saia_python.aio"]
 disable_error_code = ["valid-type"]
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+]

{saia_python-0.8.0 → saia_python-0.10.0}/saia_python/__init__.py

@@ -18,6 +18,12 @@ import concurrent.futures
 from importlib.metadata import PackageNotFoundError, version
 
 from ._http import RetryPolicy
+from ._payloads import (
+    INFERENCE_SERVICE,
+    apply_arcana_fields,
+    arcana_chat_headers,
+    build_chat_body,
+)
 from ._streaming import SSEStream
 from .arcana_references import (
     ArcanaReference,
@@ -38,10 +44,17 @@ from .auth import (
 )
 from .client import SAIAClient
 from .documents import ConversionImage, ConversionResult
-from .exceptions import APIError, AuthenticationError, RateLimitError, SAIAError
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    SAIAError,
+    StructuredOutputError,
+)
 from .openai_compat import create_openai_client
-from .rate_limits import RateLimitInfo, parse_rate_limits
+from .rate_limits import RateLimitInfo, format_rate_limit_error, parse_rate_limits
 from .responses import text_of
+from .structured import parse_structured, response_format_for
 from .tokenizer import (
     DEFAULT_TOKENIZER_DIR,
     GWDG_MODEL_REPOS,
@@ -92,12 +105,22 @@ __all__ = [
     "AuthenticationError",
     "RateLimitError",
     "APIError",
+    "StructuredOutputError",
     # Rate limits
     "RateLimitInfo",
     "parse_rate_limits",
+    "format_rate_limit_error",
+    # Request builders (pure — shared by sync, async, and external gateways)
+    "build_chat_body",
+    "apply_arcana_fields",
+    "arcana_chat_headers",
+    "INFERENCE_SERVICE",
     # Response helpers
     "text_of",
     "SSEStream",
+    # Structured output (Pydantic v2 models)
+    "response_format_for",
+    "parse_structured",
     # ARCANA reference parsing
     "ArcanaReference",
     "ParsedReferences",
@@ -142,6 +165,23 @@ __all__ = [
     "ConversionImage",
 ]
 
+# Async API (the ``[async]`` extra: ``pip install saia-python[async]``). Exposed
+# lazily so importing ``saia_python`` never pulls ``httpx`` for sync-only users;
+# ``from saia_python import AsyncSAIAClient`` still works when httpx is present.
+# Kept OUT of ``__all__`` so ``from saia_python import *`` stays httpx-free.
+_ASYNC_EXPORTS = frozenset(
+    {"AsyncSAIAClient", "AsyncChatService", "AsyncArcanaService", "AsyncModelsService"}
+)
+
+
+def __getattr__(name: str):
+    """Lazily resolve the async client from :mod:`saia_python.aio` on access."""
+    if name in _ASYNC_EXPORTS:
+        from . import aio
+
+        return getattr(aio, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 def _make_client(api_key: str | None = None, base_url: str | None = None) -> SAIAClient:
     kwargs: dict = {}

saia_python-0.10.0/saia_python/_async_http.py

@@ -0,0 +1,127 @@
+"""Async HTTP plumbing — the ``httpx.AsyncClient`` twin of :mod:`saia_python._http`.
+
+Mirrors :func:`~saia_python._http.execute` and
+:func:`~saia_python._http.post_chat_completion` over ``httpx.AsyncClient``,
+**reusing the pure retry brains** (:class:`~saia_python._http.RetryPolicy`,
+``_plan``, ``_jitter``) and :func:`~saia_python.rate_limits.parse_rate_limits`
+unchanged — so the sync and async paths can never drift on rate-limit handling.
+Only the socket-touching parts (``await client.request(...)`` /
+``await resp.aclose()`` / ``await asyncio.sleep(...)``) are re-implemented.
+
+This module never imports ``httpx`` at runtime — it only *calls methods* on a
+client object the caller supplies, so it stays import-safe without the
+``[async]`` extra and is trivially testable with a fake client. Construct the
+client via :class:`saia_python.aio.AsyncSAIAClient` (or pass your own
+``httpx.AsyncClient``).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any
+
+from ._http import RetryPolicy, _jitter, _plan
+from .exceptions import raise_for_status
+from .rate_limits import parse_rate_limits
+
+if TYPE_CHECKING:
+    import httpx
+
+log = logging.getLogger(__name__)
+
+#: An awaitable ``sleep(seconds)`` — ``asyncio.sleep`` in production; tests pass
+#: a recorder so they never actually block.
+AsyncSleep = Callable[..., Awaitable[Any]]
+
+
+async def aexecute(
+    client: httpx.AsyncClient,
+    method: str,
+    url: str,
+    *,
+    policy: RetryPolicy,
+    idempotent: bool,
+    sleep: AsyncSleep = asyncio.sleep,
+    **kwargs: Any,
+) -> httpx.Response:
+    """Issue a request under a transport policy and return the response.
+
+    The async analogue of :func:`saia_python._http.execute`: dispatches
+    ``getattr(client, method)(url, **kwargs)`` (``method`` is the lowercase verb
+    — ``"post"`` / ``"get"`` — matching the sync seam) and, on HTTP 429 that the
+    ``policy`` permits, waits per :func:`~saia_python._http._plan` and retries.
+
+    Like the sync version 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 status + headers are inspected —
+    never the body — so a give-up never consumes the response. Streaming is a
+    separate seam (:class:`saia_python.aio.AsyncSSEStream`), because ``httpx``
+    exposes a streamed body only inside ``client.stream(...)``.
+    """
+    attempt = 0
+    while True:
+        resp = await getattr(client, 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
+        await resp.aclose()
+        attempt += 1
+        wait += _jitter(policy)
+        log.info("SAIA rate limit (429) — waiting %.1fs before retry %d", wait, attempt)
+        await sleep(wait)
+
+
+async def apost_chat_completion(
+    client: httpx.AsyncClient,
+    url: str,
+    body: dict,
+    *,
+    headers: dict | None = None,
+    stream: bool = False,
+    policy: RetryPolicy | None = None,
+    sleep: AsyncSleep = asyncio.sleep,
+) -> dict | Any:
+    """POST a chat-completion request and normalise the response (async).
+
+    The async twin of :func:`saia_python._http.post_chat_completion`. For
+    ``stream=False`` it returns the response dict with an extra
+    ``"_rate_limits"`` key; for ``stream=True`` it returns a connected
+    :class:`~saia_python.aio.AsyncSSEStream` (imported lazily to avoid a cycle),
+    with the initial-429 retry already applied *before* the stream is exposed —
+    never mid-stream, exactly like the sync path.
+    """
+    policy = policy if policy is not None else RetryPolicy()
+    if stream:
+        from ._async_streaming import AsyncSSEStream
+
+        stream_body = {**body, "stream": True}
+        stream_headers = {**(headers or {}), "Accept": "text/event-stream"}
+        return await AsyncSSEStream.open(
+            client,
+            url,
+            json=stream_body,
+            headers=stream_headers,
+            policy=policy,
+            sleep=sleep,
+        )
+
+    resp = await aexecute(
+        client,
+        "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.10.0/saia_python/_async_streaming.py

@@ -0,0 +1,157 @@
+"""Async SSE streaming — the ``httpx.AsyncClient`` twin of :mod:`saia_python._streaming`.
+
+``httpx`` only exposes a streamed body inside an ``async with client.stream(...)``
+context, so unlike the sync :class:`~saia_python._streaming.SSEStream` (which
+wraps an already-open ``requests`` response) this class **owns** that context
+manager: :meth:`AsyncSSEStream.open` enters it — retrying an initial 429 *before*
+any body is exposed, exactly like the sync path — and :meth:`aclose` / the
+``async with`` protocol exits it.
+
+Like :mod:`saia_python._async_http`, this module never imports ``httpx`` at
+runtime; it only calls methods on the client / response the caller supplies,
+staying import-safe without the ``[async]`` extra and trivially fakeable in tests.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import TYPE_CHECKING, Any
+
+from ._async_http import AsyncSleep
+from ._http import RetryPolicy, _jitter, _plan
+from .exceptions import raise_for_status
+from .rate_limits import parse_rate_limits
+
+if TYPE_CHECKING:
+    import httpx
+
+log = logging.getLogger(__name__)
+
+
+class AsyncSSEStream:
+    """Async iterable over the SSE chunks of an ``httpx`` streaming response.
+
+    The async twin of :class:`~saia_python._streaming.SSEStream`. Two
+    consumption modes — pick **one**, because a streamed body can only be read
+    once:
+
+    * ``async for chunk in stream`` — decoded ``dict`` chunks (the high-level
+      API). Surfaces a typed error (:class:`~saia_python.RateLimitError` with an
+      informative message on 429, etc.) *before* the first chunk if the upstream
+      status is an error.
+    * ``async for line in stream.aiter_lines()`` — the raw decoded ``str`` SSE
+      lines. Does **not** raise, so a gateway can frame upstream errors itself
+      (this is what the AVOR adapter uses to keep its verbatim ``[DONE]`` /
+      non-``data:`` line passthrough).
+
+    Either way, use it as an async context manager (``async with stream:``) or
+    call :meth:`aclose` so the upstream connection is released.
+
+    Attributes:
+        status_code: The final upstream status code (after any retry).
+        rate_limits: A JSON-serializable dict of the response's rate-limit
+            headers (available immediately — headers arrive before the body).
+    """
+
+    def __init__(self, cm: Any, response: httpx.Response):
+        self._cm: Any = cm
+        self._response = response
+        self.status_code: int = response.status_code
+        self.rate_limits: dict = parse_rate_limits(response.headers).to_dict()
+
+    @classmethod
+    async def open(
+        cls,
+        client: httpx.AsyncClient,
+        url: str,
+        *,
+        json: dict,
+        headers: dict | None = None,
+        policy: RetryPolicy | None = None,
+        sleep: AsyncSleep = asyncio.sleep,
+    ) -> AsyncSSEStream:
+        """Open the stream, retrying an initial 429 before exposing the body.
+
+        Mirrors :func:`saia_python._http.execute`'s retry loop, but over
+        ``client.stream(...)``: it enters the context, and on a retryable 429
+        exits it (releasing the socket) and re-issues after the planned wait.
+        Only status + headers are inspected, so the streamed body is never
+        consumed by the retry decision. Returns a connected stream whose
+        ``status_code`` reflects the final attempt (which may still be an error
+        the caller inspects).
+        """
+        policy = policy if policy is not None else RetryPolicy()
+        attempt = 0
+        while True:
+            cm = client.stream("POST", url, json=json, headers=headers)
+            response = await cm.__aenter__()
+            if response.status_code != 429 or not policy.applies(True):
+                return cls(cm, response)
+            wait = _plan(parse_rate_limits(response.headers), policy, attempt)
+            if wait is None:
+                return cls(cm, response)
+            await cm.__aexit__(None, None, None)
+            attempt += 1
+            wait += _jitter(policy)
+            log.info(
+                "SAIA rate limit (429) — waiting %.1fs before retry %d", wait, attempt
+            )
+            await sleep(wait)
+
+    async def aiter_lines(self) -> AsyncIterator[str]:
+        """Yield the raw decoded SSE lines (no dict parsing, no raise).
+
+        The low-level surface: the caller sees every line verbatim (``data:``
+        payloads, ``data: [DONE]``, blank event terminators) and decides how to
+        frame errors and what to forward. Releases the connection when the
+        consumer stops, whether it finished, broke early, or was cancelled.
+        """
+        try:
+            async for raw in self._response.aiter_lines():
+                yield raw if isinstance(raw, str) else raw.decode("utf-8")
+        finally:
+            await self.aclose()
+
+    async def __aiter__(self) -> AsyncIterator[dict]:
+        """Yield decoded ``dict`` chunks (high-level; raises on an error status).
+
+        Copies the sync :func:`~saia_python._streaming.iter_sse` decision logic
+        verbatim: skip non-``data:`` lines, stop on ``[DONE]``, ``json.loads``
+        each payload, silently skip an unparseable one.
+        """
+        if self.status_code >= 400:
+            await self._response.aread()
+            raise_for_status(self._response)
+        try:
+            async for raw in self._response.aiter_lines():
+                line = raw if isinstance(raw, str) else raw.decode("utf-8")
+                if not line or not line.startswith("data:"):
+                    continue
+                payload = line[len("data:") :].strip()
+                if payload == "[DONE]":
+                    return
+                try:
+                    yield json.loads(payload)
+                except json.JSONDecodeError:
+                    continue
+        finally:
+            await self.aclose()
+
+    async def aread(self) -> bytes:
+        """Read and return the full upstream body (used to frame an error)."""
+        return await self._response.aread()
+
+    async def aclose(self) -> None:
+        """Release the upstream connection. Idempotent."""
+        if self._cm is not None:
+            cm, self._cm = self._cm, None
+            await cm.__aexit__(None, None, None)
+
+    async def __aenter__(self) -> AsyncSSEStream:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()

saia_python-0.10.0/saia_python/_payloads.py

@@ -0,0 +1,81 @@
+"""Pure request-body / header builders shared across transports.
+
+Transport-free — no ``Session``, no ``httpx.AsyncClient``, no I/O — so these
+helpers are reused **verbatim** by the sync services (:mod:`saia_python.chat`,
+:mod:`saia_python.arcana`), the async services (:mod:`saia_python.aio`), and
+external gateways that assemble the request themselves (the AVOR adapter builds
+its own body so it can inject a per-conversation system prompt, then reuses
+:func:`apply_arcana_fields` to keep the ARCANA injection identical to ours).
+
+Keeping the ARCANA injection in ONE place matters: GWDG only routes a request
+through the retrieval pipeline when **all three** of ``enable-tools`` + the
+``arcana.id`` body field *and* the ``inference-service`` header are present.
+Drop any one and the request still returns 200 — but with no retrieval. That
+invariant now lives in :func:`apply_arcana_fields` + :func:`arcana_chat_headers`
+instead of being retyped at every call site.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+#: The GWDG gateway value that opts a chat request into the ARCANA retrieval
+#: pipeline. Sent as the ``inference-service`` header (see
+#: :func:`arcana_chat_headers`); without it retrieval never fires.
+INFERENCE_SERVICE = "saia-openai-gateway"
+
+
+def build_chat_body(
+    model: str,
+    messages: list[dict],
+    *,
+    temperature: float | None = None,
+    top_p: float | None = None,
+    max_tokens: int | None = None,
+    **kwargs: Any,
+) -> dict:
+    """Assemble an OpenAI-shaped ``/chat/completions`` request body.
+
+    The sampling knobs are omitted from the body when ``None`` (so the server's
+    own defaults apply) rather than being sent as ``null``. Extra ``kwargs`` are
+    merged verbatim, letting callers pass ``stop``, ``stream``, ``seed``, etc.
+    """
+    body: dict = {"model": model, "messages": messages, **kwargs}
+    if temperature is not None:
+        body["temperature"] = temperature
+    if top_p is not None:
+        body["top_p"] = top_p
+    if max_tokens is not None:
+        body["max_tokens"] = max_tokens
+    return body
+
+
+def apply_arcana_fields(body: dict, arcana_id: str) -> dict:
+    """Return ``body`` with the ARCANA RAG **body** fields injected.
+
+    Adds ``enable-tools: true`` and ``arcana: {"id": arcana_id}``. Returns a
+    **new** dict (the input is left unmutated) with the ARCANA fields applied
+    last, so they cannot be silently clobbered by an earlier body key. This is
+    the body half of the three-part retrieval invariant; pair it with
+    :func:`arcana_chat_headers` (or set the ``inference-service`` header
+    yourself) for the header half.
+    """
+    return {**body, "enable-tools": True, "arcana": {"id": arcana_id}}
+
+
+def arcana_chat_headers(api_key: str, *, extra: dict | None = None) -> dict:
+    """Build the header set for an ARCANA chat call.
+
+    ``Bearer`` auth + ``Accept: application/json`` + the ``inference-service``
+    gateway header (the header half of the retrieval invariant). ``extra`` is
+    merged last, so a caller can add a correlation id (e.g. ``X-Request-ID``)
+    without losing the required headers.
+    """
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Accept": "application/json",
+        "inference-service": INFERENCE_SERVICE,
+    }
+    if extra:
+        headers.update(extra)
+    return headers