pineuro 1.0.0__tar.gz

pineuro-1.0.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026, Marlee M Vandewouw
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

pineuro-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: pineuro
+Version: 1.0.0
+Summary: Python for Individualized Neurofeedback
+Author-email: Marlee M Vandewouw <marlee.vandewouw@outlook.com>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro
+Project-URL: Documentation, https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/tree/main/docs
+Project-URL: Issues, https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/issues
+Project-URL: Changelog, https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/blob/main/CHANGELOG.md
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Requires-Python: <3.12,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: antspyx==0.6.2
+Requires-Dist: dcm2niix
+Requires-Dist: evdev; sys_platform == "linux"
+Requires-Dist: flet==0.80.5
+Requires-Dist: flet-charts>=0.1.0
+Requires-Dist: matplotlib
+Requires-Dist: nibabel>=5.3.0
+Requires-Dist: nilearn==0.13.1
+Requires-Dist: numpy>=2.0.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: psutil>=5.9
+Requires-Dist: psychopy>=2025.2.0
+Requires-Dist: pygame>=2.6.0
+Requires-Dist: pydicom
+Requires-Dist: python-xlib; sys_platform == "linux"
+Requires-Dist: pyyaml
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: screeninfo>=0.8
+Requires-Dist: templateflow
+Requires-Dist: watchdog
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy==1.19.1; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff==0.15.2; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Dynamic: license-file
+
+# pineuro
+
+**Python for Individualized Neurofeedback**
+
+A Python library for real-time fMRI neurofeedback research. pineuro provides a complete pipeline from DICOM acquisition through preprocessing, network mask extraction, and moment-to-moment BOLD activation estimation, with a desktop GUI for study management and participant workflows.
+
+## Features
+
+**Core pipeline**
+- **DICOM processing**: Watch for incoming scanner DICOMs and process volumes as they arrive
+- **Preprocessing**: Motion correction, brain extraction, and multi-run coregistration (ANTsPy)
+- **ICA mask extraction**: Participant-specific network masks via ICA and Yeo atlas
+- **GLM mask extraction**: Network masks from task localizer contrasts
+- **MNI atlas masks**: Atlas-based ROIs without a localizer run
+- **Incremental GLM**: Online activation estimation using Gentleman's algorithm
+- **Connectivity feedback**: Real-time functional connectivity between network pairs
+
+**Study management**
+- **Desktop GUI**: Study configuration and participant workflows (`pineuro-gui`)
+- **Session orchestration**: Multi-run and multi-session protocols
+- **Sham / control conditions**: Sham feedback, replay providers, and randomization
+- **QC reports**: HTML quality reports for each pipeline stage
+
+**Task framework**
+- **Built-in tasks**: Gauge (dual-network block design), ball (dual-network adaptive), thermometer (single-network), and RIT variants
+- **Task plugin system**: `@pineuro_task` decorator and entry-point registration
+- **Simulation mode**: Offline DICOM replay at configurable speed
+
+## Installation
+
+**Requires Python 3.10 or 3.11** (`>=3.10,<3.12`). All dependencies are pure pip; no external tools required.
+
+```bash
+git clone https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro.git
+cd pineuro
+pip install -e .
+```
+
+See the [Installation Guide](docs/getting-started/installation.md) for platform-specific notes and troubleshooting.
+
+## GUI
+
+```bash
+pineuro-gui
+```
+
+The desktop GUI provides study configuration, participant workflows, live activation plots, and QC reports. See the [First Session Tutorial](docs/getting-started/first-session.md) for a complete walkthrough.
+
+## Documentation
+
+**Getting started**
+- [Installation](docs/getting-started/installation.md): Setup and dependencies
+- [Quick Start](docs/getting-started/quickstart.md): GUI quick start (with an API snippet)
+- [First Session](docs/getting-started/first-session.md): End-to-end GUI walkthrough
+
+**User guide**: [Full index](docs/index.md)
+
+[Pipeline Overview](docs/user-guide/pipeline-overview.md) · [Study Configuration](docs/user-guide/study-configuration.md) · [Preprocessing](docs/user-guide/preprocessing.md) · [Mask Extraction](docs/user-guide/mask-extraction.md) · [Feedback Tasks](docs/user-guide/feedback-tasks.md) · [Tasks](docs/user-guide/tasks.md) · [Sham & Blinding](docs/user-guide/sham-and-blinding.md) · [Multi-Session](docs/user-guide/multi-session.md) · [Display Setup](docs/user-guide/display-setup.md) · [Simulation Mode](docs/user-guide/simulation-mode.md) · [QC Reports](docs/user-guide/qc-reports.md) · [Network Testing](docs/user-guide/network-testing.md)
+
+## Citation
+
+If you use pineuro in your research, please cite:
+
+```
+Vandewouw, M. M. (2026). pineuro: Python for Individualized Neurofeedback.
+https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro
+```
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) for details.
+

