# wq-alpha-research turns WorldQuant BRAIN failures into a SKILL.md file

> An agent skill for WorldQuant BRAIN alpha research: a local snapshot of 4,367 USA TOP3000 delay=1 fields, a group_rank plus ts_rank baseline, IS failure diagnostics, and a script that writes lessons back into the playbook.

**QuantML-Research/wq-alpha-research** — A self-evolving WorldQuant BRAIN alpha research skill.

- Repository: https://github.com/QuantML-Research/wq-alpha-research
- Stars: 403 · Forks: 119
- Language: Python
- License: not declared
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/quantml-research-wq-alpha-research

## The loop is the claimed bottleneck, not the number of expressions

The project's argument is that writing more alpha expressions is not what limits a WorldQuant BRAIN researcher. Five named frictions are, and every feature here maps back to one of them: finding usable fields fast enough, avoiding repeated low-Sharpe templates, controlling turnover before submission, checking SELF_CORRELATION against the alphas already marked ACTIVE, and keeping the lessons from a failed simulation instead of rediscovering them later.

The stated core idea is that alpha research should not stay as scattered one-off prompts. Every BRAIN interaction is meant to end up as a reusable rule, which is the same argument as the loop framing seen from the other side: the output of one run has to change the next one.

That framing is why the repository is small. The top level holds a .gitignore, README.md, SKILL.md, a pic directory, references and scripts. There is no research engine to install and no model to download. The playbook itself lives in SKILL.md, and you are told to read that file first because it carries the actual instructions and the trigger conditions.

The scope is narrow in a second way. The playbook is built around USA TOP3000 with delay=1, and the field snapshot matches that region and delay exactly. Nothing in the tree offers a second region, a second delay setting, or a switch that points the scripts at a different universe. A researcher working any other configuration inherits the operator patterns and none of the field context.

## group_rank with ts_rank on SUBINDUSTRY is the shipped baseline

One mining rule carries more weight than the rest. Fundamental fields are named as the strongest starting point, and the default construction is `group_rank` plus `ts_rank` with `SUBINDUSTRY` neutralization. That is a template you can copy before you know anything about the field, which is the point: the first attempt does not depend on the agent guessing well.

Two of the shipped rules are variations on that baseline rather than separate strategies. Analyst expectation fields earn their place but need more turnover control, handled with modest decay plus industry or subindustry neutralization. Pure technical signals fail more often unless decay is high or they are mixed with the slower fundamental ones. Windows, weights and neutralization are listed as levers, and the position taken on them is blunt: changing those rarely produces a genuinely low-correlation alpha on its own. Lower correlation usually needs a different data source or different economic logic.

That last claim sets the ceiling on what the skill can do for you. Retuning an expression is a local move inside one data family. The correlation number only moves when the inputs change, and the playbook has no mechanism for adding an input family beyond the snapshot in references.

Decay is the one control that shows up in three separate rules: modest decay for analyst expectation fields, high decay for a pure technical signal, and decay again as the first lever against a Fitness failure. Signal mixing is the second. If you remember one knob from this playbook, that is the pair.

## A Fitness failure is often a turnover problem under a different label

The diagnostics are the part with the most specific claim in them, and the claim is that Fitness failures are frequently turnover problems in disguise. Decay and signal mixing are named as the first two levers to check. The same list covers low Sharpe, high Turnover, concentrated weights and sub-universe failures, which is the set of IS checks a candidate has to clear before submission.

This is the advice most worth having and the hardest to check from outside the project, because no measurements are published. The stated goal is not a fixed Sharpe or a submission pass rate. The value is claimed in process terms instead: fewer invalid-field attempts, less repeated correlation failure, better default templates, and a growing record of what worked.

So read the diagnostics as a decision tree to work through in order rather than as a prediction about your next run. Nothing in the tree says when to stop, and no worked example in the tree pairs a failed simulation with the edit that fixed it. You still have to know what a good result looks like before the tree can tell you whether you reached it.

Three of the five named diagnoses describe how a signal behaves rather than how strong it is, which fits the turnover argument: high Turnover and concentrated weights are behavioural complaints, and a sub-universe failure is a scope complaint.

## Self-correlation is measured on daily PnL changes, not the PnL curve

The rule on self-correlation is the most mechanical in the set: measure it on daily PnL changes, not on cumulative PnL curves. Two alphas whose equity lines look unrelated can move together day to day, and a correlation computed the wrong way will pass a check it should fail.

Measuring it is the job of `scripts/evolve_skill.py`, described as the feedback engine behind the project. After simulations, submissions or status checks it can pull your alpha list, compare the new or changed alphas against the local snapshot, compute daily-return correlations against the alphas currently marked ACTIVE, and emit a Markdown lesson snippet.

That is the one place where the repository automates a judgement instead of writing it down as prose for an agent to apply. Everything else in the skill is a rule an agent reads. This one reads your account and writes back to disk, which is why the credential handling matters more here than in a documentation-only project.

Pulling all ACTIVE alphas before comparing is what gives the number its meaning. An alpha measured against a stale set clears a check it should fail.

## evolve_skill.py writes lessons back into SKILL.md, and only on request

Two commands cover the feedback loop, and the gap between them is the gap between a preview and an edit:

```bash
python scripts/evolve_skill.py
```

```bash
python scripts/evolve_skill.py --apply
```

Without a flag the script shows what it would change. With `--apply` it writes to the local `SKILL.md` and to `alpha_db.json`. The order is fixed: preview, read the output yourself, apply only for local or private updates.

