AlphaEngine & Platform Reference.

Part one · The terminal

Start here

AlphaEngine 1.1.2 is the published release. Anyone can pip install alphaengine free. The alphaengine library and its math run offline; login, workflows, reporting and sealing use the network; full return series are sent only with --share-series. Firms get ae_live_ keys through Connect in the portal; retail has no CLI and no ae_live_ keys. A separate model key is your own provider, read from the environment at call time.

pip install alphaengine==1.1.2
pip install "alphaengine[tui]==1.1.2"
alphaengine demo
alphaengine screen --data prices.csv
alphaengine

Commands that remain

The product is the sentence, the stack, and the trace. alphaengine commands prints the verbs grouped, and alphaengine commands run expands one with its flags and examples. run <name> still opens a workflow directly. Login, a model key, load, thesis, status, and quit remain.

Get started

Do the work

Bring your data

Session

The session

The session is the simulator in AlphaEngine 1.1.2. You type a sentence. The model chooses the next tool. Each tool is deterministic. Up to eight calls, one per turn, then done.

What you watch is the trace: the stack of tool calls, the figures each one returned, and a short answer at the end. While the stack runs, the session draws a live parameter surface and lights each tool as it returns. The status line reads 1.1.2. After the trace, the session asks. yes writes that trace to a text file on the machine. no leaves the file unwritten. The report is the stack and the answer.

The tools are profile, align, regime, price, reprice, correlation, covariance, cointegration, portfolio, overlap, performance, var, process, workflow, bakeoff, and done. Align keeps dates and counts gaps, and leaves them open. Regime is a two-state Hamilton filter. Price is Black-Scholes for one contract you state. Reprice is a full second price under a spot move and a vol move. Portfolio is hierarchical risk parity, or risk parity when asked. Process fits an OU, GBM, jump, or GARCH process and stresses it. A portal workflow is the tool named workflow, and only when the logged-in account offers it.

Macro and prices come from what you loaded. Nothing is fetched inside a formula. An omitted cash rate is a pinned print: the H.15 3-month Treasury constant maturity, investment basis, 4.21% as of 2026-10-06 (DGS3MO). Passing 0 means excess of zero.

Bakeoff

A bakeoff is a closed room inside the session. You ask for one in a sentence: bakeoff, bake-off, or bake off. Generators propose strategies. An adversary tries to break them. A referee, which is deterministic code, ranks the configurations. The models do not.

A generator may submit one rule: equal, hrp, risk_parity, inverse_vol, momentum, or reversion. Momentum and reversion take a trailing lookback. The engine builds the return series from the loaded book. A model cannot hand in its own returns. An adversary may name one attack: last_half, first_half, drop_best, or high_vol. drop_best removes the proposal’s best days. high_vol keeps the days the book itself was violent. Neither side may name a winner. A reply that does is ignored. Neither side may start a second bakeoff.

The room is small on purpose. Two generators propose, then the adversary attacks. That happens twice. Six model calls, then it stops. The clock defaults to 45 seconds and cannot be stretched past 60. When time runs out, the call still in flight is dropped and the referee scores only what already came back. One sentence gets one bakeoff.

The standing of a proposal is its worst Sharpe across the full sample and every attack that was actually submitted. The highest standing survives. Every proposal counts, including the ones that broke. That count is the multiple-testing denominator, and its source is bakeoff. The survivor is then deflated for that search. A pretty in-sample spike that dies on the adversary’s attack does not win.

Constant-weight rules are fit on the first half of the book and then applied to the whole path, so the second half is a holdout. Momentum and reversion are walk-forward: each day uses only the trailing window. A bakeoff needs a model key, because the generators and the adversary are model calls. The referee is not a model call.

One-shot workflows

These eight names are the workflow tool in the session, the one-shot shell, and the steps the portal agents run. Data profiles coverage, gaps, and split spikes. Test writes the shortlist, the information coefficient, the deflated Sharpe, and the overlap. Risk writes the drawdown, the cost, and the gates. Strategy returns a weight.

