dysplai 1.0.0__tar.gz

dysplai-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: dysplai
+Version: 1.0.0
+Summary: DYSPLAI Oncology Intelligence API — Python SDK (Research Use Only)
+Author: Dysplasia Diagnostics Limited
+License: Proprietary
+Project-URL: Homepage, https://www.dysplasiadx.com
+Project-URL: Documentation, https://www.dysplasiadx.com/developers
+Keywords: oncology,bioinformatics,genomics,transcriptomics,research,api,sdk
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Healthcare Industry
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: typing-extensions>=4.0
+Provides-Extra: async
+Requires-Dist: anyio>=4.0; extra == "async"
+Provides-Extra: notebooks
+Requires-Dist: pandas>=2.0; extra == "notebooks"
+Requires-Dist: matplotlib>=3.8; extra == "notebooks"
+Requires-Dist: seaborn>=0.13; extra == "notebooks"
+Requires-Dist: ipywidgets>=8.0; extra == "notebooks"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: pyyaml>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# DYSPLAI Python SDK
+
+**For Research Use Only. Not for use in diagnostic procedures.**
+
+Typed Python client for the DYSPLAI Oncology Intelligence API. Covers all seven API surfaces with Pydantic v2 response models and a blocking `wait()` helper for long-running analysis jobs.
+
+## Install
+
+```bash
+pip install dysplai
+# with notebook dependencies:
+pip install "dysplai[notebooks]"
+```
+
+## Quick start
+
+```python
+from dysplai import DysplaiClient
+
+with DysplaiClient(api_key="your-key") as client:
+    # Submit a molecular analysis
+    job = client.analysis.submit(
+        input_uri="gs://your-bucket/sample.csv",
+        sample_id="SAMPLE_001",
+        cancer_type_hint="lung_adeno",
+    )
+
+    # Wait for analysis to complete (~5–15 min)
+    result = client.analysis.wait(job.analysis_id, poll_interval=10)
+
+    print(result.cancer_type_probabilities)
+    print(result.biological_neighbourhood_description)
+    print(result.ruo_disclaimer)
+```
+
+## API surfaces
+
+| Service | Attribute | Methods |
+|---|---|---|
+| Analysis | `client.analysis` | `submit`, `status`, `result`, `wait`, `list` |
+| Cohort | `client.cohort` | `summarise`, `compare`, `neighbours` |
+| Counterfactual | `client.counterfactual` | `sensitivity`, `simulate`, `features`, `pathway_shift_search` |
+| Interpretation | `client.interpretation` | `generate`, `classify_intent` |
+| Reports | `client.reports` | `generate`, `status`, `wait`, `download`, `list` |
+| Clinical | `client.clinical` | `parse`, `annotate`, `labels`, `timeline`, `get_mapping` |
+
+## Counterfactual example
+
+```python
+# Pathway sensitivity gradients
+sens = client.counterfactual.sensitivity(result.analysis_id)
+print(sens.validity_panel.interpretation_status)
+for s in sorted(sens.sensitivities, key=lambda x: abs(x.gradient), reverse=True)[:5]:
+    print(f"  {s.pathway}: {s.gradient:+.4f}")
+
+# Simulate atlas shift — conservative perturbation bounds 0.5×–2.0×
+sim = client.counterfactual.simulate(
+    analysis_id=result.analysis_id,
+    perturbations={"HALLMARK_GLYCOLYSIS": 1.5, "HALLMARK_MYC_TARGETS_V1": 0.7},
+)
+print(sim.atlas_shift.neighbourhood_shift_description)
+```
+
+## Cohort comparison
+
+```python
+summary = client.cohort.summarise(["id-1", "id-2", "id-3"])
+
+comparison = client.cohort.compare(
+    group_a_analysis_ids=["id-1", "id-2"],
+    group_b_analysis_ids=["id-3", "id-4"],
+    fdr_threshold=0.05,
+)
+for p in comparison.differential_pathways[:5]:
+    print(f"{p.pathway}: delta={p.delta:+.3f}  q={p.fdr_q_value:.3e}")
+```
+
+## Report generation
+
+```python
+report = client.reports.generate(result.analysis_id, format="pdf")
+ready  = client.reports.wait(report.report_id)
+client.reports.download(ready.report_id, "sample_report.pdf")
+```
+
+## Clinical metadata
+
+```python
+parsed = client.clinical.parse(
+    {"diagnosis": "NSCLC", "age_at_diagnosis": 60, "ecog_ps": 1},
+)  # direct identifiers are stripped automatically
+client.clinical.annotate(result.analysis_id, clinical_record_id=parsed.clinical_record_id)
+
+# Outcome labels + timepoint harmonisation from the same record
+labels = client.clinical.labels("treatment_start", clinical_record_id=parsed.clinical_record_id)
+timeline = client.clinical.timeline(
+    [{"clinical_record_id": parsed.clinical_record_id}],
+    index_event_type="treatment_start",
+)
+```
+
+## Error handling
+
+```python
+from dysplai import AuthError, QuotaError, NotFoundError, ValidationError
+
+try:
+    result = client.analysis.result("unknown-id")
+except NotFoundError:
+    print("Analysis not found")
+except QuotaError:
+    print("Quota exceeded")
+except AuthError:
+    print("Invalid or expired API key")
+```
+
+## Notebooks
+
+Five Colab-runnable notebooks are in `sdk/notebooks/`:
+
+| Notebook | Topic |
+|---|---|
+| `01_cohort_phenotyping.ipynb` | Cohort summarisation, group comparison, volcano plot |
+| `02_responder_fingerprinting.ipynb` | Submit, wait, pathway fingerprint, atlas neighbours |
+| `03_pathway_counterfactual.ipynb` | Sensitivity gradients, simulate, natural-language shift search |
+| `04_resistance_surveillance.ipynb` | Serial timepoint atlas drift, immune phenotype monitoring |
+| `05_clinical_metadata_enrichment.ipynb` | De-identification, normalisation, batch annotation |
+
+## RUO notice
+
+All response objects include `ruo_disclaimer: "For Research Use Only. Not for use in diagnostic procedures."` This field is present on every molecular result, cohort output, counterfactual response, interpretation, and report. It is not suppressible.

