Metadata-Version: 2.4
Name: brain-login-and-sim
Version: 0.1.1
Summary: WorldQuant BRAIN client — login (biometric Scan + auto re-login), simulation, batch run, and auto-keeping promising alphas
Author-email: Tanakrit <9tanakrit.work@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Tanakrit/brain-login-and-sim
Project-URL: Issues, https://github.com/Tanakrit/brain-login-and-sim/issues
Keywords: worldquant,brain,alpha,quant,simulation,trading
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=0.19
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# 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

```bash
pip install brain-login-and-sim
```

## Configure credentials

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

```
WQ_EMAIL=your-email@example.com
WQ_PASSWORD=your-password
# Send the Scan link to Telegram (optional, but recommended)
TELEGRAM_BOT_TOKEN=123456789:AAH...
TELEGRAM_CHAT_ID=123456789
```

## Usage

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

```jsonl
{"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

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

## License

MIT
