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:
- How the CLI exposes
fin_model. - How
fin_model's standard loop is assembled. - 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.pyis executed directly, the bottom of the file still retainsfire.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 scratchpathhas a value: resume from a historical__session__snapshotstep_n: limit the number of remaining stepsloop_n: limit the number of remaining loopsall_duration: limit the total run durationcheckout: 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:
- Initializing the timer and limit conditions
- Starting
kickoff_loop()to create the loop - Starting
execute_loop()to run the worker - Pickling the entire loop object to
__session__after each step completes - Stopping once
step_n,loop_n, orall_durationis 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:
namedescriptionformulationarchitecturevariableshyperparameterstraining_hyperparametersmodel_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:
- Converting the experiment into an evolvable object
- Generating and modifying
model.pyover multiple rounds - Executing, checking, and feeding back with an evaluator
- 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:
- Preparing the historical best factor features
- Injecting the
model.pygenerated in the current round into the experiment workspace - Setting training hyperparameter environment variables
- 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_epochslrearly_stopbatch_sizeweight_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.yamlTimeSeries+ SOTA factors:conf_sota_factors_model.yamlTabular+ baseline factors:conf_baseline_factors_model.yamlTabular+ SOTA factors:conf_sota_factors_model.yaml
It also sets:
dataset_clsnum_featuresstep_lennum_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:
- Choosing the
dockerorcondaenvironment - Executing
qrun <config>in the workspace - Executing
python read_exp_res.py - Reading
qlib_res.csvandret.pkl
Finally, QlibModelRunner writes the results back to:
exp.resultexp.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.