dysplai-1.0.0/README.md

@@ -0,0 +1,131 @@
+# DYSPLAI Python SDK
+
+**For Research Use Only. Not for use in diagnostic procedures.**
+
+Typed Python client for the DYSPLAI Oncology Intelligence API. Covers all seven API surfaces with Pydantic v2 response models and a blocking `wait()` helper for long-running analysis jobs.
+
+## Install
+
+```bash
+pip install dysplai
+# with notebook dependencies:
+pip install "dysplai[notebooks]"
+```
+
+## Quick start
+
+```python
+from dysplai import DysplaiClient
+
+with DysplaiClient(api_key="your-key") as client:
+    # Submit a molecular analysis
+    job = client.analysis.submit(
+        input_uri="gs://your-bucket/sample.csv",
+        sample_id="SAMPLE_001",
+        cancer_type_hint="lung_adeno",
+    )
+
+    # Wait for analysis to complete (~5–15 min)
+    result = client.analysis.wait(job.analysis_id, poll_interval=10)
+
+    print(result.cancer_type_probabilities)
+    print(result.biological_neighbourhood_description)
+    print(result.ruo_disclaimer)
+```
+
+## API surfaces
+
+| Service | Attribute | Methods |
+|---|---|---|
+| Analysis | `client.analysis` | `submit`, `status`, `result`, `wait`, `list` |
+| Cohort | `client.cohort` | `summarise`, `compare`, `neighbours` |
+| Counterfactual | `client.counterfactual` | `sensitivity`, `simulate`, `features`, `pathway_shift_search` |
+| Interpretation | `client.interpretation` | `generate`, `classify_intent` |
+| Reports | `client.reports` | `generate`, `status`, `wait`, `download`, `list` |
+| Clinical | `client.clinical` | `parse`, `annotate`, `labels`, `timeline`, `get_mapping` |
+
+## Counterfactual example
+
+```python
+# Pathway sensitivity gradients
+sens = client.counterfactual.sensitivity(result.analysis_id)
+print(sens.validity_panel.interpretation_status)
+for s in sorted(sens.sensitivities, key=lambda x: abs(x.gradient), reverse=True)[:5]:
+    print(f"  {s.pathway}: {s.gradient:+.4f}")
+
+# Simulate atlas shift — conservative perturbation bounds 0.5×–2.0×
+sim = client.counterfactual.simulate(
+    analysis_id=result.analysis_id,
+    perturbations={"HALLMARK_GLYCOLYSIS": 1.5, "HALLMARK_MYC_TARGETS_V1": 0.7},
+)
+print(sim.atlas_shift.neighbourhood_shift_description)
+```
+
+## Cohort comparison
+
+```python
+summary = client.cohort.summarise(["id-1", "id-2", "id-3"])
+
+comparison = client.cohort.compare(
+    group_a_analysis_ids=["id-1", "id-2"],
+    group_b_analysis_ids=["id-3", "id-4"],
+    fdr_threshold=0.05,
+)
+for p in comparison.differential_pathways[:5]:
+    print(f"{p.pathway}: delta={p.delta:+.3f}  q={p.fdr_q_value:.3e}")
+```
+
+## Report generation
+
+```python
+report = client.reports.generate(result.analysis_id, format="pdf")
+ready  = client.reports.wait(report.report_id)
+client.reports.download(ready.report_id, "sample_report.pdf")
+```
+
+## Clinical metadata
+
+```python
+parsed = client.clinical.parse(
+    {"diagnosis": "NSCLC", "age_at_diagnosis": 60, "ecog_ps": 1},
+)  # direct identifiers are stripped automatically
+client.clinical.annotate(result.analysis_id, clinical_record_id=parsed.clinical_record_id)
+
+# Outcome labels + timepoint harmonisation from the same record
+labels = client.clinical.labels("treatment_start", clinical_record_id=parsed.clinical_record_id)
+timeline = client.clinical.timeline(
+    [{"clinical_record_id": parsed.clinical_record_id}],
+    index_event_type="treatment_start",
+)
+```
+
+## Error handling
+
+```python
+from dysplai import AuthError, QuotaError, NotFoundError, ValidationError
+
+try:
+    result = client.analysis.result("unknown-id")
+except NotFoundError:
+    print("Analysis not found")
+except QuotaError:
+    print("Quota exceeded")
+except AuthError:
+    print("Invalid or expired API key")
+```
+
+## Notebooks
+
+Five Colab-runnable notebooks are in `sdk/notebooks/`:
+
+| Notebook | Topic |
+|---|---|
+| `01_cohort_phenotyping.ipynb` | Cohort summarisation, group comparison, volcano plot |
+| `02_responder_fingerprinting.ipynb` | Submit, wait, pathway fingerprint, atlas neighbours |
+| `03_pathway_counterfactual.ipynb` | Sensitivity gradients, simulate, natural-language shift search |
+| `04_resistance_surveillance.ipynb` | Serial timepoint atlas drift, immune phenotype monitoring |
+| `05_clinical_metadata_enrichment.ipynb` | De-identification, normalisation, batch annotation |
+
+## RUO notice
+
+All response objects include `ruo_disclaimer: "For Research Use Only. Not for use in diagnostic procedures."` This field is present on every molecular result, cohort output, counterfactual response, interpretation, and report. It is not suppressible.

