fix(docker): use subprocess bridge for Python version isolation (#18)

PROBLEM: DeepISLES requires Python 3.8 (conda env), but Gradio 6 needs
Python 3.10+. They cannot coexist in the same Python process.

SOLUTION: Shell out architecture
- Gradio app runs in system Python (3.10+)
- DeepISLES runs via subprocess in conda env (3.8)
- New adapter script bridges the two environments

Changes:
- Dockerfile: Install deps to system Python, not conda env
- direct.py: Rewritten to use subprocess + conda run
- scripts/deepisles_adapter.py: New adapter for subprocess invocation
- tests: Updated error message expectations

This fixes the BUILD_ERROR on HF Spaces caused by trying to install
Gradio 6 into Python 3.8.

Dockerfile

@@ -31,9 +31,10 @@ WORKDIR /home/user/demo
 # Copy requirements first for better layer caching
 COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
 
-# Install Python dependencies INTO THE CONDA ENVIRONMENT
-# DeepISLES uses 'isles_ensemble' conda env - we must install there
-RUN /bin/bash -c "source activate isles_ensemble && pip install --no-cache-dir -r requirements.txt"
+# Install Python dependencies into SYSTEM Python (NOT conda env)
+# DeepISLES conda env is Python 3.8, but Gradio 6 needs Python 3.10+
+# We'll shell out to conda env for inference only
+RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy application source code and package files
 COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
@@ -41,9 +42,13 @@ COPY --chown=1000:1000 README.md /home/user/demo/README.md
 COPY --chown=1000:1000 src/ /home/user/demo/src/
 COPY --chown=1000:1000 app.py /home/user/demo/app.py
 
-# Install the package itself INTO THE CONDA ENVIRONMENT
+# Copy adapter script for subprocess invocation of DeepISLES
+# This script runs in the conda env (Py3.8) and is called via subprocess
+COPY --chown=1000:1000 scripts/deepisles_adapter.py /app/deepisles_adapter.py
+
+# Install the package itself into SYSTEM Python
 # Using --no-deps since requirements.txt already installed dependencies
-RUN /bin/bash -c "source activate isles_ensemble && pip install --no-cache-dir --no-deps -e ."
+RUN pip install --no-cache-dir --no-deps -e .
 
 # Set environment variable to indicate we're running in HF Spaces
 # This allows the app to detect runtime environment and use direct invocation
@@ -67,10 +72,9 @@ USER user
 # Expose the Gradio port
 EXPOSE 7860
 
-# IMPORTANT: DeepISLES uses a conda environment called 'isles_ensemble'
-# All PyTorch/nnU-Net dependencies are ONLY available in that conda env
-# We must run our app inside that environment to access DeepISLES imports
+# Reset ENTRYPOINT from base image
 ENTRYPOINT []
 
-# Run our Gradio app inside the isles_ensemble conda environment
-CMD ["/bin/bash", "-c", "source activate isles_ensemble && python -m stroke_deepisles_demo.ui.app"]
+# Run Gradio app with SYSTEM Python (Py3.10+)
+# DeepISLES inference is invoked via subprocess into conda env
+CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]

scripts/deepisles_adapter.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python
+"""DeepISLES adapter script for subprocess invocation.
+
+This script runs inside the isles_ensemble conda environment (Python 3.8)
+and is called by our Gradio app (Python 3.10+) via subprocess.
+
+Usage:
+    conda run -n isles_ensemble python scripts/deepisles_adapter.py \
+        --dwi /path/to/dwi.nii.gz \
+        --adc /path/to/adc.nii.gz \
+        --output /path/to/output \
+        [--flair /path/to/flair.nii.gz] \
+        [--fast]
+
+Note: This script intentionally uses Python 3.8 compatible syntax and
+os.path functions (not pathlib) for compatibility with DeepISLES environment.
+"""
+
+import argparse
+import os
+import sys
+
+# Add DeepISLES to path
+sys.path.insert(0, "/app")
+
+from src.isles22_ensemble import IslesEnsemble
+
+
+def main() -> None:
+    """Run DeepISLES inference with command-line arguments."""
+    parser = argparse.ArgumentParser(description="DeepISLES inference adapter")
+    parser.add_argument("--dwi", required=True, help="Path to DWI NIfTI file")
+    parser.add_argument("--adc", required=True, help="Path to ADC NIfTI file")
+    parser.add_argument("--output", required=True, help="Output directory")
+    parser.add_argument("--flair", default=None, help="Path to FLAIR NIfTI file")
+    parser.add_argument("--fast", action="store_true", help="Fast mode (SEALS only)")
+    parser.add_argument("--ensemble-path", default="/app", help="Path to DeepISLES repo")
+
+    args = parser.parse_args()
+
+    # Validate inputs exist (using os.path for Py3.8 compatibility)
+    if not os.path.exists(args.dwi):  # noqa: PTH110
+        print(f"ERROR: DWI file not found: {args.dwi}", file=sys.stderr)
+        sys.exit(1)
+    if not os.path.exists(args.adc):  # noqa: PTH110
+        print(f"ERROR: ADC file not found: {args.adc}", file=sys.stderr)
+        sys.exit(1)
+    if args.flair and not os.path.exists(args.flair):  # noqa: PTH110
+        print(f"ERROR: FLAIR file not found: {args.flair}", file=sys.stderr)
+        sys.exit(1)
+
+    # Create output directory (using os.makedirs for Py3.8 compatibility)
+    os.makedirs(args.output, exist_ok=True)  # noqa: PTH103
+
+    # Run inference
+    print("Running DeepISLES inference...")
+    print(f"  DWI: {args.dwi}")
+    print(f"  ADC: {args.adc}")
+    print(f"  FLAIR: {args.flair}")
+    print(f"  Output: {args.output}")
+    print(f"  Fast mode: {args.fast}")
+
+    stroke_segm = IslesEnsemble()
+    stroke_segm.predict_ensemble(
+        ensemble_path=args.ensemble_path,
+        input_dwi_path=args.dwi,
+        input_adc_path=args.adc,
+        input_flair_path=args.flair,
+        output_path=args.output,
+        fast=args.fast,
+        skull_strip=False,
+        save_team_outputs=False,
+        results_mni=False,
+        parallelize=True,
+    )
+
+    print(f"DeepISLES inference complete. Output: {args.output}")
+
+
+if __name__ == "__main__":
+    main()

