rdagent fin_factor_report Command Line Invocation Flow Analysis¶
rdagent fin_factor_report and fin_factor use the same factor execution framework, but its proposal stage does not "freely propose hypotheses from historical feedback"; instead it "first reads PDF reports, extracts factors and hypotheses from the reports, and then enters the standard factor development and backtest chain".
This document focuses on:
- How the CLI entry point leads into
fin_factor_report - What it shares with
fin_factorand where it differs - How report parsing, factor extraction, and the subsequent coding/running are connected
1. Command Entry Point¶
In rdagent/app/cli.py:
from rdagent.app.qlib_rd_loop.factor_from_report import main as fin_factor_report
app.command(name="fin_factor_report")(fin_factor_report)
So the entry chain is:
rdagent
-> rdagent.app.cli:app
-> Typer 子命令 fin_factor_report
-> rdagent.app.qlib_rd_loop.factor_from_report.main()
The bottom of the module file likewise retains:
if __name__ == "__main__":
fire.Fire(main)
2. The Main Function¶
In rdagent/app/qlib_rd_loop/factor_from_report.py:
def main(report_folder=None, path=None, all_duration=None, checkout=True):
Main logic:
if path is None and report_folder is None:
model_loop = FactorReportLoop()
elif path is not None:
model_loop = FactorReportLoop.load(path, checkout=checkout)
else:
model_loop = FactorReportLoop(report_folder=report_folder)
asyncio.run(model_loop.run(all_duration=all_duration))
There are two key differences from fin_factor here:
- The entry parameters have no
step_n/loop_n loop_nis determined insideFactorReportLoop.__init__()by the number of reports
Therefore fin_factor_report's control style leans toward "batch processing reports", rather than the user manually specifying how many rounds to run.
3. FactorReportLoop Inherits from FactorRDLoop¶
The definition is:
class FactorReportLoop(FactorRDLoop, metaclass=LoopMeta):
This means:
- It reuses
fin_factor's coder / runner / summarizer - But overrides the proposal stage
- And also customizes the feedback logic
In other words, the latter half of fin_factor_report is still the standard factor R&D chain; the change mainly happens in the "task source" at the very front.
4. The Role of FACTOR_FROM_REPORT_PROP_SETTING¶
In rdagent/app/qlib_rd_loop/conf.py:
class FactorFromReportPropSetting(FactorBasePropSetting):
scen = "rdagent.scenarios.qlib.experiment.factor_from_report_experiment.QlibFactorFromReportScenario"
report_result_json_file_path = "git_ignore_folder/report_list.json"
max_factors_per_exp = 10000
report_limit = 10000
So on top of FactorBasePropSetting it only additionally changes a few things:
- Switching the scenario object to the report scenario
- Adding a default report list file
- Limiting how many factors can be extracted per experiment at most
- Limiting how many reports are processed at most
The rest:
- hypothesis2experiment
- coder
- runner
- summarizer
all carry over from the factor scenario.
5. What FactorReportLoop.__init__() Does¶
During initialization it first calls:
super().__init__(PROP_SETTING=FACTOR_FROM_REPORT_PROP_SETTING)
This step completes the standard factor scenario assembly:
- scenario
- coder
- runner
- summarizer
- trace
Then FactorReportLoop itself does the report list initialization:
if report_folder is None:
self.judge_pdf_data_items = json.load(open(report_result_json_file_path, "r"))
else:
self.judge_pdf_data_items = [i for i in Path(report_folder).rglob("*.pdf")]
self.loop_n = min(len(self.judge_pdf_data_items), report_limit)
self.shift_report = 0
You can understand this as:
judge_pdf_data_items: the queue of PDFs to be processedloop_n: the maximum number of reports to processshift_report: used to skip invalid reports
6. Core Difference: direct_exp_gen No Longer Freely Generates from the Trace¶
This is the most core difference of fin_factor_report.
The standard fin_factor's direct_exp_gen is:
trace -> hypothesis_gen -> hypothesis2experiment
Whereas FactorReportLoop.direct_exp_gen() is:
选中一份 PDF
-> 从 PDF 中抽因子
-> 从报告文本中生成 hypothesis
-> 组装 QlibFactorExperiment
The corresponding main line of code:
report_file_path = self.judge_pdf_data_items[self.loop_idx + self.shift_report]
exp = extract_hypothesis_and_exp_from_reports(str(report_file_path))
If exp is None:
- The report is considered to have no valid factors
shift_report += 1loop_n -= 1- Continue trying the next report
7. The Pipeline of extract_hypothesis_and_exp_from_reports()¶
This layer is the real entry point for report understanding.
The main logic is as follows:
exp = FactorExperimentLoaderFromPDFfiles().load(report_file_path)
if exp is None or exp.sub_tasks == []:
return None
pdf_screenshot = extract_first_page_screenshot_from_pdf(report_file_path)
docs_dict = load_and_process_pdfs_by_langchain(report_file_path)
factor_result = ...
report_content = "\n".join(docs_dict.values())
hypothesis = generate_hypothesis(factor_result, report_content)
exp.hypothesis = hypothesis
return exp
It can be broken into four steps.
7.1 Extracting the factor experiment from the PDF¶
FactorExperimentLoaderFromPDFfiles().load(report_file_path) is the heaviest step. Internally it will:
load_and_process_pdfs_by_langchain()read the PDF textclassify_report_from_dict()determine whether the report is a usable quantitative/factor reportextract_factors_from_report_dict()extract factor names, descriptions, formulas, and variables from the reportmerge_file_to_factor_dict_to_factor_dict()merge results from multiple reportscheck_factor_viability()filter out infeasible factorsFactorExperimentLoaderFromDict().load(filtered_factor_dict)assemble them into aQlibFactorExperiment
So this is no longer an ordinary "propose a hypothesis"; instead the report content is first parsed into structured factor tasks.
7.2 Extracting the first-page screenshot¶
pdf_screenshot = extract_first_page_screenshot_from_pdf(report_file_path)
This screenshot is written into the logs, making it easy to inspect later in the UI or trace.
7.3 Extracting the full text again¶
docs_dict = load_and_process_pdfs_by_langchain(report_file_path)
report_content = "\n".join(docs_dict.values())
This uses LangChain's PDF loader, merging the text into one complete string for hypothesis generation.
7.4 Generating the hypothesis based on "the extracted factor results + the full report text"¶
generate_hypothesis(factor_result, report_content) will call the LLM:
response = APIBackend().build_messages_and_create_chat_completion(...)
Then convert the returned JSON into a standard Hypothesis object.
So the hypothesis here is not proposed out of thin air, but is a high-level summary of "the set of factors mentioned in the report".
8. Post-Processing After direct_exp_gen Produces the Experiment¶
In FactorReportLoop.direct_exp_gen(), after obtaining exp, several more things are done:
8.1 Binding the baseline and historical successful experiments¶
exp.based_experiments = [QlibFactorExperiment(sub_tasks=[], hypothesis=exp.hypothesis)] + [
t[0] for t in self.trace.hist if t[1]
]
This means:
- The first item is an empty-task baseline experiment
- Followed by the experiments whose historical decision was true
8.2 Limiting the number of factors processed per report¶
exp.sub_workspace_list = exp.sub_workspace_list[:max_factors_per_exp]
exp.sub_tasks = exp.sub_tasks[:max_factors_per_exp]
This step prevents a single report from extracting too many factors.
9. The coding Stage Is the Same as fin_factor¶
FactorReportLoop.coding():
exp = self.coder.develop(prev_out["direct_exp_gen"])
Here self.coder is still QlibFactorCoSTEER.
So the coding stage has no essential difference from fin_factor; it is still:
- Handing each
FactorTaskto CoSTEER - Generating and iterating
factor.py - Actually executing the code
- Using an evaluator to judge whether the implementation is acceptable
10. The running Stage Is the Same as fin_factor¶
Since FactorReportLoop inherits FactorRDLoop and does not override running(), what runs is:
exp = self.runner.develop(prev_out["coding"])
Here the runner is still QlibFactorRunner.
It will:
- Re-run the successfully implemented factor workspaces
- Merge the new factors
- Deduplicate against the historical SOTA factors
- Write into
combined_factors_df.parquet - Call
QlibFBWorkspace.execute()to runqrun - Read
qlib_res.csvandret.pkl
So the latter half of fin_factor_report fully reuses the standard factor backtest chain.
11. The Logic of the feedback Stage¶
On successful execution:
feedback = self.summarizer.generate_feedback(prev_out["running"], self.trace)
self.trace.hist.append((prev_out["running"], feedback))
Here the summarizer is still QlibFactorExperiment2Feedback.
On failure, it constructs a:
HypothesisFeedback(decision=False, ...)
12. A Source Code Caveat¶
FactorReportLoop.direct_exp_gen() returns the exp object itself, not the standard RDLoop style:
{"propose": hypo, "exp_gen": exp}
coding() has already been written for this new return value:
self.coder.develop(prev_out["direct_exp_gen"])
But the exception branch of feedback() still retains:
prev_out["direct_exp_gen"]["exp_gen"]
This is inconsistent with the current return structure of direct_exp_gen(). In other words, the success path is self-consistent, but the exception path carries a structural inconsistency risk at the source code level.
This issue does not affect understanding of the main flow, but it is worth noting when reading the source code.
13. Session and Resumption¶
fin_factor_report likewise inherits LoopBase's session mechanism; every time a step completes, a snapshot is generated at:
<trace_path>/__session__/<loop_id>/<step_id>_<step_name>
Resuming execution uses:
FactorReportLoop.load(path, checkout=checkout)
14. The Complete Call Chain in One Diagram¶
rdagent fin_factor_report --report-folder=<pdf_dir>
-> rdagent/app/cli.py
-> rdagent/app/qlib_rd_loop/factor_from_report.py: main()
-> FactorReportLoop(FACTOR_FROM_REPORT_PROP_SETTING)
-> LoopBase.run()
-> direct_exp_gen
-> 选一份 PDF
-> FactorExperimentLoaderFromPDFfiles.load()
-> 分类报告、抽取因子、过滤不可实现因子
-> load_and_process_pdfs_by_langchain()
-> generate_hypothesis()
-> 得到 QlibFactorExperiment
-> coding
-> QlibFactorCoSTEER
-> 生成并迭代 factor.py
-> running
-> QlibFactorRunner
-> 合并因子并执行 Qlib 回测
-> feedback
-> QlibFactorExperiment2Feedback
-> 写回 Trace
-> 下一份报告
15. Conclusion¶
The essence of rdagent fin_factor_report can be summarized as:
CLI 入口
-> 批量读取 PDF 报告
-> 从报告中抽取结构化因子任务
-> 基于报告内容生成 hypothesis
-> 复用标准 fin_factor 的 coding / running / feedback 链
-> 逐份报告完成因子实现与回测
So it is not an independent workflow, but a combined command of "report parsing up front + standard factor R&D afterward".