feat(phase-5): polish, observability, and documentation (#6)

* feat(phase-5): add polish, observability, and documentation

Implements Phase 5 deliverables:
- Structured logging with centralized setup (src/stroke_deepisles_demo/core/logging.py)
- Enhanced pydantic-settings configuration (src/stroke_deepisles_demo/core/config.py)
- Complete documentation (README, CONTRIBUTING, CHANGELOG, .env.example, docs/guides/)
- GitHub Actions CI pipeline (.github/workflows/ci.yml)
- Integration of centralized logging into pipeline, UI, and inference modules

Quality:
- 96 tests passing (8 new tests for logging and config)
- Coverage: 82%
- ruff + mypy clean

* fix: address CodeRabbit review feedback for Phase 5

Security:
- docker.py: Redact environment variable values in debug logs to prevent
leaking secrets (e.g., HF tokens)

Bug fixes:
- logging.py: Fix get_logger() to avoid double-prefixing when __name__
already includes package name (was: stroke_deepisles_demo.stroke_deepisles_demo.module)

Documentation:
- configuration.md: Add missing STROKE_DEMO_TEMP_DIR to env var table
- configuration.md: Fix example to use get_settings() instead of imported
settings (which doesn't update after reload_settings())
- README.md: Format bare URL as proper markdown link (MD034)

.env.example

@@ -0,0 +1,22 @@
+# Logging
+STROKE_DEMO_LOG_LEVEL=INFO
+STROKE_DEMO_LOG_FORMAT=simple
+
+# HuggingFace
+STROKE_DEMO_HF_DATASET_ID=YongchengYAO/ISLES24-MR-Lite
+# STROKE_DEMO_HF_TOKEN=hf_...
+
+# DeepISLES
+STROKE_DEMO_DEEPISLES_DOCKER_IMAGE=isleschallenge/deepisles
+STROKE_DEMO_DEEPISLES_FAST_MODE=true
+STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS=1800
+STROKE_DEMO_DEEPISLES_USE_GPU=true
+
+# Paths
+STROKE_DEMO_RESULTS_DIR=./results
+# STROKE_DEMO_TEMP_DIR=/tmp/custom_temp
+
+# UI
+STROKE_DEMO_GRADIO_SERVER_NAME=0.0.0.0
+STROKE_DEMO_GRADIO_SERVER_PORT=7860
+STROKE_DEMO_GRADIO_SHARE=false

.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint with ruff
+        run: uv run ruff check .
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Type check with mypy
+        run: uv run mypy src/
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run tests
+        run: uv run pytest --cov --cov-report=xml
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        with:
+          files: ./coverage.xml
+          token: ${{ secrets.CODECOV_TOKEN }}
+
+  integration:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run integration tests
+        run: uv run pytest -m integration --timeout=600

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+-   **Phase 5**: Polish, Observability, and Documentation
+    -   Structured logging via `stroke_deepisles_demo.core.logging`.
+    -   Enhanced configuration via `pydantic-settings`.
+    -   Comprehensive documentation (README, CONTRIBUTING, guides).
+    -   GitHub Actions CI pipeline.
+
+-   **Phase 4**: Gradio UI and Visualization
+    -   Interactive Gradio application (`ui/app.py`).
+    -   NiiVue integration for 3D/multi-planar visualization.
+    -   Matplotlib slice comparison plots.
+
+-   **Phase 3**: End-to-End Pipeline
+    -   `PipelineResult` and `run_pipeline_on_case`.
+    -   Metrics calculation (Dice score, Volume).
+    -   CLI (`stroke-demo`) with `list` and `run` commands.
+
+-   **Phase 2**: DeepISLES Docker Integration
+    -   Wrapper for DeepISLES Docker container.
+    -   Automatic GPU detection and fallback.
+    -   Input/Output validation and staging.
+
+-   **Phase 1**: Data Access Layer
+    -   Integration with HuggingFace Datasets (ISLES24-MR-Lite).
+    -   Local NIfTI file adapter.
+    -   Lazy loading of large neuroimaging files.
+
+-   **Phase 0**: Repository Bootstrap
+    -   Project structure with `uv` and `hatchling`.
+    -   Strict typing with `mypy`.
+    -   Linting/Formatting with `ruff`.
+    -   Testing with `pytest`.

CONTRIBUTING.md

@@ -0,0 +1,82 @@
+# Contributing to stroke-deepisles-demo
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
+   cd stroke-deepisles-demo
+   ```
+
+2. **Install uv** (if not already installed)
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. **Install dependencies**
+   ```bash
+   uv sync
+   ```
+
+4. **Install pre-commit hooks**
+   ```bash
+   uv run pre-commit install
+   ```
+
+## Running Tests
+
+```bash
+# All tests (excluding integration)
+uv run pytest
+
+# With coverage
+uv run pytest --cov
+
+# Integration tests (requires Docker)
+uv run pytest -m integration
+
+# Slow tests (requires Docker + DeepISLES image)
+uv run pytest -m "integration and slow"
+```
+
+## Code Quality
+
+```bash
+# Lint
+uv run ruff check .
+
+# Format
+uv run ruff format .
+
+# Type check
+uv run mypy src/
+```
+
+## Project Structure
+
+```
+src/stroke_deepisles_demo/
+├── core/           # Shared utilities (config, types, exceptions)
+├── data/           # HF dataset loading and case management
+├── inference/      # DeepISLES Docker integration
+├── ui/             # Gradio application
+├── pipeline.py     # End-to-end orchestration
+└── metrics.py      # Evaluation metrics
+```
+
+## Pull Request Process
+
+1. Create a feature branch from `main`
+2. Write tests for new functionality
+3. Ensure all tests pass and code quality checks pass
+4. Update documentation if needed
+5. Submit PR with clear description
+
+## Code Style
+
+- Type hints on all functions
+- Docstrings in Google style
+- Keep functions focused and small
+- Prefer explicit over implicit

README.md

@@ -1,2 +1,93 @@
-# stroke-deepisles-demo
-Demo: run DeepISLES ischemic stroke segmentation on BIDS/HF data via arc-bids (research only, not for clinical use).
+# Stroke DeepISLES Demo
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/release/python-3110/)
+[![Code style: ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)
+
+A demonstration pipeline and UI for ischemic stroke lesion segmentation using **DeepISLES** and **ISLES24-MR-Lite** data.
+
+This project provides a complete end-to-end workflow:
+1.  **Data Loading**: Lazy-loading of NIfTI neuroimaging data from HuggingFace.
+2.  **Inference**: Running DeepISLES segmentation (SEALS or Ensemble) via Docker.
+3.  **Visualization**: Interactive 3D and multi-planar viewing with NiiVue in Gradio.
+
+> **Disclaimer**: This software is for research and demonstration purposes only. It is not intended for clinical use.
+
+## Features
+
+-   🧠 **State-of-the-Art Segmentation**: Uses DeepISLES (ISLES'22 winner) for accurate lesion segmentation.
+-   ☁️ **Cloud-Native Data**: Streams data directly from HuggingFace Datasets (no massive downloads).
+-   🐳 **Dockerized Inference**: Encapsulates complex deep learning dependencies in a reproducible container.
+-   🖥️ **Interactive UI**: Gradio-based web interface with 3D rendering (NiiVue).
+-   ⚙️ **Production Ready**: Type-safe, tested, and configurable via environment variables.
+
+## Quickstart
+
+### Prerequisites
+
+-   Python 3.11+
+-   Docker (for inference)
+-   [uv](https://github.com/astral-sh/uv) (recommended) or pip
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
+cd stroke-deepisles-demo
+
+# Install dependencies
+uv sync
+```
+
+### Running the Demo
+
+1.  **Pull the Docker image** (first time only):
+    ```bash
+    docker pull isleschallenge/deepisles
+    ```
+
+2.  **Launch the UI**:
+    ```bash
+    uv run python -m stroke_deepisles_demo.ui.app
+    ```
+    Open [http://localhost:7860](http://localhost:7860) in your browser.
+
+3.  **Run via CLI**:
+    ```bash
+    # List cases
+    uv run stroke-demo list
+
+    # Run segmentation on a specific case
+    uv run stroke-demo run --case sub-stroke0001
+    ```
+
+## Documentation
+
+-   [Quickstart Guide](docs/guides/quickstart.md)
+-   [Configuration](docs/guides/configuration.md)
+-   [Deployment](docs/guides/deployment.md)
+-   [Contributing](CONTRIBUTING.md)
+
+## Architecture
+
+```mermaid
+graph TD
+    HF[HuggingFace Hub] -->|Stream NIfTI| Loader[Data Loader]
+    Loader -->|Stage Files| Staging[Staging Dir]
+    Staging -->|Mount Volume| Docker[DeepISLES Container]
+    Docker -->|Inference| Results[Prediction Mask]
+    Results -->|Load| Metrics[Metrics (Dice)]
+    Results -->|Render| UI[Gradio UI / NiiVue]
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Acknowledgements
+
+-   [DeepISLES](https://github.com/ezequieldlrosa/DeepIsles) team for the segmentation model.
+-   [ISLES24](https://www.isles-challenge.org/) challenge for the dataset.
+-   [NiiVue](https://github.com/niivue/niivue) for the web-based neuroimaging viewer.

docs/guides/configuration.md

@@ -0,0 +1,47 @@
+# Configuration
+
+All settings can be configured via environment variables.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STROKE_DEMO_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `STROKE_DEMO_LOG_FORMAT` | `simple` | Log format (simple, detailed, json) |
+| `STROKE_DEMO_HF_DATASET_ID` | `YongchengYAO/ISLES24-MR-Lite` | HuggingFace dataset ID |
+| `STROKE_DEMO_HF_CACHE_DIR` | `None` | Custom HF cache directory |
+| `STROKE_DEMO_HF_TOKEN` | `None` | HuggingFace API token (for private datasets) |
+| `STROKE_DEMO_DEEPISLES_DOCKER_IMAGE` | `isleschallenge/deepisles` | DeepISLES Docker image |
+| `STROKE_DEMO_DEEPISLES_FAST_MODE` | `true` | Use single-model mode |
+| `STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS` | `1800` | Inference timeout |
+| `STROKE_DEMO_DEEPISLES_USE_GPU` | `true` | Use GPU acceleration |
+| `STROKE_DEMO_TEMP_DIR` | `None` | Scratch directory for intermediate files |
+| `STROKE_DEMO_RESULTS_DIR` | `./results` | Directory for output files |
+| `STROKE_DEMO_GRADIO_SERVER_NAME` | `0.0.0.0` | Gradio server host |
+| `STROKE_DEMO_GRADIO_SERVER_PORT` | `7860` | Gradio server port |
+| `STROKE_DEMO_GRADIO_SHARE` | `false` | Create public Gradio link |
+
+## Using .env File
+
+Create a `.env` file in the project root:
+
+```bash
+STROKE_DEMO_LOG_LEVEL=DEBUG
+STROKE_DEMO_DEEPISLES_USE_GPU=false
+STROKE_DEMO_RESULTS_DIR=/data/results
+```
+
+## Programmatic Configuration
+
+```python
+from stroke_deepisles_demo.core.config import get_settings, reload_settings
+import os
+
+# Check current settings
+print(get_settings().log_level)
+
+# Override via environment
+os.environ["STROKE_DEMO_LOG_LEVEL"] = "DEBUG"
+reload_settings()
+print(get_settings().log_level)  # DEBUG
+```

docs/guides/deployment.md

@@ -0,0 +1,39 @@
+# Deployment
+
+The demo is designed to be deployed on Hugging Face Spaces.
+
+## Hugging Face Spaces
+
+1.  **Create a Space**: Go to [huggingface.co/spaces](https://huggingface.co/spaces) and create a new Space.
+    *   **SDK**: Docker (Recommended for custom dependencies) or Gradio
+    *   **Hardware**: GPU is recommended for DeepISLES inference.
+
+2.  **Configure Dockerfile (if using Docker SDK)**:
+    Ensure the Dockerfile installs Python 3.11, uv, and pulls the DeepISLES image (or handles it appropriately, though Spaces might restrict running Docker-in-Docker).
+
+    *Note*: Since DeepISLES runs as a Docker container, running it inside a HF Space (which is a container) requires Docker-in-Docker (DinD) or a compatible runtime. If DinD is not supported, you might need to adapt the inference to run directly in the python environment if possible (DeepISLES source code integration instead of Docker wrapper), but this project wraps the Docker image.
+
+    **Standard Deployment (Gradio SDK)**:
+    The project includes `app.py` at the root for standard Gradio deployment. However, checking `requirements.txt` or `pyproject.toml` is needed.
+
+    For standard Gradio Spaces, you need to ensure `docker` command is available if you stick to the current architecture. Most HF Spaces do not support running `docker run`.
+
+    **Alternative**: Use a VM (AWS/GCP/Azure) with Docker installed.
+
+## Local Deployment
+
+1.  **Build/Pull**:
+    ```bash
+    docker pull isleschallenge/deepisles
+    ```
+
+2.  **Run App**:
+    ```bash
+    uv run python -m stroke_deepisles_demo.ui.app
+    ```
+
+## Environment Variables
+
+Configure the deployment using environment variables (Secrets in HF Spaces):
+-   `STROKE_DEMO_HF_TOKEN`: Read-only token for accessing datasets if private.
+-   `STROKE_DEMO_DEEPISLES_USE_GPU`: Set to `false` if deploying on CPU-only instance.

docs/guides/quickstart.md

@@ -0,0 +1,67 @@
+# Quickstart
+
+Get started with stroke-deepisles-demo in 5 minutes.
+
+## Prerequisites
+
+- Python 3.11+
+- Docker (for DeepISLES inference)
+- ~10GB disk space (for Docker image and datasets)
+
+## Installation
+
+```bash
+# Clone
+git clone https://github.com/The-Obstacle-Is-The-Way/stroke-deepisles-demo.git
+cd stroke-deepisles-demo
+
+# Install
+uv sync
+```
+
+## Pull DeepISLES Docker Image
+
+```bash
+docker pull isleschallenge/deepisles
+```
+
+## Run Locally
+
+### Option 1: Gradio UI
+
+```bash
+uv run python -m stroke_deepisles_demo.ui.app
+# Open http://localhost:7860
+```
+
+### Option 2: CLI
+
+```bash
+# List available cases
+uv run stroke-demo list
+
+# Run on a specific case
+uv run stroke-demo run --case sub-stroke0001 --fast
+```
+
+### Option 3: Python API
+
+```python
+from stroke_deepisles_demo.pipeline import run_pipeline_on_case
+
+result = run_pipeline_on_case("sub-stroke0001", fast=True)
+print(f"Dice score: {result.dice_score:.3f}")
+print(f"Prediction: {result.prediction_mask}")
+```
+
+## Configuration
+
+Set environment variables or create a `.env` file:
+
+```bash
+# .env
+STROKE_DEMO_LOG_LEVEL=DEBUG
+STROKE_DEMO_DEEPISLES_USE_GPU=false  # If no GPU available
+```
+
+See [Configuration Guide](configuration.md) for all options.

src/stroke_deepisles_demo/core/config.py

@@ -2,28 +2,76 @@
 
 from __future__ import annotations
 
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 
 class Settings(BaseSettings):
-    """Application settings loaded from environment variables."""
+    """
+    Application settings loaded from environment variables.
+
+    All settings can be overridden via environment variables with
+    the STROKE_DEMO_ prefix.
+
+    Example:
+        export STROKE_DEMO_LOG_LEVEL=DEBUG
+        export STROKE_DEMO_HF_DATASET_ID=my/dataset
+    """
 
     model_config = SettingsConfigDict(
         env_prefix="STROKE_DEMO_",
         env_file=".env",
         env_file_encoding="utf-8",
+        extra="ignore",
     )
 
+    # Logging
+    log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    log_format: Literal["simple", "detailed", "json"] = "simple"
+
     # HuggingFace
     hf_dataset_id: str = "YongchengYAO/ISLES24-MR-Lite"
-    hf_cache_dir: str | None = None
+    hf_cache_dir: Path | None = None
+    hf_token: str | None = Field(default=None, repr=False)  # Hidden from logs
 
     # DeepISLES
     deepisles_docker_image: str = "isleschallenge/deepisles"
-    deepisles_fast_mode: bool = True
+    deepisles_fast_mode: bool = True  # SEALS-only (ISLES'22 winner, no FLAIR needed)
+    deepisles_timeout_seconds: int = 1800  # 30 minutes
+    deepisles_use_gpu: bool = True
 
     # Paths
-    temp_dir: str | None = None
+    temp_dir: Path | None = None
+    results_dir: Path = Path("./results")
+
+    # UI
+    gradio_server_name: str = "0.0.0.0"
+    gradio_server_port: int = 7860
+    gradio_share: bool = False
 
+    @field_validator("results_dir", mode="before")
+    @classmethod
+    def ensure_results_dir_exists(cls, v: Path | str) -> Path:
+        """Create results directory if it doesn't exist."""
+        path = Path(v)
+        path.mkdir(parents=True, exist_ok=True)
+        return path
 
+
+# Global settings instance
 settings = Settings()
+
+
+def get_settings() -> Settings:
+    """Get the current settings instance."""
+    return settings
+
+
+def reload_settings() -> Settings:
+    """Reload settings from environment (useful for testing)."""
+    global settings
+    settings = Settings()
+    return settings

src/stroke_deepisles_demo/core/logging.py

@@ -0,0 +1,59 @@
+"""Centralized logging configuration."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Literal
+
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+def setup_logging(
+    level: LogLevel = "INFO",
+    *,
+    format_style: Literal["simple", "detailed", "json"] = "simple",
+) -> None:
+    """
+    Configure logging for the application.
+
+    Args:
+        level: Minimum log level
+        format_style: Output format style
+
+    Example:
+        >>> setup_logging("DEBUG", format_style="detailed")
+    """
+    formats = {
+        "simple": "%(levelname)s: %(message)s",
+        "detailed": "%(asctime)s | %(name)s | %(levelname)s | %(message)s",
+        "json": '{"time": "%(asctime)s", "name": "%(name)s", "level": "%(levelname)s", "message": "%(message)s"}',
+    }
+
+    logging.basicConfig(
+        level=getattr(logging, level),
+        format=formats[format_style],
+        stream=sys.stderr,
+        force=True,
+    )
+
+    # Reduce noise from libraries
+    logging.getLogger("urllib3").setLevel(logging.WARNING)
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("datasets").setLevel(logging.WARNING)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """
+    Get a logger for a module.
+
+    Args:
+        name: Logger name (typically __name__)
+
+    Returns:
+        Configured logger instance
+    """
+    # Avoid double-prefixing when __name__ already includes package name
+    if name.startswith("stroke_deepisles_demo."):
+        return logging.getLogger(name)
+    return logging.getLogger(f"stroke_deepisles_demo.{name}")

src/stroke_deepisles_demo/inference/deepisles.py

@@ -7,6 +7,7 @@ from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 from stroke_deepisles_demo.core.exceptions import DeepISLESError, MissingInputError
+from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.inference.docker import (
     DockerRunResult,
     ensure_gpu_available_if_requested,
@@ -16,6 +17,8 @@ from stroke_deepisles_demo.inference.docker import (
 if TYPE_CHECKING:
     from pathlib import Path
 
+logger = get_logger(__name__)
+
 # Constants
 DEEPISLES_IMAGE = "isleschallenge/deepisles"
 EXPECTED_INPUT_FILES = ["dwi.nii.gz", "adc.nii.gz"]

src/stroke_deepisles_demo/inference/docker.py

@@ -12,11 +12,14 @@ from stroke_deepisles_demo.core.exceptions import (
     DockerGPUNotAvailableError,
     DockerNotAvailableError,
 )
+from stroke_deepisles_demo.core.logging import get_logger
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
     from pathlib import Path
 
+logger = get_logger(__name__)
+
 
 @dataclass(frozen=True)
 class DockerRunResult:
@@ -123,15 +126,18 @@ def pull_image_if_missing(image: str, *, timeout: float = 600) -> bool:
         check=False,
     )
     if result.returncode == 0:
+        logger.debug("Docker image %s already present", image)
         return False  # Image already present
 
     # Pull the image
+    logger.info("Pulling Docker image %s (this may take a while)", image)
     subprocess.run(
         ["docker", "pull", image],
         capture_output=True,
         timeout=timeout,
         check=True,
     )
+    logger.info("Successfully pulled Docker image %s", image)
     return True
 
 
@@ -241,6 +247,19 @@ def run_container(
     )
 
     start_time = time.time()
+    # Redact environment variable values to avoid leaking secrets in logs
+    redacted_cmd: list[str] = []
+    skip_next = False
+    for arg in cmd:
+        if skip_next:
+            redacted_cmd.append("***")
+            skip_next = False
+        elif arg == "-e":
+            redacted_cmd.append(arg)
+            skip_next = True
+        else:
+            redacted_cmd.append(arg)
+    logger.debug("Running container: %s", " ".join(redacted_cmd))
     result = subprocess.run(
         cmd,
         capture_output=True,
@@ -250,6 +269,13 @@ def run_container(
     )
     elapsed = time.time() - start_time
 
+    if result.returncode != 0:
+        logger.error(
+            "Container execution failed (code %d). stderr: %s", result.returncode, result.stderr
+        )
+    else:
+        logger.info("Container execution completed in %.2fs", elapsed)
+
     return DockerRunResult(
         exit_code=result.returncode,
         stdout=result.stdout,

src/stroke_deepisles_demo/pipeline.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-import logging
 import shutil
 import statistics
 import tempfile
@@ -12,6 +11,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING
 
 from stroke_deepisles_demo import metrics
+from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.data import load_isles_dataset, stage_case_for_deepisles
 from stroke_deepisles_demo.inference import run_deepisles_on_folder
 
@@ -20,7 +20,7 @@ if TYPE_CHECKING:
 
     from stroke_deepisles_demo.core.types import CaseFiles
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 @dataclass(frozen=True)

src/stroke_deepisles_demo/ui/app.py

@@ -2,12 +2,12 @@
 
 from __future__ import annotations
 
-import logging
 from typing import Any
 
 import gradio as gr
-from matplotlib.figure import Figure  # noqa: TC002 - needed at runtime for Gradio
+from matplotlib.figure import Figure  # noqa: TC002
 
+from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.pipeline import run_pipeline_on_case
 from stroke_deepisles_demo.ui.components import (
     create_case_selector,
@@ -20,7 +20,7 @@ from stroke_deepisles_demo.ui.viewer import (
     render_slice_comparison,
 )
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 def run_segmentation(

src/stroke_deepisles_demo/ui/components.py

@@ -2,13 +2,12 @@
 
 from __future__ import annotations
 
-import logging
-
 import gradio as gr
 
+from stroke_deepisles_demo.core.logging import get_logger
 from stroke_deepisles_demo.data import list_case_ids
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 def create_case_selector() -> gr.Dropdown:

tests/core/test_config.py

@@ -0,0 +1,61 @@
+"""Tests for configuration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import pytest
+
+from stroke_deepisles_demo.core.config import Settings, reload_settings
+
+
+class TestSettings:
+    """Tests for Settings."""
+
+    def test_default_values(self) -> None:
+        """Has sensible defaults."""
+        settings = Settings()
+        assert settings.log_level == "INFO"
+        assert settings.hf_dataset_id == "YongchengYAO/ISLES24-MR-Lite"
+        assert settings.deepisles_timeout_seconds == 1800
+        assert settings.results_dir == Path("./results")
+
+    def test_env_override(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Environment variables override defaults."""
+        monkeypatch.setenv("STROKE_DEMO_LOG_LEVEL", "DEBUG")
+        monkeypatch.setenv("STROKE_DEMO_DEEPISLES_TIMEOUT_SECONDS", "60")
+
+        settings = Settings()
+        assert settings.log_level == "DEBUG"
+        assert settings.deepisles_timeout_seconds == 60
+
+    def test_hf_token_hidden_from_repr(self) -> None:
+        """HF token is not visible in repr."""
+        settings = Settings(hf_token="secret123")
+        assert "secret123" not in repr(settings)
+
+    def test_results_dir_created(self, tmp_path: Path) -> None:
+        """Results directory is created if it doesn't exist."""
+        # This test relies on the validator running during instantiation
+        new_dir = tmp_path / "new_results"
+        assert not new_dir.exists()
+
+        Settings(results_dir=new_dir)
+        assert new_dir.exists()
+
+    def test_reload_settings(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Test that reload_settings updates the global instance."""
+        from stroke_deepisles_demo.core import config
+
+        # Set env var
+        monkeypatch.setenv("STROKE_DEMO_LOG_LEVEL", "ERROR")
+
+        # Reload
+        new_settings = reload_settings()
+
+        assert new_settings.log_level == "ERROR"
+        assert config.settings.log_level == "ERROR"
+        # Ensure it's the same object instance reference in the module
+        assert config.settings is new_settings

tests/core/test_logging.py

@@ -0,0 +1,38 @@
+"""Tests for logging configuration."""
+
+from __future__ import annotations
+
+import logging
+
+from stroke_deepisles_demo.core.logging import get_logger, setup_logging
+
+
+class TestSetupLogging:
+    """Tests for setup_logging."""
+
+    def test_sets_log_level(self) -> None:
+        """Sets the root logger level."""
+        # Reset root logger handlers to avoid interference
+        logging.getLogger().handlers = []
+
+        setup_logging("DEBUG")
+        # Note: basicConfig might not reset if already configured unless force=True is used
+        # The implementation should use force=True
+        assert logging.getLogger().level == logging.DEBUG
+
+    def test_format_styles(self) -> None:
+        """Different format styles work."""
+        for style in ["simple", "detailed", "json"]:
+            # Reset handlers
+            logging.getLogger().handlers = []
+            setup_logging("INFO", format_style=style)  # type: ignore
+            # Should not raise
+
+
+class TestGetLogger:
+    """Tests for get_logger."""
+
+    def test_returns_namespaced_logger(self) -> None:
+        """Returns logger with stroke_demo prefix."""
+        logger = get_logger("my_module")
+        assert logger.name == "stroke_deepisles_demo.my_module"