Skip to content

Concepts

The words the SDK, the app and Helyx use for the same things, and how they connect. The SDK is changing quickly; the vocabulary is not.

The objects

Term What it is Where you meet it
Signal Information a strategy can read: a value per delivery period at a point in time, computed from the market data or supplied by you. Signals, Catalogue
Signal library Your shelf of signals from the catalogue, each pinned to a version, with why it is in. A Study reads only from its library. Signals, Libraries
Strategy A chain of declared components (trade rules, filters, volume policy, market policy, completion) that decides what to do on every event. Named <id>@<version>; a saved version never changes. Strategies, Strategy Library; --strategy on a run
Configuration A strategy document as edited inside a Study, saved as numbered states. What a backtest actually tests. a Study, Configurations; --configuration on a run
Study An objective-scoped collection of experiments: one strategy to start from, the datasets held fixed, the periods to compare over, the configurations tried, the backtests run. It ends in a conclusion. Studies; --study on a run
Backtest (a run) One configuration over one period on your datasets, replayed against the historical order book. One experiment. Studies, Backtests; helyx request, helyx runs
Evaluation frame The datasets, periods and metrics a Study holds fixed. Two backtests are comparable only when they share it. a Study's header
Conclusion How a Study ends: what was learned, and which configurations are promoted. "Nothing beat the baseline" is a valid conclusion. A concluded Study is read-only. a Study, Conclude
Promoted model A configuration locked at the state a Study concluded on, with its config hash. The pool holds every model ever promoted. Strategies, Promoted models
Config hash A fingerprint of what the engine would do: the chain, its parameters, the per-tag settings, and the version of every signal read. Two documents with the same hash decide identically. every version, configuration and model
Model health Read against the catalogue: healthy (every signal at the version it was locked on), degraded (a signal moved or is gone; it still runs, flagged), retired (cannot be assigned; stays in history). Promoted models
Trading group A trading responsibility: a desk, a client's book, a mandate. It holds portfolios. Strategies, Trading Groups
Portfolio The assets whose position is traded as one. A trading group has one or more. Trading Groups, Data
Assignment A promoted model placed in a portfolio with a role and, for live roles, a share of the volume. Trading Groups, Operations
Role Champion: the one model trading the portfolio's volume by default. Challenger: a model given part of the volume to compete with the champion. Shadow: a model deciding live without volume, so its decisions can be compared. an assignment

How they connect

flowchart LR
  subgraph Research
    SIG["Signal library"] --> ST["Study"]
    STR["Strategy version"] --> ST
    DS["Your datasets"] --> ST
    ST --> CFG["Configurations"]
    CFG --> BT["Backtests"]
    BT --> CON["Conclusion"]
  end
  CON -- "promotes up to the cap" --> POOL["Pool of promoted models"]
  subgraph Deployment
    POOL -- "assignment" --> PF["Portfolio"]
    PF --> CH["Champion"]
    PF --> CL["Challengers"]
    PF --> SH["Shadows"]
  end

Research and deployment are two cycles with one gate between them. A Study never trades; a portfolio never experiments. The pool is the handover: a model in it is locked, fingerprinted and checked for health every time it is shown.

One portfolio, one champion

When several strategies should run at the same time with a volume split, each split is its own portfolio inside one trading group, and each portfolio has at most one champion. Two models that share a portfolio's volume on purpose are a champion and a challenger with a split, and the split is the record of the experiment. There are no co-champions.

flowchart TB
  TG["Trading group: Solar NL"] --> A["Portfolio A · 50%"]
  TG --> B["Portfolio B · 50%"]
  A --> A1["Champion: long window (s2)"]
  A --> A2["Shadow: baseline"]
  B --> B1["Champion: baseline"]
  B --> B2["Challenger 20%: finer deadband"]

Per portfolio: zero or one champion (none means the portfolio is not algorithmically live), zero to four challengers with real volume and only when there is a champion, and shadows without volume. Every change to an assignment or a split is logged with who, when, which model, from and to which role, and the split at that moment. Rollback is re-assigning a model already in the pool; it needs no new Study.

A run names what it tests

A backtest request can carry the Study and configuration it belongs to, beside the policy version and the configuration file the engine takes today:

helyx request --id solar-long-window-aug \
  --policy v1.3.0 --config long-window \
  --strategy esg_closer@1.1.0 --study solar-portfolio-rebalancing --configuration long-window \
  --start 2026-08-01 --end 2026-08-31 \
  --pm-targets pm-floor20 --da-cleared actual-da --delivered realised

--strategy, --study and --configuration are provenance: they say which research the run belongs to, so the Study's results matrix can find it. The engine runs the policy version plus the config. Starting a run from the app fills all of this in.