# AlphaMaster keeps one StackVM signal path from search to live

> AlphaMaster is an AGPL-3.0 factor mining workshop for MetaTrader 5 data: reinforcement learning searches interpretable formulas in a feature and operator space, the winner is saved as a token sequence, and a single StackVM evaluates it identically in training, backtest and live analysis behind a FastAPI console.

**rosemarycox5334-debug/AlphaMaster** — MT5 factor mining, backtest, and web training UI

- Repository: https://github.com/rosemarycox5334-debug/AlphaMaster
- Stars: 611 · Forks: 226
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-17 · Updated: 2026-09-17 · Language: en
- Canonical page: https://hysenlabs.com/projects/rosemarycox5334-debug-alphamaster

## One signal path, three ways of running it

The design decision worth noticing is that training, backtest and live analysis share a single signal implementation. A formula is stored as a token sequence, for example in strategies/best_BTCUSDT.json, and a StackVM interprets and executes it, so the same code path produces the factor in all three places.

The signal semantics are stated in four lines and apply everywhere. The StackVM computes a scalar series from the factor. The position is tanh(factor), which lands inside the range from minus 1 to 1, so a stronger signal means a larger position. When the absolute position is below a threshold it counts as no signal, a wait state rather than a small trade. And the live side uses closed candles only, explicitly to avoid intraday flicker and a mismatch with the backtest.

That last rule is the one to keep in mind when reading any result from this project. A live number that moved intraday was never part of the backtest definition.

## The web console is the recommended way in

The console is a FastAPI application started with two commands:

```bash
pip install -r requirements.txt
python run_web.py --port 8765
```

You then open http://127.0.0.1:8765 in a browser. The interface is three numbered steps rather than a dashboard. Step 01 is model training, where you pick a Parquet file, start or restart a run, watch curves and logs, and export the strategy and checkpoint. Step 02 is strategy backtest, where you pick a strategy JSON, set commission and slippage, and read the performance numbers and equity curve. Step 03 is real-time analysis, which monitors several data sources, updates signals after each close, and can push a Feishu alert on a direction reversal.

A command-line route exists for the same training job on a single file:

```bash
python train_file.py --data-file D:\K线数据\BTCUSDT_H1.parquet
python train_file.py --data-file D:\K线数据\BTCUSDT_H1.parquet --from-scratch
```

## Retraining treats the best strategy as a floor

Start training and restart training do different things. Starting resumes from the checkpoint if one exists, so a long search is not lost. Restarting clears the checkpoints and searches again from scratch.

What makes the restart safe is one sentence in the training panel: an existing better strategy becomes the score floor, so a weaker result will not overwrite it. In other words, the file in strategies/ is monotonic in score, which means a bad run can waste time but cannot damage what you already had.

The panel also shows the best score, the validation score, the training curve and the best formula it found, with an optional AI analysis of how the current run is going. Selection happens on validation performance rather than on the training fit, which is the only place in the description where the two are distinguished at all.

## tanh sizing makes the cost assumptions visible

Backtesting runs the factor through the same position rule as live trading, position = tanh(factor), so the size of a position follows the strength of the signal instead of being a fixed contract count. Costs are explicit inputs: commission plus slippage, with defaults of roughly 0.02 percent and 0.01 percent.

The outputs are the usual backtest panel: total return, Sharpe, Sortino, the profit and loss ratio, a rolling Sharpe and the equity curve. Rolling Sharpe is the one that matters most here, because a single aggregate Sharpe hides the stretches where the strategy was not working.

Those numbers are only as honest as the cost inputs. The defaults are small, the position rule assumes you can fill at the modelled price, and the wait state below the threshold means the strategy sits out rather than trading small, which changes both the turnover and the cost profile compared with a system that always holds a position.

## Live signals wait for the candle to close

Real-time analysis pulls from sources such as MT5 and OKX, with the exact set depending on what the interface offers. It re-evaluates only after the current period's bar has closed, and an unfinished bar takes no part in the signal at all. Each card shows a direction, bullish, bearish or uncertain, along with a level of confidence.

Alerts are optional and narrow. A Feishu webhook, when configured, pushes a text message only when the direction reverses, so a steady trend does not generate a stream of notifications.

