pyproject.toml

# ---------------------------------------------------------------------------
# Root pyproject for the `embpy` package.
#
# This repository hosts the public embpy package under src/embpy/.
# Private perturbation-model research code lives in a separate repository.
# ---------------------------------------------------------------------------
[build-system]
build-backend = "hatchling.build"
requires = [ "hatchling", "hatch-vcs" ]

[project]
name = "embpy"
dynamic = [ "version" ]
description = "A package for biological embeddings in the perturbation experimental space"
readme = "README.md"
license = { file = "LICENSE" }
maintainers = [
  { name = "Goncalo Rei Pinto", email = "goncalo.pinto@helmholtz-munich.de" },
]
authors = [
  { name = "Goncalo Rei Pinto" },
]
requires-python = ">=3.11"
classifiers = [
  "Programming Language :: Python :: 3 :: Only",
  "Programming Language :: Python :: 3.11",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
]
dependencies = [
  "anndata",
  "biopython",
  "broad-babel>=0.1",
  "cirpy",
  "huggingface-hub>=0.35,<1.0.0",
  "ipywidgets",
  "matplotlib",
  # Intentionally permissive: scipy 1.13 (needed by helical) pre-dates numpy 2,
  # while modern torch / transformers work fine with numpy 2. Both are ok.
  "numpy>=1.26,<3",
  "pysam>=0.22",
  "pandas>=2.2",
  "pyarrow>=14.0.2",
  "pyensembl>=2.3.13",
  "rdkit",
  "requests",
  "scikit-learn>=1.3",
  "scipy>=1.11",
  "seaborn",
  "sentencepiece>=0.1.99",
  "protobuf>=3.20",
  "session-info",
  "torch-geometric>=2.5",
  "transformers>=4.45.0,<5.0.0",
]

scripts.embpy-static-embeddings = "embpy.scripts.package_static_embeddings:main"

