How x35f/alpha2 works
1. Overall shape
- This repository is a research prototype / pseudocode architecture for Alpha², not a full runnable product.
- The system is organized around a config-driven experiment runner that prepares market data, launches a Ray-based distributed trainer, and uses MCTS + a neural network to search over symbolic financial expressions.
2. Top-level execution flow
- run.sh is the intended entrypoint: it first generates computation data, then starts the experiment runner.
- run.py is the main orchestration entrypoint for an experiment.
- computation_data.py prepares the input artifacts used by the experiment, likely derived from market/computation metadata.
3. Configuration and environment boundary
- alpha2/configs/default.py and sample.py define experiment settings.
- env.yaml and setup.py indicate a Python-based project environment and package layout.
- utils/logger.py and utils/util.py provide support functions for logging and config/loading behavior.
4. Core domain layer: symbolic expression environment
- The alpha2/expression package defines the search space that MCTS operates on.
- operators.py, operands.py, and tokens.py define the vocabulary of the expression language.
- structure.py, tree.py, and port.py define the expression-tree representation and help separate domain logic from Ray import concerns.
- evaluate.py computes the value of an expression, which is the basis for scoring candidate alphas.
- legal_actions.py enforces which token expansions are valid at each MCTS step.
- meta_data.py holds market/futures metadata used by the expression semantics.
5. Search layer: MCTS
- The alpha2/mcts package contains the search and learning loop, adapted from AlphaDev-style code.
- game.py and structure.py define the game/search state abstraction for MCTS.
- play.py performs search rollout / self-play style interaction.
- buffer.py stores generated experience.
- update.py applies learning updates from buffered search data.
- networks.py defines the neural model used to guide the search.
6. Trainer orchestration
- trainer.py is the bridge between the experiment runner and the MCTS/network components.
- The README says it defines MCTS and network trainer actors for Ray, so this is the distributed execution boundary.
- This is where parallel search, model updates, and coordination of worker actors are expected to happen.
7. Data flow through the system
- Prepared market/computation data enters through computation_data.py.
- The expression layer turns that data into a legal symbolic environment.
- MCTS proposes candidate expression trees, constrained by legal_actions.py and token validity checks.
- Candidate expressions are evaluated by evaluate.py, and their outcomes feed back into buffer/update logic for training.
8. Important architectural boundaries
- Domain boundary: expression/ is the pure problem representation: tokens, trees, legality, and evaluation.
- Algorithm boundary: mcts/ contains the search-and-learn machinery.
- Orchestration boundary: run.py, run.sh, and trainer.py coordinate the experiment lifecycle.
- port.py exists specifically to prevent recursive import issues with Ray, so the code deliberately separates runtime plumbing from domain logic.
9. External/runtime dependencies that matter
- Ray is a key runtime dependency because the training/search actors are distributed.
- The code is designed for deep reinforcement learning over symbolic expressions, so the neural network and search components are tightly coupled.
- The repository appears to target financial market data (stocks/futures) as the domain for alpha discovery.
10. How to draw the architecture
- Place run.sh/run.py at the top as the experiment launcher.
- Show computation_data.py feeding prepared data into the experiment.
- Put trainer.py as the distributed coordinator, backed by Ray.
- Under it, split into two major subsystems: mcts/ for search/training and expression/ for the symbolic environment.
- Connect expression/evaluate.py and legal_actions.py as the feedback/control points that determine reward and valid expansion of expression trees.
Main entry points: run.py run.py · trainer.py trainer.py · play.py play · tree.py tree
Components 23
Orchestration
Experiment entrypoints, environment setup, and distributed training coordination.
- run.sh · Shell entrypoint that prepares data and starts the experiment.
alpha2/run.sh - run.py · Main experiment runner and lifecycle coordinator.
alpha2/run.py - trainer.py · Distributed trainer boundary for Ray-based search and model updates.
alpha2/trainer.py - data prep · Builds computation artifacts and input data for experiments.
alpha2/computation_data.py - default cfg · Default experiment configuration.
alpha2/configs/default.py - sample cfg · Example configuration overrides for a run.
alpha2/configs/sample.py
Expression Domain
Symbolic financial expression language and evaluation rules.
- tokens · Token definitions for the symbolic expression language.
alpha2/expression/tokens.py - operators · Operator definitions used to compose expressions.
alpha2/expression/operators.py - operands · Operand definitions and terminals for expressions.
alpha2/expression/operands.py - tree · Expression tree representation and manipulation.
alpha2/expression/tree.py - structure · Structural rules for the symbolic environment.
alpha2/expression/structure.py - legal actions · Checks which token expansions are valid at each step.
alpha2/expression/legal_actions.py - evaluate · Computes expression values and candidate alpha scores.
alpha2/expression/evaluate.py - meta data · Market/futures metadata used by expression semantics.
alpha2/expression/meta_data.py - port · Import boundary to avoid recursive Ray-related dependencies.
alpha2/expression/port.py
MCTS Search
Search policy, experience buffer, learning updates, and neural guidance.
- game · MCTS game/search state abstraction.
alpha2/mcts/game.py - play · Search rollout and self-play style interaction.
alpha2/mcts/play.py - buffer · Stores generated search experience for learning.
alpha2/mcts/buffer.py - update · Applies training updates from buffered search data.
alpha2/mcts/update.py - networks · Neural network used to guide search and training.
alpha2/mcts/networks.py - mcts structure · MCTS-specific structure and state organization.
alpha2/mcts/structure.py
Connections 28
- run.sh → data prep: prepare data · Shell entrypoint invokes computation data generation first.
- run.sh → run.py: launch · Shell entrypoint starts the experiment runner.
- run.py → default cfg: load cfg · Runner reads default experiment settings.
- run.py → sample cfg: override cfg · Sample config provides alternative run parameters.
- run.py → trainer.py: start trainer · Runner hands control to the distributed trainer.
- trainer.py → play: coordinate · Trainer coordinates search workers and rollout execution.
- trainer.py → update: update · Trainer triggers learning updates from collected experience.
- trainer.py → networks: serve model · Trainer owns the neural model used by workers.
- trainer.py → port: bridge · Trainer uses the Ray-safe import boundary.
- data prep → meta data: seed metadata · Prepared data supplies market metadata to the environment.
- data prep → structure: prepare env · Computation artifacts feed the symbolic environment setup.
- tokens → operators: compose · Operators and tokens jointly define the expression vocabulary.
- tokens → operands: terminal set · Operands define the available terminal symbols.
- structure → tree: build · Structural rules instantiate expression trees.
- legal actions → tree: constrain · Legal action rules restrict tree expansion.
- evaluate → tree: score · Evaluation runs over candidate expression trees.
- meta data → evaluate: context · Metadata informs expression semantics and evaluation.
- game → legal actions: valid actions · Search state queries legal expansions from the domain layer.
- game → tree: state · Game state wraps the current expression tree.
- play → game: step · Rollouts advance through the search state.
- play → networks: policy/value · Search uses the network for guidance.
- play → evaluate: reward · Rollouts depend on expression evaluation for scoring.
- play → buffer: store · Search experience is written to the buffer.
- buffer → update: train data · Buffered experience feeds learning updates.
- update → networks: fit model · Updates adjust the neural model parameters.
- port → mcts structure: decouple · Port layer separates runtime plumbing from search/domain structure.
- logger → run.py: log · Shared logging support for orchestration.
- util → run.py: helpers · Utility helpers support configuration and loading behavior.