dysplai-1.0.0/dysplai/__init__.py

@@ -0,0 +1,66 @@
+"""DYSPLAI Oncology Intelligence API — Python SDK.
+
+For Research Use Only. Not for use in diagnostic procedures.
+
+Quick start::
+
+    from dysplai import DysplaiClient
+
+    client = DysplaiClient(api_key="your-key")
+
+    # Submit and wait for analysis
+    job = client.analysis.submit("gs://bucket/sample.csv", input_type="count_matrix",
+                                 sample_id="S001")
+    result = client.analysis.wait(job.analysis_id)
+
+    # Pathway sensitivity
+    sens = client.counterfactual.sensitivity(result.analysis_id)
+
+    # Research interpretation (grounded in an analysis)
+    interp = client.interpretation.query(
+        "Which pathways are enriched in this molecular neighbourhood?",
+        analysis_id=result.analysis_id,
+    )
+    print(interp.answer)
+"""
+from .client import (
+    AuthError,
+    DysplaiClient,
+    DysplaiError,
+    InsufficientCreditsError,
+    NotFoundError,
+    QuotaError,
+    ValidationError,
+)
+from .models import (
+    AnalysisResult,
+    AnalysisSubmitResponse,
+    ClinicalAnnotateResponse,
+    ClinicalParseResponse,
+    CohortCompareResponse,
+    CohortSummaryResponse,
+    CreditBalance,
+    Identity,
+    InterpretationResponse,
+    NeighboursResponse,
+    ReportMetadata,
+    SensitivityResponse,
+    SimulationResponse,
+    UsageSummary,
+    ValidityPanel,
+)
+
+__version__ = "1.0.0"
+__all__ = [
+    "DysplaiClient",
+    "DysplaiError", "AuthError", "QuotaError", "InsufficientCreditsError",
+    "NotFoundError", "ValidationError",
+    "ValidityPanel",
+    "AnalysisSubmitResponse", "AnalysisResult",
+    "CohortSummaryResponse", "CohortCompareResponse", "NeighboursResponse",
+    "SensitivityResponse", "SimulationResponse",
+    "InterpretationResponse",
+    "ReportMetadata",
+    "ClinicalParseResponse", "ClinicalAnnotateResponse",
+    "Identity", "CreditBalance", "UsageSummary",
+]

