runcrate-sdk 0.1.0__py3-none-any.whl

runcrate/__init__.py

@@ -0,0 +1,44 @@
+"""Runcrate Python SDK — Official client for the Runcrate API."""
+
+from runcrate._client import AsyncRuncrate, Runcrate
+from runcrate._exceptions import (
+    ApiError,
+    AuthenticationError,
+    BadRequestError,
+    ConflictError,
+    UnprocessableEntityError,
+    ConnectionError,
+    InsufficientCreditsError,
+    InternalServerError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    RuncrateError,
+    TimeoutError,
+)
+from runcrate._pagination import PaginatedResponse
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncRuncrate",
+    "Runcrate",
+    # Exceptions
+    "ApiError",
+    "AuthenticationError",
+    "BadRequestError",
+    "ConflictError",
+    "UnprocessableEntityError",
+    "ConnectionError",
+    "InsufficientCreditsError",
+    "InternalServerError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "RuncrateError",
+    "TimeoutError",
+    # Pagination
+    "PaginatedResponse",
+    # Version
+    "__version__",
+]

runcrate/_client.py

@@ -0,0 +1,323 @@
+"""Main client classes."""
+
+from __future__ import annotations
+
+from typing import Any, Iterator, AsyncIterator, Optional, Union
+
+import httpx
+
+from runcrate._config import ClientConfig
+from runcrate._transport import AsyncTransport, SyncTransport
+from runcrate.resources.billing import AsyncBilling, Billing
+from runcrate.resources.environments import AsyncEnvironments, Environments
+from runcrate.resources.instances import AsyncInstances, Instances
+from runcrate.resources.models import AsyncModels, Models
+from runcrate.resources.ssh_keys import AsyncSSHKeys, SSHKeys
+from runcrate.resources.storage import AsyncStorage, Storage
+from runcrate.resources.templates import AsyncTemplates, Templates
+from runcrate.models.models import ChatCompletion, ImageGeneration, Transcription, VideoJob
+
+
+# ─── OpenAI-compatible namespace classes (sync) ────────────────────────────────
+
+class _ChatCompletions:
+    """OpenAI-compatible chat.completions namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self._models = models
+
+    def create(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> Union[ChatCompletion, Iterator[dict[str, Any]]]:
+        return self._models.chat_completion(model=model, messages=messages, stream=stream, **kwargs)
+
+
+class _Chat:
+    """OpenAI-compatible chat namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self.completions = _ChatCompletions(models)
+
+
+class _Images:
+    """OpenAI-compatible images namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self._models = models
+
+    def generate(self, *, model: str, prompt: str, **kwargs: Any) -> ImageGeneration:
+        return self._models.generate_image(model=model, prompt=prompt, **kwargs)
+
+
+class _Speech:
+    """OpenAI-compatible audio.speech namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self._models = models
+
+    def create(self, *, model: str, input: str, **kwargs: Any) -> bytes:
+        return self._models.text_to_speech(model=model, input=input, **kwargs)
+
+
+class _Transcriptions:
+    """OpenAI-compatible audio.transcriptions namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self._models = models
+
+    def create(self, *, model: str, file: Any, **kwargs: Any) -> Transcription:
+        return self._models.transcribe(model=model, file=file, **kwargs)
+
+
+class _Audio:
+    """OpenAI-compatible audio namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self.speech = _Speech(models)
+        self.transcriptions = _Transcriptions(models)
+
+
+class _Videos:
+    """Video namespace."""
+
+    def __init__(self, models: Models) -> None:
+        self._models = models
+
+    def generate(self, *, model: str, prompt: str, **kwargs: Any) -> VideoJob:
+        return self._models.generate_video(model=model, prompt=prompt, **kwargs)
+
+    def get_status(self, id: str) -> VideoJob:
+        return self._models.get_video_status(id)
+
+    def download(self, id: str) -> bytes:
+        return self._models.download_video(id)
+
+    def generate_and_save(self, path: str, *, model: str, prompt: str, **kwargs: Any) -> VideoJob:
+        return self._models.generate_video_and_save(path, model=model, prompt=prompt, **kwargs)
+
+
+# ─── OpenAI-compatible namespace classes (async) ───────────────────────────────
+
+class _AsyncChatCompletions:
+    """OpenAI-compatible chat.completions namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self._models = models
+
+    async def create(
+        self,
+        *,
+        model: str,
+        messages: list[dict[str, Any]],
+        stream: bool = False,
+        **kwargs: Any,
+    ) -> Union[ChatCompletion, AsyncIterator[dict[str, Any]]]:
+        return await self._models.chat_completion(model=model, messages=messages, stream=stream, **kwargs)
+
+
+class _AsyncChat:
+    """OpenAI-compatible chat namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self.completions = _AsyncChatCompletions(models)
+
+
+class _AsyncImages:
+    """OpenAI-compatible images namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self._models = models
+
+    async def generate(self, *, model: str, prompt: str, **kwargs: Any) -> ImageGeneration:
+        return await self._models.generate_image(model=model, prompt=prompt, **kwargs)
+
+
+class _AsyncSpeech:
+    """OpenAI-compatible audio.speech namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self._models = models
+
+    async def create(self, *, model: str, input: str, **kwargs: Any) -> bytes:
+        return await self._models.text_to_speech(model=model, input=input, **kwargs)
+
+
+class _AsyncTranscriptions:
+    """OpenAI-compatible audio.transcriptions namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self._models = models
+
+    async def create(self, *, model: str, file: Any, **kwargs: Any) -> Transcription:
+        return await self._models.transcribe(model=model, file=file, **kwargs)
+
+
+class _AsyncAudio:
+    """OpenAI-compatible audio namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self.speech = _AsyncSpeech(models)
+        self.transcriptions = _AsyncTranscriptions(models)
+
+
+class _AsyncVideos:
+    """Video namespace (async)."""
+
+    def __init__(self, models: AsyncModels) -> None:
+        self._models = models
+
+    async def generate(self, *, model: str, prompt: str, **kwargs: Any) -> VideoJob:
+        return await self._models.generate_video(model=model, prompt=prompt, **kwargs)
+
+    async def get_status(self, id: str) -> VideoJob:
+        return await self._models.get_video_status(id)
+
+    async def download(self, id: str) -> bytes:
+        return await self._models.download_video(id)
+
+    async def generate_and_save(self, path: str, *, model: str, prompt: str, **kwargs: Any) -> VideoJob:
+        return await self._models.generate_video_and_save(path, model=model, prompt=prompt, **kwargs)
+
+
+def _make_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": "runcrate-python/0.1.0",
+    }
+
+
+class Runcrate:
+    """Synchronous Runcrate API client.
+
+    Usage::
+
+        from runcrate import Runcrate
+
+        client = Runcrate(api_key="rc_live_...")
+        instances = client.instances.list()
+        client.close()
+
+    Or as a context manager::
+
+        with Runcrate(api_key="rc_live_...") as client:
+            instances = client.instances.list()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        inference_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        environment: Optional[str] = None,
+    ) -> None:
+        self._config = ClientConfig.from_args(
+            api_key=api_key,
+            base_url=base_url,
+            inference_url=inference_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            environment=environment,
+        )
+        self._transport = SyncTransport(self._config)
+
+        # Separate httpx client for inference API (api.runcrate.ai)
+        self._inference_client = httpx.Client(
+            base_url=self._config.inference_url,
+            headers=_make_headers(self._config.api_key),
+            timeout=self._config.timeout,
+        )
+
+        self.instances = Instances(self._transport)
+        self.environments = Environments(self._transport)
+        self.ssh_keys = SSHKeys(self._transport)
+        self.storage = Storage(self._transport)
+        self.billing = Billing(self._transport)
+        self.templates = Templates(self._transport)
+        self.models = Models(self._inference_client)
+
+        # OpenAI-compatible aliases
+        self.chat = _Chat(self.models)
+        self.images = _Images(self.models)
+        self.audio = _Audio(self.models)
+        self.videos = _Videos(self.models)
+
+    def close(self) -> None:
+        self._transport.close()
+        self._inference_client.close()
+
+    def __enter__(self) -> Runcrate:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncRuncrate:
+    """Asynchronous Runcrate API client.
+
+    Usage::
+
+        from runcrate import AsyncRuncrate
+
+        async with AsyncRuncrate(api_key="rc_live_...") as client:
+            instances = await client.instances.list()
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        inference_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        environment: Optional[str] = None,
+    ) -> None:
+        self._config = ClientConfig.from_args(
+            api_key=api_key,
+            base_url=base_url,
+            inference_url=inference_url,
+            timeout=timeout,
+            max_retries=max_retries,
+            environment=environment,
+        )
+        self._transport = AsyncTransport(self._config)
+
+        # Separate httpx client for inference API (api.runcrate.ai)
+        self._inference_client = httpx.AsyncClient(
+            base_url=self._config.inference_url,
+            headers=_make_headers(self._config.api_key),
+            timeout=self._config.timeout,
+        )
+
+        self.instances = AsyncInstances(self._transport)
+        self.environments = AsyncEnvironments(self._transport)
+        self.ssh_keys = AsyncSSHKeys(self._transport)
+        self.storage = AsyncStorage(self._transport)
+        self.billing = AsyncBilling(self._transport)
+        self.templates = AsyncTemplates(self._transport)
+        self.models = AsyncModels(self._inference_client)
+
+        # OpenAI-compatible aliases
+        self.chat = _AsyncChat(self.models)
+        self.images = _AsyncImages(self.models)
+        self.audio = _AsyncAudio(self.models)
+        self.videos = _AsyncVideos(self.models)
+
+    async def close(self) -> None:
+        await self._transport.close()
+        await self._inference_client.aclose()
+
+    async def __aenter__(self) -> AsyncRuncrate:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()

