Skip to content
ml4bioPublic

About

Nature Biotechnology: RhoAgent is an agentic framework for functional RNA design. It wraps RDiff, AlphaFold3, RNA secondary-structure extraction, structure evaluation, and filtering tools behind a task-oriented conversational agent.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

🧬 RhoAgent: Functional RNA Design Agent

Python License RDiff

An agentic framework for functional RNA design, combining diffusion-based generation, structure prediction, evaluation, and candidate filtering in a task-oriented workflow.

πŸ“‘ Contents

✨ Key Features

  • Task-oriented RNA design: the agent first asks the user to choose a task type, then loads the matching workflow.
  • Motif sampling and constrained sequence design: ribozyme tasks support Mode 1 (fully locked fixed motif) and Mode 2 (motif sampling / unlock) via RDiff_seq partial sampling; iterative workflows can also run seed-based partial diffusion for local resampling while keeping key motifs fixed.
  • Checkpoint-ensemble design tools: backbone, scaffolding, and sequence design tools can split a requested sample count across all checkpoints in configured checkpoint directories.
  • Ribozyme and aptamer scaffolding workflows:
    • secondary-structure-conditioned ribozyme design
    • subsequence-conditioned ribozyme design
    • limited-prior Hovlinc optimization
    • Broccoli/Pepper single-motif scaffolding
    • Broccoli-Pepper FRET dual-motif scaffolding
  • Scaffolding-specific evaluation: WT motif gate, backbone-AF3 self-consistency, C1'-lDDT, compactness, motif-scaffold contacts, and length-aware candidate filtering.
  • Two-mode first-round filtering:
    • standard: sequence recovery, GC, sequence similarity, ss_f1score >= 0.9 when available, TM-score ranking
    • scaffolding: backbone-AF3 consistency, compactness, and length-aware selection

πŸ“¦ Installation

Prerequisites

  • Python 3.9 or higher
  • Conda (recommended for environment management)

Setup

  1. RDiff repository:

Please refer to the RDiff repository.

  1. Clone the repository:
git clone <repository-url>
cd RhoAgent
  1. Create and activate conda environment:
conda create -n RhoAgent python=3.9
conda activate RhoAgent
  1. Install dependencies:
pip install -e .
  1. Configure environment variables: Create a .env file in the project root (or set shell exports) before running the agent. Do not commit real API keys.

RDiff design tools read paths from .env. You must configure the RDiff_str and RDiff_seq repository directories, the Python interpreter for the RDiff conda environment, and the checkpoint directories used by each design tool.

export DEFAULT_MODEL="your-model-name"
export DEFAULT_API_BASE="https://your-openai-compatible-endpoint/v1"
export DEFAULT_API_KEY="your-api-key"

# Optional but recommended for evaluation
export DEFAULT_USALIGN_BIN="/path/to/USalign"

# Required: RDiff code repositories
# RDiff_str: structure diffusion (backbone design + motif scaffolding)
export RDIFF_STR_CODE_DIR="/path/to/RDiff_str"
# RDiff_seq: sequence design on generated backbones
export RDIFF_SEQ_CODE_DIR="/path/to/RDiff_seq"
# Python executable from the RDiff conda environment
export PYTHON_CONDA_RDIFF="/path/to/ribodiffusion/bin/python"

# Required: checkpoint directories for ensemble design
# Each directory may contain one or more .pth checkpoints.
# The requested num_samples is split across all checkpoints in the directory.
export RDIFF_BACKBONE_CHECKPOINT_DIR="/path/to/RDiff_str/backbone_checkpoints"
export RDIFF_SCAFFOLDING_CHECKPOINT_DIR="/path/to/RDiff_str/scaffolding_checkpoints"
export RDIFF_SEQUENCE_CHECKPOINT_DIR="/path/to/RDiff_seq/checkpoints"

Optional: set RHOAGENT_ROOT or WORKSPACE_ROOT if your .env file lives outside the repo root. The agent also searches ./.env and <repo-root>/.env automatically.

🧩 Agent Skills

The skills in skills/ provide an alternative way to use this repository through another agent, alongside the built-in RhoAgent interface. They guide the agent through the same design workflows, including local setup, tool execution, evaluation, and output tracking.

Skill Supported workflows
Ribozyme design Motif-constrained design, subsequence-constrained design, and limited-prior iterative optimization.
Aptamer design Single-motif Broccoli/Pepper scaffolding and dual-motif Broccoli–Pepper FRET scaffold design.

Follow the original workflows or ask your agent to add, remove, replace, or reorder steps. The skills check downstream input requirements and record workflow changes.

To get started, ask your agent:

