Fix ROSE As a Service merge conflicts

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: ci 
+name: ci
 on:
   push:
     branches:
@@ -18,12 +18,12 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: 3.x
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - run: echo "cache_id=$(date --utc '+%V')" >> "$GITHUB_ENV"
       - uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .cache
           restore-keys: |
             mkdocs-material-
       - run: pip install mkdocs mkdocs-material mkdocs-glightbox mkdocs-material-extensions mkdocs-minify-plugin
-      - run: mkdocs gh-deploy --force
+      - run: mkdocs gh-deploy --force

.github/workflows/tests.yml

@@ -3,20 +3,29 @@ name: tests
 on:
   push:
     branches: [main, test-me-*]
-    tags:
   pull_request:
   workflow_dispatch:
 
 jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Run pre-commit
+        uses: pre-commit/action@v3.0.1
+
   unit:
+    needs: [pre-commit]
     timeout-minutes: 15
     strategy:
       fail-fast: false
       matrix:
         include:
-        - os: ubuntu-latest
-          python: '3.9'
-          toxenv: py39
         - os: ubuntu-latest
           python: '3.10'
           toxenv: py310
@@ -39,7 +48,7 @@ jobs:
           python-version: ${{ matrix.python }}
       - name: Get pip cache dir
         id: pip-cache-dir
-        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> $GITHUB_ENV
+        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> "$GITHUB_ENV"
       - name: Use pip cache
         id: pip-cache
         uses: actions/cache@v4
@@ -54,14 +63,12 @@ jobs:
         run: tox -e ${{ matrix.toxenv }} -- -vv
 
   integration:
+    needs: [pre-commit]
     timeout-minutes: 20
     strategy:
       fail-fast: false
       matrix:
         include:
-        - os: ubuntu-latest
-          python: '3.9'
-          toxenv: py39-all
         - os: ubuntu-latest
           python: '3.10'
           toxenv: py310-all
@@ -84,7 +91,7 @@ jobs:
           python-version: ${{ matrix.python }}
       - name: Get pip cache dir
         id: pip-cache-dir
-        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> $GITHUB_ENV
+        run: echo "PIP_CACHE_DIR=$(pip cache dir)" >> "$GITHUB_ENV"
       - name: Use pip cache
         id: pip-cache
         uses: actions/cache@v4
@@ -97,17 +104,3 @@ jobs:
         run: python -m pip install --upgrade pip tox
       - name: Run Integration Tests
         run: tox -e ${{ matrix.toxenv }} -- -vv
-
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-      - name: Install tox
-        run: python -m pip install --upgrade pip tox
-      - name: Run linting
-        run: tox -e lint

.gitignore

@@ -159,5 +159,6 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 
 # rose specific
+*.db
 *.pkl
-asyncflow.session.*
+asyncflow.session.*

.pre-commit-config.yaml

@@ -0,0 +1,54 @@
+# .pre-commit-config.yaml
+
+default_language_version:
+  python: python3.12
+
+repos:
+  - repo: https://github.com/PyCQA/docformatter
+    rev: v1.7.7
+    hooks:
+      - id: docformatter
+        args: ["--in-place", "--wrap-summaries=100", "--wrap-descriptions=100"]
+        language_version: python3.12
+        exclude: ^examples/use_cases/
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.13.1
+    hooks:
+      - id: ruff
+        args: ["--fix", "--exit-non-zero-on-fix"]
+        language_version: python3.12
+        exclude: \.ipynb$|^examples/use_cases/
+      - id: ruff-format
+        language_version: python3.12
+        exclude: \.ipynb$|^examples/use_cases/
+
+  - 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
+        exclude: ^mkdocs\.yml$
+      - id: check-toml
+      - id: debug-statements
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: ["--maxkb=500"]
+
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.7
+    hooks:
+      - id: actionlint
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.34.0
+    hooks:
+      - id: check-github-workflows
+        files: ^\.github/workflows/.*\.ya?ml$
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.36.2
+    hooks:
+      - id: typos
+        exclude: ^examples/use_cases/

CHANGELOG.md

@@ -8,15 +8,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+---
+
+## [0.3.0] - 2026-03-05
+
+### Added
+- **`IterationState.learner_id`**: New field (`int | str | None`, default `None`) on `IterationState`
+  identifying which parallel learner produced a given state. Integer index for
+  `ParallelActiveLearner` and `ParallelReinforcementLearner`; learner name string for
+  `ParallelUQLearner`.
+
+### Changed
+- **Unified async-iterator API for parallel learners**: `ParallelActiveLearner.start()`,
+  `ParallelReinforcementLearner.start()`, and `ParallelUQLearner.start()` now return
+  `AsyncIterator[IterationState]` instead of blocking until all learners finish and returning
+  `list[Any]`. States stream in real time as each parallel learner completes an iteration,
+  using the same `async for state in learner.start():` interface as `SequentialActiveLearner`.
+- **Shared `_stream_parallel` helper**: The internal `asyncio.Queue`-based fan-in pattern
+  is extracted into a single module-level async generator in `rose/learner.py`, eliminating
+  identical code that was previously duplicated across all three parallel learner classes.
+
+### Deprecated
+- **`ParallelActiveLearner.teach()`**, **`ParallelReinforcementLearner.learn()`**, and
+  **`ParallelUQLearner.teach()`** still work but now internally iterate `start()` and
+  collect final states into a list. Migrate to `async for state in learner.start():`.
+
+---
+
+## [0.2.0] - 2026-02-27
+
 ### Added
+- **RHAPSODY backend integration**: Execution backends (`RadicalExecutionBackend`, `ConcurrentExecutionBackend`) are now imported from `rhapsody-py` (`from rhapsody.backends import ...`) instead of `radical.asyncflow`. `WorkflowEngine` remains in `radical.asyncflow`. Updated all examples, tutorials, docs, and notebooks accordingly.
+- **Pre-commit hooks**: Added `.pre-commit-config.yaml` with docformatter, ruff, standard file checks, actionlint, GitHub workflow validation, and typos. The `examples/use_cases/` directory is excluded from linting.
+- **CI pre-commit gate**: The `tests.yml` workflow now runs pre-commit as a required job before unit and integration tests, replacing the separate `lint` job.
+- **New tutorials**: Added `03-highly-parallel-surrogates` and `04-al-algorithm-selector` tutorials with corresponding optional dependencies in `tutorials/pyproject.toml` and `tutorials/README.md`.
 - **New `start()` API**: Replaced the blocking `teach()` method with an asynchronous iterator `start()`. This allows users to instrument the loop, log metrics in real-time (e.g., to MLflow), and implement custom early stopping or adaptive logic.
 - **IterationState**: Granular state reporting after each iteration, providing metrics, labeled/unlabeled counts, and statistics in a structured dataclass.
 - **Dynamic Configuration**: Added ability to update learner configuration (batch sizes, task arguments, etc.) between iterations using `learner.set_next_config()`.
-- **Added `Mlflow` integration: `rose.learner()` is now compatible with `mlflow` tracking. This feature is to support the need by the diffusion model community to track the training process via ROSE.
+- **MLflow integration**: `rose.learner()` is now compatible with MLflow tracking to support the diffusion model community's need to monitor the training process via ROSE.
 
 ### Changed
-- **Async-First Execution**: The core learner logic is now `asyncio` based, enabling better concurrency and integration with modern Python stacks.
-- **Separation of Concerns**: Orchestration logic (ROSE) is more clearly separated from task execution (AsyncFlow).
+- **Dependency update**: `rhapsody-py[radical_pilot]` added as a core dependency; Dragon HPC backend (`rhapsody-py[dragon]`) auto-installed on Python ≤3.12 via PEP 508 environment marker. `radical.asyncflow` retained for `WorkflowEngine`.
+- **Python support**: Minimum Python version is 3.10; Python 3.9 dropped from all tooling, CI, and tox environments.
+- **Async-first execution**: The core learner logic is now `asyncio`-based, enabling better concurrency and integration with modern Python stacks.
+- **Separation of concerns**: Orchestration logic (ROSE) is more clearly separated from task execution (AsyncFlow/RHAPSODY).
+- **Package discovery**: Explicitly scoped setuptools to the `rose` package to prevent accidental inclusion of `tutorials/` and `examples/` in the distribution.
+- **Ruff configuration**: Raised line length to 100, added ML naming convention rules to the ignore list (`N803`, `N806`, `N801`, `N812`–`N817`), and scoped the `B006` exception to example `run_me.py` files where `task_description={"shell": True}` is a required API pattern.
+- **GitHub Actions**: Fixed unquoted `$GITHUB_ENV` shell variable in `tests.yml` and `ci.yml` (shellcheck SC2086).
 
 ### Deprecated
 - `learner.teach()`: This method is deprecated and will be removed in a future version. Users should migrate to the `async for state in learner.start()` pattern.

README.md

@@ -6,7 +6,7 @@ ROSE is a Python package that provides tools to facilitate the development of ma
 
 ROSE also provides tools to facilitate the selection of the best surrogate model for a given simulation based on performance metrics.
 
-ROSE uses RADICAL-Cybertools -- middleware building blocks to facilitate the development of sophisticated scientific workflows on HPC resources. 
+ROSE uses RADICAL-Cybertools -- middleware building blocks to facilitate the development of sophisticated scientific workflows on HPC resources.
 
 ### How to install:
 
@@ -30,7 +30,7 @@ from rose.metrics import MEAN_SQUARED_ERROR_MSE
 from rose.al.active_learner import SequentialActiveLearner
 
 from radical.asyncflow import WorkflowEngine
-from radical.asyncflow import RadicalExecutionBackend
+from rhapsody.backends import RadicalExecutionBackend
 
 async def main():
     execution_engine = await RadicalExecutionBackend(

docs/changelog.md

@@ -1 +1 @@
---8<-- "CHANGELOG.md"
+--8<-- "CHANGELOG.md"

docs/getting-started/dry-run.md

@@ -42,4 +42,4 @@ asyncio.run(rose_al())
 
 * ROSE logs the task definitions, dependencies, and flow structure.
 
-* Useful for catching configuration errors or invalid paths before real execution.
+* Useful for catching configuration errors or invalid paths before real execution.

docs/getting-started/installation.md

@@ -24,7 +24,7 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
     ```
     python --version
     ```
-4. create new pip virtual env: 
+4. create new pip virtual env:
     ```
     python3 -m venv rose_env
     ```

docs/index.md

@@ -11,6 +11,10 @@ ROSE leverages [**RADICAL-Cybertools**](https://radical-cybertools.github.io), a
 ROSE allows you to enable, scale, and accelerate your learning workflows across thousands of CPU cores and GPUs effectively and efficiently with just a few lines of code.
 ROSE is built on the [**RADICAL-AsyncFlow**](https://radical-cybertools.github.io/radical.asyncflow/) and [**RADICAL-Pilot**](https://github.com/radical-cybertools/radical.pilot) runtime system, a powerful execution engine that enables the distributed execution of millions of scientific tasks and applications such as executables, functions and containers effortlessly.
 
+**Preemption-safe on HPC.** Every completed iteration is written to disk before the next one starts. If the job is killed mid-run, all completed iterations are already on disk — inspect them, resume from the last checkpoint, and never rerun a finished iteration.
+
+**Clean separation of control and observability.** Your `async for` loop contains only decisions — `break`, `set_next_config()`, application logic. Tracking (MLflow, ClearML, file-based) is wired once with `learner.add_tracker(...)` and fires automatically at every lifecycle point. No tracking code belongs in the control loop.
+
 
 <figure markdown="span" style="position: relative;">
   <img src="assets/rose_mind_flow.png" alt="">
@@ -20,7 +24,7 @@ ROSE is built on the [**RADICAL-AsyncFlow**](https://radical-cybertools.github.i
 
 ## Key Features ⭐⭐⭐
 
-- **Express, build and run** different surrogate building worklfows on HPC such as Active, and Reinforcement Learning workflows in minutes.
+- **Express, build and run** different surrogate building workflows on HPC such as Active, and Reinforcement Learning workflows in minutes.
 - **Seamless Execution of Complex ML surrogate building Workflows on HPC** across diverse computing platforms:
     - Local desktops and laptops
     - Local and remote clusters and grids