pyproject.toml

[build-system]
requires = ["scikit-build-core>=0.12", "pybind11>=2.12"]
build-backend = "scikit_build_core.build"

[project]
name = "vdjtools"  # if the PyPI name is taken, fall back to a distinct dist name (cf. arda -> arda-mapper)
version = "3.1.2"
description = "TCR/BCR repertoire analysis — Pgen/generation/inference, diversity, overlap, biomarkers (Python + C++)"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "GPL-3.0-or-later" }
authors = [{ name = "Mikhail Shugay", email = "mikhail.shugay@gmail.com" }]
keywords = ["immunology", "tcr", "bcr", "airr", "repertoire", "pgen", "olga", "igor", "bioinformatics"]
classifiers = [
    "Development Status :: 2 - Pre-Alpha",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
    "Programming Language :: Python :: 3",
    "Programming Language :: C++",
    "Topic :: Scientific/Engineering :: Bio-Informatics",
]
# Base deps are kept to what the currently-implemented code imports; the parent libraries
# (arda-mapper, vdjmatch->seqtree) are promoted from the extras below to base deps as the
# phases that import them land (model -> arda, overlap -> vdjmatch). Every dep traces to a use.
dependencies = [
    "polars>=1.0",
    "numpy",
    "scipy",
    "typer>=0.12",  # the `vdjtools` CLI (Phase 8) is a core entry point
    # arda = the single source of germline truth (see model/reference.py): V/D/J germline +
    # CDR3 anchors for every locus, contig stitching/annotation, and the arda-native model
    # builder. Phase 1 landed, so it is promoted to a base dep: a plain `pip install vdjtools`
    # must ship the model engine AND the germline reference, because downstream libraries
    # (mirpy) depend on vdjtools *for* that reference and cannot be expected to opt into an
    # extra. Cheap to require: same wheel matrix as vdjtools (cp310-313 x mac/linux/win) and
    # its only runtime deps are polars + typer (already ours) + requests. It is imported
    # lazily inside the functions that need it, so `import vdjtools` stays light. mmseqs2 is
    # needed only for arda's alignment/annotate path, never for germline lookup or Pgen.
    "arda-mapper>=2.5.5",
    # seqtree = the fuzzy-search / e-value engine, vdjmatch = overlap + TCRnet on top of it.
    # Phase 4/5 landed, so they are base deps too: without them a plain install cannot do
    # error correction (preprocess.correct), fuzzy/similarity overlap, TCRnet, or
    # metaclonotypes -- all advertised capabilities, and none has a fallback. Cheap: seqtree
    # itself has ZERO runtime deps and the same wheel matrix as vdjtools; vdjmatch is a
    # pure-python wheel needing only polars (ours) + seqtree. Both are imported lazily.
    "seqtree>=0.6.1",   # 0.6.1 fixes a corrupted MJ A-N contact energy (structural()) and names the bad sequence in gapblock's alphabet error
    "vdjmatch>=0.1.2",  # 0.1.2 fixes cluster.overlap() raising SchemaError on zero fuzzy matches
    # We declare huggingface_hub OURSELVES rather than borrowing seqtree's `[control]` extra:
    # it is genuinely OUR dependency (model/data.py imports hf_hub_download directly), and
    # tcrnet()'s DEFAULT path (control=None) scores each locus against a matched background
    # repertoire that seqtree.control fetches from HF on demand -- an unconditional, lazy
    # `from huggingface_hub import hf_hub_download`, satisfied by HF being present in the env
    # however it got there. Depending on another package's extra to obtain a dep we import
    # ourselves would couple our install to seqtree's packaging choices; this states the real
    # requirement. (Same on-demand-reference pattern as arda's IMGT fetch.)
    "huggingface_hub",
]

[project.scripts]
vdjtools = "vdjtools.cli:app"

[project.optional-dependencies]
model = []                             # DEPRECATED no-op alias: arda-mapper is a BASE dep since v2.4.0 (the model engine + germline reference ship with a plain `pip install vdjtools`). Kept so existing `vdjtools[model]` pins (e.g. mirpy's) keep resolving.
overlap = ["scikit-learn"]             # vdjmatch/seqtree are BASE deps since v2.5.0; sklearn is still an extra -- it is only needed by cluster_samples(method="mds") (method="hclust" uses scipy, a base dep) and sc.cluster_eval, and both raise a clear install hint.
preprocess = []                        # DEPRECATED no-op alias: seqtree (freq-based error correction) is a BASE dep since v2.5.0.
sc = ["scikit-learn", "pyyaml", "anndata"]  # Phase 7: single-cell — sklearn for cluster_eval contingency, pyyaml for AIRR Cell export, anndata for the scverse bridge (to_anndata). huggingface_hub is a BASE dep now.
examples = ["marimo", "matplotlib", "scikit-learn"]  # example notebooks (scipy + huggingface_hub are base deps)
oracle = ["olga"]                      # Pgen cross-check oracle (tests only)
test = ["pytest>=7.4", "pytest-cov"]
bench = []  # DEPRECATED no-op alias: huggingface_hub (real-data fetch) is a BASE dep.
docs = ["sphinx>=7", "pydata-sphinx-theme>=0.15", "nbsphinx"]
dev = ["ruff", "pytest>=7.4", "pybind11>=2.12"]
all = ["scikit-learn"]                 # the antigenomics engines (arda-mapper, seqtree, vdjmatch) are base deps, not extras

[project.urls]
Homepage = "https://github.com/antigenomics/vdjtools"
Repository = "https://github.com/antigenomics/vdjtools"
Documentation = "https://antigenomics.github.io/vdjtools/"

[tool.scikit-build]
wheel.packages = ["python/vdjtools"]
cmake.build-type = "Release"
build-dir = "build/{wheel_tag}"
# Ext compiles at install time; flip to true during C++-heavy work for recompile-on-import.
editable.rebuild = false
# Keep the sdist lean (build inputs only); anchor paths with a leading "/". README logos (assets/),
# dev docs, the LaTeX appendix, and stray scratch files must not ship to PyPI — the wheel carries
# just the package + compiled _core.
sdist.exclude = [
    "/tests", "/docs", "/.github", "/setup.sh", "/build", "/examples", "/assets",
    "/appendix", "/CLAUDE.md", "/ROADMAP.md", "/SOURCES.md", "/arda-ref.md",
    "/notebooks", "/scripts",
]

[tool.scikit-build.cmake.define]
VDJTOOLS_PYTHON = "ON"

[tool.ruff]
line-length = 100
target-version = "py310"

[tool.pytest.ini_options]
testpaths = ["tests/python"]
addopts = "-ra -m 'not slow'"
markers = ["slow: heavier oracle / reference-arithmetic checks (e.g. vs OLGA's own slow Pgen); run with -m slow"]