strand-sdk 0.1.0__tar.gz

strand_sdk-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.egg-info/
+dist/
+build/
+uv.lock

strand_sdk-0.1.0/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+   Copyright 2026 Strand AI, Inc.

strand_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,167 @@
+Metadata-Version: 2.4
+Name: strand-sdk
+Version: 0.1.0
+Summary: Official Python client for the Strand Platform API — H&E → multiplex protein inference.
+Project-URL: Homepage, https://strandai.com
+Project-URL: Documentation, https://docs.strandai.com
+Project-URL: Repository, https://github.com/Strand-AI/strand-sdk-python
+Project-URL: Source, https://github.com/Strand-AI/strand-sdk-python
+Project-URL: Issues, https://github.com/Strand-AI/strand-sdk-python/issues
+Project-URL: Changelog, https://github.com/Strand-AI/strand-sdk-python/blob/main/CHANGELOG.md
+Author-email: Strand AI <support@strandai.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: anndata,bioinformatics,h&e,imputation,pathology,spatial-omics,strand
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: typing-extensions>=4.10
+Provides-Extra: anndata
+Requires-Dist: anndata>=0.10; extra == 'anndata'
+Requires-Dist: numpy>=1.24; extra == 'anndata'
+Provides-Extra: dev
+Requires-Dist: anndata>=0.10; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: numpy>=1.24; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# strand-sdk
+
+Python client for the [Strand Platform](https://strandai.com) — H&E → multiplex protein inference.
+
+**Agent-friendly docs:** The full API reference is published as Markdown at [https://app.strandai.com/docs/api.md](https://app.strandai.com/docs/api.md), and the LLM index lives at [https://app.strandai.com/llms.txt](https://app.strandai.com/llms.txt).
+
+```bash
+pip install strand-sdk
+# or with bioinformatics extras (AnnData / zarr):
+pip install "strand-sdk[anndata]"
+```
+
+If your environment can't reach PyPI, you can install directly from the
+repository as a fallback:
+
+```bash
+pip install "git+https://github.com/Strand-AI/strand-sdk-python.git"
+```
+
+## Quickstart
+
+One blocking call runs the full pipeline — upload, submit, wait, download:
+
+```python
+from strand import Client
+
+client = Client(api_key="sk-strand-...")
+result = client.predict(
+    "biopsy.ome.tiff",
+    markers=["HER2", "CD8", "PD1"],
+    output_dir="./outputs/",
+)
+print(f"Used {result.credits_used} credits; wrote {len(result.marker_outputs)} markers")
+```
+
+`client.predict(...)` returns a `PredictResult` with `job_id`, `status`,
+`credits_used`, `marker_outputs` (paths under `output_dir`), and `results`
+(a `JobResults` handle for selective reads). It raises `JobFailedError` if the
+job fails, `JobTimeoutError` if the deadline elapses, and surfaces
+`InsufficientCreditsError` / `RateLimitError` on submit issues.
+
+Pass `on_progress=lambda stage, frac: ...` to follow the four stages
+(`"upload"`, `"submit"`, `"wait"`, `"download"`).
+
+### Lower-level primitives
+
+`client.predict` is also a namespace, so the underlying steps stay available
+for fine-grained control:
+
+```python
+upload = client.uploads.upload_file("slide.svs")
+estimate = client.predict.estimate(upload.id, markers=["CD3", "CD8", "Ki67"])
+print(f"Will cost ≈ {estimate.estimated_credits} credits")
+
+job = client.predict.submit(upload.id, markers=["CD3", "CD8", "Ki67"])
+job.wait()                                    # blocks until terminal status
+adata = job.download_results()                # AnnData
+```
+
+## Configuration
+
+| Source | Variable / argument | Default |
+|---|---|---|
+| Env | `STRAND_API_KEY` | required |
+| Env | `STRAND_BASE_URL` | `https://app.strandai.com` |
+| Arg | `Client(api_key=..., base_url=..., timeout=..., max_retries=...)` | — |
+
+## Layout
+
+```
+src/strand/
+  __init__.py        public surface re-exports
+  _client.py         Client (top-level)
+  _uploads.py        uploads namespace (incl. resumable chunked upload helper)
+  _predict.py        predict namespace — `client.predict(...)` (full pipeline) + `.estimate` / `.submit`
+  _jobs.py           Job (wait / stream_events / download_results)
+  _results.py        OME-Zarr v3 download + AnnData conversion
+  _models.py         user-facing snake_case dataclasses
+  _http.py           internal httpx wrapper with typed error mapping
+  _errors.py         typed exceptions
+openapi.json         pinned snapshot of the platform spec (drift-check)
+```
+
+## Verifying against the platform OpenAPI spec
+
+Transport is hand-written for ergonomic snake_case fields and AnnData
+integration. To check the SDK against an updated spec:
+
+```bash
+# regenerate a reference client and diff the request/response surface
+uv tool run --from "openapi-python-client>=0.21" --with "click<8.2" \
+    openapi-python-client generate \
+    --path openapi.json \
+    --output-path /tmp/strand-sdk-ref \
+    --meta none --overwrite
+```
+
+To refresh `openapi.json` itself against a live server:
+
+```bash
+curl https://app.strandai.com/api/v1/openapi.json -o openapi.json
+# or against local dev:
+# curl http://localhost:3000/api/v1/openapi.json -o openapi.json
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+## Issues & contributing
+
+File bug reports and feature requests at
+[Strand-AI/strand-sdk-python/issues](https://github.com/Strand-AI/strand-sdk-python/issues).
+
+We don't accept external pull requests on the SDK at this time. If you'd like
+to contribute or have ideas you'd like to discuss, email
+[support@strandai.com](mailto:support@strandai.com).
+
+## License
+
+Apache 2.0

strand_sdk-0.1.0/README.md

@@ -0,0 +1,126 @@
+# strand-sdk
+
+Python client for the [Strand Platform](https://strandai.com) — H&E → multiplex protein inference.
+
+**Agent-friendly docs:** The full API reference is published as Markdown at [https://app.strandai.com/docs/api.md](https://app.strandai.com/docs/api.md), and the LLM index lives at [https://app.strandai.com/llms.txt](https://app.strandai.com/llms.txt).
+
+```bash
+pip install strand-sdk
+# or with bioinformatics extras (AnnData / zarr):
+pip install "strand-sdk[anndata]"
+```
+
+If your environment can't reach PyPI, you can install directly from the
+repository as a fallback:
+
+```bash
+pip install "git+https://github.com/Strand-AI/strand-sdk-python.git"
+```
+
+## Quickstart
+
+One blocking call runs the full pipeline — upload, submit, wait, download:
+
+```python
+from strand import Client
+
+client = Client(api_key="sk-strand-...")
+result = client.predict(
+    "biopsy.ome.tiff",
+    markers=["HER2", "CD8", "PD1"],
+    output_dir="./outputs/",
+)
+print(f"Used {result.credits_used} credits; wrote {len(result.marker_outputs)} markers")
+```
+
+`client.predict(...)` returns a `PredictResult` with `job_id`, `status`,
+`credits_used`, `marker_outputs` (paths under `output_dir`), and `results`
+(a `JobResults` handle for selective reads). It raises `JobFailedError` if the
+job fails, `JobTimeoutError` if the deadline elapses, and surfaces
+`InsufficientCreditsError` / `RateLimitError` on submit issues.
+
+Pass `on_progress=lambda stage, frac: ...` to follow the four stages
+(`"upload"`, `"submit"`, `"wait"`, `"download"`).
+
+### Lower-level primitives
+
+`client.predict` is also a namespace, so the underlying steps stay available
+for fine-grained control:
+
+```python
+upload = client.uploads.upload_file("slide.svs")
+estimate = client.predict.estimate(upload.id, markers=["CD3", "CD8", "Ki67"])
+print(f"Will cost ≈ {estimate.estimated_credits} credits")
+
+job = client.predict.submit(upload.id, markers=["CD3", "CD8", "Ki67"])
+job.wait()                                    # blocks until terminal status
+adata = job.download_results()                # AnnData
+```
+
+## Configuration
+
+| Source | Variable / argument | Default |
+|---|---|---|
+| Env | `STRAND_API_KEY` | required |
+| Env | `STRAND_BASE_URL` | `https://app.strandai.com` |
+| Arg | `Client(api_key=..., base_url=..., timeout=..., max_retries=...)` | — |
+
+## Layout
+
+```
+src/strand/
+  __init__.py        public surface re-exports
+  _client.py         Client (top-level)
+  _uploads.py        uploads namespace (incl. resumable chunked upload helper)
+  _predict.py        predict namespace — `client.predict(...)` (full pipeline) + `.estimate` / `.submit`
+  _jobs.py           Job (wait / stream_events / download_results)
+  _results.py        OME-Zarr v3 download + AnnData conversion
+  _models.py         user-facing snake_case dataclasses
+  _http.py           internal httpx wrapper with typed error mapping
+  _errors.py         typed exceptions
+openapi.json         pinned snapshot of the platform spec (drift-check)
+```
+
+## Verifying against the platform OpenAPI spec
+
+Transport is hand-written for ergonomic snake_case fields and AnnData
+integration. To check the SDK against an updated spec:
+
+```bash
+# regenerate a reference client and diff the request/response surface
+uv tool run --from "openapi-python-client>=0.21" --with "click<8.2" \
+    openapi-python-client generate \
+    --path openapi.json \
+    --output-path /tmp/strand-sdk-ref \
+    --meta none --overwrite
+```
+
+To refresh `openapi.json` itself against a live server:
+
+```bash
+curl https://app.strandai.com/api/v1/openapi.json -o openapi.json
+# or against local dev:
+# curl http://localhost:3000/api/v1/openapi.json -o openapi.json
+```
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+## Issues & contributing
+
+File bug reports and feature requests at
+[Strand-AI/strand-sdk-python/issues](https://github.com/Strand-AI/strand-sdk-python/issues).
+
+We don't accept external pull requests on the SDK at this time. If you'd like
+to contribute or have ideas you'd like to discuss, email
+[support@strandai.com](mailto:support@strandai.com).
+
+## License
+
+Apache 2.0

strand_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "strand-sdk"
+version = "0.1.0"
+description = "Official Python client for the Strand Platform API — H&E → multiplex protein inference."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Strand AI", email = "support@strandai.com" },
+]
+keywords = ["bioinformatics", "spatial-omics", "pathology", "h&e", "imputation", "anndata", "strand"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+    "httpx-sse>=0.4",
+    "typing-extensions>=4.10",
+]
+
+[project.optional-dependencies]
+anndata = ["anndata>=0.10", "numpy>=1.24"]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "anndata>=0.10",
+    "numpy>=1.24",
+]
+
+[project.urls]
+Homepage = "https://strandai.com"
+Documentation = "https://docs.strandai.com"
+Repository = "https://github.com/Strand-AI/strand-sdk-python"
+Source = "https://github.com/Strand-AI/strand-sdk-python"
+Issues = "https://github.com/Strand-AI/strand-sdk-python/issues"
+Changelog = "https://github.com/Strand-AI/strand-sdk-python/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/strand"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/strand", "README.md", "LICENSE"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/strand"]
+
+[[tool.mypy.overrides]]
+module = ["anndata", "httpx_sse"]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+filterwarnings = ["error"]

strand_sdk-0.1.0/src/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_sdk-0.1.0/src/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_sdk-0.1.0/src/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."""