optional-dependencies.torch = [
  "torch>=2.5.1",
]
# CPU-only PyTorch (pulled from the standard PyPI index).
optional-dependencies.torch-cpu = [
  "torch>=2.5.1",
]
# CUDA builds of PyTorch. Use with --extra-index-url (or the provided uv/pixi
# config) pointing to https://download.pytorch.org/whl/cuXXX
optional-dependencies.torch-cu121 = [
  "torch>=2.5.1",
]
optional-dependencies.torch-cu124 = [
  "torch>=2.5.1",
]
optional-dependencies.torch-cu128 = [
  "torch>=2.5.1",
]
optional-dependencies.torch-cu130 = [
  "torch>=2.5.1",
]
# ESM-3 / ESM-C wrappers. Kept separate because `esm>=3.2.0` hard-pins
# `transformers<4.48.2`, which conflicts with helical (needs >=4.49.0) and a
# few other packages. ESM-2 / ProtT5 do NOT need this extra -- they go through
# HuggingFace `transformers` directly.
optional-dependencies.esm3 = [
  "esm>=3.2.0",
]
# DNA/RNA sequence model wrappers. borzoi-pytorch hard-pins
# `transformers<4.51.0`, so it cannot coexist with helical (needs >=4.53).
# Kept optional so users without DNA sequence use-cases aren't forced onto an
# older transformers. The other DNA wrappers (Evo, Caduceus) are in their own
# extras and don't need this.
optional-dependencies.seqmodels = [
  "borzoi-pytorch>=0.4.3",
  "enformer-pytorch>=0.8.10",
]
# AlphaGenome (Google DeepMind cloud API client). No local weights are
# downloaded; inference runs against Google's servers and requires an
# `ALPHAGENOME_API_KEY` in the environment. Pure-Python, no CUDA/compiler
# needed -- kept out of "all" anyway (see below) since it implies an
# external API account rather than a local model.
optional-dependencies.alphagenome = [
  "alphagenome>=0.7",
]
# Scooby (gagneurlab/scooby): single-cell-resolution DNA sequence model built
# on the Borzoi trunk, conditioned on a precomputed per-cell embedding. 
optional-dependencies.scooby = [
  "snapatac2-scooby",
  "scooby @ git+https://github.com/gagneurlab/scooby.git",
]
# MiniMol molecule GNN. Kept separate because it transitively depends on
# `torch-sparse`, `torch-scatter` etc. which fail to build via pip unless
# torch is pre-installed (the packages don't declare torch as a build-time
# dep). The other molecule models (ChemBERTa, MolFormer, RDKit, MHG-GNN,
# MolE) work without this extra.
# Recommended install path: use conda/pixi which ships pre-built binaries.
optional-dependencies.minimol = [
  "minimol",
]
optional-dependencies.evo = [
  "evo-model>=0.3",
]
optional-dependencies.evo2 = [
  "evo2",
]
# Caduceus -- requires mamba-ssm, a CUDA extension compiled against your torch.
# Install the matching torch-cu* extra FIRST, then:
#   pip install embpy[caduceus]
# If the build fails, try:
#   pip install mamba-ssm --no-build-isolation
optional-dependencies.caduceus = [
  "mamba-ssm>=2.0",
]
optional-dependencies.ntv3 = [
  "transformers>=5.0.0",
]
optional-dependencies.boltz = [
  "boltz>=2.0",
]
optional-dependencies.ppi = [
  "h5py",
]
optional-dependencies.helical = [
  "helical",
]
# Arc Institute STATE / STACK foundation backbones. Each is gated
# behind its own extra so a default install does NOT pull either.
# Downstream code lazy-imports these inside model providers; a missing
# dep only fails when the user opts into that specific backbone.
optional-dependencies.state = [
  "arc-state>=0.10",
]
optional-dependencies.stack = [
  "arc-stack>=0.1.3",
]
optional-dependencies.lamindb = [
  "lamindb",
]
optional-dependencies.pertpy = [
  "pertpy",
]
optional-dependencies.scanpy = [
  "scanpy>=1.10",
]
optional-dependencies.eval = [
  "cell-eval>=0.7.2",
]
optional-dependencies.morphology = [
  "pillow>=10",
  "jump-portrait>=0.0.7",
]
# "all" = every extra that installs cleanly via plain pip/uv (no compiler,
# no CUDA toolkit, compatible with numpy 2.x). Intentionally excludes:
#   * torch-cu* CUDA variants -- pick one explicitly (see all-cu124 etc)
#   * caduceus, evo2 -- need a CUDA toolchain to build mamba-ssm
#   * boltz>=2 -- hard-pins numpy<2, conflicts with our numpy>=2
#   * esm3 -- pins transformers<4.48.2, conflicts with helical and others
#   * helical -- transitively needs the igraph C library (louvain) which
#     pip cannot build; use conda/pixi for helical instead
#   * minimol -- transitive torch-sparse build chain; use conda/pixi instead
#   * scooby -- pulls in `scooby` and `peft` via direct git references (see
#     the scooby extra above); install it explicitly if you need it
#   * alphagenome -- calls a hosted API and needs an ALPHAGENOME_API_KEY;
#     kept opt-in so "all" doesn't imply an external API account
# Install those explicitly in a separate env if you need them.
optional-dependencies.all = [
  "embpy[torch,ppi,lamindb,pertpy,scanpy,morphology,seqmodels]",
]
# Convenience bundles that combine "all" with a specific torch build. These
# intentionally omit caduceus/evo2 so a plain `pip install embpy[all-cu124]`
# does not fail on users without a working CUDA toolchain.
optional-dependencies.all-cpu = [
  "embpy[all,torch-cpu]",
]
optional-dependencies.all-cu121 = [
  "embpy[all,torch-cu121]",
]
optional-dependencies.all-cu124 = [
  "embpy[all,torch-cu124]",
]
optional-dependencies.all-cu128 = [
  "embpy[all,torch-cu128]",
]
optional-dependencies.dev = [
  "pre-commit",
  "twine>=6.1",
]
optional-dependencies.doc = [
  "docutils>=0.8,!=0.18.*,!=0.19.*",
  "ipykernel",
  "ipython",
  "myst-nb>=1.1",
  "setuptools",
  "sphinx>=4",
  "sphinx-autodoc-typehints",
  "sphinx-book-theme>=1",
  "sphinx-copybutton",
  "sphinx-tabs",
  "sphinxcontrib-bibtex>=1",
  "sphinxext-opengraph",
]
optional-dependencies.test = [
  "coverage",
  "pytest",
  "pytest-mock",
]

# https://docs.pypi.org/project_metadata/#project-urls
urls.Documentation = "https://embpy.readthedocs.io/"
urls.Homepage = "https://github.com/theislab/embpy"
urls.Source = "https://github.com/theislab/embpy"

[tool.hatch.metadata]
allow-direct-references = true

# Derive the package version from git tags (e.g. tag `v0.1.0` -> version 0.1.0).
# No need to bump a version string by hand anymore.
[tool.hatch.version]
source = "vcs"

# ---------------------------------------------------------------------------
# uv (https://docs.astral.sh/uv/) configuration.
#
# `uv` is a fast drop-in pip replacement that honors these tables. With the
# config below, users can just run:
#
#   uv sync --extra all-cu124      # GPU install, CUDA 12.4
#   uv sync --extra all-cpu        # CPU-only install
#   uv pip install -e ".[dev,doc]" # editable dev install
#
# without having to remember the correct --extra-index-url for torch wheels.
# ---------------------------------------------------------------------------
[tool.uv]
# Resolve the normal PyPI index AND the matching PyTorch CUDA wheel index.
# Using "explicit = true" means packages only come from these indexes if they
# are explicitly requested via [tool.uv.sources] -- prevents polluting
# unrelated packages with the torch index.
conflicts = [
  [
    { extra = "torch-cpu" },
    { extra = "torch-cu121" },
    { extra = "torch-cu124" },
    { extra = "torch-cu128" },
    { extra = "torch-cu130" },
  ],
]

