Skip to content

rdagent fin_quant Command Line Invocation Flow Analysis

rdagent fin_quant is the most complex command in the Qlib scenario, because it does not only do factor or model — it dynamically switches between the two and evolves them jointly.

This document focuses on:

  1. How fin_quant is entered from the CLI.
  2. What structural differences it has from the standard RDLoop.
  3. How the factor/model branches switch within the same loop.

1. Command Entry Point

fin_quant is registered in rdagent/app/cli.py:

from rdagent.app.qlib_rd_loop.quant import main as fin_quant

app.command(name="fin_quant")(fin_quant)

So the entry call chain is:

rdagent
  -> rdagent.app.cli:app
  -> Typer 子命令 fin_quant
  -> rdagent.app.qlib_rd_loop.quant.main()

Like fin_model, the module file itself also retains:

if __name__ == "__main__":
    fire.Fire(main)

So the unified CLI layer is Typer, while the module remains Fire-compatible when run standalone.

2. The Main Function

In rdagent/app/qlib_rd_loop/quant.py:

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

Core logic:

if path is None:
    quant_loop = QuantRDLoop(QUANT_PROP_SETTING)
else:
    quant_loop = QuantRDLoop.load(path, checkout=checkout)

asyncio.run(quant_loop.run(step_n=step_n, loop_n=loop_n, all_duration=all_duration))

Therefore fin_quant likewise supports:

  • Fresh startup
  • Session resumption
  • Step count control
  • Loop count control
  • Total duration control

3. Differences Between QuantRDLoop and the Standard RDLoop

QuantRDLoop inherits from RDLoop, but it does not simply reuse the standard assembly; instead it overrides:

  • __init__
  • direct_exp_gen
  • coding
  • running
  • feedback

The reason is simple: it needs to switch between the factor and model R&D chains.

It declares the skippable errors as:

skip_loop_error = (FactorEmptyError, ModelEmptyError)

4. QUANT_PROP_SETTING Assembles Dual-Track Components

In rdagent/app/qlib_rd_loop/conf.py:

class QuantBasePropSetting(BasePropSetting):
    scen = "rdagent.scenarios.qlib.experiment.quant_experiment.QlibQuantScenario"
    quant_hypothesis_gen = "rdagent.scenarios.qlib.proposal.quant_proposal.QlibQuantHypothesisGen"

    model_hypothesis2experiment = "rdagent.scenarios.qlib.proposal.model_proposal.QlibModelHypothesis2Experiment"
    model_coder = "rdagent.scenarios.qlib.developer.model_coder.QlibModelCoSTEER"
    model_runner = "rdagent.scenarios.qlib.developer.model_runner.QlibModelRunner"
    model_summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibModelExperiment2Feedback"

    factor_hypothesis2experiment = "rdagent.scenarios.qlib.proposal.factor_proposal.QlibFactorHypothesis2Experiment"
    factor_coder = "rdagent.scenarios.qlib.developer.factor_coder.QlibFactorCoSTEER"
    factor_runner = "rdagent.scenarios.qlib.developer.factor_runner.QlibFactorRunner"
    factor_summarizer = "rdagent.scenarios.qlib.developer.feedback.QlibFactorExperiment2Feedback"

This shows that the core of fin_quant is not a single coder / runner, but two sets:

factor 轨:
  hypothesis2experiment / coder / runner / summarizer

model 轨:
  hypothesis2experiment / coder / runner / summarizer

5. How QuantRDLoop.__init__() Assembles

QuantRDLoop explicitly creates during initialization:

  • QlibQuantScenario
  • QlibQuantHypothesisGen
  • factor's experiment generator / coder / runner / summarizer
  • model's experiment generator / coder / runner / summarizer
  • QuantTrace

The biggest difference from the standard RDLoop is that it does not have a single:

  • self.hypothesis2experiment
  • self.coder
  • self.runner
  • self.summarizer

Instead it maintains separate factor/model object sets.

6. QlibQuantScenario Is a Joint Scenario Descriptor

QlibQuantScenario in rdagent/scenarios/qlib/experiment/quant_experiment.py simultaneously provides:

  • Joint background
  • Factor background
  • Model background
  • A unified source data description
  • Respective interface, output format, and simulator for factor/model

When calling get_scenario_all_desc(), it can return different versions of the scenario description depending on:

  • filtered_tag
  • action

Therefore, in the quant scenario, the prompt given to the LLM is a "dynamic description with action context", not a static fixed description.

7. QuantTrace Has an Extra Controller Compared to the Ordinary Trace

QuantTrace inherits Trace and additionally holds:

self.controller = EnvController()

This controller is used to make strategy choices between the two actions factor/model; by default it is a bandit.

8. direct_exp_gen: Decide the Action First, Then Generate the Corresponding Experiment

This is the core difference of fin_quant.

The main logic of QuantRDLoop.direct_exp_gen():

hypo = self._propose()
assert hypo.action in ["factor", "model"]
if hypo.action == "factor":
    exp = self.factor_hypothesis2experiment.convert(hypo, self.trace)
