strand-sdk 0.1.0__py3-none-any.whl

strand/__init__.py

@@ -0,0 +1,62 @@
+"""Strand Platform Python SDK.
+
+Quickstart — one-call pipeline:
+
+    >>> from strand import Client
+    >>> client = Client()  # reads STRAND_API_KEY
+    >>> result = client.predict(
+    ...     "slide.svs",
+    ...     markers=["CD3", "CD8"],
+    ...     output_dir="./outputs/",
+    ... )
+    >>> print(f"used {result.credits_used} credits")
+
+Lower-level primitives stay available for fine-grained control:
+
+    >>> upload = client.uploads.upload_file("slide.svs")
+    >>> job = client.predict.submit(upload.id, markers=["CD3", "CD8"])
+    >>> job.wait()
+    >>> adata = job.download_results()
+
+See `https://app.strandai.com/docs/api` for the underlying REST API reference.
+"""
+
+from __future__ import annotations
+
+from ._client import Client
+from ._errors import (
+    AuthError,
+    BadRequestError,
+    InsufficientCreditsError,
+    JobFailedError,
+    JobTimeoutError,
+    NotFoundError,
+    RateLimitError,
+    StrandError,
+    UploadError,
+)
+from ._jobs import Job, JobEvent
+from ._models import Estimate, JobStatus, PredictResult, Upload
+from ._results import JobResults
+
+__all__ = [
+    "AuthError",
+    "BadRequestError",
+    "Client",
+    "Estimate",
+    "InsufficientCreditsError",
+    "Job",
+    "JobEvent",
+    "JobFailedError",
+    "JobResults",
+    "JobStatus",
+    "JobTimeoutError",
+    "NotFoundError",
+    "PredictResult",
+    "RateLimitError",
+    "StrandError",
+    "Upload",
+    "UploadError",
+]
+
+__version__ = "0.1.0"

strand/_client.py

@@ -0,0 +1,95 @@
+"""Top-level `Client` — entry point for the SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import httpx
+
+from ._http import DEFAULT_TIMEOUT, HttpSession
+from ._predict import Predict
+from ._uploads import Uploads
+
+if TYPE_CHECKING:
+    from ._jobs import Job
+
+
+class _JobsNamespace:
+    """`client.jobs` namespace — fetch / look up jobs by id."""
+
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, job_id: str) -> Job:
+        """Return a `Job` handle and pre-populate its cached status."""
+        from ._jobs import Job
+
+        job = Job(id=job_id, reserved_credits=None, client=self._client)
+        job.refresh()
+        return job
+
+
+class Client:
+    """Strand Platform API client.
+
+    Args:
+        api_key: API key (`sk-strand-...`). Falls back to `STRAND_API_KEY` env var.
+        base_url: API base URL. Defaults to `STRAND_BASE_URL` env var, else
+            `https://app.strandai.com`. Should not include the `/api/v1` suffix.
+        timeout: Per-request timeout in seconds (or an `httpx.Timeout`).
+        http_client: Pre-built `httpx.Client` for advanced use (e.g., custom
+            transport, retries, ASGI mounting in tests). The SDK will NOT
+            override the client's `Authorization` header — if you pass one,
+            wire auth headers yourself.
+
+    Example — one-call pipeline:
+
+        >>> client = Client(api_key="sk-strand-...")
+        >>> result = client.predict(
+        ...     "slide.svs",
+        ...     markers=["CD3", "CD8"],
+        ...     output_dir="./outputs/",
+        ... )
+        >>> print(f"used {result.credits_used} credits")
+
+    Lower-level primitives (`client.predict` is also a namespace):
+
+        >>> upload = client.uploads.upload_file("slide.svs")
+        >>> estimate = client.predict.estimate(upload.id, markers=["CD3"])
+        >>> job = client.predict.submit(upload.id, markers=["CD3"])
+        >>> job.wait()
+        >>> adata = job.download_results()
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._http = HttpSession(
+            api_key=api_key, base_url=base_url, timeout=timeout, client=http_client
+        )
+        self.uploads = Uploads(self._http)
+        self.predict = Predict(self._http, self)
+        self.jobs = _JobsNamespace(self)
+
+    @property
+    def base_url(self) -> str:
+        return self._http.base_url
+
+    @property
+    def api_root(self) -> str:
+        return self._http.api_root
+
+    def close(self) -> None:
+        """Close the underlying httpx client."""
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

strand/_errors.py

