alpha-cli

alpha-cli is a local, reproducible research assistant for WorldQuant Brain FASTEXPR experiments. It delegates candidate generation to an already authenticated local Gemini CLI or Claude Code installation, validates the result locally, and can submit the candidate through the existing Brain API flow.

It is not an autonomous trading system, a guaranteed alpha generator, or an automatic alpha-submission tool.

What it does

CLI → deterministic original template baseline → local delegate slot mutation
    → strict local rendering + FASTEXPR validation → comparable primary Brain simulations
    → SQLite run, candidate pair, evidence snapshot, generation, and simulation history

Every mining command creates a run ID. Its provider, seed, prompt-template version, selected context, input hash, generated response, validation findings, corrections, simulation attempts, metrics, and outcome are stored locally.

Install

Python 3.10–3.13 is supported.

pip install -e .
alpha-cli --help

For contributors:

pip install -e .[dev]

Setup and examples

Install and authenticate either gemini or claude on your machine first. Then run:

alpha-cli setup
alpha-cli config show
alpha-cli doctor

setup saves WorldQuant username/password only in the system keychain. The local config file stores non-sensitive preferences only.

Generate and validate without any WorldQuant authentication or simulation:

alpha-cli mine start --dry-run --seed 42

Run a recorded research batch with Brain simulation:

alpha-cli mine start --region USA --universe TOP3000 --iterations 10 --seed 42

Illustrative output (not a performance claim):

Run 77b… completed: DRY_RUN

Commands

Command	Purpose
alpha-cli setup	Interactive provider preference and keychain credential setup.
alpha-cli doctor	Checks config, keychain presence, delegate executable, database, and package version without exposing secrets.
alpha-cli config show [--json]	Shows non-sensitive settings and credential presence.
alpha-cli templates list / templates show ID	Inspects the immutable local template catalog.
alpha-cli mine start --generation-mode hybrid --seed N [--dry-run]	Default mode: each iteration is a baseline/variant pair, up to two simulations.
alpha-cli mine start --generation-mode freeform	Uses the prior freeform delegate flow.
alpha-cli runs list / runs show ID --json	Inspects immutable run history.
alpha-cli results view [--json]	Displays recorded simulation attempts.
`alpha-cli results export --format json	csv [--limit N] [--min-sharpe S]`

Run outcomes and exit codes

A run reports COMPLETE only when every iteration produced a usable baseline and variant result. PARTIAL means some comparable work landed; ERROR means nothing usable was produced. A run row is marked RUNNING while in flight, so an interrupted run stays distinguishable from a finished one.

Exit code	Meaning
0	Run completed, or completed partially.
1	The run finished but produced nothing usable (ERROR, NO_CANDIDATE).
2	Configuration, template-filter, or input validation failure.
3	Authentication failure.
5	Local delegate failure.
6	WorldQuant Brain network or API failure.
7	Local storage failure.

Failed simulations are never reported as success: if Brain cannot be reached, the affected attempts are recorded as FAILED and the run exits non-zero.

Local storage and security

The standard local store is ~/.alpha-cli/; use ALPHA_CLI_HOME to point a test or isolated session at a different directory. It governs both config.json and alpha_mining.db, so an isolated session shares nothing with your normal one. WorldQuant credentials remain in the operating system keychain, which is a system service and therefore not affected by ALPHA_CLI_HOME. Prompts, cookies, tokens, passwords, authentication response bodies, and raw credentials are never printed by the application.

The SQLite schema is versioned. Existing prototype alphas and simulations tables are retained untouched and imported once into a new legacy-* run, so the original data remains recoverable. New records use UUIDs for runs, candidates, and attempts; remote simulation/alpha IDs are nullable external identifiers.

Reproducibility and validation

Hybrid mode freezes the catalog, metadata snapshot, history cutoff, bounded evidence snapshot, provider identity, settings, template, slots, and canonical generation-input hash before each provider call. The same database state and run inputs produce the same baseline and provider prompt. The provider may change one or two typed slot values only; it cannot provide an expression or settings.

Primary baseline and variant simulations use the same conservative settings: delay 1, decay 2, truncation 0.08, and SUBINDUSTRY neutralization, with the CLI-selected universe. Later optimization attempts are stored separately and are excluded from pair comparisons.

Original project templates distributed under the repository’s MIT licence.

Local validation proceeds in this order:

1. Pydantic structured delegate response validation.
2. FASTEXPR syntax checks.
3. Field/operator metadata warnings when metadata is available.
4. Semantic warnings.
5. Remote simulation, unless --dry-run is selected.

Warnings remain visible in history; syntax errors prevent remote submission. Repeated unchanged expression/settings pairs are not simulated within a candidate.

Testing and quality checks

ruff format --check .
ruff check .
pytest -q
python -m build

$ pytest -q
...................................                                      [100%]
35 passed in 0.32s

No network, Gemini, Claude, or WorldQuant calls are made in tests. CI runs the same checks on Python 3.10–3.13 on every push.

Current limitations and API assumptions

Brain endpoints and payload fields have been preserved from the existing integration: /authentication, /operators, /data-sets, /data-fields, /simulations, and /alphas/{id}. The client validates responses rather than guessing missing fields. The project cannot independently verify endpoint semantics without a user-authorized, credentialed manual run.

The local template doctor validates catalog structure and local FASTEXPR syntax only. It does not claim Brain compatibility; a credentialed Brain smoke test is still required for every new operator, field, or platform compatibility question. The local delegate command shapes may need adjustment for a particular installed Gemini CLI or Claude Code version.

WorldQuant Brain and all financial research involve risk. Use this project only in accordance with the platform’s terms and with human review; nothing here is investment advice.