spt-models 0.2.0__tar.gz

spt_models-0.2.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+
+# Node / Admin
+node_modules/
+admin/dist/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.log
+
+# Models cache (large files)
+/data/
+*.bin
+*.safetensors
+*.gguf
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Session artefacts — agent caches, local test inputs, ad-hoc outputs
+.playwright-mcp/
+examples/
+results/
+
+# Harness runtime lock (do not commit)
+.claude/scheduled_tasks.lock

spt_models-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sponge Theory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spt_models-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: spt-models
+Version: 0.2.0
+Summary: Python client for the SPT Models GPU inference platform
+Project-URL: Homepage, https://models.sponge-theory.dev
+Project-URL: Repository, https://github.com/sponge-theory/spt-models
+Project-URL: Documentation, https://github.com/sponge-theory/spt-models/tree/main/spt-models-python
+Author-email: Sponge Theory <dev@sponge-theory.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,api-client,gpu,inference,llm,ml,openai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.34; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# spt-models
+
+Python client for the SPT Models GPU inference platform.
+
+## Model aliases
+
+An admin can publish client-facing names (`gpt-4`, `prod-embeddings`, …) that
+point at a catalogue model. Every `/v1/*` call accepts an alias wherever it
+accepts a slug, and echoes the alias back in the response `model` field.
+`client.admin.aliases` manages them (admin token required); `Model.alias_of`
+tells an alias entry apart from a real model in `client.models.list()`.
+
+```python
+from spt_models import Client
+
+with Client(api_key="sk-...", admin_token="...") as client:
+    # Create an alias pointing at model id 1, then use it like a slug.
+    alias = client.admin.aliases.create("gpt-4", 1, description="OpenAI drop-in")
+    resp = client.chat.completions.create(
+        model="gpt-4", messages=[{"role": "user", "content": "Hello"}]
+    )
+    assert resp.model == "gpt-4"          # the alias is echoed, not the slug
+
+    # Repoint, disable, or drop it — clients keep the same name throughout.
+    client.admin.aliases.update(alias.id, model_id=2)
+    client.admin.aliases.update(alias.id, enabled=False)
+    client.admin.aliases.delete(alias.id)
+
+    for m in client.models.list().data:
+        if m.alias_of:
+            print(f"{m.id} -> {m.alias_of}")
+```
+
+Async variants follow the usual `a` prefix: `alist`, `acreate`, `aupdate`, `adelete`.

spt_models-0.2.0/README.md

@@ -0,0 +1,34 @@
+# spt-models
+
+Python client for the SPT Models GPU inference platform.
+
+## Model aliases
+
+An admin can publish client-facing names (`gpt-4`, `prod-embeddings`, …) that
+point at a catalogue model. Every `/v1/*` call accepts an alias wherever it
+accepts a slug, and echoes the alias back in the response `model` field.
+`client.admin.aliases` manages them (admin token required); `Model.alias_of`
+tells an alias entry apart from a real model in `client.models.list()`.
+
+```python
+from spt_models import Client
+
+with Client(api_key="sk-...", admin_token="...") as client:
+    # Create an alias pointing at model id 1, then use it like a slug.
+    alias = client.admin.aliases.create("gpt-4", 1, description="OpenAI drop-in")
+    resp = client.chat.completions.create(
+        model="gpt-4", messages=[{"role": "user", "content": "Hello"}]
+    )
+    assert resp.model == "gpt-4"          # the alias is echoed, not the slug
+
+    # Repoint, disable, or drop it — clients keep the same name throughout.
+    client.admin.aliases.update(alias.id, model_id=2)
+    client.admin.aliases.update(alias.id, enabled=False)
+    client.admin.aliases.delete(alias.id)
+
+    for m in client.models.list().data:
+        if m.alias_of:
+            print(f"{m.id} -> {m.alias_of}")
+```
+
+Async variants follow the usual `a` prefix: `alist`, `acreate`, `aupdate`, `adelete`.

spt_models-0.2.0/deploy-pypi.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Deploy spt-models to PyPI
+# Usage:
+#   ./deploy-pypi.sh          # deploy to PyPI
+#   ./deploy-pypi.sh --test   # deploy to TestPyPI first
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+info()  { echo -e "${GREEN}[INFO]${NC} $*"; }
+warn()  { echo -e "${YELLOW}[WARN]${NC} $*"; }
+error() { echo -e "${RED}[ERROR]${NC} $*"; exit 1; }
+
+# Check dependencies
+command -v uv >/dev/null 2>&1 || error "uv is required. Install: curl -LsSf https://astral.sh/uv/install.sh | sh"
+
+# Parse version from pyproject.toml
+VERSION=$(python3 -c "
+import tomllib
+with open('pyproject.toml', 'rb') as f:
+    print(tomllib.load(f)['project']['version'])
+")
+info "Package version: $VERSION"
+
+# Clean previous builds
+info "Cleaning previous builds..."
+rm -rf dist/ build/ src/*.egg-info
+
+# Build
+info "Building sdist and wheel..."
+uv build
+
+# Verify build artifacts
+SDIST="dist/spt_models-${VERSION}.tar.gz"
+WHEEL=$(ls dist/spt_models-${VERSION}-*.whl 2>/dev/null | head -1)
+
+[ -f "$SDIST" ] || error "sdist not found: $SDIST"
+[ -n "$WHEEL" ] || error "wheel not found in dist/"
+
+info "Built: $(basename "$SDIST")"
+info "Built: $(basename "$WHEEL")"
+
+# Upload
+if [[ "${1:-}" == "--test" ]]; then
+    info "Uploading to TestPyPI..."
+    uv publish --publish-url https://test.pypi.org/legacy/
+    info "Uploaded to TestPyPI"
+    echo ""
+    info "Install from TestPyPI with:"
+    echo "  uv pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ spt-models==$VERSION"
+    echo ""
+    warn "Run again without --test to publish to production PyPI"
+else
+    info "Uploading to PyPI..."
+    uv publish
+    info "Published spt-models==$VERSION to PyPI"
+    echo ""
+    info "Install with:"
+    echo "  uv pip install spt-models==$VERSION"
+fi

spt_models-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spt-models"
+version = "0.2.0"
+description = "Python client for the SPT Models GPU inference platform"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Sponge Theory", email = "dev@sponge-theory.dev" },
+]
+keywords = ["ai", "ml", "inference", "gpu", "llm", "openai", "api-client"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27,<1",
+    "pydantic>=2,<3",
+]
+
+[project.urls]
+Homepage = "https://models.sponge-theory.dev"
+Repository = "https://github.com/sponge-theory/spt-models"
+Documentation = "https://github.com/sponge-theory/spt-models/tree/main/spt-models-python"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "pytest-httpx>=0.34",
+    "respx>=0.22",
+    "ruff>=0.8",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spt_models"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

spt_models-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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()