pyproject.toml

[build-system]
requires = ["setuptools>=42", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "chatspatial"
version = "1.2.3"
description = "ChatSpatial: Natural language-driven spatial transcriptomics analysis via Model Context Protocol (MCP) integration"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Chen Yang", email = "cafferychen777@tamu.edu"}
]
keywords = ["spatial-transcriptomics", "single-cell", "mcp", "llm", "bioinformatics", "scanpy", "squidpy"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Programming Language :: Python :: 3.13",
    "Topic :: Scientific/Engineering :: Bio-Informatics",
]
requires-python = ">=3.11,<3.14"
dependencies = [
    # ========== Core Foundation (Essential) ==========
    # MCP and data processing
    # Updated to 1.17.0 for full Pydantic v2 and ImageContent support
    "mcp>=1.17.0",
    "numpy>=1.21.0",
    "pandas>=1.3.0",
    "scipy>=1.7.0",
    "scikit-learn>=1.0.0",
    
    # Visualization
    "matplotlib>=3.5.0",
    "seaborn>=0.11.0",
    "Pillow>=8.0.0",
    
    # Single-cell analysis core
    "scanpy>=1.9.0,<2.0",
    "anndata>=0.11.0",  # Updated for scvi-tools 1.3.x compatibility
    "squidpy>=1.2.0",
    
    # Clustering and dimensionality reduction
    "umap-learn>=0.5.0",
    "igraph>=0.9.0",
    "leidenalg>=0.8.0",  # Leiden is preferred over Louvain (better algorithm, fewer compilation issues on macOS)
    
    # MCP server framework
    "pydantic>=2.0.0,<3.0",
    "click>=8.0.0",
    "aiohttp>=3.8.0",
    
    # Version constraints
    "jinja2>=3.0.0",  # Handle conflict with pygpcca
    
    # ========== High-Frequency Features (Extended Default) ==========
    # Most commonly used advanced features based on usage analysis
    
    # Multi-tool dependency (24 references in codebase)
    "scvi-tools>=1.0.0,<2.0",
    "mudata>=0.2.0",  # Core dependency of scvi-tools (not optional)
    
    # RNA velocity (7 references)
    "scvelo>=0.2.5",  # Removed upper bound for better compatibility
    
    # Cell communication (10 references combined)
    "liana",  # No version constraint - let pip choose compatible version
    "cellphonedb>=5.0.0,<6.0",
    "fastccc>=0.1.0",  # FFT-based ultra-fast cell-cell communication (Nature Communications 2025)
    
    # Batch integration (frequently needed)
    "harmonypy>=0.0.9",
    "bbknn>=1.5.0",
    
    # Spatial statistics extensions
    "esda>=2.4.0",  # Exploratory spatial data analysis
    "libpysal>=4.6.0",  # Core spatial analysis library

    # Gene set enrichment (commonly used)
    "gseapy>=1.0.0",

    # Spatial deconvolution (default method)
    "flashdeconv>=0.1.0",  # Ultra-fast deconvolution using random sketching
]

[project.optional-dependencies]
# Full installation with all features (recommended)
full = [
    # ========== Deep Learning Frameworks ==========
    "torch>=2.0.0,<3.0",  # Required for many advanced methods

    # ========== Spatial Domain Identification ==========
    "GraphST>=1.1.0",  # Graph self-supervised contrastive learning (no louvain dependency)
    # Note: SpaGCN/BANKSY moved to [spatial-domains] due to dependency issues
    # SpaGCN requires louvain which has compilation issues on macOS
    # BANKSY requires numpy<2.0 which conflicts with other packages

    # ========== Advanced Deconvolution ==========
    "cell2location>=0.1.4",  # Bayesian deconvolution (0.1.4+ fixes scvi-tools one_hot compatibility)
    
    # ========== Advanced Trajectory Analysis ==========
    "cellrank>=2.0.0,<3.0",  # RNA velocity-based fate mapping
    "palantir>=1.0.0",  # Probabilistic trajectory inference
    
    # CellRank acceleration: petsc4py/slepc4py moved to [hpc] - requires system PETSc/SLEPc
    # CellRank works without these, just slower for some operations
    
    # ========== Additional Integration Methods ==========
    "scanorama>=1.7.0",  # Cross-dataset integration
    
    # ========== Spatial Variable Genes ==========
    "spatialde>=1.1.3",  # Gaussian process-based method
    "scikit-misc>=0.5.0",  # Required for Seurat v3 HVG selection (used by GraphST)
    
    # ========== Advanced Cell Type Annotation ==========
    "tangram-sc>=1.0.0",  # Spatial mapping of cell types

    # SingleR requires C++ dependencies (mattress, knncolle) that fail on Windows
    # Error: MinGW "too many sections" compilation error (Windows PE format limitation)
    "singler>=0.4.0; sys_platform != 'win32'",  # SingleR Python implementation
    "singlecellexperiment>=0.4.0; sys_platform != 'win32'",  # Required for SingleR
    "celldex>=0.3.0; sys_platform != 'win32'",  # Reference datasets for SingleR
    "mllmcelltype>=0.1.0",  # LLM-based cell type annotation

    # ========== R Interface (for specific methods) ==========
    # IMPORTANT: rpy2 3.6.x requires R 4.5 which has compatibility issues
    # We pin to 3.5.x which works well with R 4.4.1
    # Note: Requires R to be installed (GitHub Actions installs R 4.4.1)
    "rpy2>=3.5.0,<3.7",  # Compatible with R 4.4.x, required for RCTD, SPOTlight, etc.
    "anndata2ri>=1.3.0",  # Sparse matrix support for R deconvolution (85.9% memory savings)
    
    # ========== Extended Spatial Analysis ==========
    "pysal>=2.6.0",  # Full Python spatial analysis library
    "statsmodels>=0.13.0",  # Statistical modeling
    "networkx>=2.6.0",  # Network analysis for spatial graphs
    
    # ========== Spatial Registration ==========
    "POT>=0.9.0",  # Python optimal transport
    # "STalign>=1.0.0",  # Spatial alignment tool (install from GitHub, not on PyPI)
    "paste-bio>=1.0.0",  # PASTE spatial registration

    # ========== CNV Analysis ==========
    "infercnvpy>=0.4.0",  # Copy number variation inference from spatial transcriptomics
    # Note: Numbat CNV analysis also supported via rpy2 (requires R package: install.packages('numbat'))

    # ========== Advanced Differential Expression ==========
    "pydeseq2>=0.4.0",  # Python DESeq2 for pseudobulk differential expression

    # ========== Spatial Enrichment Extensions ==========
    "enrichmap",  # Enrichment map visualization (Python >=3.10)
    "statannotations>=0.2.0",  # Statistical annotations for plots
    "pygam>=0.8.0",  # Generalized additive models
    "scikit-gstat>=1.0.0",  # Geostatistical analysis
    "adjustText>=0.8.0",  # Automatic label placement
    "splot>=1.1.0",  # Spatial plotting
    
    # ========== Emerging Technologies ==========
    "spatialdata>=0.2.0",  # Emerging spatial data format standard
]

