QuantaAlpha: LLM-Driven Factor Mining With Trajectory Evolution

The Problem QuantaAlpha Targets: Factor Discovery as a Search Loop

Quantitative factor research has a throughput problem. A researcher writes a hypothesis about price and volume behaviour, translates it into code, backtests it, looks at the result, and writes the next hypothesis. The bottleneck is not the backtest, which is cheap, but the hypothesis generation and the code translation around it. QuantaAlpha's stated goal is to automate that loop. The README describes the input as a research direction and the output as validated alpha factors, with the intermediate steps labelled as diversified planning, trajectory evolution, and validation. The intended user is a quant researcher or small team that already has a Qlib data setup and wants to expand the candidate factor pool faster than manual iteration allows. It is not a trading system, not a portfolio constructor, and not a replacement for a research process. The README's own pipeline diagram shows the scope: research direction in, verified factors out. Everything downstream of factor generation, including position sizing and execution, sits outside the project.

Trajectory Evolution and the Hypothesis-Code Constraint

The mechanism the README names is trajectory-based self-evolution, supported by three components: diversified planning initialization, trajectory-level evolution, and structured hypothesis-code constraints. The last of these is the most concrete. A structured constraint between hypothesis and code means the generated factor expression is tied to a written rationale, so the evolutionary step mutates something that has a stated meaning rather than an arbitrary string. That matters because unconstrained code generation produces factors that fit noise and cannot be explained. The README also reports an IC trajectory across the first five mining iterations, with QuantaAlpha holding the highest IC throughout. That figure is a claim from the project's own evaluation, not an independent measurement, and the README does not describe the mutation operators, the selection pressure, or how many candidate trajectories are kept per generation. Those are the details that determine whether the evolution is doing real work or just re-sampling the language model. The planning initialization step is likewise named but not specified. Treat the architecture as documented at the level of components, not at the level of algorithms.

What the Setup Actually Requires

Installation follows a standard Python path. The README gives: git clone the repository, create a conda environment with python=3.10, install the package in development mode with SETUPTOOLS_SCM_PRETEND_VERSION=0.1.0 pip install -e ., then pip install -r requirements.txt. The version pin is worth noting. It exists because setuptools_scm derives the version from git tags, and the repository has no releases, so the version cannot be inferred and must be supplied manually. Configuration is a .env file copied from configs/.env.example. Four keys are marked required: QLIB_DATA_DIR, DATA_RESULTS_DIR, OPENAI_API_KEY, and OPENAI_BASE_URL. Two more select the models: CHAT_MODEL and REASONING_MODEL, with deepseek-v3 given as the example value and gpt-4 and qwen-max named as alternatives. The OPENAI_BASE_URL example points at DashScope, which confirms the client is OpenAI-compatible rather than OpenAI-only. Data is the real dependency. QuantaAlpha needs Qlib market data for backtesting and precomputed price-volume HDF5 files for mining, both hosted at huggingface.co/datasets/QuantaAlpha/qlib_csi300. The README is explicit about why the HDF5 files are shipped: the system can generate daily_pv.h5 from Qlib data on first run, but that process is described as very time consuming. The files must land in specific paths: git_ignore_folder/factor_implementation_source_data/daily_pv.h5 and git_ignore_folder/factor_implementation_source_data_debug/daily_pv.h5. Note that the debug directory expects a file named daily_pv.h5, not daily_pv_debug.h5, which is a copy step that is easy to get wrong.

The Data Dependency Is the Adoption Cost

The HuggingFace dataset is not optional convenience. Without daily_pv.h5 the mining stage has no input, and without cn_data.zip the backtest stage has no market data. The README states the dataset covers A-share data from 2016 to 2025. That has two consequences. First, the framework as shipped is oriented toward the Chinese A-share market, and the reported experiments are on CSI 300 with cross-market transfer to CSI 500 and S&P 500. Second, the precomputed HDF5 files are tied to that data window. If your universe or date range differs, you are in the position of regenerating daily_pv.h5 yourself, which the README describes as slow without quantifying how slow. The README does not document the schema of the HDF5 files, so a user bringing their own data has to reverse-engineer the expected column layout from the source. That is the sharpest practical limitation in the material: the project is easy to run on the supplied dataset and underspecified for any other dataset.

Reported Results and What They Do Not Cover

