Skip to content

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:

  1. How the command rdagent fin_factor gets registered.
  2. Which core objects and stages the command enters after execution.
  3. 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:

  1. Deciding whether to start a new FactorRDLoop or resume from a historical session.
  2. 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:

  1. Declaring that FactorEmptyError is an error for which the current loop can be skipped.
  2. 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 QlibFactorScenario for the scenario object
  • Use QlibFactorHypothesisGen for the hypothesis generator
  • Use QlibFactorHypothesis2Experiment for the hypothesis-to-experiment converter
  • Use QlibFactorCoSTEER for the code developer
  • Use QlibFactorRunner for the experiment executor
  • Use QlibFactorExperiment2Feedback for 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:

  1. Initializing the timer, step count, and loop count.
  2. Starting kickoff_loop() to continuously create new loops.
  3. Starting several execute_loop() workers to consume loops in parallel.
  4. Dumping a session snapshot each time a step completes.
  5. Stopping after the step_n, loop_n, or all_duration condition 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() calls self.hypothesis_gen.gen(self.trace)
  • _exp_gen() calls self.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_name
  • factor_description
  • factor_formulation
  • variables

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:

  1. Converting the Experiment into an evolvable object.
  2. Creating a RAGEvoAgent.
  3. Continuously modifying the implementation over multiple evolve rounds.
  4. Using an evaluator to check implementation quality.
  5. 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:

  1. Execution feedback
  2. Factor value checks
  3. 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.h5 was 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:

  1. Creating an independent working directory.
  2. Injecting factor.py into the workspace.
  3. Symlinking the source data into the workspace.
  4. Executing factor.py with the Python interpreter from the configuration.
  5. Reading the output file result.h5.
  6. 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.py written 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, FactorEmptyError is 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:

  1. Select the docker or conda environment according to the configuration.
  2. Execute qrun <config> in the workspace.
  3. Then execute python read_exp_res.py to read the experiment results.
  4. Read from the workspace:
  5. qlib_res.csv
  6. ret.pkl

Depending on the situation, the runner selects different configuration files:

  • conf_baseline.yaml
  • conf_combined_factors.yaml
  • conf_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:

  1. This round had an exception
  2. 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) to trace.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 checkout is 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.