feat(phase-0): bootstrap project with TDD structure (#1)

* feat(phase-0): bootstrap project with TDD structure

Phase 0 complete - repo bootstrap with 2025 Python best practices:

- pyproject.toml with uv + hatchling backend
- Tobias's datasets fork for BIDS/NIfTI support
- src/stroke_deepisles_demo/ package structure
- core/ module with config, types, exceptions stubs
- data/, inference/, ui/ module stubs
- tests/ with pytest smoke tests (TDD - written first!)
- ruff for linting + formatting
- mypy strict mode on src/ and tests/
- pre-commit hooks configured

All "done" criteria verified:
- uv sync ✓
- pytest (3 passed) ✓
- ruff check ✓
- ruff format --check ✓
- mypy src/ tests/ ✓
- pre-commit run --all-files ✓
- package import ✓

* fix: address CodeRabbit review - ironclad Gucci banger status

Fixes all nitpicks from CodeRabbit review:

1. Python version alignment:
- ruff target-version: py311 → py312
- mypy python_version: 3.11 → 3.12
- Now aligned with .python-version (3.12)

2. Author info updated:
- Removed placeholder "Your Name" → "stroke-deepisles-demo contributors"

3. Consolidated dev deps:
- Removed duplicate [tool.uv].dev-dependencies section
- Single source of truth: [dependency-groups].dev

4. Pre-commit versions aligned:
- ruff: v0.8.0 → v0.14.8
- mypy: v1.8.0 → v1.19.0
- pre-commit-hooks: v4.5.0 → v6.0.0
- pyproject.toml minimums updated to match

5. Pydantic v2 modern style:
- Replaced nested `class Config` with `model_config = SettingsConfigDict(...)`

6. TypedDict improved:
- Changed flair/ground_truth from `Path | None` (required key, optional value)
- To `NotRequired[Path]` (optional key entirely)
- Added comprehensive docstring explaining required vs optional keys

All checks pass: pytest ✓ ruff ✓ mypy ✓ pre-commit ✓

.gitignore

@@ -182,9 +182,9 @@ cython_debug/
 .abstra/
 
 # Visual Studio Code
-#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
 #  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
-#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
 #  you could uncomment the following to ignore the entire vscode folder
 # .vscode/
 

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.8
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.19.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - pydantic>=2.5.0
+          - pydantic-settings>=2.1.0
+        args: [--config-file=pyproject.toml]
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=1000]

.python-version

@@ -0,0 +1 @@
+3.12

pyproject.toml