Coverage, gaps, and split spikes

alphaengine run diagnose_data --universe sp500

Profiles the panel before anything is computed on it: how much history each name has, where the gaps are, which series end early, and how many spikes look like splits rather than moves. Reports; repairs nothing. A gap stays a gap, because filling one invents observations nobody supplied and makes every coverage figure downstream a lie.

Rank and a bounded shortlist

alphaengine run screen_universe --universe sp500 --input rank_by=rsi

Ranks your universe and returns a bounded shortlist. If most of the universe could not be measured it refuses rather than ranking the survivors, because the names that drop out are the young, the illiquid and the recently listed, so the bias has a direction and it flatters.

Information coefficient and quantile decay

alphaengine run evaluate_signal --project research.factor

The information coefficient through time, the spread between quantiles, and how fast the edge decays. The gate that matters here runs the other way: an implausibly HIGH IC stops the run, because nothing real ranks a wide cross-section that well and a leak does it effortlessly. A fabricated edge that ships is worse than any overfit one, and this is the cheapest place in the system to catch it.

Deflated Sharpe and the trial count

alphaengine run validate_study --project research.momentum

Sweeps your grid, then deflates the result for the number of configurations actually tried. Most results that look good do not survive this, which is the reason to run it. A result that holds at exactly one point in its parameter space is a fitted result; the workflow refuses it rather than dressing the problem up as a smaller number.

Drawdown and the cost where the edge thins

alphaengine run stress_study --data returns.csv --input turnover=0.2

Subperiod stability, the drawdown anatomy, and the cost ladder: what execution costs the edge, and the basis-point level at which the strategy stops being one. Supply no turnover and the ladder is not drawn and says so, rather than reporting a cost of zero.

Correlation and beta through the drawdowns

alphaengine run check_overlap --data returns.csv

Correlation and beta of the candidate to what the book already holds, and the correlation through time rather than only on average. An idea that averages 0.2 to the book and runs at 0.9 in every drawdown is the book again exactly when being the book again costs money, and the average says the opposite.

A target weight from the risk budget

alphaengine run size_position --data returns.csv --input risk_budget=0.01

A target weight, never a share count. If the track record is too short to tell the result from luck it refuses to size it at all. A small position is still a claim there is something there, and the caveat does not follow the number into a book.

Drawdown and volatility against the gates

alphaengine run monitor_sleeve --data returns.csv   --input tolerances='{"max_drawdown_pct": 12}'

Measures a live sleeve against the tolerances you gave it, and reports every limit’s margin rather than only the ones that broke. A monitor does not stop on a breach. Every other workflow stops when a gate refuses, but withholding a monitor’s artifact on a breach withholds it exactly when it matters. The status is four-way: ok, breached, undetermined, unchecked. That is because “nothing crossed” and “nobody was watching” must never read the same.

Install

The package requires numpy>=1.24 and scipy>=1.10 (our server pins numpy==2.2.6 and scipy==1.15.3 for exact golden parity). The alphaengine library and its math run offline; login, workflows, reporting and sealing use the network; full return series are sent only with --share-series. Anyone can pip install alphaengine free.

pip install alphaengine==1.1.2

# factor decomposition and cointegration need statsmodels
pip install 'alphaengine[factors]==1.1.2'

Your first sweep

The library does not backtest anything. It runs your backtest once per combination in a grid, then measures the result against the size of the search that produced it.

from alphaengine import sweep

r = sweep(
    my_backtest,                                    # YOUR function
    {"fast": [5, 10, 20], "slow": [50, 100, 200]},  # the search
    data=prices,                                    # passed through untouched
)

r.n_trials
# 9

That number is why the API is shaped this way. The correction that makes a Sharpe ratio honest needs to know how many variants you tested. Ask a person for it and you get the number that flatters them, not from dishonesty, but because nobody counts what they threw away. Running the grid makes the count len(grid), so the question never has to be asked.

