spt-models 0.2.0__py3-none-any.whl

spt_models/__init__.py

@@ -0,0 +1,52 @@
+"""SPT Models Python client library."""
+
+__version__ = "0.2.0"
+
+from ._client import Client, AsyncClient
+from ._exceptions import (
+    SPTError,
+    AuthenticationError,
+    RateLimitError,
+    NotFoundError,
+    ValidationError,
+    UpstreamError,
+    APIConnectionError,
+    APIStatusError,
+)
+from .types.chat import ChatCompletion, ChatCompletionChunk, ChatMessage
+from .types.completions import Completion, CompletionChunk
+from .types.embeddings import EmbeddingResponse
+from .types.images import ImageResponse, VideoResponse
+from .types.audio import Transcription
+from .types.models import Model, ModelList, ModelParameters, ParameterInfo
+
+__all__ = [
+    # Clients
+    "Client",
+    "AsyncClient",
+    # Exceptions
+    "SPTError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "UpstreamError",
+    "APIConnectionError",
+    "APIStatusError",
+    # Inference types
+    "ChatCompletion",
+    "ChatCompletionChunk",
+    "ChatMessage",
+    "Completion",
+    "CompletionChunk",
+    "EmbeddingResponse",
+    "ImageResponse",
+    "VideoResponse",
+    "Transcription",
+    "Model",
+    "ModelList",
+    "ModelParameters",
+    "ParameterInfo",
+    # Version
+    "__version__",
+]

spt_models/_base.py

