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

{saia_python-0.9.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.9.0
+Version: 0.10.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only
@@ -42,6 +42,7 @@ 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: pydantic>=2; extra == "test"
 Requires-Dist: saia-python[async,openai]; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0; extra == "docs"
@@ -166,7 +167,7 @@ remain synchronous on `SAIAClient` — see
 
 | 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.9.0 → saia_python-0.10.0}/README.md

@@ -106,7 +106,7 @@ remain synchronous on `SAIAClient` — see
 
 | 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.9.0 → saia_python-0.10.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "saia-python"
-version = "0.9.0"
+version = "0.10.0"
 description = "Python wrapper for the GWDG SAIA platform REST API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -81,6 +81,8 @@ tokenizer = [
 test = [
     "pytest>=7.0",
     "pytest-cov>=4.0",
+    # the structured-output tests define Pydantic v2 models
+    "pydantic>=2",
     "saia-python[openai,async]",
 ]
 docs = [
@@ -132,3 +134,8 @@ disable_error_code = ["index", "operator", "union-attr", "call-arg"]
 # `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.9.0 → saia_python-0.10.0}/saia_python/__init__.py

@@ -44,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, 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,
@@ -98,6 +105,7 @@ __all__ = [
     "AuthenticationError",
     "RateLimitError",
     "APIError",
+    "StructuredOutputError",
     # Rate limits
     "RateLimitInfo",
     "parse_rate_limits",
@@ -110,6 +118,9 @@ __all__ = [
     # Response helpers
     "text_of",
     "SSEStream",
+    # Structured output (Pydantic v2 models)
+    "response_format_for",
+    "parse_structured",
     # ARCANA reference parsing
     "ArcanaReference",
     "ParsedReferences",

{saia_python-0.9.0 → saia_python-0.10.0}/saia_python/aio.py

@@ -41,7 +41,7 @@ the two transports cannot drift.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from ._async_http import aexecute, apost_chat_completion
 from ._async_streaming import AsyncSSEStream
@@ -54,6 +54,7 @@ from ._payloads import (
 from .auth import resolve_credentials
 from .exceptions import raise_for_status
 from .rate_limits import RateLimitInfo, parse_rate_limits
+from .structured import ModelT, parse_structured, response_format_for
 
 if TYPE_CHECKING:
     import httpx
@@ -140,6 +141,38 @@ class AsyncChatService:
             policy=resolve_retry(self._retry, retry),
         )
 
+    async def completions_structured(
+        self,
+        model: str,
+        messages: list[dict],
+        response_model: type[ModelT],
+        *,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        max_tokens: int | None = None,
+        retry: RetryPolicy | bool | None = None,
+        **kwargs: Any,
+    ) -> ModelT:
+        """Return the answer as a validated ``response_model`` instance.
+
+        See :meth:`ChatService.completions_structured
+        <saia_python.chat.ChatService.completions_structured>`; raises
+        :class:`~saia_python.StructuredOutputError` when there is no answer
+        that validates.
+        """
+        response = await self.completions(
+            model,
+            messages,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stream=False,
+            retry=retry,
+            response_format=response_format_for(response_model),
+            **kwargs,
+        )
+        return parse_structured(cast(dict, response), response_model)
+
     def __repr__(self) -> str:
         return f"AsyncChatService(base_url={self._base_url!r})"
 

saia_python-0.10.0/saia_python/chat.py

@@ -0,0 +1,141 @@
+"""Chat service — completions and streaming."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from ._http import RetryPolicy, coerce_retry, post_chat_completion, resolve_retry
+from ._streaming import SSEStream
+from .structured import ModelT, parse_structured, response_format_for
+
+if TYPE_CHECKING:
+    import requests
+
+
+class ChatService:
+    """Access the ``/chat/completions`` endpoint.
+
+    Args:
+        session: A :class:`requests.Session` with auth headers configured.
+        base_url: The SAIA API base URL.
+    """
+
+    def __init__(
+        self,
+        session: requests.Session,
+        base_url: str,
+        *,
+        retry: RetryPolicy | bool | None = None,
+    ):
+        self._session = session
+        self._base_url = base_url
+        self._retry = coerce_retry(retry)
+
+    def completions(
+        self,
+        model: str,
+        messages: list[dict],
+        *,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        max_tokens: int | None = None,
+        stream: bool = False,
+        retry: RetryPolicy | bool | None = None,
+        **kwargs,
+    ) -> dict | SSEStream:
+        """Send a chat completion request.
+
+        Args:
+            model: Model identifier (e.g. ``"meta-llama-3.1-8b-instruct"``).
+            messages: List of message dicts with ``"role"`` and ``"content"`` keys.
+            temperature: Sampling temperature (0–2).
+            top_p: Nucleus sampling parameter (0–1).
+            max_tokens: Maximum tokens to generate.
+            stream: If ``True``, return a generator yielding chunks.
+            **kwargs: Additional parameters forwarded to the API.
+
+        Returns:
+            When ``stream=False``: the API response dict, with an extra
+            ``"_rate_limits"`` key — a JSON-serializable dict of the current
+            rate-limit headers (see :class:`~saia_python.RateLimitInfo`).
+            When ``stream=True``: an ``SSEStream`` — iterate it for the
+            response chunks; its ``rate_limits`` attribute exposes the same
+            dict (available immediately, from the response headers).
+        """
+        body = {"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 post_chat_completion(
+            self._session,
+            f"{self._base_url}/chat/completions",
+            body,
+            stream=stream,
+            policy=resolve_retry(self._retry, retry),
+        )
+
+    def completions_structured(
+        self,
+        model: str,
+        messages: list[dict],
+        response_model: type[ModelT],
+        *,
+        temperature: float | None = None,
+        top_p: float | None = None,
+        max_tokens: int | None = None,
+        retry: RetryPolicy | bool | None = None,
+        **kwargs,
+    ) -> ModelT:
+        """Send a chat completion and return the answer as a validated model.
+
+        Sends ``response_model``'s JSON Schema as the ``response_format`` (see
+        :func:`~saia_python.response_format_for`), which SAIA enforces on the
+        server, then validates the answer into an instance (see
+        :func:`~saia_python.parse_structured`). Non-streaming only. To keep the
+        raw response too (``usage``, ``_rate_limits``), call those two helpers
+        around :meth:`completions` yourself.
+
+        Args:
+            model: Model identifier (e.g. ``"meta-llama-3.1-8b-instruct"``).
+            messages: List of message dicts with ``"role"`` and ``"content"`` keys.
+                SAIA uses the schema only to constrain the output and does not
+                add it to the prompt, so say what each field should hold.
+            response_model: The Pydantic v2 model class the answer must match.
+            temperature: Sampling temperature (0–2).
+            top_p: Nucleus sampling parameter (0–1).
+            max_tokens: Maximum tokens to generate. Reasoning models think
+                before they answer, so leave room, or turn thinking off where
+                the chat template allows it (e.g. Qwen:
+                ``chat_template_kwargs={"enable_thinking": False}``).
+            retry: Overrides the service's rate-limit retry policy for this
+                call, as in :meth:`completions`.
+            **kwargs: Additional parameters forwarded to the API.
+
+        Returns:
+            An instance of ``response_model``.
+
+        Raises:
+            StructuredOutputError: The response holds no answer that validates,
+                e.g. because the token budget ran out (``finish_reason`` is
+                ``"length"``). The error keeps the full response, ``usage``
+                included.
+        """
+        response = self.completions(
+            model,
+            messages,
+            temperature=temperature,
+            top_p=top_p,
+            max_tokens=max_tokens,
+            stream=False,
+            retry=retry,
+            response_format=response_format_for(response_model),
+            **kwargs,
+        )
+        return parse_structured(cast(dict, response), response_model)
+
+    def __repr__(self):
+        return f"ChatService(base_url={self._base_url!r})"

{saia_python-0.9.0 → saia_python-0.10.0}/saia_python/exceptions.py

@@ -76,6 +76,32 @@ class APIError(SAIAError):
         super().__init__(message, status_code=status_code, response_body=response_body)
 
 
+class StructuredOutputError(SAIAError):
+    """Raised when a chat response holds no answer that validates against the
+    requested structured-output model.
+
+    The HTTP call itself succeeded, so ``status_code`` is ``None``; the message
+    says why the answer is unusable. The response stays attached, so a caller
+    can still read ``usage`` (the tokens were spent) or inspect the raw content.
+
+    Attributes:
+        response: The chat response dict the answer was read from.
+        finish_reason: The first choice's ``finish_reason`` — ``"length"`` means
+            the token budget ran out — or ``None`` when there was no choice.
+    """
+
+    def __init__(
+        self,
+        message: object,
+        *,
+        response: dict,
+        finish_reason: str | None = None,
+    ):
+        super().__init__(message)
+        self.response = response
+        self.finish_reason = finish_reason
+
+
 def _extract_detail(resp: Any) -> str:
     """Try to extract a human-readable message from a JSON error body.
 

saia_python-0.10.0/saia_python/structured.py

@@ -0,0 +1,130 @@
+"""Structured output — a Pydantic model in, a validated instance out.
+
+SAIA enforces a ``json_schema`` ``response_format`` on the server: its inference
+backend (vLLM) compiles the schema into a grammar and blocks every token that
+would break it, so the answer matches the schema by construction and needs no
+validate-and-retry loop. This module covers the two client-side ends:
+
+- :func:`response_format_for` turns a Pydantic model into the
+  ``response_format`` request field.
+- :func:`parse_structured` validates a chat response back into the model, and
+  raises :class:`~saia_python.StructuredOutputError` with the reason when there
+  is nothing usable — most often a reasoning model that spent its
+  ``max_tokens`` thinking.
+
+:meth:`ChatService.completions_structured
+<saia_python.chat.ChatService.completions_structured>` does both in one call.
+Use the two helpers directly when you also need the raw response, e.g. its
+``usage``::
+
+    resp = client.chat.completions(
+        model, messages, response_format=response_format_for(Invoice)
+    )
+    invoice = parse_structured(resp, Invoice)
+    tokens = resp["usage"]["total_tokens"]
+
+Needs Pydantic v2, which you already have if you define a model; the package
+itself imports it only inside :func:`parse_structured`.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, TypeVar
+
+from .exceptions import StructuredOutputError
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel
+
+ModelT = TypeVar("ModelT", bound="BaseModel")
+
+_TOKEN_HINT = (
+    "Reasoning models spend tokens thinking before they answer: raise max_tokens, "
+    "or turn thinking off where the chat template allows it (e.g. Qwen: "
+    "chat_template_kwargs={'enable_thinking': False})."
+)
+
+
+def response_format_for(response_model: type[BaseModel]) -> dict:
+    """Build the ``response_format`` request field for a Pydantic model.
+
+    ``strict`` is left unset: SAIA's backends enforce the schema either way,
+    whereas OpenAI's strict mode would reject a plain Pydantic schema (it
+    requires ``additionalProperties: false`` on every object).
+
+    Args:
+        response_model: A Pydantic v2 model class.
+
+    Returns:
+        ``{"type": "json_schema", "json_schema": {"name": ..., "schema": ...}}``
+        with the model's JSON Schema, named after the class (characters outside
+        ``a-z A-Z 0-9 _ -``, such as a generic's brackets, become ``_``).
+    """
+    name = re.sub(r"[^a-zA-Z0-9_-]", "_", response_model.__name__)[:64]
+    return {
+        "type": "json_schema",
+        "json_schema": {"name": name, "schema": response_model.model_json_schema()},
+    }
+
+
+def parse_structured(response: dict, response_model: type[ModelT]) -> ModelT:
+    """Validate a chat response's answer into ``response_model``.
+
+    Reads the first choice's ``content`` — the JSON string the model wrote — and
+    validates it with ``response_model.model_validate_json``. Works on any
+    OpenAI-style ChatCompletion dict, such as the one
+    :meth:`~saia_python.chat.ChatService.completions` returns.
+
+    Args:
+        response: A chat completion response dict.
+        response_model: The Pydantic v2 model class to validate into.
+
+    Returns:
+        The validated ``response_model`` instance.
+
+    Raises:
+        StructuredOutputError: When there is no usable answer: no choices; no
+            content (a reasoning model that ran out of tokens while thinking
+            returns ``content: None`` with ``finish_reason: "length"``); an
+            answer cut off at ``max_tokens``; or one that fails validation, with
+            the :class:`pydantic.ValidationError` chained as the cause.
+    """
+    from pydantic import ValidationError
+
+    name = response_model.__name__
+    choices = response.get("choices") or []
+    if not choices:
+        raise StructuredOutputError(
+            f"{name}: the response has no choices", response=response
+        )
+    finish_reason = choices[0].get("finish_reason")
+    message = choices[0].get("message") or {}
+    content = message.get("content")
+    if not content:
+        if finish_reason == "length":
+            reason = f"the model ran out of tokens before answering. {_TOKEN_HINT}"
+        elif message.get("refusal"):
+            reason = f"the model refused: {message['refusal']}"
+        else:
+            reason = f"the response has no content (finish_reason={finish_reason!r})"
+        raise StructuredOutputError(
+            f"{name}: {reason}", response=response, finish_reason=finish_reason
+        )
+    try:
+        return response_model.model_validate_json(content)
+    except ValidationError as exc:
+        # Validate before blaming finish_reason: an answer can be complete even
+        # when generation hit the limit afterwards (e.g. trailing whitespace).
+        if finish_reason == "length":
+            reason = f"the answer was cut off at max_tokens. {_TOKEN_HINT}"
+        else:
+            error = exc.errors()[0]
+            where = ".".join(str(part) for part in error["loc"])
+            detail = f"{where}: {error['msg']}" if where else error["msg"]
+            if exc.error_count() > 1:
+                detail += f"; {exc.error_count() - 1} more"
+            reason = f"the answer failed validation ({detail})"
+        raise StructuredOutputError(
+            f"{name}: {reason}", response=response, finish_reason=finish_reason
+        ) from exc

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: saia-python
-Version: 0.9.0
+Version: 0.10.0
 Summary: Python wrapper for the GWDG SAIA platform REST API
 Author: Friedrich Schwarz
 License-Expression: AGPL-3.0-only
@@ -42,6 +42,7 @@ 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: pydantic>=2; extra == "test"
 Requires-Dist: saia-python[async,openai]; extra == "test"
 Provides-Extra: docs
 Requires-Dist: sphinx>=7.0; extra == "docs"
@@ -166,7 +167,7 @@ remain synchronous on `SAIAClient` — see
 
 | 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.9.0 → saia_python-0.10.0}/saia_python.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ saia_python/openai_compat.py
 saia_python/py.typed
 saia_python/rate_limits.py
 saia_python/responses.py
+saia_python/structured.py
 saia_python/tokenizer.py
 saia_python/voice.py
 saia_python.egg-info/PKG-INFO
@@ -42,6 +43,8 @@ tests/test_client.py
 tests/test_documents.py
 tests/test_exceptions.py
 tests/test_health_check.py
+tests/test_live_responses_route.py
+tests/test_live_structured.py
 tests/test_models.py
 tests/test_openai_compat.py
 tests/test_payloads.py
@@ -50,6 +53,7 @@ tests/test_rate_limits.py
 tests/test_responses.py
 tests/test_setup_from_directory.py
 tests/test_streaming.py
+tests/test_structured.py
 tests/test_tokenizer.py
 tests/test_transport_policy.py
 tests/test_voice.py

{saia_python-0.9.0 → saia_python-0.10.0}/saia_python.egg-info/requires.txt

@@ -27,6 +27,7 @@ openai>=1.0
 [test]
 pytest>=7.0
 pytest-cov>=4.0
+pydantic>=2
 saia-python[async,openai]
 
 [tokenizer]

{saia_python-0.9.0 → saia_python-0.10.0}/tests/test_async_streaming.py

@@ -8,6 +8,7 @@ loop.
 from __future__ import annotations
 
 import asyncio
+import json
 
 import pytest
 
@@ -140,3 +141,26 @@ def test_aclose_is_idempotent():
 
     asyncio.run(_run())
     assert client.closed == 1
+
+
+def test_keeps_trailing_usage_chunk_with_empty_choices():
+    # Same contract as the sync twin: SAIA's final chunk has no choices but
+    # carries the token usage, and the stream must hand it over unchanged.
+    usage_chunk = {
+        "choices": [],
+        "usage": {"prompt_tokens": 104, "total_tokens": 124, "completion_tokens": 20},
+    }
+    lines = [
+        'data: {"choices": [{"delta": {"content": "Hi"}}]}',
+        f"data: {json.dumps(usage_chunk)}",
+        "data: [DONE]",
+    ]
+    client = FakeAsyncClient(
+        stream_responses=[FakeAsyncResponse(200, headers=rl_headers(), lines=lines)]
+    )
+
+    async def _run():
+        stream = await _open(client)
+        return [chunk async for chunk in stream]
+
+    assert asyncio.run(_run())[-1] == usage_chunk

saia_python-0.10.0/tests/test_live_responses_route.py

@@ -0,0 +1,61 @@
+"""Live check that SAIA's undocumented ``/v1/responses`` route still answers.
+
+GWDG's docs say SAIA does not provide OpenAI's Responses API, yet the route
+currently returns genuine Responses API objects. This test tracks that against
+the real service, so it needs an API key and the network. It is gated behind the
+``SAIA_RESPONSES_LIVE`` environment variable and never runs in CI or the offline
+gate by default::
+
+    SAIA_RESPONSES_LIVE=1 pytest tests/test_live_responses_route.py
+
+``SAIA_RESPONSES_LIVE_MODEL`` overrides the probed model. Keep it a
+non-reasoning model: a reasoning model can spend the small token budget thinking
+and come back ``incomplete``.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+import requests
+
+from saia_python import load_api_key, resolve_base_url
+
+MODEL = os.environ.get("SAIA_RESPONSES_LIVE_MODEL", "meta-llama-3.1-8b-instruct")
+
+
+@pytest.mark.skipif(
+    not os.environ.get("SAIA_RESPONSES_LIVE"),
+    reason="set SAIA_RESPONSES_LIVE=1 to run the network-backed /v1/responses check",
+)
+def test_live_responses_route_still_answers():
+    resp = requests.post(
+        f"{resolve_base_url()}/responses",
+        headers={"Authorization": f"Bearer {load_api_key()}"},
+        json={
+            "model": MODEL,
+            "instructions": "Answer in one word.",
+            "input": "What is the capital of France?",
+            "max_output_tokens": 16,
+        },
+        timeout=(10, 60),
+    )
+    if resp.status_code == 429:
+        pytest.skip("rate-limited (HTTP 429); cannot tell whether the route works")
+    assert resp.status_code == 200, f"HTTP {resp.status_code}: {resp.text[:300]}"
+
+    body = resp.json()
+    # Only the Responses API answers in this shape: Chat Completions would say
+    # "chat.completion", answer under "choices", and count prompt/completion tokens.
+    assert body["object"] == "response"
+    assert body["status"] == "completed"
+    texts = [
+        part["text"]
+        for item in body["output"]
+        if item.get("type") == "message"
+        for part in item.get("content", [])
+        if part.get("type") == "output_text"
+    ]
+    assert any(text.strip() for text in texts), body["output"]
+    assert {"input_tokens", "output_tokens"} <= body["usage"].keys()

saia_python-0.10.0/tests/test_live_structured.py

@@ -0,0 +1,50 @@
+"""Live check that SAIA still enforces a ``json_schema`` ``response_format``.
+
+Calls :meth:`ChatService.completions_structured` against the real service, so it
+needs an API key and the network. It is gated behind the
+``SAIA_STRUCTURED_LIVE`` environment variable and never runs in CI or the
+offline gate by default::
+
+    SAIA_STRUCTURED_LIVE=1 pytest tests/test_live_structured.py
+
+The prompt never mentions JSON, so a schema-shaped answer shows that the server
+enforces the schema, not that the model followed instructions.
+``SAIA_STRUCTURED_LIVE_MODEL`` overrides the model. No ``max_tokens`` is set, so
+a reasoning model has room to think before it answers.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+import pytest
+from pydantic import BaseModel
+
+from saia_python import RateLimitError, SAIAClient
+
+MODEL = os.environ.get("SAIA_STRUCTURED_LIVE_MODEL", "meta-llama-3.1-8b-instruct")
+
+
+class Sentiment(BaseModel):
+    label: Literal["positive", "negative", "neutral"]
+    confidence: float
+
+
+@pytest.mark.skipif(
+    not os.environ.get("SAIA_STRUCTURED_LIVE"),
+    reason="set SAIA_STRUCTURED_LIVE=1 to run the network-backed structured-output check",
+)
+def test_live_completions_structured_returns_a_validated_model():
+    try:
+        result = SAIAClient().chat.completions_structured(
+            MODEL,
+            [{"role": "user", "content": "Sentiment of: 'The update broke my build.'"}],
+            Sentiment,
+            retry=False,
+        )
+    except RateLimitError:
+        pytest.skip("rate-limited (HTTP 429); cannot tell whether the schema holds")
+    # completions_structured raises StructuredOutputError on anything unusable,
+    # so reaching this line means the answer validated.
+    assert isinstance(result, Sentiment)

{saia_python-0.9.0 → saia_python-0.10.0}/tests/test_streaming.py

@@ -1,5 +1,6 @@
 """Tests for saia_python._streaming — SSE line parsing."""
 
+import json
 from unittest.mock import MagicMock
 
 import pytest
@@ -98,3 +99,26 @@ class TestSSEStream:
         stream = SSEStream(resp)
         stream.close()
         resp.close.assert_called()
+
+    def test_keeps_trailing_usage_chunk_with_empty_choices(self):
+        # SAIA ends every chat stream with a chunk that has no choices but carries
+        # the token usage, even without stream_options.include_usage. Callers bill
+        # from it, so the stream must hand it over unchanged.
+        usage_chunk = {
+            "choices": [],
+            "usage": {
+                "prompt_tokens": 104,
+                "total_tokens": 124,
+                "completion_tokens": 20,
+            },
+        }
+        resp = _make_response(
+            [
+                'data: {"choices": [{"delta": {"content": "Hi"}}]}',
+                f"data: {json.dumps(usage_chunk)}",
+                "data: [DONE]",
+            ]
+        )
+        resp.headers = {}
+        chunks = list(SSEStream(resp))
+        assert chunks[-1] == usage_chunk

saia_python-0.10.0/tests/test_structured.py

@@ -0,0 +1,184 @@
+"""Tests for structured output — ``response_format_for``, ``parse_structured``,
+and ``completions_structured`` on the sync and async chat services.
+
+The error cases mirror what SAIA returned live (2026-10-08): a reasoning model
+that runs out of tokens while thinking answers HTTP 200 with ``content: None``
+and ``finish_reason: "length"``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Generic, Literal, TypeVar
+from unittest.mock import MagicMock
+
+import pytest
+from pydantic import BaseModel, ValidationError
+
+from saia_python import (
+    SAIAError,
+    StructuredOutputError,
+    parse_structured,
+    response_format_for,
+)
+from saia_python._http import RetryPolicy
+from saia_python.aio import AsyncChatService
+from saia_python.chat import ChatService
+
+from ._async_fakes import FakeAsyncClient, FakeAsyncResponse, rl_headers
+
+T = TypeVar("T")
+
+GOOD = '{"label": "negative", "confidence": 0.95}'
+
+
+class Sentiment(BaseModel):
+    label: Literal["positive", "negative", "neutral"]
+    confidence: float
+
+
+class Wrapper(BaseModel, Generic[T]):
+    value: T
+
+
+def _response(content, finish_reason="stop", **message):
+    return {
+        "choices": [
+            {
+                "message": {"role": "assistant", "content": content, **message},
+                "finish_reason": finish_reason,
+            }
+        ],
+        "usage": {"prompt_tokens": 21, "completion_tokens": 150, "total_tokens": 171},
+    }
+
+
+def _sync_service(json_body) -> ChatService:
+    svc = ChatService.__new__(ChatService)
+    svc._session = MagicMock()
+    svc._base_url = "https://example.com/v1"
+    svc._retry = RetryPolicy()
+    resp = MagicMock()
+    resp.ok = True
+    resp.status_code = 200
+    resp.headers = rl_headers()
+    resp.json.return_value = json_body
+    svc._session.post.return_value = resp
+    return svc
+
+
+def test_response_format_for_sends_the_model_schema():
+    assert response_format_for(Sentiment) == {
+        "type": "json_schema",
+        "json_schema": {"name": "Sentiment", "schema": Sentiment.model_json_schema()},
+    }
+
+
+def test_response_format_for_sanitizes_generic_model_names():
+    # OpenAI-style APIs allow only a-z, A-Z, 0-9, _ and - in the name.
+    assert response_format_for(Wrapper[int])["json_schema"]["name"] == "Wrapper_int_"
+
+
+def test_parse_structured_returns_validated_instance():
+    result = parse_structured(_response(GOOD), Sentiment)
+    assert result == Sentiment(label="negative", confidence=0.95)
+
+
+def test_reasoning_model_out_of_tokens_raises_with_hint():
+    resp = _response(None, finish_reason="length", reasoning="Okay, the user...")
+    with pytest.raises(StructuredOutputError) as info:
+        parse_structured(resp, Sentiment)
+    err = info.value
+    assert isinstance(err, SAIAError)
+    assert err.finish_reason == "length"
+    assert "max_tokens" in str(err)
+    assert "enable_thinking" in str(err)
+    # The tokens were spent, so a caller billing from usage can still read it.
+    assert err.response["usage"]["total_tokens"] == 171
+
+
+def test_answer_cut_off_at_max_tokens_raises_truncation_error():
+    resp = _response('{"label": "nega', finish_reason="length")
+    with pytest.raises(StructuredOutputError, match="cut off at max_tokens") as info:
+        parse_structured(resp, Sentiment)
+    assert isinstance(info.value.__cause__, ValidationError)
+
+
+def test_complete_answer_is_kept_even_when_generation_hit_the_limit():
+    resp = _response(GOOD + "\n\n\n", finish_reason="length")
+    assert parse_structured(resp, Sentiment).label == "negative"
+
+
+def test_mismatching_answer_names_the_failing_field():
+    # Bad label and missing confidence: the first error is named, the rest counted.
+    resp = _response('{"label": "great"}')
+    with pytest.raises(StructuredOutputError) as info:
+        parse_structured(resp, Sentiment)
+    message = str(info.value)
+    assert "failed validation (label: " in message
+    assert message.endswith("; 1 more)")
+    assert info.value.finish_reason == "stop"
+    assert isinstance(info.value.__cause__, ValidationError)
+
+
+def test_non_json_answer_reports_the_parse_error():
+    # What a backend that ignores the schema might send: JSON in a code fence.
+    resp = _response(f"```json\n{GOOD}\n```")
+    with pytest.raises(
+        StructuredOutputError, match=r"failed validation \(Invalid JSON"
+    ):
+        parse_structured(resp, Sentiment)
+
+
+def test_missing_content_reports_the_finish_reason():
+    # E.g. the model called a tool instead of answering.
+    resp = _response(None, finish_reason="tool_calls")
+    with pytest.raises(StructuredOutputError, match="finish_reason='tool_calls'"):
+        parse_structured(resp, Sentiment)
+
+
+def test_refusal_is_reported():
+    resp = _response(None, refusal="I can't help with that.")
+    with pytest.raises(StructuredOutputError, match="refused: I can't help with that"):
+        parse_structured(resp, Sentiment)
+
+
+def test_no_choices_raises():
+    with pytest.raises(StructuredOutputError, match="no choices") as info:
+        parse_structured({"choices": []}, Sentiment)
+    assert info.value.finish_reason is None
+
+
+def test_completions_structured_sends_schema_and_returns_instance():
+    svc = _sync_service(_response(GOOD))
+    result = svc.completions_structured(
+        "m",
+        [{"role": "user", "content": "hi"}],
+        Sentiment,
+        max_tokens=2000,
+        chat_template_kwargs={"enable_thinking": False},
+    )
+    assert result == Sentiment(label="negative", confidence=0.95)
+    body = svc._session.post.call_args.kwargs["json"]
+    assert body["response_format"] == response_format_for(Sentiment)
+    assert body["max_tokens"] == 2000
+    assert body["chat_template_kwargs"] == {"enable_thinking": False}
+
+
+def test_completions_structured_refuses_streaming():
+    svc = _sync_service(_response(GOOD))
+    with pytest.raises(TypeError):
+        svc.completions_structured("m", [], Sentiment, stream=True)
+    svc._session.post.assert_not_called()
+
+
+def test_async_completions_structured_sends_schema_and_returns_instance():
+    client = FakeAsyncClient(
+        responses=[
+            FakeAsyncResponse(200, headers=rl_headers(), json_body=_response(GOOD))
+        ]
+    )
+    svc = AsyncChatService(client, "https://x/v1")
+    result = asyncio.run(svc.completions_structured("m", [], Sentiment))
+    assert result == Sentiment(label="negative", confidence=0.95)
+    assert client.calls[0]["json"]["response_format"] == response_format_for(Sentiment)

saia_python-0.9.0/saia_python/chat.py

@@ -1,81 +0,0 @@
-"""Chat service — completions and streaming."""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from ._http import RetryPolicy, coerce_retry, post_chat_completion, resolve_retry
-from ._streaming import SSEStream
-
-if TYPE_CHECKING:
-    import requests
-
-
-class ChatService:
-    """Access the ``/chat/completions`` endpoint.
-
-    Args:
-        session: A :class:`requests.Session` with auth headers configured.
-        base_url: The SAIA API base URL.
-    """
-
-    def __init__(
-        self,
-        session: requests.Session,
-        base_url: str,
-        *,
-        retry: RetryPolicy | bool | None = None,
-    ):
-        self._session = session
-        self._base_url = base_url
-        self._retry = coerce_retry(retry)
-
-    def completions(
-        self,
-        model: str,
-        messages: list[dict],
-        *,
-        temperature: float | None = None,
-        top_p: float | None = None,
-        max_tokens: int | None = None,
-        stream: bool = False,
-        retry: RetryPolicy | bool | None = None,
-        **kwargs,
-    ) -> dict | SSEStream:
-        """Send a chat completion request.
-
-        Args:
-            model: Model identifier (e.g. ``"meta-llama-3.1-8b-instruct"``).
-            messages: List of message dicts with ``"role"`` and ``"content"`` keys.
-            temperature: Sampling temperature (0–2).
-            top_p: Nucleus sampling parameter (0–1).
-            max_tokens: Maximum tokens to generate.
-            stream: If ``True``, return a generator yielding chunks.
-            **kwargs: Additional parameters forwarded to the API.
-
-        Returns:
-            When ``stream=False``: the API response dict, with an extra
-            ``"_rate_limits"`` key — a JSON-serializable dict of the current
-            rate-limit headers (see :class:`~saia_python.RateLimitInfo`).
-            When ``stream=True``: an ``SSEStream`` — iterate it for the
-            response chunks; its ``rate_limits`` attribute exposes the same
-            dict (available immediately, from the response headers).
-        """
-        body = {"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 post_chat_completion(
-            self._session,
-            f"{self._base_url}/chat/completions",
-            body,
-            stream=stream,
-            policy=resolve_retry(self._retry, retry),
-        )
-
-    def __repr__(self):
-        return f"ChatService(base_url={self._base_url!r})"