The README reports a best configuration of QuantaAlpha with GPT-5.2 on CSI 300 over a 2022-2025 test period: IC 0.0472, Rank IC 0.0459, annualized return 4.68%, information ratio 0.6453, and maximum drawdown 11.80%. It also reports cumulative excess return of roughly 40.3% on CSI 500 and 19.1% on S&P 500 when factors mined on CSI 300 are transferred zero-shot. Those are the project's own numbers, and the README states they come with comparisons against traditional machine learning, deep learning, factor library, and LLM agent baselines. I have not reproduced them. Two things are worth flagging for anyone reading the table. The annualized return of 4.68% is modest in absolute terms, and the headline strength is the information ratio and the drawdown, not the return. And the test window ends in 2025, which is recent enough that the result has not been through a full market cycle. The README also claims QuantaAlpha held up in 2023 when baselines failed during a style shift. That is a single episode, and a single episode is not evidence of regime robustness.

Where QuantaAlpha Is the Wrong Choice

Three cases stand out. If your workflow is not built on Qlib, the backtest half of the pipeline does not apply to you, and you would be using QuantaAlpha only as a factor expression generator, which discards the validation claim that justifies the framework. If you need reproducible runs, the LLM dependency is a problem: the same research direction passed to a hosted model can produce different factor candidates across calls, and the README documents no seed control, caching layer, or snapshot mechanism for model outputs. If you work with non-A-share data at a different frequency, the precomputed HDF5 files do not transfer and the README does not explain how to build your own. The project also has no releases and no retrieved release notes, so there is no versioned artifact to pin against. You are tracking the main branch, and the SETUPTOOLS_SCM_PRETEND_VERSION workaround is a symptom of that, not a fix.

Alternatives and the Difference in Approach

The README positions QuantaAlpha against factor libraries and against other LLM agent baselines, though it does not name them. The meaningful comparison is with AlphaGen-style reinforcement learning approaches to formulaic alpha generation, which search a symbolic expression space with a learned policy and reward signal from IC or ICIR. The difference is in where the search intelligence sits. An RL approach optimizes a policy over expression trees using backtest reward as the training signal, which makes the objective explicit and the search reproducible given a fixed seed. QuantaAlpha instead uses a language model to propose and mutate factors guided by a written hypothesis, with the README's structured hypothesis-code constraint keeping the expression tied to its rationale. The trade-off is legibility against reproducibility. The LLM route can incorporate domain text and produce factors a human can read and argue about; the RL route gives you a deterministic search you can rerun. QuantaAlpha's own README does not claim to beat RL methods directly, only to beat the baselines it lists. If your priority is a search you can audit and rerun exactly, the RL formulation is the better fit, and QuantaAlpha's contribution is the hypothesis-code link rather than the search itself.

Licence, Maintenance, and What to Check Before Committing

The README displays an MIT badge, but the repository metadata supplied here lists the licence as unknown, and no LICENSE file is confirmed to exist. An MIT badge in a README is not a licence grant. Before you build anything on QuantaAlpha, confirm there is an actual LICENSE file at the repository root and read it, because the terms that apply to your use are the ones in that file, not the badge image. On maintenance: the last push is dated 2026-06-29, the repository is not archived, and there are no releases. The README also announces QuantaAlpha-claw as the next-generation harness, describing multi-role parallel exploration with Lead, Reviewer, and Miner roles, session memory, skill-based operators with lineage tracking, and stricter walk-forward validation. That announcement is a signal about where effort is going. If claw is the successor, the current repository may see less development, and the README does not state a compatibility or migration path between the two. The practical check before adopting is narrow: clone the repository, confirm the LICENSE file, run the install with the version pin, point QLIB_DATA_DIR at your Qlib data, and run the debug path with daily_pv_debug.h5 before committing to the full dataset download. If the debug run produces factors you can inspect, the pipeline works and the question becomes whether the factors survive your own validation. If it does not, you have spent one conda environment and no data transfer.

Editorial conclusion

QuantaAlpha is worth a trial if you already run Qlib, have an OpenAI-compatible LLM endpoint, and want to generate candidate factors from a written research direction rather than hand-code them. It is the wrong tool if you need a stable API, a published licence file, or a system that runs without downloading precomputed HDF5 data from HuggingFace. Before adopting, verify three things: that the repository actually contains a LICENSE file matching the MIT badge, that your LLM provider supports the model names you put in CHAT_MODEL and REASONING_MODEL, and that the factor library it produces survives your own out-of-sample split rather than the 2022-2025 test window reported in the README.

Official sources

1. Issues
2. QuantaAlpha/QuantaAlpha on GitHub
3. README