@@ -0,0 +1,50 @@
+"""Shared base client configuration and utilities."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+_DEFAULT_BASE_URL = "https://models.sponge-theory.dev"
+# Server-side inference budget is 3600s end-to-end (orchestrator's
+# inference_timeout_seconds, gateway's proxy/admin-router timeouts — video
+# gen can run 28+ min).  Default must clear that budget with margin, or the
+# client gives up on a call the server is about to finish successfully — the
+# worst kind of failure, since it looks like an error when none occurred.
+_DEFAULT_TIMEOUT = 3900  # seconds
+
+
+@dataclass
+class BaseClientConfig:
+    api_key: str | None = None
+    admin_token: str | None = None
+    base_url: str = ""
+    timeout: float | None = None
+
+    def __post_init__(self) -> None:
+        if not self.api_key:
+            self.api_key = os.environ.get("SPT_API_KEY")
+        if not self.admin_token:
+            self.admin_token = os.environ.get("SPT_ADMIN_TOKEN")
+        if not self.base_url:
+            self.base_url = os.environ.get("SPT_BASE_URL", _DEFAULT_BASE_URL)
+        if self.base_url.endswith("/"):
+            self.base_url = self.base_url.rstrip("/")
+        if self.timeout is None:
+            self.timeout = _DEFAULT_TIMEOUT
+
+
+def build_headers(*, api_key: str | None) -> dict[str, str]:
+    """Build HTTP headers for inference requests (API key only)."""
+    headers: dict[str, str] = {"Accept": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def build_admin_headers(*, admin_token: str | None) -> dict[str, str]:
+    """Build HTTP headers for admin requests (admin token only)."""
+    headers: dict[str, str] = {"Accept": "application/json"}
+    if admin_token:
+        headers["Authorization"] = f"Bearer {admin_token}"
+    return headers

spt_models/_client.py

@@ -0,0 +1,238 @@
+"""Sync and async client implementations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from ._base import BaseClientConfig, build_headers, build_admin_headers
+from ._exceptions import APIConnectionError, raise_for_status
+
+
+class _ResourceMixin:
+    """Provides lazy resource namespace access shared between sync/async clients."""
+
+    _config: BaseClientConfig
+
+    @property
+    def chat(self) -> Any:
+        if not hasattr(self, "_chat"):
+            from .resources.chat import ChatResource
+            self._chat = ChatResource(self)
+        return self._chat
+
+    @property
+    def completions(self) -> Any:
+        if not hasattr(self, "_completions"):
+            from .resources.completions import CompletionsResource
+            self._completions = CompletionsResource(self)
+        return self._completions
+
+    @property
+    def embeddings(self) -> Any:
+        if not hasattr(self, "_embeddings"):
+            from .resources.embeddings import EmbeddingsResource
+            self._embeddings = EmbeddingsResource(self)
+        return self._embeddings
+
+    @property
+    def images(self) -> Any:
+        if not hasattr(self, "_images"):
+            from .resources.images import ImagesResource
+            self._images = ImagesResource(self)
+        return self._images
+
+    @property
+    def videos(self) -> Any:
+        if not hasattr(self, "_videos"):
+            from .resources.videos import VideosResource
+            self._videos = VideosResource(self)
+        return self._videos
+
+    @property
+    def audio(self) -> Any:
+        if not hasattr(self, "_audio"):
+            from .resources.audio import AudioResource
+            self._audio = AudioResource(self)
+        return self._audio
+
+    @property
+    def models(self) -> Any:
+        if not hasattr(self, "_models"):
+            from .resources.models import ModelsResource
+            self._models = ModelsResource(self)
+        return self._models
+
+    @property
+    def admin(self) -> Any:
+        if not hasattr(self, "_admin"):
+            from .resources.admin import AdminResource
+            self._admin = AdminResource(self)
+        return self._admin
+
+
+class Client(_ResourceMixin):
+    """Synchronous SPT Models client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        admin_token: str | None = None,
+        base_url: str = "",
+        timeout: float | None = None,
+    ) -> None:
+        self._config = BaseClientConfig(
+            api_key=api_key, admin_token=admin_token,
+            base_url=base_url, timeout=timeout,
+        )
+        self._http = httpx.Client(
+            base_url=self._config.base_url,
+            timeout=httpx.Timeout(self._config.timeout, connect=10.0),
+        )
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        admin: bool = False,
+    ) -> httpx.Response:
+        """Send an HTTP request with auth headers and error handling."""
+        if headers is None:
+            if admin:
+                headers = build_admin_headers(admin_token=self._config.admin_token)
+            else:
+                headers = build_headers(api_key=self._config.api_key)
+        try:
+            resp = self._http.request(
+                method, path, json=json, params=params,
+                headers=headers, timeout=timeout,
+            )
+        except httpx.ConnectError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except httpx.TimeoutException as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        raise_for_status(resp)
+        return resp
+
+    def _stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send a request and return the response for SSE line parsing."""
+        if headers is None:
+            headers = build_headers(api_key=self._config.api_key)
+        try:
+            resp = self._http.request(
+                method, path, json=json, headers=headers, timeout=timeout,
+            )
+        except httpx.ConnectError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except httpx.TimeoutException as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        raise_for_status(resp)
+        return resp
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+
+class AsyncClient(_ResourceMixin):
+    """Asynchronous SPT Models client."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        admin_token: str | None = None,
+        base_url: str = "",
+        timeout: float | None = None,
+    ) -> None:
+        self._config = BaseClientConfig(
+            api_key=api_key, admin_token=admin_token,
+            base_url=base_url, timeout=timeout,
+        )
+        self._http = httpx.AsyncClient(
+            base_url=self._config.base_url,
+            timeout=httpx.Timeout(self._config.timeout, connect=10.0),
+        )
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+        admin: bool = False,
+    ) -> httpx.Response:
+        """Send an async HTTP request with auth headers and error handling."""
+        if headers is None:
+            if admin:
+                headers = build_admin_headers(admin_token=self._config.admin_token)
+            else:
+                headers = build_headers(api_key=self._config.api_key)
+        try:
+            resp = await self._http.request(
+                method, path, json=json, params=params,
+                headers=headers, timeout=timeout,
+            )
+        except httpx.ConnectError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except httpx.TimeoutException as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        raise_for_status(resp)
+        return resp
+
+    async def _stream_request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> httpx.Response:
+        """Send an async request and return the response for SSE line parsing."""
+        if headers is None:
+            headers = build_headers(api_key=self._config.api_key)
+        try:
+            resp = await self._http.request(
+                method, path, json=json, headers=headers, timeout=timeout,
+            )
+        except httpx.ConnectError as e:
+            raise APIConnectionError(f"Connection error: {e}") from e
+        except httpx.TimeoutException as e:
+            raise APIConnectionError(f"Request timed out: {e}") from e
+        raise_for_status(resp)
+        return resp
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client."""
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncClient:
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()

spt_models/_exceptions.py

