wq-alpha-research: an agent skill for the WorldQuant BRAIN alpha loop

The research loop, not the expression, is the bottleneck

Most alpha mining tooling assumes the hard part is writing expressions. This project takes the opposite position. The README lists the actual friction points: finding usable fields quickly, avoiding repeated low-Sharpe templates, controlling turnover before submission, checking SELF_CORRELATION against existing ACTIVE alphas, and preserving lessons from failed simulations instead of rediscovering them. Each of those is a step in a loop, and the repository is organized around that loop rather than around expression generation. The intended user is someone who already runs simulations on WorldQuant BRAIN and has felt the loop slow down: a consultant, a researcher, or an agent-driven workflow where context is lost between sessions. It is not aimed at someone who wants a finished alpha handed over. The README is unusually direct on this point, stating that the goal is not to promise a fixed Sharpe or submission pass rate, and that the value is a faster, cleaner mining loop with fewer invalid-field attempts and better default templates.

What actually ships in the repository

The layout is small and readable. SKILL.md holds the playbook and the trigger instructions, and the README says to read it first. Two scripts sit under scripts/: evolve_skill.py, described as the feedback engine, and submit_batch.py, the batch submission example. Three reference files hold a local snapshot of BRAIN data fields for USA TOP3000 delay=1, in CSV, JSON and a summary JSON. That snapshot contains 4,367 fields according to the README. The playbook itself is built around USA TOP3000 delay=1 and has distilled several mining rules into prose: fundamental fields are usually the strongest starting point, with group_rank plus ts_rank and SUBINDUSTRY neutralization as the default baseline; analyst expectation fields need more turnover control, typically through modest decay and industry or subindustry neutralization; pure technical signals fail more often unless decay is high or they are mixed with slower fundamental signals. Two of the stated rules are worth flagging because they correct common mistakes. Fitness failures, the README says, are often turnover problems in disguise, so decay and signal mixing are the first levers to check. And self-correlation must be measured on daily PnL changes, not cumulative PnL curves.

evolve_skill.py and the daily-return correlation check

The self-evolution mechanism is the part that distinguishes this from a static prompt library. Per the README, evolve_skill.py can fetch the user's alpha list, compare new or changed alphas against the local snapshot, compute daily-return correlations against ACTIVE alphas, and generate a Markdown lesson snippet. The recommended loop is seven steps: generate or modify candidate expressions from SKILL.md, simulate and inspect IS checks on BRAIN, pull all ACTIVE alphas and compare daily-return correlation, run the script to preview new lessons, review the output manually, run it with --apply only for local or private updates, and publish only sanitized general rules. The manual review step is deliberate, and the README repeats the boundary: never publish raw alpha IDs, PnL series, account-linked submission statuses, or private candidate expressions. One claim in the mining rules is a genuine constraint rather than a tip. Changing windows, weights, or neutralization rarely creates truly low-correlation alphas by itself, the README states; low correlation usually needs a different data source or economic logic. That rules out a whole class of parameter-tuning busywork, and it is the kind of statement a tool vendor usually avoids making.

Installing it and running a first field lookup

There is no package to install, no pip name and no release artifact. The README's Quick Start is a single instruction: read SKILL.md first, because it contains the actual playbook and trigger instructions. To get the files, clone the repository, since the README gives no other distribution channel. The scripts require requests and numpy, and the README names those two dependencies without pinning versions. The first real use is local field lookup against the shipped snapshot. This snippet is the README's own example and loads the JSON field file, then filters by a keyword against the field id and its description. Replace the keyword with a term from your own research idea. The README prints the first five matches, so a working run shows a short list of field dictionaries rather than a traceback. If the list is empty, the keyword does not appear in either the id or the description of any of the 4,367 fields, and the next move is a broader term.

import json
from pathlib import Path

fields = json.loads(
    Path("references/wq_usa_top3000_delay1_data_fields.json").read_text(encoding="utf-8")
)

