The Recommended Recipe Creation Workflow

The ideal, best-practice way to build robust recipes in rolv follows a two-stage workflow:

Workflow Actions & Save as Recipe

  1. Build & Validate in Graph View:
    • Create a visual pipeline in Graph View. Add nodes, write/generate code, set up inputs/outputs, and execute the nodes.
    • Test execution locally or over SSH. Enable Auto-Correct Failures and Strict Fact-Checking in Graph Actions to verify your pipeline runs end-to-end without errors.
  2. Export as Recipe:
    • Open Graph Actions (top-right slider icon) and click Save as Recipe.
    • This packages your graph structure, scripts, environment specs, and parameters into a clean recipe bundle.
  3. Refine in Recipe Designer:
    • Open your new recipe in the Recipe Designer (Recipes → Open Designer).
    • Polish recipe.md documentation, click Enhance on node descriptions for vector RAG search, configure env/ files, and add troubleshooting hints.
  4. Submit to Cloud Library:
    • Click Submit in the designer header to publish your recipe for peer review.

Recipe Library & Cloud Library

Recipes Navigation & Cloud Library

Click Recipes in the sidebar to open the Recipe Library. Local recipes load instantly from your machine, while any available cloud updates or new versions check silently in the background. Use the tab toggle at the top:

  • Local Library: Browse, run, edit, duplicate, export, or delete recipes saved on your local machine.
  • Cloud Library: Search the online community repository for verified pipelines and sub-node blueprints. Signed-in Free users can browse names; downloading requires Academic or Pro. A Cloud Library hit that is not on disk yet is downloaded on first use (chat Use Recipe, library Run Recipe, or saying “run it” in chat).

Recipe Download Slot Limits

  • Free Tier: Browse the Cloud Library. Downloading recipes is not included.
  • Academic Tier (🎓): Includes 5 active local recipe slots. Downloading a recipe from the Cloud Library consumes 1 slot.
  • Publish-to-Earn Rewards (Academic): When your submitted community recipe is approved by maintainers/admins, you earn +5,000 Compute Credits, +2 Permanent Recipe Workspace Slots, and Maintainer Status to review and approve community updates!
  • Pro & Team Tiers: Unlimited recipe workspace slots.

Recipe Properties

Types

Type Description
User Created by you
Team Shared within your organization
Validated Reviewed and approved

Statuses

Status Meaning
Draft Work in progress
Saved Saved locally
Submitted Submitted to the cloud for review
Approved Accepted by a reviewer

Categories (Cloud)

Category Meaning
Core Maintained by the rolv core team
Community Contributed by other users — use at your own discretion

Running a Recipe

From the library

  1. Select a recipe in the library
  2. Click Run Recipe
  3. Choose a working directory
  4. The recipe is instantiated as a new graph session with all nodes and code pre-loaded. Data Input/Output come back as I/O nodes (not compute) when the recipe was saved with node_type. Fill input variable paths on the Data Input node, then run.

From chat

You do this What happens
Click Use Recipe on a card the agent showed Same as Run Recipe: a new graph session
Type the recipe name, “run it”, “yes”, or “do 2” Loads the recipe into the current session (replaces the current graph)

Recipes saved from Graph before I/O round-trip may still show Data Input as a compute node. Re-open the original graph and Save as Recipe again.

Linked cloud recipes show a Cloud vN badge. Local-only recipes show Local only. Unsaved edits on a cloud-linked recipe show Local changes not submitted.

Importing Pipelines

The recipe browser can import a local folder, a Snakemake pipeline, or a GitHub repository.

Source How it works
Folder Accepts a Rolv recipe folder, a Snakemake pipeline, or a folder of scripts. A Rolv recipe imports as-is. A folder of scripts is compiled into a pipeline.
Snakemake Select a Snakefile or pipeline folder. This rewrite uses many tokens and is not failsafe: a pipeline that cannot be adapted is rejected.
GitHub Paste a public repository URL. Accepted repositories are a Rolv recipe, a folder of scripts, or a Snakemake pipeline. A Snakemake repository uses the same rewrite as the Snakemake button, so it spends many tokens and is not failsafe.

During import, a live status chip in the interface tracks scanning, script extraction, DAG construction, and validation in real time.

Recipe Designer

Click Open Designer on any recipe to enter the full editor. It has four tabs:

Recipe Tab

Edit the recipe.md file — the human-readable documentation for your pipeline. Toggle between Edit and Preview modes.

Syncing Documentation with Your Pipeline

