Merge pull request #2 from zhangtaolab/dev

Dev

Author: forrestzhang

CONTRIBUTING.md

@@ -59,7 +59,7 @@ source .venv/bin/activate  # Linux/macOS
 .venv\Scripts\activate     # Windows
 
 # Install DNALLM in development mode
-uv pip install -e '.[dev,test]'
+uv pip install -e '.[dev]'
 ```
 
 ### 2. Pre-commit Hooks (Optional)
@@ -627,7 +627,7 @@ We follow [Semantic Versioning](https://semver.org/):
 # Setup development environment
 uv venv
 source .venv/bin/activate
-uv pip install -e '.[dev,test]'
+uv pip install -e '.[dev]'
 
 # Pre-commit validation (run before every commit)
 # Option 1: Use automated script (recommended, code quality only)
@@ -658,7 +658,7 @@ mkdocs serve
 1. **Code check script fails**:
    - Make sure you're in the DNALLM root directory
    - Ensure virtual environment is activated: `source .venv/bin/activate`
-   - Install dependencies: `uv pip install -e '.[dev,test]'`
+   - Install dependencies: `uv pip install -e '.[dev]'`
 
 2. **Ruff formatting errors**:
    - Auto-fix: `python scripts/check_code.py --fix`

README.md

@@ -77,11 +77,11 @@ pip install --upgrade pip
 # Install uv in virtual environment
 pip install uv
 
-# Install DNALLM with base dependencies
-uv pip install -e '.[base]'
+# Install DNALLM with all optional dependencies
+uv pip install -e '.[all]'
 
-# For MCP server support (optional)
-uv pip install -e '.[mcp]'
+# Or install only base development tools
+# uv pip install -e '.[base]'
 
 # Verify installation
 python -c "import dnallm; print('DNALLM installed successfully!')"
@@ -103,19 +103,19 @@ conda activate dnallm
 # Install uv in conda environment
 conda install uv -c conda-forge
 
-# Install DNALLM with base dependencies
-uv pip install -e '.[base]'
+# Install DNALLM with all optional dependencies
+uv pip install -e '.[all]'
 
-# For MCP server support (optional)
-uv pip install -e '.[mcp]'
+# Or install only base development tools
+# uv pip install -e '.[base]'
 
 # Verify installation
 python -c "import dnallm; print('DNALLM installed successfully!')"
 ```
 
 ### GPU Support
 
-For GPU acceleration, install the appropriate CUDA version:
+For GPU acceleration, install the appropriate CUDA version **after** installing the base package:
 
 ```bash
 # For venv users: activate virtual environment
@@ -127,11 +127,45 @@ source .venv/bin/activate  # Linux/MacOS
 # conda activate dnallm
 
 # CUDA 12.4 (recommended for recent GPUs)
-uv pip install -e '.[cuda124]'
+uv pip install -e '.[all,cuda124]'
 
 # Other supported versions: cpu, cuda121, cuda126, cuda128
 # Nvidia 5090 Please use cuda128 & torch==2.7
-uv pip install -e '.[cuda128]'
+uv pip install -e '.[all,cuda128]'
+```
+
+> **Warning:** Hardware groups (`cpu`, `cuda121`, `cuda124`, `cuda126`, `cuda128`, `rocm`, `mamba`) are mutually exclusive. You must choose exactly one. Do NOT combine multiple CUDA versions.
+
+### Dependency Groups
+
+| Group | Purpose | Includes |
+|-------|---------|----------|
+| `all` | Install everything | `base` + `docs` + `ui` |
+| `base` | Full dev environment | `dev` + `test` + `notebook` + `mcp` + extra tools |
+| `dev` | Development | `test` + `notebook` + linting/typing tools |
+| `test` | Testing only | pytest and plugins |
+| `notebook` | Interactive notebooks | Jupyter, Marimo |
+| `docs` | Build documentation | mkdocs and plugins |
+| `ui` | Gradio web interface | Gradio |
+| `mcp` | MCP server | (included in core) |
+
+**Hardware groups (mutually exclusive, NOT included in `all`):**
+
+| Group | PyTorch | Use Case |
+|-------|---------|----------|
+| `cpu` | 2.4.0-2.7 | No GPU |
+| `cuda121` | 2.2.0-2.7 | Older NVIDIA GPUs |
+| `cuda124` | 2.4.0-2.7 | Most modern GPUs (recommended) |
+| `cuda126` | 2.6.0-2.7 | Ada/Hopper with Flash Attention |
+| `cuda128` | 2.6.0-2.7 | RTX 5090 and latest hardware |
+| `rocm` | 2.5.0-2.7 | AMD GPUs |
+| `mamba` | 2.6.0-2.7 | Native Mamba architecture (requires CUDA) |
+
+```bash
+# Examples:
+uv pip install -e '.[all,cuda124]'    # Everything + CUDA 12.4
+uv pip install -e '.[base,mamba]'     # Dev tools + native Mamba
+uv pip install -e '.[test,cpu]'       # Testing only, no GPU
 ```
 
 ### Native Mamba Support

