Metadata-Version: 2.5
Name: strand-sdk
Version: 0.18.0
Summary: Official Python client for Lattice spatial proteomics from H&E — predicted virtual mIF protein-marker channels.
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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: google-crc32c>=1.6
Requires-Dist: httpx-sse>=0.4
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.10
Provides-Extra: anndata
Requires-Dist: anndata>=0.10; extra == 'anndata'
Requires-Dist: numpy>=1.24; extra == 'anndata'
Requires-Dist: zstandard>=0.22; (python_version < '3.14') and 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'
Requires-Dist: zarr==3.1.5; extra == 'dev'
Requires-Dist: zstandard>=0.22; (python_version < '3.14') and extra == 'dev'
Description-Content-Type: text/markdown

# strand-sdk

Python client for [Lattice spatial proteomics from H&E](https://strandai.com/lattice).
Upload H&E whole-slide images, predict spatially resolved protein-marker maps,
and download the virtual mIF channels as AnnData or OME-Zarr/OME-TIFF.

📚 **Full documentation: <https://docs.strandai.com/sdks/python>**

Agent-readable API reference: <https://app.strandai.com/docs/api.md> · LLM
index: <https://app.strandai.com/llms.txt>

Requires Python 3.12+.

## Install

```bash
pip install strand-sdk
# or with bioinformatics extras (AnnData / zarr):
pip install "strand-sdk[anndata]"
```

The package also installs the `strand` command. It supports the same sample
and run lifecycle without renaming the SDK-native verbs:

```bash
sample_id=$(strand upload biopsy.svs --mpp 0.26 | jq -r .id)
while :; do
  status=$(strand samples get "$sample_id" | jq -r .status)
  case "$status" in ready) break ;; *failed) exit 1 ;; esac
  sleep 2
done
strand predict "$sample_id" -m CD4,PanCK --dry-run
job_id=$(strand predict "$sample_id" -m CD4,PanCK | jq -r .job_id)
strand wait "$job_id" --timeout 1800
strand export "$job_id" --format ome-tiff --out result.ome.tiff --timeout 1800
```

Use `strand cancel "$job_id"` for an eligible in-flight run and `strand
results "$job_id" --out ./results/` for the OME-Zarr tree.

## Quickstart

One blocking call runs the full pipeline: upload, submit, wait, and download.

```python
from uuid import uuid4

from strand import Client, SampleFieldFilter

client = Client()  # reads STRAND_API_KEY; mint one at https://app.strandai.com/settings/api-keys
result = client.predict(
    "biopsy.ome.tiff",
    markers=["PanCK", "CD4", "CD45"],
    output_dir="./outputs/",
)
print(f"Used {result.credits_used} credits; wrote {len(result.marker_outputs)} markers")
```

Scoped sample reads and updates use one namespace:

```python
cohort = client.samples.create_field(
    "Study cohort", "single_select",
    options=["Discovery", "Validation"],
    description="Study arm used for analysis",
)
print(cohort.key, cohort.description)
definitions = client.samples.fields()
tags_id = next(field.id for field in definitions if field.key == "tags")
page = client.samples.list(
    scope="mine",
    field=SampleFieldFilter(tags_id, "eq", "trial-042"),
)
sample_id = page.items[0].id
sample = client.samples.get(sample_id)
client.samples.patch(
    sample_id,
    name="Baseline",
    fields={"tags": ["trial-042"]},
    mpp=0.26,
)

estimate = client.predict.submit(sample_id, ["CD4", "PanCK"], dry_run=True)
job = client.predict.submit(
    sample_id,
    ["CD4", "PanCK"],
    expected_estimate=estimate,
    idempotency_key=str(uuid4()),
)
```

The `expected_estimate`/`idempotency_key` example requires the matching REST
release and idempotency migration. This local integration candidate does not
attest that the current production endpoint is upgraded. Coordinate API rollout
before enabling modern MCP paid confirmation; native forms are an MCP host
workflow, not a new SDK prompt or a change to legacy direct SDK submission.
Uploads still stream directly to GCS, never through ChatGPT or MCP.

Persist an idempotency key until its submission response is safely recorded, and
reuse it only for that exact request. Exact retries return the original job
without another reservation while the job remains stored. Hard deletion of the
job, its sample, organization, or account removes the mapping and ends that
replay guarantee.

Uploads, model selection, async jobs, public OME-Zarr reads, OME-TIFF export,
and error handling are covered in the
[hosted docs](https://docs.strandai.com/sdks/python).

## Signed whole-object results

With the matching REST endpoint deployed, whole stored objects can use an
opt-in version-pinned transport; the authenticated proxy remains the default:

```python
results = job.results()
plan = results.get_signed_files(paths, max_download_bytes=64 * 1024**2)
print(plan.total_bytes)  # complete payload preflight, no storage download
raw_files = plan.download()  # or get_files_batch(paths, transport="signed", ...)
```

Signed mode is raw-only. It validates every manifest before payload I/O, enforces
the complete byte budget, uses a fresh unauthenticated storage client, and checks
expiry, version, length and available MD5/CRC32C checksums. It does not refresh
URLs or return silent partial results. Capability URLs stay in memory: never
persist manifest bodies or provider error bodies. Instrument both API and storage
transports when metering requests/bytes; see the hosted Python docs for the
`storage_client_factory` guard seam and logging boundaries.

## Issues & support

File bug reports and feature requests at
[Strand-AI/strand-sdk-python/issues](https://github.com/Strand-AI/strand-sdk-python/issues),
or email [support@strandai.com](mailto:support@strandai.com). This repository
is a generated, read-only mirror of Strand's monorepo. Pull requests opened
here are overwritten by the next sync.

## License

Apache 2.0
