Skip to content

rdagent fin_model Command Line Invocation Flow Analysis

This document analyzes the call chain of rdagent fin_model based on the source code, focusing on:

  1. How the CLI exposes fin_model.
  2. How fin_model's standard loop is assembled.
  3. What proposal, coding, running, and feedback each do in the model scenario.

1. Command Entry Point

The rdagent command comes from pyproject.toml:

[project.scripts]
rdagent = "rdagent.app.cli:app"

What actually registers the fin_model subcommand is rdagent/app/cli.py:

from rdagent.app.qlib_rd_loop.model import main as fin_model

app = typer.Typer()
app.command(name="fin_model")(fin_model)

So the first segment of the call chain is:

rdagent
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_model
  -> rdagent.app.qlib_rd_loop.model.main()

Note that two layers of entry points coexist:

  • When invoked from the unified CLI, it uses Typer
  • When rdagent/app/qlib_rd_loop/model.py is executed directly, the bottom of the file still retains fire.Fire(main)

In other words, the project-level unified command entry is Typer, while the module remains Fire-compatible when run standalone.

2. fin_model's Main Function

The entry point in rdagent/app/qlib_rd_loop/model.py is as follows:

def main(
    path=None,
    step_n: int | None = None,
    loop_n: int | None = None,
    all_duration: str | None = None,
    checkout: bool = True,
):

The core logic is very direct:

if path is None:
    model_loop = ModelRDLoop(MODEL_PROP_SETTING)
else:
    model_loop = ModelRDLoop.load(path, checkout=checkout)
asyncio.run(model_loop.run(step_n=step_n, loop_n=loop_n, all_duration=all_duration))

This means:

  • path is None: run the model evolution pipeline from scratch
  • path has a value: resume from a historical __session__ snapshot
  • step_n: limit the number of remaining steps
  • loop_n: limit the number of remaining loops
  • all_duration: limit the total run duration
  • checkout: when resuming, whether to truncate and reuse the current session/log

3. ModelRDLoop Is a Standard RDLoop

ModelRDLoop is defined very thinly:

class ModelRDLoop(RDLoop):
    skip_loop_error = (ModelEmptyError,)

It does not override coding, running, or feedback, so fin_model directly uses RDLoop's standard four stages:

direct_exp_gen -> coding -> running -> feedback

In other words, fin_model is the command closest to the "standard template" in the Qlib scenario.

4. MODEL_PROP_SETTING Determines Which Components Are Assembled

rdagent/app/qlib_rd_loop/conf.py defines the dependency injection configuration for the model scenario:

