# x35f/alpha2 architecture

> Architecture diagram of the GitHub repository x35f/alpha2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/x35f/alpha2
- Repository: https://github.com/x35f/alpha2

## Overview

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: [`alpha2/run.py`](https://github.com/x35f/alpha2/blob/main/alpha2/run.py) (run.py), [`alpha2/trainer.py`](https://github.com/x35f/alpha2/blob/main/alpha2/trainer.py) (trainer.py), [`alpha2/mcts/play.py`](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/play.py) (play), [`alpha2/expression/tree.py`](https://github.com/x35f/alpha2/blob/main/alpha2/expression/tree.py) (tree)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_orchestration["Orchestration"]
  node_run_sh["run.sh<br/>entrypoint<br/>[run.sh]"]
  node_run_py["run.py<br/>orchestrator<br/>[run.py]"]
  node_trainer_py["trainer.py<br/>ray trainer<br/>[trainer.py]"]
  node_comp_data_py["data prep"]
  node_configs_default["default cfg<br/>config<br/>[default.py]"]
  node_configs_sample["sample cfg<br/>config<br/>[sample.py]"]
end

subgraph group_grp_domain["Expression Domain"]
  node_expr_tokens["tokens<br/>vocabulary<br/>[tokens.py]"]
  node_expr_operators["operators<br/>ops<br/>[operators.py]"]
  node_expr_operands["operands<br/>[operands.py]"]
  node_expr_tree(("tree<br/>[tree.py]"))
  node_expr_structure["structure<br/>domain model<br/>[structure.py]"]
  node_expr_legal["legal actions<br/>constraints<br/>[legal_actions.py]"]
  node_expr_eval[("evaluate<br/>scoring<br/>[evaluate.py]")]
  node_expr_meta["meta data<br/>market metadata<br/>[meta_data.py]"]
  node_expr_port["port<br/>ray bridge<br/>[port.py]"]
end

subgraph group_grp_search["MCTS Search"]
  node_mcts_game["game<br/>search state<br/>[game.py]"]
  node_mcts_play["play<br/>rollout<br/>[play.py]"]
  node_mcts_buffer["buffer<br/>experience store<br/>[buffer.py]"]
  node_mcts_update["update<br/>learning step<br/>[update.py]"]
  node_mcts_networks["networks<br/>neural model<br/>[networks.py]"]
  node_mcts_structure["mcts structure<br/>search model<br/>[structure.py]"]
end

subgraph group_grp_support["Support"]
  node_utils_logger["logger<br/>logging helper<br/>[logger.py]"]
  node_utils_util["util<br/>helpers<br/>[util.py]"]
end

node_run_sh -->|"prepare data"| node_comp_data_py
node_run_sh -->|"launch"| node_run_py
node_run_py -->|"load cfg"| node_configs_default
node_run_py -.->|"override cfg"| node_configs_sample
node_run_py -->|"start trainer"| node_trainer_py
node_trainer_py -->|"coordinate"| node_mcts_play
node_trainer_py -->|"update"| node_mcts_update
node_trainer_py -->|"serve model"| node_mcts_networks
node_trainer_py -.->|"bridge"| node_expr_port
node_comp_data_py -->|"seed metadata"| node_expr_meta
node_comp_data_py -->|"prepare env"| node_expr_structure
node_expr_tokens -->|"compose"| node_expr_operators
node_expr_tokens -->|"terminal set"| node_expr_operands
node_expr_structure -->|"build"| node_expr_tree
node_expr_legal -->|"constrain"| node_expr_tree
node_expr_eval -->|"score"| node_expr_tree
node_expr_meta -->|"context"| node_expr_eval
node_mcts_game -->|"valid actions"| node_expr_legal
node_mcts_game -->|"state"| node_expr_tree
node_mcts_play -->|"step"| node_mcts_game
node_mcts_play -->|"policy/value"| node_mcts_networks
node_mcts_play -->|"reward"| node_expr_eval
node_mcts_play -->|"store"| node_mcts_buffer
node_mcts_buffer -->|"train data"| node_mcts_update
node_mcts_update -->|"fit model"| node_mcts_networks
node_expr_port -.->|"decouple"| node_mcts_structure
node_utils_logger -.->|"log"| node_run_py
node_utils_util -.->|"helpers"| node_run_py

click node_run_sh "https://github.com/x35f/alpha2/blob/main/alpha2/run.sh"
click node_run_py "https://github.com/x35f/alpha2/blob/main/alpha2/run.py"
click node_trainer_py "https://github.com/x35f/alpha2/blob/main/alpha2/trainer.py"
click node_comp_data_py "https://github.com/x35f/alpha2/blob/main/alpha2/computation_data.py"
click node_configs_default "https://github.com/x35f/alpha2/blob/main/alpha2/configs/default.py"
click node_configs_sample "https://github.com/x35f/alpha2/blob/main/alpha2/configs/sample.py"
click node_expr_tokens "https://github.com/x35f/alpha2/blob/main/alpha2/expression/tokens.py"
click node_expr_operators "https://github.com/x35f/alpha2/blob/main/alpha2/expression/operators.py"
click node_expr_operands "https://github.com/x35f/alpha2/blob/main/alpha2/expression/operands.py"
click node_expr_tree "https://github.com/x35f/alpha2/blob/main/alpha2/expression/tree.py"
click node_expr_structure "https://github.com/x35f/alpha2/blob/main/alpha2/expression/structure.py"
click node_expr_legal "https://github.com/x35f/alpha2/blob/main/alpha2/expression/legal_actions.py"
click node_expr_eval "https://github.com/x35f/alpha2/blob/main/alpha2/expression/evaluate.py"
click node_expr_meta "https://github.com/x35f/alpha2/blob/main/alpha2/expression/meta_data.py"
click node_expr_port "https://github.com/x35f/alpha2/blob/main/alpha2/expression/port.py"
click node_mcts_game "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/game.py"
click node_mcts_play "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/play.py"
click node_mcts_buffer "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/buffer.py"
click node_mcts_update "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/update.py"
click node_mcts_networks "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/networks.py"
click node_mcts_structure "https://github.com/x35f/alpha2/blob/main/alpha2/mcts/structure.py"
click node_utils_logger "https://github.com/x35f/alpha2/blob/main/alpha2/utils/logger.py"
click node_utils_util "https://github.com/x35f/alpha2/blob/main/alpha2/utils/util.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_run_sh,node_run_py,node_trainer_py,node_comp_data_py,node_configs_default,node_configs_sample toneBlue
class node_expr_tokens,node_expr_operators,node_expr_operands,node_expr_tree,node_expr_structure,node_expr_legal,node_expr_eval,node_expr_meta,node_expr_port toneAmber
class node_mcts_game,node_mcts_play,node_mcts_buffer,node_mcts_update,node_mcts_networks,node_mcts_structure toneMint
class node_utils_logger,node_utils_util toneRose
```

## Components

### Orchestration

Experiment entrypoints, environment setup, and distributed training coordination.

- [run.sh](https://github.com/x35f/alpha2/blob/main/alpha2/run.sh): entrypoint · Shell entrypoint that prepares data and starts the experiment. · `alpha2/run.sh`
- [run.py](https://github.com/x35f/alpha2/blob/main/alpha2/run.py): orchestrator · Main experiment runner and lifecycle coordinator. · `alpha2/run.py`
- [trainer.py](https://github.com/x35f/alpha2/blob/main/alpha2/trainer.py): ray trainer · Distributed trainer boundary for Ray-based search and model updates. · `alpha2/trainer.py`
- [data prep](https://github.com/x35f/alpha2/blob/main/alpha2/computation_data.py): data prep · Builds computation artifacts and input data for experiments. · `alpha2/computation_data.py`
- [default cfg](https://github.com/x35f/alpha2/blob/main/alpha2/configs/default.py): config · Default experiment configuration. · `alpha2/configs/default.py`
- [sample cfg](https://github.com/x35f/alpha2/blob/main/alpha2/configs/sample.py): config · Example configuration overrides for a run. · `alpha2/configs/sample.py`

### Expression Domain

Symbolic financial expression language and evaluation rules.

- [tokens](https://github.com/x35f/alpha2/blob/main/alpha2/expression/tokens.py): vocabulary · Token definitions for the symbolic expression language. · `alpha2/expression/tokens.py`
- [operators](https://github.com/x35f/alpha2/blob/main/alpha2/expression/operators.py): ops · Operator definitions used to compose expressions. · `alpha2/expression/operators.py`
- [operands](https://github.com/x35f/alpha2/blob/main/alpha2/expression/operands.py): operands · Operand definitions and terminals for expressions. · `alpha2/expression/operands.py`
- [tree](https://github.com/x35f/alpha2/blob/main/alpha2/expression/tree.py): tree model · Expression tree representation and manipulation. · `alpha2/expression/tree.py`
- [structure](https://github.com/x35f/alpha2/blob/main/alpha2/expression/structure.py): domain model · Structural rules for the symbolic environment. · `alpha2/expression/structure.py`
- [legal actions](https://github.com/x35f/alpha2/blob/main/alpha2/expression/legal_actions.py): constraints · Checks which token expansions are valid at each step. · `alpha2/expression/legal_actions.py`
- [evaluate](https://github.com/x35f/alpha2/blob/main/alpha2/expression/evaluate.py): scoring · Computes expression values and candidate alpha scores. · `alpha2/expression/evaluate.py`
- [meta data](https://github.com/x35f/alpha2/blob/main/alpha2/expression/meta_data.py): market metadata · Market/futures metadata used by expression semantics. · `alpha2/expression/meta_data.py`
- [port](https://github.com/x35f/alpha2/blob/main/alpha2/expression/port.py): ray bridge · Import boundary to avoid recursive Ray-related dependencies. · `alpha2/expression/port.py`

### MCTS Search

Search policy, experience buffer, learning updates, and neural guidance.

- [game](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/game.py): search state · MCTS game/search state abstraction. · `alpha2/mcts/game.py`
- [play](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/play.py): rollout · Search rollout and self-play style interaction. · `alpha2/mcts/play.py`
- [buffer](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/buffer.py): experience store · Stores generated search experience for learning. · `alpha2/mcts/buffer.py`
- [update](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/update.py): learning step · Applies training updates from buffered search data. · `alpha2/mcts/update.py`
- [networks](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/networks.py): neural model · Neural network used to guide search and training. · `alpha2/mcts/networks.py`
- [mcts structure](https://github.com/x35f/alpha2/blob/main/alpha2/mcts/structure.py): search model · MCTS-specific structure and state organization. · `alpha2/mcts/structure.py`

### Support

Configuration and utility helpers used across the experiment.

- [logger](https://github.com/x35f/alpha2/blob/main/alpha2/utils/logger.py): logging helper · Shared logging support. · `alpha2/utils/logger.py`
- [util](https://github.com/x35f/alpha2/blob/main/alpha2/utils/util.py): helpers · General-purpose utility helpers. · `alpha2/utils/util.py`

## Connections

- 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.