# 0xreisearch/hanabi-1 architecture

> Architecture diagram of the GitHub repository 0xreisearch/hanabi-1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/0xreisearch/hanabi-1
- Repository: https://github.com/0xreisearch/hanabi-1

## Overview

##### Main Components
- Input Data & Data Sources:
- Hourly Price Data (CSV files such as “hourly_data.csv” – as described in the README)
- Fear and Greed Index Data (CSV files within a folder like “fear_greed_data”, with examples provided in “example_data”)
- Data Preprocessing:
- The “data_preprocessor.py” script handles loading, normalization, and sequence creation including positional encoding.
- Transformer Model Core:
- “transformer_model.py” contains the architecture details – multiple transformer layers with multi-head self-attention, BatchNorm, leaky activations, specialized prediction heads (for Direction, Volatility, Price Change, and Spread).
- Training Pipeline:
- “train_model.py” manages the training process with configurable parameters (e.g., window size, hidden dimensions, learning rate, etc.).
- Training scripts (like “robust_model.sh”, “balance_test.sh”, “seed_test.sh” as mentioned in the README) orchestrate different training configurations.
- Prediction & Evaluation:
- “predict.py” is used for generating predictions.
- “evaluate_ensemble.py” supports ensemble evaluations and performance metrics.
- Data Output and Logging:
- Directories such as “trained_models/”, “logs/”, “evaluation/”, and “predictions/” (as mentioned in the README) store outputs, checkpoints, metrics, and visualizations.

##### Relationships and Interactions
- Data Sources feed into Data Preprocessing. The preprocessed data is then fed into the Transformer Architecture.
- The Transformer Model’s outputs branch out into different “heads” for each prediction type (classification for direction, regressions for volatility, price change, and spread).
- The Training Pipeline takes preprocessed data and feeds it into the model, applying techniques like Xavier initialization, BatchNorm, and gradient clipping.
- Once trained, the model checkpoints (saved in “trained_models/”) are used by the Prediction and Evaluation components.
- Evaluation and ensemble testing generate metrics and visualizations that are stored in “evaluation/” and “logs/”.

##### Architectural Patterns and Design Principles
- Modular Design: There is clear separation of concerns – data processing, model architecture, training, prediction, and evaluation are all handled by distinct modules.
- Configurable Parameters: The architecture highlights flexibility (e.g., adjustable window sizes, transformer layers, learning rate) making the system highly parameterizable.
- Ensemble and Robust Evaluation: Support for ensemble approaches and dynamic calibration of thresholds emphasize reliability in prediction.

##### Relevant Technologies and Libraries
- Core language: Python
- Frameworks/Libraries: Likely PyTorch or TensorFlow for transformer implementations (inferred from typical practices), though the exact one isn’t specified.
- Additional tools: Scripts for training (shell scripts) and likely use of visualization libraries for evaluation outputs (e.g., matplotlib or similar).

##### Elements
- Raw Data → Preprocessing → Transformer Model → Training → Prediction/Evaluation
- Data sources (input files)
- Processing components (data_preprocessor.py)
- Core model components (transformer_model.py with sub-heads for each prediction type)
- Execution scripts (train_model.py, predict.py, evaluation scripts) and output/storage (trained_models, logs, predictions)
- Optionally, annotate connections with key parameters (e.g., window sizes, hidden dimensions) and details like “BatchNorm, Xavier, Gradient clipping.”

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Ingestion Layer"
        DS["Data Sources (Hourly Price CSV & Fear&Greed CSV)"]:::datasource
    end

    DS -->|"feeds"| DP["Data Preprocessor (data_preprocessor.py)"]:::preprocess

    subgraph "Model Core Layer"
        DP -->|"processed"| TM["Transformer Architecture (transformer_model.py)"]:::transformer
        TM -->|"triggers"| TR["Training Pipeline (train_model.py)"]:::training
        TM -->|"inference"| PI["Prediction (predict.py)"]:::prediction
    end

    subgraph "Output & Evaluation"
        TR -->|"saves"| TMdl["Trained Models"]:::storage
        TR -->|"logs"| LG["Logs"]:::storage
        PI -->|"generates"| PR["Predictions"]:::storage
        PI -->|"evaluates"| EV["Ensemble Eval (evaluate_ensemble.py)"]:::evaluation
        EV -->|"outputs"| EVout["Evaluation Results"]:::storage
    end

    %% Click Events
    click DS "https://github.com/0xreisearch/hanabi-1/tree/main/example_data/"
    click DP "https://github.com/0xreisearch/hanabi-1/blob/main/data_preprocessor.py"
    click TM "https://github.com/0xreisearch/hanabi-1/blob/main/transformer_model.py"
    click TR "https://github.com/0xreisearch/hanabi-1/blob/main/train_model.py"
    click PI "https://github.com/0xreisearch/hanabi-1/blob/main/predict.py"
    click EV "https://github.com/0xreisearch/hanabi-1/blob/main/evaluate_ensemble.py"

    %% Styles
    classDef datasource fill:#f9c,stroke:#333,stroke-width:2px;
    classDef preprocess fill:#ff9,stroke:#333,stroke-width:2px;
    classDef transformer fill:#9f9,stroke:#333,stroke-width:2px;
    classDef training fill:#99f,stroke:#333,stroke-width:2px;
    classDef prediction fill:#f99,stroke:#333,stroke-width:2px;
    classDef evaluation fill:#fc9,stroke:#333,stroke-width:2px;
    classDef storage fill:#ccc,stroke:#333,stroke-width:2px;
```