docs/faq/models_troubleshooting.md

@@ -8,7 +8,7 @@
 
 ```bash
 # Install without the [mamba] extra
-uv pip install -e '.[base,mcp,dev,notebook]'
+uv pip install -e '.[base]'
 ```
 
 Then load a Mamba model through `transformers` (cpu only) as usual. Note that this fallback path is significantly slower than the optimized `mamba-ssm` kernels (which require Linux + CUDA).

docs/getting_started/installation.md

@@ -113,28 +113,34 @@ DNALLM provides multiple dependency groups for different use cases:
 
 ### Core Dependency Groups
 
-| Dependency Group | Purpose | When to Use |
-|-----------------|---------|-------------|
-| **base** | Development tools + ML libraries | Recommended for most users |
-| **dev** | Complete development environment | For contributors |
-| **test** | Testing environment only | For running tests |
-| **notebook** | Jupyter and Marimo support | For interactive notebooks |
-| **docs** | Documentation building | For building docs |
-| **mcp** | MCP server support | For MCP deployment |
+| Group | Purpose | Includes |
+|-------|---------|----------|
+| **all** | Install all optional dependencies | `base` + `docs` + `ui` |
+| **base** | Full development environment | `dev` + `test` + `notebook` + `mcp` + extra tools (isort, types-transformers) |
+| **dev** | Complete development environment | `test` + `notebook` + linting/typing (ruff, flake8, pre-commit, mypy, pandas-stubs) |
+| **test** | Testing environment only | pytest and plugins |
+| **notebook** | Jupyter and Marimo support | Jupyter Lab, Marimo |
+| **docs** | Documentation building | mkdocs-material, mkdocstrings, mkdocs-jupyter |
+| **ui** | Gradio web interface | Gradio |
+| **mcp** | MCP server support | Included in core dependencies (no extra install needed) |
 
-> **Note:** Core ML libraries (torch, transformers, datasets, peft, accelerate) are installed automatically as main dependencies. The groups above add additional functionality.
+> **Note:** `mcp` is an empty extra because MCP dependencies (`mcp`, `starlette`, `uvicorn`, `websockets`) are already part of the core dependencies. You can still use `.[mcp]` for clarity but it won't install additional packages.
 
-### Hardware-Specific Groups
+### Hardware-Specific Groups (Mutually Exclusive)
 
-| Dependency Group | PyTorch Version | GPU Type | When to Use |
-|-----------------|-----------------|----------|-------------|
+> **Warning:** These groups are mutually exclusive. You MUST choose exactly one. Combining multiple hardware groups will cause conflicts.
+
+| Group | PyTorch Version | GPU Type | When to Use |
+|-------|----------------|----------|-------------|
 | **cpu** | 2.4.0-2.7 | CPU only | Development without GPU |
 | **cuda121** | 2.2.0-2.7 | NVIDIA (older) | Volta/Turing/Ampere early |
 | **cuda124** | 2.4.0-2.7 | NVIDIA (recommended) | Most modern GPUs |
 | **cuda126** | 2.6.0-2.7 | NVIDIA (latest) | Ada/Hopper with Flash Attention |