Install the rhoagent-ribozyme-design skill from the skills folder of https://github.com/ml4bio/RhoAgent. Help me install the required tools and configure local paths, then use the original workflow with my RNA sequence, secondary structure, and fixed-motif constraints.

You can also customize a run:

Use my existing structure predictions instead of running AF3, insert my candidate-filter script before evaluation, and omit final LLM ranking.

Install each complete skill folder, including its supporting files. Scientific software and model checkpoints are installed separately; the skills guide prerequisite checks and local path adaptation. See the skills installation and usage guide for details.

πŸš€ Quick Start

Running the Agent

The simplest way to start using RhoAgent is through the interactive entry point:

conda activate RhoAgent
python run_agent.py

The agent will first ask you to choose one task:

  1. Ribozyme Design
  2. Subsequence-Conditioned Ribozyme Design
  3. Hovlinc Limited-Prior Iterative Optimization
  4. Single-Motif Fluorogenic Aptamer Scaffolding
  5. Dual-Motif Broccoli-Pepper FRET Scaffold Design

After task selection, the agent collects only the required inputs for that task and asks for parameter confirmation. It must also ask for confirmation before every individual tool call.

Example Usage

from rhoagent.agents.rhoagent_pipeline import build_rna_design_pipeline_agent

# Configure LLM
llm_cfg = {
    'model': 'Qwen3-235B-A22B',
    'model_server': 'https://dashscope.aliyuncs.com/compatible-mode/v1',
    'api_key': 'your-api-key'
}

# Create agent
agent = build_rna_design_pipeline_agent(llm=llm_cfg)

# Run interactive session
messages = [{
    'role': 'user',
    'content': '''
    I want to design a functional RNA structure. Task 1.
    - wildtype_seq: ACACCCACCUGUUACAAGUCAGGACAGAAGCAGAGUAACGGUUGCUUACGCAACCGGUAAUGCUACUGGGUGU
    - target_ss: (((((((((((.[[[..{{)))).....((((..]]].(((((((....)))))))....))))}})))))))
    - fixed_motif: -----------UUACAA---------------G-GUA--------------------UAA-------------
    - work_dir: /path/to/output
    '''
}]

for response in agent.run(messages=messages):
    print(response)

πŸ—‚οΈ Project Structure

RhoAgent/
β”œβ”€β”€ rhoagent/                    # Main package
β”‚   β”œβ”€β”€ agents/                  # Agent implementations
β”‚   β”‚   β”œβ”€β”€ rhoagent_pipeline.py    # RNA Design Pipeline Agent (main)
β”‚   β”‚   β”œβ”€β”€ assistant.py        # Base assistant agent
β”‚   β”‚   β”œβ”€β”€ fncall_agent.py      # Function calling agent
β”‚   β”‚   β”œβ”€β”€ user_agent.py        # User interaction agent
β”‚   β”‚   β”œβ”€β”€ doc_qa/              # Document Q&A agents
β”‚   β”‚   β”‚   β”œβ”€β”€ basic_doc_qa.py
β”‚   β”‚   β”‚   β”œβ”€β”€ parallel_doc_qa.py
β”‚   β”‚   β”‚   └── ...
β”‚   β”‚   └── keygen_strategies/   # Keyword generation strategies
β”‚   β”œβ”€β”€ tools/                   # Tool implementations
β”‚   β”œβ”€β”€ llm/                     # LLM integration
β”‚   β”œβ”€β”€ memory/                  # Memory management
β”‚   β”‚   └── memory.py
β”‚   β”œβ”€β”€ utils/                   # Utility functions
β”‚   β”‚   β”œβ”€β”€ utils.py
β”‚   β”‚   β”œβ”€β”€ output_beautify.py
β”‚   β”‚   └── parallel_executor.py
β”‚   β”œβ”€β”€ agent.py                 # Base agent class
β”‚   β”œβ”€β”€ settings.py              # Configuration settings
β”‚   └── multi_agent_hub.py      # Multi-agent coordination
β”œβ”€β”€ examples/                    # Example scripts
β”‚   β”œβ”€β”€ rhoagent_example.py     # Example usage
β”‚   └── resource/                # Example resources
β”œβ”€β”€ tests/                       # Test files
β”‚   β”œβ”€β”€ agents/                  # Agent tests
β”‚   β”œβ”€β”€ llm/                     # LLM tests
β”‚   β”œβ”€β”€ tools/                   # Tool tests
β”‚   └── pipeline_test_output*/   # Test output directories
β”œβ”€β”€ run_agent.py                 # Main entry point
β”œβ”€β”€ setup.py                     # Package configuration
β”œβ”€β”€ MANIFEST.in                  # Package manifest
β”œβ”€β”€ LICENSE                      # Apache 2.0 License
└── README.md                    # This file

🧭 Supported Task Types