As your pipeline evolves—when you add nodes, change parameters, or rewrite scripts—your documentation can quickly become outdated. The Sync docs with pipeline button uses AI to read your entire workflow graph, scripts, inputs, and outputs, then proposes updated documentation.

  1. Open the Sync Modal: Click Sync docs with pipeline in the recipe.md editor header.
  2. Provide Optional Instructions: You can add specific focus areas, such as "Focus on explaining input parameters" or "Add notes on expected runtimes", or leave it blank for a complete overview.

Sync Documentation with Pipeline

  1. Review Changes Section by Section: Rolv compares your current documentation with the generated draft and displays an interactive diff:
    • Section Checklist: Browse detected sections (such as Title & Overview, What this recipe does, Steps, Inputs & Parameters). Check the boxes for updates you want to apply, and uncheck any you prefer to keep unchanged.
    • Visual Diff: The right pane highlights additions in green and removals in red so you know exactly what is changing.
    • Safe Metadata: Your existing YAML frontmatter header (name, id, version, type) and custom sections (like References) are guaranteed preserved.
  2. Apply Selected Changes: Click Apply Selected to update your recipe.md draft. You can continue editing manually before saving.

Review & Select Documentation Changes

Workflow Tab

Visual graph editor showing nodes and edges. Click a node to see and edit:

Compute / research nodes

  • Label and Kind (script = compute, agent = research, manual = reserved)
  • Touch-last / protected — AI auto-heal prefers other nodes first. Optional reason is stored and sent to the model.
  • Research mode (research / agent only) — Interpret / simple agent (files and figures, no web search), Literature review (search only), or Full (both)
  • Structured output (research / agent only) — optional. Tick this when the next compute node must read a table. Enter comma-separated field names or leave blank for automatic schema inference.
  • Batch iteration across items (ForEach) (research / agent only) — optional. Automatically loops across up to 100 items/rows in parallel with live progress and produces aggregated Markdown and JSON results (<slug>-results.json, <slug>-report.md).
  • Expects and Produces (input/output data contracts)
  • Description — Used for semantic search; click Enhance to auto-generate a dense description using AI
  • Code file — The template code associated with this node

Data Input / Data Output

  • Canvas uses the same purple/green I/O chrome as Graph View
  • Right pane is an I/O panel (no Kind, Core, or code editor)
  • Data Input: names, descriptions, and defaults of inputs. A local file path is cleared. Plus an optional test-data script. The script creates sample files and a test_input.json. Generating test data copies those values into input.json. See Test data in Graph View.
  • Data Output: ledger only; artifacts come from output.json after a run

Environment Tab

Edit environment files under env/ and troubleshooting.md. Typical files:

File Purpose
python-requirements.txt Python packages (conda-forge / pip-style names)
r-packages.txt R / Bioconda packages
system-tools.txt CLI tools installed via Mamba

Automatic Python Package Resolution

When running or saving pipelines, Rolv automatically maps Python import statements to their real package names (such as mapping cv2 to opencv-python and sklearn to scikit-learn). If a package is not found in Conda or Bioconda, Rolv automatically attempts to install it via pip, both for local runs and across remote SSH servers.

The troubleshooting file can be auto-refreshed from the source session's execution history. Save as Recipe from Graph fills the env files with versions where known, automatically resolves Bioconductor and CRAN packages with canonical version constraints, and omits Python stdlib / R base packages.

Changes Tab

A diff viewer showing what's changed since the last save.

Publishing to Cloud

  1. Click Submit in the designer header
  2. Your recipe is uploaded for review
  3. Once approved, it becomes available to other users
  4. Submit again on a recipe that is already on the Cloud Library updates that listing (it does not create a duplicate). If the cloud copy is gone, Rolv creates a new listing.

Cloud Sync & Updates

When a cloud recipe has a newer version available, you'll see an "Update Available" badge:

Action What it does
Keep My Version Accept the new version number without changing your local files
Snooze 7 days Hide the update reminder for a week
Smart Merge AI merges the cloud changes with your local edits (creates a restore point first)
Clean Overwrite Replaces your local recipe entirely with the cloud version (creates a restore point first)

Note: Clean Overwrite requires Academic or Pro. Smart Merge requires a Pro subscription.

Recipe Sharing

When AI modifies a cloud-origin recipe locally, rolv can share improvements back. Configure this in Settings:

  • Ask every time — Prompts you after each save
  • Never ask — Silently skips sharing
  • Auto broadcast — Automatically submits contributions

Reporting a Recipe

For cloud-sourced recipes, click ⋮ → Report this recipe to flag content that's harmful, misleading, or violates guidelines.


Next: Reviews →

Try rolv on your desktop

Execute these workflows locally or connect to your lab's HPC.

Download App