@@ -0,0 +1,134 @@
+[project]
+name = "stroke-deepisles-demo"
+version = "0.1.0"
+description = "Demo: HF datasets + DeepISLES stroke segmentation + Gradio visualization"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [
+    { name = "stroke-deepisles-demo contributors" }
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+keywords = ["stroke", "neuroimaging", "segmentation", "BIDS", "NIfTI", "deep-learning"]
+
+dependencies = [
+    # Core - pinned to Tobias's fork for BIDS + NIfTI lazy loading
+    "datasets @ git+https://github.com/CloseChoice/datasets.git@feat/bids-loader-streaming-upload-fix",
+    "huggingface-hub>=0.25.0",
+
+    # NIfTI handling
+    "nibabel>=5.2.0",
+    "numpy>=1.26.0",
+
+    # Configuration
+    "pydantic>=2.5.0",
+    "pydantic-settings>=2.1.0",
+
+    # UI (Gradio 5.x)
+    "gradio>=5.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-cov>=4.1.0",
+    "pytest-mock>=3.12.0",
+    "mypy>=1.19.0",
+    "ruff>=0.14.0",
+    "pre-commit>=3.6.0",
+    # Type stubs
+    "types-requests",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stroke_deepisles_demo"]
+
+# ─────────────────────────────────────────────────────────────────
+# Tool configurations
+# ─────────────────────────────────────────────────────────────────
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "ARG",    # flake8-unused-arguments
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+    "PTH",    # flake8-use-pathlib
+    "RUF",    # ruff-specific
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["stroke_deepisles_demo"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+plugins = ["pydantic.mypy"]
+
+[[tool.mypy.overrides]]
+module = [
+    "nibabel.*",
+    "gradio.*",
+    "datasets.*",
+    "niivue.*",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = [
+    "-v",
+    "--tb=short",
+    "--strict-markers",
+]
+markers = [
+    "integration: marks tests requiring external resources (Docker, network)",
+    "slow: marks tests that take >10s to run",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src/stroke_deepisles_demo"]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

src/stroke_deepisles_demo/__init__.py

@@ -0,0 +1,5 @@
+"""stroke-deepisles-demo: HF datasets + DeepISLES + Gradio visualization."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

src/stroke_deepisles_demo/core/__init__.py

@@ -0,0 +1,23 @@
+"""Core utilities for stroke-deepisles-demo."""
+
+from stroke_deepisles_demo.core.config import Settings, settings
+from stroke_deepisles_demo.core.exceptions import (
+    DataLoadError,
+    DeepISLESError,
+    DockerNotAvailableError,
+    MissingInputError,
+    StrokeDemoError,
+)
+from stroke_deepisles_demo.core.types import CaseFiles, InferenceResult
+
+__all__ = [
+    "CaseFiles",
+    "DataLoadError",
+    "DeepISLESError",
+    "DockerNotAvailableError",
+    "InferenceResult",
+    "MissingInputError",
+    "Settings",
+    "StrokeDemoError",
+    "settings",
+]

src/stroke_deepisles_demo/core/config.py

@@ -0,0 +1,29 @@
+"""Application configuration using pydantic-settings."""
+
+from __future__ import annotations
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="STROKE_DEMO_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+    )
+
+    # HuggingFace
+    hf_dataset_id: str = "YongchengYAO/ISLES24-MR-Lite"
+    hf_cache_dir: str | None = None
+
+    # DeepISLES
+    deepisles_docker_image: str = "isleschallenge/deepisles"
+    deepisles_fast_mode: bool = True
+
+    # Paths
+    temp_dir: str | None = None
+
+
+settings = Settings()

src/stroke_deepisles_demo/core/exceptions.py

@@ -0,0 +1,23 @@
+"""Custom exceptions for stroke-deepisles-demo."""
+
+from __future__ import annotations
+
+
+class StrokeDemoError(Exception):
+    """Base exception for stroke-deepisles-demo."""
+
+
+class DataLoadError(StrokeDemoError):
+    """Failed to load data from HuggingFace Hub."""
+
+
+class DockerNotAvailableError(StrokeDemoError):
+    """Docker is not installed or not running."""
+
+
+class DeepISLESError(StrokeDemoError):
+    """DeepISLES inference failed."""
+
+
+class MissingInputError(StrokeDemoError):
+    """Required input files are missing."""

src/stroke_deepisles_demo/core/types.py

@@ -0,0 +1,37 @@
+"""Shared type definitions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, NotRequired, TypedDict
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+
+class CaseFiles(TypedDict):
+    """Paths to NIfTI files for a single case.
+
+    Required keys:
+        dwi: Path to DWI NIfTI file
+        adc: Path to ADC NIfTI file
+
+    Optional keys (may be absent):
+        flair: Path to FLAIR NIfTI file (not all cases have FLAIR)
+        ground_truth: Path to ground truth mask (not available during inference)
+    """
+
+    dwi: Path
+    adc: Path
+    flair: NotRequired[Path]
+    ground_truth: NotRequired[Path]
+
+
+@dataclass(frozen=True)
+class InferenceResult:
+    """Result of running DeepISLES on a case."""
+
+    case_id: str
+    input_files: CaseFiles
+    prediction_mask: Path
+    elapsed_seconds: float

src/stroke_deepisles_demo/data/__init__.py

@@ -0,0 +1 @@
+"""Data loading module for stroke-deepisles-demo."""

src/stroke_deepisles_demo/inference/__init__.py

@@ -0,0 +1 @@
+"""DeepISLES inference module for stroke-deepisles-demo."""

src/stroke_deepisles_demo/ui/__init__.py

@@ -0,0 +1 @@
+"""Gradio UI module for stroke-deepisles-demo."""

tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for stroke-deepisles-demo."""

tests/conftest.py

@@ -0,0 +1,5 @@
+"""Shared pytest fixtures for stroke-deepisles-demo tests."""
+
+from __future__ import annotations
+
+# No fixtures needed for Phase 0 - pure import tests

tests/test_package.py

@@ -0,0 +1,29 @@
+"""Smoke tests for package structure."""
+
+from __future__ import annotations
+
+
+def test_package_imports() -> None:
+    """Verify the package can be imported."""
+    import stroke_deepisles_demo
+
+    assert stroke_deepisles_demo.__version__ == "0.1.0"
+
+
+def test_core_modules_import() -> None:
+    """Verify core modules can be imported without side effects."""
+    from stroke_deepisles_demo.core import config, exceptions, types
+
+    assert config.settings is not None
+    assert types.CaseFiles is not None
+    assert exceptions.StrokeDemoError is not None
+
+
+def test_subpackages_exist() -> None:
+    """Verify subpackage structure exists."""
+    from stroke_deepisles_demo import data, inference, ui
+
+    # These are stubs, just verify they exist
+    assert data is not None
+    assert inference is not None
+    assert ui is not None