Task 1: Ribozyme Design

For Twister-P3, CPEB3, Hammerhead, and related ribozymes.

Typical flow:

  1. Confirm wildtype_seq, target_ss, fixed_motif, and work directory.
  2. Run rdiff_3d_backbone_design_tool.
  3. Run backbone_filter.
  4. Run rdiff_seq_design_tool.
  5. Run seq_filter.
  6. Run af3_prediction_pipeline.
  7. Run eval_rna_struct_batch.
  8. Run first_round_filtering(filter_mode="standard").
  9. Run llm_weighted_filter.

Task 2: Subsequence-Conditioned Ribozyme Design

Same core flow as Task 1, but the user also provides a subsequence that must be preserved. The subsequence is merged into the fixed motif constraints before sequence design.

Task 3: Hovlinc Limited-Prior Iterative Optimization

For Hovlinc-like cases with limited structural priors. The agent can infer secondary structure and pocket constraints using AF3, RNApolis, and find_pocket. Round 2 refinement is possible when wet-lab feedback is available.

Task 4: Single-Motif Fluorogenic Aptamer Scaffolding

For Broccoli or Pepper motif scaffolding. Uses rdiff_scaffolding_design_tool, not the generic secondary-structure backbone design tool.

Typical inputs:

  • motif/reference PDB
  • contig template
  • scaffold length range
  • ligand/ion context for AF3 when needed

Primary evaluation uses scaffolding_structure_eval.

Task 5: Dual-Motif Broccoli-Pepper FRET Scaffold Design

For one-chain Broccoli-Pepper FRET constructs. Uses a dual-motif PDB and a dual-motif contig such as:

10+/A3-16/15+/A29-47/10+/E3-22/15+/E35-47/10+

Primary evaluation uses scaffolding_structure_eval with both Broccoli and Pepper motif specs.

🧰 Core Components

Agents

  • RNA Design Pipeline Agent (rhoagent/agents/rhoagent_pipeline.py): Main agent that orchestrates the complete design pipeline
  • Assistant (rhoagent/agents/assistant.py): Base assistant with tool usage and file reading capabilities
  • FnCallAgent (rhoagent/agents/fncall_agent.py): Function calling agent
  • UserAgent (rhoagent/agents/user_agent.py): User interaction agent
  • Document Q&A Agents (rhoagent/agents/doc_qa/): Document question-answering agents (basic and parallel)

Tools

Design Tools

  • RDiff3DBackboneDesignTool (rdiff_3d_backbone_design_tool): Secondary-structure-conditioned backbone generation with RDiff_str.
    • Requires RDIFF_STR_CODE_DIR and PYTHON_CONDA_RDIFF in .env.
    • Reads checkpoints from RDIFF_BACKBONE_CHECKPOINT_DIR unless checkpoint_dir or checkpoint_paths is passed.
    • Splits total num_samples across all checkpoints.
  • RDiffScaffoldingDesignTool (rdiff_scaffolding_design_tool): Motif scaffolding using RDiff_str rna_scaffolding_training + scaffolding_iter.
    • Requires RDIFF_STR_CODE_DIR and PYTHON_CONDA_RDIFF in .env.
    • Reads checkpoints from RDIFF_SCAFFOLDING_CHECKPOINT_DIR.
    • Inputs include target_pdb_path, contigs, length range, and total num_samples.
    • Merges shard outputs into output_dir/inference_name.
  • RDiffSeqDesignTool (rdiff_seq_design_tool): Sequence design on filtered backbones with RDiff_seq.
    • Requires RDIFF_SEQ_CODE_DIR and PYTHON_CONDA_RDIFF in .env.
    • Reads checkpoints from RDIFF_SEQUENCE_CHECKPOINT_DIR.
    • Splits total num_samples across all sequence checkpoints.

Structure Tools

  • AF3PredictionPipelineTool: Batch structure prediction using AlphaFold3
  • ExtractSSTool: Extract secondary structure (dot-bracket) from PDB/CIF files
  • FindPocketTool: Identify functional pocket regions from structure and seed positions
  • Mxfold2PredictTool: Predict secondary structure from sequence
  • AnalyzeRNAStructureTool: Analyze RNA structure and return chain, residue, and base pair statistics

