Skip to content

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:

  1. How the CLI entry point leads into fin_factor_report
  2. What it shares with fin_factor and where it differs
  3. 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:

  1. The entry parameters have no step_n / loop_n
  2. loop_n is determined inside FactorReportLoop.__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 processed
  • loop_n: the maximum number of reports to process
  • shift_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 += 1
  • loop_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:

  1. load_and_process_pdfs_by_langchain() read the PDF text
  2. classify_report_from_dict() determine whether the report is a usable quantitative/factor report
  3. extract_factors_from_report_dict() extract factor names, descriptions, formulas, and variables from the report
  4. merge_file_to_factor_dict_to_factor_dict() merge results from multiple reports
  5. check_factor_viability() filter out infeasible factors
  6. FactorExperimentLoaderFromDict().load(filtered_factor_dict) assemble them into a QlibFactorExperiment

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:

  1. Handing each FactorTask to CoSTEER
  2. Generating and iterating factor.py
  3. Actually executing the code
  4. 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:

  1. Re-run the successfully implemented factor workspaces
  2. Merge the new factors
  3. Deduplicate against the historical SOTA factors
  4. Write into combined_factors_df.parquet
  5. Call QlibFBWorkspace.execute() to run qrun
  6. Read qlib_res.csv and ret.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".