quantlab-factor-agent

English | 简体中文

quantlab-factor-agent mines daily stock factors with language models, mechanism first. A model states an economic mechanism and writes the factor it implies as KunQuant code. Fixed checks and statistics from quantlab then decide whether the factor is new and adds to the factors you already have. The model only proposes and reviews, and it sees nothing but the training segment.

Documentation · Example configs · Changelog

Status: alpha (0.x). The API, the config format and the run directory's layout may change between minor versions.

How it works

A campaign runs in rounds. The planner picks one research direction per slot, and the proposer writes a hypothesis, a description and KunQuant code for each. The Gate builds the code in a sandbox and refuses rewrites of existing factors; the reviewer checks that hypothesis and code describe the same factor. The Evaluator then scores what is left on the training segment, and admission accepts or rejects it. After the campaign, Acceptance trains a quantlab return model with and without the accepted factors, opens the hold-out once and exports the chosen factors.

• Mechanism first. The Gate compares KunQuant graphs and refuses rewrites, parameter-only variants and large shared subtrees of every reference, known and accepted factor.
• No look-ahead. Prompts carry training-segment statistics only: no return, no date, no validation or hold-out metric. The hold-out opens once, behind a lock.
• Only code accepts. The Evaluator scores candidates on quantlab's whole-market panels, masked to each day's members, and the partial-IC t threshold tightens with every evaluated trial.
• Nothing hard-coded about the market. Fields, operators, prompts, mechanism types and scoring come from the config's files, so a new input family is a new field file.
• Any provider, replayable. Each role picks its backend: OpenAI-compatible endpoints (DeepSeek, OpenAI, vLLM, ...), Anthropic or Claude Code. Every call is logged, and the replay backend reproduces a run byte for byte without a provider.
• Resumable. run() picks up from the run directory after a crash or an exhausted balance.

The diagram below shows how the parts fit together: what the models search, what each judge refuses, how every trial feeds the next round, and where the data the models see ends. How the agent mines factors explains it in full.

With themes turned on, the planner also reads a map of the directions tried so far; see the direction map.

Install

You need Python 3.13+ and a C++ compiler on the PATH (KunQuant compiles factor graphs to native code):

pip install "quantlab-factor-agent[web]"   # [web] adds the factor-agent-web frontend

To work on the code, or to run the example configs and the offline test suite, install from a checkout with uv, with quantlab's checkout beside it:

git clone https://github.com/ZhaorongDai/quantlab.git
git clone https://github.com/ZhaorongDai/quantlab-factor-agent.git
cd quantlab-factor-agent
uv sync --extra web
uv run pytest -n auto    # offline: no LLM call, a synthetic market

On macOS, xgboost also needs brew install libomp. Keys come from environment variables only (ANTHROPIC_API_KEY, or the variable a role's api_key_env names), and a config that holds a key is refused. See installation.

Run a campaign

from factor_agent.acceptance import Acceptance
from factor_agent.campaign import Campaign
from factor_agent.config import CampaignConfig

config = CampaignConfig.from_file("configs/us3000_ret5.yaml")
result = Campaign(config).run()          # resumes when run_dir already holds a state
print(result.stop, len(result.accepted), "accepted of", len(result.records))

report = Acceptance(config).validate()   # baseline vs baseline + accepted, on validation
print(report.markdown())

Point the config's data paths at your own quantlab stores first. A campaign runs for hours, mostly waiting on the model, and needs no GPU; Acceptance uses CUDA when it is available. Before a long run, factor-agent check <config> reports everything run() would refuse (a store that does not exist, an unset API key variable, a resume that changed the config) in seconds, without writing anything; --ping also sends each backend one short request.

Watch a run in the browser

factor-agent-web runs/    # then open http://127.0.0.1:8000

The web panel lists your runs and opens each one: whether its accepted factors improve your model, a card per factor, every trial on a Lineage graph and the admission map, the LLM calls of the round in progress, the memory and the config. It only reads the run directory, listens on localhost only, and on a server you reach it through an SSH tunnel. See the web frontend.

Building on earlier trials

Every trial after the first round either starts a new direction or builds on an earlier one, its parent, as a refinement or a mutation. A trial's Lineage sums up the trials built on it: how many, how many stopped early, which were accepted and how far the best got. With context.lineage the planner and the proposer read it. With round.picked_parents: k the code, not the planner, chooses the parents of k slots each round, the Picked parents: it ranks the evaluated trials by quality, fertility and novelty, each shared over the Trial graph of trials related by generation, code structure and correlation, so a trial whose relatives did well rises with them. The trial_graph section sets how much is shared and how the graph is built. Both are off by default. The web panel's "why these parents" shows, for each round, how propagation moved each trial's utilities and rank:

See building on earlier trials and the campaign config.

Documentation

• How the agent mines factors: the search, the judges, the learning loop and what the models may see, in one diagram
• First campaign: run one and read its outcome
• Concepts: roles, factor sets, segments, what "accepted" means
• The campaign config: every section, checking a config, stopping and resuming
• The web frontend: every page of the panel, and how to reach it on a server
• The vocabulary and prompts: what candidates may read and write, and what the models are told
• LLM backends: providers, the LLM log, replay, cost
• Gate, review and evaluation and acceptance: how a factor is judged

Contributing

Bug reports, questions and pull requests are welcome; see CONTRIBUTING.md. Report security problems privately, as SECURITY.md describes.

License

MIT. factor_agent/_max_drawdown.py adapts code from KunQuant under the Apache License 2.0.