docs: added docs for LLM agent integration with scvi-tools (#3741)

Author: ori-kron-wis

docs/user_guide/use_case/index.md

@@ -6,6 +6,7 @@
 custom_dataloaders
 downstream_analysis_tasks
 hyper_parameters_tuning
+llm_assisted_analysis
 multi_gpu_training
 saving_and_loading_models
 scvi_criticism

docs/user_guide/use_case/llm_assisted_analysis.md

@@ -0,0 +1,146 @@
+# Using LLM Engines with scvi-tools
+
+Large language models (LLMs) can significantly lower the barrier to using scvi-tools by helping researchers write code, choose models, tune parameters, and troubleshoot analyses through natural language. This page covers how to leverage five popular AI platforms—Claude, ChatGPT, OpenClaw, Gemini, and BioMNI—to get the most out of scvi-tools.
+
+---
+
+## Claude (Anthropic)
+
+Claude is a general-purpose AI assistant from Anthropic. For scvi-tools users, Claude offers a dedicated **scvi-tools Skill Bundle**—a curated set of skills covering the full scvi-tools ecosystem.
+
+### scvi-tools Skill Bundle
+
+The skill bundle gives Claude deep knowledge of scvi-tools workflows and includes guidance for:
+
+- **Batch integration**: scVI and scArches
+- **Cell type annotation**: SCANVI and CellAssign
+- **Spatial analysis**: DestVI, Tangram, Cell2location, Stereoscope
+- **Epigenetic data**: PeakVI and scBasset
+- **Multimodal integration**: TotalVI (CITE-seq) and MultiVI (RNA+ATAC)
+- **Perturbation studies**: contrastiveVI
+
+Each skill covers recommended workflows, parameter guidance, and troubleshooting tips.
+
+### Installation
+
+**Claude Code users:**
+```bash
+/plugin install scvi-tools@life-sciences
+```
+
+**Claude.ai users:**
+Organization admins can upload the skill ZIP via *Admin Settings > Skills*. Individual users can upload via *Settings > Capabilities > Skills*. Download instructions and the skill ZIP are provided in the [Anthropic tutorial](https://claude.com/resources/tutorials/how-to-use-the-scvi-tools-bioinformatics-skill-bundle-with-claude).
+
+Once installed, you can ask questions like:
+> "I have 10x Chromium data from 3 donors with different sequencing depths. Which scvi-tools model should I use for integration, and what batch key should I set?"
+
+See the full tutorial at [Anthropic's scvi-tools Skill Bundle guide](https://claude.com/resources/tutorials/how-to-use-the-scvi-tools-bioinformatics-skill-bundle-with-claude).
+
+---
+
+## ChatGPT (OpenAI)
+
+ChatGPT can assist with scvi-tools through two complementary routes: custom GPTs and MCP (Model Context Protocol) tool integrations.
+
+### Custom GPTs
+
+OpenAI's GPT Store hosts community-built GPTs specialized in single-cell analysis. For example, the [Scanpy – Your Single-Cell RNA-seq Data Analyst](https://chatgpt.com/g/g-GKNExWk2P-scanpy-your-single-cell-rna-seq-data-analyst) GPT is configured to assist with scanpy-based workflows, which pair naturally with scvi-tools preprocessing pipelines.
+
+You can use such GPTs to:
+- Walk through an end-to-end scRNA-seq analysis
+- Get scvi-tools code snippets for common operations
+- Debug errors from scvi-tools model training
+
+### MCP (Model Context Protocol) Tool Use
+
+OpenAI supports [tool use via the API](https://developers.openai.com/api/docs/guides/tools/), which enables agents to call external functions—including Python code execution. This makes it possible to build automated pipelines where ChatGPT generates and runs scvi-tools code on your data.
+
+A simple agent prompt example:
+> "Load the AnnData file at `data/pbmc.h5ad`, run scVI with 2 batches defined by `adata.obs['batch']`, train for 400 epochs, and return the UMAP coordinates."
+
+With tool use enabled, ChatGPT can generate the code and invoke a Python execution environment to produce results.
+
+---
+
+## OpenClaw
+
+[OpenClaw](https://lobehub.com/skills/k-dense-ai-claude-scientific-skills-scvi-tools) (available via the LobeHub market) provides an installable skill focused on scvi-tools for use with Claude-based agents. It is optimized for researchers who need rigorous statistical frameworks and multi-batch integration.
+
+### Installation
+
+```bash
+# Register your agent (one-time)
+npx -y @lobehub/market-cli register --name "YourName" --source open-claw
+
+# Install the scvi-tools skill
+npx -y @lobehub/market-cli skills install k-dense-ai-claude-scientific-skills-scvi-tools
+```
+
+After installation, read the `SKILL.md` file in the extracted directory for usage instructions. The skill covers:
+
+- Probabilistic batch correction and dataset alignment
+- Multi-modal analysis (CITE-seq, spatial, multiome)
+- Uncertainty quantification in differential expression
+- Cell annotation with transfer learning
+
+This skill is best suited for users who want a lightweight Claude-compatible skill without requiring the full Claude.ai platform.
+
+---
+
+## Gemini (Google)
+
+Gemini is Google's general-purpose LLM, accessible via [Google AI Studio](https://aistudio.google.com) and the Gemini API. While there is no dedicated scvi-tools skill for Gemini, it is effective for assisted code generation, debugging, and conceptual guidance when working with scvi-tools.
+
+### General Use
+
+Gemini can help with scvi-tools through natural language prompting for:
+- Generating scvi-tools setup and training code
+- Explaining model outputs and hyperparameters
+- Suggesting appropriate models for your data type
+
+**Example prompt in AI Studio:**
+> "Write Python code to train an scVI model on an AnnData object with a batch column called `sample_id`, then extract the latent embedding and run a UMAP."
+
+You can paste scvi-tools error messages, documentation excerpts, or code snippets directly into the chat to get targeted assistance.
+
+---
+
+## BioMNI (Stanford)
+
+[BioMNI](https://biomni.stanford.edu/) is a general-purpose biomedical AI agent from Stanford, designed to autonomously execute research tasks across diverse biomedical subfields. It has a native integration with the scverse ecosystem—including scvi-tools—announced in 2025.
+
+### Integration with scverse and scvi-tools
+
+BioMNI understands biological context and can orchestrate multi-step pipelines across scverse packages (Scanpy, scvi-tools, Squidpy, Pertpy) from plain-language instructions. Crucially, all agent-generated code is packaged as reproducible Jupyter notebooks.
+
+**Example prompts:**
+> "Run QC and normalization, integrate my three batches using scVI, cluster the cells, and annotate cell types using SCANVI."
+
+> "Cluster cells and identify marker genes for each cluster."
+
+BioMNI handles parameter selection, dependency management, and returns documented, reproducible results—no manual coding required.
+
+### Access
+
+- **Web platform**: [biomni.stanford.edu](https://biomni.stanford.edu/) — interactive, no setup required
+- **Open-source**: [github.com/snap-stanford/Biomni](https://github.com/snap-stanford/Biomni) — self-hosted deployment
+
+BioMNI is particularly well-suited for biologists who want to run complete single-cell and spatial workflows without writing code, while still producing reproducible, shareable analyses.
+
+---
+
+## Summary
+
+| Platform | Best For | scvi-tools Integration |
+|---|---|---|
+| **Claude** | Guided workflows, parameter tuning, troubleshooting | Dedicated skill bundle with full model coverage |
+| **ChatGPT** | Code generation, custom GPTs, agentic pipelines | Custom GPTs + MCP tool use |
+| **OpenClaw** | Lightweight Claude-based skill, CLI install | Installable scvi-tools skill via LobeHub |
+| **Gemini** | General code assistance, AI Studio prompting | General LLM assistance; no dedicated skill |
+| **BioMNI** | End-to-end automated scverse pipelines | Native scverse/scvi-tools integration |
+
+Each platform offers a different trade-off between ease of use, customization, and depth of scvi-tools knowledge. For users who primarily want guidance and code examples, Claude's skill bundle or BioMNI provide the deepest integration. For users building custom pipelines or agentic workflows, ChatGPT's MCP tool use or BioMNI's open-source deployment offer the most flexibility.
+
+:::{note}
+LLM-generated code should always be reviewed before running on important data. Check that model parameters, batch keys, and data shapes match your specific dataset.
+:::

src/scvi/external/decipher/_model.py

@@ -93,6 +93,41 @@ def train(
         plan_kwargs: dict | None = None,
         **trainer_kwargs,
     ):
+        """Train the model.
+
+        Wraps :meth:`~scvi.model.base.PyroSviTrainMixin.train` with Decipher-specific
+        defaults (``early_stopping_monitor="nll_validation"`` and ``drop_last=True``).
+
+        Parameters
+        ----------
+        max_epochs
+            Number of passes through the dataset.
+        accelerator
+            Supports passing different accelerator types ``("cpu", "gpu", "tpu", "ipu",
+            "hpu", "mps", "auto")`` as well as custom accelerator instances.
+        device
+            The device to use. Can be set to a non-negative index (int or str) or ``"auto"``
+            for automatic selection.
+        train_size
+            Size of training set in the range ``[0.0, 1.0]``.
+        validation_size
+            Size of the validation set. If ``None``, defaults to ``1 - train_size``.
+        shuffle_set_split
+            Whether to shuffle indices before splitting.
+        batch_size
+            Minibatch size to use during training.
+        early_stopping
+            Perform early stopping. Additional arguments can be passed in ``**trainer_kwargs``.
+        training_plan
+            Training plan instance. If ``None``, a default :class:`~scvi.train.PyroTrainingPlan`
+            is used.
+        datasplitter_kwargs
+            Additional keyword arguments passed into :class:`~scvi.dataloaders.DataSplitter`.
+        plan_kwargs
+            Keyword arguments for :class:`~scvi.train.PyroTrainingPlan`.
+        **trainer_kwargs
+            Additional keyword arguments passed to :class:`~scvi.train.Trainer`.
+        """
         if "early_stopping_monitor" not in trainer_kwargs:
             trainer_kwargs["early_stopping_monitor"] = "nll_validation"
         datasplitter_kwargs = datasplitter_kwargs or {}

src/scvi/external/mrvi/_model.py

@@ -226,6 +226,21 @@ def load(
         else:
             raise ValueError("Unknown backend . Use 'torch' or 'jax' MRVI.")
 
+    def differential_expression(self, *args, **kwargs):
+        """Perform differential expression analysis.
+
+        Delegates to the underlying :class:`~scvi.external.TorchMRVI` or
+        :class:`~scvi.external.JaxMRVI` instance returned by the constructor.
+
+        See Also
+        --------
+        :meth:`~scvi.external.TorchMRVI.differential_expression`
+        """
+        raise NotImplementedError(
+            "Call differential_expression on the TorchMRVI or JaxMRVI instance "
+            "returned by MRVI(...)."
+        )
+
 
 def peek_loaded_model_registry(dir_path, prefix):
     """Getting the loaded model registry to give better warnings for loading MRVI"""

src/scvi/external/poissonvi/_model.py

@@ -388,7 +388,12 @@ def m1_domain_fn(samples):
     def differential_expression(
         self,
     ):
-        # Refer to function differential_accessibility
+        """Not implemented. Use :meth:`~scvi.external.POISSONVI.differential_accessibility` instead
+
+        Raises
+        ------
+        NotImplementedError
+        """
         msg = (
             f"differential_expression is not implemented for {self.__class__.__name__}, please "
             f"use {self.__class__.__name__}.differential_accessibility"

src/scvi/external/resolvi/_model.py

@@ -393,6 +393,22 @@ def _prepare_data(
         adata.obsm["distance_neighbor"] = distance_neighbor
 
     def compute_dataset_dependent_priors(self, n_small_genes=None):
+        """Compute dataset-dependent prior parameters for the ResolVI model.
+
+        Estimates background expression ratio and spatial kernel size from the data,
+        which are used as priors during training.
+
+        Parameters
+        ----------
+        n_small_genes
+            Number of low-expressed genes used to estimate the background ratio.
+            If ``None``, defaults to ``n_genes // 50``.
+
+        Returns
+        -------
+        dict with keys ``"background_ratio"``, ``"median_distance"``,
+        ``"mean_log_counts"``, and ``"std_log_counts"``.
+        """
         x = self.adata_manager.get_from_registry(REGISTRY_KEYS.X_KEY)
         n_small_genes = x.shape[1] // 50 if n_small_genes is None else int(n_small_genes)
         # Computing library size over low-expressed genes (expectation for the background).

src/scvi/external/velovi/_model.py

@@ -901,6 +901,15 @@ def get_gene_likelihood(
 
     @torch.inference_mode()
     def get_rates(self):
+        """Return the learned splicing, degradation, and transcription rates.
+
+        Returns
+        -------
+        dict with keys ``"beta"`` (splicing), ``"gamma"`` (degradation),
+        ``"alpha"`` (transcription on-state), ``"alpha_1"`` (transcription off-state),
+        and ``"lambda_alpha"`` (switching rate), each as a numpy array of shape
+        ``(n_genes,)``.
+        """
         gamma, beta, alpha, alpha_1, lambda_alpha = self.module._get_rates()
 
         return {
@@ -950,6 +959,27 @@ def get_directional_uncertainty(
         gene_list: Iterable[str] = None,
         n_jobs: int = -1,
     ):
+        """Compute directional uncertainty of RNA velocity.
+
+        Estimates the uncertainty of the velocity vector direction for each cell
+        by sampling from the posterior and computing pairwise cosine similarities.
+
+        Parameters
+        ----------
+        adata
+            AnnData object. If ``None``, uses the AnnData passed during model initialization.
+        n_samples
+            Number of posterior samples for estimating uncertainty.
+        gene_list
+            List of genes to use. If ``None``, uses all genes.
+        n_jobs
+            Number of parallel jobs for cosine similarity computation.
+            ``-1`` uses all available cores.
+
+        Returns
+        -------
+        Tuple of (DataFrame of directional statistics per cell, cosine similarity matrix).
+        """
         adata = self._validate_anndata(adata)
 
         logger.info("Sampling from model...")

src/scvi/model/_jaxscvi.py

@@ -185,8 +185,10 @@ def get_latent_representation(
         return self.module.as_numpy_array(latent)
 
     def to_device(self, device):
+        """Move model to device. No-op for JAX models (device placement is handled by JAX)."""
         pass
 
     @property
     def device(self):
+        """The current device that the module's params are on."""
         return self.module.device

src/scvi/model/base/_base_model.py

@@ -1271,10 +1271,28 @@ def update_setup_method_args(self, setup_method_args: dict):
         self._registry[_SETUP_ARGS_KEY].update(setup_method_args)
 
     def get_normalized_expression(self, *args, **kwargs):
+        """Not implemented for this model class.
+
+        Available in RNA models that inherit from
+        :class:`~scvi.model.base.RNASeqMixin`.
+
+        Raises
+        ------
+        NotImplementedError
+        """
         msg = f"get_normalized_expression is not implemented for {self.__class__.__name__}."
         raise NotImplementedError(msg)
 
     def differential_abundance(self, *args, **kwargs):
+        """Not implemented for this model class.
+
+        Available in models that inherit from
+        :class:`~scvi.model.base.VAEMixin`.
+
+        Raises
+        ------
+        NotImplementedError
+        """
         msg = f"differential_abundance is not implemented for {self.__class__.__name__}."
         raise NotImplementedError(msg)
 

src/scvi/train/__init__.py

@@ -9,6 +9,7 @@
     AdversarialTrainingPlanConfig,
     ClassifierTrainingPlanConfig,
     JaxTrainingPlanConfig,
+    KwargsConfig,
     LowLevelPyroTrainingPlanConfig,
     PyroTrainingPlanConfig,
     SemiSupervisedAdversarialTrainingPlanConfig,
@@ -54,6 +55,7 @@
     "ScibCallback",
     "METRIC_KEYS",
     "JaxTrainingPlanConfig",
+    "KwargsConfig",
 ]