pineuro-1.0.0/README.md

@@ -0,0 +1,72 @@
+# pineuro
+
+**Python for Individualized Neurofeedback**
+
+A Python library for real-time fMRI neurofeedback research. pineuro provides a complete pipeline from DICOM acquisition through preprocessing, network mask extraction, and moment-to-moment BOLD activation estimation, with a desktop GUI for study management and participant workflows.
+
+## Features
+
+**Core pipeline**
+- **DICOM processing**: Watch for incoming scanner DICOMs and process volumes as they arrive
+- **Preprocessing**: Motion correction, brain extraction, and multi-run coregistration (ANTsPy)
+- **ICA mask extraction**: Participant-specific network masks via ICA and Yeo atlas
+- **GLM mask extraction**: Network masks from task localizer contrasts
+- **MNI atlas masks**: Atlas-based ROIs without a localizer run
+- **Incremental GLM**: Online activation estimation using Gentleman's algorithm
+- **Connectivity feedback**: Real-time functional connectivity between network pairs
+
+**Study management**
+- **Desktop GUI**: Study configuration and participant workflows (`pineuro-gui`)
+- **Session orchestration**: Multi-run and multi-session protocols
+- **Sham / control conditions**: Sham feedback, replay providers, and randomization
+- **QC reports**: HTML quality reports for each pipeline stage
+
+**Task framework**
+- **Built-in tasks**: Gauge (dual-network block design), ball (dual-network adaptive), thermometer (single-network), and RIT variants
+- **Task plugin system**: `@pineuro_task` decorator and entry-point registration
+- **Simulation mode**: Offline DICOM replay at configurable speed
+
+## Installation
+
+**Requires Python 3.10 or 3.11** (`>=3.10,<3.12`). All dependencies are pure pip; no external tools required.
+
+```bash
+git clone https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro.git
+cd pineuro
+pip install -e .
+```
+
+See the [Installation Guide](docs/getting-started/installation.md) for platform-specific notes and troubleshooting.
+
+## GUI
+
+```bash
+pineuro-gui
+```
+
+The desktop GUI provides study configuration, participant workflows, live activation plots, and QC reports. See the [First Session Tutorial](docs/getting-started/first-session.md) for a complete walkthrough.
+
+## Documentation
+
+**Getting started**
+- [Installation](docs/getting-started/installation.md): Setup and dependencies
+- [Quick Start](docs/getting-started/quickstart.md): GUI quick start (with an API snippet)
+- [First Session](docs/getting-started/first-session.md): End-to-end GUI walkthrough
+
+**User guide**: [Full index](docs/index.md)
+
+[Pipeline Overview](docs/user-guide/pipeline-overview.md) · [Study Configuration](docs/user-guide/study-configuration.md) · [Preprocessing](docs/user-guide/preprocessing.md) · [Mask Extraction](docs/user-guide/mask-extraction.md) · [Feedback Tasks](docs/user-guide/feedback-tasks.md) · [Tasks](docs/user-guide/tasks.md) · [Sham & Blinding](docs/user-guide/sham-and-blinding.md) · [Multi-Session](docs/user-guide/multi-session.md) · [Display Setup](docs/user-guide/display-setup.md) · [Simulation Mode](docs/user-guide/simulation-mode.md) · [QC Reports](docs/user-guide/qc-reports.md) · [Network Testing](docs/user-guide/network-testing.md)
+
+## Citation
+
+If you use pineuro in your research, please cite:
+
+```
+Vandewouw, M. M. (2026). pineuro: Python for Individualized Neurofeedback.
+https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro
+```
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) for details.
+

pineuro-1.0.0/pyproject.toml

