API reference

Use this page as the routing layer for the public API. The main question should be easy to answer quickly:

• stable baseline workflow: TaskRunner

• experimental labeled annotation workflow: Experimental annotation quickstart API

• lower-level control: Trainer plus Data preparation

• custom extension: Adapters

What it is

Status: stable and experimental.

This index is the navigation page for the public API contract. Stable and experimental surfaces are documented separately so users can see the current scope without guessing.

When to use it

Use this page when you need to answer one of these quickly:

• which entrypoint should I start with?

• where is the workflow tutorial for that entrypoint?

• where is the parameter and return contract for that API?

Minimal example

Stable beginner route:

import scanpy as sc
from scdlkit import TaskRunner

adata = sc.datasets.pbmc3k_processed()
runner = TaskRunner(model="vae", task="representation", label_key="louvain")
runner.fit(adata)

Experimental beginner route:

from scdlkit import adapt_annotation

runner = adapt_annotation(adata, label_key="cell_type")

Parameters

• Start with TaskRunner for bundled stable baselines.

• Start with Experimental annotation quickstart API for labeled annotation adaptation.

• Use Trainer and Data preparation when you need lower-level control.

• Use Adapters when you already have a custom PyTorch module.

Input expectations

• stable baseline pages assume processed AnnData and bundled models

• experimental annotation pages assume labeled human scRNA-seq and the scGPT whole-human checkpoint

• lower-level pages assume you are comfortable managing model and data objects more explicitly

Returns / outputs

• TaskRunner and adapt_annotation(...) are the highest-level routes and return fitted workflow objects

• lower-level pages document datasets, raw prediction dictionaries, and wrapped modules in more detail

Failure modes / raises

• stable pages call out model/task mismatches and missing AnnData columns

• experimental pages call out foundation-extra installation, label requirements, and checkpoint-compatibility failures

• lower-level pages call out task-contract and data-contract errors explicitly

Notes / caveats

• TaskRunner remains the stable beginner path.

• adapt_annotation(...) is the easiest experimental annotation path.

• scdlkit.foundation remains the lower-level experimental surface underneath the beginner alias.

Related tutorial(s)

• Scanpy PBMC quickstart

• Custom model extension

• Experimental scGPT dataset-specific annotation

Start here

High-level stable workflow

• TaskRunner

Related tutorial:

• Scanpy PBMC quickstart

Experimental beginner annotation

• Experimental annotation quickstart API

Related tutorial:

• Experimental scGPT dataset-specific annotation

Low-level stable workflow

• Trainer

• Data preparation

Extension surfaces

• Adapters

• Experimental foundation helpers

Evaluation and reports

• Evaluation and outputs

Built-in models

• Built-in models