Client#

class saia_python.SAIAClient(api_key: str | None = None, base_url: str | None = None, key_file: str | None = None, *, timeout: float | tuple[float, float] | None = (10.0, 60.0), retry: RetryPolicy | bool | None = None)[source]#

High-level client for the GWDG SAIA platform.

Provides access to Chat, Voice AI, ARCANA, Documents, and model listing through a shared, authenticated HTTP session. An OpenAI- compatible client is available via the .openai property.

Parameters:

  • api_key – Your SAIA API key. If omitted, the key is resolved automatically — see load_api_key() for the resolution order.

  • base_url – Base URL for the SAIA API. Resolution order: explicit parameter > [saia] base_url in config.toml > 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 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).

  • retry – Rate-limit handling policy (RetryPolicy), forwarded to the data-plane services (chat, ARCANA chat, documents, voice). On by default — a 429 on an idempotent call is waited out and retried within bounds. Pass False to disable, or a RetryPolicy to tune it (e.g. max_waiting_time).

Example:

# All settings resolved automatically
client = SAIAClient()

# Native services
client.chat.completions(model="...", messages=[...])

# OpenAI-compatible client (requires pip install saia-python[openai])
client.openai.chat.completions.create(model="...", messages=[...])
property chat: ChatService#

Chat completions service.

property voice: VoiceService#

Voice AI (transcription/translation) service.

property models: ModelsService#

Model listing service.

property tokenizers: TokenizerService#

Tokenizer service for the open-weight models.

Loads model tokenizers, counts chat-template tokens, and annotates the live model list with Hugging Face repositories. Requires the optional [tokenizer] extra (pip install saia-python[tokenizer]) for the download/load operations; the repository annotations work without it.

property arcana: ArcanaService#

ARCANA/RAG service.

property documents: DocumentService#

Document conversion (Docling) service.

property openai#

OpenAI-compatible synchronous client.

Returns an openai.OpenAI instance configured with the same API key and base URL as this client. Requires pip install saia-python[openai].

Example:

response = client.openai.chat.completions.create(
    model="llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": "Hello!"}],
)
property openai_async#

OpenAI-compatible asynchronous client.

Returns an openai.AsyncOpenAI instance. Requires pip install saia-python[openai].

get_rate_limits() → RateLimitInfo[source]#

Fetch current rate-limit status by making a lightweight API call.

Uses a GET to /chat/completions which returns 400 but includes rate-limit headers.

Returns:

Parsed RateLimitInfo.

Raises:

AuthenticationError – If the API key is invalid or expired (401/403). Other non-2xx statuses (notably the expected 400) are tolerated since they still carry the headers.

arcana_version() → str[source]#

Return the ARCANA API version string.

Thin delegate to ArcanaService.version() (client.arcana.version()), which owns the ARCANA URL path and auth scheme.

Returns:

The version string (e.g. "0.4.16").

arcana_heartbeat() → bool[source]#

Check if the ARCANA service is alive.

Thin delegate to ArcanaService.heartbeat() (client.arcana.heartbeat()). Returns True if the service responds with 204, False otherwise.

Returns:

True if the service is reachable.

health_check(*, verbose: bool = False) → bool | dict[source]#

Verify that the client can reach the API and authenticate.

Combines two cheap GETs:

  • GET /models (authenticated) — confirms the API key resolves and the chat backend is reachable.

  • GET /arcanas/api/v1/heartbeat (cheap 204) — confirms the ARCANA backend is reachable.

Parameters:

verbose – If True, return a diagnostic dict instead of a bool. Useful in onboarding / setup scripts where you want to surface which leg failed.

Returns:

True if both legs succeed, False otherwise. With verbose=True, a dict:

{
    "ok":            <bool>,
    "base_url":      <str>,
    "models_ok":     <bool>,
    "model_count":   <int>,    # 0 if models leg failed
    "arcana_ok":     <bool>,
    "error":         <str|None>,  # first leg that failed
}