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:
- How
fin_quantis entered from the CLI. - What structural differences it has from the standard
RDLoop. - 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_gencodingrunningfeedback
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:
QlibQuantScenarioQlibQuantHypothesisGen- 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.hypothesis2experimentself.coderself.runnerself.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_tagaction
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:
banditllmrandom
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
factorormodel - 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.targetsto 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 factorsmodel: 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:QlibFactorCoSTEERmodel: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.