@@ -0,0 +1,92 @@
+"""Typed exceptions for the Strand SDK.
+
+All HTTP-level failures raised by the public surface inherit from `StrandError`.
+Network-level failures (`httpx.HTTPError` and friends) pass through unchanged so
+callers can apply their own retry logic — we only wrap responses that the
+platform itself returned with a documented error shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class StrandError(Exception):
+    """Base class for SDK errors raised against documented API responses."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        error_code: str | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error_code = error_code
+        self.body = body or {}
+
+
+class AuthError(StrandError):
+    """401 — missing / invalid / expired API key."""
+
+
+class BadRequestError(StrandError):
+    """400 — request body or arguments rejected by the server."""
+
+
+class NotFoundError(StrandError):
+    """404 — referenced resource (upload, job, file) does not exist or isn't accessible."""
+
+
+class InsufficientCreditsError(StrandError):
+    """402 — org has insufficient credits to reserve for this job.
+
+    Attributes:
+        required: Credits required to run the job, as returned by the server.
+        balance:  Best-effort cached org balance from the most recent estimate, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        required: int | None = None,
+        balance: int | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, status_code=402, error_code="insufficient_credits", body=body)
+        self.required = required
+        self.balance = balance
+
+
+class RateLimitError(StrandError):
+    """429 — per-org concurrent job cap exceeded. `retry_after` is in seconds."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        retry_after: int | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message, status_code=429, error_code="rate_limited", body=body)
+        self.retry_after = retry_after
+
+
+class JobFailedError(StrandError):
+    """Raised by `Job.wait()` when the job terminates with `status == "failed"`."""
+
+    def __init__(self, message: str, *, job_id: str) -> None:
+        super().__init__(message, error_code="job_failed")
+        self.job_id = job_id
+
+
+class JobTimeoutError(StrandError):
+    """Raised by `Job.wait(timeout=...)` when the wait deadline elapses before terminal status."""
+
+
+class UploadError(StrandError):
+    """Raised when the resumable upload session aborts or returns an unexpected response."""

strand/_http.py