The project separates the live logic from the research logic in the tree: strategy_manager/ holds the live signal and position logic and is described as matching the backtest convention, while execution/ holds the MetaTrader 5 order interface. The separation is what lets you run the live panel without placing orders, and it is where you would look first if live and backtest results ever diverge.

## Parquet naming is the contract with the data layer

Data arrives as Parquet files whose names encode symbol and period, following the pattern {symbol}_{period}.parquet, with BTCUSDT_H1.parquet and XAUUSD_H1.parquet given as the examples. The data_pipeline/ directory loads and aligns them, which is where a misaligned feed between symbol and period would surface first.

Generated strategies follow the same convention, landing by default at strategies/best_{symbol}.json. Training checkpoints live beside them in checkpoints/, so a run can be resumed or inspected after the fact.

The declared environment is Python 3.10 or newer, with 3.11 recommended. requirements.txt mixes numerical and market data work, torch, numpy, scipy, pandas, pyarrow, with MetaTrader5, tushare, pytdx and a tvdatafeed package installed straight from git, which the file flags as the line that can fail on a given network.

## AGPL-3.0, and a top level full of check scripts

The licence is GNU Affero General Public License v3.0, and the README spells out the consequence in one line: modifying, distributing or providing the project over a network requires publishing the corresponding source under the same protocol. Running the FastAPI console on a shared host therefore falls under the network clause.

The top level shows how the project is actually worked on. Alongside the expected directories there are single-purpose scripts: check_ckpt.py through check_ckpt5.py, deep_check_all.py, deep_investigate.py, benchmark_speed.py, analyze_index_overfit.py and analyze_index_overfit2.py, monitor_live_risk.py, live_trade.py, and a group of download_ and fetch_ scripts for futures, rubber and metals. There is also a requirements-optional.txt beside the main one.

Credentials follow a template rather than living in code. .env.example carries MT5_LOGIN, MT5_PASSWORD and MT5_SERVER, and the note at the top says to copy it to .env, which is already in .gitignore and will not be pushed. The repository was last pushed on September 3, 2026 and has no GitHub releases.

## Conclusion

AlphaMaster suits someone who wants an interpretable formula rather than a black box, and who values that the backtest and the live signal run the same StackVM code. It does not suit anyone expecting a finished strategy library: there are no releases, the repository was last pushed on September 3, 2026, and the factor search is a starting point whose equity curve still depends on your data and your costs. Before running it, decide the commission and slippage you will believe, keep the .env out of version control as the template intends, and read the AGPL-3.0 terms before exposing the console over a network.

## FAQ

### How does AlphaMaster turn a factor into a position?

The StackVM evaluates the formula into a scalar series and the position is tanh(factor), bounded between minus 1 and 1, so a stronger signal means a larger position. When the absolute value sits below the threshold, AlphaMaster treats it as no signal.

### How do I start the AlphaMaster web console?

Install the dependencies with pip install -r requirements.txt, run python run_web.py --port 8765, then open http://127.0.0.1:8765 in a browser. The README calls this the recommended entry point.

### What data format does AlphaMaster expect?

Parquet files named {symbol}_{period}.parquet, with BTCUSDT_H1.parquet and XAUUSD_H1.parquet given as examples. The data_pipeline directory loads and aligns them, and MT5 candlesticks are the other source.

### Does retraining in AlphaMaster throw away a good strategy?

No. Starting training resumes from an existing checkpoint, while restarting clears checkpoints and searches again from scratch. An already better strategy acts as a score floor, so a weaker result will not overwrite it.

### Does AlphaMaster need a MetaTrader 5 terminal?

Only for the live MT5 data source and the live trading scripts. Training and backtest run from Parquet files, and MT5 credentials go into a .env file copied from .env.example.

### What licence is AlphaMaster released under?

GNU Affero General Public License v3.0. Modifying, distributing or providing it over a network requires publishing the corresponding source code under the same licence.

## Sources

- [Issues](https://github.com/rosemarycox5334-debug/AlphaMaster/issues)
- [License: AGPL-3.0](https://github.com/rosemarycox5334-debug/AlphaMaster/blob/main/LICENSE)
- [README](https://github.com/rosemarycox5334-debug/AlphaMaster/blob/main/README.md)
- [rosemarycox5334-debug/AlphaMaster on GitHub](https://github.com/rosemarycox5334-debug/AlphaMaster)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rosemarycox5334-debug-alphamaster