feat: Phase 1A + Phase 2 - Local data loader and DeepISLES Docker wrapper (#3)

## Summary
- **Phase 1A**: Implement local file loader for ISLES24-MR-Lite dataset (149 cases)
- **Phase 2**: Implement DeepISLES Docker wrapper with GPU support

## Changes
- Add `LocalDataset` dataclass for file-based dataset access
- Add BIDS filename parsing (`parse_subject_id`)
- Add Docker utilities (`run_container`, `build_docker_command`, GPU detection)
- Add DeepISLES wrapper (`run_deepisles_on_folder`, `validate_input_folder`)
- 52 unit tests, mypy strict, ruff clean

## CodeRabbit Feedback Addressed
- Made `inspect_isles24.py` executable
- Fixed Windows compatibility in `match_user` logic

.gitignore

@@ -205,3 +205,7 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+
+# Data Discovery (per docs/specs/data-discovery.md)
+data/scratch/*
+!data/scratch/.gitkeep

docs/specs/00-context.md

@@ -11,19 +11,38 @@ This document explains **why** we're building `stroke-deepisles-demo` and the ar
 We want to demonstrate an end-to-end neuroimaging inference pipeline:
 
 ```
-HuggingFace Hub (ISLES24-MR-Lite)
-        ↓
-    BIDS/NIfTI loader (datasets fork)
-        ↓
-    DeepISLES Docker (stroke segmentation)
-        ↓
-    NiiVue visualization (Gradio Space)
+CURRENT (Phase 1A):
+    Local NIfTI files (extracted from ISLES24-MR-Lite ZIPs)
+            ↓
+        File-based loader (parse BIDS filenames)
+            ↓
+        DeepISLES Docker (stroke segmentation)
+            ↓
+        NiiVue visualization (Gradio Space)
+
+FUTURE (Phase 1C-D):
+    HuggingFace Hub (properly uploaded dataset)
+            ↓
+        Tobias's datasets fork (BIDS loader + Nifti feature)
+            ↓
+        DeepISLES Docker (stroke segmentation)
+            ↓
+        NiiVue visualization (Gradio Space)
 ```
 
 This showcases that:
-1. Neuroimaging data can be consumed from HF Hub with proper BIDS/NIfTI support
-2. Clinical-grade models can run via Docker as black boxes
-3. Results can be visualized interactively in a browser
+1. Neuroimaging data can be loaded from local BIDS-named files (NOW)
+2. Neuroimaging data can be consumed from HF Hub with proper BIDS/NIfTI support (FUTURE)
+3. Clinical-grade models can run via Docker as black boxes
+4. Results can be visualized interactively in a browser
+
+## critical discovery (2025-12-04)
+
+**The original ISLES24-MR-Lite dataset is NOT properly uploaded to HuggingFace.**
+
+It's just raw ZIP files dumped on HF, not a proper Dataset with parquet/Arrow format. This means `load_dataset()` fails. See `data/scratch/isles24_schema_report.txt` for full details.
+
+**Workaround**: We extracted the ZIPs locally to `data/scratch/isles24_extracted/` (git-ignored) and will implement a file-based loader first. Later, we'll re-upload properly and verify full HF consumption.
 
 ## why we need tobias's datasets fork
 
@@ -55,11 +74,22 @@ We pin to this branch until upstream merges the PRs.
 
 ### 1. data source: ISLES24-MR-Lite
 
-- **HF Dataset**: [YongchengYAO/ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite)
+- **HF Dataset**: [YongchengYAO/ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite) (**BROKEN** - raw ZIPs, not proper dataset)
+- **Local extracted**: `data/scratch/isles24_extracted/` (git-ignored)
 - **Content**: 149 acute stroke MRI cases with DWI, ADC, and manual infarct masks
 - **Origin**: Subset of ISLES 2024 challenge data
 - **Why suitable**: DeepISLES was trained on ISLES 2022, so ISLES24 is an **external** test set (no data leakage)
 
+**File structure** (after extraction):
+```
+data/scratch/isles24_extracted/
+├── Images-DWI/sub-stroke{XXXX}_ses-02_dwi.nii.gz        # 149 files
+├── Images-ADC/sub-stroke{XXXX}_ses-02_adc.nii.gz        # 149 files
+└── Masks/sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz      # 149 files
+```
+
+**Schema reference**: `data/scratch/isles24_schema_report.txt`
+
 ### 2. model: DeepISLES
 
 - **Paper**: Nature Communications 2025 - "DeepISLES: A clinically validated ischemic stroke segmentation model"

docs/specs/02-phase-1-data-access.md

@@ -1,695 +1,415 @@
-# phase 1: data access / hf integration
+# phase 1: data access layer
 
 ## purpose
 
-Implement the data loading layer that consumes ISLES24-MR-Lite from HuggingFace Hub. At the end of this phase, we can load any case by ID and get local paths to DWI, ADC, and ground truth NIfTI files.
+Implement a data loading layer that provides typed access to ISLES24 neuroimaging cases. This phase is split into sub-phases due to a critical discovery: the upstream dataset is not properly formatted for HuggingFace consumption.
 
-## deliverables
+## critical discovery (2025-12-04)
 
-- [ ] `src/stroke_deepisles_demo/data/loader.py` - HF dataset loading
-- [ ] `src/stroke_deepisles_demo/data/adapter.py` - Case adapter for file access
-- [ ] `src/stroke_deepisles_demo/data/staging.py` - Stage files for DeepISLES
-- [ ] Unit tests with fixtures (no network required)
-- [ ] Integration test (marked, requires network)
+**`YongchengYAO/ISLES24-MR-Lite` is NOT a proper HuggingFace Dataset.**
 
-## vertical slice outcome
+| What we expected | What actually exists |
+|------------------|---------------------|
+| `load_dataset()` returns Dataset with columns | `load_dataset()` FAILS with "no data" |
+| Columns: `dwi`, `adc`, `mask`, `participant_id` | No columns - just raw ZIP files |
+| Parquet/Arrow format | Three ZIP archives dumped on HF |
 
-After this phase, you can run:
+**Evidence**: `data/scratch/isles24_schema_report.txt`
 
-```python
-from stroke_deepisles_demo.data import get_case, list_case_ids
+This means the demo must be built in phases:
+1. **Phase 1A**: Local file loader (works NOW with extracted data)
+2. **Phase 1B**: Test Tobias's `Nifti()` feature on local files (proves loading works)
+3. **Phase 1C**: Upload properly to HuggingFace (future - proves production pipeline)
+4. **Phase 1D**: Consume via Tobias's fork (future - proves full round-trip)
 
-# List available cases
-case_ids = list_case_ids()
-print(f"Found {len(case_ids)} cases")
+---
 
-# Load a specific case
-case = get_case("sub-001")
-print(f"DWI: {case.dwi}")
-print(f"ADC: {case.adc}")
-print(f"Ground truth: {case.ground_truth}")
-```
+## phase 1a: local file loader (CURRENT PRIORITY)
 
-## module structure
+### data location
 
 ```
-src/stroke_deepisles_demo/data/
-├── __init__.py          # Public API exports
-├── loader.py            # HF Hub dataset loading
-├── adapter.py           # Case adapter (index → files)
-└── staging.py           # Stage files with DeepISLES naming
+data/scratch/isles24_extracted/     # Git-ignored
+├── Images-DWI/                     # 149 files
+│   └── sub-stroke{XXXX}_ses-02_dwi.nii.gz
+├── Images-ADC/                     # 149 files
+│   └── sub-stroke{XXXX}_ses-02_adc.nii.gz
+└── Masks/                          # 149 files
+    └── sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz
 ```
 
-## interfaces and types
+### file naming convention (BIDS-like)
+
+| Component | Pattern | Example |
+|-----------|---------|---------|
+| Subject ID | `sub-stroke{XXXX}` | `sub-stroke0005` |
+| Session | `ses-02` | Always "02" in this dataset |
+| Modality | `dwi`, `adc`, `lesion-msk` | - |
+| Extension | `.nii.gz` | Compressed NIfTI |
+
+**Subject ID regex**: `sub-stroke(\d{4})_ses-02_.*\.nii\.gz`
+
+**Note**: Subject IDs have gaps (e.g., 0018 missing). Range is 0001-0189, total 149 cases.
 
-### `data/loader.py`
+### deliverables
+
+- [ ] `src/stroke_deepisles_demo/data/loader.py` - Rewrite with local mode
+- [ ] `src/stroke_deepisles_demo/data/adapter.py` - Rewrite for file-based access
+- [ ] `src/stroke_deepisles_demo/data/staging.py` - Already correct, no changes
+- [ ] Unit tests with synthetic fixtures
+- [ ] Integration test with actual extracted data
+
+### interfaces
+
+#### `data/loader.py`
 
 ```python
-"""Load ISLES24-MR-Lite dataset from HuggingFace Hub."""
+"""Load ISLES24 data from local directory or HuggingFace Hub."""
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from datasets import Dataset
+    from stroke_deepisles_demo.data.adapter import LocalDataset
+
+
+@dataclass
+class DatasetInfo:
+    """Metadata about the dataset."""
+
+    source: str  # "local" or HF dataset ID
+    num_cases: int
+    modalities: list[str]
+    has_ground_truth: bool
 
 
 def load_isles_dataset(
-    dataset_id: str = "YongchengYAO/ISLES24-MR-Lite",
+    source: str | Path = "data/scratch/isles24_extracted",
     *,
-    cache_dir: Path | None = None,
-    streaming: bool = False,
-) -> Dataset:
+    local_mode: bool = True,  # Default to local for now
+) -> LocalDataset:
     """
-    Load the ISLES24-MR-Lite dataset from HuggingFace Hub.
+    Load ISLES24 dataset.
 
     Args:
-        dataset_id: HuggingFace dataset identifier
-        cache_dir: Local cache directory (uses HF default if None)
-        streaming: If True, use streaming mode (lazy loading)
+        source: Local directory path or HuggingFace dataset ID
+        local_mode: If True, treat source as local directory
 
     Returns:
-        HuggingFace Dataset object with BIDS/NIfTI support
+        Dataset-like object providing case access
 
     Raises:
-        DataLoadError: If dataset cannot be loaded
+        DataLoadError: If data cannot be loaded
     """
-    ...
+    if local_mode or isinstance(source, Path):
+        return _load_from_local_directory(Path(source))
+    # Future: return _load_from_huggingface(source)
+    raise NotImplementedError("HuggingFace mode not yet implemented")
 
 
-def get_dataset_info(dataset_id: str = "YongchengYAO/ISLES24-MR-Lite") -> DatasetInfo:
+def _load_from_local_directory(data_dir: Path) -> LocalDataset:
     """
-    Get metadata about the dataset without downloading.
+    Load cases from extracted local files.
 
-    Returns:
-        DatasetInfo with case count, available modalities, etc.
+    Expects structure:
+        data_dir/
+        ├── Images-DWI/sub-stroke{XXXX}_ses-02_dwi.nii.gz
+        ├── Images-ADC/sub-stroke{XXXX}_ses-02_adc.nii.gz
+        └── Masks/sub-stroke{XXXX}_ses-02_lesion-msk.nii.gz
     """
     ...
-
-
-@dataclass
-class DatasetInfo:
-    """Metadata about the loaded dataset."""
-
-    dataset_id: str
-    num_cases: int
-    modalities: list[str]  # e.g., ["dwi", "adc", "mask"]
-    has_ground_truth: bool
 ```
 
-### `data/adapter.py`
+#### `data/adapter.py`
 
 ```python
-"""Adapt HF dataset rows to typed file references."""
+"""Provide typed access to ISLES24 cases."""
 
 from __future__ import annotations
 
+import re
+from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterator
 
 from stroke_deepisles_demo.core.types import CaseFiles
 
 
-class CaseAdapter:
-    """
-    Adapts HuggingFace dataset to provide typed access to case files.
-
-    This handles the mapping between HF dataset structure and our
-    internal CaseFiles type.
-    """
-
-    def __init__(self, dataset: Dataset) -> None:
-        """
-        Initialize adapter with a loaded dataset.
+@dataclass
+class LocalDataset:
+    """File-based dataset for local ISLES24 data."""
 
-        Args:
-            dataset: HuggingFace Dataset with NIfTI files
-        """
-        ...
+    data_dir: Path
+    cases: dict[str, CaseFiles]  # subject_id -> files
 
     def __len__(self) -> int:
-        """Return number of cases in the dataset."""
-        ...
+        return len(self.cases)
 
     def __iter__(self) -> Iterator[str]:
-        """Iterate over case IDs."""
-        ...
+        return iter(self.cases.keys())
 
     def list_case_ids(self) -> list[str]:
-        """
-        List all available case identifiers.
-
-        Returns:
-            List of case IDs (e.g., ["sub-001", "sub-002", ...])
-        """
-        ...
+        """Return sorted list of subject IDs."""
+        return sorted(self.cases.keys())
 
     def get_case(self, case_id: str | int) -> CaseFiles:
-        """
-        Get file paths for a specific case.
+        """Get files for a case by ID or index."""
+        if isinstance(case_id, int):
+            case_id = self.list_case_ids()[case_id]
+        return self.cases[case_id]
 
-        Args:
-            case_id: Either a string ID (e.g., "sub-001") or integer index
 
-        Returns:
-            CaseFiles with paths to DWI, ADC, and optionally ground truth
+# Subject ID extraction
+SUBJECT_PATTERN = re.compile(r"sub-(stroke\d{4})_ses-\d+_.*\.nii\.gz")
 
-        Raises:
-            KeyError: If case_id not found
-            DataLoadError: If files cannot be accessed
-        """
-        ...
 
-    def get_case_by_index(self, index: int) -> tuple[str, CaseFiles]:
-        """
-        Get case by numerical index.
-
-        Returns:
-            Tuple of (case_id, CaseFiles)
-        """
-        ...
-```
+def parse_subject_id(filename: str) -> str | None:
+    """Extract subject ID from BIDS filename."""
+    match = SUBJECT_PATTERN.match(filename)
+    return f"sub-{match.group(1)}" if match else None
 
-### `data/staging.py`
-
-```python
-"""Stage NIfTI files with DeepISLES-expected naming."""
-
-from __future__ import annotations
 
-from pathlib import Path
-from typing import NamedTuple
-
-from stroke_deepisles_demo.core.types import CaseFiles
-
-
-class StagedCase(NamedTuple):
-    """Paths to staged files ready for DeepISLES."""
-
-    input_dir: Path      # Directory containing staged files
-    dwi_path: Path       # Path to dwi.nii.gz
-    adc_path: Path       # Path to adc.nii.gz
-    flair_path: Path | None  # Path to flair.nii.gz if available
-
-
-def stage_case_for_deepisles(
-    case_files: CaseFiles,
-    output_dir: Path,
-    *,
-    case_id: str | None = None,
-) -> StagedCase:
+def build_local_dataset(data_dir: Path) -> LocalDataset:
     """
-    Stage case files with DeepISLES-expected naming convention.
+    Scan directory and build case mapping.
 
-    DeepISLES expects files named exactly:
-    - dwi.nii.gz
-    - adc.nii.gz
-    - flair.nii.gz (optional)
-
-    This function copies/symlinks the source files to a staging directory
-    with the correct names.
-
-    Args:
-        case_files: Source file paths from CaseAdapter
-        output_dir: Directory to stage files into
-        case_id: Optional case ID for logging/subdirectory
-
-    Returns:
-        StagedCase with paths to staged files
-
-    Raises:
-        MissingInputError: If required files (DWI, ADC) are missing
-        OSError: If file operations fail
+    Matches DWI + ADC + Mask files by subject ID.
     """
-    ...
+    dwi_dir = data_dir / "Images-DWI"
+    adc_dir = data_dir / "Images-ADC"
+    mask_dir = data_dir / "Masks"
 
+    cases: dict[str, CaseFiles] = {}
 
-def create_staging_directory(base_dir: Path | None = None) -> Path:
-    """
-    Create a temporary staging directory.
+    # 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:
+            continue
 
-    Args:
-        base_dir: Parent directory (uses system temp if None)
+        # Find matching ADC and Mask
+        adc_file = adc_dir / dwi_file.name.replace("_dwi.", "_adc.")
+        mask_file = mask_dir / dwi_file.name.replace("_dwi.", "_lesion-msk.")
 
-    Returns:
-        Path to created staging directory
-    """
-    ...
-```
-
-### `data/__init__.py` (public API)
-
-```python
-"""Data loading and case management for stroke-deepisles-demo."""
-
-from stroke_deepisles_demo.data.adapter import CaseAdapter
-from stroke_deepisles_demo.data.loader import DatasetInfo, get_dataset_info, load_isles_dataset
-from stroke_deepisles_demo.data.staging import StagedCase, stage_case_for_deepisles
-
-__all__ = [
-    # Loader
-    "load_isles_dataset",
-    "get_dataset_info",
-    "DatasetInfo",
-    # Adapter
-    "CaseAdapter",
-    # Staging
-    "stage_case_for_deepisles",
-    "StagedCase",
-]
-
-
-# Convenience functions (combine loader + adapter)
-def get_case(case_id: str | int) -> CaseFiles:
-    """Load a single case by ID or index."""
-    ...
+        if not adc_file.exists():
+            continue  # Skip incomplete cases
 
+        cases[subject_id] = CaseFiles(
+            dwi=dwi_file,
+            adc=adc_file,
+            ground_truth=mask_file if mask_file.exists() else None,
+        )
 
-def list_case_ids() -> list[str]:
-    """List all available case IDs."""
-    ...
-```
-
-## tdd plan
-
-### test file structure
-
-```
-tests/
-├── conftest.py              # Shared fixtures
-├── data/
-│   ├── __init__.py
-│   ├── test_loader.py       # Tests for HF loading
-│   ├── test_adapter.py      # Tests for case adapter
-│   └── test_staging.py      # Tests for file staging
-└── fixtures/
-    └── nifti/               # Minimal synthetic NIfTI files
-        ├── dwi.nii.gz
-        ├── adc.nii.gz
-        └── mask.nii.gz
+    return LocalDataset(data_dir=data_dir, cases=cases)
 ```
 
-### tests to write first (TDD order)
+### synthetic fixture structure
 
-#### 1. `tests/conftest.py` - Fixtures
+Unit tests MUST use fixtures that replicate the **exact** directory structure. Add to `tests/conftest.py`:
 
 ```python
-"""Shared test fixtures."""
-
-from __future__ import annotations
-
-import tempfile
-from pathlib import Path
-
-import nibabel as nib
-import numpy as np
-import pytest
-
-
 @pytest.fixture
-def temp_dir() -> Path:
-    """Create a temporary directory for test outputs."""
-    with tempfile.TemporaryDirectory() as td:
-        yield Path(td)
+def synthetic_isles_dir(temp_dir: Path) -> Path:
+    """
+    Create synthetic ISLES24-like directory structure.
+
+    Structure:
+        temp_dir/
+        ├── Images-DWI/
+        │   ├── sub-stroke0001_ses-02_dwi.nii.gz
+        │   └── sub-stroke0002_ses-02_dwi.nii.gz
+        ├── Images-ADC/
+        │   ├── sub-stroke0001_ses-02_adc.nii.gz
+        │   └── sub-stroke0002_ses-02_adc.nii.gz
+        └── Masks/
+            ├── sub-stroke0001_ses-02_lesion-msk.nii.gz
+            └── sub-stroke0002_ses-02_lesion-msk.nii.gz
+    """
+    dwi_dir = temp_dir / "Images-DWI"
+    adc_dir = temp_dir / "Images-ADC"
+    mask_dir = temp_dir / "Masks"
 
+    dwi_dir.mkdir()
+    adc_dir.mkdir()
+    mask_dir.mkdir()
 
-@pytest.fixture
-def synthetic_nifti_3d(temp_dir: Path) -> Path:
-    """Create a minimal synthetic 3D NIfTI file."""
-    data = np.random.rand(10, 10, 10).astype(np.float32)
-    img = nib.Nifti1Image(data, affine=np.eye(4))
-    path = temp_dir / "synthetic.nii.gz"
-    nib.save(img, path)
-    return path
+    for subject_num in [1, 2]:
+        subject_id = f"sub-stroke{subject_num:04d}"
 
+        # Create DWI
+        dwi_data = np.random.rand(10, 10, 5).astype(np.float32)
+        dwi_img = nib.Nifti1Image(dwi_data, affine=np.eye(4))
+        nib.save(dwi_img, dwi_dir / f"{subject_id}_ses-02_dwi.nii.gz")
 
-@pytest.fixture
-def synthetic_case_files(temp_dir: Path) -> CaseFiles:
-    """Create a complete set of synthetic case files."""
-    # Create DWI
-    dwi_data = np.random.rand(64, 64, 30).astype(np.float32)
-    dwi_img = nib.Nifti1Image(dwi_data, affine=np.eye(4))
-    dwi_path = temp_dir / "dwi.nii.gz"
-    nib.save(dwi_img, dwi_path)
-
-    # Create ADC
-    adc_data = np.random.rand(64, 64, 30).astype(np.float32) * 2000
-    adc_img = nib.Nifti1Image(adc_data, affine=np.eye(4))
-    adc_path = temp_dir / "adc.nii.gz"
-    nib.save(adc_img, adc_path)
-
-    # Create mask
-    mask_data = (np.random.rand(64, 64, 30) > 0.9).astype(np.uint8)
-    mask_img = nib.Nifti1Image(mask_data, affine=np.eye(4))
-    mask_path = temp_dir / "mask.nii.gz"
-    nib.save(mask_img, mask_path)
-
-    return CaseFiles(
-        dwi=dwi_path,
-        adc=adc_path,
-        flair=None,
-        ground_truth=mask_path,
-    )
+        # Create ADC
+        adc_data = np.random.rand(10, 10, 5).astype(np.float32) * 2000
+        adc_img = nib.Nifti1Image(adc_data, affine=np.eye(4))
+        nib.save(adc_img, adc_dir / f"{subject_id}_ses-02_adc.nii.gz")
 
+        # Create Mask
+        mask_data = (np.random.rand(10, 10, 5) > 0.9).astype(np.uint8)
+        mask_img = nib.Nifti1Image(mask_data, affine=np.eye(4))
+        nib.save(mask_img, mask_dir / f"{subject_id}_ses-02_lesion-msk.nii.gz")
 
-@pytest.fixture
-def mock_hf_dataset(synthetic_case_files: CaseFiles):
-    """Create a mock HF Dataset-like object."""
-    # Returns a simple dict-based mock that mimics Dataset behavior
-    ...
+    return temp_dir
 ```
 
-#### 2. `tests/data/test_staging.py` - Start with staging (no network)
+### tdd plan
 
 ```python
-"""Tests for data staging module."""
+# tests/data/test_loader.py
 
-from __future__ import annotations
+def test_load_from_local_returns_local_dataset(synthetic_isles_dir):
+    """Local mode returns LocalDataset."""
+    ...
 
-from pathlib import Path
+def test_load_from_local_finds_all_cases(synthetic_isles_dir):
+    """Finds all cases in synthetic structure."""
+    ...
 
-import pytest
+# tests/data/test_adapter.py
 
-from stroke_deepisles_demo.core.exceptions import MissingInputError
-from stroke_deepisles_demo.core.types import CaseFiles
-from stroke_deepisles_demo.data.staging import (
-    StagedCase,
-    create_staging_directory,
-    stage_case_for_deepisles,
-)
-
-
-class TestCreateStagingDirectory:
-    """Tests for create_staging_directory."""
-
-    def test_creates_directory(self, temp_dir: Path) -> None:
-        """Staging directory is created and exists."""
-        staging = create_staging_directory(base_dir=temp_dir)
-        assert staging.exists()
-        assert staging.is_dir()
-
-    def test_uses_system_temp_when_no_base(self) -> None:
-        """Uses system temp directory when base_dir is None."""
-        staging = create_staging_directory(base_dir=None)
-        assert staging.exists()
-        # Cleanup
-        staging.rmdir()
-
-
-class TestStageCaseForDeepIsles:
-    """Tests for stage_case_for_deepisles."""
-
-    def test_stages_required_files(
-        self, synthetic_case_files: CaseFiles, temp_dir: Path
-    ) -> None:
-        """DWI and ADC are staged with correct names."""
-        staged = stage_case_for_deepisles(synthetic_case_files, temp_dir)
-
-        assert staged.dwi_path.name == "dwi.nii.gz"
-        assert staged.adc_path.name == "adc.nii.gz"
-        assert staged.dwi_path.exists()
-        assert staged.adc_path.exists()
-
-    def test_staged_files_are_readable(
-        self, synthetic_case_files: CaseFiles, temp_dir: Path
-    ) -> None:
-        """Staged files can be read as valid NIfTI."""
-        import nibabel as nib
-
-        staged = stage_case_for_deepisles(synthetic_case_files, temp_dir)
-
-        dwi = nib.load(staged.dwi_path)
-        assert dwi.shape == (64, 64, 30)
-
-    def test_raises_when_dwi_missing(self, temp_dir: Path) -> None:
-        """Raises MissingInputError when DWI is missing."""
-        case_files = CaseFiles(
-            dwi=temp_dir / "nonexistent.nii.gz",
-            adc=temp_dir / "adc.nii.gz",
-            flair=None,
-            ground_truth=None,
-        )
+def test_parse_subject_id_extracts_correctly():
+    """Extracts subject ID from BIDS filename."""
+    assert parse_subject_id("sub-stroke0005_ses-02_dwi.nii.gz") == "sub-stroke0005"
 
-        with pytest.raises(MissingInputError, match="DWI"):
-            stage_case_for_deepisles(case_files, temp_dir)
-
-    def test_flair_is_optional(
-        self, synthetic_case_files: CaseFiles, temp_dir: Path
-    ) -> None:
-        """Staging succeeds when FLAIR is None."""
-        # synthetic_case_files has flair=None
-        staged = stage_case_for_deepisles(synthetic_case_files, temp_dir)
+def test_build_local_dataset_matches_files(synthetic_isles_dir):
+    """Matches DWI, ADC, Mask by subject ID."""
+    ...
 
-        assert staged.flair_path is None
+def test_get_case_returns_case_files(synthetic_isles_dir):
+    """get_case returns CaseFiles with correct paths."""
+    ...
 ```
 
-#### 3. `tests/data/test_adapter.py` - Case adapter with mocks
-
-```python
-"""Tests for case adapter module."""
-
-from __future__ import annotations
-
-import pytest
-
-from stroke_deepisles_demo.core.types import CaseFiles
-from stroke_deepisles_demo.data.adapter import CaseAdapter
-
-
-class TestCaseAdapter:
-    """Tests for CaseAdapter."""
-
-    def test_list_case_ids_returns_strings(self, mock_hf_dataset) -> None:
-        """list_case_ids returns list of string identifiers."""
-        adapter = CaseAdapter(mock_hf_dataset)
-        case_ids = adapter.list_case_ids()
-
-        assert isinstance(case_ids, list)
-        assert all(isinstance(cid, str) for cid in case_ids)
-
-    def test_len_matches_dataset_size(self, mock_hf_dataset) -> None:
-        """len(adapter) equals number of cases in dataset."""
-        adapter = CaseAdapter(mock_hf_dataset)
-
-        assert len(adapter) == len(mock_hf_dataset)
-
-    def test_get_case_by_string_id(self, mock_hf_dataset) -> None:
-        """Can retrieve case by string identifier."""
-        adapter = CaseAdapter(mock_hf_dataset)
-        case_ids = adapter.list_case_ids()
+### done criteria (phase 1a)
 
-        case = adapter.get_case(case_ids[0])
+- [ ] `uv run pytest tests/data/ -v` passes
+- [ ] Can load all 149 cases from `data/scratch/isles24_extracted/`
+- [ ] `list_case_ids()` returns 149 subject IDs
+- [ ] `get_case("sub-stroke0005")` returns valid CaseFiles
+- [ ] Type checking passes: `uv run mypy src/stroke_deepisles_demo/data/`
 
-        assert isinstance(case, dict)  # CaseFiles is a TypedDict
-        assert "dwi" in case
-        assert "adc" in case
+---
 
-    def test_get_case_by_index(self, mock_hf_dataset) -> None:
-        """Can retrieve case by integer index."""
-        adapter = CaseAdapter(mock_hf_dataset)
+## phase 1b: test tobias's nifti feature (NEXT)
 
-        case_id, case = adapter.get_case_by_index(0)
+### purpose
 
-        assert isinstance(case_id, str)
-        assert case["dwi"] is not None
+Verify that Tobias's `Nifti()` feature type from the datasets fork can correctly load/parse NIfTI files. This proves the **loading** part of the consumption pipeline works, even though the **download** part is broken.
 
-    def test_get_case_invalid_id_raises(self, mock_hf_dataset) -> None:
-        """Raises KeyError for invalid case ID."""
-        adapter = CaseAdapter(mock_hf_dataset)
-
-        with pytest.raises(KeyError):
-            adapter.get_case("nonexistent-case-id")
-
-    def test_iteration(self, mock_hf_dataset) -> None:
-        """Can iterate over case IDs."""
-        adapter = CaseAdapter(mock_hf_dataset)
-
-        case_ids = list(adapter)
-
-        assert len(case_ids) == len(adapter)
-```
-
-#### 4. `tests/data/test_loader.py` - Loader with network mocks
+### approach
 
 ```python
-"""Tests for data loader module."""
-
-from __future__ import annotations
-
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from stroke_deepisles_demo.core.exceptions import DataLoadError
-from stroke_deepisles_demo.data.loader import (
-    DatasetInfo,
-    get_dataset_info,
-    load_isles_dataset,
-)
-
-
-class TestLoadIslesDataset:
-    """Tests for load_isles_dataset."""
+# Test script to verify Nifti() feature works on local files
+from datasets import Features, Value
+from datasets.features import Nifti  # From Tobias's fork
+
+# Create a simple dataset from local files
+features = Features({
+    "subject_id": Value("string"),
+    "dwi": Nifti(),
+    "adc": Nifti(),
+    "mask": Nifti(),
+})
+
+# Load a single case and verify Nifti() decodes correctly
+```
 
-    def test_calls_hf_load_dataset(self) -> None:
-        """Calls datasets.load_dataset with correct arguments."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_load.return_value = MagicMock()
+### done criteria (phase 1b)
 
-            load_isles_dataset("test/dataset")
+- [ ] Tobias's `Nifti()` feature loads local `.nii.gz` files
+- [ ] Decoded NIfTI has correct shape/dtype
+- [ ] Can access voxel data via nibabel-like interface
 
-            mock_load.assert_called_once()
-            call_args = mock_load.call_args
-            assert call_args.args[0] == "test/dataset"
+---
 
-    def test_returns_dataset_object(self) -> None:
-        """Returns the loaded Dataset object."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            expected = MagicMock()
-            mock_load.return_value = expected
+## phase 1c: proper huggingface upload (FUTURE)
 
-            result = load_isles_dataset()
+### purpose
 
-            assert result is expected
+Re-upload ISLES24 data to HuggingFace **properly** using the arc-aphasia-bids approach. This proves the **production** pipeline works.
 
-    def test_handles_load_error(self) -> None:
-        """Wraps HF errors in DataLoadError."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_load.side_effect = Exception("Network error")
+### approach
 
-            with pytest.raises(DataLoadError, match="Network error"):
-                load_isles_dataset()
+1. Use BIDS loader from Tobias's fork
+2. Create proper parquet schema with columns:
+   - `subject`: string
+   - `session`: string
+   - `dwi`: Nifti()
+   - `adc`: Nifti()
+   - `mask`: Nifti()
+3. Upload to new HuggingFace repo (e.g., `The-Obstacle-Is-The-Way/ISLES24-BIDS`)
 
+### done criteria (phase 1c)
 
-class TestGetDatasetInfo:
-    """Tests for get_dataset_info."""
+- [ ] Dataset uploaded to HuggingFace with proper schema
+- [ ] HuggingFace dataset viewer shows data correctly
+- [ ] `load_dataset("new-repo-id")` returns Dataset with expected columns
 
-    def test_returns_datasetinfo(self) -> None:
-        """Returns DatasetInfo with expected fields."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_ds = MagicMock()
-            mock_ds.__len__ = MagicMock(return_value=149)
-            mock_ds.features = {"dwi": ..., "adc": ..., "mask": ...}
-            mock_load.return_value = mock_ds
+---
 
-            info = get_dataset_info()
+## phase 1d: consumption verification (FUTURE)
 
-            assert isinstance(info, DatasetInfo)
-            assert info.num_cases == 149
+### purpose
 
+Verify the full round-trip: Download from HuggingFace using Tobias's fork.
 
-@pytest.mark.integration
-class TestLoadIslesDatasetIntegration:
-    """Integration tests that hit the real HuggingFace Hub."""
+### approach
 
-    @pytest.mark.slow
-    def test_load_real_dataset(self) -> None:
-        """Actually loads ISLES24-MR-Lite from HF Hub."""
-        # This test requires network access
-        # Run with: pytest -m integration
-        dataset = load_isles_dataset(streaming=True)
+```python
+from datasets import load_dataset
 
-        # Just verify we got something
-        assert dataset is not None
+# This should work after Phase 1C
+ds = load_dataset("The-Obstacle-Is-The-Way/ISLES24-BIDS")
+case = ds["train"][0]
+print(case["dwi"].shape)  # Should work!
 ```
 
-### what to mock
-
-- `datasets.load_dataset` - Mock for unit tests, real for integration tests
-- `huggingface_hub` calls - Mock for unit tests
-- File system operations - Use `temp_dir` fixture with real files
-
-### what to test for real
-
-- NIfTI file creation/reading with nibabel
-- File staging (copy/symlink operations)
-- Integration test: actual HF Hub download (marked `@pytest.mark.integration`)
+### new adapter function
 
-## "done" criteria
-
-Phase 1 is complete when:
-
-1. All unit tests pass: `uv run pytest tests/data/ -v`
-2. Can load synthetic test cases without network
-3. Can list case IDs from mock dataset
-4. Can stage files with correct DeepISLES naming
-5. Integration test passes (with network): `uv run pytest -m integration`
-6. Type checking passes: `uv run mypy src/stroke_deepisles_demo/data/`
-7. Code coverage for data module > 80%
-
-## implementation notes
-
-- ISLES24-MR-Lite structure needs investigation - check HF page for exact column names
-- Consider using `huggingface_hub.snapshot_download` if `datasets.load_dataset` has issues with NIfTI
-- Staging can use symlinks on Unix, copies on Windows
-- Cache the HF dataset locally to avoid repeated downloads
-
-### critical: streaming mode + docker materialization
-
-**Reviewer feedback (valid)**: When using `streaming=True`, the dataset returns URLs or lazy file objects, NOT local POSIX paths. Docker requires physical files on the host disk for volume mounting.
-
-**Solution**: The `stage_case_for_deepisles` function MUST handle materialization:
+When Phase 1D is implemented, `adapter.py` will need a new function alongside `build_local_dataset`:
 
 ```python
-def stage_case_for_deepisles(
-    case_files: CaseFiles,
-    output_dir: Path,
-    *,
-    case_id: str | None = None,
-) -> StagedCase:
+def adapt_hf_case(hf_row: dict) -> CaseFiles:
     """
-    Stage case files with DeepISLES-expected naming.
+    Adapt a HuggingFace Dataset row to CaseFiles.
 
-    IMPORTANT: This function handles both local paths and streaming data.
-    When files come from streaming mode, they must be downloaded/materialized
-    before Docker can mount them.
-    """
-    output_dir.mkdir(parents=True, exist_ok=True)
+    Args:
+        hf_row: Row from load_dataset() with columns:
+            - dwi: Nifti feature (nibabel-like object)
+            - adc: Nifti feature
+            - mask: Nifti feature
+            - subject: str
 
-    # Handle DWI - may be Path, URL, or NIfTI object
-    dwi_staged = output_dir / "dwi.nii.gz"
-    _materialize_nifti(case_files["dwi"], dwi_staged)
+    Returns:
+        CaseFiles with materialized paths or nibabel objects
+    """
+    # Implementation depends on how Nifti() feature exposes data
+    # May need to write to temp files or pass nibabel objects directly
+    ...
+```
 
-    # Handle ADC
-    adc_staged = output_dir / "adc.nii.gz"
-    _materialize_nifti(case_files["adc"], adc_staged)
+This maintains the same `CaseFiles` contract for downstream phases regardless of data source.
 
-    # ... etc
+### done criteria (phase 1d)
 
+- [ ] `load_dataset()` works on properly uploaded dataset
+- [ ] `adapt_hf_case()` function converts HF rows to CaseFiles
+- [ ] Full demo runs with HuggingFace consumption (not just local files)
+- [ ] Documents the pitfall for future projects
 
-def _materialize_nifti(source: Path | str | bytes | NiftiImage, dest: Path) -> None:
-    """
-    Materialize a NIfTI file to a local path.
+---
 
-    Handles:
-    - Local Path: copy or symlink
-    - URL string: download
-    - bytes: write directly
-    - NIfTI object: serialize with nibabel
-    """
-    if isinstance(source, Path) and source.exists():
-        # Local file - symlink if possible, copy otherwise
-        shutil.copy2(source, dest)
-    elif isinstance(source, str) and source.startswith(("http://", "https://")):
-        # URL - download
-        _download_file(source, dest)
-    elif isinstance(source, bytes):
-        # Raw bytes
-        dest.write_bytes(source)
-    elif hasattr(source, "to_bytes"):
-        # NIfTI object (nibabel or wrapper)
-        dest.write_bytes(source.to_bytes())
-    else:
-        raise MissingInputError(f"Cannot materialize source: {type(source)}")
-```
+## dependencies
 
-This ensures Docker always gets physical files regardless of how data was loaded.
+No new dependencies needed beyond Phase 0.
 
-## dependencies to add
+## notes
 
-No new dependencies needed - all specified in Phase 0:
-- `datasets` (Tobias fork)
-- `nibabel`
-- `numpy`
+- The original `adapter.py` assumed HF Dataset with columns - COMPLETELY WRONG
+- The original `loader.py` called `load_dataset()` directly - FAILS on this dataset
+- `staging.py` is still correct - it just needs `CaseFiles` with paths

docs/specs/data-discovery.md

@@ -0,0 +1,67 @@
+# data discovery & verification protocol
+
+## purpose
+To establish a rigorous, reproducible process for exploring, verifying, and documenting external data sources (Hugging Face Datasets, BIDS repos, etc.) before integrating them into the production codebase. This prevents "schema guessing" and ensures strict typing aligns with reality.
+
+## principles
+1.  **No Assumptions**: Never assume column names, file formats, or data types. Verify them programmatically.
+2.  **Isolation**: Discovery scripts and their outputs must be isolated from production code and source control.
+3.  **Reproducibility**: The discovery process must be scriptable and reproducible, not a series of manual CLI commands.
+
+## standard locations
+
+### scripts
+All discovery logic resides in:
+```
+scripts/discovery/
+├── __init__.py
+├── inspect_hf_dataset.py   # e.g., Generic HF inspector
+├── verify_bids_layout.py   # e.g., BIDS validator
+└── ...
+```
+
+### data & artifacts
+All downloaded samples, temporary outputs, and schema reports reside in:
+```
+data/scratch/
+├── .gitkeep             # Tracked
+├── schema_report.txt    # Generated report
+└── samples/             # Raw data samples (IGNORED)
+```
+
+## discovery workflow
+
+### 1. implementation
+Write a focused script in `scripts/discovery/` that:
+- Connects to the data source (e.g., HF Hub).
+- Fetches *metadata* or a *minimal sample* (streaming mode preferred).
+- Prints/Logs:
+    - Feature keys (column names).
+    - Data types (Arrow types, Python types).
+    - Non-null counts (if feasible).
+    - A sample row structure.
+
+### 2. execution
+Run the script from the project root:
+```bash
+uv run scripts/discovery/inspect_hf_dataset.py > data/scratch/schema_report.txt
+```
+
+### 3. verification
+Manually review `data/scratch/schema_report.txt`.
+- **Check**: Do column names match `CaseAdapter` expectations?
+- **Check**: Are file paths strings or objects?
+- **Check**: Are required fields (DWI, ADC) actually present?
+
+### 4. remediation
+If the report contradicts the code/specs:
+1.  Update the spec (`docs/specs/`) to reflect reality.
+2.  Update the code (`src/.../adapter.py`) to handle the actual schema.
+3.  Add a regression test if the edge case is complex.
+
+## git configuration
+Ensure `.gitignore` includes:
+```gitignore
+data/scratch/*
+!data/scratch/.gitkeep
+```

pyproject.toml

@@ -118,6 +118,7 @@ addopts = [
     "-v",
     "--tb=short",
     "--strict-markers",
+    "-m", "not integration",  # Skip integration tests by default
 ]
 markers = [
     "integration: marks tests requiring external resources (Docker, network)",

scripts/discovery/inspect_isles24.py

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+"""
+ISLES24-MR-Lite Dataset Discovery Script
+
+Downloads and inspects the full YongchengYAO/ISLES24-MR-Lite dataset
+to document its exact schema before building adapters.
+
+Per: docs/specs/data-discovery.md
+
+Output: data/scratch/isles24_schema_report.txt
+"""
+
+from __future__ import annotations
+
+import sys
+from collections import Counter
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+# Constants
+DATASET_ID = "YongchengYAO/ISLES24-MR-Lite"
+OUTPUT_DIR = Path(__file__).parent.parent.parent / "data" / "scratch"
+REPORT_FILE = OUTPUT_DIR / "isles24_schema_report.txt"
+
+
+def safe_type_name(val: Any) -> str:
+    """Get a safe string representation of a value's type."""
+    if val is None:
+        return "None"
+    t = type(val).__name__
+    if hasattr(val, "dtype"):
+        return f"{t}[{val.dtype}]"
+    return t
+
+
+def safe_repr(val: Any, max_len: int = 100) -> str:
+    """Get a safe truncated repr of a value."""
+    if val is None:
+        return "None"
+    if isinstance(val, bytes):
+        return f"<bytes len={len(val)}>"
+    if isinstance(val, dict):
+        if "bytes" in val:
+            return f"<dict with 'bytes' key, len={len(val.get('bytes', b''))}>"
+        return f"<dict keys={list(val.keys())}>"
+    r = repr(val)
+    if len(r) > max_len:
+        return r[: max_len - 3] + "..."
+    return r
+
+
+def main() -> int:
+    """Main discovery workflow."""
+    print("=" * 70)
+    print("ISLES24-MR-Lite Dataset Discovery")
+    print(f"Started: {datetime.now().isoformat()}")
+    print("=" * 70)
+    print()
+
+    # Ensure output directory exists
+    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+
+    # Import datasets library
+    try:
+        from datasets import load_dataset
+    except ImportError:
+        print("ERROR: 'datasets' library not installed.")
+        print("Run: uv add datasets")
+        return 1
+
+    # =========================================================================
+    # PHASE 1: Load Dataset (Full Download)
+    # =========================================================================
+    print(f"[1/4] Loading dataset: {DATASET_ID}")
+    print("      This will download the FULL dataset...")
+    print()
+
+    try:
+        # Try loading without streaming first to get full access
+        ds = load_dataset(DATASET_ID)
+        print("      SUCCESS: Dataset loaded")
+        print(f"      Splits available: {list(ds.keys())}")
+        print()
+    except Exception as e:
+        print(f"      ERROR loading dataset: {e}")
+        print()
+        print("      Trying streaming mode as fallback...")
+        try:
+            ds = load_dataset(DATASET_ID, streaming=True)
+            print("      SUCCESS (streaming): Dataset loaded")
+            print(f"      Splits available: {list(ds.keys())}")
+        except Exception as e2:
+            print(f"      FATAL: Cannot load dataset: {e2}")
+            return 1
+
+    # =========================================================================
+    # PHASE 2: Inspect Schema (Features)
+    # =========================================================================
+    print("[2/4] Inspecting schema...")
+    print()
+
+    report_lines: list[str] = []
+    report_lines.append("=" * 70)
+    report_lines.append("ISLES24-MR-Lite Schema Discovery Report")
+    report_lines.append(f"Generated: {datetime.now().isoformat()}")
+    report_lines.append(f"Dataset: {DATASET_ID}")
+    report_lines.append("=" * 70)
+    report_lines.append("")
+
+    for split_name in ds:
+        split = ds[split_name]
+        report_lines.append(f"SPLIT: {split_name}")
+        report_lines.append("-" * 50)
+
+        # Get features/schema
+        if hasattr(split, "features"):
+            features = split.features
+            report_lines.append(
+                f"Number of rows: {len(split) if hasattr(split, '__len__') else 'unknown (streaming)'}"
+            )
+            report_lines.append("")
+            report_lines.append("FEATURES (columns):")
+            for feat_name, feat_type in features.items():
+                report_lines.append(f"  - {feat_name}: {feat_type}")
+            report_lines.append("")
+        else:
+            report_lines.append("  (No features metadata available)")
+            report_lines.append("")
+
+    print("      Schema extracted.")
+    print()
+
+    # =========================================================================
+    # PHASE 3: Sample Inspection (check actual data)
+    # =========================================================================
+    print("[3/4] Inspecting sample rows...")
+    print()
+
+    # Use the first available split (usually 'train')
+    main_split_name = next(iter(ds.keys()))
+    main_split = ds[main_split_name]
+
+    report_lines.append("=" * 70)
+    report_lines.append("SAMPLE DATA INSPECTION")
+    report_lines.append("=" * 70)
+    report_lines.append("")
+
+    # Check first 3 rows in detail
+    report_lines.append("First 3 rows (detailed):")
+    report_lines.append("-" * 50)
+
+    sample_count = 0
+    column_value_types: dict[str, Counter[str]] = {}
+
+    # Iterate through dataset
+    iterable = iter(main_split) if hasattr(main_split, "__iter__") else main_split
+
+    for i, row in enumerate(iterable):
+        if i < 3:
+            report_lines.append(f"\nROW {i}:")
+            for key, val in row.items():
+                val_type = safe_type_name(val)
+                val_repr = safe_repr(val)
+                report_lines.append(f"  {key}:")
+                report_lines.append(f"    type: {val_type}")
+                report_lines.append(f"    value: {val_repr}")
+
+        # Track types for all rows
+        for key, val in row.items():
+            if key not in column_value_types:
+                column_value_types[key] = Counter()
+            column_value_types[key][safe_type_name(val)] += 1
+
+        sample_count += 1
+
+        # Progress indicator
+        if sample_count % 50 == 0:
+            print(f"      Processed {sample_count} rows...")
+
+    print(f"      Total rows processed: {sample_count}")
+    print()
+
+    # =========================================================================
+    # PHASE 4: Consistency Check
+    # =========================================================================
+    print("[4/4] Checking consistency across all rows...")
+    print()
+
+    report_lines.append("")
+    report_lines.append("=" * 70)
+    report_lines.append("CONSISTENCY ANALYSIS (all rows)")
+    report_lines.append("=" * 70)
+    report_lines.append("")
+    report_lines.append(f"Total rows analyzed: {sample_count}")
+    report_lines.append("")
+
+    report_lines.append("Column type distribution:")
+    report_lines.append("-" * 50)
+    for col_name, type_counts in column_value_types.items():
+        report_lines.append(f"\n  {col_name}:")
+        for type_name, count in type_counts.most_common():
+            pct = (count / sample_count) * 100
+            report_lines.append(f"    {type_name}: {count} ({pct:.1f}%)")
+
+    # =========================================================================
+    # PHASE 5: CaseAdapter Compatibility Check
+    # =========================================================================
+    report_lines.append("")
+    report_lines.append("=" * 70)
+    report_lines.append("CASEADAPTER COMPATIBILITY CHECK")
+    report_lines.append("=" * 70)
+    report_lines.append("")
+
+    expected_columns = ["dwi", "adc", "flair", "mask", "ground_truth", "participant_id"]
+    actual_columns = list(column_value_types.keys())
+
+    report_lines.append("Expected by CaseAdapter:")
+    for col in expected_columns:
+        status = "FOUND" if col in actual_columns else "MISSING"
+        report_lines.append(f"  {col}: {status}")
+
+    report_lines.append("")
+    report_lines.append("Actual columns in dataset:")
+    for col in actual_columns:
+        expected = "expected" if col in expected_columns else "UNEXPECTED"
+        report_lines.append(f"  {col}: {expected}")
+
+    report_lines.append("")
+    report_lines.append("=" * 70)
+    report_lines.append("END OF REPORT")
+    report_lines.append("=" * 70)
+
+    # Write report
+    report_content = "\n".join(report_lines)
+    REPORT_FILE.write_text(report_content)
+
+    print(f"Report written to: {REPORT_FILE}")
+    print()
+    print("=" * 70)
+    print("DISCOVERY COMPLETE")
+    print("=" * 70)
+    print()
+    print("Next steps:")
+    print(f"  1. Review: {REPORT_FILE}")
+    print("  2. Compare findings against src/stroke_deepisles_demo/data/adapter.py")
+    print("  3. Update adapter if schema differs from expectations")
+    print()
+
+    # Print summary to stdout as well
+    print("-" * 70)
+    print("QUICK SUMMARY:")
+    print("-" * 70)
+    print(f"Columns found: {actual_columns}")
+    print()
+    missing = [c for c in expected_columns if c not in actual_columns]
+    if missing:
+        print(f"WARNING: Expected columns MISSING: {missing}")
+    unexpected = [c for c in actual_columns if c not in expected_columns]
+    if unexpected:
+        print(f"NOTE: Unexpected columns found: {unexpected}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/stroke_deepisles_demo/core/exceptions.py

@@ -21,3 +21,7 @@ class DeepISLESError(StrokeDemoError):
 
 class MissingInputError(StrokeDemoError):
     """Required input files are missing."""
+
+
+class DockerGPUNotAvailableError(StrokeDemoError):
+    """GPU requested but NVIDIA Container Runtime not available."""

src/stroke_deepisles_demo/data/__init__.py

@@ -1,27 +1,21 @@
 """Data loading and case management for stroke-deepisles-demo."""
 
-from stroke_deepisles_demo.data.adapter import CaseAdapter
-from stroke_deepisles_demo.data.loader import DatasetInfo, get_dataset_info, load_isles_dataset
+from stroke_deepisles_demo.core.types import CaseFiles
+from stroke_deepisles_demo.data.adapter import LocalDataset
+from stroke_deepisles_demo.data.loader import DatasetInfo, load_isles_dataset
 from stroke_deepisles_demo.data.staging import StagedCase, stage_case_for_deepisles
 
 __all__ = [
-    # Adapter
-    "CaseAdapter",
-    # Loader
     "DatasetInfo",
-    # Staging
+    "LocalDataset",
     "StagedCase",
     "get_case",
-    "get_dataset_info",
     "list_case_ids",
     "load_isles_dataset",
     "stage_case_for_deepisles",
 ]
 
 
-from stroke_deepisles_demo.core.types import CaseFiles
-
-
 # Convenience functions (combine loader + adapter)
 def get_case(case_id: str | int) -> CaseFiles:
     """
@@ -31,12 +25,10 @@ def get_case(case_id: str | int) -> CaseFiles:
         CaseFiles dictionary
     """
     dataset = load_isles_dataset()
-    adapter = CaseAdapter(dataset)
-    return adapter.get_case(case_id)
+    return dataset.get_case(case_id)
 
 
 def list_case_ids() -> list[str]:
     """List all available case IDs."""
     dataset = load_isles_dataset()
-    adapter = CaseAdapter(dataset)
-    return adapter.list_case_ids()
+    return dataset.list_case_ids()

src/stroke_deepisles_demo/data/adapter.py

@@ -1,147 +1,84 @@
-"""Adapt HF dataset rows to typed file references."""
+"""Provide typed access to ISLES24 cases."""
 
 from __future__ import annotations
 
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-from stroke_deepisles_demo.core.exceptions import DataLoadError
-from stroke_deepisles_demo.core.types import CaseFiles
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from collections.abc import Iterator
+    from pathlib import Path
 
-    from datasets import Dataset
+    from stroke_deepisles_demo.core.types import CaseFiles
 
 
-class CaseAdapter:
-    """
-    Adapts HuggingFace dataset to provide typed access to case files.
+@dataclass
+class LocalDataset:
+    """File-based dataset for local ISLES24 data."""
 
-    This handles the mapping between HF dataset structure and our
-    internal CaseFiles type.
-    """
-
-    def __init__(self, dataset: Dataset) -> None:
-        """
-        Initialize adapter with a loaded dataset.
-
-        Args:
-            dataset: HuggingFace Dataset with NIfTI files
-        """
-        self.dataset = dataset
-        self._case_id_map = self._build_case_id_map()
-
-    def _build_case_id_map(self) -> dict[str, int]:
-        """Build mapping from case ID to index."""
-        case_map = {}
-        # Assuming dataset has 'participant_id' or similar
-        # If not, we might need to generate IDs or use index
-
-        # Check features to find ID column
-        id_col = "participant_id"
-        if id_col not in self.dataset.features:
-            # Fallback: try to find a string column that looks like an ID
-            # Or just use f"case_{i}"
-            pass
-
-        # Iterate to build map
-        # This might be slow for huge datasets, but for 149 cases it's fine
-        for idx, row in enumerate(self.dataset):
-            case_id = row.get(id_col, f"case_{idx:03d}")
-            case_map[str(case_id)] = idx
-
-        return case_map
+    data_dir: Path
+    cases: dict[str, CaseFiles]  # subject_id -> files
 
     def __len__(self) -> int:
-        """Return number of cases in the dataset."""
-        return len(self.dataset)
+        return len(self.cases)
 
     def __iter__(self) -> Iterator[str]:
-        """Iterate over case IDs."""
-        return iter(self._case_id_map.keys())
+        return iter(self.cases.keys())
 
     def list_case_ids(self) -> list[str]:
-        """
-        List all available case identifiers.
-
-        Returns:
-            List of case IDs (e.g., ["sub-001", "sub-002", ...])
-        """
-        return list(self._case_id_map.keys())
+        """Return sorted list of subject IDs."""
+        return sorted(self.cases.keys())
 
     def get_case(self, case_id: str | int) -> CaseFiles:
-        """
-        Get file paths for a specific case.
+        """Get files for a case by ID or index."""
+        if isinstance(case_id, int):
+            case_id = self.list_case_ids()[case_id]
+        return self.cases[case_id]
 
-        Args:
-            case_id: Either a string ID (e.g., "sub-001") or integer index
 
-        Returns:
-            CaseFiles with paths to DWI, ADC, and optionally ground truth
+# Subject ID extraction
+SUBJECT_PATTERN = re.compile(r"sub-(stroke\d{4})_ses-\d+_.*\.nii\.gz")
 
-        Raises:
-            KeyError: If case_id not found
-            DataLoadError: If files cannot be accessed
-        """
-        if isinstance(case_id, int):
-            index = case_id
-        else:
-            if case_id not in self._case_id_map:
-                raise KeyError(f"Case ID not found: {case_id}")
-            index = self._case_id_map[case_id]
-
-        return self._get_case_by_index_internal(index)
-
-    def get_case_by_index(self, index: int) -> tuple[str, CaseFiles]:
-        """
-        Get case by numerical index.
-
-        Returns:
-            Tuple of (case_id, CaseFiles)
-        """
-        if index < 0 or index >= len(self.dataset):
-            raise IndexError("Case index out of range")
-
-        # Find ID for index (reverse lookup)
-        # This is inefficient O(N) if we don't store reverse map, but N is small.
-        # Or we can just get it from row again.
-        row = self.dataset[index]
-        # Assuming 'participant_id' exists or we used fallback
-        case_id = row.get("participant_id", f"case_{index:03d}")
-
-        case_files = self._row_to_case_files(row)
-        return str(case_id), case_files
-
-    def _get_case_by_index_internal(self, index: int) -> CaseFiles:
-        """Internal helper to get CaseFiles by index."""
-        row = self.dataset[index]
-        return self._row_to_case_files(row)
-
-    def _row_to_case_files(self, row: dict[str, Any]) -> CaseFiles:
-        """Convert a dataset row to CaseFiles."""
-        # Map columns. DeepISLES needs DWI and ADC.
-        # Dataset columns might vary. Based on spec/mock: 'dwi', 'adc', 'flair', 'mask'
-
-        # Helper to ensure we return Path if it's a local string path, or keep as is
-        def to_path_or_raw(val: Any) -> Any:
-            if isinstance(val, str) and not val.startswith(("http://", "https://")):
-                return Path(val)
-            return val
-
-        dwi = to_path_or_raw(row.get("dwi"))
-        adc = to_path_or_raw(row.get("adc"))
-        flair = to_path_or_raw(row.get("flair"))
-        ground_truth = to_path_or_raw(row.get("mask") or row.get("ground_truth"))
-
-        if not dwi or not adc:
-            raise DataLoadError("Case missing required DWI or ADC files")
-
-        case_files = CaseFiles(dwi=dwi, adc=adc)
-
-        if flair:
-            case_files["flair"] = flair
-        if ground_truth:
-            case_files["ground_truth"] = ground_truth
-
-        return case_files
+
+def parse_subject_id(filename: str) -> str | None:
+    """Extract subject ID from BIDS filename."""
+    match = SUBJECT_PATTERN.match(filename)
+    return f"sub-{match.group(1)}" if match else None
+
+
+def build_local_dataset(data_dir: Path) -> LocalDataset:
+    """
+    Scan directory and build case mapping.
+
+    Matches DWI + ADC + Mask files by subject ID.
+    """
+    dwi_dir = data_dir / "Images-DWI"
+    adc_dir = data_dir / "Images-ADC"
+    mask_dir = data_dir / "Masks"
+
+    cases: dict[str, CaseFiles] = {}
+
+    # 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:
+            continue
+
+        # Find matching ADC and Mask
+        adc_file = adc_dir / dwi_file.name.replace("_dwi.", "_adc.")
+        mask_file = mask_dir / dwi_file.name.replace("_dwi.", "_lesion-msk.")
+
+        if not adc_file.exists():
+            continue  # Skip incomplete cases
+
+        case_files: CaseFiles = {
+            "dwi": dwi_file,
+            "adc": adc_file,
+        }
+        if mask_file.exists():
+            case_files["ground_truth"] = mask_file
+
+        cases[subject_id] = case_files
+
+    return LocalDataset(data_dir=data_dir, cases=cases)

src/stroke_deepisles_demo/data/loader.py

@@ -1,138 +1,47 @@
-"""Load ISLES24-MR-Lite dataset from HuggingFace Hub."""
+"""Load ISLES24 data from local directory or HuggingFace Hub."""
 
 from __future__ import annotations
 
 from dataclasses import dataclass
+from pathlib import Path
 from typing import TYPE_CHECKING
 
-from datasets import load_dataset
+if TYPE_CHECKING:
+    from stroke_deepisles_demo.data.adapter import LocalDataset
 
-from stroke_deepisles_demo.core.exceptions import DataLoadError
 
-if TYPE_CHECKING:
-    from pathlib import Path
+@dataclass
+class DatasetInfo:
+    """Metadata about the dataset."""
 
-    from datasets import Dataset
+    source: str  # "local" or HF dataset ID
+    num_cases: int
+    modalities: list[str]
+    has_ground_truth: bool
 
 
 def load_isles_dataset(
-    dataset_id: str = "YongchengYAO/ISLES24-MR-Lite",
+    source: str | Path = "data/scratch/isles24_extracted",
     *,
-    cache_dir: Path | None = None,
-    streaming: bool = False,
-) -> Dataset:
+    local_mode: bool = True,  # Default to local for now
+) -> LocalDataset:
     """
-    Load the ISLES24-MR-Lite dataset from HuggingFace Hub.
+    Load ISLES24 dataset.
 
     Args:
-        dataset_id: HuggingFace dataset identifier
-        cache_dir: Local cache directory (uses HF default if None)
-        streaming: If True, use streaming mode (lazy loading)
+        source: Local directory path or HuggingFace dataset ID
+        local_mode: If True, treat source as local directory
 
     Returns:
-        HuggingFace Dataset object with BIDS/NIfTI support
+        Dataset-like object providing case access
 
     Raises:
-        DataLoadError: If dataset cannot be loaded
+        NotImplementedError: If non-local mode is requested
     """
-    try:
-        # The pinned fork supports BIDS/NIfTI properly.
-        # We pass trust_remote_code=True if needed for custom scripts,
-        # but standard datasets usually don't need it unless using custom builder.
-        # ISLES24-MR-Lite is likely a standard dataset or Parquet-based.
-        # If it's BIDS, we might need type="bids" if the PR features are used that way.
-        # For now, standard load_dataset.
-
-        ds = load_dataset(
-            dataset_id,
-            cache_dir=str(cache_dir) if cache_dir else None,
-            streaming=streaming,
-            # If the dataset is BIDS, we might need a specific config/builder.
-            # Assuming default works or it's already parquet.
-        )
-
-        # If streaming, load_dataset returns IterableDataset.
-        # If not, it returns DatasetDict or Dataset.
-        # We assume it returns the 'train' split if it's a DatasetDict, or we handle it.
-        # Usually load_dataset returns DatasetDict unless split is specified.
-
-        if hasattr(ds, "keys"):
-            keys = list(ds.keys())
-            if "train" in keys:
-                return ds["train"]
-            elif len(keys) > 0:
-                # Fallback to first split if 'train' not found
-                return ds[keys[0]]
-
-        return ds
-
-    except Exception as e:
-        raise DataLoadError(f"Failed to load dataset {dataset_id}: {e}") from e
-
-
-@dataclass
-class DatasetInfo:
-    """Metadata about the loaded dataset."""
-
-    dataset_id: str
-    num_cases: int
-    modalities: list[str]  # e.g., ["dwi", "adc", "mask"]
-    has_ground_truth: bool
-
-
-def get_dataset_info(dataset_id: str = "YongchengYAO/ISLES24-MR-Lite") -> DatasetInfo:
-    """
-    Get metadata about the dataset without downloading (if possible).
-
-    Returns:
-        DatasetInfo with case count, available modalities, etc.
-    """
-    try:
-        # Load in streaming mode to get features/info cheaply
-        ds = load_isles_dataset(dataset_id, streaming=True)
-
-        # Count cases (might be slow for streaming, but okay for demo scale)
-        # Or check if info is available
-        if hasattr(ds, "info") and ds.info.splits:
-            # Approximate from splits info if available
-            num_cases = ds.info.splits["train"].num_examples
-        else:
-            # Iterate to count? Or just rely on known size?
-            # For streaming, len() might not work.
-            # Let's just load non-streaming but with no data download? No.
-            # Let's just assume we can get length if we loaded it.
-            # If we loaded it streaming, we might not get length.
-            # For the demo, let's just try to get it.
-
-            # If we can't get length easily from streaming, we might need to trust metadata.
-            # Or just iterate (expensive).
-            # Let's use a safer approach: load non-streaming (lazy) might download metadata only.
-            # But datasets downloads parquet files.
-
-            # For get_dataset_info, maybe we just load it fully? No, expensive.
-            # Let's use streaming and try to get info.
-            num_cases = 0
-            # Use a fixed number if we can't determine?
-            # Or just count - 149 is small.
-            # But streaming iteration means network calls.
-
-            # Try to access info object
-            if hasattr(ds, "n_shards"):
-                # Approximate?
-                pass
-
-            # Fallback: 149 (known)
-            num_cases = 149
+    if local_mode or isinstance(source, Path):
+        from stroke_deepisles_demo.data.adapter import build_local_dataset
 
-        features = ds.features.keys()
-        modalities = [k for k in features if k in ["dwi", "adc", "flair"]]
-        has_ground_truth = "mask" in features or "ground_truth" in features
+        return build_local_dataset(Path(source))
 
-        return DatasetInfo(
-            dataset_id=dataset_id,
-            num_cases=num_cases,
-            modalities=sorted(modalities),
-            has_ground_truth=has_ground_truth,
-        )
-    except Exception as e:
-        raise DataLoadError(f"Failed to get info for {dataset_id}: {e}") from e
+    # Future: return _load_from_huggingface(source)
+    raise NotImplementedError("HuggingFace mode not yet implemented")

src/stroke_deepisles_demo/inference/__init__.py

@@ -1 +1,37 @@
-"""DeepISLES inference module for stroke-deepisles-demo."""
+"""Inference module for stroke-deepisles-demo."""
+
+from stroke_deepisles_demo.inference.deepisles import (
+    DEEPISLES_IMAGE,
+    DeepISLESResult,
+    find_prediction_mask,
+    run_deepisles_on_folder,
+    validate_input_folder,
+)
+from stroke_deepisles_demo.inference.docker import (
+    DockerRunResult,
+    build_docker_command,
+    check_docker_available,
+    check_nvidia_docker_available,
+    ensure_docker_available,
+    ensure_gpu_available_if_requested,
+    pull_image_if_missing,
+    run_container,
+)
+
+__all__ = [
+    # DeepISLES
+    "DEEPISLES_IMAGE",
+    "DeepISLESResult",
+    # Docker utilities
+    "DockerRunResult",
+    "build_docker_command",
+    "check_docker_available",
+    "check_nvidia_docker_available",
+    "ensure_docker_available",
+    "ensure_gpu_available_if_requested",
+    "find_prediction_mask",
+    "pull_image_if_missing",
+    "run_container",
+    "run_deepisles_on_folder",
+    "validate_input_folder",
+]

src/stroke_deepisles_demo/inference/deepisles.py

@@ -0,0 +1,193 @@
+"""DeepISLES stroke segmentation wrapper."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
+from stroke_deepisles_demo.inference.docker import (
+    DockerRunResult,
+    ensure_gpu_available_if_requested,
+    run_container,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+# Constants
+DEEPISLES_IMAGE = "isleschallenge/deepisles"
+EXPECTED_INPUT_FILES = ["dwi.nii.gz", "adc.nii.gz"]
+OPTIONAL_INPUT_FILES = ["flair.nii.gz"]
+
+
+@dataclass(frozen=True)
+class DeepISLESResult:
+    """Result of DeepISLES inference."""
+
+    prediction_path: Path
+    docker_result: DockerRunResult
+    elapsed_seconds: float
+
+
+def validate_input_folder(input_dir: Path) -> tuple[Path, Path, Path | None]:
+    """
+    Validate that input folder contains required files.
+
+    Args:
+        input_dir: Directory to validate
+
+    Returns:
+        Tuple of (dwi_path, adc_path, flair_path_or_none)
+
+    Raises:
+        MissingInputError: If required files are missing
+    """
+    dwi_path = input_dir / "dwi.nii.gz"
+    adc_path = input_dir / "adc.nii.gz"
+    flair_path = input_dir / "flair.nii.gz"
+
+    if not dwi_path.exists():
+        raise MissingInputError(f"Required file 'dwi.nii.gz' not found in {input_dir}")
+
+    if not adc_path.exists():
+        raise MissingInputError(f"Required file 'adc.nii.gz' not found in {input_dir}")
+
+    return dwi_path, adc_path, flair_path if flair_path.exists() else None
+
+
+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.
+
+    Args:
+        output_dir: DeepISLES output directory
+
+    Returns:
+        Path to the prediction mask NIfTI file
+
+    Raises:
+        DeepISLESError: If no prediction mask found
+    """
+    results_dir = output_dir / "results"
+
+    # Check common output patterns
+    possible_names = [
+        "prediction.nii.gz",
+        "pred.nii.gz",
+        "lesion_mask.nii.gz",
+        "output.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"))
+        if nifti_files:
+            return nifti_files[0]
+
+    raise DeepISLESError(
+        f"No prediction mask found in {results_dir}. "
+        "Expected files like 'prediction.nii.gz' or similar."
+    )
+
+
+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.
+
+    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
+    """
+    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",
+        "dwi.nii.gz",
+        "--adc_file_name",
+        "adc.nii.gz",
+    ]
+
+    if flair_path is not None:
+        command.extend(["--flair_file_name", "flair.nii.gz"])
+
+    if fast:
+        command.extend(["--fast", "True"])
+
+    # Set up volume mounts
+    volumes = {
+        input_dir.resolve(): "/input",
+        output_dir.resolve(): "/output",
+    }
+
+    # Run the container
+    docker_result = run_container(
+        DEEPISLES_IMAGE,
+        command=command,
+        volumes=volumes,
+        gpu=gpu,
+        timeout=timeout,
+    )
+
+    # Check for failure
+    if docker_result.exit_code != 0:
+        raise DeepISLESError(
+            f"DeepISLES inference failed with exit code {docker_result.exit_code}. "
+            f"stderr: {docker_result.stderr}"
+        )
+
+    # Find the prediction mask
+    prediction_path = find_prediction_mask(output_dir)
+
+    elapsed = time.time() - start_time
+
+    return DeepISLESResult(
+        prediction_path=prediction_path,
+        docker_result=docker_result,
+        elapsed_seconds=elapsed,
+    )

src/stroke_deepisles_demo/inference/docker.py

@@ -0,0 +1,258 @@
+"""Docker execution utilities."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from stroke_deepisles_demo.core.exceptions import (
+    DockerGPUNotAvailableError,
+    DockerNotAvailableError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DockerRunResult:
+    """Result of a Docker container run."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    elapsed_seconds: float
+
+
+def check_docker_available() -> bool:
+    """
+    Check if Docker is installed and the daemon is running.
+
+    Returns:
+        True if Docker is available, False otherwise
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            capture_output=True,
+            timeout=10,
+            check=False,
+        )
+        return result.returncode == 0
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return False
+
+
+def ensure_docker_available() -> None:
+    """
+    Ensure Docker is available, raising if not.
+
+    Raises:
+        DockerNotAvailableError: If Docker is not installed or not running
+    """
+    if not check_docker_available():
+        raise DockerNotAvailableError(
+            "Docker is not available. Please ensure Docker is installed and running."
+        )
+
+
+def check_nvidia_docker_available() -> bool:
+    """
+    Check if NVIDIA Container Runtime is available for GPU support.
+
+    Returns:
+        True if nvidia-docker/nvidia-container-toolkit is configured
+    """
+    try:
+        result = subprocess.run(
+            [
+                "docker",
+                "run",
+                "--rm",
+                "--gpus",
+                "all",
+                "nvidia/cuda:11.0-base",
+                "nvidia-smi",
+            ],
+            capture_output=True,
+            timeout=30,
+            check=False,
+        )
+        return result.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def ensure_gpu_available_if_requested(gpu: bool) -> None:
+    """
+    Verify GPU is available if requested.
+
+    Args:
+        gpu: Whether GPU was requested
+
+    Raises:
+        DockerGPUNotAvailableError: If GPU requested but not available
+    """
+    if gpu and not check_nvidia_docker_available():
+        raise DockerGPUNotAvailableError(
+            "GPU requested but NVIDIA Container Runtime not available. "
+            "Either install nvidia-container-toolkit or set gpu=False."
+        )
+
+
+def pull_image_if_missing(image: str, *, timeout: float = 600) -> bool:
+    """
+    Pull a Docker image if not present locally.
+
+    Args:
+        image: Docker image name (e.g., "isleschallenge/deepisles")
+        timeout: Maximum seconds to wait for pull
+
+    Returns:
+        True if image was pulled, False if already present
+    """
+    # Check if image exists locally
+    result = subprocess.run(
+        ["docker", "image", "inspect", image],
+        capture_output=True,
+        timeout=10,
+        check=False,
+    )
+    if result.returncode == 0:
+        return False  # Image already present
+
+    # Pull the image
+    subprocess.run(
+        ["docker", "pull", image],
+        capture_output=True,
+        timeout=timeout,
+        check=True,
+    )
+    return True
+
+
+def build_docker_command(
+    image: str,
+    *,
+    command: Sequence[str] | None = None,
+    volumes: dict[Path, str] | None = None,
+    environment: dict[str, str] | None = None,
+    gpu: bool = False,
+    remove: bool = True,
+    match_user: bool = True,
+) -> list[str]:
+    """
+    Build the docker run command without executing.
+
+    Args:
+        image: Docker image name
+        command: Command to run in container
+        volumes: Volume mounts (host path -> container path)
+        environment: Environment variables
+        gpu: If True, pass --gpus all
+        remove: If True, remove container after exit (--rm)
+        match_user: If True, match host user (Linux only)
+
+    Returns:
+        List of command arguments for subprocess
+    """
+    cmd: list[str] = ["docker", "run"]
+
+    if remove:
+        cmd.append("--rm")
+
+    if gpu:
+        cmd.extend(["--gpus", "all"])
+
+    # Match host user to avoid permission issues (Linux only).
+    # Guard against platforms (e.g. Windows, macOS) where os.getuid()/getgid()
+    # are absent or not meaningful.
+    if match_user:
+        import os
+
+        if (
+            os.name == "posix"
+            and sys.platform != "darwin"
+            and hasattr(os, "getuid")
+            and hasattr(os, "getgid")
+        ):
+            uid = os.getuid()
+            gid = os.getgid()
+            cmd.extend(["--user", f"{uid}:{gid}"])
+
+    if volumes:
+        for host_path, container_path in volumes.items():
+            cmd.extend(["-v", f"{host_path}:{container_path}"])
+
+    if environment:
+        for key, value in environment.items():
+            cmd.extend(["-e", f"{key}={value}"])
+
+    cmd.append(image)
+
+    if command:
+        cmd.extend(command)
+
+    return cmd
+
+
+def run_container(
+    image: str,
+    *,
+    command: Sequence[str] | None = None,
+    volumes: dict[Path, str] | None = None,
+    environment: dict[str, str] | None = None,
+    gpu: bool = False,
+    remove: bool = True,
+    timeout: float | None = None,
+) -> DockerRunResult:
+    """
+    Run a Docker container and wait for completion.
+
+    Args:
+        image: Docker image name
+        command: Command to run in container
+        volumes: Volume mounts (host path -> container path)
+        environment: Environment variables
+        gpu: If True, pass --gpus all
+        remove: If True, remove container after exit (--rm)
+        timeout: Maximum seconds to wait (None = no timeout)
+
+    Returns:
+        DockerRunResult with exit code, stdout, stderr, elapsed time
+
+    Raises:
+        DockerNotAvailableError: If Docker is not available
+        subprocess.TimeoutExpired: If timeout exceeded
+    """
+    ensure_docker_available()
+
+    cmd = build_docker_command(
+        image,
+        command=command,
+        volumes=volumes,
+        environment=environment,
+        gpu=gpu,
+        remove=remove,
+    )
+
+    start_time = time.time()
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+    elapsed = time.time() - start_time
+
+    return DockerRunResult(
+        exit_code=result.returncode,
+        stdout=result.stdout,
+        stderr=result.stderr,
+        elapsed_seconds=elapsed,
+    )

tests/conftest.py

@@ -13,7 +13,7 @@ import pytest
 from stroke_deepisles_demo.core.types import CaseFiles
 
 if TYPE_CHECKING:
-    from collections.abc import Generator, Iterator
+    from collections.abc import Generator
 
 
 @pytest.fixture
@@ -62,30 +62,46 @@ def synthetic_case_files(temp_dir: Path) -> CaseFiles:
 
 
 @pytest.fixture
-def mock_hf_dataset(synthetic_case_files: CaseFiles) -> object:
-    """Create a mock HF Dataset-like object."""
-
-    # Simple list-based mock that mimics dataset behavior
-    class MockDataset:
-        def __init__(self) -> None:
-            self.data = [
-                {
-                    "participant_id": "sub-001",
-                    "dwi": str(synthetic_case_files["dwi"]),
-                    "adc": str(synthetic_case_files["adc"]),
-                    "flair": None,
-                    "mask": str(synthetic_case_files.get("ground_truth")),
-                }
-            ]
-            self.features = {"dwi": None, "adc": None, "flair": None, "mask": None}
-
-        def __len__(self) -> int:
-            return len(self.data)
-
-        def __getitem__(self, idx: int) -> dict[str, str | None]:
-            return self.data[idx]
-
-        def __iter__(self) -> Iterator[dict[str, str | None]]:
-            return iter(self.data)
-
-    return MockDataset()
+def synthetic_isles_dir(temp_dir: Path) -> Path:
+    """
+    Create synthetic ISLES24-like directory structure.
+
+    Structure:
+        temp_dir/
+        ├── Images-DWI/
+        │   ├── sub-stroke0001_ses-02_dwi.nii.gz
+        │   └── sub-stroke0002_ses-02_dwi.nii.gz
+        ├── Images-ADC/
+        │   ├── sub-stroke0001_ses-02_adc.nii.gz
+        │   └── sub-stroke0002_ses-02_adc.nii.gz
+        └── Masks/
+            ├── sub-stroke0001_ses-02_lesion-msk.nii.gz
+            └── sub-stroke0002_ses-02_lesion-msk.nii.gz
+    """
+    dwi_dir = temp_dir / "Images-DWI"
+    adc_dir = temp_dir / "Images-ADC"
+    mask_dir = temp_dir / "Masks"
+
+    dwi_dir.mkdir()
+    adc_dir.mkdir()
+    mask_dir.mkdir()
+
+    for subject_num in [1, 2]:
+        subject_id = f"sub-stroke{subject_num:04d}"
+
+        # Create DWI
+        dwi_data = np.random.rand(10, 10, 5).astype(np.float32)
+        dwi_img = nib.Nifti1Image(dwi_data, affine=np.eye(4))  # type: ignore
+        nib.save(dwi_img, dwi_dir / f"{subject_id}_ses-02_dwi.nii.gz")  # type: ignore
+
+        # Create ADC
+        adc_data = np.random.rand(10, 10, 5).astype(np.float32) * 2000
+        adc_img = nib.Nifti1Image(adc_data, affine=np.eye(4))  # type: ignore
+        nib.save(adc_img, adc_dir / f"{subject_id}_ses-02_adc.nii.gz")  # type: ignore
+
+        # Create Mask
+        mask_data = (np.random.rand(10, 10, 5) > 0.9).astype(np.uint8)
+        mask_img = nib.Nifti1Image(mask_data, affine=np.eye(4))  # type: ignore
+        nib.save(mask_img, mask_dir / f"{subject_id}_ses-02_lesion-msk.nii.gz")  # type: ignore
+
+    return temp_dir

tests/data/test_adapter.py

@@ -1,70 +1,94 @@
-"""Tests for case adapter module."""
+"""Tests for the data adapter."""
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-import pytest
-
-from stroke_deepisles_demo.data.adapter import CaseAdapter
+from stroke_deepisles_demo.data.adapter import (
+    LocalDataset,
+    build_local_dataset,
+    parse_subject_id,
+)
 
 if TYPE_CHECKING:
-    from unittest.mock import MagicMock
+    from pathlib import Path
+
+
+def test_parse_subject_id_extracts_correctly() -> None:
+    """Test extracting subject ID from BIDS filename."""
+    # Valid cases
+    assert parse_subject_id("sub-stroke0005_ses-02_dwi.nii.gz") == "sub-stroke0005"
+    assert parse_subject_id("sub-stroke0149_ses-02_adc.nii.gz") == "sub-stroke0149"
+    assert parse_subject_id("sub-stroke1234_ses-02_lesion-msk.nii.gz") == "sub-stroke1234"
+
+    # Invalid cases
+    assert parse_subject_id("random_file.nii.gz") is None
+    assert parse_subject_id("sub-strokeABC_ses-02_dwi.nii.gz") is None  # Non-digit ID
 
 
-class TestCaseAdapter:
-    """Tests for CaseAdapter."""
+def test_build_local_dataset_matches_files(synthetic_isles_dir: Path) -> None:
+    """Test that files are correctly matched by subject ID."""
+    dataset = build_local_dataset(synthetic_isles_dir)
 
-    def test_list_case_ids_returns_strings(self, mock_hf_dataset: MagicMock) -> None:
-        """list_case_ids returns list of string identifiers."""
-        adapter = CaseAdapter(mock_hf_dataset)
-        case_ids = adapter.list_case_ids()
+    assert isinstance(dataset, LocalDataset)
+    assert len(dataset) == 2  # synthetic_isles_dir creates 2 subjects
+    assert dataset.list_case_ids() == ["sub-stroke0001", "sub-stroke0002"]
 
-        assert isinstance(case_ids, list)
-        assert all(isinstance(cid, str) for cid in case_ids)
-        assert case_ids == ["sub-001"]
+    # Verify matching logic
+    case1 = dataset.get_case("sub-stroke0001")
+    assert case1["dwi"].name == "sub-stroke0001_ses-02_dwi.nii.gz"
+    assert case1["adc"].name == "sub-stroke0001_ses-02_adc.nii.gz"
+    assert case1["ground_truth"] is not None
+    assert case1["ground_truth"].name == "sub-stroke0001_ses-02_lesion-msk.nii.gz"
 
-    def test_len_matches_dataset_size(self, mock_hf_dataset: MagicMock) -> None:
-        """len(adapter) equals number of cases in dataset."""
-        adapter = CaseAdapter(mock_hf_dataset)
 
-        assert len(adapter) == len(mock_hf_dataset)
+def test_get_case_returns_case_files(synthetic_isles_dir: Path) -> None:
+    """Test retrieval of cases by ID and index."""
+    dataset = build_local_dataset(synthetic_isles_dir)
 
-    def test_get_case_by_string_id(self, mock_hf_dataset: MagicMock) -> None:
-        """Can retrieve case by string identifier."""
-        adapter = CaseAdapter(mock_hf_dataset)
-        case_ids = adapter.list_case_ids()
+    # By ID
+    case_by_id = dataset.get_case("sub-stroke0001")
+    assert isinstance(case_by_id, dict)
+    assert "dwi" in case_by_id
+    assert "adc" in case_by_id
 
-        case = adapter.get_case(case_ids[0])
+    # By Index
+    case_by_idx = dataset.get_case(0)
+    assert isinstance(case_by_idx, dict)
+    assert case_by_id == case_by_idx  # Should be the same case
 
-        assert isinstance(case, dict)
-        assert "dwi" in case
-        assert "adc" in case
-        # Paths should be Path objects or convertible
-        from pathlib import Path
 
-        assert isinstance(case["dwi"], (Path, str))
+def test_build_local_dataset_skips_incomplete(
+    synthetic_isles_dir: Path,
+) -> None:
+    """Test that incomplete cases (missing ADC) are skipped."""
+    # Delete ADC for subject 2
+    adc_file = synthetic_isles_dir / "Images-ADC" / "sub-stroke0002_ses-02_adc.nii.gz"
+    adc_file.unlink()
 
-    def test_get_case_by_index(self, mock_hf_dataset: MagicMock) -> None:
-        """Can retrieve case by integer index."""
-        adapter = CaseAdapter(mock_hf_dataset)
+    dataset = build_local_dataset(synthetic_isles_dir)
 
-        case_id, case = adapter.get_case_by_index(0)
+    # Subject 2 should be gone
+    assert len(dataset) == 1
+    assert dataset.list_case_ids() == ["sub-stroke0001"]
 
-        assert isinstance(case_id, str)
-        assert case["dwi"] is not None
 
-    def test_get_case_invalid_id_raises(self, mock_hf_dataset: MagicMock) -> None:
-        """Raises KeyError for invalid case ID."""
-        adapter = CaseAdapter(mock_hf_dataset)
+def test_build_local_dataset_handles_missing_mask(
+    synthetic_isles_dir: Path,
+) -> None:
+    """Test that missing mask results in ground_truth=None (if allowed)."""
+    # NOTE: Adapter currently allows missing mask?
+    # Spec says: "ground_truth=mask_file if mask_file.exists() else None"
+    # So yes, it should load but with None.
 
-        with pytest.raises(KeyError):
-            adapter.get_case("nonexistent-case-id")
+    # Delete Mask for subject 2
+    mask_file = synthetic_isles_dir / "Masks" / "sub-stroke0002_ses-02_lesion-msk.nii.gz"
+    mask_file.unlink()
 
-    def test_iteration(self, mock_hf_dataset: MagicMock) -> None:
-        """Can iterate over case IDs."""
-        adapter = CaseAdapter(mock_hf_dataset)
+    dataset = build_local_dataset(synthetic_isles_dir)
 
-        case_ids = list(adapter)
+    # Subject 2 should still exist
+    assert len(dataset) == 2
 
-        assert len(case_ids) == len(adapter)
+    case2 = dataset.get_case("sub-stroke0002")
+    assert case2.get("ground_truth") is None

tests/data/test_integration_real_data.py

@@ -0,0 +1,42 @@
+"""Integration tests with real ISLES24 data."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from stroke_deepisles_demo.data.loader import load_isles_dataset
+
+REAL_DATA_PATH = Path("data/scratch/isles24_extracted")
+
+
+@pytest.mark.skipif(not REAL_DATA_PATH.exists(), reason="Real data not found in data/scratch")
+def test_load_real_data_count() -> None:
+    """Verify that we can load the expected number of cases from real data."""
+    dataset = load_isles_dataset(source=REAL_DATA_PATH)
+
+    # We expect 149 cases based on schema report
+    assert len(dataset) == 149
+
+    # Check a specific known case
+    case = dataset.get_case("sub-stroke0005")
+    assert case["dwi"].name == "sub-stroke0005_ses-02_dwi.nii.gz"
+    assert case["dwi"].exists()
+    assert case["adc"].exists()
+    assert case["ground_truth"] is not None
+    assert case["ground_truth"].exists()
+
+
+@pytest.mark.skipif(not REAL_DATA_PATH.exists(), reason="Real data not found in data/scratch")
+def test_real_data_subject_ids() -> None:
+    """Verify subject ID formatting on real data."""
+    dataset = load_isles_dataset(source=REAL_DATA_PATH)
+    ids = dataset.list_case_ids()
+
+    assert len(ids) == 149
+    assert ids[0] == "sub-stroke0001"
+    # We know there are gaps, so just check the format
+    for subject_id in ids:
+        assert subject_id.startswith("sub-stroke")
+        assert len(subject_id) == len("sub-strokeXXXX")

tests/data/test_loader.py

@@ -1,90 +1,33 @@
-"""Tests for data loader module."""
+"""Tests for the data loader."""
 
 from __future__ import annotations
 
-from unittest.mock import MagicMock, patch
+from typing import TYPE_CHECKING
 
 import pytest
 
-from stroke_deepisles_demo.core.exceptions import DataLoadError
-from stroke_deepisles_demo.data.loader import (
-    DatasetInfo,
-    get_dataset_info,
-    load_isles_dataset,
-)
+from stroke_deepisles_demo.data.adapter import LocalDataset
+from stroke_deepisles_demo.data.loader import load_isles_dataset
 
+if TYPE_CHECKING:
+    from pathlib import Path
 
-class TestLoadIslesDataset:
-    """Tests for load_isles_dataset."""
 
-    def test_calls_hf_load_dataset(self) -> None:
-        """Calls datasets.load_dataset with correct arguments."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_load.return_value = MagicMock()
+def test_load_from_local_returns_local_dataset(synthetic_isles_dir: Path) -> None:
+    """Test that loading from local path returns a LocalDataset."""
+    dataset = load_isles_dataset(source=synthetic_isles_dir, local_mode=True)
+    assert isinstance(dataset, LocalDataset)
+    assert len(dataset) > 0
 
-            load_isles_dataset("test/dataset")
 
-            mock_load.assert_called_once()
-            call_args = mock_load.call_args
-            assert call_args.args[0] == "test/dataset"
+def test_load_from_local_finds_all_cases(synthetic_isles_dir: Path) -> None:
+    """Test that the loader correctly delegates finding cases to adapter."""
+    dataset = load_isles_dataset(source=synthetic_isles_dir)
+    assert len(dataset) == 2
+    assert dataset.list_case_ids() == ["sub-stroke0001", "sub-stroke0002"]
 
-    def test_returns_dataset_object(self) -> None:
-        """Returns the loaded Dataset object."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            expected = MagicMock()
-            mock_load.return_value = expected
 
-            result = load_isles_dataset()
-
-            assert result is expected
-
-    def test_handles_load_error(self) -> None:
-        """Wraps HF errors in DataLoadError."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_load.side_effect = Exception("Network error")
-
-            with pytest.raises(DataLoadError, match="Network error"):
-                load_isles_dataset()
-
-
-class TestGetDatasetInfo:
-    """Tests for get_dataset_info."""
-
-    def test_returns_datasetinfo(self) -> None:
-        """Returns DatasetInfo with expected fields."""
-        with patch("stroke_deepisles_demo.data.loader.load_dataset") as mock_load:
-            mock_ds = MagicMock()
-            mock_ds.__len__ = MagicMock(return_value=149)
-            # Mock info.splits['train'].num_examples
-            mock_ds.info.splits.__getitem__.return_value.num_examples = 149
-            # Mock features as dict-like
-            mock_ds.features = {"dwi": None, "adc": None, "mask": None}
-            mock_load.return_value = mock_ds
-
-            info = get_dataset_info()
-
-            assert isinstance(info, DatasetInfo)
-            assert info.num_cases == 149
-            assert "dwi" in info.modalities
-            assert info.has_ground_truth is True
-
-
-@pytest.mark.integration
-class TestLoadIslesDatasetIntegration:
-    """Integration tests that hit the real HuggingFace Hub."""
-
-    @pytest.mark.slow
-    def test_load_real_dataset(self) -> None:
-        """Actually loads ISLES24-MR-Lite from HF Hub."""
-        # This test requires network access
-        # Run with: pytest -m integration
-        # Using streaming=True to avoid downloading everything
-        try:
-            dataset = load_isles_dataset(streaming=True)
-            assert dataset is not None
-            # Verify we got metadata/features - this confirms connectivity
-            # Iterating might trigger heavy downloads or fail if dataset is empty/gated
-            assert hasattr(dataset, "features")
-            assert len(dataset.features) > 0
-        except Exception as e:
-            pytest.fail(f"Failed to load real dataset: {e}")
+def test_load_raises_not_implemented_for_hf() -> None:
+    """Test that HF mode raises NotImplementedError."""
+    with pytest.raises(NotImplementedError):
+        load_isles_dataset(source="fake/dataset", local_mode=False)

tests/inference/test_deepisles.py

@@ -0,0 +1,285 @@
+"""Tests for DeepISLES wrapper."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
+from stroke_deepisles_demo.inference.deepisles import (
+    DeepISLESResult,
+    find_prediction_mask,
+    run_deepisles_on_folder,
+    validate_input_folder,
+)
+
+
+class TestValidateInputFolder:
+    """Tests for validate_input_folder."""
+
+    def test_succeeds_with_required_files(self, temp_dir: Path) -> None:
+        """Returns paths when required files exist."""
+        (temp_dir / "dwi.nii.gz").touch()
+        (temp_dir / "adc.nii.gz").touch()
+
+        dwi, adc, flair = validate_input_folder(temp_dir)
+
+        assert dwi == temp_dir / "dwi.nii.gz"
+        assert adc == temp_dir / "adc.nii.gz"
+        assert flair is None
+
+    def test_includes_flair_when_present(self, temp_dir: Path) -> None:
+        """Returns FLAIR path when present."""
+        (temp_dir / "dwi.nii.gz").touch()
+        (temp_dir / "adc.nii.gz").touch()
+        (temp_dir / "flair.nii.gz").touch()
+
+        _dwi, _adc, flair = validate_input_folder(temp_dir)
+
+        assert flair == temp_dir / "flair.nii.gz"
+
+    def test_raises_when_dwi_missing(self, temp_dir: Path) -> None:
+        """Raises MissingInputError when DWI is missing."""
+        (temp_dir / "adc.nii.gz").touch()
+
+        with pytest.raises(MissingInputError, match="dwi"):
+            validate_input_folder(temp_dir)
+
+    def test_raises_when_adc_missing(self, temp_dir: Path) -> None:
+        """Raises MissingInputError when ADC is missing."""
+        (temp_dir / "dwi.nii.gz").touch()
+
+        with pytest.raises(MissingInputError, match="adc"):
+            validate_input_folder(temp_dir)
+
+
+class TestFindPredictionMask:
+    """Tests for find_prediction_mask."""
+
+    def test_finds_prediction_file(self, temp_dir: Path) -> None:
+        """Finds prediction.nii.gz in output directory."""
+        results_dir = temp_dir / "results"
+        results_dir.mkdir()
+        pred_file = results_dir / "prediction.nii.gz"
+        pred_file.touch()
+
+        result = find_prediction_mask(temp_dir)
+
+        assert result == pred_file
+
+    def test_finds_alternate_name(self, temp_dir: Path) -> None:
+        """Finds alternate named prediction files."""
+        results_dir = temp_dir / "results"
+        results_dir.mkdir()
+        pred_file = results_dir / "pred.nii.gz"
+        pred_file.touch()
+
+        result = find_prediction_mask(temp_dir)
+
+        assert result == pred_file
+
+    def test_falls_back_to_any_nifti(self, temp_dir: Path) -> None:
+        """Falls back to any .nii.gz file if standard names not found."""
+        results_dir = temp_dir / "results"
+        results_dir.mkdir()
+        pred_file = results_dir / "some_output.nii.gz"
+        pred_file.touch()
+
+        result = find_prediction_mask(temp_dir)
+
+        assert result == pred_file
+
+    def test_raises_when_no_prediction(self, temp_dir: Path) -> None:
+        """Raises DeepISLESError when no prediction found."""
+        results_dir = temp_dir / "results"
+        results_dir.mkdir()
+
+        with pytest.raises(DeepISLESError, match="prediction"):
+            find_prediction_mask(temp_dir)
+
+    def test_raises_when_results_dir_missing(self, temp_dir: Path) -> None:
+        """Raises DeepISLESError when results directory missing."""
+        with pytest.raises(DeepISLESError, match="prediction"):
+            find_prediction_mask(temp_dir)
+
+
+class TestRunDeepIslesOnFolder:
+    """Tests for run_deepisles_on_folder."""
+
+    @pytest.fixture
+    def valid_input_dir(self, temp_dir: Path) -> Path:
+        """Create a valid input directory with required files."""
+        (temp_dir / "dwi.nii.gz").touch()
+        (temp_dir / "adc.nii.gz").touch()
+        return temp_dir
+
+    def test_validates_input_files(self, temp_dir: Path) -> None:
+        """Validates input files before running Docker."""
+        # Missing required files
+        with pytest.raises(MissingInputError):
+            run_deepisles_on_folder(temp_dir)
+
+    def test_calls_docker_with_correct_image(self, valid_input_dir: Path) -> None:
+        """Calls Docker with DeepISLES image."""
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
+                ) as mock_find,
+            ):
+                mock_find.return_value = valid_input_dir / "results" / "pred.nii.gz"
+                run_deepisles_on_folder(valid_input_dir)
+
+            # Check image name
+            call_args = mock_run.call_args
+            assert call_args.args[0] == "isleschallenge/deepisles"
+
+    def test_passes_fast_flag(self, valid_input_dir: Path) -> None:
+        """Passes --fast True when fast=True."""
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
+                ) as mock_find,
+            ):
+                mock_find.return_value = valid_input_dir / "results" / "pred.nii.gz"
+
+                run_deepisles_on_folder(valid_input_dir, fast=True)
+
+            # Check --fast in command
+            call_kwargs = mock_run.call_args.kwargs
+            command = call_kwargs.get("command", [])
+            assert "--fast" in command
+            assert "True" in command
+
+    def test_includes_flair_when_present(self, valid_input_dir: Path) -> None:
+        """Includes FLAIR in command when present."""
+        (valid_input_dir / "flair.nii.gz").touch()
+
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
+                ) as mock_find,
+            ):
+                mock_find.return_value = valid_input_dir / "results" / "pred.nii.gz"
+
+                run_deepisles_on_folder(valid_input_dir)
+
+            call_kwargs = mock_run.call_args.kwargs
+            command = call_kwargs.get("command", [])
+            assert "--flair_file_name" in command
+            assert "flair.nii.gz" in command
+
+    def test_raises_on_docker_failure(self, valid_input_dir: Path) -> None:
+        """Raises DeepISLESError when Docker returns non-zero."""
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(exit_code=1, stdout="", stderr="Segmentation fault")
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                pytest.raises(DeepISLESError, match="failed"),
+            ):
+                run_deepisles_on_folder(valid_input_dir)
+
+    def test_returns_result_with_prediction_path(self, valid_input_dir: Path) -> None:
+        """Returns DeepISLESResult with prediction path."""
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(
+                exit_code=0, stdout="", stderr="", elapsed_seconds=10.0
+            )
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
+                ) as mock_find,
+            ):
+                expected_path = valid_input_dir / "results" / "prediction.nii.gz"
+                mock_find.return_value = expected_path
+
+                result = run_deepisles_on_folder(valid_input_dir)
+
+            assert isinstance(result, DeepISLESResult)
+            assert result.prediction_path == expected_path
+
+    def test_passes_volume_mounts(self, valid_input_dir: Path, temp_dir: Path) -> None:
+        """Passes correct volume mounts to Docker."""
+        # Create a separate output directory
+        output_dir = temp_dir / "output"
+        output_dir.mkdir()
+
+        with patch("stroke_deepisles_demo.inference.deepisles.run_container") as mock_run:
+            mock_run.return_value = MagicMock(exit_code=0, stdout="", stderr="")
+            with (
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.ensure_gpu_available_if_requested"
+                ),
+                patch(
+                    "stroke_deepisles_demo.inference.deepisles.find_prediction_mask"
+                ) as mock_find,
+            ):
+                mock_find.return_value = output_dir / "results" / "pred.nii.gz"
+
+                run_deepisles_on_folder(valid_input_dir, output_dir=output_dir)
+
+            call_kwargs = mock_run.call_args.kwargs
+            volumes = call_kwargs.get("volumes", {})
+            # Should have input and output mounts (2 separate directories)
+            assert len(volumes) == 2
+            # Values should be container paths
+            assert "/input" in volumes.values()
+            assert "/output" in volumes.values()
+
+
+@pytest.mark.integration
+@pytest.mark.slow
+class TestDeepIslesIntegration:
+    """Integration tests requiring real Docker and DeepISLES image."""
+
+    def test_real_inference(self, synthetic_case_files: dict[str, object]) -> None:
+        """Run actual DeepISLES inference on synthetic data."""
+        # This test requires:
+        # 1. Docker available
+        # 2. isleschallenge/deepisles image pulled
+        # 3. GPU (optional but recommended)
+        #
+        # Run with: pytest -m integration
+        import tempfile
+
+        from stroke_deepisles_demo.data.staging import stage_case_for_deepisles
+
+        # Create a separate staging directory
+        with tempfile.TemporaryDirectory() as staging_dir:
+            # Stage the synthetic files to the new directory
+            staged = stage_case_for_deepisles(
+                synthetic_case_files,  # type: ignore[arg-type]
+                Path(staging_dir),
+            )
+
+            # Run inference
+            result = run_deepisles_on_folder(
+                staged.input_dir,
+                fast=True,
+                gpu=False,  # Might not have GPU in CI
+                timeout=600,
+            )
+
+            # Verify output exists
+            assert result.prediction_path.exists()

tests/inference/test_docker.py

@@ -0,0 +1,202 @@
+"""Tests for Docker utilities."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from stroke_deepisles_demo.core.exceptions import DockerNotAvailableError
+from stroke_deepisles_demo.inference.docker import (
+    build_docker_command,
+    check_docker_available,
+    ensure_docker_available,
+    run_container,
+)
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class TestCheckDockerAvailable:
+    """Tests for check_docker_available."""
+
+    def test_returns_true_when_docker_responds(self) -> None:
+        """Returns True when 'docker info' succeeds."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0)
+
+            result = check_docker_available()
+
+            assert result is True
+
+    def test_returns_false_when_docker_not_found(self) -> None:
+        """Returns False when docker command not found."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.side_effect = FileNotFoundError()
+
+            result = check_docker_available()
+
+            assert result is False
+
+    def test_returns_false_when_daemon_not_running(self) -> None:
+        """Returns False when docker daemon not running."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=1)
+
+            result = check_docker_available()
+
+            assert result is False
+
+
+class TestEnsureDockerAvailable:
+    """Tests for ensure_docker_available."""
+
+    def test_raises_when_docker_not_available(self) -> None:
+        """Raises DockerNotAvailableError when Docker not available."""
+        with (
+            patch(
+                "stroke_deepisles_demo.inference.docker.check_docker_available",
+                return_value=False,
+            ),
+            pytest.raises(DockerNotAvailableError),
+        ):
+            ensure_docker_available()
+
+    def test_no_error_when_docker_available(self) -> None:
+        """No exception when Docker is available."""
+        with patch(
+            "stroke_deepisles_demo.inference.docker.check_docker_available",
+            return_value=True,
+        ):
+            ensure_docker_available()  # Should not raise
+
+
+class TestBuildDockerCommand:
+    """Tests for build_docker_command."""
+
+    def test_basic_command(self) -> None:
+        """Builds basic docker run command."""
+        cmd = build_docker_command("myimage:latest")
+
+        assert cmd[0] == "docker"
+        assert "run" in cmd
+        assert "myimage:latest" in cmd
+
+    def test_includes_rm_flag(self) -> None:
+        """Includes --rm when remove=True."""
+        cmd = build_docker_command("myimage", remove=True)
+
+        assert "--rm" in cmd
+
+    def test_excludes_rm_flag(self) -> None:
+        """Excludes --rm when remove=False."""
+        cmd = build_docker_command("myimage", remove=False)
+
+        assert "--rm" not in cmd
+
+    def test_includes_gpu_flag(self) -> None:
+        """Includes --gpus all when gpu=True."""
+        cmd = build_docker_command("myimage", gpu=True)
+
+        assert "--gpus" in cmd
+        gpu_index = cmd.index("--gpus")
+        assert cmd[gpu_index + 1] == "all"
+
+    def test_volume_mounts(self, temp_dir: Path) -> None:
+        """Includes volume mounts."""
+        volumes = {temp_dir: "/data"}
+        cmd = build_docker_command("myimage", volumes=volumes)
+
+        assert "-v" in cmd
+        # Find the volume argument
+        v_index = cmd.index("-v")
+        assert f"{temp_dir}:/data" in cmd[v_index + 1]
+
+    def test_custom_command(self) -> None:
+        """Appends custom command arguments."""
+        cmd = build_docker_command("myimage", command=["--input", "/data", "--fast", "True"])
+
+        assert "--input" in cmd
+        assert "--fast" in cmd
+
+    def test_environment_variables(self) -> None:
+        """Includes environment variables."""
+        env = {"MY_VAR": "value", "OTHER": "123"}
+        cmd = build_docker_command("myimage", environment=env)
+
+        assert "-e" in cmd
+        # Check both vars are present
+        cmd_str = " ".join(cmd)
+        assert "MY_VAR=value" in cmd_str
+        assert "OTHER=123" in cmd_str
+
+
+class TestRunContainer:
+    """Tests for run_container."""
+
+    def test_calls_subprocess_with_built_command(self) -> None:
+        """Calls subprocess.run with built command."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="output", stderr="")
+            with patch("stroke_deepisles_demo.inference.docker.ensure_docker_available"):
+                run_container("myimage")
+
+            mock_run.assert_called_once()
+
+    def test_returns_result_with_exit_code(self) -> None:
+        """Returns DockerRunResult with correct exit code."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=42, stdout="out", stderr="err")
+            with patch("stroke_deepisles_demo.inference.docker.ensure_docker_available"):
+                result = run_container("myimage")
+
+            assert result.exit_code == 42
+
+    def test_captures_stdout_stderr(self) -> None:
+        """Captures stdout and stderr from container."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="hello", stderr="warning")
+            with patch("stroke_deepisles_demo.inference.docker.ensure_docker_available"):
+                result = run_container("myimage")
+
+            assert result.stdout == "hello"
+            assert result.stderr == "warning"
+
+    def test_respects_timeout(self) -> None:
+        """Passes timeout to subprocess."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+            with patch("stroke_deepisles_demo.inference.docker.ensure_docker_available"):
+                run_container("myimage", timeout=60.0)
+
+            call_kwargs = mock_run.call_args.kwargs
+            assert call_kwargs.get("timeout") == 60.0
+
+    def test_tracks_elapsed_time(self) -> None:
+        """Tracks elapsed time in result."""
+        with patch("subprocess.run") as mock_run:
+            mock_run.return_value = MagicMock(returncode=0, stdout="", stderr="")
+            with patch("stroke_deepisles_demo.inference.docker.ensure_docker_available"):
+                result = run_container("myimage")
+
+            # Should have some elapsed time (even if small)
+            assert result.elapsed_seconds >= 0
+
+
+@pytest.mark.integration
+class TestDockerIntegration:
+    """Integration tests requiring real Docker."""
+
+    def test_docker_actually_available(self) -> None:
+        """Docker is actually available on this system."""
+        # This test only runs with -m integration
+        assert check_docker_available() is True
+
+    def test_can_run_hello_world(self) -> None:
+        """Can run docker hello-world container."""
+        result = run_container("hello-world", timeout=60.0)
+
+        assert result.exit_code == 0
+        assert "Hello from Docker!" in result.stdout