-| **cuda128** | 2.7.0+ | NVIDIA (cutting-edge) | Latest hardware |
+| **cuda128** | 2.6.0-2.7 | NVIDIA (cutting-edge) | RTX 5090 and latest hardware |
 | **rocm** | 2.5.0-2.7 | AMD GPUs | AMD GPU users |
-| **mamba** | 2.4.0-2.7 | NVIDIA + Mamba | For Mamba architecture models |
+| **mamba** | 2.6.0-2.7 | NVIDIA + Mamba | Native Mamba architecture (requires CUDA) |
+
+> **Note:** Hardware groups are NOT included in `all` because they conflict with each other. Always combine a hardware group with your chosen feature group: e.g., `.[all,cuda124]`
 
 ## Installation Scenarios
 
@@ -147,8 +153,8 @@ For development and testing without GPU acceleration:
 conda create -n dnallm-cpu python=3.12 -y
 conda activate dnallm-cpu
 
-# Install base dependencies and CPU version
-uv pip install -e '.[base,cpu]'
+# Install all dependencies and CPU version
+uv pip install -e '.[all,cpu]'
 
 # Verify installation
 python -c "import dnallm; print('DNALLM installed successfully!')"
@@ -166,8 +172,8 @@ nvidia-smi
 conda create -n dnallm-gpu python=3.12 -y
 conda activate dnallm-gpu
 
-# Install base dependencies and CUDA 12.4 support
-uv pip install -e '.[base,cuda124]'
+# Install all dependencies and CUDA 12.4 support
+uv pip install -e '.[all,cuda124]'
 
 # Verify installation
 python -c "import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"
@@ -182,7 +188,7 @@ For models with Mamba architecture (Plant DNAMamba, Caduceus, Jamba-DNA):
 conda create -n dnallm-mamba python=3.12 -y
 conda activate dnallm-mamba
 
-# Install base dependencies
+# Install base dependencies first
 uv pip install -e '.[base]'
 
 # Install Mamba support (requires GPU)
@@ -201,8 +207,8 @@ For contributors and developers:
 conda create -n dnallm-dev python=3.12 -y
 conda activate dnallm-dev
 
-# Install complete development dependencies
-uv pip install -e '.[dev,notebook,docs,mcp,cuda124]'
+# Install all dependencies + CUDA support
+uv pip install -e '.[all,cuda124]'
 
 # Verify installation
 python -c "
@@ -223,8 +229,8 @@ For MCP server deployment:
 conda create -n dnallm-mcp python=3.12 -y
 conda activate dnallm-mcp
 
-# Install MCP-related dependencies
-uv pip install -e '.[base,mcp,cuda124]'
+# MCP dependencies are included in core, just install with CUDA support
+uv pip install -e '.[base,cuda124]'
 
 # Verify installation
 python -c 'from dnallm.mcp import server; print("MCP server dependencies installed!")'

docs/getting_started/quick_start.md

@@ -315,8 +315,8 @@ DNALLM supports the following task types:
 ## Need More Details?
 
 - See [Installation Guide](installation.md) for complete dependency information, including:
-  - All available dependency groups (base, dev, test, notebook, docs, mcp)
-  - Hardware-specific groups (cpu, cuda121, cuda124, cuda126, cuda128, rocm, mamba)
+  - All available dependency groups (`all`, `base`, `dev`, `test`, `notebook`, `docs`, `mcp`)
+  - Hardware-specific groups (`cpu`, `cuda121`, `cuda124`, `cuda126`, `cuda128`, `rocm`, `mamba`) — mutually exclusive
   - Installation scenarios for different use cases
   - Troubleshooting common issues
 