@@ -0,0 +1,99 @@
+"""Exception hierarchy for SPT Models client."""
+
+from __future__ import annotations
+
+
+import httpx
+
+
+class SPTError(Exception):
+    """Base exception for all SPT Models client errors."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        response: httpx.Response | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.response = response
+
+
+class AuthenticationError(SPTError):
+    """Raised on 401/403 — invalid or missing API key / admin token."""
+
+
+class RateLimitError(SPTError):
+    """Raised on 429 — rate limit exceeded."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int = 429,
+        response: httpx.Response | None = None,
+        retry_after: int | None = None,
+    ) -> None:
+        super().__init__(message, status_code=status_code, response=response)
+        self.retry_after = retry_after
+
+
+class NotFoundError(SPTError):
+    """Raised on 404 — model, key, or resource not found."""
+
+
+class ValidationError(SPTError):
+    """Raised on 400/409/413 — bad request, conflict, or payload too large."""
+
+
+class UpstreamError(SPTError):
+    """Raised on 502 — orchestrator or worker unreachable."""
+
+
+class APIConnectionError(SPTError):
+    """Raised when the HTTP connection fails entirely."""
+
+
+class APIStatusError(SPTError):
+    """Raised on unexpected HTTP status codes."""
+
+
+def _extract_detail(resp: httpx.Response) -> str:
+    """Extract error message from response body."""
+    try:
+        body = resp.json()
+        if isinstance(body, dict) and "detail" in body:
+            detail = body["detail"]
+            return detail if isinstance(detail, str) else str(detail)
+    except Exception:
+        pass
+    return resp.text or f"HTTP {resp.status_code}"
+
+
+def raise_for_status(resp: httpx.Response) -> None:
+    """Raise a typed SPTError if the response indicates an error."""
+    code = resp.status_code
+    if code < 400:
+        return
+
+    message = _extract_detail(resp)
+
+    if code in (401, 403):
+        raise AuthenticationError(message, status_code=code, response=resp)
+    if code == 404:
+        raise NotFoundError(message, status_code=code, response=resp)
+    if code == 429:
+        retry = resp.headers.get("Retry-After")
+        raise RateLimitError(
+            message,
+            status_code=code,
+            response=resp,
+            retry_after=int(retry) if retry else None,
+        )
+    if code in (400, 409, 413):
+        raise ValidationError(message, status_code=code, response=resp)
+    if code == 502:
+        raise UpstreamError(message, status_code=code, response=resp)
+    raise APIStatusError(message, status_code=code, response=resp)

spt_models/_streaming.py

@@ -0,0 +1,82 @@
+"""SSE (Server-Sent Events) stream parsing for sync and async clients."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterator, AsyncIterator, TypeVar, Generic, Type
+
+from pydantic import BaseModel
+
+from ._exceptions import SPTError
+
+T = TypeVar("T", bound=BaseModel)
+
+
+def parse_sse_line(line: str) -> dict[str, Any] | None:
+    """Parse a single SSE line. Returns parsed JSON, None for [DONE]/empty, or raises on error."""
+    line = line.strip()
+    if not line or line.startswith(":"):
+        return None
+    if line.startswith("data: "):
+        data = line[6:]
+        if data == "[DONE]":
+            return None
+        parsed = json.loads(data)
+        # Check for error chunks
+        choices = parsed.get("choices", [])
+        if choices and choices[0].get("finish_reason") == "error":
+            raise SPTError("Stream error: server returned error chunk during streaming")
+        return parsed
+    return None
+
+
+class SyncSSEIterator(Generic[T]):
+    """Synchronous iterator over SSE stream, yielding typed Pydantic models."""
+
+    def __init__(self, response: Any, model_class: Type[T]) -> None:
+        self._response = response
+        self._model_class = model_class
+        # Parse lines from the response text
+        self._lines = iter(response.text.splitlines())
+
+    def __iter__(self) -> Iterator[T]:
+        return self
+
+    def __next__(self) -> T:
+        while True:
+            try:
+                line = next(self._lines)
+            except StopIteration:
+                raise
+            parsed = parse_sse_line(line)
+            if parsed is not None:
+                return self._model_class.model_validate(parsed)
+
+    def close(self) -> None:
+        pass
+
+
+class AsyncSSEIterator(Generic[T]):
+    """Async iterator over SSE stream, yielding typed Pydantic models."""
+
+    def __init__(self, response: Any, model_class: Type[T]) -> None:
+        self._response = response
+        self._model_class = model_class
+        self._iter = response.aiter_lines()
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        while True:
+            try:
+                line = await self._iter.__anext__()
+            except StopAsyncIteration:
+                await self._response.aclose()
+                raise
+            parsed = parse_sse_line(line)
+            if parsed is not None:
+                return self._model_class.model_validate(parsed)
+
+    async def close(self) -> None:
+        await self._response.aclose()

spt_models/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource namespace modules for the SPT client."""

spt_models/resources/admin/__init__.py