dysplai-1.0.0/dysplai/account.py

@@ -0,0 +1,33 @@
+"""Account service client — identity, metered usage, and credit balance.
+
+Wraps the two gateway-exposed account endpoints:
+
+- ``GET /v1/whoami`` — the tenant + capability scopes behind the calling key.
+- ``GET /v1/usage``  — current-period metered usage against limits, plus the
+  credit balance when billing is active.
+
+Credits are the billing currency: a request that needs more than the
+available balance is rejected with HTTP 402 (``InsufficientCreditsError``), so
+``balance()`` is the pre-flight a caller uses to check headroom.
+"""
+from __future__ import annotations
+
+from .client import _Client
+from .models import CreditBalance, Identity, UsageSummary
+
+
+class AccountService:
+    def __init__(self, http: _Client) -> None:
+        self._http = http
+
+    def whoami(self) -> Identity:
+        """Identify the tenant and capability scopes behind the calling key."""
+        return Identity.model_validate(self._http.get("/v1/whoami"))
+
+    def usage(self) -> UsageSummary:
+        """Current billing-period metered usage, limits, and credit balance."""
+        return UsageSummary.model_validate(self._http.get("/v1/usage"))
+
+    def balance(self) -> CreditBalance | None:
+        """Convenience: the credit balance, or None when billing is inactive."""
+        return self.usage().credits

dysplai-1.0.0/dysplai/analysis.py

