brain-login-and-sim 0.1.1

WorldQuant BRAIN client — login (biometric Scan + auto re-login), simulation, batch run, and auto-keeping promising alphas

brain-login-and-sim

A Python client for WorldQuant BRAIN — handles login (including the biometric "Scan" step and automatic re-login), runs simulations, runs them in batches (up to 3 concurrently, matching the platform limit), and automatically keeps the alphas that pass your criteria.

Install

pip install brain-login-and-sim

Configure credentials

Create a .env file (see .env.example):

WQ_EMAIL=[e-mail]
WQ_PASSWORD=your-password
# Send the Scan link to Telegram (optional, but recommended)
TELEGRAM_BOT_TOKEN=123456789:AAH...
TELEGRAM_CHAT_ID=123456789

Usage

from brain_login_and_sim import BrainClient, Simulator

# Log in — if a biometric Scan is required, the link is sent to Telegram
# and the client polls until you finish scanning on your phone.
client = BrainClient(notify_telegram=True).authenticate()
print(client.whoami()["id"])

sim = Simulator(client)

# Run a single simulation
r = sim.simulate("ts_rank(close, 5)")
print(r["simulation"]["status"], r["alpha"]["is"]["sharpe"])

# Run many alphas from a JSONL file and auto-keep the promising ones
sim.simulate_batch("alphas.jsonl", save_promising=True)

Features

• Login + biometric Scan — sends the scan link to Telegram/email and polls until it's done, so you don't have to watch the terminal.
• Auto re-login — when the session expires (WorldQuant allows ~4 hours), a 401 triggers an automatic re-login and the request is retried once.
• Promising-alpha filter — keeps alphas with |Sharpe| >= 1 and |Fitness| >= 0.9 (absolute value, so it also catches "flip candidates" that become good when the expression is negated).
• Batch — runs up to 3 simulations concurrently (the WorldQuant limit); a failure on one alpha does not abort the whole batch.
• Resume — checkpoints by hash; re-running the same file skips already-processed alphas and continues where it left off (survives interruptions).
• Flexible input — a list of expressions, a .txt file (one expression per line), or a .jsonl file with an expression field (and optional hash).

JSONL input format

{"hash": "f7b3...", "expression": "rank(reverse(ts_delta(anl4_cfo_median, 10)))", "status": "generated"}

The client extracts expression to run, and if the alpha passes the criteria it stores the originating source_hash in promising_alphas.jsonl so you can trace it back.

API at a glance

BrainClient: authenticate(on_biometric=None), whoami(), get(path), post(path), auto_relogin

Simulator(client): simulate(...), simulate_batch(...), is_promising(...), save_if_promising(...), load_promising(path), get_operators(), get_data_fields(...), get_alpha(id)

Test

python tests/test_full_loop.py   # mock API — no network or credentials needed

License

MIT