@@ -0,0 +1,52 @@
+"""Admin resource namespace — client.admin.*"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...types.admin import AdminHealth
+from .dashboard import AdminDashboardResource
+from .models import AdminModelsResource
+from .aliases import AdminAliasesResource
+from .keys import AdminKeysResource
+from .usage import AdminUsageResource
+from .gpu import AdminGPUResource
+from .conversion import AdminConversionResource
+
+
+class AdminResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+        self.dashboard = AdminDashboardResource(client)
+        self.models = AdminModelsResource(client)
+        self.aliases = AdminAliasesResource(client)
+        self.keys = AdminKeysResource(client)
+        self.usage = AdminUsageResource(client)
+        self.gpu = AdminGPUResource(client)
+        self.conversion = AdminConversionResource(client)
+
+    def login(self, *, timeout: float | None = None) -> dict[str, Any]:
+        resp = self._client._request(
+            "POST", "/admin/api/auth/login",
+            json={"token": self._client._config.admin_token},
+            admin=True, timeout=timeout,
+        )
+        return resp.json()
+
+    async def alogin(self, *, timeout: float | None = None) -> dict[str, Any]:
+        resp = await self._client._request(
+            "POST", "/admin/api/auth/login",
+            json={"token": self._client._config.admin_token},
+            admin=True, timeout=timeout,
+        )
+        return resp.json()
+
+    def health(self, *, timeout: float | None = None) -> AdminHealth:
+        resp = self._client._request("GET", "/admin/api/health", admin=True, timeout=timeout)
+        return AdminHealth.model_validate(resp.json())
+
+    async def ahealth(self, *, timeout: float | None = None) -> AdminHealth:
+        resp = await self._client._request(
+            "GET", "/admin/api/health", admin=True, timeout=timeout
+        )
+        return AdminHealth.model_validate(resp.json())

spt_models/resources/admin/aliases.py

@@ -0,0 +1,91 @@
+"""Admin model aliases resource — client-facing names that point at a catalogue model."""
+
+from __future__ import annotations
+
+from typing import Any, TYPE_CHECKING
+
+from ...types.admin import AdminAlias
+
+if TYPE_CHECKING:
+    pass
+
+
+class AdminAliasesResource:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def list(self, *, timeout: float | None = None) -> list[AdminAlias]:
+        resp = self._client._request("GET", "/admin/api/aliases", admin=True, timeout=timeout)
+        return [AdminAlias.model_validate(a) for a in resp.json()]
+
+    async def alist(self, *, timeout: float | None = None) -> list[AdminAlias]:
+        resp = await self._client._request(
+            "GET", "/admin/api/aliases", admin=True, timeout=timeout
+        )
+        return [AdminAlias.model_validate(a) for a in resp.json()]
+
+    def create(
+        self,
+        alias: str,
+        model_id: int,
+        *,
+        description: str = "",
+        enabled: bool = True,
+        timeout: float | None = None,
+    ) -> AdminAlias:
+        body: dict[str, Any] = {
+            "alias": alias,
+            "model_id": model_id,
+            "description": description,
+            "enabled": enabled,
+        }
+        resp = self._client._request(
+            "POST", "/admin/api/aliases", json=body, admin=True, timeout=timeout
+        )
+        return AdminAlias.model_validate(resp.json())
+
+    async def acreate(
+        self,
+        alias: str,
+        model_id: int,
+        *,
+        description: str = "",
+        enabled: bool = True,
+        timeout: float | None = None,
+    ) -> AdminAlias:
+        body: dict[str, Any] = {
+            "alias": alias,
+            "model_id": model_id,
+            "description": description,
+            "enabled": enabled,
+        }
+        resp = await self._client._request(
+            "POST", "/admin/api/aliases", json=body, admin=True, timeout=timeout
+        )
+        return AdminAlias.model_validate(resp.json())
+
+    def update(
+        self, alias_id: int, *, timeout: float | None = None, **kwargs: Any
+    ) -> AdminAlias:
+        resp = self._client._request(
+            "PUT", f"/admin/api/aliases/{alias_id}", json=kwargs, admin=True, timeout=timeout
+        )
+        return AdminAlias.model_validate(resp.json())
+
+    async def aupdate(
+        self, alias_id: int, *, timeout: float | None = None, **kwargs: Any
+    ) -> AdminAlias:
+        resp = await self._client._request(
+            "PUT", f"/admin/api/aliases/{alias_id}", json=kwargs, admin=True, timeout=timeout
+        )
+        return AdminAlias.model_validate(resp.json())
+
+    def delete(self, alias_id: int, *, timeout: float | None = None) -> None:
+        self._client._request(
+            "DELETE", f"/admin/api/aliases/{alias_id}", admin=True, timeout=timeout
+        )
+
+    async def adelete(self, alias_id: int, *, timeout: float | None = None) -> None:
+        await self._client._request(
+            "DELETE", f"/admin/api/aliases/{alias_id}", admin=True, timeout=timeout
+        )