runcrate/_config.py

@@ -0,0 +1,51 @@
+"""Client configuration."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+_DEFAULT_BASE_URL = "https://runcrate.ai"
+_DEFAULT_INFERENCE_URL = "https://api.runcrate.ai"
+_DEFAULT_TIMEOUT = 30.0
+_DEFAULT_MAX_RETRIES = 3
+
+
+@dataclass
+class ClientConfig:
+    api_key: str
+    base_url: str = _DEFAULT_BASE_URL
+    inference_url: str = _DEFAULT_INFERENCE_URL
+    timeout: float = _DEFAULT_TIMEOUT
+    max_retries: int = _DEFAULT_MAX_RETRIES
+    custom_headers: dict[str, str] = field(default_factory=dict)
+    environment: Optional[str] = None
+
+    @classmethod
+    def from_args(
+        cls,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        inference_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+        max_retries: Optional[int] = None,
+        environment: Optional[str] = None,
+    ) -> ClientConfig:
+        resolved_key = api_key or os.environ.get("RUNCRATE_API_KEY", "")
+        if not resolved_key:
+            raise ValueError(
+                "API key is required. Pass api_key= or set the RUNCRATE_API_KEY environment variable."
+            )
+        if not resolved_key.startswith("rc_live_"):
+            raise ValueError("Invalid API key format. Keys must start with 'rc_live_'.")
+
+        return cls(
+            api_key=resolved_key,
+            base_url=(base_url or _DEFAULT_BASE_URL).rstrip("/"),
+            inference_url=(inference_url or _DEFAULT_INFERENCE_URL).rstrip("/"),
+            timeout=timeout if timeout is not None else _DEFAULT_TIMEOUT,
+            max_retries=max_retries if max_retries is not None else _DEFAULT_MAX_RETRIES,
+            environment=environment,
+        )

runcrate/_exceptions.py

@@ -0,0 +1,147 @@
+"""Exception hierarchy for the Runcrate SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+import httpx
+
+
+class RuncrateError(Exception):
+    """Base exception for all Runcrate SDK errors."""
+
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class ApiError(RuncrateError):
+    """Raised when the API returns a non-2xx response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str,
+        details: Optional[dict[str, Any]] = None,
+        response: Optional[httpx.Response] = None,
+    ) -> None:
+        self.status_code = status_code
+        self.code = code
+        self.details = details
+        self.response = response
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(status_code={self.status_code}, code={self.code!r}, message={self.message!r})"
+
+
+class BadRequestError(ApiError):
+    """400 - Invalid request parameters."""
+
+
+class AuthenticationError(ApiError):
+    """401 - Invalid or missing API key."""
+
+
+class InsufficientCreditsError(ApiError):
+    """402 - Not enough credits to perform operation."""
+
+
+class PermissionDeniedError(ApiError):
+    """403 - User lacks permission."""
+
+
+class NotFoundError(ApiError):
+    """404 - Resource not found."""
+
+
+class ConflictError(ApiError):
+    """409 - Resource conflict (e.g., duplicate SSH key)."""
+
+
+class UnprocessableEntityError(ApiError):
+    """422 - Validation error (e.g., invalid model parameters)."""
+
+
+class RateLimitError(ApiError):
+    """429 - Rate limit exceeded."""
+
+
+class InternalServerError(ApiError):
+    """500 - Server error."""
+
+
+class ConnectionError(RuncrateError):
+    """Network connectivity failure."""
+
+
+class TimeoutError(RuncrateError):
+    """Request timed out."""
+
+
+_STATUS_MAP: dict[int, type[ApiError]] = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    402: InsufficientCreditsError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    422: UnprocessableEntityError,
+    429: RateLimitError,
+    500: InternalServerError,
+}
+
+
+def _extract_error_info(body: Any) -> tuple[Optional[str], str, Optional[dict[str, Any]]]:
+    """Extract message, code, and details from various error response formats."""
+    if not isinstance(body, dict):
+        return None, "api_error", None
+
+    # Format: { error: { code, message, details } }
+    err = body.get("error")
+    if isinstance(err, dict):
+        return (
+            err.get("message"),
+            err.get("code", "api_error"),
+            err.get("details"),
+        )
+
+    # Format: { error: "string message" }
+    if isinstance(err, str):
+        return err, "api_error", None
+
+    # Format: { message: "string" }
+    if isinstance(body.get("message"), str):
+        return body["message"], body.get("code", "api_error"), None
+
+    # Format: { detail: "string" } (FastAPI style)
+    if isinstance(body.get("detail"), str):
+        return body["detail"], "api_error", None
+
+    return None, "api_error", None
+
+
+def make_api_error(response: httpx.Response) -> ApiError:
+    """Create the appropriate ApiError subclass from an HTTP response."""
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+
+    extracted_message, code, details = _extract_error_info(body)
+
+    # Fallback: use raw response text if we couldn't extract a message
+    if extracted_message is None:
+        text = response.text or ""
+        extracted_message = text[:500] if text else f"HTTP {response.status_code}"
+
+    cls = _STATUS_MAP.get(response.status_code, ApiError)
+    return cls(
+        extracted_message,
+        status_code=response.status_code,
+        code=code,
+        details=details,
+        response=response,
+    )

runcrate/_pagination.py

@@ -0,0 +1,40 @@
+"""Pagination helpers."""
+
+from __future__ import annotations
+
+from typing import Generic, List, Optional, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from runcrate.models.shared import ListMeta
+
+T = TypeVar("T")
+
+
+class PaginatedResponse(Generic[T]):
+    """A single page of results with metadata."""
+
+    def __init__(self, data: List[T], meta: Optional[ListMeta] = None) -> None:
+        self.data = data
+        self.meta = meta or ListMeta()
+
+    @property
+    def has_more(self) -> bool:
+        return self.meta.has_more or False
+
+    @property
+    def cursor(self) -> Optional[str]:
+        return self.meta.cursor
+
+    @property
+    def total(self) -> Optional[int]:
+        return self.meta.total
+
+    def __iter__(self):
+        return iter(self.data)
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        return f"PaginatedResponse(count={len(self.data)}, has_more={self.has_more}, total={self.total})"