Reading the surface

Before any verdict, look at the neighbourhood. A result sitting on a broad plateau is robust. A single spike surrounded by failures is a result fitted to its own parameters.

r.surface()
# {
#   'shape': 'knife_edge',
#   'n_ok': 9,
#   'n_failed': 0,
#   'best_sharpe': 1.9143,
#   'median_sharpe': 0.221,
#   'share_within_20pct_of_best': 0.1111,
#   'plateau_centre': None,
#   'reading': 'One configuration performs and its neighbours do not. '
#              'Usually a fitted result.',
# }

shape

plateau, ridge or knife_edge (API literal). Share of the grid within 20% of the best result: ≥30% plateau, ≥10% ridge, else knife_edge.

share_within_20pct_of_best

The number behind the shape, so you are free to disagree with the thresholds.

plateau_centre

Per parameter, where the robust region sits and how wide it is. The actionable half: it tells you where to re-centre, not merely that your number was flattered.

reading

The shape in one sentence. The same string every time, so it can be quoted.

Reading the verdict

The verdict deflates the best result for the search that actually produced it, and reports what it needed in order to say so.

v = r.verdict()

v["n_trials"]                 # 9
v["n_trials_source"]          # 'derived_from_grid'
v["deflated_sharpe"]          # 0.3106
v["verdict"]                  # 'inconclusive'
v["data_hash"]                # a content hash of what it ran on
v["min_track_record_length"]  # how long this record must run to beat luck

n_trials_source travels with the figure on purpose. A count that was asserted and a count that was counted are different claims, and every deflated number downstream rests on which one it is. When this package produces the figure the source is always derived_from_grid, because there is no other way to produce it here.

Probability of backtest overfitting is reported alongside, and is deliberately not the gate:

v["selection"]
# {
#   'question': 'was the choice among configurations informative?',
#   'not_a_verdict_on_the_edge': True,
#   'pbo': 0.48, ...
# }

The study file

A study is a JSON artifact holding what was tried, what came back, and a content hash of the data it ran on. Readable in a text editor, diffable, and versioned so it still parses in two years.

r.save("study.json")
# PosixPath('study.json')

from alphaengine import load
s = load("study.json")

s.schema_version   # load() refuses an unknown MAJOR version
s.data_hash        # a label can be changed to escape a history; an array cannot
s.n_trials_source  # 'derived_from_grid'

The version rule here is stricter than semver: a bump is required whenever a computed value changes, even when the signature is untouched. Once the numbers are published they are a contract, and somebody’s saved study has to reproduce.

AlphaEngine CLI + quantOS

The alphaengine library and its math run offline; login, workflows, reporting and sealing use the network; full return series are sent only with --share-series. Anyone can pip install alphaengine free. Firms get org-scoped ae_live_ keys through Connect in the portal (/portal/data) and sync via ae remote add quantos, ae push, and ae pull; retail has no CLI and no ae_live_ keys. See the dedicated AlphaEngine CLI + quantOS guide for the full protocol reference.

pip install alphaengine==1.1.2
ae init
ae seal study.json
ae verify study.json

export QUANTOS_API_KEY="ae_live_..."
ae remote add quantos https://api.qosai.app
ae push
ae pull

Local-first vs. synced

The alphaengine library and its math (`sweep()`, `ae seal`, `ae verify`, custom `.py` strategy modules) run offline; login, workflows, reporting and sealing use the network; full return series are sent only with `--share-series`. Synced (`POST /api/workspace/sync`, `GET /api/workspace/pull`): sealed studies, idea objects (`thesis`, `kill_rule`, `status`, `family`), run records, and `trial_ledger` entries update the shared Firm Hypothesis Board and Experiment Ledger.

What `ae push` sends

Sealed study metadata (`content_sha256`, `n_trials`, `n_trials_source`, 64-hex `data_hash` / `dataset_hashes`, `deflated_sharpe`, `psr_vs_zero`, `sr0_expected_max`, `min_track_record_length`, `selection` with CSCV `pbo`, `surface`, `performance`, `trial_ledger`), idea objects, run records, and 1D figure curves capped at 512 points (or full return series only when explicitly opted in with `--share-series`).