Two file names carry the weight. `SKILL.md` is the playbook an agent reads at the start of every run, so a lesson written into it changes later behaviour instead of sitting in a log. `alpha_db.json` is the memory file, and it and `batch_submit_results.json` are both deliberately ignored by git.

The loop the project recommends puts the evolve call in the middle. Generate or modify candidates from `SKILL.md`, simulate and inspect IS checks on BRAIN, pull all ACTIVE alphas and compare daily-return correlation, then preview, review, apply locally, and publish only sanitized general rules.

## 4,367 fields ship as one CSV and two JSON files

Field lookup is the part you can use without a BRAIN account. `references/` holds three files describing the same snapshot of 4,367 USA TOP3000 delay=1 data fields: a CSV, a JSON array and a JSON summary. Searching them is a few lines of Python rather than a shipped search tool.

```python
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])
```

The snippet matches on the field id and on the description, guards a missing description with a default of `""`, and prints only the first five hits. Copy it as written and it tells you whether the snapshot contains the field you had in mind before you spend a simulation on it.

Note what this is not. The snapshot is pinned to one region and one delay, and no script in the tree refreshes it from BRAIN. A field that exists in your account but not in this file reads as absent here, which is the failure mode that costs you the most.

No schema is given for any of the three files. The summary file is named rather than explained, so the region and delay live in the filename and nowhere else you can check from here.

## Credentials come from two places, and both are gitignored

The repository states that it is a reusable skill and not a credential bundle, which shapes how it handles secrets. Two mechanisms are documented. Environment variables:

```bash
export WQ_BRAIN_USERNAME="your_username"
export WQ_BRAIN_PASSWORD="your_password"
```

Or a local `credential.txt` holding a JSON array:

```json
["your_username", "your_password"]
```

Six paths are named as intentionally ignored: `credential.txt`, `alpha_db.json`, `batch_submit_results.json`, `.env`, Python caches and virtual environments. The scripts need `requests` and `numpy`, and nothing else is named as a requirement.

The choice between the two mechanisms is not explained. Which one the evolve script reads first, whether `credential.txt` is optional when the variables are exported, and what happens when neither is present are all left unstated. If your environment already exports those variables, that is the path with the most explicit coverage.

The same restraint applies to research output. Before publishing lessons from local runs, the project asks for them to be summarised into general rules. Raw alpha IDs, PnL series, account-linked submission statuses and private candidate expressions stay out of anything you share.

## submit_batch.py runs as a bare example with no documented flags

The second script gets one line: "Run the batch submission example".

```bash
python scripts/submit_batch.py
```

No arguments, no environment variables and no output format are given for it. The wider promise it serves is automating simulation and submission workflows with explicit post-submit status checks, which points at real work inside the file rather than at an interface you drive from outside. Anyone planning to script their own submissions should open the file before assuming it can be parameterised.

Licensing is equally low-key. The work is offered under the Creative Commons Attribution-NonCommercial 4.0 International License, so reuse, modification and sharing are allowed for non-commercial purposes with clear citation and a link back to the repository. The non-commercial clause is a real constraint for anyone planning to build a service on top of the field snapshot or the playbook.

There are no GitHub releases, so there is no version history beyond the commit log. The last recorded push to the main branch is dated 2026-06-29.

Contact runs through a WeChat group called QuantML Factor Research, or a personal QR code to add the author as a friend. That is the only contact route offered, which matters if you hit a credential or correlation problem and expected an issue tracker instead.

## Conclusion

Adopt it if you already hold BRAIN credentials and work on USA TOP3000 delay=1, because the field snapshot and the group_rank plus ts_rank baseline are only useful inside that universe. Skip it if you need a research engine, a second region, or anything you can parameterise from outside the two scripts, since none of that is in the tree. Before trusting the diagnostics, check that the daily-return correlation your account reports for a candidate matches what you get from the method the project names, since every low-correlation conclusion in the playbook rests on that one definition.

## FAQ

### Is WorldQuant BRAIN a legitimate platform?

This repository treats WorldQuant BRAIN as the platform where alpha expressions are simulated and IS metrics are checked, and it says nothing about how the platform is operated or verified. The only account details it documents are the two credentials its scripts read, WQ_BRAIN_USERNAME and WQ_BRAIN_PASSWORD.

### What is alpha in quant?

Here an alpha is a WorldQuant BRAIN Alpha expression that the skill helps an agent design, simulate and diagnose. The metrics named for judging one are Sharpe, Fitness, Turnover, concentration of weights and SELF_CORRELATION against existing ACTIVE alphas.

### How does WorldQuant brain work?

Inside this project, BRAIN is reached through two Python scripts that need requests and numpy. evolve_skill.py fetches your alpha list after simulations, submissions or status checks, compares new and changed alphas with the local snapshot, and computes daily-return correlations against ACTIVE alphas.

### How does WorldQuant make money?

No payout, fee or payment mechanism is described anywhere in this repository, so the question has no answer here. What the project does describe is a research loop on your own account: build expressions, run IS checks on BRAIN, and turn the results into rules in SKILL.md.

## Sources

- [Issues](https://github.com/QuantML-Research/wq-alpha-research/issues)
- [QuantML-Research/wq-alpha-research on GitHub](https://github.com/QuantML-Research/wq-alpha-research)
- [README](https://github.com/QuantML-Research/wq-alpha-research/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/quantml-research-wq-alpha-research