class ModelBasePropSetting(BasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.model_experiment.QlibModelScenario"
    hypothesis_gen = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesisGen"
    hypothesis2experiment = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesis2Experiment"
    coder = "rdagent.scenarios.qlib.developer.model_coder.QlibModelCoSTEER"
    runner = "rdagent.scenarios.qlib.developer.model_runner.QlibModelRunner"
    summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibModelExperiment2Feedback"

Therefore ModelRDLoop(MODEL_PROP_SETTING) will obtain, during initialization:

QlibModelScenario
QlibModelHypothesisGen
QlibModelHypothesis2Experiment
QlibModelCoSTEER
QlibModelRunner
QlibModelExperiment2Feedback
Trace

5. The Assembly Process During RDLoop Initialization

RDLoop.__init__() in rdagent/components/workflow/rd_loop.py dynamically imports the above string configurations into objects:

scen = import_class(PROP_SETTING.scen)()
self.hypothesis_gen = import_class(PROP_SETTING.hypothesis_gen)(scen)
self.hypothesis2experiment = import_class(PROP_SETTING.hypothesis2experiment)()
self.coder = import_class(PROP_SETTING.coder)(scen)
self.runner = import_class(PROP_SETTING.runner)(scen)
self.summarizer = import_class(PROP_SETTING.summarizer)(scen)
self.trace = Trace(scen=scen)

This shows that fin_model's main function is only responsible for starting the loop; the real scenario capabilities are all assembled through configuration.

6. The Runtime Skeleton: LoopBase.run()

RDLoop inherits from LoopBase. LoopBase.run() is responsible for:

  1. Initializing the timer and limit conditions
  2. Starting kickoff_loop() to create the loop
  3. Starting execute_loop() to run the worker
  4. Pickling the entire loop object to __session__ after each step completes
  5. Stopping once step_n, loop_n, or all_duration is reached

Therefore fin_model has:

  • Multi-round iteration
  • Parallel step execution
  • Session checkpoint resumption
  • Global timeout control

7. The Four-Stage Call Flow

7.1 direct_exp_gen

RDLoop.direct_exp_gen() internally executes in sequence:

hypo = self._propose()
exp = self._exp_gen(hypo)
return {"propose": hypo, "exp_gen": exp}

That is:

QlibModelHypothesisGen.gen(trace)
  -> 生成 hypothesis
QlibModelHypothesis2Experiment.convert(hypothesis, trace)
  -> 生成 QlibModelExperiment

7.1.1 hypothesis generation

QlibModelHypothesisGen organizes the following information and sends it to the LLM:

  • Historical hypotheses + feedback
  • The hypothesis + feedback of the most recent experiment of the same kind
  • The current SOTA hypothesis + feedback
  • RAG prompts targeted at quantitative models

The RAG prompts here emphasize two points:

  • Prefer time-series modeling scenarios, suitable for GRU/LSTM
  • Data scale is limited, so the model and training hyperparameters must be kept under control

7.1.2 experiment generation

QlibModelHypothesis2Experiment converts the hypothesis into one or more ModelTasks. Each task will contain:

  • name
  • description
  • formulation
  • architecture
  • variables
  • hyperparameters
  • training_hyperparameters
  • model_type

The final product is a QlibModelExperiment.

8. QlibModelExperiment and the Scenario Object

The model experiment object is defined in rdagent/scenarios/qlib/experiment/model_experiment.py:

class QlibModelExperiment(ModelExperiment):
    def __init__(...):
        self.experiment_workspace = QlibFBWorkspace(
            template_folder_path=Path(__file__).parent / "model_template"
        )

It automatically carries an experiment workspace based on model_template.

Meanwhile, the scenario description that QlibModelScenario provides to the LLM includes:

  • Background information
  • Code interface specification
  • Output format specification
  • Simulator/executor description
  • The current model runtime environment

9. The coding Stage: QlibModelCoSTEER

RDLoop.coding() will call:

exp = self.coder.develop(prev_out["direct_exp_gen"]["exp_gen"])

Here self.coder is QlibModelCoSTEER, which is simply:

QlibModelCoSTEER = ModelCoSTEER

ModelCoSTEER essentially follows the general CoSTEER framework, with the flow:

  1. Converting the experiment into an evolvable object
  2. Generating and modifying model.py over multiple rounds
  3. Executing, checking, and feeding back with an evaluator
  4. Selecting an acceptable fallback version

So fin_model's coding stage does not produce code in one shot, but is a "generate -> run -> evaluate -> iterate" CoSTEER closed loop.

10. The running Stage: QlibModelRunner

QlibModelRunner.develop() is where fin_model and fin_factor differ the most.

Its main responsibilities are:

  1. Preparing the historical best factor features
  2. Injecting the model.py generated in the current round into the experiment workspace
  3. Setting training hyperparameter environment variables
  4. Calling the Qlib template to perform training and backtesting

10.1 Handling the historical SOTA factor first

If a successful QlibFactorExperiment exists in based_experiments, the runner will:

  • Re-run the historical SOTA factors into a dataframe via process_factor_data()
  • Merge them into combined_factors_df.parquet
  • Place it into the current experiment workspace

This step is equivalent to providing model training with "the current optimal factor library".

10.2 Injecting model.py

The runner checks the workspace produced by the coding stage:

if exp.sub_workspace_list[0].file_dict.get("model.py") is None:
    raise ModelEmptyError("model.py is empty")

Then writes model.py into the experiment workspace:

exp.experiment_workspace.inject_files(**{"model.py": ...})

10.3 Injecting training parameters

If training_hyperparameters is not empty, the runner passes these parameters as environment variables to the Qlib execution environment:

  • n_epochs
  • lr
  • early_stop
  • batch_size
  • weight_decay

10.4 Choosing the configuration by model type

The runner selects different configurations based on model_type and whether SOTA factors exist:

  • TimeSeries + baseline factors: conf_baseline_factors_model.yaml
  • TimeSeries + SOTA factors: conf_sota_factors_model.yaml
  • Tabular + baseline factors: conf_baseline_factors_model.yaml
  • Tabular + SOTA factors: conf_sota_factors_model.yaml

It also sets:

  • dataset_cls
  • num_features
  • step_len
  • num_timesteps

10.5 Actual execution still goes through QlibFBWorkspace.execute()

The execution stage ultimately lands in QlibFBWorkspace.execute() in rdagent/scenarios/qlib/experiment/workspace.py:

  1. Choosing the docker or conda environment
  2. Executing qrun <config> in the workspace
  3. Executing python read_exp_res.py
  4. Reading qlib_res.csv and ret.pkl

Finally, QlibModelRunner writes the results back to:

  • exp.result
  • exp.stdout

If the result is empty, it raises ModelEmptyError.

11. The feedback Stage: QlibModelExperiment2Feedback

The standard RDLoop.feedback() calls, on successful execution:

feedback = self.summarizer.generate_feedback(prev_out["running"], self.trace)

The summarizer corresponding to the model scenario is QlibModelExperiment2Feedback.

It sends the following content to the LLM:

  • The current hypothesis
  • The current model task information
  • The current model.py
  • Key metrics in the current experiment results
  • Historical SOTA hypothesis / task / code / result

Finally it produces a HypothesisFeedback and appends (experiment, feedback) to trace.hist.

This directly influences the next round's proposal.

12. The Session Resumption Mechanism

Each time a step completes, LoopBase dumps the current object to:

<trace_path>/__session__/<loop_id>/<step_id>_<step_name>

When fin_model resumes execution, it goes through:

ModelRDLoop.load(path, checkout=checkout)

It supports:

  • Resuming directly by passing a session file
  • Automatically selecting the latest session when a directory is passed
  • Truncating subsequent sessions/logs when checkout=True

13. The Complete Chain in One Diagram

rdagent fin_model
  -> rdagent/app/cli.py
  -> rdagent/app/qlib_rd_loop/model.py: main()
  -> ModelRDLoop(MODEL_PROP_SETTING)
  -> LoopBase.run()
  -> direct_exp_gen
       -> QlibModelHypothesisGen
       -> QlibModelHypothesis2Experiment
       -> QlibModelExperiment + ModelTask
  -> coding
       -> QlibModelCoSTEER / ModelCoSTEER
       -> 生成并迭代 model.py
  -> running
       -> QlibModelRunner
       -> 合并 SOTA factor
       -> 注入 model.py 与训练超参数
       -> 选择 Qlib 配置执行训练/回测
  -> feedback
       -> QlibModelExperiment2Feedback
       -> 写回 Trace
  -> 下一轮循环

14. Conclusion

The essence of rdagent fin_model is not "running a model script", but:

CLI 入口
  -> LLM 生成模型 hypothesis
  -> LLM 生成模型任务
  -> CoSTEER 迭代实现 model.py
  -> Qlib runner 训练并回测
  -> LLM 生成反馈并推动下一轮模型演进

Compared with fin_factor, it reuses the same workflow skeleton, but switches the "implementation object" and "runner logic" to the model R&D scenario.