feat(hf-spaces): complete deployment infrastructure for Hugging Face Spaces (#8)

* feat(hf-spaces): complete deployment infrastructure for Hugging Face Spaces

This commit implements full Hugging Face Spaces deployment support with:

Deployment Infrastructure:
- Add Dockerfile based on isleschallenge/deepisles image with Gradio app
- Add requirements.txt for HF Spaces (with git dependency)
- Add README.md YAML frontmatter (sdk: docker, t4-small GPU)

Direct DeepISLES Invocation:
- Add HF Spaces environment detection (is_running_in_hf_spaces())
- Add direct Python invocation wrapper (inference/direct.py)
- Refactor deepisles.py to auto-select Docker vs direct invocation
- This enables running on HF Spaces where Docker-in-Docker is unavailable

NiiVue Viewer Improvements:
- Update NiiVue from 0.57.0 to 0.65.0 (latest stable Dec 2025)
- Generate unique canvas IDs with UUID to support multiple viewers
- Add WebGL2 detection with graceful fallback
- Improve error handling in JavaScript

Dependency Updates:
- Pin Gradio to 6.0.x (latest stable Dec 2025)
- Pin numpy <2.0.0 for compatibility
- Add src.isles22_ensemble to mypy ignore list

Tests:
- Add tests for HF Spaces detection and direct invocation
- All 114 tests passing

References:
- docs/specs/07-hf-spaces-deployment.md
- https://huggingface.co/docs/hub/spaces-sdks-docker
- https://github.com/ezequieldlrosa/DeepIsles

* fix(hf-spaces): resolve critical deployment issues found in code review

Critical fixes:
- Dockerfile: Install package via `pip install -e .` so stroke_deepisles_demo is importable
(previously module would fail with ModuleNotFoundError on HF Spaces)
- config.py: Remove path-based HF Spaces detection fallback that caused false positives
on any Linux machine with /home/user and /app directories

Code quality:
- Consolidate duplicate find_prediction_mask functions into single implementation
in deepisles.py (direct.py now imports from deepisles.py)
- Update tests to import from correct locations

All 114 tests passing.

* refactor: improve error handling and observability

Changes:
- components.py: Fail loudly instead of silent fallback when loading cases
- Specific error messages for FileNotFoundError vs unexpected errors
- No more "Error loading cases" as a fake dropdown option
- Wire up deepisles_fast_mode config to UI checkbox (was dead code)

- adapter.py: Add logging for skipped cases in build_local_dataset
- Warn when DWI files have unparseable subject IDs
- Warn when cases are missing ADC files (shows first 5)
- Info log showing total loaded cases

These changes ensure problems surface immediately rather than causing
confusing failures downstream.

* fix: address CodeRabbit review feedback

Security:
- viewer.py: Fix XSS vulnerability by using json.dumps() to serialize URLs
before embedding in JavaScript (prevents injection via special characters)

Reproducibility:
- Dockerfile: Add documentation explaining 'latest' tag usage and
recommend SHA digest pinning for production
- requirements.txt: Pin CloseChoice/datasets to specific commit hash
(c1c15aaa4f00f28f1916f3a896283494162eac49) instead of branch name

Code quality:
- config.py: Make is_deepisles_direct_available() side-effect free
(only checks env var, no sys.path mutation during availability checks)
- deepisles.py: Use _ for unused tuple elements from validate_input_folder()
- direct.py: Remove unused stdout/stderr fields from DirectInvocationResult
(direct invocation uses Python API, not subprocess)
- components.py: Fix ruff formatting

All 114 tests passing.

* fix: additional codebase-wide anti-pattern fixes

- pipeline.py: Add exc_info=True to warning when Dice computation fails
(preserves traceback for debugging instead of just error message)

- metrics.py: Replace assert with proper type narrowing
(asserts are stripped in optimized mode -O; restructured to use
explicitly typed local variable `voxel_dims`)

All 114 tests passing.

* fix: address CodeRabbit review nitpicks

- Remove unused stdout/stderr fields from DirectInvocationResult
- Add logger.exception before re-raising DeepISLESError for full traceback

---------

Co-authored-by: Claude <noreply@anthropic.com>

Dockerfile

@@ -0,0 +1,60 @@
+# Dockerfile for Hugging Face Spaces deployment
+# Base: DeepISLES image with nnU-Net, SEALS, and all ML dependencies
+# See: docs/specs/07-hf-spaces-deployment.md
+#
+# IMPORTANT: During Docker build, GPU is NOT available.
+# All GPU operations happen at runtime only.
+
+# NOTE: isleschallenge/deepisles only publishes 'latest' tag on Docker Hub.
+# For reproducibility, consider using a SHA digest if available:
+#   FROM isleschallenge/deepisles@sha256:<digest>
+# Check https://hub.docker.com/r/isleschallenge/deepisles/tags for updates.
+# Current base: DeepISLES v1.1 (as of Dec 2025)
+FROM isleschallenge/deepisles:latest
+
+# Set environment variables for non-interactive installation
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# HF Spaces runs containers with user ID 1000
+# Create user if not exists (DeepISLES image may already have a user)
+RUN useradd -m -u 1000 user 2>/dev/null || true
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements first for better layer caching
+COPY --chown=1000:1000 requirements.txt /app/requirements.txt
+
+# Install Python dependencies (extras only - DeepISLES image has PyTorch, nnUNet, etc.)
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application source code and package files
+COPY --chown=1000:1000 pyproject.toml /app/pyproject.toml
+COPY --chown=1000:1000 README.md /app/README.md
+COPY --chown=1000:1000 src/ /app/src/
+COPY --chown=1000:1000 app.py /app/app.py
+
+# Install the package itself (makes stroke_deepisles_demo importable)
+# Using --no-deps since requirements.txt already installed dependencies
+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
+ENV HF_SPACES=1
+ENV DEEPISLES_DIRECT_INVOCATION=1
+
+# Create directories for data with proper permissions
+RUN mkdir -p /app/data /app/results /app/cache && \
+    chown -R 1000:1000 /app
+
+# Switch to non-root user (required by HF Spaces)
+USER user
+
+# Expose the Gradio port
+EXPOSE 7860
+
+# Set the default command
+# Use Gradio's built-in server settings for HF Spaces
+CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]

README.md

@@ -1,3 +1,27 @@
+---
+title: Stroke DeepISLES Demo
+emoji: "\U0001F9E0"
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_port: 7860
+suggested_hardware: t4-small
+pinned: false
+license: mit
+short_description: Ischemic stroke lesion segmentation using DeepISLES
+models:
+  - isleschallenge/deepisles
+datasets:
+  - YongchengYAO/ISLES24-MR-Lite
+tags:
+  - medical-imaging
+  - stroke
+  - segmentation
+  - neuroimaging
+  - niivue
+  - nnunet
+---
+
 # Stroke DeepISLES Demo
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

app.py

@@ -1,11 +1,37 @@
-"""Entry point for Hugging Face Spaces deployment."""
+"""Entry point for Hugging Face Spaces deployment.
+
+This module provides the entry point for deploying the stroke-deepisles-demo
+application to Hugging Face Spaces. It handles environment detection and
+configures Gradio appropriately for the deployment environment.
+
+See:
+    - docs/specs/07-hf-spaces-deployment.md
+    - https://huggingface.co/docs/hub/spaces-sdks-docker
+"""
 
 import gradio as gr
 
+from stroke_deepisles_demo.core.config import get_settings
+from stroke_deepisles_demo.core.logging import setup_logging
 from stroke_deepisles_demo.ui.app import get_demo
 
+# Initialize logging
+settings = get_settings()
+setup_logging(settings.log_level, format_style=settings.log_format)
+
 # Create the demo instance at module level for Gradio
 demo = get_demo()
 
 if __name__ == "__main__":
-    demo.launch(theme=gr.themes.Soft(), css="footer {visibility: hidden}")
+    # Launch configuration
+    # - server_name: 0.0.0.0 required for HF Spaces (Docker)
+    # - server_port: 7860 is HF Spaces default
+    # - theme: Gradio 6 uses launch() for theme
+    # - css: Hide footer for cleaner look
+    demo.launch(
+        server_name=settings.gradio_server_name,
+        server_port=settings.gradio_server_port,
+        share=settings.gradio_share,
+        theme=gr.themes.Soft(),
+        css="footer {visibility: hidden}",
+    )

pyproject.toml

@@ -25,14 +25,14 @@ dependencies = [
 
     # NIfTI handling
     "nibabel>=5.2.0",
-    "numpy>=1.26.0",
+    "numpy>=1.26.0,<2.0.0",
 
     # Configuration
     "pydantic>=2.5.0",
     "pydantic-settings>=2.1.0",
 
-    # UI (Gradio 5.x)
-    "gradio>=5.0.0",
+    # UI (Gradio 6.x - Dec 2025 stable)
+    "gradio>=6.0.0,<7.0.0",
     "matplotlib>=3.8.0",
 
     # Networking
@@ -112,6 +112,8 @@ module = [
     "niivue.*",
     "numpy.*",
     "pytest.*",
+    # DeepISLES modules (only available in DeepISLES Docker image)
+    "src.isles22_ensemble",
 ]
 ignore_missing_imports = true
 

requirements.txt

@@ -0,0 +1,25 @@
+# requirements.txt for Hugging Face Spaces Docker deployment
+# Generated: December 2025
+# See: docs/specs/07-hf-spaces-deployment.md
+
+# Core - Tobias's fork with BIDS + NIfTI lazy loading
+# Pinned to specific commit for reproducibility (Dec 2025)
+git+https://github.com/CloseChoice/datasets.git@c1c15aaa4f00f28f1916f3a896283494162eac49
+
+# HuggingFace
+huggingface-hub>=0.25.0
+
+# NIfTI handling
+nibabel>=5.2.0
+numpy>=1.26.0,<2.0.0
+
+# Configuration
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+
+# UI - Gradio 6.x (latest stable as of Dec 2025)
+gradio>=6.0.0,<7.0.0
+matplotlib>=3.8.0
+
+# Networking
+requests>=2.0.0

src/stroke_deepisles_demo/core/config.py

@@ -2,13 +2,56 @@
 
 from __future__ import annotations
 
+import os
 from pathlib import Path
 from typing import Literal
 
-from pydantic import Field, field_validator
+from pydantic import Field, computed_field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
+def is_running_in_hf_spaces() -> bool:
+    """
+    Detect if running inside Hugging Face Spaces environment.
+
+    Returns:
+        True if running in HF Spaces, False otherwise
+
+    Detection methods (all env-var based for reliability):
+        1. HF_SPACES=1 env var (set by our Dockerfile)
+        2. SPACE_ID env var (set by HF Spaces runtime)
+
+    Note:
+        We intentionally avoid path-based detection (like checking for
+        /home/user or /app) because these paths exist on many Linux
+        systems and would cause false positives.
+    """
+    # Check explicit env vars only - no path-based fallbacks
+    if os.environ.get("HF_SPACES") == "1":
+        return True
+    # SPACE_ID is set by HF Spaces runtime
+    return bool(os.environ.get("SPACE_ID"))
+
+
+def is_deepisles_direct_available() -> bool:
+    """
+    Check if DeepISLES can be invoked directly (without Docker).
+
+    Returns:
+        True if DEEPISLES_DIRECT_INVOCATION env var is set
+
+    This check is intentionally simple and side-effect free.
+    The env var is set by our Dockerfile when running on HF Spaces.
+    Actual module path setup happens in inference/direct.py when invoked.
+
+    Note:
+        We don't attempt import-based detection here because it would
+        require modifying sys.path, which is a side effect inappropriate
+        for a simple availability check.
+    """
+    return os.environ.get("DEEPISLES_DIRECT_INVOCATION") == "1"
+
+
 class Settings(BaseSettings):
     """
     Application settings loaded from environment variables.
@@ -42,6 +85,8 @@ class Settings(BaseSettings):
     deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
     deepisles_timeout_seconds: int = 1800  # 30 minutes
     deepisles_use_gpu: bool = True
+    # Path to DeepISLES repo (for direct invocation mode)
+    deepisles_repo_path: Path | None = None
 
     # Paths
     temp_dir: Path | None = None
@@ -52,6 +97,24 @@ class Settings(BaseSettings):
     gradio_server_port: int = 7860
     gradio_share: bool = False
 
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def is_hf_spaces(self) -> bool:
+        """Check if running in HF Spaces environment."""
+        return is_running_in_hf_spaces()
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def use_direct_invocation(self) -> bool:
+        """
+        Check if should use direct DeepISLES invocation (vs Docker).
+
+        Direct invocation is used when:
+        1. Running in HF Spaces (cannot run Docker-in-Docker)
+        2. DeepISLES modules are available for import
+        """
+        return self.is_hf_spaces or is_deepisles_direct_available()
+
     @field_validator("results_dir", mode="before")
     @classmethod
     def ensure_results_dir_exists(cls, v: Path | str) -> Path:

src/stroke_deepisles_demo/data/adapter.py

@@ -6,12 +6,16 @@ import re
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from stroke_deepisles_demo.core.logging import get_logger
+
 if TYPE_CHECKING:
     from collections.abc import Iterator
     from pathlib import Path
 
     from stroke_deepisles_demo.core.types import CaseFiles
 
+logger = get_logger(__name__)
+
 
 @dataclass
 class LocalDataset:
@@ -52,17 +56,21 @@ def build_local_dataset(data_dir: Path) -> LocalDataset:
     Scan directory and build case mapping.
 
     Matches DWI + ADC + Mask files by subject ID.
+    Logs warnings for incomplete cases that are skipped.
     """
     dwi_dir = data_dir / "Images-DWI"
     adc_dir = data_dir / "Images-ADC"
     mask_dir = data_dir / "Masks"
 
     cases: dict[str, CaseFiles] = {}
+    skipped_no_subject_id = 0
+    skipped_no_adc: list[str] = []
 
     # Scan DWI files to get subject IDs
     for dwi_file in dwi_dir.glob("*.nii.gz"):
         subject_id = parse_subject_id(dwi_file.name)
         if not subject_id:
+            skipped_no_subject_id += 1
             continue
 
         # Find matching ADC and Mask
@@ -70,7 +78,8 @@ def build_local_dataset(data_dir: Path) -> LocalDataset:
         mask_file = mask_dir / dwi_file.name.replace("_dwi.", "_lesion-msk.")
 
         if not adc_file.exists():
-            continue  # Skip incomplete cases
+            skipped_no_adc.append(subject_id)
+            continue
 
         case_files: CaseFiles = {
             "dwi": dwi_file,
@@ -81,4 +90,18 @@ def build_local_dataset(data_dir: Path) -> LocalDataset:
 
         cases[subject_id] = case_files
 
+    # Log skipped cases for debugging
+    if skipped_no_subject_id > 0:
+        logger.warning(
+            "Skipped %d DWI files: could not parse subject ID from filename",
+            skipped_no_subject_id,
+        )
+    if skipped_no_adc:
+        logger.warning(
+            "Skipped %d cases missing ADC file: %s",
+            len(skipped_no_adc),
+            ", ".join(skipped_no_adc[:5]) + ("..." if len(skipped_no_adc) > 5 else ""),
+        )
+
+    logger.info("Loaded %d cases from %s", len(cases), data_dir)
     return LocalDataset(data_dir=data_dir, cases=cases)

src/stroke_deepisles_demo/inference/__init__.py

@@ -6,6 +6,10 @@ from stroke_deepisles_demo.inference.deepisles import (
     run_deepisles_on_folder,
     validate_input_folder,
 )
+from stroke_deepisles_demo.inference.direct import (
+    DirectInvocationResult,
+    run_deepisles_direct,
+)
 from stroke_deepisles_demo.inference.docker import (
     DockerRunResult,
     build_docker_command,
@@ -17,11 +21,13 @@ from stroke_deepisles_demo.inference.docker import (
 __all__ = [
     "DEEPISLES_IMAGE",
     "DeepISLESResult",
+    "DirectInvocationResult",
     "DockerRunResult",
     "build_docker_command",
     "check_docker_available",
     "ensure_docker_available",
     "run_container",
+    "run_deepisles_direct",
     "run_deepisles_on_folder",
     "validate_input_folder",
 ]

src/stroke_deepisles_demo/inference/deepisles.py

@@ -1,4 +1,14 @@
-"""DeepISLES stroke segmentation wrapper."""
+"""DeepISLES stroke segmentation wrapper.
+
+This module provides a unified interface for running DeepISLES segmentation.
+It automatically detects the runtime environment and uses either:
+- Docker invocation (local development with Docker)
+- Direct Python invocation (HF Spaces, inside DeepISLES container)
+
+See:
+    - docs/specs/07-hf-spaces-deployment.md
+    - https://github.com/ezequieldlrosa/DeepIsles
+"""
 
 from __future__ import annotations
 
@@ -6,6 +16,7 @@ import time
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
+from stroke_deepisles_demo.core.config import get_settings
 from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
 from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.inference.docker import (
@@ -30,7 +41,7 @@ class DeepISLESResult:
     """Result of DeepISLES inference."""
 
     prediction_path: Path
-    docker_result: DockerRunResult
+    docker_result: DockerRunResult | None  # None when using direct invocation
     elapsed_seconds: float
 
 
@@ -65,7 +76,8 @@ def find_prediction_mask(output_dir: Path) -> Path:
     Find the prediction mask in DeepISLES output directory.
 
     DeepISLES outputs may have varying names depending on version.
-    This function finds the most likely prediction file.
+    This function searches both the results subdirectory and the
+    output directory itself.
 
     Args:
         output_dir: DeepISLES output directory
@@ -76,7 +88,9 @@ def find_prediction_mask(output_dir: Path) -> Path:
     Raises:
         DeepISLESError: If no prediction mask found
     """
+    # Check for results subdirectory (standard DeepISLES output structure)
     results_dir = output_dir / "results"
+    search_dirs = [results_dir, output_dir] if results_dir.exists() else [output_dir]
 
     # Check common output patterns
     possible_names = [
@@ -84,70 +98,50 @@ def find_prediction_mask(output_dir: Path) -> Path:
         "pred.nii.gz",
         "lesion_mask.nii.gz",
         "output.nii.gz",
+        "ensemble_prediction.nii.gz",
     ]
 
-    for name in possible_names:
-        pred_path = results_dir / name
-        if pred_path.exists():
-            return pred_path
-
-    # Fall back to finding any .nii.gz in results dir
-    if results_dir.exists():
-        nifti_files = list(results_dir.glob("*.nii.gz"))
+    for search_dir in search_dirs:
+        for name in possible_names:
+            pred_path = search_dir / name
+            if pred_path.exists():
+                return pred_path
+
+        # Fall back to finding any .nii.gz in the directory
+        # Exclude input files that might have been copied
+        nifti_files = list(search_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 {results_dir}. "
+        f"No prediction mask found in {output_dir}. "
         "Expected files like 'prediction.nii.gz' or similar."
     )
 
 
-def run_deepisles_on_folder(
+def _run_via_docker(
     input_dir: Path,
+    output_dir: Path,
     *,
-    output_dir: Path | None = None,
-    fast: bool = True,
-    gpu: bool = True,
-    timeout: float | None = 1800,  # 30 minutes default
+    flair_path: Path | None,
+    fast: bool,
+    gpu: bool,
+    timeout: float | None,
 ) -> DeepISLESResult:
     """
-    Run DeepISLES stroke segmentation on a folder of NIfTI files.
+    Run DeepISLES via Docker container.
 
-    Args:
-        input_dir: Directory containing dwi.nii.gz, adc.nii.gz, [flair.nii.gz]
-        output_dir: Where to write results (default: input_dir/results)
-        fast: If True, use single-model mode (faster, slightly less accurate)
-        gpu: If True, use GPU acceleration
-        timeout: Maximum seconds to wait for inference
-
-    Returns:
-        DeepISLESResult with path to prediction mask
-
-    Raises:
-        DockerNotAvailableError: If Docker is not available
-        DockerGPUNotAvailableError: If GPU requested but not available
-        MissingInputError: If required input files are missing
-        DeepISLESError: If inference fails (non-zero exit, missing output)
-
-    Example:
-        >>> result = run_deepisles_on_folder(Path("/data/case001"), fast=True)
-        >>> print(result.prediction_path)
-        /data/case001/results/prediction.nii.gz
+    This is the standard execution path for local development.
     """
     start_time = time.time()
 
-    # Validate inputs
-    _dwi_path, _adc_path, flair_path = validate_input_folder(input_dir)
-
     # Check GPU if requested
     if gpu:
         ensure_gpu_available_if_requested(gpu)
 
-    # Set up output directory
-    if output_dir is None:
-        output_dir = input_dir
-
     # Build command arguments
     command: list[str] = [
         "--dwi_file_name",
@@ -168,6 +162,8 @@ def run_deepisles_on_folder(
         output_dir.resolve(): "/output",
     }
 
+    logger.info("Running DeepISLES via Docker: input=%s, fast=%s, gpu=%s", input_dir, fast, gpu)
+
     # Run the container
     docker_result = run_container(
         DEEPISLES_IMAGE,
@@ -194,3 +190,114 @@ def run_deepisles_on_folder(
         docker_result=docker_result,
         elapsed_seconds=elapsed,
     )
+
+
+def _run_via_direct_invocation(
+    input_dir: Path,
+    output_dir: Path,
+    *,
+    flair_path: Path | None,
+    fast: bool,
+) -> DeepISLESResult:
+    """
+    Run DeepISLES via direct Python invocation.
+
+    This execution path is used on HF Spaces where Docker-in-Docker
+    is not available. The container is based on isleschallenge/deepisles
+    so all dependencies are pre-installed.
+    """
+    from stroke_deepisles_demo.inference.direct import run_deepisles_direct
+
+    dwi_path = input_dir / "dwi.nii.gz"
+    adc_path = input_dir / "adc.nii.gz"
+
+    logger.info(
+        "Running DeepISLES via direct invocation: input=%s, fast=%s",
+        input_dir,
+        fast,
+    )
+
+    result = run_deepisles_direct(
+        dwi_path=dwi_path,
+        adc_path=adc_path,
+        output_dir=output_dir,
+        flair_path=flair_path,
+        fast=fast,
+    )
+
+    return DeepISLESResult(
+        prediction_path=result.prediction_path,
+        docker_result=None,  # No Docker result for direct invocation
+        elapsed_seconds=result.elapsed_seconds,
+    )
+
+
+def run_deepisles_on_folder(
+    input_dir: Path,
+    *,
+    output_dir: Path | None = None,
+    fast: bool = True,
+    gpu: bool = True,
+    timeout: float | None = 1800,  # 30 minutes default
+) -> DeepISLESResult:
+    """
+    Run DeepISLES stroke segmentation on a folder of NIfTI files.
+
+    This function automatically selects the execution method based on
+    the runtime environment:
+    - Docker invocation: Used for local development
+    - Direct invocation: Used on HF Spaces (Docker-in-Docker not available)
+
+    Args:
+        input_dir: Directory containing dwi.nii.gz, adc.nii.gz, [flair.nii.gz]
+        output_dir: Where to write results (default: input_dir/results)
+        fast: If True, use single-model mode (faster, slightly less accurate)
+        gpu: If True, use GPU acceleration (only affects Docker mode)
+        timeout: Maximum seconds to wait for inference (only affects Docker mode)
+
+    Returns:
+        DeepISLESResult with path to prediction mask
+
+    Raises:
+        DockerNotAvailableError: If Docker is not available (Docker mode only)
+        DockerGPUNotAvailableError: If GPU requested but not available (Docker mode only)
+        MissingInputError: If required input files are missing
+        DeepISLESError: If inference fails (non-zero exit, missing output)
+
+    Example:
+        >>> result = run_deepisles_on_folder(Path("/data/case001"), fast=True)
+        >>> print(result.prediction_path)
+        /data/case001/results/prediction.nii.gz
+    """
+    # Validate inputs (validation ensures dwi/adc exist; we only need flair_path)
+    _, _, flair_path = validate_input_folder(input_dir)
+
+    # Set up output directory
+    if output_dir is None:
+        output_dir = input_dir
+
+    # Check if we should use direct invocation
+    settings = get_settings()
+    use_direct = settings.use_direct_invocation
+
+    if use_direct:
+        logger.info(
+            "Using direct DeepISLES invocation (HF Spaces mode: %s)",
+            settings.is_hf_spaces,
+        )
+        return _run_via_direct_invocation(
+            input_dir=input_dir,
+            output_dir=output_dir,
+            flair_path=flair_path,
+            fast=fast,
+        )
+    else:
+        logger.info("Using Docker-based DeepISLES invocation")
+        return _run_via_docker(
+            input_dir=input_dir,
+            output_dir=output_dir,
+            flair_path=flair_path,
+            fast=fast,
+            gpu=gpu,
+            timeout=timeout,
+        )

src/stroke_deepisles_demo/inference/direct.py

@@ -0,0 +1,202 @@
+"""Direct DeepISLES invocation without Docker.
+
+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.
+
+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.
+
+See:
+    - https://github.com/ezequieldlrosa/DeepIsles
+    - docs/specs/07-hf-spaces-deployment.md
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+
+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__)
+
+# Paths where DeepISLES source might be located in the Docker image
+DEEPISLES_SEARCH_PATHS = [
+    "/app",
+    "/DeepIsles",
+    "/opt/deepisles",
+    "/home/user/DeepIsles",
+]
+
+
+@dataclass(frozen=True)
+class DirectInvocationResult:
+    """Result of direct DeepISLES invocation."""
+
+    prediction_path: Path
+    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
+    """
+    for path in DEEPISLES_SEARCH_PATHS:
+        if Path(path).exists():
+            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.debug("Found DeepISLES at %s", path)
+                return path
+            except ImportError:
+                continue
+
+    raise DeepISLESError(
+        "DeepISLES modules not found. Direct invocation requires running "
+        "inside the DeepISLES Docker image. Searched paths: "
+        f"{DEEPISLES_SEARCH_PATHS}"
+    )
+
+
+def validate_input_files(
+    dwi_path: Path,
+    adc_path: Path,
+    flair_path: Path | None = None,
+) -> None:
+    """
+    Validate that input files exist.
+
+    Args:
+        dwi_path: Path to DWI NIfTI file
+        adc_path: Path to ADC NIfTI file
+        flair_path: Optional path to FLAIR NIfTI file
+
+    Raises:
+        MissingInputError: If required files are missing
+    """
+    if not dwi_path.exists():
+        raise MissingInputError(f"DWI file not found: {dwi_path}")
+    if not adc_path.exists():
+        raise MissingInputError(f"ADC file not found: {adc_path}")
+    if flair_path is not None and not flair_path.exists():
+        raise MissingInputError(f"FLAIR file not found: {flair_path}")
+
+
+def run_deepisles_direct(
+    dwi_path: Path,
+    adc_path: Path,
+    output_dir: Path,
+    *,
+    flair_path: Path | None = None,
+    fast: bool = True,
+    skull_strip: bool = False,
+    parallelize: bool = True,
+    save_team_outputs: bool = False,
+    results_mni: bool = False,
+) -> DirectInvocationResult:
+    """
+    Run DeepISLES segmentation via direct Python invocation.
+
+    This function calls the DeepISLES IslesEnsemble.predict_ensemble() method
+    directly, bypassing Docker. It's used when running inside the DeepISLES
+    container on HF Spaces.
+
+    Args:
+        dwi_path: Path to DWI NIfTI file (b=1000)
+        adc_path: Path to ADC NIfTI file
+        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
+
+    Returns:
+        DirectInvocationResult with path to prediction mask
+
+    Raises:
+        DeepISLESError: If invocation fails
+        MissingInputError: If required input files are missing
+
+    Example:
+        >>> result = run_deepisles_direct(
+        ...     dwi_path=Path("/data/dwi.nii.gz"),
+        ...     adc_path=Path("/data/adc.nii.gz"),
+        ...     output_dir=Path("/data/output"),
+        ...     fast=True
+        ... )
+        >>> print(result.prediction_path)
+    """
+    start_time = time.time()
+
+    # 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",
+        dwi_path,
+        adc_path,
+        flair_path,
+        fast,
+    )
+
+    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,
+        )
+    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)
+    prediction_path = find_prediction_mask(output_dir)
+
+    elapsed = time.time() - start_time
+    logger.info("DeepISLES direct invocation completed in %.2fs", elapsed)
+
+    return DirectInvocationResult(
+        prediction_path=prediction_path,
+        elapsed_seconds=elapsed,
+    )

src/stroke_deepisles_demo/metrics.py

@@ -101,21 +101,19 @@ def compute_volume_ml(
     Returns:
         Volume in milliliters (mL)
     """
+    # Resolve data and voxel sizes
+    data: NDArray[np.float64]
+    voxel_dims: tuple[float, float, float]
+
     if isinstance(mask, Path):
         data, loaded_zooms = load_nifti_as_array(mask)
-        if voxel_size_mm is None:
-            voxel_size_mm = loaded_zooms
+        voxel_dims = voxel_size_mm if voxel_size_mm is not None else loaded_zooms
     else:
         data = mask
-        if voxel_size_mm is None:
-            # Default to 1mm isotropic if not provided for array
-            voxel_size_mm = (1.0, 1.0, 1.0)
-
-    # Ensure voxel_size_mm is not None for type checker
-    assert voxel_size_mm is not None
+        # Default to 1mm isotropic if not provided for array
+        voxel_dims = voxel_size_mm if voxel_size_mm is not None else (1.0, 1.0, 1.0)
 
     volume_voxels = np.sum(data > 0)
-    # Use math.prod for better type compatibility
-    voxel_vol_mm3 = math.prod(voxel_size_mm)
+    voxel_vol_mm3 = math.prod(voxel_dims)
 
     return float(volume_voxels * voxel_vol_mm3 / 1000.0)  # mm3 -> mL

src/stroke_deepisles_demo/pipeline.py

@@ -129,8 +129,8 @@ def run_pipeline_on_case(
     if compute_dice and ground_truth and ground_truth.exists():
         try:
             dice_score = metrics.compute_dice(inference_result.prediction_path, ground_truth)
-        except Exception as e:
-            logger.warning("Failed to compute Dice score for %s: %s", resolved_case_id, e)
+        except Exception:
+            logger.warning("Failed to compute Dice score for %s", resolved_case_id, exc_info=True)
 
     # 5. Cleanup (Optional)
     if cleanup_staging:

src/stroke_deepisles_demo/ui/app.py

@@ -113,13 +113,15 @@ def create_app() -> gr.Blocks:
     ) as demo:
         # Header
         gr.Markdown("""
-        # 🧠 Stroke Lesion Segmentation Demo
+        # Stroke Lesion Segmentation Demo
 
         This demo runs [DeepISLES](https://github.com/ezequieldlrosa/DeepIsles)
         stroke segmentation on cases from
         [ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite).
 
-        **Note:** The pipeline runs inside a Docker container. First run might be slow (pulling image).
+        **Model:** SEALS (ISLES'22 winner) - Fast, accurate ischemic stroke lesion segmentation.
+
+        **Note:** First run may take a moment to load models and data.
         """)
 
         with gr.Row():
@@ -167,4 +169,16 @@ def get_demo() -> gr.Blocks:
 
 
 if __name__ == "__main__":
-    get_demo().launch(theme=gr.themes.Soft(), css="footer {visibility: hidden}")
+    from stroke_deepisles_demo.core.config import get_settings
+    from stroke_deepisles_demo.core.logging import setup_logging
+
+    settings = get_settings()
+    setup_logging(settings.log_level, format_style=settings.log_format)
+
+    get_demo().launch(
+        server_name=settings.gradio_server_name,
+        server_port=settings.gradio_server_port,
+        share=settings.gradio_share,
+        theme=gr.themes.Soft(),
+        css="footer {visibility: hidden}",
+    )

src/stroke_deepisles_demo/ui/components.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import gradio as gr
 
+from stroke_deepisles_demo.core.config import get_settings
 from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.data import list_case_ids
 
@@ -16,16 +17,27 @@ def create_case_selector() -> gr.Dropdown:
 
     Returns:
         Configured gr.Dropdown component
+
+    Raises:
+        RuntimeError: If case IDs cannot be loaded (no silent fallback)
     """
     try:
         case_ids = list_case_ids()
-    except Exception:
-        logger.warning("Failed to load case IDs, using fallback", exc_info=True)
-        case_ids = ["Error loading cases"]
+    except FileNotFoundError as e:
+        # Data directory not found - fail loudly with helpful message
+        logger.error("Data directory not found: %s", e)
+        raise RuntimeError("ISLES24 data not found. Please run: uv run stroke-demo download") from e
+    except Exception as e:
+        # Unexpected error - fail loudly, don't mask with fake dropdown option
+        logger.exception("Failed to load case IDs")
+        raise RuntimeError(f"Failed to load case IDs: {e}") from e
+
+    if not case_ids:
+        raise RuntimeError("No cases found in dataset. Please verify data directory structure.")
 
     return gr.Dropdown(
         choices=case_ids,
-        value=case_ids[0] if case_ids else None,
+        value=case_ids[0],
         label="Select Case",
         info="Choose a case from ISLES24-MR-Lite",
         filterable=True,
@@ -65,9 +77,11 @@ def create_settings_accordion() -> dict[str, gr.components.Component]:
     Returns:
         Dictionary of setting name -> gr.Component
     """
+    settings = get_settings()
+
     with gr.Accordion("Advanced Settings", open=False):
         fast_mode = gr.Checkbox(
-            value=True,
+            value=settings.deepisles_fast_mode,
             label="Fast Mode (SEALS)",
             info="Run SEALS only (ISLES'22 winner, requires DWI+ADC). Disable for full ensemble (requires FLAIR).",
         )

src/stroke_deepisles_demo/ui/viewer.py

@@ -1,8 +1,19 @@
-"""Neuroimaging visualization for Gradio."""
+"""Neuroimaging visualization for Gradio.
+
+This module provides visualization components for neuroimaging data:
+- NiiVue WebGL-based 3D viewer
+- Matplotlib-based 2D slice comparisons
+
+See:
+    - https://github.com/niivue/niivue (NiiVue v0.65.0)
+    - docs/specs/07-hf-spaces-deployment.md
+"""
 
 from __future__ import annotations
 
 import base64
+import json
+import uuid
 from typing import TYPE_CHECKING
 
 import matplotlib.pyplot as plt
@@ -15,6 +26,10 @@ if TYPE_CHECKING:
 
     from matplotlib.figure import Figure
 
+# NiiVue version - updated to latest stable (Dec 2025)
+NIIVUE_VERSION = "0.65.0"
+NIIVUE_CDN_URL = f"https://unpkg.com/@niivue/niivue@{NIIVUE_VERSION}/dist/index.js"
+
 
 def nifti_to_data_url(nifti_path: Path) -> str:
     """
@@ -268,57 +283,103 @@ def create_niivue_html(
     """
     Create HTML/JS for NiiVue viewer.
 
+    This function generates an HTML snippet with embedded JavaScript for
+    NiiVue WebGL-based neuroimaging visualization. Each invocation creates
+    a unique canvas ID to avoid conflicts when multiple viewers are rendered.
+
     Args:
-        volume_url: URL to volume NIfTI file
-        mask_url: Optional URL to mask NIfTI file
+        volume_url: Data URL or URL to volume NIfTI file
+        mask_url: Optional data URL or URL to mask NIfTI file
         height: Viewer height in pixels
 
     Returns:
         HTML string with embedded NiiVue viewer
+
+    Note:
+        The JavaScript uses dynamic import() which works in modern browsers
+        and Gradio's HTML component. Each viewer gets a unique ID to support
+        multiple simultaneous viewers.
     """
+    # Generate unique ID for this viewer instance
+    viewer_id = uuid.uuid4().hex[:8]
+    canvas_id = f"niivue-canvas-{viewer_id}"
+    container_id = f"niivue-container-{viewer_id}"
+
+    # Safely serialize URLs for JavaScript (prevents XSS)
+    volume_url_js = json.dumps(volume_url)
+
+    # Build mask volume configuration if provided
     mask_js = ""
     if mask_url:
+        mask_url_js = json.dumps(mask_url)
         mask_js = f"""
-        volumes.push({{
-            url: '{mask_url}',
-            colorMap: 'red',
-            opacity: 0.5
-        }});
-        """
-
+                volumes.push({{
+                    url: {mask_url_js},
+                    colorMap: 'red',
+                    opacity: 0.5
+                }});"""
+
+    # JavaScript that initializes NiiVue
+    # Using an IIFE pattern that works better in Gradio's HTML component
     return f"""
-    <div style="width:100%; height:{height}px; background:#000; border-radius:8px; position: relative;">
-        <canvas id="niivue-canvas" style="width:100%; height:100%;"></canvas>
+    <div id="{container_id}" style="width:100%; height:{height}px; background:#000; border-radius:8px; position:relative;">
+        <canvas id="{canvas_id}" style="width:100%; height:100%;"></canvas>
     </div>
     <script type="module">
-        const niivueModule = await import('https://unpkg.com/@niivue/niivue@0.57.0/dist/index.js');
-        const Niivue = niivueModule.Niivue;
-
-        const nv = new Niivue({{
-            logging: false,
-            show3Dcrosshair: true,
-            textHeight: 0.04,
-            backColor: [0, 0, 0, 1]
-        }});
-
-        await nv.attachTo('niivue-canvas');
-
-        const volumes = [{{
-            url: '{volume_url}',
-            name: 'input.nii.gz'
-        }}];
-        {mask_js}
-
-        await nv.loadVolumes(volumes);
-
-        // Multiplanar + 3D view
-        nv.setSliceType(nv.sliceTypeMultiplanar);
-        // Check if setMultiplanarLayout exists (added in newer versions, 0.57 has it)
-        if (nv.setMultiplanarLayout) {{
-            nv.setMultiplanarLayout(2);
-        }}
-        nv.opts.show3Dcrosshair = true;
-        nv.setRenderAzimuthElevation(120, 10);
-        nv.drawScene();
+        // NiiVue initialization for viewer {viewer_id}
+        (async function() {{
+            try {{
+                // Check if browser supports WebGL2
+                const testCanvas = document.createElement('canvas');
+                const gl = testCanvas.getContext('webgl2');
+                if (!gl) {{
+                    document.getElementById('{container_id}').innerHTML =
+                        '<div style="color:#fff;padding:20px;text-align:center;">' +
+                        'WebGL2 not supported. Please use a modern browser.</div>';
+                    return;
+                }}
+
+                // Dynamically import NiiVue
+                const niivueModule = await import('{NIIVUE_CDN_URL}');
+                const Niivue = niivueModule.Niivue;
+
+                // Initialize NiiVue with options
+                const nv = new Niivue({{
+                    logging: false,
+                    show3Dcrosshair: true,
+                    textHeight: 0.04,
+                    backColor: [0, 0, 0, 1],
+                    crosshairColor: [0.2, 0.8, 0.2, 1]
+                }});
+
+                // Attach to canvas
+                await nv.attachToCanvas(document.getElementById('{canvas_id}'));
+
+                // Prepare volumes
+                const volumes = [{{
+                    url: {volume_url_js},
+                    name: 'input.nii.gz'
+                }}];{mask_js}
+
+                // Load volumes
+                await nv.loadVolumes(volumes);
+
+                // Configure view: multiplanar + 3D
+                nv.setSliceType(nv.sliceTypeMultiplanar);
+                if (typeof nv.setMultiplanarLayout === 'function') {{
+                    nv.setMultiplanarLayout(2);
+                }}
+                nv.opts.show3Dcrosshair = true;
+                nv.setRenderAzimuthElevation(120, 10);
+                nv.drawScene();
+
+                console.log('NiiVue viewer {viewer_id} initialized successfully');
+            }} catch (error) {{
+                console.error('NiiVue initialization error:', error);
+                document.getElementById('{container_id}').innerHTML =
+                    '<div style="color:#fff;padding:20px;text-align:center;">' +
+                    'Error loading viewer: ' + error.message + '</div>';
+            }}
+        }})();
     </script>
     """

tests/core/test_config.py

@@ -8,7 +8,12 @@ from typing import TYPE_CHECKING
 if TYPE_CHECKING:
     import pytest
 
-from stroke_deepisles_demo.core.config import Settings, reload_settings
+from stroke_deepisles_demo.core.config import (
+    Settings,
+    is_deepisles_direct_available,
+    is_running_in_hf_spaces,
+    reload_settings,
+)
 
 
 class TestSettings:
@@ -59,3 +64,72 @@ class TestSettings:
         assert config.settings.log_level == "ERROR"
         # Ensure it's the same object instance reference in the module
         assert config.settings is new_settings
+
+
+class TestHFSpacesDetection:
+    """Tests for HF Spaces environment detection."""
+
+    def test_not_in_hf_spaces_by_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Returns False when not in HF Spaces."""
+        # Clear any HF Spaces env vars
+        monkeypatch.delenv("HF_SPACES", raising=False)
+        monkeypatch.delenv("SPACE_ID", raising=False)
+        assert is_running_in_hf_spaces() is False
+
+    def test_detects_hf_spaces_env_var(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detects HF Spaces via HF_SPACES env var."""
+        monkeypatch.setenv("HF_SPACES", "1")
+        assert is_running_in_hf_spaces() is True
+
+    def test_detects_space_id_env_var(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detects HF Spaces via SPACE_ID env var."""
+        monkeypatch.delenv("HF_SPACES", raising=False)
+        monkeypatch.setenv("SPACE_ID", "username/space-name")
+        assert is_running_in_hf_spaces() is True
+
+
+class TestDirectInvocationDetection:
+    """Tests for direct DeepISLES invocation detection."""
+
+    def test_not_available_by_default(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Returns False when DeepISLES modules not available."""
+        # Clear env var
+        monkeypatch.delenv("DEEPISLES_DIRECT_INVOCATION", raising=False)
+        # In test environment, DeepISLES won't be importable
+        assert is_deepisles_direct_available() is False
+
+    def test_detects_env_var(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Detects direct invocation via env var."""
+        monkeypatch.setenv("DEEPISLES_DIRECT_INVOCATION", "1")
+        assert is_deepisles_direct_available() is True
+
+
+class TestSettingsComputedFields:
+    """Tests for Settings computed fields."""
+
+    def test_is_hf_spaces_computed(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Settings.is_hf_spaces reflects environment."""
+        monkeypatch.delenv("HF_SPACES", raising=False)
+        monkeypatch.delenv("SPACE_ID", raising=False)
+        settings = Settings()
+        assert settings.is_hf_spaces is False
+
+        monkeypatch.setenv("HF_SPACES", "1")
+        # Need new instance to pick up env change
+        settings2 = Settings()
+        assert settings2.is_hf_spaces is True
+
+    def test_use_direct_invocation_computed(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Settings.use_direct_invocation reflects environment."""
+        monkeypatch.delenv("HF_SPACES", raising=False)
+        monkeypatch.delenv("SPACE_ID", raising=False)
+        monkeypatch.delenv("DEEPISLES_DIRECT_INVOCATION", raising=False)
+
+        settings = Settings()
+        # Not in HF Spaces and DeepISLES not directly available
+        assert settings.use_direct_invocation is False
+
+        # Enable direct invocation
+        monkeypatch.setenv("DEEPISLES_DIRECT_INVOCATION", "1")
+        settings2 = Settings()
+        assert settings2.use_direct_invocation is True

tests/inference/test_direct.py

@@ -0,0 +1,163 @@
+"""Tests for direct DeepISLES invocation module."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import pytest
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
+from stroke_deepisles_demo.inference.deepisles import find_prediction_mask
+from stroke_deepisles_demo.inference.direct import validate_input_files
+
+
+class TestValidateInputFiles:
+    """Tests for validate_input_files."""
+
+    def test_valid_files(self, tmp_path: Path) -> None:
+        """Passes validation when required files exist."""
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        dwi.touch()
+        adc.touch()
+
+        # Should not raise
+        validate_input_files(dwi, adc)
+
+    def test_valid_files_with_flair(self, tmp_path: Path) -> None:
+        """Passes validation when all files including FLAIR exist."""
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        flair = tmp_path / "flair.nii.gz"
+        dwi.touch()
+        adc.touch()
+        flair.touch()
+
+        # Should not raise
+        validate_input_files(dwi, adc, flair)
+
+    def test_missing_dwi(self, tmp_path: Path) -> None:
+        """Raises MissingInputError when DWI file missing."""
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        adc.touch()
+
+        with pytest.raises(MissingInputError, match="DWI file not found"):
+            validate_input_files(dwi, adc)
+
+    def test_missing_adc(self, tmp_path: Path) -> None:
+        """Raises MissingInputError when ADC file missing."""
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        dwi.touch()
+
+        with pytest.raises(MissingInputError, match="ADC file not found"):
+            validate_input_files(dwi, adc)
+
+    def test_missing_flair_when_specified(self, tmp_path: Path) -> None:
+        """Raises MissingInputError when FLAIR specified but missing."""
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        flair = tmp_path / "flair.nii.gz"
+        dwi.touch()
+        adc.touch()
+
+        with pytest.raises(MissingInputError, match="FLAIR file not found"):
+            validate_input_files(dwi, adc, flair)
+
+
+class TestFindPredictionMask:
+    """Tests for find_prediction_mask (shared function in deepisles module)."""
+
+    def test_finds_prediction_in_results_dir(self, tmp_path: Path) -> None:
+        """Finds prediction.nii.gz in results subdirectory."""
+        results = tmp_path / "results"
+        results.mkdir()
+        pred = results / "prediction.nii.gz"
+        pred.touch()
+
+        found = find_prediction_mask(tmp_path)
+        assert found == pred
+
+    def test_finds_alternative_names(self, tmp_path: Path) -> None:
+        """Finds prediction with alternative naming patterns."""
+        results = tmp_path / "results"
+        results.mkdir()
+        pred = results / "lesion_mask.nii.gz"
+        pred.touch()
+
+        found = find_prediction_mask(tmp_path)
+        assert found == pred
+
+    def test_finds_in_output_dir_directly(self, tmp_path: Path) -> None:
+        """Finds prediction directly in output directory."""
+        pred = tmp_path / "prediction.nii.gz"
+        pred.touch()
+
+        found = find_prediction_mask(tmp_path)
+        assert found == pred
+
+    def test_finds_any_nifti(self, tmp_path: Path) -> None:
+        """Falls back to any NIfTI file if standard names not found."""
+        results = tmp_path / "results"
+        results.mkdir()
+        pred = results / "custom_output.nii.gz"
+        pred.touch()
+
+        found = find_prediction_mask(tmp_path)
+        assert found == pred
+
+    def test_excludes_input_files(self, tmp_path: Path) -> None:
+        """Excludes DWI/ADC/FLAIR from fallback search."""
+        # Only input files, no prediction
+        (tmp_path / "dwi.nii.gz").touch()
+        (tmp_path / "adc.nii.gz").touch()
+
+        with pytest.raises(DeepISLESError, match="No prediction mask found"):
+            find_prediction_mask(tmp_path)
+
+    def test_no_mask_found(self, tmp_path: Path) -> None:
+        """Raises DeepISLESError when no prediction mask found."""
+        with pytest.raises(DeepISLESError, match="No prediction mask found"):
+            find_prediction_mask(tmp_path)
+
+
+class TestRunDeepISLESDirect:
+    """Tests for run_deepisles_direct function.
+
+    Note: These tests don't actually run DeepISLES (which requires the
+    DeepISLES Docker image). They test the wrapper logic only.
+    """
+
+    def test_missing_input_raises(self, tmp_path: Path) -> None:
+        """Raises MissingInputError for missing input files."""
+        from stroke_deepisles_demo.inference.direct import run_deepisles_direct
+
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        output = tmp_path / "output"
+
+        with pytest.raises(MissingInputError):
+            run_deepisles_direct(dwi, adc, output)
+
+    def test_deepisles_not_available_raises(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Raises DeepISLESError when DeepISLES not available."""
+        from stroke_deepisles_demo.inference.direct import run_deepisles_direct
+
+        # Create input files
+        dwi = tmp_path / "dwi.nii.gz"
+        adc = tmp_path / "adc.nii.gz"
+        output = tmp_path / "output"
+        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"):
+            run_deepisles_direct(dwi, adc, output)

uv.lock

@@ -1541,83 +1541,26 @@ wheels = [
 
 [[package]]
 name = "numpy"
-version = "2.3.5"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/76/65/21b3bc86aac7b8f2862db1e808f1ea22b028e30a225a34a5ede9bf8678f2/numpy-2.3.5.tar.gz", hash = "sha256:784db1dcdab56bf0517743e746dfb0f885fc68d948aba86eeec2cba234bdf1c0", size = 20584950, upload-time = "2025-11-16T22:52:42.067Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/43/77/84dd1d2e34d7e2792a236ba180b5e8fcc1e3e414e761ce0253f63d7f572e/numpy-2.3.5-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:de5672f4a7b200c15a4127042170a694d4df43c992948f5e1af57f0174beed10", size = 17034641, upload-time = "2025-11-16T22:49:19.336Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/ea/25e26fa5837106cde46ae7d0b667e20f69cbbc0efd64cba8221411ab26ae/numpy-2.3.5-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:acfd89508504a19ed06ef963ad544ec6664518c863436306153e13e94605c218", size = 12528324, upload-time = "2025-11-16T22:49:22.582Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/1a/e85f0eea4cf03d6a0228f5c0256b53f2df4bc794706e7df019fc622e47f1/numpy-2.3.5-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:ffe22d2b05504f786c867c8395de703937f934272eb67586817b46188b4ded6d", size = 5356872, upload-time = "2025-11-16T22:49:25.408Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/bb/35ef04afd567f4c989c2060cde39211e4ac5357155c1833bcd1166055c61/numpy-2.3.5-cp311-cp311-macosx_14_0_x86_64.whl", hash = "sha256:872a5cf366aec6bb1147336480fef14c9164b154aeb6542327de4970282cd2f5", size = 6893148, upload-time = "2025-11-16T22:49:27.549Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/2b/05bbeb06e2dff5eab512dfc678b1cc5ee94d8ac5956a0885c64b6b26252b/numpy-2.3.5-cp311-cp311-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:3095bdb8dd297e5920b010e96134ed91d852d81d490e787beca7e35ae1d89cf7", size = 14557282, upload-time = "2025-11-16T22:49:30.964Z" },
-    { url = "https://files.pythonhosted.org/packages/65/fb/2b23769462b34398d9326081fad5655198fcf18966fcb1f1e49db44fbf31/numpy-2.3.5-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:8cba086a43d54ca804ce711b2a940b16e452807acebe7852ff327f1ecd49b0d4", size = 16897903, upload-time = "2025-11-16T22:49:34.191Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/14/085f4cf05fc3f1e8aa95e85404e984ffca9b2275a5dc2b1aae18a67538b8/numpy-2.3.5-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:6cf9b429b21df6b99f4dee7a1218b8b7ffbbe7df8764dc0bd60ce8a0708fed1e", size = 16341672, upload-time = "2025-11-16T22:49:37.2Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/3b/1f73994904142b2aa290449b3bb99772477b5fd94d787093e4f24f5af763/numpy-2.3.5-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:396084a36abdb603546b119d96528c2f6263921c50df3c8fd7cb28873a237748", size = 18838896, upload-time = "2025-11-16T22:49:39.727Z" },
-    { url = "https://files.pythonhosted.org/packages/cd/b9/cf6649b2124f288309ffc353070792caf42ad69047dcc60da85ee85fea58/numpy-2.3.5-cp311-cp311-win32.whl", hash = "sha256:b0c7088a73aef3d687c4deef8452a3ac7c1be4e29ed8bf3b366c8111128ac60c", size = 6563608, upload-time = "2025-11-16T22:49:42.079Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/44/9fe81ae1dcc29c531843852e2874080dc441338574ccc4306b39e2ff6e59/numpy-2.3.5-cp311-cp311-win_amd64.whl", hash = "sha256:a414504bef8945eae5f2d7cb7be2d4af77c5d1cb5e20b296c2c25b61dff2900c", size = 13078442, upload-time = "2025-11-16T22:49:43.99Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/a7/f99a41553d2da82a20a2f22e93c94f928e4490bb447c9ff3c4ff230581d3/numpy-2.3.5-cp311-cp311-win_arm64.whl", hash = "sha256:0cd00b7b36e35398fa2d16af7b907b65304ef8bb4817a550e06e5012929830fa", size = 10458555, upload-time = "2025-11-16T22:49:47.092Z" },
-    { url = "https://files.pythonhosted.org/packages/44/37/e669fe6cbb2b96c62f6bbedc6a81c0f3b7362f6a59230b23caa673a85721/numpy-2.3.5-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:74ae7b798248fe62021dbf3c914245ad45d1a6b0cb4a29ecb4b31d0bfbc4cc3e", size = 16733873, upload-time = "2025-11-16T22:49:49.84Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/65/df0db6c097892c9380851ab9e44b52d4f7ba576b833996e0080181c0c439/numpy-2.3.5-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ee3888d9ff7c14604052b2ca5535a30216aa0a58e948cdd3eeb8d3415f638769", size = 12259838, upload-time = "2025-11-16T22:49:52.863Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/e1/1ee06e70eb2136797abe847d386e7c0e830b67ad1d43f364dd04fa50d338/numpy-2.3.5-cp312-cp312-macosx_14_0_arm64.whl", hash = "sha256:612a95a17655e213502f60cfb9bf9408efdc9eb1d5f50535cc6eb365d11b42b5", size = 5088378, upload-time = "2025-11-16T22:49:55.055Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/9c/1ca85fb86708724275103b81ec4cf1ac1d08f465368acfc8da7ab545bdae/numpy-2.3.5-cp312-cp312-macosx_14_0_x86_64.whl", hash = "sha256:3101e5177d114a593d79dd79658650fe28b5a0d8abeb8ce6f437c0e6df5be1a4", size = 6628559, upload-time = "2025-11-16T22:49:57.371Z" },
-    { url = "https://files.pythonhosted.org/packages/74/78/fcd41e5a0ce4f3f7b003da85825acddae6d7ecb60cf25194741b036ca7d6/numpy-2.3.5-cp312-cp312-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8b973c57ff8e184109db042c842423ff4f60446239bd585a5131cc47f06f789d", size = 14250702, upload-time = "2025-11-16T22:49:59.632Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/23/2a1b231b8ff672b4c450dac27164a8b2ca7d9b7144f9c02d2396518352eb/numpy-2.3.5-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0d8163f43acde9a73c2a33605353a4f1bc4798745a8b1d73183b28e5b435ae28", size = 16606086, upload-time = "2025-11-16T22:50:02.127Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/c5/5ad26fbfbe2012e190cc7d5003e4d874b88bb18861d0829edc140a713021/numpy-2.3.5-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:51c1e14eb1e154ebd80e860722f9e6ed6ec89714ad2db2d3aa33c31d7c12179b", size = 16025985, upload-time = "2025-11-16T22:50:04.536Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/fa/dd48e225c46c819288148d9d060b047fd2a6fb1eb37eae25112ee4cb4453/numpy-2.3.5-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:b46b4ec24f7293f23adcd2d146960559aaf8020213de8ad1909dba6c013bf89c", size = 18542976, upload-time = "2025-11-16T22:50:07.557Z" },
-    { url = "https://files.pythonhosted.org/packages/05/79/ccbd23a75862d95af03d28b5c6901a1b7da4803181513d52f3b86ed9446e/numpy-2.3.5-cp312-cp312-win32.whl", hash = "sha256:3997b5b3c9a771e157f9aae01dd579ee35ad7109be18db0e85dbdbe1de06e952", size = 6285274, upload-time = "2025-11-16T22:50:10.746Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/57/8aeaf160312f7f489dea47ab61e430b5cb051f59a98ae68b7133ce8fa06a/numpy-2.3.5-cp312-cp312-win_amd64.whl", hash = "sha256:86945f2ee6d10cdfd67bcb4069c1662dd711f7e2a4343db5cecec06b87cf31aa", size = 12782922, upload-time = "2025-11-16T22:50:12.811Z" },
-    { url = "https://files.pythonhosted.org/packages/78/a6/aae5cc2ca78c45e64b9ef22f089141d661516856cf7c8a54ba434576900d/numpy-2.3.5-cp312-cp312-win_arm64.whl", hash = "sha256:f28620fe26bee16243be2b7b874da327312240a7cdc38b769a697578d2100013", size = 10194667, upload-time = "2025-11-16T22:50:16.16Z" },
-    { url = "https://files.pythonhosted.org/packages/db/69/9cde09f36da4b5a505341180a3f2e6fadc352fd4d2b7096ce9778db83f1a/numpy-2.3.5-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:d0f23b44f57077c1ede8c5f26b30f706498b4862d3ff0a7298b8411dd2f043ff", size = 16728251, upload-time = "2025-11-16T22:50:19.013Z" },
-    { url = "https://files.pythonhosted.org/packages/79/fb/f505c95ceddd7027347b067689db71ca80bd5ecc926f913f1a23e65cf09b/numpy-2.3.5-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:aa5bc7c5d59d831d9773d1170acac7893ce3a5e130540605770ade83280e7188", size = 12254652, upload-time = "2025-11-16T22:50:21.487Z" },
-    { url = "https://files.pythonhosted.org/packages/78/da/8c7738060ca9c31b30e9301ee0cf6c5ffdbf889d9593285a1cead337f9a5/numpy-2.3.5-cp313-cp313-macosx_14_0_arm64.whl", hash = "sha256:ccc933afd4d20aad3c00bcef049cb40049f7f196e0397f1109dba6fed63267b0", size = 5083172, upload-time = "2025-11-16T22:50:24.562Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/b4/ee5bb2537fb9430fd2ef30a616c3672b991a4129bb1c7dcc42aa0abbe5d7/numpy-2.3.5-cp313-cp313-macosx_14_0_x86_64.whl", hash = "sha256:afaffc4393205524af9dfa400fa250143a6c3bc646c08c9f5e25a9f4b4d6a903", size = 6622990, upload-time = "2025-11-16T22:50:26.47Z" },
-    { url = "https://files.pythonhosted.org/packages/95/03/dc0723a013c7d7c19de5ef29e932c3081df1c14ba582b8b86b5de9db7f0f/numpy-2.3.5-cp313-cp313-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9c75442b2209b8470d6d5d8b1c25714270686f14c749028d2199c54e29f20b4d", size = 14248902, upload-time = "2025-11-16T22:50:28.861Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/10/ca162f45a102738958dcec8023062dad0cbc17d1ab99d68c4e4a6c45fb2b/numpy-2.3.5-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:11e06aa0af8c0f05104d56450d6093ee639e15f24ecf62d417329d06e522e017", size = 16597430, upload-time = "2025-11-16T22:50:31.56Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/51/c1e29be863588db58175175f057286900b4b3327a1351e706d5e0f8dd679/numpy-2.3.5-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:ed89927b86296067b4f81f108a2271d8926467a8868e554eaf370fc27fa3ccaf", size = 16024551, upload-time = "2025-11-16T22:50:34.242Z" },
-    { url = "https://files.pythonhosted.org/packages/83/68/8236589d4dbb87253d28259d04d9b814ec0ecce7cb1c7fed29729f4c3a78/numpy-2.3.5-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:51c55fe3451421f3a6ef9a9c1439e82101c57a2c9eab9feb196a62b1a10b58ce", size = 18533275, upload-time = "2025-11-16T22:50:37.651Z" },
-    { url = "https://files.pythonhosted.org/packages/40/56/2932d75b6f13465239e3b7b7e511be27f1b8161ca2510854f0b6e521c395/numpy-2.3.5-cp313-cp313-win32.whl", hash = "sha256:1978155dd49972084bd6ef388d66ab70f0c323ddee6f693d539376498720fb7e", size = 6277637, upload-time = "2025-11-16T22:50:40.11Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/88/e2eaa6cffb115b85ed7c7c87775cb8bcf0816816bc98ca8dbfa2ee33fe6e/numpy-2.3.5-cp313-cp313-win_amd64.whl", hash = "sha256:00dc4e846108a382c5869e77c6ed514394bdeb3403461d25a829711041217d5b", size = 12779090, upload-time = "2025-11-16T22:50:42.503Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/88/3f41e13a44ebd4034ee17baa384acac29ba6a4fcc2aca95f6f08ca0447d1/numpy-2.3.5-cp313-cp313-win_arm64.whl", hash = "sha256:0472f11f6ec23a74a906a00b48a4dcf3849209696dff7c189714511268d103ae", size = 10194710, upload-time = "2025-11-16T22:50:44.971Z" },
-    { url = "https://files.pythonhosted.org/packages/13/cb/71744144e13389d577f867f745b7df2d8489463654a918eea2eeb166dfc9/numpy-2.3.5-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:414802f3b97f3c1eef41e530aaba3b3c1620649871d8cb38c6eaff034c2e16bd", size = 16827292, upload-time = "2025-11-16T22:50:47.715Z" },
-    { url = "https://files.pythonhosted.org/packages/71/80/ba9dc6f2a4398e7f42b708a7fdc841bb638d353be255655498edbf9a15a8/numpy-2.3.5-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:5ee6609ac3604fa7780e30a03e5e241a7956f8e2fcfe547d51e3afa5247ac47f", size = 12378897, upload-time = "2025-11-16T22:50:51.327Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/6d/db2151b9f64264bcceccd51741aa39b50150de9b602d98ecfe7e0c4bff39/numpy-2.3.5-cp313-cp313t-macosx_14_0_arm64.whl", hash = "sha256:86d835afea1eaa143012a2d7a3f45a3adce2d7adc8b4961f0b362214d800846a", size = 5207391, upload-time = "2025-11-16T22:50:54.542Z" },
-    { url = "https://files.pythonhosted.org/packages/80/ae/429bacace5ccad48a14c4ae5332f6aa8ab9f69524193511d60ccdfdc65fa/numpy-2.3.5-cp313-cp313t-macosx_14_0_x86_64.whl", hash = "sha256:30bc11310e8153ca664b14c5f1b73e94bd0503681fcf136a163de856f3a50139", size = 6721275, upload-time = "2025-11-16T22:50:56.794Z" },
-    { url = "https://files.pythonhosted.org/packages/74/5b/1919abf32d8722646a38cd527bc3771eb229a32724ee6ba340ead9b92249/numpy-2.3.5-cp313-cp313t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1062fde1dcf469571705945b0f221b73928f34a20c904ffb45db101907c3454e", size = 14306855, upload-time = "2025-11-16T22:50:59.208Z" },
-    { url = "https://files.pythonhosted.org/packages/a5/87/6831980559434973bebc30cd9c1f21e541a0f2b0c280d43d3afd909b66d0/numpy-2.3.5-cp313-cp313t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ce581db493ea1a96c0556360ede6607496e8bf9b3a8efa66e06477267bc831e9", size = 16657359, upload-time = "2025-11-16T22:51:01.991Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/91/c797f544491ee99fd00495f12ebb7802c440c1915811d72ac5b4479a3356/numpy-2.3.5-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:cc8920d2ec5fa99875b670bb86ddeb21e295cb07aa331810d9e486e0b969d946", size = 16093374, upload-time = "2025-11-16T22:51:05.291Z" },
-    { url = "https://files.pythonhosted.org/packages/74/a6/54da03253afcbe7a72785ec4da9c69fb7a17710141ff9ac5fcb2e32dbe64/numpy-2.3.5-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:9ee2197ef8c4f0dfe405d835f3b6a14f5fee7782b5de51ba06fb65fc9b36e9f1", size = 18594587, upload-time = "2025-11-16T22:51:08.585Z" },
-    { url = "https://files.pythonhosted.org/packages/80/e9/aff53abbdd41b0ecca94285f325aff42357c6b5abc482a3fcb4994290b18/numpy-2.3.5-cp313-cp313t-win32.whl", hash = "sha256:70b37199913c1bd300ff6e2693316c6f869c7ee16378faf10e4f5e3275b299c3", size = 6405940, upload-time = "2025-11-16T22:51:11.541Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/81/50613fec9d4de5480de18d4f8ef59ad7e344d497edbef3cfd80f24f98461/numpy-2.3.5-cp313-cp313t-win_amd64.whl", hash = "sha256:b501b5fa195cc9e24fe102f21ec0a44dffc231d2af79950b451e0d99cea02234", size = 12920341, upload-time = "2025-11-16T22:51:14.312Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/ab/08fd63b9a74303947f34f0bd7c5903b9c5532c2d287bead5bdf4c556c486/numpy-2.3.5-cp313-cp313t-win_arm64.whl", hash = "sha256:a80afd79f45f3c4a7d341f13acbe058d1ca8ac017c165d3fa0d3de6bc1a079d7", size = 10262507, upload-time = "2025-11-16T22:51:16.846Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/97/1a914559c19e32d6b2e233cf9a6a114e67c856d35b1d6babca571a3e880f/numpy-2.3.5-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:bf06bc2af43fa8d32d30fae16ad965663e966b1a3202ed407b84c989c3221e82", size = 16735706, upload-time = "2025-11-16T22:51:19.558Z" },
-    { url = "https://files.pythonhosted.org/packages/57/d4/51233b1c1b13ecd796311216ae417796b88b0616cfd8a33ae4536330748a/numpy-2.3.5-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:052e8c42e0c49d2575621c158934920524f6c5da05a1d3b9bab5d8e259e045f0", size = 12264507, upload-time = "2025-11-16T22:51:22.492Z" },
-    { url = "https://files.pythonhosted.org/packages/45/98/2fe46c5c2675b8306d0b4a3ec3494273e93e1226a490f766e84298576956/numpy-2.3.5-cp314-cp314-macosx_14_0_arm64.whl", hash = "sha256:1ed1ec893cff7040a02c8aa1c8611b94d395590d553f6b53629a4461dc7f7b63", size = 5093049, upload-time = "2025-11-16T22:51:25.171Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/0e/0698378989bb0ac5f1660c81c78ab1fe5476c1a521ca9ee9d0710ce54099/numpy-2.3.5-cp314-cp314-macosx_14_0_x86_64.whl", hash = "sha256:2dcd0808a421a482a080f89859a18beb0b3d1e905b81e617a188bd80422d62e9", size = 6626603, upload-time = "2025-11-16T22:51:27Z" },
-    { url = "https://files.pythonhosted.org/packages/5e/a6/9ca0eecc489640615642a6cbc0ca9e10df70df38c4d43f5a928ff18d8827/numpy-2.3.5-cp314-cp314-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:727fd05b57df37dc0bcf1a27767a3d9a78cbbc92822445f32cc3436ba797337b", size = 14262696, upload-time = "2025-11-16T22:51:29.402Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/f6/07ec185b90ec9d7217a00eeeed7383b73d7e709dae2a9a021b051542a708/numpy-2.3.5-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:fffe29a1ef00883599d1dc2c51aa2e5d80afe49523c261a74933df395c15c520", size = 16597350, upload-time = "2025-11-16T22:51:32.167Z" },
-    { url = "https://files.pythonhosted.org/packages/75/37/164071d1dde6a1a84c9b8e5b414fa127981bad47adf3a6b7e23917e52190/numpy-2.3.5-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:8f7f0e05112916223d3f438f293abf0727e1181b5983f413dfa2fefc4098245c", size = 16040190, upload-time = "2025-11-16T22:51:35.403Z" },
-    { url = "https://files.pythonhosted.org/packages/08/3c/f18b82a406b04859eb026d204e4e1773eb41c5be58410f41ffa511d114ae/numpy-2.3.5-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:2e2eb32ddb9ccb817d620ac1d8dae7c3f641c1e5f55f531a33e8ab97960a75b8", size = 18536749, upload-time = "2025-11-16T22:51:39.698Z" },
-    { url = "https://files.pythonhosted.org/packages/40/79/f82f572bf44cf0023a2fe8588768e23e1592585020d638999f15158609e1/numpy-2.3.5-cp314-cp314-win32.whl", hash = "sha256:66f85ce62c70b843bab1fb14a05d5737741e74e28c7b8b5a064de10142fad248", size = 6335432, upload-time = "2025-11-16T22:51:42.476Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/2e/235b4d96619931192c91660805e5e49242389742a7a82c27665021db690c/numpy-2.3.5-cp314-cp314-win_amd64.whl", hash = "sha256:e6a0bc88393d65807d751a614207b7129a310ca4fe76a74e5c7da5fa5671417e", size = 12919388, upload-time = "2025-11-16T22:51:45.275Z" },
-    { url = "https://files.pythonhosted.org/packages/07/2b/29fd75ce45d22a39c61aad74f3d718e7ab67ccf839ca8b60866054eb15f8/numpy-2.3.5-cp314-cp314-win_arm64.whl", hash = "sha256:aeffcab3d4b43712bb7a60b65f6044d444e75e563ff6180af8f98dd4b905dfd2", size = 10476651, upload-time = "2025-11-16T22:51:47.749Z" },
-    { url = "https://files.pythonhosted.org/packages/17/e1/f6a721234ebd4d87084cfa68d081bcba2f5cfe1974f7de4e0e8b9b2a2ba1/numpy-2.3.5-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:17531366a2e3a9e30762c000f2c43a9aaa05728712e25c11ce1dbe700c53ad41", size = 16834503, upload-time = "2025-11-16T22:51:50.443Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/1c/baf7ffdc3af9c356e1c135e57ab7cf8d247931b9554f55c467efe2c69eff/numpy-2.3.5-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:d21644de1b609825ede2f48be98dfde4656aefc713654eeee280e37cadc4e0ad", size = 12381612, upload-time = "2025-11-16T22:51:53.609Z" },
-    { url = "https://files.pythonhosted.org/packages/74/91/f7f0295151407ddc9ba34e699013c32c3c91944f9b35fcf9281163dc1468/numpy-2.3.5-cp314-cp314t-macosx_14_0_arm64.whl", hash = "sha256:c804e3a5aba5460c73955c955bdbd5c08c354954e9270a2c1565f62e866bdc39", size = 5210042, upload-time = "2025-11-16T22:51:56.213Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/3b/78aebf345104ec50dd50a4d06ddeb46a9ff5261c33bcc58b1c4f12f85ec2/numpy-2.3.5-cp314-cp314t-macosx_14_0_x86_64.whl", hash = "sha256:cc0a57f895b96ec78969c34f682c602bf8da1a0270b09bc65673df2e7638ec20", size = 6724502, upload-time = "2025-11-16T22:51:58.584Z" },
-    { url = "https://files.pythonhosted.org/packages/02/c6/7c34b528740512e57ef1b7c8337ab0b4f0bddf34c723b8996c675bc2bc91/numpy-2.3.5-cp314-cp314t-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:900218e456384ea676e24ea6a0417f030a3b07306d29d7ad843957b40a9d8d52", size = 14308962, upload-time = "2025-11-16T22:52:01.698Z" },
-    { url = "https://files.pythonhosted.org/packages/80/35/09d433c5262bc32d725bafc619e095b6a6651caf94027a03da624146f655/numpy-2.3.5-cp314-cp314t-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:09a1bea522b25109bf8e6f3027bd810f7c1085c64a0c7ce050c1676ad0ba010b", size = 16655054, upload-time = "2025-11-16T22:52:04.267Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/ab/6a7b259703c09a88804fa2430b43d6457b692378f6b74b356155283566ac/numpy-2.3.5-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:04822c00b5fd0323c8166d66c701dc31b7fbd252c100acd708c48f763968d6a3", size = 16091613, upload-time = "2025-11-16T22:52:08.651Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/88/330da2071e8771e60d1038166ff9d73f29da37b01ec3eb43cb1427464e10/numpy-2.3.5-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:d6889ec4ec662a1a37eb4b4fb26b6100841804dac55bd9df579e326cdc146227", size = 18591147, upload-time = "2025-11-16T22:52:11.453Z" },
-    { url = "https://files.pythonhosted.org/packages/51/41/851c4b4082402d9ea860c3626db5d5df47164a712cb23b54be028b184c1c/numpy-2.3.5-cp314-cp314t-win32.whl", hash = "sha256:93eebbcf1aafdf7e2ddd44c2923e2672e1010bddc014138b229e49725b4d6be5", size = 6479806, upload-time = "2025-11-16T22:52:14.641Z" },
-    { url = "https://files.pythonhosted.org/packages/90/30/d48bde1dfd93332fa557cff1972fbc039e055a52021fbef4c2c4b1eefd17/numpy-2.3.5-cp314-cp314t-win_amd64.whl", hash = "sha256:c8a9958e88b65c3b27e22ca2a076311636850b612d6bbfb76e8d156aacde2aaf", size = 13105760, upload-time = "2025-11-16T22:52:17.975Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/fd/4b5eb0b3e888d86aee4d198c23acec7d214baaf17ea93c1adec94c9518b9/numpy-2.3.5-cp314-cp314t-win_arm64.whl", hash = "sha256:6203fdf9f3dc5bdaed7319ad8698e685c7a3be10819f41d32a0723e611733b42", size = 10545459, upload-time = "2025-11-16T22:52:20.55Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/65/f9dea8e109371ade9c782b4e4756a82edf9d3366bca495d84d79859a0b79/numpy-2.3.5-pp311-pypy311_pp73-macosx_10_15_x86_64.whl", hash = "sha256:f0963b55cdd70fad460fa4c1341f12f976bb26cb66021a5580329bd498988310", size = 16910689, upload-time = "2025-11-16T22:52:23.247Z" },
-    { url = "https://files.pythonhosted.org/packages/00/4f/edb00032a8fb92ec0a679d3830368355da91a69cab6f3e9c21b64d0bb986/numpy-2.3.5-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:f4255143f5160d0de972d28c8f9665d882b5f61309d8362fdd3e103cf7bf010c", size = 12457053, upload-time = "2025-11-16T22:52:26.367Z" },
-    { url = "https://files.pythonhosted.org/packages/16/a4/e8a53b5abd500a63836a29ebe145fc1ab1f2eefe1cfe59276020373ae0aa/numpy-2.3.5-pp311-pypy311_pp73-macosx_14_0_arm64.whl", hash = "sha256:a4b9159734b326535f4dd01d947f919c6eefd2d9827466a696c44ced82dfbc18", size = 5285635, upload-time = "2025-11-16T22:52:29.266Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/2f/37eeb9014d9c8b3e9c55bc599c68263ca44fdbc12a93e45a21d1d56df737/numpy-2.3.5-pp311-pypy311_pp73-macosx_14_0_x86_64.whl", hash = "sha256:2feae0d2c91d46e59fcd62784a3a83b3fb677fead592ce51b5a6fbb4f95965ff", size = 6801770, upload-time = "2025-11-16T22:52:31.421Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/e4/68d2f474df2cb671b2b6c2986a02e520671295647dad82484cde80ca427b/numpy-2.3.5-pp311-pypy311_pp73-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ffac52f28a7849ad7576293c0cb7b9f08304e8f7d738a8cb8a90ec4c55a998eb", size = 14391768, upload-time = "2025-11-16T22:52:33.593Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/50/94ccd8a2b141cb50651fddd4f6a48874acb3c91c8f0842b08a6afc4b0b21/numpy-2.3.5-pp311-pypy311_pp73-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:63c0e9e7eea69588479ebf4a8a270d5ac22763cc5854e9a7eae952a3908103f7", size = 16729263, upload-time = "2025-11-16T22:52:36.369Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/ee/346fa473e666fe14c52fcdd19ec2424157290a032d4c41f98127bfb31ac7/numpy-2.3.5-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:f16417ec91f12f814b10bafe79ef77e70113a2f5f7018640e7425ff979253425", size = 12967213, upload-time = "2025-11-16T22:52:39.38Z" },
+version = "1.26.4"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/65/6e/09db70a523a96d25e115e71cc56a6f9031e7b8cd166c1ac8438307c14058/numpy-1.26.4.tar.gz", hash = "sha256:2a02aba9ed12e4ac4eb3ea9421c420301a0c6460d9830d74a9df87efa4912010", size = 15786129, upload-time = "2024-02-06T00:26:44.495Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/11/57/baae43d14fe163fa0e4c47f307b6b2511ab8d7d30177c491960504252053/numpy-1.26.4-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4c66707fabe114439db9068ee468c26bbdf909cac0fb58686a42a24de1760c71", size = 20630554, upload-time = "2024-02-05T23:51:50.149Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/2e/151484f49fd03944c4a3ad9c418ed193cfd02724e138ac8a9505d056c582/numpy-1.26.4-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:edd8b5fe47dab091176d21bb6de568acdd906d1887a4584a15a9a96a1dca06ef", size = 13997127, upload-time = "2024-02-05T23:52:15.314Z" },
+    { url = "https://files.pythonhosted.org/packages/79/ae/7e5b85136806f9dadf4878bf73cf223fe5c2636818ba3ab1c585d0403164/numpy-1.26.4-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7ab55401287bfec946ced39700c053796e7cc0e3acbef09993a9ad2adba6ca6e", size = 14222994, upload-time = "2024-02-05T23:52:47.569Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/d0/edc009c27b406c4f9cbc79274d6e46d634d139075492ad055e3d68445925/numpy-1.26.4-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:666dbfb6ec68962c033a450943ded891bed2d54e6755e35e5835d63f4f6931d5", size = 18252005, upload-time = "2024-02-05T23:53:15.637Z" },
+    { url = "https://files.pythonhosted.org/packages/09/bf/2b1aaf8f525f2923ff6cfcf134ae5e750e279ac65ebf386c75a0cf6da06a/numpy-1.26.4-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:96ff0b2ad353d8f990b63294c8986f1ec3cb19d749234014f4e7eb0112ceba5a", size = 13885297, upload-time = "2024-02-05T23:53:42.16Z" },
+    { url = "https://files.pythonhosted.org/packages/df/a0/4e0f14d847cfc2a633a1c8621d00724f3206cfeddeb66d35698c4e2cf3d2/numpy-1.26.4-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:60dedbb91afcbfdc9bc0b1f3f402804070deed7392c23eb7a7f07fa857868e8a", size = 18093567, upload-time = "2024-02-05T23:54:11.696Z" },
+    { url = "https://files.pythonhosted.org/packages/d2/b7/a734c733286e10a7f1a8ad1ae8c90f2d33bf604a96548e0a4a3a6739b468/numpy-1.26.4-cp311-cp311-win32.whl", hash = "sha256:1af303d6b2210eb850fcf03064d364652b7120803a0b872f5211f5234b399f20", size = 5968812, upload-time = "2024-02-05T23:54:26.453Z" },
+    { url = "https://files.pythonhosted.org/packages/3f/6b/5610004206cf7f8e7ad91c5a85a8c71b2f2f8051a0c0c4d5916b76d6cbb2/numpy-1.26.4-cp311-cp311-win_amd64.whl", hash = "sha256:cd25bcecc4974d09257ffcd1f098ee778f7834c3ad767fe5db785be9a4aa9cb2", size = 15811913, upload-time = "2024-02-05T23:54:53.933Z" },
+    { url = "https://files.pythonhosted.org/packages/95/12/8f2020a8e8b8383ac0177dc9570aad031a3beb12e38847f7129bacd96228/numpy-1.26.4-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:b3ce300f3644fb06443ee2222c2201dd3a89ea6040541412b8fa189341847218", size = 20335901, upload-time = "2024-02-05T23:55:32.801Z" },
+    { url = "https://files.pythonhosted.org/packages/75/5b/ca6c8bd14007e5ca171c7c03102d17b4f4e0ceb53957e8c44343a9546dcc/numpy-1.26.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:03a8c78d01d9781b28a6989f6fa1bb2c4f2d51201cf99d3dd875df6fbd96b23b", size = 13685868, upload-time = "2024-02-05T23:55:56.28Z" },
+    { url = "https://files.pythonhosted.org/packages/79/f8/97f10e6755e2a7d027ca783f63044d5b1bc1ae7acb12afe6a9b4286eac17/numpy-1.26.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9fad7dcb1aac3c7f0584a5a8133e3a43eeb2fe127f47e3632d43d677c66c102b", size = 13925109, upload-time = "2024-02-05T23:56:20.368Z" },
+    { url = "https://files.pythonhosted.org/packages/0f/50/de23fde84e45f5c4fda2488c759b69990fd4512387a8632860f3ac9cd225/numpy-1.26.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:675d61ffbfa78604709862923189bad94014bef562cc35cf61d3a07bba02a7ed", size = 17950613, upload-time = "2024-02-05T23:56:56.054Z" },
+    { url = "https://files.pythonhosted.org/packages/4c/0c/9c603826b6465e82591e05ca230dfc13376da512b25ccd0894709b054ed0/numpy-1.26.4-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:ab47dbe5cc8210f55aa58e4805fe224dac469cde56b9f731a4c098b91917159a", size = 13572172, upload-time = "2024-02-05T23:57:21.56Z" },
+    { url = "https://files.pythonhosted.org/packages/76/8c/2ba3902e1a0fc1c74962ea9bb33a534bb05984ad7ff9515bf8d07527cadd/numpy-1.26.4-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:1dda2e7b4ec9dd512f84935c5f126c8bd8b9f2fc001e9f54af255e8c5f16b0e0", size = 17786643, upload-time = "2024-02-05T23:57:56.585Z" },
+    { url = "https://files.pythonhosted.org/packages/28/4a/46d9e65106879492374999e76eb85f87b15328e06bd1550668f79f7b18c6/numpy-1.26.4-cp312-cp312-win32.whl", hash = "sha256:50193e430acfc1346175fcbdaa28ffec49947a06918b7b92130744e81e640110", size = 5677803, upload-time = "2024-02-05T23:58:08.963Z" },
+    { url = "https://files.pythonhosted.org/packages/16/2e/86f24451c2d530c88daf997cb8d6ac622c1d40d19f5a031ed68a4b73a374/numpy-1.26.4-cp312-cp312-win_amd64.whl", hash = "sha256:08beddf13648eb95f8d867350f6a018a4be2e5ad54c8d8caed89ebca558b2818", size = 15517754, upload-time = "2024-02-05T23:58:36.364Z" },
 ]
 
 [[package]]
@@ -2468,11 +2411,11 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "datasets", git = "https://github.com/CloseChoice/datasets.git?rev=feat%2Fbids-loader-streaming-upload-fix" },
-    { name = "gradio", specifier = ">=5.0.0" },
+    { name = "gradio", specifier = ">=6.0.0,<7.0.0" },
     { name = "huggingface-hub", specifier = ">=0.25.0" },
     { name = "matplotlib", specifier = ">=3.8.0" },
     { name = "nibabel", specifier = ">=5.2.0" },
-    { name = "numpy", specifier = ">=1.26.0" },
+    { name = "numpy", specifier = ">=1.26.0,<2.0.0" },
     { name = "pydantic", specifier = ">=2.5.0" },
     { name = "pydantic-settings", specifier = ">=2.1.0" },
     { name = "requests", specifier = ">=2.0.0" },