@@ -0,0 +1,145 @@
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pineuro"
+version = "1.0.0"
+description = "Python for Individualized Neurofeedback"
+readme = "README.md"
+requires-python = ">=3.10,<3.12"
+authors = [{name = "Marlee M Vandewouw", email = "marlee.vandewouw@outlook.com"}]
+license = "Apache-2.0"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+]
+dependencies = [
+    # antspyx/nilearn are exact-pinned: the validation suite asserts their
+    # output via exact / first-principles checks that only reproduce when the
+    # iterative optimizers run deterministically (single-threaded ITK/BLAS; see
+    # tests/validation/conftest.py). A version bump can change that output, so it
+    # must be a deliberate, re-verified change -- see tests/validation/README.md.
+    "antspyx==0.6.2",
+    "dcm2niix",
+    # Linux-only: reads /dev/input/event* for global key polling under Wayland,
+    # where XQueryKeymap is starved of events when the stimulus window is
+    # unfocused (see tasks/task_base.py:_poll_keys_evdev). Compiles against
+    # linux/input.h, so it must not install on Windows/macOS.
+    "evdev; sys_platform == 'linux'",
+    "flet==0.80.5",
+    "flet-charts>=0.1.0",
+    "matplotlib",
+    "nibabel>=5.3.0",
+    "nilearn==0.13.1",  # exact-pinned -- see the antspyx note above
+    "numpy>=2.0.0",
+    "pandas>=2.0.0",
+    "psutil>=5.9",  # Terminate the ICA subprocess tree on GUI Stop (mask_extraction)
+    "psychopy>=2025.2.0",
+    "pygame>=2.6.0",  # Cross-platform audio backend for PsychoPy
+    "pydicom",
+    # Linux-only: Xlib window positioning (_move_window_xlib) and the Xorg
+    # unfocused-key poll path (XQueryKeymap). Present transitively via PsychoPy
+    # today, but pineuro uses it directly, so depend on it explicitly.
+    "python-xlib; sys_platform == 'linux'",
+    "pyyaml",
+    "scipy>=1.14.0",
+    "screeninfo>=0.8",
+    "templateflow",
+    "watchdog",
+]
+
+[project.urls]
+Homepage = "https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro"
+Documentation = "https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/tree/main/docs"
+Issues = "https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/issues"
+Changelog = "https://github.com/WhitfieldGabrieli-EPICBrainLab/pineuro/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+# ruff and mypy are exact-pinned so the checks CI runs match a local
+# `pip install -e ".[dev]"`: a new release can change their output on unchanged
+# code (ruff 0.17 formats code blocks in Markdown files; 0.15 did not). Upgrade them
+# deliberately, together with the ruff install in .github/workflows/ci.yml.
+dev = ["build", "mypy==1.19.1", "pytest>=8.0", "ruff==0.15.2", "types-PyYAML"]
+
+[project.scripts]
+pineuro-gui = "pineuro.gui.app:main"
+
+# Third-party task plugins register under this entry-point group.
+# In a plugin package's pyproject.toml:
+#   [project.entry-points."pineuro.tasks"]
+#   my_task = "my_package.tasks"
+# pineuro auto-discovers all registered plugins at GUI startup.
+[project.entry-points."pineuro.tasks"]
+
+# ---------------------------------------------------------------------------
+# Ruff — linter + formatter
+# ---------------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+exclude = [".git", ".venv", "__pycache__", "*.egg-info", "build", "dist"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "UP", "B", "SIM"]
+ignore = [
+    "E501",   # line too long — formatter handles this
+    "E402",   # module-level import not at top — lazy PsychoPy imports are intentional
+    "UP007",  # Use X | Y for Union — noisy to enforce retroactively
+    "B007",   # loop variable not used — common in NumPy loops (for _ in range(n))
+    "B008",   # function call in default arg — legitimate for np.array() defaults
+    "SIM108", # use ternary — hurts readability in numerical code
+]
+fixable = ["I", "UP", "E", "W", "F401"]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401"]
+"tests/*.py" = ["T20", "S101", "INP001", "E402"]
+"tests/**/*.py" = ["T20", "S101", "INP001", "E402"]
+"analysis/*.py" = ["T20", "S101", "INP001", "E402"]
+"src/pineuro/gui/**/*.py" = ["B006"]
+"src/pineuro/tasks/*.py" = ["E402"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["pineuro"]
+force-sort-within-sections = false
+split-on-trailing-comma = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+docstring-code-format = false
+
+# ---------------------------------------------------------------------------
+# pytest
+# ---------------------------------------------------------------------------
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "slow: marks tests as slow (>10s)",
+    "validation: scientific-correctness validation (real ANTs/nilearn/dcm2niix, synthetic ground truth)",
+]
+addopts = "-m 'not validation'"
+
+# ---------------------------------------------------------------------------
+# mypy — basic type checking
+# ---------------------------------------------------------------------------
+
+[tool.mypy]
+# Keep in step with the Python of the lint-and-typecheck job in .github/workflows/ci.yml.
+python_version = "3.10"
+warn_return_any = true
+warn_unused_configs = true
+ignore_missing_imports = true
+no_implicit_optional = false
+disable_error_code = ["import-untyped"]
+