keyword = "operating_income"
matches = [
    f for f in fields
    if keyword in f["id"].lower()
    or keyword in (f.get("description") or "").lower()
]
print(matches[:5])

Credentials, if you go on to run the scripts, come from environment variables or a local credential.txt file holding a two-element JSON array of username and password.

export WQ_BRAIN_USERNAME="your_username"
export WQ_BRAIN_PASSWORD="your_password"

The README also gives the file form, which is ignored by git.

["your_username", "your_password"]

Once credentials are in place, the evolution script previews lessons without touching your files, and the batch example runs as-is.

python scripts/evolve_skill.py

python scripts/evolve_skill.py --apply

python scripts/submit_batch.py

Where the skill stops being the right tool

Three limits are visible from the README alone. First, the playbook is scoped to USA TOP3000 delay=1. The field snapshot, the neutralization defaults and the mining rules all carry that scope, so a researcher working another region or delay is reading guidance written for a different setting. Second, the self-evolution loop depends on credentials and on live BRAIN calls. The scripts fetch the user's alpha list and pull ACTIVE alphas; without working credentials, evolve_skill.py has nothing to compare against, and the local snapshot is just a static file. Third, the repository is not a credential bundle, and the README says so in the opening section. Anyone looking for a managed service, a shared alpha database, or a hosted dashboard will not find one here. There is also a governance limit worth naming: because the useful output is distilled from your own runs, the quality of the lessons depends on how carefully the preview step is reviewed before --apply writes to SKILL.md and alpha_db.json. The README puts that review in the loop on purpose, and skipping it turns the feedback engine into an unreviewed edit to your own playbook.

How this differs from a generic coding agent setup

The obvious alternative is a general-purpose coding or research agent with no domain skill attached: you paste BRAIN field names and operator patterns into the prompt each session and rely on the model's memory of the last conversation. The difference is not model quality, it is where the domain knowledge lives. Here the field snapshot is a file on disk, the mining rules are written into SKILL.md, and the correlation check is a script with a defined input and output. A generic setup has none of that persistence, which is exactly the failure mode the README describes as scattered one-off prompts. The trade-off runs the other way too. A generic agent adapts to a new region or a new data category immediately, while this skill's rules were distilled for one universe and one delay, and its field snapshot is a point-in-time copy. If your research is exploratory across many datasets, the packaged playbook may constrain you more than it helps.

Maintenance, licence and what to verify

The repository is not archived, and the last push was on 2026-06-29. That is roughly two and a half months before the date of writing, so the code has not been sitting untouched for a long stretch, but there are no retrieved releases, which means upgrades arrive as commits to the main branch rather than as tagged versions. Practically, that makes the field snapshot and SKILL.md the two files to diff when you pull, since both change as the author distills new rules. The licence is Creative Commons Attribution-NonCommercial 4.0 International, stated in the README's License and Attribution section. That permits use, modification and sharing for non-commercial purposes with clear attribution and a link back to the repository. The non-commercial clause is the part to read closely if you are a consultant billing for alpha research, because the licence text draws a line this article cannot draw for you. There is no separate LICENSE file listed among the top-level entries, so the README section is the statement of record. The repository also ignores credential.txt, alpha_db.json, batch_submit_results.json and .env, which is a safety default, not a guarantee: confirm your own git status before the first commit.

Editorial conclusion

Adopt wq-alpha-research if you already simulate on WorldQuant BRAIN and want the research loop written down as templates, IS diagnostics and a local field snapshot instead of scattered prompts. Do not adopt it if you expect a ready-made alpha, a hosted service, or a fixed Sharpe promise; the README states outright that it does not promise a submission pass rate. Before anything else, read SKILL.md, confirm the playbook targets USA TOP3000 delay=1, and check that CC BY-NC 4.0 fits how you intend to use the output.

Frequently asked questions

Official sources

1. Issues
2. QuantML-Research/wq-alpha-research on GitHub
3. README