Evaluation Tools

  • EvalRNAStructBatchTool: Batch evaluation of predicted structures
    • TM-score and RMSD (structural similarity)
    • Sequence recovery rate and sequence similarity
    • Secondary structure F1-score (ss_f1score)
    • Functional core F1-score (functional_core_f1score)
    • Canonical pair ratios (ss_pairs_ratio, designed_pseudoknot_canonical_pairs_ratio)
  • ScaffoldingStructureEvalTool: Scaffolding-specific AF3 evaluation
    • WT motif gate
    • motif RMSD/TM only when WT motif gate passes
    • backbone-AF3 TM/RMSD/lDDT
    • compactness and motif-scaffold contact metrics
  • FirstRoundFilterTool: First-round filtering based on multiple criteria
    • filter_mode="standard" for ribozyme/general evals
    • filter_mode="scaffolding" for length-aware scaffolding selection
  • LLMWeightedFilterTool: LLM-determined weighted filtering for final candidate selection
  • PipelineCriticTool: Quality evaluation and decision-making for pipeline steps

Filtering Tools

  • BackboneFilterTool: Filter backbone structures based on secondary structure matching
  • SeqFilterTool: Filter FASTA records using GC, homopolymer, duplicate, optional repeated subsequence, and optional recovery-rate criteria

πŸ“Š Evaluation Metrics

The evaluation system provides comprehensive metrics for RNA design assessment:

Structure Metrics

  • TM-score: Structural similarity score (0-1, higher is better)
  • RMSD: Root mean square deviation (lower is better)

Sequence Metrics

  • seq_rec_rate: Sequence recovery rate (percentage of identical positions)
  • seq_similarity: Sequence similarity using local alignment (0-1)

Secondary Structure Metrics

  • ss_f1score: F1-score for secondary structure prediction (0-1)
  • functional_core_f1score: F1-score for fixed motif regions (0-1)
  • ss_pairs_ratio: Ratio of canonical pairs (AU+GC+GU) in target structure
  • designed_pseudoknot_canonical_pairs_ratio: Ratio of canonical AU/GC/GU pairs in designed/predicted pseudoknot regions

Scaffolding Metrics

  • backbone_af3_tm_score / backbone_af3_rmsd: AF3 prediction self-consistency against generated backbone
  • backbone_af3_lddt: C1'-based lDDT after backbone alignment
  • rg_norm / end_to_end_dist_norm: Length-normalized compactness metrics
  • non_motif_long_range_contact_density: Contacts among non-motif scaffold residues
  • isolated_scaffold_fraction: Fraction of weakly connected scaffold residues
  • motif_scaffold_contact_count: Potential unintended long-range motif-scaffold contacts
  • motif_rmsd / motif_tm_score: Used only when the WT motif gate indicates AF3 can reproduce the wild-type motif

🎯 Checkpoint Ensemble Behavior

The design tools support running multiple checkpoints automatically. The requested num_samples is treated as the total number of samples and split approximately evenly across checkpoints in the configured directory.

Example:

export RDIFF_SEQUENCE_CHECKPOINT_DIR=/path/to/RDiff_seq/checkpoints

If that directory contains four .pth files and the tool receives num_samples=100, each checkpoint is assigned about 25 samples. Exact allocation uses integer round-robin splitting.

You can override the .env directory per call using:

  • checkpoint_dir
  • checkpoint_paths

πŸ” Tool-Call Confirmation Policy

The pipeline agent is intentionally conservative. Before any tool call, it must show:

  1. the exact registered tool name
  2. the exact JSON parameters
  3. a prompt asking the user to confirm or modify the call

The agent should not call the tool until the user confirms the parameters.

πŸ“š Dependencies

Core Dependencies

  • dashscope>=1.11.0: Alibaba Cloud DashScope API
  • pydantic>=2.3.0: Data validation
  • openai: OpenAI-compatible API support
  • requests, json5, jsonschema: HTTP and JSON handling
  • Bio: Biopython for biological data processing
  • numpy, pandas: Numerical computing and data manipulation

Project Files

  • run_agent.py: Main entry point for running the RNA design agent interactively
  • setup.py: Package configuration and dependencies
  • MANIFEST.in: Files to include in package distribution
  • .gitignore: Git ignore patterns

πŸ“„ Citation

If you use RhoAgent in your research, please cite the associated paper:

@article{rhoagent,
  title   = {Programmable functional RNA design with a virtual scientist},
  author  = {Han Huang, Tianqing Zhang, Liang Hong, Ziqian Lin, Dongchen He, Jiuming Wang, Tian-Ying Wu, Huimin Li, Da Han, Le Yu, Jiyue Jiang, Yimin Fan, Yanruisheng Shao, Irwin King, Pengan Chen, Chun Kit Kwok, James J. Collins, and Yu Li},
  journal = {Nature Biotechnology},
  year    = {2026},
  doi     = {10.1038/s41587-026-03362-3}
}

πŸ“œ License

RhoAgent is released under the Apache License 2.0.

About

Nature Biotechnology: RhoAgent is an agentic framework for functional RNA design. It wraps RDiff, AlphaFold3, RNA secondary-structure extraction, structure evaluation, and filtering tools behind a task-oriented conversational agent.

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages