Metadata-Version: 2.4
Name: dysplai
Version: 1.0.4
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<1,>=0.27
Requires-Dist: pydantic<3,>=2.0
Requires-Dist: typing-extensions>=4.0
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.**

DYSPLAI is a molecular oncology research platform spanning sequence analysis,
reference-atlas positioning, cohort discovery, molecular evidence graphs,
counterfactual pathway exploration, clinical metadata harmonisation and
reproducible reporting.

This is the typed Python client for it: Pydantic v2 response models, a blocking
`wait()` helper for long-running jobs, and thirteen service surfaces. The SDK is
a thin client — every model, atlas and pipeline stays on DYSPLAI infrastructure.

## 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`, `submit_batch`, `submit_local`, `stage`, `status`, `batch_status`, `result`, `wait`, `list` |
| Cohort | `client.cohort` | `summarise`, `compare`, `neighbours`, `rank_targets`, `reference_compare` |
| Counterfactual | `client.counterfactual` | `sensitivity`, `simulate`, `features`, `pathway_shift_search`, `explore`, `characterise`, `aggressiveness`, `cohort_sensitivity`, `liquid_bleed`, `normal_projection`, `perturb_latent`, `vulnerability_search` |
| Interpretation | `client.interpretation` | `query` |
| Graph | `client.graph` | `network`, `pathways`, `explanation`, `clinical_metrics`, `ingest_status`, `junction` |
| Experts | `client.experts` | `list`, `capabilities`, `metrics`, `classify`, `route`, `interpret`, `evidence` |
| Assay design | `client.assays` | `design`, `get`, `results`, `wait` |
| Histology | `client.histology` | `submit_slide`, `wait_slide`, `slide_status`, `slide_result`, `analyse_slide`, `search_slides`, `molecular_context`, `search_molecular_context`, `pathway_scores`, `gene_expression`, `regions`, `tile_grid`, `ood`, `tile_ood`, `quality`, `supporting_data` |
| Radiomics | `client.radiomics` | `submit`, `wait`, `status`, `result`, `report` |
| Clinical | `client.clinical` | `parse`, `annotate`, `labels`, `timeline`, `get_mapping` |
| Reports | `client.reports` | `generate`, `status`, `wait`, `download`, `list` |
| Model builder | `client.model_builder` | `submit_run`, `get_run`, `list_runs`, `cancel_run`, `get_run_labels`, `list_models`, `get_model`, `activate_model` |
| Account | `client.account` | `whoami`, `balance`, `usage` |

The molecular evidence graph (`client.graph`) grounds a prediction in the
evidence behind it — supporting and contradicting — rather than returning a
score alone. Graph reads take the **analysis id** and are tenant-private.

## Worked examples

Task-oriented guides — cohort discovery, evidence graphs, counterfactual
exploration, imaging, assay design and reporting — are in the developer
documentation at <https://www.dysplasiadx.com/developers>, alongside the Colab
notebooks listed below.

## 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-ready notebooks are published with the developer documentation at
<https://www.dysplasiadx.com/developers>. They are not installed by `pip` — this
distribution is the client only.

| 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

**Every scientific output carries `ruo_disclaimer: "For Research Use Only. Not
for use in diagnostic procedures."`, and it is not suppressible by the caller.**

That is the rule, not a list — it holds for analysis, cohort, counterfactual,
interpretation, graph, experts, assay design, histology, radiomics, model
builder and reports alike. The only exception is `client.account`, which returns
administrative data (identity, credit balance, usage) and no scientific result.

DYSPLAI does not diagnose disease, recommend treatment, guide clinical
management, provide clinical decision support, or generate prognosis.