What `ae push` never sends

Raw datasets (`raw_dataset`, `raw_data`, `price_matrix`, `return_matrix`, `ohlcv`, CSV/Parquet files, 2D return matrices), proprietary `.py` strategy code, unhashed parameter values (`store_params` is off by default), and local LLM API keys.

Plan limits (server-enforced)

Anyone can `pip install alphaengine` free for local math. Retail tiers ($79 Starter, $149 Pro, $299 Power) are web-only and have no CLI or `ae_live_` keys. Firm tiers (`firm_core` $10K/mo, `firm_pro` $15K/mo, `firm_enterprise` $25K/mo) get org-scoped `ae_live_` keys through Connect and full team workspace sync & pull across all pod members.

Wiring your own backtest

Your function is called once per combination and must return a sequence of per-period returns. It is called as backtest_fn(data=data, **params) when data is given, and backtest_fn(**params) when it is not.

def my_backtest(*, data, fast, slow):
    fast_ma = data.close.rolling(fast).mean()
    slow_ma = data.close.rolling(slow).mean()
    signal = (fast_ma > slow_ma).shift(1)
    return (signal * data.close.pct_change()).dropna().to_numpy()

r = sweep(my_backtest, {"fast": [5, 10, 20], "slow": [50, 100, 200]}, data=px)

data

Passed through untouched. Only hashed, never inspected, never stored.

store_params

OFF by default. Hashes are always kept, so runs stay comparable without the parameter values leaving your machine. The grid is often bigger intellectual property than the return series.

on_error

'record' (the default) marks a failing combination and continues, because one bad corner of a grid should not lose the other ninety-nine results. 'raise' propagates.

The result holds the full trial matrix, which is what PBO needs and what a single-point run structurally cannot produce. That is the argument for running a grid rather than calling a calculator on one number.

What is in the core

Everything below is a pure function: no clock read, no environment read, no data-layer import. That is guaranteed by a test that scans the module tree without importing it.

from alphaengine.core import (
    deflated_sharpe,                 # corrected for the size of the search
    probabilistic_sharpe_ratio,
    expected_max_sharpe,             # what the best of N looks like under no edge
    min_track_record_length,         # how long before it beats luck
    pbo_cscv,                        # probability of backtest overfitting
    combinatorial_oos_stability,     # single-stream combinatorial purged OOS stability (cpcv_score is a deprecated alias)
    performance_report,
    compute_var_cvar,
    run_backtest,
    score_backtest,
    technical_features,
)

VaR and CVaR

Always POSITIVE loss magnitudes, with CVaR at least VaR. Sign conventions are the most common source of a wrong risk number, so this one is fixed everywhere.

Calmar

Geometric. Annualised return compounds rather than averaging.

Sortino

The denominator is target semideviation over all N periods, not the standard deviation of the negative subset.

Factor decomposition and cointegration live behind the factors extra, so statsmodels is not a hard dependency of the core.

Whose data it is

The alphaengine library and its math run offline; login, workflows, reporting and sealing use the network; full return series are sent only with --share-series. The platform holds what it needs to do the job, because a monitor cannot run overnight against a browser tab and a study cannot be reproduced in two years against a series nobody kept. The question that matters is not whether we hold it, it is on what terms.

Yours

Encrypted at rest, scoped to your account, exportable in full, deletable in full.

Never pooled

One customer's data never sits in a store another can read, and no aggregate is derived across customers.

Never learned from

Nothing trains or tunes on it. Not a model, not a ranking, not a default.

Never redistributed

Vendor data stays under your licence and your entitlement, used on your behalf and never resold.

Your model

Never ingested. We do not take your alpha logic.

Your parameter grid

Hashed by default; values kept only if you ask for it.

The full line, item by item, is on the Trust page.