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.