# SCTransform normalization (variance-stabilizing transformation)
# Note: SCTransform now uses R's sctransform package via rpy2 (more stable than pySCTransform)
# Requirements: R with sctransform package installed
# Install R package: R -e 'install.packages("sctransform")'
# rpy2 is already included in the [full] optional dependencies

# Spatial domain methods with known dependency issues
# - SpaGCN: directly depends on louvain which fails to compile on newer macOS/Clang
#   (louvain 0.7.x has C function prototype issues, fixed in 0.8.0 but SpaGCN pins old version)
# - BANKSY: requires numpy<2.0 which conflicts with many modern packages
#   (pybanksy works with numpy 2.x despite the constraint, see GitHub issue #37)
# Install igraph first if issues: brew install igraph (macOS) or apt install libigraph-dev (Linux)
spatial-domains = [
    "SpaGCN>=1.2.5,<2.0",  # Graph convolutional network (requires louvain)
    "pybanksy>=1.3.4",  # BANKSY: spatial feature augmentation (declares numpy<2.0)
]

# HPC acceleration (requires system PETSc/SLEPc libraries)
# Install: brew install petsc slepc (macOS) or apt install petsc-dev slepc-dev (Linux)
hpc = [
    "petsc4py>=3.18.0,<4.0; sys_platform != 'win32'",
    "slepc4py>=3.18.0,<4.0; sys_platform != 'win32'",
]

# Development dependencies
dev = [
    "pytest>=8.0.0",
    "pytest-asyncio>=0.23.0,<2.0",
    "black>=22.0.0,<26.0",
    "mypy>=1.0.0,<2.0",
    "ruff>=0.1.0",
    "isort>=5.0.0",
    "pre-commit>=3.0.0,<5.0",
]

[project.urls]
Homepage = "https://github.com/cafferychen777/ChatSpatial"
Documentation = "https://chatspatial.readthedocs.io"
Repository = "https://github.com/cafferychen777/ChatSpatial"
Issues = "https://github.com/cafferychen777/ChatSpatial/issues"

[project.scripts]
chatspatial = "chatspatial.__main__:main"

[tool.pytest.ini_options]
minversion = "6.0"
testpaths = ["tests"]
python_files = "test_*.py"
python_classes = "Test*"
python_functions = "test_*"
addopts = "-v -m 'not slow' --strict-markers"
# Fix pytest-asyncio warning
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"
markers = [
    "unit: Unit tests for pure functions",
    "integration: Multi-component integration tests",
    "e2e: End-to-end workflow tests through public tool interfaces",
    "slow: Heavy dependency or long-running tests (excluded by default)",
]
# Suppress known upstream dependency version warnings
filterwarnings = [
    "ignore:.*jinja2.*:UserWarning",
    "ignore:.*numpy.*version.*:UserWarning",
]

[tool.black]
line-length = 88
target-version = ["py311"]

[tool.isort]
profile = "black"
line_length = 88

[tool.mypy]
python_version = "3.11"
warn_return_any = false
warn_unused_ignores = true
ignore_missing_imports = true
plugins = ["pydantic.mypy"]

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true

[tool.setuptools.packages.find]
where = ["."]
include = ["chatspatial", "chatspatial.*"]
exclude = ["tests", "tests.*", "chatspatial.tests", "chatspatial.tests.*"]

[tool.setuptools.package-data]
chatspatial = ["py.typed"]