@@ -0,0 +1,213 @@
+"""Thin HTTP helper around the generated `AuthenticatedClient`.
+
+Centralizes:
+- Constructing an `httpx.Client` with our auth header, base URL, and timeouts.
+- Mapping documented error response bodies onto our typed exceptions.
+
+We deliberately do not lean on the generated `client.AuthenticatedClient.with_*`
+helpers — `httpx.Client` is plenty, and we want a single source of truth for
+error mapping.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+from typing import Any, cast
+
+import httpx
+
+from ._errors import (
+    AuthError,
+    BadRequestError,
+    InsufficientCreditsError,
+    NotFoundError,
+    RateLimitError,
+    StrandError,
+)
+
+DEFAULT_BASE_URL = "https://app.strandai.com"
+DEFAULT_TIMEOUT = 60.0
+USER_AGENT = "strand-sdk-python/0.1.0"
+
+
+class HttpSession:
+    """Wraps `httpx.Client` with Strand auth + error mapping."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        base_url: str | None,
+        timeout: float | httpx.Timeout | None,
+        client: httpx.Client | None = None,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("STRAND_API_KEY")
+        if not resolved_key:
+            raise AuthError(
+                "No API key provided. Pass api_key=... or set STRAND_API_KEY.",
+                status_code=401,
+                error_code="missing_api_key",
+            )
+
+        resolved_base = (
+            base_url or os.environ.get("STRAND_BASE_URL") or DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        self.api_key = resolved_key
+        self.base_url = resolved_base
+        self.api_root = f"{resolved_base}/api/v1"
+        self._owned_client = client is None
+        self._client = client or httpx.Client(
+            base_url=self.api_root,
+            timeout=timeout if timeout is not None else DEFAULT_TIMEOUT,
+            headers={
+                "Authorization": f"Bearer {resolved_key}",
+                "User-Agent": USER_AGENT,
+                "Accept": "application/json",
+            },
+            follow_redirects=False,
+        )
+
+    # ---------- lifecycle ----------
+
+    def close(self) -> None:
+        if self._owned_client:
+            self._client.close()
+
+    def __enter__(self) -> HttpSession:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    @property
+    def client(self) -> httpx.Client:
+        return self._client
+
+    # ---------- request helpers ----------
+
+    def request_json(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: dict[str, Any] | None = None,
+        expected: tuple[int, ...] = (200,),
+    ) -> dict[str, Any]:
+        resp = self._client.request(method, path, json=json, params=params)
+        self._raise_for_error(resp)
+        if resp.status_code not in expected:
+            raise StrandError(
+                f"Unexpected status {resp.status_code} for {method} {path}",
+                status_code=resp.status_code,
+                body=_safe_body(resp),
+            )
+        return cast(dict[str, Any], resp.json())
+
+    def request_bytes(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> bytes:
+        resp = self._client.request(method, path, params=params)
+        self._raise_for_error(resp)
+        return resp.content
+
+    def stream_lines(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> Iterator[bytes]:
+        """Yield raw lines (including trailing newlines stripped) from a streaming response.
+
+        Used for the SSE endpoint — callers wrap with httpx-sse for event parsing.
+        """
+        ctx_timeout = (
+            timeout if timeout is not None else httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)
+        )
+        with self._client.stream(method, path, params=params, timeout=ctx_timeout) as resp:
+            self._raise_for_error(resp)
+            for line in resp.iter_lines():
+                yield line.encode("utf-8") if isinstance(line, str) else line
+
+    def stream_response(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        timeout: float | httpx.Timeout | None = None,
+    ) -> httpx.Response:
+        """Open a streaming response and return it; caller must call `.close()`.
+
+        Used by the SSE wait loop with httpx-sse.
+        """
+        ctx_timeout = (
+            timeout if timeout is not None else httpx.Timeout(connect=10.0, read=None, write=10.0, pool=10.0)
+        )
+        req = self._client.build_request(method, path, params=params, timeout=ctx_timeout)
+        return self._client.send(req, stream=True)
+
+    # ---------- error mapping ----------
+
+    def _raise_for_error(self, resp: httpx.Response) -> None:
+        if resp.status_code < 400:
+            return
+
+        body = _safe_body(resp)
+        message = _extract_message(body, resp)
+        error_code = body.get("error") if isinstance(body, dict) else None
+
+        if resp.status_code == 400:
+            raise BadRequestError(message, status_code=400, error_code=error_code, body=body)
+        if resp.status_code == 401:
+            raise AuthError(message, status_code=401, error_code=error_code, body=body)
+        if resp.status_code == 402:
+            required = body.get("required") if isinstance(body, dict) else None
+            raise InsufficientCreditsError(
+                message,
+                required=int(required) if isinstance(required, int) else None,
+                body=body,
+            )
+        if resp.status_code == 404:
+            raise NotFoundError(message, status_code=404, error_code=error_code, body=body)
+        if resp.status_code == 429:
+            retry_after_raw = resp.headers.get("Retry-After")
+            try:
+                retry_after = int(retry_after_raw) if retry_after_raw is not None else None
+            except ValueError:
+                retry_after = None
+            raise RateLimitError(message, retry_after=retry_after, body=body)
+        # 409 and other 4xx with a documented error shape — surface as generic StrandError.
+        raise StrandError(
+            message,
+            status_code=resp.status_code,
+            error_code=error_code,
+            body=body,
+        )
+
+
+def _safe_body(resp: httpx.Response) -> dict[str, Any]:
+    try:
+        data = resp.json()
+    except ValueError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _extract_message(body: dict[str, Any], resp: httpx.Response) -> str:
+    if isinstance(body, dict):
+        msg = body.get("message")
+        if isinstance(msg, str) and msg:
+            return msg
+        err = body.get("error")
+        if isinstance(err, str) and err:
+            return err
+    return f"HTTP {resp.status_code}"

strand/_jobs.py

@@ -0,0 +1,205 @@
+"""Job handle: status polling, SSE waits, results download."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from httpx_sse import EventSource, SSEError
+
+from ._errors import JobFailedError, JobTimeoutError, StrandError
+from ._models import JobStatus
+from ._results import JobResults
+
+if TYPE_CHECKING:
+    from ._client import Client
+
+TERMINAL_STATUSES = frozenset({"completed", "failed"})
+
+
+@dataclass
+class JobEvent:
+    """A single status snapshot pushed over SSE."""
+
+    id: str | None
+    status: str | None
+    progress: float | None
+    result_gcs_path: str | None
+    raw: dict[str, Any]
+
+    @classmethod
+    def _from_payload(cls, payload: dict[str, Any]) -> JobEvent:
+        return cls(
+            id=payload.get("id"),
+            status=payload.get("status"),
+            progress=(
+                float(payload["progress"])
+                if isinstance(payload.get("progress"), (int, float))
+                else None
+            ),
+            result_gcs_path=payload.get("resultGcsPath"),
+            raw=payload,
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in TERMINAL_STATUSES
+
+
+class Job:
+    """Handle for a submitted prediction job.
+
+    Created by `Client.predict.submit(...)` and `Client.jobs.get(...)`.
+    """
+
+    def __init__(self, *, id: str, reserved_credits: int | None, client: Client) -> None:
+        self.id = id
+        self.reserved_credits = reserved_credits
+        self._client = client
+        self._http = client._http
+        self._cached_status: JobStatus | None = None
+
+    # ---------- public surface ----------
+
+    def __repr__(self) -> str:
+        s = self._cached_status.status if self._cached_status else "unknown"
+        return f"Job(id={self.id!r}, status={s!r})"
+
+    def refresh(self) -> JobStatus:
+        """Fetch the latest status snapshot and cache it on the job."""
+        raw = self._http.request_json("GET", f"/jobs/{self.id}")
+        status = JobStatus._from_dict(raw)
+        self._cached_status = status
+        return status
+
+    @property
+    def status(self) -> JobStatus:
+        """Most recently fetched status. Calls `refresh()` if none cached."""
+        if self._cached_status is None:
+            return self.refresh()
+        return self._cached_status
+
+    def stream_events(self) -> Iterator[JobEvent]:
+        """Yield `JobEvent`s as the server emits them.
+
+        The generator closes when the job reaches a terminal status. The platform
+        emits `: keep-alive` heartbeats; httpx-sse filters those out.
+        """
+        resp = self._http.stream_response("GET", f"/jobs/{self.id}/stream")
+        try:
+            try:
+                event_source = EventSource(resp)
+                for sse in event_source.iter_sse():
+                    if sse.event and sse.event != "message":
+                        continue
+                    data = sse.data
+                    if not data:
+                        continue
+                    try:
+                        payload = json.loads(data)
+                    except json.JSONDecodeError:
+                        continue
+                    if not isinstance(payload, dict):
+                        continue
+                    if "error" in payload and "status" not in payload:
+                        raise StrandError(
+                            f"Server reported error in stream: {payload['error']}",
+                            body=payload,
+                        )
+                    event = JobEvent._from_payload(payload)
+                    yield event
+                    if event.is_terminal:
+                        return
+            except SSEError as exc:  # malformed stream → fall back to polling.
+                raise StrandError(f"Malformed SSE stream: {exc}") from exc
+        finally:
+            resp.close()
+
+    def wait(
+        self,
+        *,
+        timeout: float | None = None,
+        poll_interval: float = 2.0,
+        use_stream: bool = True,
+    ) -> JobStatus:
+        """Block until the job reaches a terminal status.
+
+        Args:
+            timeout: Max seconds to wait. `None` waits forever.
+            poll_interval: Used by the polling fallback if `use_stream=False`
+                or if the stream connection drops mid-job.
+            use_stream: When `True` (default), prefer SSE; fall back to polling
+                if the stream errors out.
+
+        Returns:
+            The terminal `JobStatus`.
+
+        Raises:
+            JobFailedError: status terminates as `"failed"`.
+            JobTimeoutError: `timeout` elapses before terminal status.
+        """
+        deadline = time.monotonic() + timeout if timeout is not None else None
+
+        def _check_deadline() -> None:
+            if deadline is not None and time.monotonic() > deadline:
+                raise JobTimeoutError(
+                    f"Job {self.id} did not reach terminal status within {timeout}s",
+                )
+
+        if use_stream:
+            try:
+                for event in self.stream_events():
+                    _check_deadline()
+                    if event.is_terminal:
+                        break
+            except (httpx.HTTPError, StrandError):
+                # Drop down to polling — possibly a transient disconnect.
+                pass
+
+        while True:
+            _check_deadline()
+            status = self.refresh()
+            if status.is_terminal:
+                if status.status == "failed":
+                    raise JobFailedError(
+                        status.error_message or f"Job {self.id} failed",
+                        job_id=self.id,
+                    )
+                return status
+            sleep_for = poll_interval
+            if deadline is not None:
+                sleep_for = min(sleep_for, max(0.0, deadline - time.monotonic()))
+            if sleep_for <= 0:
+                _check_deadline()
+            time.sleep(sleep_for)
+
+    def results(self) -> JobResults:
+        """Return a `JobResults` handle (lazy — does not fetch zarr bytes)."""
+        raw = self._http.request_json("GET", f"/jobs/{self.id}/results")
+        return JobResults(
+            job_id=self.id,
+            result_url=str(raw["resultUrl"]),
+            result_base_path=str(raw.get("resultBasePath", "")),
+            expires_at=str(raw["expiresAt"]),
+            client=self._client,
+        )
+
+    def download_results(
+        self,
+        path: str | None = None,
+    ) -> Any:
+        """Download all result zarr files.
+
+        - If `path` is `None` (default), parse the zarr in-memory and return an
+          `AnnData` object (requires the `anndata` extra).
+        - If `path` is given, write the zarr store to that directory and return
+          the `Path`. No `anndata` dependency required.
+        """
+        results = self.results()
+        if path is None:
+            return results.to_anndata()
+        return results.download_to(path)