docs/index.md

@@ -56,11 +56,14 @@ conda activate dnallm
 # Install uv in conda environment
 conda install uv -c conda-forge
 
-# Install DNALLM with base dependencies
-uv pip install -e '.[base]'
+# Install DNALLM with all optional dependencies
+uv pip install -e '.[all]'
 
-# For MCP server support (optional)
-uv pip install -e '.[mcp]'
+# Or install only core + base development tools
+# uv pip install -e '.[base]'
+
+# Add GPU support (choose ONE: cpu, cuda121, cuda124, cuda126, cuda128, rocm)
+# uv pip install -e '.[all,cuda124]'
 
 # Verify installation
 python -c "import dnallm; print('DNALLM installed successfully!')"

docs/user_guide/getting_started.md

@@ -46,8 +46,11 @@ Getting DNALLM installed is the first step. We recommend using `uv`, a fast Pyth
     # Install uv, the fast package manager
     pip install uv
 
-    # Install DNALLM and its core dependencies
-    uv pip install -e '.[base]'
+    # Install DNALLM and all optional dependencies
+    uv pip install -e '.[all]'
+
+    # Or install only base development tools
+    # uv pip install -e '.[base]'
     ```
 
 4.  **Verify the Installation**

docs/user_guide/tutorial/end_to_end_workflow.md

@@ -998,7 +998,7 @@ COPY README.md ./
 
 # Install Python dependencies
 RUN pip install --no-cache-dir uv && \
-    uv pip install -e '.[base,mcp,cuda124]' --system
+    uv pip install -e '.[base,cuda124]' --system
 
 # Copy application code
 COPY dnallm/ ./dnallm/

pyproject.toml

@@ -76,20 +76,12 @@ Documentation = "https://zhangtaolab.github.io/DNALLM/"
 
 [project.optional-dependencies]
 dev = [
+    "dnallm[test,notebook]",
     "ruff==0.15.8",
     "flake8>=7.0.0",
     "pre-commit>=3.6.0",
-    "ipywidgets>=8",
-    "jupyter>=1.1.1",
-    "marimo>=0.16.3",
     "mypy>=1.15.0",
     "pandas-stubs>=2.3.0",
-    "pydantic>=2.10.6",
-    "pytest>=8.3.5",
-    "pytest-asyncio>=0.21.1",
-    "pytest-cov>=6.0.0",
-    "pytest-progress>=0.1.0",
-    "pytest-timeout>=2.3.1",
 ]
 test = [
     "pytest>=8.3.5",
@@ -99,7 +91,6 @@ test = [
     "pytest-timeout>=2.3.1",
 ]
 notebook = [
-    "ipywidgets>=8",
     "jupyter>=1.1.1",
     "marimo>=0.16.3",
 ]
@@ -109,26 +100,17 @@ docs = [
     "mkdocstrings-python>=1.16.10",
     "click<8.2.2",
 ]
-mcp = [
-    "mcp>=1.3.0",
-    "asyncio>=3.4.3",
+ui = [
+    "gradio>=4.0.0",
 ]
+mcp = []
 base = [
-    "asyncio>=3.4.3",
-    "ruff==0.15.8",
-    "flake8>=7.0.0",
-    "ipywidgets>=8",
+    "dnallm[dev,test,notebook,mcp]",
     "isort>=6.0.1",
-    "jupyter>=1.1.1",
-    "marimo>=0.16.3",
-    "mcp>=1.3.0",
-    "mypy>=1.15.0",
-    "pandas-stubs>=2.3.0",
-    "pydantic>=2.10.6",
     "types-transformers>=0.1.0",
-    "pytest>=8.3.5",
-    "pytest-cov>=6.0.0",
-    "pytest-progress>=0.1.0",
+]
+all = [
+    "dnallm[base,docs,ui]",
 ]
 cpu = [
     "torch>=2.4.0,<2.7",