src/stroke_deepisles_demo/inference/direct.py

@@ -1,57 +1,37 @@
-"""Direct DeepISLES invocation without Docker.
+"""Direct DeepISLES invocation via subprocess.
 
-This module provides direct Python invocation of DeepISLES when running
-inside the DeepISLES Docker image (e.g., on HF Spaces). This avoids
-Docker-in-Docker which is not supported on HF Spaces.
+This module provides subprocess-based invocation of DeepISLES when running
+on HF Spaces. We use subprocess because:
+- DeepISLES runs in a conda env with Python 3.8
+- Our Gradio app requires Python 3.10+ for modern dependencies
+- The two environments are incompatible, so we bridge via subprocess
 
 Usage:
-    When running in HF Spaces, our container is based on isleschallenge/deepisles,
-    which has all DeepISLES dependencies pre-installed. This module imports
-    and calls DeepISLES directly.
+    The subprocess calls /app/deepisles_adapter.py inside the isles_ensemble
+    conda environment, which imports and runs IslesEnsemble.
 
 See:
     - https://github.com/ezequieldlrosa/DeepIsles
     - docs/specs/07-hf-spaces-deployment.md
+    - scripts/deepisles_adapter.py
 """
 
 from __future__ import annotations
 
-import os
-import sys
+import subprocess
 import time
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path  # noqa: TC003 - used at runtime in dataclass and functions
 
 from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
 from stroke_deepisles_demo.core.logging import get_logger
-from stroke_deepisles_demo.inference.deepisles import find_prediction_mask
 
 logger = get_logger(__name__)
 
-
-def _get_deepisles_search_paths() -> list[str]:
-    """Get paths to search for DeepISLES modules.
-
-    Checks DEEPISLES_PATH environment variable first, then falls back to
-    common installation locations.
-    """
-    paths = []
-
-    # Check environment variable first (set in Dockerfile)
-    env_path = os.environ.get("DEEPISLES_PATH")
-    if env_path:
-        paths.append(env_path)
-
-    # Add common installation locations (excluding any already added via env var)
-    fallback_paths = [
-        "/app",  # Default location in isleschallenge/deepisles Docker image
-        "/DeepIsles",
-        "/opt/deepisles",
-        "/home/user/DeepIsles",
-    ]
-    paths.extend(p for p in fallback_paths if p not in paths)
-
-    return paths
+# Path to conda and adapter script in the Docker container
+CONDA_PATH = "/opt/conda/bin/conda"
+ADAPTER_SCRIPT = "/app/deepisles_adapter.py"
+CONDA_ENV_NAME = "isles_ensemble"
 
 
 @dataclass(frozen=True)
@@ -62,53 +42,6 @@ class DirectInvocationResult:
     elapsed_seconds: float
 
 
-def _ensure_deepisles_importable() -> str:
-    """
-    Ensure DeepISLES modules are importable by adding to sys.path.
-
-    Returns:
-        Path where DeepISLES was found
-
-    Raises:
-        DeepISLESError: If DeepISLES cannot be found
-    """
-    search_paths = _get_deepisles_search_paths()
-
-    for path in search_paths:
-        path_obj = Path(path)
-        if path_obj.exists():
-            # Log what we find for debugging
-            logger.info("Checking path %s - exists: True", path)
-            if (path_obj / "src").exists():
-                src_contents = list((path_obj / "src").iterdir())[:10]
-                logger.info("  /src contents: %s", [f.name for f in src_contents])
-            else:
-                logger.info("  /src does NOT exist")
-                # Check what IS in this directory
-                contents = list(path_obj.iterdir())[:10]
-                logger.info("  directory contents: %s", [f.name for f in contents])
-
-            if path not in sys.path:
-                sys.path.insert(0, path)
-            try:
-                # Test import (only available in DeepISLES Docker image)
-                from src.isles22_ensemble import IslesEnsemble  # noqa: F401
-
-                logger.info("Found DeepISLES at %s", path)
-                return path
-            except ImportError as e:
-                logger.warning("Import failed at %s: %s", path, e)
-                continue
-        else:
-            logger.info("Checking path %s - exists: False", path)
-
-    raise DeepISLESError(
-        "DeepISLES modules not found. Direct invocation requires running "
-        "inside the DeepISLES Docker image. Searched paths: "
-        f"{search_paths}"
-    )
-
-
 def validate_input_files(
     dwi_path: Path,
     adc_path: Path,
@@ -133,6 +66,39 @@ def validate_input_files(
         raise MissingInputError(f"FLAIR file not found: {flair_path}")
 
 
+def find_prediction_mask(output_dir: Path) -> Path:
+    """
+    Find the prediction mask in DeepISLES output directory.
+
+    DeepISLES outputs the lesion mask as 'lesion_msk.nii.gz'.
+
+    Args:
+        output_dir: DeepISLES output directory
+
+    Returns:
+        Path to the prediction mask NIfTI file
+
+    Raises:
+        DeepISLESError: If no prediction mask found
+    """
+    # DeepISLES outputs lesion_msk.nii.gz
+    expected_path = output_dir / "lesion_msk.nii.gz"
+    if expected_path.exists():
+        return expected_path
+
+    # Fall back to searching for any NIfTI file
+    nifti_files = list(output_dir.glob("*.nii.gz"))
+    nifti_files = [
+        f for f in nifti_files if not any(x in f.name.lower() for x in ["dwi", "adc", "flair"])
+    ]
+    if nifti_files:
+        return nifti_files[0]
+
+    raise DeepISLESError(
+        f"No prediction mask found in {output_dir}. Expected 'lesion_msk.nii.gz' or similar."
+    )
+
+
 def run_deepisles_direct(
     dwi_path: Path,
     adc_path: Path,
@@ -140,17 +106,18 @@ def run_deepisles_direct(
     *,
     flair_path: Path | None = None,
     fast: bool = True,
-    skull_strip: bool = False,
-    parallelize: bool = True,
-    save_team_outputs: bool = False,
-    results_mni: bool = False,
+    skull_strip: bool = False,  # noqa: ARG001 - kept for API compatibility
+    parallelize: bool = True,  # noqa: ARG001 - kept for API compatibility
+    save_team_outputs: bool = False,  # noqa: ARG001 - kept for API compatibility
+    results_mni: bool = False,  # noqa: ARG001 - kept for API compatibility
+    timeout: float = 1800,  # 30 minutes
 ) -> DirectInvocationResult:
     """