else:
    exp = self.model_hypothesis2experiment.convert(hypo, self.trace)
return {"propose": hypo, "exp_gen": exp}

In other words, the proposal stage first produces a hypothesis carrying an action, and then decides which chain to follow.

8.1 How the action Is Chosen

QlibQuantHypothesisGen.prepare_context() supports three strategies:

  1. bandit
  2. llm
  3. random

The default configuration comes from:

QUANT_PROP_SETTING.action_selection = "bandit"

8.1.1 bandit

If it is bandit:

  • Extract metrics from the most recent experiment.result
  • Read the most recent action factor or model
  • Call trace.controller.record(metric, prev_action) to update the bandit
  • Call trace.controller.decide(metric) to select the next action

Internally, EnvController uses LinearThompsonTwoArm, i.e. a two-arm Thompson Sampling structure.

8.1.2 llm

If it is llm:

  • Concatenate historical hypothesis/feedback into a prompt
  • Let the LLM directly output the next action action

8.1.3 random

Simply pick randomly between factor / model.

8.2 The action Determines the Prompt Context

Once the action is determined, QlibQuantHypothesisGen will:

  • Set self.targets to the corresponding action
  • Select only the trace subset relevant to that action
  • Construct different RAG prompts for factor and model respectively

For example:

  • factor: in early rounds prefer simple, fast factors; in later rounds encourage high-IC factors
  • model: emphasize time series models and controlled hyperparameters

8.3 The hypothesis Output Object

What is ultimately returned is not an ordinary Hypothesis, but:

class QlibQuantHypothesis(Hypothesis):
    action: str

So in the quant scenario the hypothesis itself carries routing information.

9. coding: Route to Different Coders by action

QuantRDLoop.coding():

if action == "factor":
    exp = self.factor_coder.develop(...)
elif action == "model":
    exp = self.model_coder.develop(...)

So the real branching at the coding stage is:

  • factor: QlibFactorCoSTEER
  • model: QlibModelCoSTEER

That is, it respectively reuses the CoSTEER development capabilities of fin_factor and fin_model.

10. running: Route to Different Runners by action

QuantRDLoop.running():

if action == "factor":
    exp = self.factor_runner.develop(...)
elif action == "model":
    exp = self.model_runner.develop(...)

The corresponding behavior is:

  • Factor rounds: go through QlibFactorRunner
  • Model rounds: go through QlibModelRunner

So fin_quant's runner logic is not new; it chains the two independent pipelines into one overall loop.

11. feedback: Use Different Summarizers by action

On successful execution:

if action == "factor":
    feedback = self.factor_summarizer.generate_feedback(...)
elif action == "model":
    feedback = self.model_summarizer.generate_feedback(...)

On failure it uniformly falls back to:

HypothesisFeedback(decision=False, ...)

Finally, (experiment, feedback) is likewise appended to trace.hist.

Since trace.hist mixes both factor and model results, the next round's action selection and hypothesis generation can see cross-type history.

12. How the factor/model Chains Influence Each Other

This is the most important design point of fin_quant.

12.1 Factor Rounds Reference Model History

When action=factor, QlibQuantHypothesisGen puts:

  • All factor history
  • The most recently accepted model experiment

together into specific_trace.

This means that when generating new factors, the current best model background is taken into account.

12.2 Model Rounds Reference Factor History

When action=model, it puts:

  • All model history
  • The most recently accepted factor experiment

together into the context.

Meanwhile, QlibModelRunner also merges the SOTA factors into combined_factors_df.parquet for model training.

This means model iteration is explicitly built on top of the current best factor library.

13. Session and Resumption Mechanism

fin_quant likewise inherits LoopBase's session mechanism; every time a step completes, a snapshot is saved at:

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

When resuming, use:

QuantRDLoop.load(path, checkout=checkout)

14. The Complete Call Chain in One Diagram

rdagent fin_quant
  -> rdagent/app/cli.py
  -> rdagent/app/qlib_rd_loop/quant.py: main()
  -> QuantRDLoop(QUANT_PROP_SETTING)
  -> LoopBase.run()
  -> direct_exp_gen
       -> QlibQuantHypothesisGen
       -> 先决定 action = factor 或 model
       -> factor_hypothesis2experiment / model_hypothesis2experiment
  -> coding
       -> factor_coder 或 model_coder
  -> running
       -> factor_runner 或 model_runner
  -> feedback
       -> factor_summarizer 或 model_summarizer
  -> 写回 QuantTrace
  -> 下一轮再决定 action

15. Conclusion

The essence of rdagent fin_quant is a joint R&D controller with "switchable actions":

统一 CLI 入口
  -> Quant 场景 hypothesis 生成
  -> 先决定本轮做 factor 还是 model
  -> 路由到对应的生成/开发/执行/反馈链
  -> 把结果混合写回同一个 Trace
  -> 用 bandit / LLM / random 决定下一轮方向

Therefore it is not simply concatenating fin_factor and fin_model sequentially, but dynamically allocating R&D resources within the same iterative closed loop.