@@ -0,0 +1,174 @@
+"""Analysis service client — submission, polling, and result retrieval."""
+from __future__ import annotations
+
+import builtins
+import time
+
+from .client import _Client
+from .models import AnalysisResult, AnalysisSubmitResponse
+
+_BASE = "/v1/analyses"
+
+
+class AnalysisService:
+    def __init__(self, http: _Client) -> None:
+        self._http = http
+
+    def submit(
+        self,
+        input_uri: str,
+        input_type: str,
+        sample_id: str = "",
+        atlas_version: str | None = None,
+        config: dict | None = None,
+        qc_profile: str | None = None,
+        assay_context: str | None = None,
+        genome_build: str | None = None,
+        webhook_url: str | None = None,
+    ) -> AnalysisSubmitResponse:
+        """Submit a new analysis. Returns immediately with analysis_id and 'queued' status.
+
+        input_type: one of fastq | fastq_paired | bam | count_matrix |
+            expression_tsv | stringtie_gtf.
+        """
+        body: dict = {"input_uri": input_uri, "input_type": input_type}
+        if sample_id:
+            body["sample_id"] = sample_id
+        if atlas_version:
+            body["atlas_version"] = atlas_version
+        if config:
+            body["config"] = config
+        if qc_profile:
+            body["qc_profile"] = qc_profile
+        if assay_context:
+            body["assay_context"] = assay_context
+        if genome_build:
+            body["genome_build"] = genome_build
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        data = self._http.post(_BASE, json=body)
+        return AnalysisSubmitResponse.model_validate(data)
+
+    def submit_batch(
+        self,
+        manifest_content: str = "",
+        manifest_uri: str = "",
+        pipeline_profile: str = "comprehensive",
+        qc_profile: str = "auto",
+        assay_context: str = "solid_tumour",
+        genome_build: str = "GRCh38",
+        atlas_version: str | None = None,
+        webhook_url: str | None = None,
+    ) -> dict:
+        """Submit a samplesheet for multi-sample analysis.
+
+        Provide the nf-core-style TSV samplesheet inline via ``manifest_content``
+        or by staged ``manifest_uri`` (gs://) — exactly one. Each row is fanned
+        out to an independent analysis sharing a ``batch_id``. The other fields
+        are defaults applied to rows that don't override them in their own column.
+
+        Returns the batch envelope: {batch_id, count, analyses: [...]}. Poll
+        progress with ``batch_status(batch_id)``.
+        """
+        if bool(manifest_content) == bool(manifest_uri):
+            raise ValueError(
+                "Provide exactly one of manifest_content or manifest_uri."
+            )
+        body: dict = {
+            "pipeline_profile": pipeline_profile,
+            "qc_profile": qc_profile,
+            "assay_context": assay_context,
+            "genome_build": genome_build,
+        }
+        if manifest_content:
+            body["manifest_content"] = manifest_content
+        if manifest_uri:
+            body["manifest_uri"] = manifest_uri
+        if atlas_version:
+            body["atlas_version"] = atlas_version
+        if webhook_url:
+            body["webhook_url"] = webhook_url
+        return self._http.post(f"{_BASE}/batch", json=body)
+
+    def stage(self, local_path: str, input_type: str = "") -> str:
+        """Upload a LOCAL file into tenant-scoped GCS and return its gs:// URI.
+
+        Requests a short-lived signed URL from the API, then uploads the bytes
+        directly to GCS (never through the API). The returned URI can be passed
+        straight to ``submit`` / ``submit_batch``.
+
+        input_type (optional) validates the filename extension server-side.
+        """
+        import os
+
+        filename = os.path.basename(local_path)
+        body: dict = {"filename": filename}
+        if input_type:
+            body["input_type"] = input_type
+        staged = self._http.post("/v1/uploads", json=body)
+
+        with open(local_path, "rb") as fh:
+            data = fh.read()
+        self._http.put_binary(staged["upload_url"], data)
+        return staged["gcs_uri"]
+
+    def submit_local(
+        self,
+        local_path: str,
+        input_type: str,
+        sample_id: str = "",
+        **kwargs,
+    ) -> AnalysisSubmitResponse:
+        """Stage a LOCAL file to GCS, then submit it for analysis in one call.
+
+        Convenience wrapper over ``stage`` + ``submit`` for callers who have a
+        file on disk rather than a pre-staged gs:// URI.
+        """
+        gcs_uri = self.stage(local_path, input_type=input_type)
+        return self.submit(gcs_uri, input_type, sample_id=sample_id, **kwargs)
+
+    def batch_status(self, batch_id: str) -> dict:
+        """Roll-up status for every analysis in a samplesheet batch."""
+        return self._http.get(f"{_BASE}/batch/{batch_id}")
+
+    def status(self, analysis_id: str) -> AnalysisResult:
+        """Poll the status of an in-progress analysis."""
+        data = self._http.get(f"{_BASE}/{analysis_id}")
+        return AnalysisResult.model_validate(data)
+
+    def result(self, analysis_id: str) -> AnalysisResult:
+        """Retrieve the completed result for an analysis."""
+        data = self._http.get(f"{_BASE}/{analysis_id}/results")
+        return AnalysisResult.model_validate(data)
+
+    def wait(
+        self,
+        analysis_id: str,
+        poll_interval: float = 5.0,
+        timeout: float = 600.0,
+    ) -> AnalysisResult:
+        """Block until the analysis completes or timeout is reached.
+
+        Polls status every poll_interval seconds. Raises TimeoutError if the
+        analysis is still pending after timeout seconds.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            result = self.status(analysis_id)
+            if result.status == "completed":
+                return self.result(analysis_id)
+            if result.status == "failed":
+                raise RuntimeError(
+                    f"Analysis {analysis_id} failed. Check logs for details."
+                )
+            if time.monotonic() > deadline:
+                raise TimeoutError(
+                    f"Analysis {analysis_id} did not complete within {timeout}s. "
+                    f"Last status: {result.status}"
+                )
+            time.sleep(poll_interval)
+
+    def list(self, limit: int = 20, offset: int = 0) -> builtins.list[AnalysisResult]:
+        """List analyses for this tenant, most recent first."""
+        data = self._http.get(f"{_BASE}", params={"limit": limit, "offset": offset})
+        return [AnalysisResult.model_validate(r) for r in data.get("analyses", [])]

dysplai-1.0.0/dysplai/assays.py

@@ -0,0 +1,90 @@
+"""Assay-design client — primer design over back-splice junctions.
+
+Submit BSJ coordinates, poll the job, fetch the designed assays. Coordinates are
+``chr:start-end:strand`` against the genome build you name — ``GRCh38`` by
+default, and getting this wrong is not a validation error, it is a silently
+wrong design: hg19 coordinates against a GRCh38 reference resolve to different
+sequence and produce primers for the wrong locus.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from .client import _Client
+
+_BASE = "/v1/assays"
+
+#: Terminal states. Compared case-insensitively — the service answers COMPLETED
+#: in upper case, and a lower-case comparison here silently never matches, which
+#: turns a finished job into a poll loop that runs to its timeout.
+_TERMINAL = {"completed", "failed", "cancelled"}
+_SUCCESS = {"completed"}
+
+
+class AssayDesignService:
+    def __init__(self, http: _Client) -> None:
+        self._http = http
+
+    def design(
+        self,
+        coordinates: list[str],
+        *,
+        assay_mode: str = "auto",
+        genome_build: str = "GRCh38",
+    ) -> dict[str, Any]:
+        """Submit BSJ coordinates for primer design. Returns the job.
+
+        ``coordinates`` are ``chr:start-end:strand``, 1 to 500 of them.
+
+        ``assay_mode`` is one of:
+          ``co_amplification`` — Mode A, shared reverse primer, 3 primers
+          ``linear_specific``  — Mode B, independent, 4 primers
+          ``auto``             — A, then B, then an independent fallback
+
+        Billing is base plus a charge per started block of junctions, so batching
+        related coordinates into one job costs less than one job each.
+        """
+        if not coordinates:
+            raise ValueError("at least one BSJ coordinate is required")
+        return self._http.post(f"{_BASE}/design", json={
+            "coordinates": list(coordinates),
+            "assay_mode": assay_mode,
+            "genome_build": genome_build,
+        })
+
+    def get(self, job_id: str) -> dict[str, Any]:
+        """Current state of a design job."""
+        return self._http.get(f"{_BASE}/{job_id}")
+
+    def results(self, job_id: str) -> dict[str, Any]:
+        """Designed assays for a completed job."""
+        return self._http.get(f"{_BASE}/{job_id}/results")
+
+    def wait(
+        self,
+        job_id: str,
+        *,
+        poll_interval: float = 10.0,
+        timeout: float = 1200.0,
+    ) -> dict[str, Any]:
+        """Block until the job reaches a terminal state, then return its results.
+
+        Raises ``TimeoutError`` if the window closes first, and ``RuntimeError``
+        if the job ends in a non-success terminal state — the job's own status is
+        the message, so a failure is not mistaken for an empty result set.
+        """
+        deadline = time.monotonic() + timeout
+        while True:
+            job = self.get(job_id)
+            state = str(job.get("status") or "").lower()
+            if state in _TERMINAL:
+                if state in _SUCCESS:
+                    return self.results(job_id)
+                raise RuntimeError(
+                    f"assay job {job_id} ended {job.get('status')}: "
+                    f"{job.get('error_message') or 'no reason given'}")
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"assay job {job_id} still {job.get('status')} after {timeout:.0f}s")
+            time.sleep(poll_interval)