pineuro-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pineuro-1.0.0/src/pineuro/__init__.py

@@ -0,0 +1,284 @@
+"""pineuro - Python Real-Time fMRI Neurofeedback
+
+A complete pipeline for real-time fMRI neurofeedback research, from volume acquisition
+through preprocessing, network mask extraction, and moment-to-moment BOLD activation estimation.
+
+Main Functions
+--------------
+run_feedback_task : Run a complete real-time feedback task
+preprocessing : DICOM conversion, motion correction, brain extraction
+collect_volumes : Watch for and collect incoming scanner volumes (DICOM or NIfTI)
+mask_extraction_rest : Extract network masks using ICA and Yeo atlas
+mask_extraction_mni : Extract network masks directly from MNI atlas (no localizer needed)
+mask_extraction_task : Extract network masks using GLM contrasts from task localizer
+coregister_reference : Coregister masks to real-time scanner position
+
+Task Framework
+--------------
+BaseTask : Abstract base for custom neurofeedback tasks
+BaseLocalizerTask : Abstract base for localizer/stimulus tasks
+BallTask : Built-in dual-network ball game with adaptive difficulty
+ThermometerTask : Built-in single-network thermometer feedback
+create_task : Factory function to create tasks from registry
+NetworkRole : Declare network slot semantics for tasks
+ActivationSmoother : Exponential moving average smoothing
+ActivationNormalizer : Percentile-based normalization
+
+Session Orchestration
+--------------------
+SessionConfig : High-level session configuration
+LocalizerConfig / FeedbackRunConfig : Per-localizer and per-feedback-run configuration
+run_full_session : Run complete multi-run session
+setup_session : Initialize session (collection, preprocessing, mask extraction)
+run_single_task : Run one feedback/transfer task via task factory
+TaskState : Persistent state across runs
+
+Examples
+--------
+>>> from pineuro import preprocessing, mask_extraction_rest, run_feedback_task
+>>>
+>>> # Step 1: Preprocess resting-state data
+>>> preproc_file, mask_file, ref_file = preprocessing(
+...     participant_id='sub-01', session_id='ses-01', task='rest',
+...     root_dir='/data/sub-01/ses-01/preprocessing',
+...     input_dicoms='/scanner/sub-01/rest',
+... )
+>>>
+>>> # Step 2: Extract participant-specific network masks (ICA + Yeo atlas)
+>>> mask_paths = mask_extraction_rest(
+...     participant_id='sub-01', session_id='ses-01',
+...     root_dir='/data/sub-01/ses-01/mask_extraction',
+...     input_file=preproc_file, mask_file=mask_file, ref_file=ref_file,
+...     networks=['ContA', 'DefaultA'],  # returns a list of mask Paths
+... )
+>>>
+>>> # Step 3: Run a real-time feedback task (here, simulated offline)
+>>> result = run_feedback_task(
+...     mask_paths=mask_paths, subject='sub-01', session='ses-01',
+...     task='ball', run=1,
+...     output_dir='/data/sub-01/ses-01/feedback',
+...     collection_dir='/scanner/incoming',
+...     n_baseline=15, n_volumes=200, tr=2.0,
+...     simulator_source_dir='/data/sub-01/feedback_dicoms', simulator_speed=10.0,
+... )
+"""
+
+import importlib as _importlib
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    # Single source of truth: the version declared in pyproject.toml and
+    # recorded in the installed package metadata.
+    __version__ = _pkg_version("pineuro")
+except _PackageNotFoundError:  # pragma: no cover - package not installed
+    __version__ = "unknown"
+
+# ---------------------------------------------------------------------------
+# Lazy import system (PEP 562)
+#
+# Heavy neuroimaging libraries (ANTsPy, nilearn, scipy, nibabel) take 8-17s
+# to import on cold start. By deferring submodule imports until first access,
+# the GUI starts instantly and scripts only pay for what they actually use.
+# ---------------------------------------------------------------------------
+
+# Mapping: attribute_name -> (submodule_path, attribute_name_in_submodule)
+_LAZY_IMPORTS: dict[str, tuple[str, str]] = {
+    # --- feedback.py (heavy: nibabel, scipy, watchdog, pydicom) ---
+    "run_feedback_task": (".feedback", "run_feedback_task"),
+    "ConnectivityEstimator": (".feedback", "ConnectivityEstimator"),
+    "get_next_run_number": (".feedback", "get_next_run_number"),
+    "get_slot_run_info": (".feedback", "get_slot_run_info"),
+    # --- preprocessing.py (heavy: nibabel, scipy) ---
+    "preprocessing": (".preprocessing", "preprocessing"),
+    "collect_volumes": (".preprocessing", "collect_volumes"),
+    # --- mask_extraction.py (heavy: nibabel, scipy, pandas) ---
+    "mask_extraction_rest": (".mask_extraction", "mask_extraction_rest"),
+    "mask_extraction_mni": (".mask_extraction", "mask_extraction_mni"),
+    "mask_extraction_task": (".mask_extraction", "mask_extraction_task"),
+    "run_mask_extraction_from_config": (".mask_extraction", "run_mask_extraction_from_config"),
+    "import_manual_masks": (".mask_extraction", "import_manual_masks"),
+    "coregister_reference": (".mask_extraction", "coregister_reference"),
+    "create_tissue_masks": (".mask_extraction", "create_tissue_masks"),
+    "ATLAS_SOURCES": (".atlas_registry", "ATLAS_SOURCES"),
+    "get_atlas_labels": (".mask_extraction", "get_atlas_labels"),
+    # --- tasks (lightweight but deferred to avoid loading task modules) ---
+    "BaseTask": (".tasks", "BaseTask"),
+    "BaseLocalizerTask": (".tasks", "BaseLocalizerTask"),
+    "BallTask": (".tasks", "BallTask"),
+    "ThermometerTask": (".tasks", "ThermometerTask"),
+    "ActivationSmoother": (".tasks", "ActivationSmoother"),
+    "ActivationNormalizer": (".tasks", "ActivationNormalizer"),
+    "NetworkRole": (".tasks", "NetworkRole"),
+    "create_task": (".tasks", "create_task"),
+    "create_localizer_task": (".tasks", "create_localizer_task"),
+    # --- tasks.state ---
+    "TaskState": (".tasks.state", "TaskState"),
+    "RunInfo": (".tasks.state", "RunInfo"),
+    # --- session.py (lightweight: stdlib only) ---
+    "SessionConfig": (".session", "SessionConfig"),
+    "PathConfig": (".session", "PathConfig"),
+    "LocalizerConfig": (".session", "LocalizerConfig"),
+    "LocalizerExtractionConfig": (".session", "LocalizerExtractionConfig"),
+    "FeedbackRunConfig": (".session", "FeedbackRunConfig"),
+    "QCConfig": (".session", "QCConfig"),
+    "GLMConfig": (".session", "GLMConfig"),
+    "ConnectivityConfig": (".session", "ConnectivityConfig"),
+    "IntermittentConfig": (".session", "IntermittentConfig"),
+    "SimulatorConfig": (".session", "SimulatorConfig"),
+    "ScannerConfig": (".session", "ScannerConfig"),
+    "ReferenceConfig": (".session", "ReferenceConfig"),
+    "SessionMetadata": (".session", "SessionMetadata"),
+    "ShamConfig": (".session", "ShamConfig"),
+    "ShamRunConfig": (".session", "ShamRunConfig"),
+    "SimulatorSourceMapping": (".session", "SimulatorSourceMapping"),
+    "setup_session": (".session", "setup_session"),
+    "run_single_task": (".session", "run_single_task"),
+    "run_full_session": (".session", "run_full_session"),
+    "run_next_task": (".session", "run_next_task"),
+    "reset_task_state": (".session", "reset_task_state"),
+    "resolve_localizer_masks": (".session", "resolve_localizer_masks"),
+    "detect_existing_sessions": (".session", "detect_existing_sessions"),
+    "next_session_id": (".session", "next_session_id"),
+    # --- sham.py ---
+    "ShamActivationProvider": (".sham", "ShamActivationProvider"),
+    "ReplayActivationProvider": (".sham", "ReplayActivationProvider"),
+    "load_randomization": (".sham", "load_randomization"),
+    "generate_randomization": (".sham", "generate_randomization"),
+    "get_condition_for_participant": (".sham", "get_condition_for_participant"),
+    "find_feedbacklog_for_replay": (".sham", "find_feedbacklog_for_replay"),
+    # --- utils.py (heavy: numpy, nibabel, scipy, templateflow) ---
+    "enable_timing": (".utils", "enable_timing"),
+    "disable_timing": (".utils", "disable_timing"),
+    "get_timing_data": (".utils", "get_timing_data"),
+    "save_timing_report": (".utils", "save_timing_report"),
+    "Timer": (".utils", "Timer"),
+    "check_platform_requirements": (".utils", "check_platform_requirements"),
+    "outputs_exist": (".utils", "outputs_exist"),
+    "count_volume_files": (".utils", "count_volume_files"),
+    "collection_is_complete": (".utils", "collection_is_complete"),
+    "ProgressEmitter": (".utils", "ProgressEmitter"),
+    "compute_hrf": (".utils", "compute_hrf"),
+    "compute_boxcar_task_regressor": (".utils", "compute_boxcar_task_regressor"),
+    # --- script_generator.py ---
+    "generate_mask_extraction_script": (".script_generator", "generate_mask_extraction_script"),
+    "save_script": (".script_generator", "save_script"),
+    # --- scanner_setup.py (lightweight: stdlib only) ---
+    "test_scanner_connection": (".scanner_setup", "test_scanner_connection"),
+    "ConnectionTestResult": (".scanner_setup", "ConnectionTestResult"),
+    "ping_scanner": (".scanner_setup", "ping_scanner"),
+    "check_watch_directory": (".scanner_setup", "check_watch_directory"),
+    "get_setup_instructions": (".scanner_setup", "get_setup_instructions"),
+    # --- config module ---
+    "config": (".config", ""),  # Module import, not attribute
+}
+
+
+def __getattr__(name: str):
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = _importlib.import_module(module_path, __name__)
+        if not attr_name:
+            # Module-level import (e.g., config)
+            val = module
+        else:
+            val = getattr(module, attr_name)
+        globals()[name] = val  # Cache for subsequent access
+        return val
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    # Version
+    "__version__",
+    # Core functions
+    "run_feedback_task",
+    "ConnectivityEstimator",
+    "get_next_run_number",
+    "get_slot_run_info",
+    "preprocessing",
+    "collect_volumes",
+    "mask_extraction_rest",
+    "mask_extraction_mni",
+    "mask_extraction_task",
+    "run_mask_extraction_from_config",
+    "import_manual_masks",
+    "coregister_reference",
+    "ATLAS_SOURCES",
+    "get_atlas_labels",
+    # Task classes
+    "BaseTask",
+    "BaseLocalizerTask",
+    "BallTask",
+    "ThermometerTask",
+    "ActivationSmoother",
+    "ActivationNormalizer",
+    # Task registry & factory
+    "NetworkRole",
+    "create_task",
+    "create_localizer_task",
+    # Task regressor computation
+    "compute_hrf",
+    "compute_boxcar_task_regressor",
+    # Task state
+    "TaskState",
+    "RunInfo",
+    # Configuration dataclasses
+    "SessionConfig",
+    "PathConfig",
+    "LocalizerConfig",
+    "LocalizerExtractionConfig",
+    "FeedbackRunConfig",
+    "QCConfig",
+    "GLMConfig",
+    "ConnectivityConfig",
+    "IntermittentConfig",
+    "SimulatorConfig",
+    "ScannerConfig",
+    "ReferenceConfig",
+    "SessionMetadata",
+    "ShamConfig",
+    "ShamRunConfig",
+    "SimulatorSourceMapping",
+    # Sham functionality
+    "ShamActivationProvider",
+    "ReplayActivationProvider",
+    "load_randomization",
+    "generate_randomization",
+    "get_condition_for_participant",
+    "find_feedbacklog_for_replay",
+    # Orchestration functions
+    "setup_session",
+    "run_single_task",
+    "run_full_session",
+    "run_next_task",
+    "reset_task_state",
+    # Multi-session support functions
+    "resolve_localizer_masks",
+    "detect_existing_sessions",
+    "next_session_id",
+    # Timing functions
+    "enable_timing",
+    "disable_timing",
+    "get_timing_data",
+    "save_timing_report",
+    "Timer",
+    # Platform checks
+    "check_platform_requirements",
+    # Utilities
+    "outputs_exist",
+    "count_volume_files",
+    "collection_is_complete",
+    "ProgressEmitter",
+    # Script generation
+    "generate_mask_extraction_script",
+    "save_script",
+    # Scanner setup
+    "test_scanner_connection",
+    "ConnectionTestResult",
+    "ping_scanner",
+    "check_watch_directory",
+    "get_setup_instructions",
+    # Configuration
+    "config",
+]