-    Run DeepISLES segmentation via direct Python invocation.
+    Run DeepISLES segmentation via subprocess into conda environment.
 
-    This function calls the DeepISLES IslesEnsemble.predict_ensemble() method
-    directly, bypassing Docker. It's used when running inside the DeepISLES
-    container on HF Spaces.
+    This function calls the deepisles_adapter.py script inside the
+    isles_ensemble conda environment via subprocess. This bridges the
+    Python version gap (Gradio needs 3.10+, DeepISLES needs 3.8).
 
     Args:
         dwi_path: Path to DWI NIfTI file (b=1000)
@@ -158,10 +125,11 @@ def run_deepisles_direct(
         output_dir: Directory for output files
         flair_path: Optional path to FLAIR NIfTI file
         fast: If True, use SEALS model only (faster, no FLAIR needed)
-        skull_strip: If True, perform skull stripping
-        parallelize: If True, run models in parallel
-        save_team_outputs: If True, save individual team outputs
-        results_mni: If True, output results in MNI space
+        skull_strip: If True, perform skull stripping (not passed to subprocess)
+        parallelize: If True, run models in parallel (not passed to subprocess)
+        save_team_outputs: If True, save individual team outputs (not passed)
+        results_mni: If True, output results in MNI space (not passed)
+        timeout: Maximum seconds to wait for inference
 
     Returns:
         DirectInvocationResult with path to prediction mask
@@ -184,52 +152,76 @@ def run_deepisles_direct(
     # Validate inputs
     validate_input_files(dwi_path, adc_path, flair_path)
 
-    # Ensure DeepISLES is importable
-    deepisles_path = _ensure_deepisles_importable()
-
-    # Import DeepISLES (only available in DeepISLES Docker image)
-    try:
-        from src.isles22_ensemble import IslesEnsemble
-    except ImportError as e:
-        raise DeepISLESError(f"Failed to import DeepISLES: {e}") from e
-
     # Create output directory
     output_dir.mkdir(parents=True, exist_ok=True)
 
     logger.info(
-        "Running DeepISLES direct invocation: dwi=%s, adc=%s, flair=%s, fast=%s",
+        "Running DeepISLES via subprocess: dwi=%s, adc=%s, flair=%s, fast=%s",
         dwi_path,
         adc_path,
         flair_path,
         fast,
     )
 
+    # Build command to run adapter script in conda environment
+    # Using: conda run -n isles_ensemble python /app/deepisles_adapter.py ...
+    cmd = [
+        CONDA_PATH,
+        "run",
+        "-n",
+        CONDA_ENV_NAME,
+        "python",
+        ADAPTER_SCRIPT,
+        "--dwi",
+        str(dwi_path.resolve()),
+        "--adc",
+        str(adc_path.resolve()),
+        "--output",
+        str(output_dir.resolve()),
+    ]
+
+    if flair_path is not None:
+        cmd.extend(["--flair", str(flair_path.resolve())])
+
+    if fast:
+        cmd.append("--fast")
+
+    logger.info("Subprocess command: %s", " ".join(cmd))
+
     try:
-        # Initialize the ensemble
-        stroke_segm = IslesEnsemble()
-
-        # Run prediction
-        stroke_segm.predict_ensemble(
-            ensemble_path=deepisles_path,
-            input_dwi_path=str(dwi_path),
-            input_adc_path=str(adc_path),
-            input_flair_path=str(flair_path) if flair_path else None,
-            output_path=str(output_dir),
-            skull_strip=skull_strip,
-            fast=fast,
-            save_team_outputs=save_team_outputs,
-            results_mni=results_mni,
-            parallelize=parallelize,
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd="/app",  # Run from DeepISLES directory
         )
-    except Exception as e:
-        logger.exception("DeepISLES inference failed")
-        raise DeepISLESError(f"DeepISLES inference failed: {e}") from e
 
-    # Find the prediction mask (using shared function from deepisles module)
+        # Log output
+        if result.stdout:
+            logger.info("DeepISLES stdout:\n%s", result.stdout)
+        if result.stderr:
+            logger.warning("DeepISLES stderr:\n%s", result.stderr)
+
+        # Check for failure
+        if result.returncode != 0:
+            raise DeepISLESError(
+                f"DeepISLES inference failed with exit code {result.returncode}. "
+                f"stderr: {result.stderr}"
+            )
+
+    except subprocess.TimeoutExpired as e:
+        raise DeepISLESError(f"DeepISLES inference timed out after {timeout} seconds") from e
+    except FileNotFoundError as e:
+        raise DeepISLESError(
+            f"Failed to run DeepISLES subprocess: {e}. Is conda available at /opt/conda/bin/conda?"
+        ) from e
+
+    # Find the prediction mask
     prediction_path = find_prediction_mask(output_dir)
 
     elapsed = time.time() - start_time
-    logger.info("DeepISLES direct invocation completed in %.2fs", elapsed)
+    logger.info("DeepISLES subprocess completed in %.2fs", elapsed)
 
     return DirectInvocationResult(
         prediction_path=prediction_path,

tests/inference/test_direct.py

@@ -143,9 +143,7 @@ class TestRunDeepISLESDirect:
         with pytest.raises(MissingInputError):
             run_deepisles_direct(dwi, adc, output)
 
-    def test_deepisles_not_available_raises(
-        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
-    ) -> None:
+    def test_deepisles_not_available_raises(self, tmp_path: Path) -> None:
         """Raises DeepISLESError when DeepISLES not available."""
         from stroke_deepisles_demo.inference.direct import run_deepisles_direct
 
@@ -156,8 +154,7 @@ class TestRunDeepISLESDirect:
         dwi.touch()
         adc.touch()
 
-        # Ensure DeepISLES is not importable
-        monkeypatch.delenv("DEEPISLES_DIRECT_INVOCATION", raising=False)
-
-        with pytest.raises(DeepISLESError, match="DeepISLES modules not found"):
+        # Subprocess will fail because conda/adapter not available locally
+        # The error message depends on what's missing (conda, /app dir, etc.)
+        with pytest.raises(DeepISLESError, match=r"(subprocess|conda|No such file)"):
             run_deepisles_direct(dwi, adc, output)