rdagent fin_factor Command Line Invocation Flow Analysis¶
This document traces the actual call chain of rdagent fin_factor based on the source code, focusing on three questions:
- How the command
rdagent fin_factorgets registered. - Which core objects and stages the command enters after execution.
- Where factor experiment code, backtest execution, and feedback recording are each completed.
1. Where the Command Entry Point Comes From¶
The rdagent command itself comes from the script entry in pyproject.toml:
[project.scripts]
rdagent = "rdagent.app.cli:app"
This means that when the user enters:
rdagent fin_factor
it actually goes into the app object in rdagent/app/cli.py. This app is a Typer application in which all subcommand registration is done:
app = typer.Typer()
app.command(name="fin_factor")(fin_factor)
Here fin_factor is not a string, but the main function imported from the following module:
from rdagent.app.qlib_rd_loop.factor import main as fin_factor
So the first segment of the call chain can be written as:
rdagent
-> pyproject.toml [project.scripts]
-> rdagent.app.cli:app
-> Typer 子命令 fin_factor
-> rdagent.app.qlib_rd_loop.factor.main()
2. The Main Function the fin_factor Command Actually Calls¶
main() in rdagent/app/qlib_rd_loop/factor.py is the direct entry point of this subcommand:
def main(
path: Optional[str] = None,
step_n: Optional[int] = None,
loop_n: Optional[int] = None,
all_duration: str | None = None,
checkout: Annotated[bool, typer.Option("--checkout/--no-checkout", "-c/-C")] = True,
checkout_path: Optional[str] = None,
):
From the source code, this entry point mainly does two things:
- Deciding whether to start a new
FactorRDLoopor resume from a historical session. - Using
asyncio.run()to start the entire R&D closed loop.
The core logic is as follows:
if not checkout_path is None:
checkout = Path(checkout_path)
if path is None:
model_loop = FactorRDLoop(FACTOR_PROP_SETTING)
else:
model_loop = FactorRDLoop.load(path, checkout=checkout)
asyncio.run(model_loop.run(step_n=step_n, loop_n=loop_n, all_duration=all_duration))
So it can be further summarized as:
path is None: run a new factor R&D loop from scratch.path is not None: resume execution from some__session__snapshot.step_n: limit the maximum number of additional steps to run.loop_n: limit the maximum number of additional loops to run.all_duration: set a global timeout.checkout/checkout_path: control whether to reuse/switch the log and session directories when resuming a session.
3. FactorRDLoop Is Just a Thin Wrapper¶
FactorRDLoop is defined in rdagent/app/qlib_rd_loop/factor.py; it is itself very thin, and the real process framework comes from the parent class RDLoop:
class FactorRDLoop(RDLoop):
skip_loop_error = (FactorEmptyError,)
def running(self, prev_out: dict[str, Any]):
exp = self.runner.develop(prev_out["coding"])
if exp is None:
raise FactorEmptyError("Factor extraction failed.")
return exp
This subclass only does two things:
- Declaring that
FactorEmptyErroris an error for which the current loop can be skipped. - Overriding
running()to actively raise an error when the runner returns an empty result.
So fin_factor's main behavior does not lie in FactorRDLoop itself, but in the RDLoop + LoopBase it inherits.
4. FACTOR_PROP_SETTING Determines Which Classes This Chain Assembles¶
When creating FactorRDLoop(FACTOR_PROP_SETTING), what really matters is FACTOR_PROP_SETTING. It is defined in rdagent/app/qlib_rd_loop/conf.py:
class FactorBasePropSetting(BasePropSetting):
scen = "rdagent.scenarios.qlib.experiment.factor_experiment.QlibFactorScenario"
hypothesis_gen = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesisGen"
hypothesis2experiment = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesis2Experiment"
coder = "rdagent.scenarios.qlib.developer.factor_coder.QlibFactorCoSTEER"
runner = "rdagent.scenarios.qlib.developer.factor_runner.QlibFactorRunner"
summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibFactorExperiment2Feedback"
This is equivalent to telling RDLoop:
- Use
QlibFactorScenariofor the scenario object - Use
QlibFactorHypothesisGenfor the hypothesis generator - Use
QlibFactorHypothesis2Experimentfor the hypothesis-to-experiment converter - Use
QlibFactorCoSTEERfor the code developer - Use
QlibFactorRunnerfor the experiment executor - Use
QlibFactorExperiment2Feedbackfor the feedback summarizer
In other words, fin_factor does not hardcode the logic in one function, but assembles a whole set of "scenario components" through configuration.
5. RDLoop Completes Object Assembly During Initialization¶
RDLoop.__init__() in rdagent/components/workflow/rd_loop.py:
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 completes the core dependency injection of the whole execution chain:
FactorRDLoop
-> QlibFactorScenario
-> QlibFactorHypothesisGen
-> QlibFactorHypothesis2Experiment
-> QlibFactorCoSTEER
-> QlibFactorRunner
-> QlibFactorExperiment2Feedback
-> Trace
Trace is critical: it stores historical experiments and feedback, and the subsequent proposal stage will feed these historical records back to the LLM.
6. The Real Runtime Skeleton Comes from LoopBase.run()¶
RDLoop inherits LoopBase, and LoopBase automatically collects steps via the LoopMeta metaclass. For RDLoop, the actual steps are:
direct_exp_gen -> coding -> running -> feedback
What LoopBase.run() does can be summarized as:
- Initializing the timer, step count, and loop count.
- Starting
kickoff_loop()to continuously create new loops. - Starting several
execute_loop()workers to consume loops in parallel. - Dumping a session snapshot each time a step completes.
- Stopping after the
step_n,loop_n, orall_durationcondition is reached.
This mechanism gives rdagent fin_factor:
- Multi-round iteration capability
- Parallel execution capability
- Timeout stop capability
- Interrupt-and-resume capability
7. The Four Stages of Each Loop¶
Below we expand in the real step order.
7.1 direct_exp_gen: First Propose a Hypothesis, Then Convert the Hypothesis into Experiment Tasks¶
The core logic of RDLoop.direct_exp_gen():
hypo = self._propose()
exp = self._exp_gen(hypo)
return {"propose": hypo, "exp_gen": exp}
Where:
_propose()callsself.hypothesis_gen.gen(self.trace)_exp_gen()callsself.hypothesis2experiment.convert(hypothesis, self.trace)
That is, this step actually contains two sub-stages.
7.1.1 Hypothesis generation: QlibFactorHypothesisGen¶
QlibFactorHypothesisGen first constructs the context based on trace.hist:
- Historical hypotheses and feedback
- The feedback of the most recent experiment
- A simple RAG prompt
- The hypothesis output format description
- Hypothesis writing guidelines
Then it hands this to APIBackend().build_messages_and_create_chat_completion(...) to call the LLM, and finally converts the JSON response into a Hypothesis object.
So the proposal stage is not fixed-rule generation, but:
Trace 历史
+ QlibFactorScenario 描述
+ Prompt 模板
+ LLM
-> Hypothesis
7.1.2 Experiment generation: QlibFactorHypothesis2Experiment¶
This step continues to call the LLM, but the goal changes from "proposing an idea" to "breaking the idea down into implementable factor tasks".
It feeds the following information to the model:
- The current hypothesis
- The scenario description
- Historical experiments and feedback
- The list of existing factors
- The experiment output format requirements
After the model returns JSON, it is converted into multiple FactorTasks, which are then assembled into a QlibFactorExperiment.
Each FactorTask contains at least:
factor_namefactor_descriptionfactor_formulationvariables
Meanwhile, this step also performs a layer of deduplication:
- Collecting existing factors from historical
based_experiments - If a task name in the current round duplicates a historical one, it is excluded from the new tasks
This shows that fin_factor's proposal stage not only "generates new tasks" but also actively avoids repeatedly mining factors with exactly the same names.
7.2 coding: QlibFactorCoSTEER Generates the Factor Code¶
RDLoop.coding() is very direct:
exp = self.coder.develop(prev_out["direct_exp_gen"]["exp_gen"])
Mapped to the factor scenario, self.coder is QlibFactorCoSTEER, which is essentially an alias of FactorCoSTEER.
FactorCoSTEER in turn inherits from the general CoSTEER, and its way of working is:
- Converting the
Experimentinto an evolvable object. - Creating a
RAGEvoAgent. - Continuously modifying the implementation over multiple evolve rounds.
- Using an evaluator to check implementation quality.
- Selecting an acceptable fallback version as the final submitted result.
This is not "one-shot code generation", but "multi-round generation-execution-evaluation-improvement".
7.2.1 What the coding stage evaluates¶
The factor coder uses FactorEvaluatorForCoder, which combines three types of checks:
- Execution feedback
- Factor value checks
- Code quality and the final decision
The very first internal step actually executes the workspace code:
execution_feedback, gen_df = implementation.execute()
That is, during the coding stage the generated factor.py is already run, and it checks:
- Whether the code runs through
- Whether
result.h5was produced - Whether the resulting dataframe meets the expected format
7.2.2 How FactorFBWorkspace.execute() actually runs the code¶
The behavior of FactorFBWorkspace.execute() is key:
- Creating an independent working directory.
- Injecting
factor.pyinto the workspace. - Symlinking the source data into the workspace.
- Executing
factor.pywith the Python interpreter from the configuration. - Reading the output file
result.h5. - Returning
(execution_feedback, factor_dataframe).
If execution fails, the truncated stderr/stdout is returned as feedback; if result.h5 was not generated, it is treated as a failure.
So the coding stage's output is not abstract code text, but:
- The
factor.pywritten into the workspace - Real execution feedback after actually running
- The actually generated factor dataframe
7.3 running: QlibFactorRunner Organizes Factor Merging and the Qlib Backtest¶
FactorRDLoop.running() calls:
exp = self.runner.develop(prev_out["coding"])
Here the runner is QlibFactorRunner. Compared with the coding stage, it leans more toward being an "experiment executor", mainly responsible for integrating the successfully implemented factors into the Qlib backtest pipeline.
The core steps are as follows.
7.3.1 Preparing the baseline and historical SOTA first¶
If the last experiment in exp.based_experiments has not been run yet, the runner will recursively execute it first. This usually means ensuring that the baseline or historical SOTA already has results.
7.3.2 Extracting and merging this round's new factors¶
process_factor_data(exp) calls each successful workspace's implementation.execute("All") again to obtain the factor values on the full sample, then:
- Filters out invalid results
- Filters out minute-level data
- Column-concatenates all successful factors into one dataframe
7.3.3 Deduplicating against the historical SOTA factors¶
If a historical SOTA factor set exists, the runner computes the correlations between the new and old factors and removes new factors that are highly similar to existing ones:
- Via
deduplicate_new_factors() - If the correlation exceeds a threshold, it is considered a duplicate
- If all are judged as duplicates,
FactorEmptyErroris raised
This is why some loops are skipped rather than crashing outright, because FactorRDLoop.skip_loop_error has already marked this class of errors as "skip the current round".
7.3.4 Writing combined_factors_df.parquet¶
The merged factors are not left only in memory; they are written to the experiment workspace:
<experiment_workspace>/combined_factors_df.parquet
parquet rather than pickle is deliberately used here; the source comments explain the reason as numpy version compatibility across environments.
7.3.5 Calling the Qlib environment to run the backtest¶
QlibFactorRunner relies on QlibFBWorkspace.execute() to actually run the backtest. This method will:
- Select the
dockerorcondaenvironment according to the configuration. - Execute
qrun <config>in the workspace. - Then execute
python read_exp_res.pyto read the experiment results. - Read from the workspace:
qlib_res.csvret.pkl
Depending on the situation, the runner selects different configuration files:
conf_baseline.yamlconf_combined_factors.yamlconf_combined_factors_sota_model.yaml
If a SOTA model exists in history, the corresponding model.py will also be injected into the current workspace, and the training hyperparameters passed in via environment variables.
So the essence of the running stage is:
本轮通过 coding 的因子
+ 历史 SOTA 因子/模型
+ Qlib 模板工作区
-> qrun 回测
-> 产出绩效结果
7.4 feedback: Writing the Results Back to Trace¶
RDLoop.feedback() has two branches:
- This round had an exception
- This round executed successfully
If an exception occurs:
- Construct a
HypothesisFeedback(decision=False, ...) - Write the exception information into
observations - Record the failed experiment into
trace.hist
If execution succeeds:
- Hand it to
self.summarizer.generate_feedback(...) - Obtain structured feedback
- Then append
(experiment, feedback)totrace.hist
Therefore Trace keeps accumulating:
(实验, 反馈)
(实验, 反馈)
(实验, 反馈)
...
The next round's proposal will again use these historical records as context, forming a genuinely self-iterating closed loop.
8. The Session Resumption and Checkpoint Continue Mechanism¶
An important feature of fin_factor is support for resuming from session snapshots.
Each time a step completes, LoopBase pickles the current loop object to:
<trace_path>/__session__/<loop_id>/<step_id>_<step_name>
When resuming, it is loaded via FactorRDLoop.load(path, checkout=...):
- If a directory is passed in, the latest snapshot is automatically taken
- If
checkout=True, subsequent sessions/logs are truncated, keeping only the state before the current node - If
checkoutis a path, the resumed session is output to a new directory
This means the following pattern is valid:
跑到一半停止
-> 定位某个 __session__ 快照
-> load()
-> 从中间继续执行
This is also the origin of the "continue running session" mentioned in the source comments.
9. Where the Caching Mechanism Sits in This Chain¶
There are at least two layers of caching in the fin_factor chain:
9.1 Workspace-level caching¶
FactorFBWorkspace.execute() uses cache_with_pickle(hash_func); for the same factor.py implementation, repeated execution can be avoided.
9.2 Runner-level caching¶
QlibFactorRunner.develop() also uses cache_with_pickle(...), with the cache key computed jointly from:
- The task information in the historical
based_experiments - The task information in the current
exp.sub_tasks
This means that if the task set has not changed, the runner-level backtest results can also be reused.
10. The Complete Call Chain in One Diagram¶
rdagent fin_factor
-> pyproject.toml: rdagent = rdagent.app.cli:app
-> rdagent/app/cli.py
-> app.command(name="fin_factor")(factor.main)
-> rdagent/app/qlib_rd_loop/factor.py: main()
-> FactorRDLoop(FACTOR_PROP_SETTING) or FactorRDLoop.load(...)
-> asyncio.run(loop.run(...))
-> LoopBase.run()
-> direct_exp_gen
-> QlibFactorHypothesisGen.gen(trace)
-> QlibFactorHypothesis2Experiment.convert(hypothesis, trace)
-> QlibFactorExperiment + FactorTask[]
-> coding
-> QlibFactorCoSTEER.develop(exp)
-> 反复生成/执行/评估 factor.py
-> 产出 sub_workspace_list
-> running
-> QlibFactorRunner.develop(exp)
-> process_factor_data()
-> 合并/去重因子
-> 写入 combined_factors_df.parquet
-> QlibFBWorkspace.execute()
-> qrun 回测,读取 qlib_res.csv / ret.pkl
-> feedback
-> QlibFactorExperiment2Feedback.generate_feedback(...)
-> trace.hist 追加 (experiment, feedback)
-> 下一轮 loop
11. Conclusion¶
On the surface rdagent fin_factor is just a CLI command, but at the source code level it actually starts a "resumable, parallelizable, self-iterating" R&D closed loop. It can be summarized in the following sentence:
Typer 命令入口
-> 组装 Qlib 因子场景组件
-> 用 LLM 生成 hypothesis 与 factor tasks
-> 用 CoSTEER 实现并调试因子代码
-> 用 Qlib runner 合并因子并执行回测
-> 把结果写回 Trace,驱动下一轮演化
If you only look at the CLI, it is easy to mistakenly think that rdagent fin_factor just "runs a script"; but from the source code structure, it is closer to an automated R&D workflow engine with session management.