# Several PyG-adjacent packages (torch-sparse, torch-scatter, torch-cluster,
# pyg-lib) do NOT declare `torch` in `build-system.requires`, so their build
# isolation env is missing torch and `setup.py` crashes. uv lets us inject
# those build-time deps without disabling build isolation globally.
[tool.uv.extra-build-dependencies]
torch-sparse = [{ requirement = "torch>=2.5.1", match-runtime = true }]
torch-scatter = [{ requirement = "torch>=2.5.1", match-runtime = true }]
torch-cluster = [{ requirement = "torch>=2.5.1", match-runtime = true }]
torch-spline-conv = [{ requirement = "torch>=2.5.1", match-runtime = true }]
pyg-lib = [{ requirement = "torch>=2.5.1", match-runtime = true }]
mamba-ssm = [{ requirement = "torch>=2.5.1", match-runtime = true }]
causal-conv1d = [{ requirement = "torch>=2.5.1", match-runtime = true }]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu121"
url = "https://download.pytorch.org/whl/cu121"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu124"
url = "https://download.pytorch.org/whl/cu124"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu130"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "torch-cpu" },
  { index = "pytorch-cu121", extra = "torch-cu121" },
  { index = "pytorch-cu124", extra = "torch-cu124" },
  { index = "pytorch-cu128", extra = "torch-cu128" },
  { index = "pytorch-cu130", extra = "torch-cu130" },
]

[tool.hatch.envs.default]
installer = "uv"
features = [ "dev" ]

[tool.hatch.envs.docs]
features = [ "doc" ]
scripts.build = "sphinx-build -M html docs docs/_build {args}"
scripts.open = "python -m webbrowser -t docs/_build/html/index.html"
scripts.clean = "git clean -fdX -- {args:docs}"

[tool.hatch.envs.hatch-test]
features = [ "test" ]

[tool.pyright]
# Tell pyright / basedpyright / cursorpyright that the source tree
# lives under `src/`. Without this, the IDE integration cannot
# resolve relative imports from freshly-created subpackage
# `__init__.py` files.
include = [ "src", "tests" ]
extraPaths = [ "src" ]

[tool.ruff]
line-length = 120
src = [ "src" ]
extend-include = [ "*.ipynb" ]

format.docstring-code-format = true

lint.select = [
  "B",      # flake8-bugbear
  "BLE",    # flake8-blind-except
  "C4",     # flake8-comprehensions
  "D",      # pydocstyle
  "E",      # Error detected by Pycodestyle
  "F",      # Errors detected by Pyflakes
  "I",      # isort
  "RUF100", # Report unused noqa directives
  "TID",    # flake8-tidy-imports
  "UP",     # pyupgrade
  "W",      # Warning detected by Pycodestyle
]
lint.ignore = [
  "B008", # Errors from function calls in argument defaults. These are fine when the result is immutable.
  "D100", # Missing docstring in public module
  "D104", # Missing docstring in public package
  "D105", # __magic__ methods are often self-explanatory, allow missing docstrings
  "D107", # Missing docstring in __init__
  # Disable one in each pair of mutually incompatible rules
  "D203", # We don't want a blank line before a class docstring
  "D213", # <> We want docstrings to start immediately after the opening triple quote
  "D400", # first line should end with a period [Bug: doesn't work with single-line docstrings]
  "D401", # First line should be in imperative mood; try rephrasing
  "E501", # line too long -> we accept long comment lines; formatter gets rid of long code lines
  "E731", # Do not assign a lambda expression, use a def -> lambda expression assignments are convenient
  "E741", # allow I, O, l as variable names -> I is the identity matrix
]
lint.per-file-ignores."*/__init__.py" = [ "F401" ]
lint.per-file-ignores."docs/*" = [ "I" ]
lint.per-file-ignores."tests/*" = [ "D" ]
lint.pydocstyle.convention = "numpy"

[tool.pytest.ini_options]
testpaths = [ "tests" ]
xfail_strict = true
addopts = [
  "--import-mode=importlib",
]

[tool.coverage.run]
source = [ "embpy" ]
omit = [
  "**/test_*.py",
]

[tool.cruft]
skip = [
  "tests",
  "src/**/__init__.py",
  "src/**/basic.py",
  "docs/api.md",
  "docs/changelog.md",
  "docs/references.bib",
  "docs/references.md",
  "docs/notebooks/example.ipynb",
]