fix(ui): lazy dataset loading to prevent HF Spaces timeout (#14)

* fix(ui): lazy load dataset to prevent HF Spaces startup timeout (P0)

Root Cause:
- `create_case_selector()` called `list_case_ids()` synchronously
- This triggered HuggingFace dataset download (~6-8 min for 149 cases)
- App failed to bind to port 7860 before HF Spaces health check timeout
- Container restarted repeatedly in a loop

Solution:
- `create_case_selector()` now returns empty dropdown immediately
- Added `initialize_case_selector()` in app.py for lazy loading
- `demo.load()` triggers data loading AFTER UI renders
- App binds to port 7860 instantly, user sees "Initializing dataset..."

Additional Fixes:
- Set `HF_HOME=/app/cache` in Dockerfile for writable cache directory
- Updated test to reflect lazy loading (no mock needed for create_app)
- Fixed lint issues (B008, W293)

Behavior Change:
- Before: Blank screen for 6-8 min, then restart loop
- After: UI loads instantly, dropdown shows "Initializing..." then populates

* fix: update dataset references from YongchengYAO to hugging-science

Replace all user-facing references to the old ISLES24-MR-Lite dataset
with the proper hugging-science/isles24-stroke dataset:
- UI markdown link and text
- Config default value
- .env.example
- Test assertion

.env.example

@@ -3,7 +3,7 @@ STROKE_DEMO_LOG_LEVEL=INFO
 STROKE_DEMO_LOG_FORMAT=simple
 
 # HuggingFace
-STROKE_DEMO_HF_DATASET_ID=YongchengYAO/ISLES24-MR-Lite
+STROKE_DEMO_HF_DATASET_ID=hugging-science/isles24-stroke
 # STROKE_DEMO_HF_TOKEN=hf_...
 
 # DeepISLES

Dockerfile

@@ -44,6 +44,8 @@ RUN pip install --no-cache-dir --no-deps -e .
 # This allows the app to detect runtime environment and use direct invocation
 ENV HF_SPACES=1
 ENV DEEPISLES_DIRECT_INVOCATION=1
+# Ensure HuggingFace cache uses our writable directory
+ENV HF_HOME=/app/cache
 
 # Create directories for data with proper permissions
 RUN mkdir -p /app/data /app/results /app/cache && \

src/stroke_deepisles_demo/core/config.py

@@ -76,7 +76,7 @@ class Settings(BaseSettings):
     log_format: Literal["simple", "detailed", "json"] = "simple"
 
     # HuggingFace
-    hf_dataset_id: str = "YongchengYAO/ISLES24-MR-Lite"
+    hf_dataset_id: str = "hugging-science/isles24-stroke"
     hf_cache_dir: Path | None = None
     hf_token: str | None = Field(default=None, repr=False)  # Hidden from logs
 

src/stroke_deepisles_demo/ui/app.py

@@ -9,6 +9,7 @@ import gradio as gr
 from matplotlib.figure import Figure  # noqa: TC002
 
 from stroke_deepisles_demo.core.logging import get_logger
+from stroke_deepisles_demo.data import list_case_ids
 from stroke_deepisles_demo.pipeline import run_pipeline_on_case
 from stroke_deepisles_demo.ui.components import (
     create_case_selector,
@@ -30,6 +31,31 @@ logger = get_logger(__name__)
 _previous_results_dir: Path | None = None
 
 
+def initialize_case_selector() -> gr.Dropdown:
+    """
+    Initialize case selector by loading dataset (lazy load).
+
+    This prevents the app from hanging during startup while downloading data.
+    Called via demo.load() after the UI renders.
+    """
+    try:
+        logger.info("Initializing dataset for case selector...")
+        case_ids = list_case_ids()
+
+        if not case_ids:
+            return gr.Dropdown(choices=[], info="No cases found in dataset.")
+
+        return gr.Dropdown(
+            choices=case_ids,
+            value=case_ids[0],
+            info="Choose a case from isles24-stroke dataset",
+            interactive=True,
+        )
+    except Exception as e:
+        logger.exception("Failed to initialize dataset")
+        return gr.Dropdown(choices=[], info=f"Error loading data: {e!s}")
+
+
 def run_segmentation(
     case_id: str, fast_mode: bool, show_ground_truth: bool
 ) -> tuple[str, Figure | None, dict[str, Any], str | None, str]:
@@ -139,7 +165,7 @@ def create_app() -> gr.Blocks:
 
         This demo runs [DeepISLES](https://github.com/ezequieldlrosa/DeepIsles)
         stroke segmentation on cases from
-        [ISLES24-MR-Lite](https://huggingface.co/datasets/YongchengYAO/ISLES24-MR-Lite).
+        [isles24-stroke](https://huggingface.co/datasets/hugging-science/isles24-stroke).
 
         **Model:** SEALS (ISLES'22 winner) - Fast, accurate ischemic stroke lesion segmentation.
 
@@ -175,6 +201,9 @@ def create_app() -> gr.Blocks:
             ],
         )
 
+        # Trigger data loading after UI renders (prevents startup timeout)
+        demo.load(initialize_case_selector, outputs=[case_selector])
+
     return demo  # type: ignore[no-any-return]
 
 

src/stroke_deepisles_demo/ui/components.py

@@ -6,7 +6,6 @@ import gradio as gr
 
 from stroke_deepisles_demo.core.config import get_settings
 from stroke_deepisles_demo.core.logging import get_logger
-from stroke_deepisles_demo.data import list_case_ids
 
 logger = get_logger(__name__)
 
@@ -15,32 +14,18 @@ def create_case_selector() -> gr.Dropdown:
     """
     Create a dropdown for selecting cases.
 
+    Initially empty; populated by app load event to prevent blocking startup.
+
     Returns:
         Configured gr.Dropdown component
-
-    Raises:
-        RuntimeError: If case IDs cannot be loaded (no silent fallback)
     """
-    try:
-        case_ids = list_case_ids()
-    except FileNotFoundError as e:
-        # Data directory not found - fail loudly with helpful message
-        logger.error("Data directory not found: %s", e)
-        raise RuntimeError("ISLES24 data not found. Please run: uv run stroke-demo download") from e
-    except Exception as e:
-        # Unexpected error - fail loudly, don't mask with fake dropdown option
-        logger.exception("Failed to load case IDs")
-        raise RuntimeError(f"Failed to load case IDs: {e}") from e
-
-    if not case_ids:
-        raise RuntimeError("No cases found in dataset. Please verify data directory structure.")
-
     return gr.Dropdown(
-        choices=case_ids,
-        value=case_ids[0],
+        choices=[],
+        value=None,
         label="Select Case",
-        info="Choose a case from ISLES24-MR-Lite",
+        info="Initializing dataset... please wait.",
         filterable=True,
+        interactive=True,
     )
 
 

tests/core/test_config.py

@@ -23,7 +23,7 @@ class TestSettings:
         """Has sensible defaults."""
         settings = Settings()
         assert settings.log_level == "INFO"
-        assert settings.hf_dataset_id == "YongchengYAO/ISLES24-MR-Lite"
+        assert settings.hf_dataset_id == "hugging-science/isles24-stroke"
         assert settings.deepisles_timeout_seconds == 1800
         assert settings.results_dir == Path("./results")
 

tests/ui/test_app.py

@@ -18,13 +18,13 @@ def test_create_app_returns_blocks() -> None:
     """create_app returns a gr.Blocks instance."""
     import gradio as gr
 
-    # Mock list_case_ids to avoid network call
-    with patch("stroke_deepisles_demo.ui.components.list_case_ids", return_value=["sub-001"]):
-        from stroke_deepisles_demo.ui.app import create_app
+    from stroke_deepisles_demo.ui.app import create_app
 
-        app = create_app()
+    # No mock needed - create_case_selector is now lazy (empty dropdown)
+    # Data loading happens via demo.load() after UI renders
+    app = create_app()
 
-        assert isinstance(app, gr.Blocks)
+    assert isinstance(app, gr.Blocks)
 
 
 def test_viewer_module_imports() -> None: