ROSE Spec for Service

docs/getting-started/faq.md

@@ -9,6 +9,9 @@ Refer to the [Installation Guide](installation.md) for detailed instructions bas
 A dry run allows you to simulate the execution of your tasks locally without making any changes to the behavior of your ML workflow.
 It's a way to verify your setup is working on HPC before applying it to prevent time and resource waste.
 
+!!! tip
+    See the [Dry Run](dry-run.md) guide for a full step-by-step walkthrough.
+
 ## Q3: What if I have an issue?
 If you have any additional questions or an issue, feel free to reach out to our support team by opening a Github [ticket](https://github.com/radical-cybertools/ROSE/issues).
 

docs/getting-started/installation.md

@@ -7,7 +7,7 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
 ## For Linux and macOS 🐧
 
 1. Clone the latest version from the [official website](https://github.com/radical-cybertools/ROSE).
-   ```
+   ```bash
    git clone https://github.com/radical-cybertools/ROSE.git
    ```
 2. Run the following commands to install ROSE and its dependencies:
@@ -21,19 +21,19 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
 1. Download the Windows WSL installer from the [official website](https://apps.microsoft.com/detail/9pdxgncfsczv?hl=en-US&gl=US).
 2. Setup you WSL user name and password.
 3. Make sure you have Python 3.9 or higher in your WSL as follows:
-    ```
+    ```bash
     python --version
     ```
 4. create new pip virtual env:
-    ```
+    ```bash
     python3 -m venv rose_env
     ```
 5. Activate the env:
-   ```
+   ```bash
    source rose_env/bin/activate
    ```
 6. Clone the latest version from the [official website](https://github.com/radical-cybertools/ROSE).
-   ```
+   ```bash
    git clone https://github.com/radical-cybertools/ROSE.git
    ```
 7. Run the following commands to install ROSE and its dependencies:
@@ -42,4 +42,5 @@ machines, please refer to the following link: [RADICAL-Pilot Supported HPC Machi
     pip install .
     ```
 
-If you encounter any issues, refer to the [Issues Section](https://github.com/radical-cybertools/ROSE/issues).
+!!! note
+    If you encounter any issues, refer to the [Issues Section](https://github.com/radical-cybertools/ROSE/issues).

docs/index.md

@@ -1,6 +1,6 @@
 ## What is ROSE? 🌹
 
-ROSE: RADICAL Orchestrator for Surrogate Exploration (ROSE) toolkit is a framework designed to enable the concurrent and adaptive execution of simulation, surrogate training, and selection tasks on High-Performance Computing (HPC) resources. ROSE is a Python package that provides tools for developing active and reinforcement learning (AL and RL) methods for scientific applications. It enables users to define simulation and surrogate training tasks and automatically manage their execution on HPC resources via a predefined set of Learning Policies (Learners).
+ROSE: RADICAL Orchestrator for Surrogate Exploration (ROSE) toolkit is a framework designed to enable the distribuited, concurrent and adaptive execution of simulation, surrogate training, and selection tasks on High-Performance Computing (HPC) resources at a scale. ROSE is a Python package that provides tools for developing active and reinforcement learning (AL and RL) methods for scientific applications. It enables users to define simulation and surrogate training tasks and automatically manage their execution on HPC resources via a predefined set of Learning Policies (Learners).
 
 ROSE also includes tools to facilitate the selection of the most effective surrogate model for a given simulation based on performance metrics.
 

docs/integrations/clearml.md

@@ -61,6 +61,10 @@ For **parallel learners**, `state.learner_id` is included automatically. The tra
 each state as a separate `series` inside the same scalar title, making per-learner curves
 directly comparable without any user code.
 
+!!! note
+    No user code is required to get this overlay — `state.learner_id` is already populated
+    by the parallel learner framework before the tracker ever sees the state.
+
 ### Task tags — logged in `on_stop`
 
 | ClearML tag | Value |

docs/user-guide/acl-metrics.md

@@ -4,7 +4,7 @@ ROSE supports different Machine Learning (ML) Metrics such as `RMSE`, `MAE`, and
 
 
 ## Standard Metrics
-For a full list of the supported metrics please refer to the following link [ROSE Standard Metrics](https://github.com/radical-cybertools/ROSE/blob/feature/al_algo_selector/rose/metrics.py)
+For a full list of the supported metrics please refer to the following link [ROSE Standard Metrics](https://github.com/radical-cybertools/ROSE/blob/main/rose/metrics.py)
 
 
 ## Custom Metrics
@@ -26,3 +26,8 @@ async def check_metric(*args):
 ```
 
 In this way, ROSE will understand the relation between the custom metric and the target threshold value.
+
+!!! note
+    `metric_name` is just a label used for logging and tracking — ROSE does not validate it
+    against a fixed list. Any string is accepted as long as the decorated function returns a
+    numerical value to compare against `threshold`.

docs/user-guide/advanced-acl-workflow.md

@@ -1,26 +1,39 @@
+# Advanced Active Learning Workflow
+
 To support the rapid advancement of AL techniques, ROSE offers an additional approach to building and executing complex AL workflows.
 
 In this example, we demonstrate how to express an AL workflow with different levels of parallelism. What does that mean?
 
 In some cases, AL workflows may require the execution of N simulation or training tasks **concurrently**. But not only that—additionally, they may also require the submission of M AL workflows concurrently. This introduces two levels of parallelism: one at the task level and another at the AL workflow level. Such an approach is possible and can be easily expressed and executed using ROSE's **custom AL policy**.
 
-```sh
-                             (N AL WFs in Parallel)
-          +-------------------+               +-------------------+
-          |      AL WF 1      |               |      AL WF 2      |
-          +-------------------+               +-------------------+
-                   │                                    │
-  +----------------+-----------------+  +----------------+-----------------+
-  |       (N tasks Parallel)         |  |       (N AL tasks Parallel)      |
-  +---------------+  +---------------+  +---------------+  +---------------+
-  | Simulation 1  |  | Simulation 2  |  | Simulation 1  |  | Simulation 2  |
-  +---------------+  +---------------+  +---------------+  +---------------+
-          |                |                    |                 |
-  +---------------+  +---------------+  +---------------+  +---------------+
-  |  Training 1   |  |  Training 2   |  |  Training 1   |  |  Training 2   |
-  +---------------+  +---------------+  +---------------+  +---------------+
-          |                |                    |                 |
-        (...)            (...)                (...)             (...)
+!!! note
+    Task-level parallelism (N simulation/training tasks per iteration) and workflow-level
+    parallelism (M AL loops running side by side) are independent dimensions — you can scale
+    either one without changing the other.
+
+```mermaid
+graph TD
+    N["N AL WFs in Parallel"]
+    N --> WF1["AL WF 1"]
+    N --> WF2["AL WF 2"]
+
+    subgraph G1[" "]
+        WF1 --> S1a["Simulation 1"]
+        WF1 --> S1b["Simulation 2"]
+        S1a --> T1a["Training 1"]
+        S1b --> T1b["Training 2"]
+        T1a --> E1a["..."]
+        T1b --> E1b["..."]
+    end
+
+    subgraph G2[" "]
+        WF2 --> S2a["Simulation 1"]
+        WF2 --> S2b["Simulation 2"]
+        S2a --> T2a["Training 1"]
+        S2b --> T2b["Training 2"]
+        T2a --> E2a["..."]
+        T2b --> E2b["..."]
+    end
 ```
 
 Since we have already learned how to deploy and load ROSE, and how to instruct it to use different resources, we will skip this part and focus only on expressing the AL workflow.

docs/user-guide/advanced-rl-workflow.md

@@ -1,33 +1,21 @@
+# Advanced Reinforcement Learning Workflow
+
 In addition to basic reinforcement learning (RL) workflows, ROSE supports advanced RL workflows that can run multiple environment instances in parallel.
 
 The 'ParallelLearner' gives you the ability to run multiple environment tasks simultaneously, each with different parameters, and then merge their experiences for training.
 
 This is particularly useful for scenarios where you want to explore different configurations or hyperparameters in parallel, speeding up the learning process.
-```sh
-
-                +-------------------+
-                |        RL WF      |
-                +-------------------+
-                            │
-  +-------------------------+---------------------------+
-  |             (N Environment Tasks Parallel)          |
-  +---------------+  +---------------+  +---------------+
-  | Environment 1 |  | Environment 2 |  | Environment 3 |
-  +---------------+  +---------------+  +---------------+
-          |                |                    |
-          └────────────────┼────────────────────┘
-                           │
-                    +------v------+
-                    |    Merge    |
-                    +------+------+
-                           │
-                    +------v------+
-                    |   Update    |
-                    +------+------+
-                           │
-                    +------v------+
-                    |    Test     |
-                    +-------------+
+```mermaid
+graph TD
+    WF["RL WF"]
+    WF --> E1["Environment 1"]
+    WF --> E2["Environment 2"]
+    WF --> E3["Environment 3"]
+    E1 --> M["Merge"]
+    E2 --> M
+    E3 --> M
+    M --> U["Update"]
+    U --> T["Test"]
 ```
 Import ROSE parallel RL modules:
 
@@ -80,8 +68,7 @@ async def main():
 Now that each environment task is defined, we define the rest of the workflow components:
 
 !!! note
-
-This snippet of code must be inside an async context or inside `main` function
+    This snippet of code must be inside an async context or inside `main` function
 
 ```python
 @pe.update_task

docs/user-guide/basic-acl-workflow.md

@@ -38,8 +38,8 @@ async def active_learn(*args):
 ```
 
 !!! tip
-ROSE supports defining tasks with python code instead of executables (i.e., python scripts, shell scripts, etc.). To do that, the user have to
-pass the `as_executable=False` argument to the decorator as follows:
+    ROSE supports defining tasks with python code instead of executables (i.e., python scripts, shell scripts, etc.). To do that, the user have to
+    pass the `as_executable=False` argument to the decorator as follows:
 
 ```python
 @acl.simulation_task(as_executable=False)
@@ -92,7 +92,7 @@ async def check_mse(*args):
     return f'python3 check_mse.py'
 ```
 
-!!! Warning
+!!! warning
     For any metric function like `@acl.as_stop_criterion` the invoked script like `check_mse.py` must return a numerical value.
 
 

docs/user-guide/basic-rl-workflow.md

@@ -1,3 +1,5 @@
+# Basic Reinforcement Learning Workflow
+
 ## Define your target machine to run on
 
 Import ROSE main modules:
@@ -33,7 +35,7 @@ async def check_reward(*args):
     return 'python3 check_reward.py'
 ```
 
-!!! Warning
+!!! warning
     For any metric function like `@rl.as_stop_criterion` the invoked script like `check_reward.py` must return a numerical value.
 
 Finally invoke the tasks and register them with the reinforcement learner as a workflow:

docs/user-guide/experience.md

@@ -39,6 +39,10 @@ batch = bank.sample(batch_size=32, replace=True)
 
 ROSE assigns experience banks a unique session ID automatically, or session IDs can be assigned manually. The session ID is used to identify the bank and can be used to save/load the bank to/from disk:
 
+!!! note
+    Automatic session IDs require no bookkeeping on your part — pass `session_id` explicitly
+    only when you need a stable, predictable filename across runs (e.g. resuming a bank by name).
+
 ```python
 # Custom session ID
 bank = ExperienceBank(session_id="rose_session")

docs/user-guide/parallel_learners_docs.md

@@ -10,8 +10,7 @@ This tutorial demonstrates how to configure and run multiple learning pipelines
 ---
 
 !!! note
-
-This approach can be applied for both Active and Reinforcement learners (Sequential and Parallel).
+    This approach can be applied for both Active and Reinforcement learners (Sequential and Parallel).
 
 ## Example Overview
 

docs/user-guide/rose-aas.md

@@ -0,0 +1,82 @@
+# ROSE as a Service
+
+This page describes ROSE's service model: how the active-learning/RL loop you define stays under your control while the actual simulation and training work executes on HPC, and what that does and does not require from you today.
+
+---
+
+## Core idea: BYOF — Bring Your Own Workflow
+
+ROSE does not own the science. It owns the **orchestration loop**: submit a task, wait for it, decide what runs next, check a stop criterion, repeat — until `max_iter` or the criterion is met.
+
+You bring:
+
+- A `simulate` / `train` / `active_learn` (or `environment` / `update`, or `prediction` / `uncertainty`) implementation, as a plain Python function or a shell command.
+- The environment that implementation needs (packages, data, scripts).
+- The decision of where it should run — a laptop, a login node, or a leadership-class HPC allocation.
+
+ROSE brings the orchestration: dependency-correct task submission, iteration bookkeeping, stop-criterion evaluation, checkpoint-safe state, and tracking integration. The [YAML Spec API](spec-api.md) is the declarative form of this contract — `function: tasks:simulate` is a pointer to *your* code, not a hook into ROSE's.
+
+This is the same boundary that makes ROSE usable across domains without ROSE having to understand any of them: it sees `*args, **kwargs` in, a return value out, nothing about what happened in between.
+
+---
+
+## Two places work can happen
+
+A ROSE learner doesn't run anything itself — it submits tasks through whichever `asyncflow` execution backend you hand it. Two backends matter for the "as a Service" framing:
+
+| Backend | Where the orchestration loop runs | Where tasks execute | Documented at |
+|---|---|---|---|
+| `RadicalExecutionBackend` (RHAPSODY) | Wherever your script runs — it submits a pilot job and blocks inside it | Inside the pilot job it just submitted | [Target Resources](target-resources.md) |
+| Edge backend (RHAPSODY, `bridge_url` + `edge_name`) | Wherever your script runs — does **not** need to be the HPC machine | Inside a separate, already-running edge agent — possibly on a different machine entirely | this page |
+
+The first model is "submit a job, then run my loop inside it." The second is "run my loop here; dispatch tasks to a job running somewhere else." That second model is what makes ROSE service-like: the loop's control plane (your `learner.start()` call, deciding when to stop, talking to MLflow/ClearML) is decoupled from the compute plane (the HPC allocation actually executing `simulate`/`train`).
+
+---
+
+## How ROSE operates within a job
+
+The edge backend connects two things over a bridge:
+
+1. **An edge agent**, running inside an HPC job allocation. The job itself is requested through whatever your site normally uses to get an allocation — it doesn't have to be requested by ROSE. Once the job starts, the edge agent comes up inside it and stays alive for the allocation's lifetime, ready to accept task descriptions.
+2. **Your orchestration process**, running anywhere — your laptop, a long-lived service host, a CI runner. It builds the learner from your spec (`LearnerBuilder(cfg, asyncflow).build()`), starts the loop (`learner.start(...)`), and for every `simulation`/`training`/`active_learn`/... task it submits, the asyncflow engine forwards that task description over the bridge to the edge, waits for the result, and resumes the loop.
+
+The practical effect: you submit a ROSE workflow to HPC without an interactive session on the cluster, and without your laptop needing to stay connected to the scheduler — only to the bridge. The job allocation is what's expensive and scheduler-queued; your control process is cheap and can be restarted independently of it. Stop-criterion checks, `set_next_config()` decisions, and tracking calls all happen on your side of the bridge, on every iteration, with no per-iteration job resubmission.
+
+This is additive to the model in [Target Resources](target-resources.md), not a replacement — both go through the same `WorkflowEngine`/`LearnerBuilder` plumbing. Which backend you choose only changes *where* the edge lives; the spec, the learner, and the loop semantics are identical either way.
+
+---
+
+## What ROSE automates for you today
+
+- **The loop itself** — iterate, await, check criterion, repeat, with no boilerplate beyond defining your tasks and the threshold.
+- **Preemption-safe state** — every completed iteration is durable before the next starts, so a killed job loses at most the in-flight iteration.
+- **Tracking** — `tracking.backend: mlflow | clearml` in the spec wires a tracker once; every iteration's metrics, params, and lifecycle events are reported automatically, with no tracking code inside your task functions.
+- **Heterogeneous dispatch** — the same loop drives CPU-only, GPU, MPI, or shell-executable tasks, and (via the `learners:` block) distinct task implementations per parallel learner.
+
+## What ROSE does **not** yet automate: data movement
+
+Today, getting a simulation's output into the training task's hands is entirely your task code's responsibility:
+
+- `type: python` slots pass the previous task's return value in-memory, as the first positional argument — this is implicit in the task type, not something you declare.
+- `type: shell` slots pass nothing automatically; your command's stdout becomes the next task's input only if your scripts agree on a file path or convention outside the spec (this is exactly the pattern in the M3DC1 use case, where `simulate`/`train`/`active_learn` hand-roll a namespaced directory of files to communicate).
+
+**Planned:** a `DataExchangeProtocol` field in the YAML spec — `FileBased` or `MemoryBased` — that makes this an explicit, ROSE-managed choice instead of an implicit consequence of task type:
+
+- `MemoryBased` formalizes what `type: python` already does today — in-process object passing between tasks on the same worker.
+- `FileBased` would let ROSE own staging a per-iteration (and per-learner, for parallel runs) working directory, instead of every use case reimplementing its own namespace/path convention by hand inside task code.
+
+This isn't implemented yet — it's the next piece of surface area on the spec, and the natural place to close the "no environment/output contract" gap without ROSE needing to know anything about the science moving through it.
+
+---
+
+## What you bring, concretely
+
+| You supply | ROSE does not check this for you (today) |
+|---|---|
+| Task implementations (`simulate`, `train`, `active_learn`, criterion evaluator, ...) matching the `*args, **kwargs` convention | Whether return shapes match what the next task expects |
+| The runtime environment those implementations need on the worker | No environment/dependency manifest in the spec |
+| Access to wherever the edge agent's job runs (account, queue, allocation) | Out of scope for the spec layer entirely |
+| Your data, and a convention for how tasks find it (today: `parameters:` + your own file paths) | No declared output/data contract yet — see `DataExchangeProtocol` above |
+| Correct `remote.pythonpath` if task modules aren't already importable where the edge runs | `validate_imports=True` only checks importability in *your local* environment |
+
+None of this is unique to the service model — it's the same BYOF boundary as running ROSE locally. What the service model changes is *where* that boundary sits physically: your task code and its dependencies need to be reachable from the edge's job allocation, not from your laptop.