# halsoo/robot-radio-station architecture

> Architecture diagram of the GitHub repository halsoo/robot-radio-station, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/halsoo/robot-radio-station
- Repository: https://github.com/halsoo/robot-radio-station

## Overview

##### Project Type and Purpose
- The project is an AI-based playlist generator, specifically named “Robot Radio Station.” Its primary function is to generate playlists using neural network models. This is evident from the readme and the file structure, which includes configurations for neural networks (nn_params), data-related configurations, and scripts for training and inference.

##### Analyzing the File Structure
- Key Directories:
- config: Contains YAML configuration files for data, neural network parameters, and wandb configurations. This indicates a strong emphasis on configurable experiments.
- rrs: This is the core module that holds the functionality for data utilities, model definitions (model_zoo, nn, sampling_util), training utilities (trainer, train_utils), and other support functions such as vocab and general utils. It encapsulates the core logic of the application.
- notebooks: For exploratory analysis, preprocessing, and experimentation – though the guidelines emphasize that only notebooks in “notebooks_local” should be run.
- Main Script Files:
- train.py and inference.py are the primary entry points for training the model and running inference, respectively.
- Several shell scripts (inference.sh, train_debug.sh, train_decoder_only.sh) suggest multiple entrypoints including debugging and specialized training configurations.
- Other Components:
- environment.yml provides essential dependency management.
- The project’s readme also mentions metadata (e.g., CSV files for train/valid/test segments) and outputs (for experiment checkpoints), even if not explicitly visible in the file tree.

##### Components and Relationships
- Main Components to Include:
a. Configuration Layer:
- “config” directory (data config, nn_params, wandb_config): Acts as the backbone for experiment configuration.
b. Core Application Module:
- “rrs” package: Contains core functionalities such as data handling (data_utils), neural network implementations (nn, model_zoo), training logic (trainer, train_utils), sampling, and vocabulary utilities.
c. Execution Scripts:
- Training Infrastructure: train.py and accompanying shell scripts for various training modes.
- Inference Infrastructure: inference.py and its shell wrapper (inference.sh).
d. Experimentation and Documentation:
- Jupyter Notebooks: Notebooks in both “notebooks” and “notebooks_local/” for exploratory data analysis, preprocessing (e.g., naive splitting, PDA experiments), and prototyping.
e. Environment & Dependencies Management:
- environment.yml to detail how the configured environment is set up.
f. External Integrations:
- WandB (Weights & Biases): Managed via wandb_config and the outputs directory (as per readme) for experiment tracking and checkpoint management.
- Relationships and Data Flows:
- The system starts with configurations loaded from the “config” files, which set parameters for data processing and neural network training.
- The “rrs” module consumes these configurations to handle data processing, model initialization, training workflows, and evaluation.
- The training process (initiated via train.py or related shell scripts) invokes “rrs/trainer.py” and its supporting utilities.
- Once a model is trained, inference.py uses a similar pipeline to perform predictions.
- Throughout these processes, WandB integration ensures experiment results, logs, and checkpoints are tracked.
- The notebooks provide a parallel channel for experimentation and analysis without affecting production code.

##### Architectural Patterns and Design Principles
- Modularity:
- Clear separation between configuration, core logic (rrs modules), training/inference scripts, and exploratory code (notebooks).
- Config-Driven Execution:
- The use of YAML configuration files indicates a design built for reproducibility and ease of experimentation.
- Experiment Tracking:
- Integration with WandB demonstrates an architecture crafted for iterative improvements and robust experiment management.

##### Wrapping Up
- Remember the collaboration rules noted in the README, particularly regarding who modifies notebooks and how changes propagate from experimental code into production code.

## Diagram (Mermaid)

```mermaid
flowchart TD

    subgraph "Configuration Layer"
        config1("config/config.yaml"):::config
        config2("config/data/smp_naive.yaml"):::config
        config3("config/data/smp_naive_debug.yaml"):::config
        config4("config/nn_params/decoder_only.yaml"):::config
        config5("config/wandb_config/default.yaml"):::config
    end

    subgraph "Core Application Module"
        rrs1("rrs/data_utils.py"):::core
        rrs2("rrs/model_zoo.py"):::core
        rrs3("rrs/nn.py"):::core
        rrs4("rrs/sampling_utils.py"):::core
        rrs5("rrs/train_utils.py"):::core
        rrs6("rrs/trainer.py"):::core
        rrs7("rrs/utils.py"):::core
        rrs8("rrs/vocab_utils.py"):::core
    end

    subgraph "Execution Scripts"
        exec1("train.py"):::exec
        exec2("inference.py"):::exec
        exec3("inference.sh"):::exec
        exec4("train_debug.sh"):::exec
        exec5("train_decoder_only.sh"):::exec
    end

    subgraph "Experimentation and Analysis"
        note1("notebooks/naive_split_and_preprocess.ipynb"):::notebook
        note2("notebooks/pda.ipynb"):::notebook
    end

    subgraph "Environment & Dependencies"
        env("environment.yml"):::env
    end

    %% Data flows from Configuration to Core Module
    config1 -->|"configures"| rrs1
    config2 -->|"data_settings"| rrs3
    config4 -->|"NN_parameters"| rrs3

    %% WandB configuration flows to Training Script
    config5 -->|"WandB_config"| exec1

    %% Core Module triggers training and inference
    rrs6 -->|"initiates"| exec1
    rrs6 -->|"supports_inference"| exec2

    %% Experimentation uses Core utilities
    note1 -->|"explores_data"| rrs1

    %% Environment management applies to Execution Scripts
    env -->|"dependencies"| exec1
    env -->|"dependencies"| exec2

    %% Click Events for Configuration Layer
    click config1 "https://github.com/halsoo/robot-radio-station/blob/main/config/config.yaml"
    click config2 "https://github.com/halsoo/robot-radio-station/blob/main/config/data/smp_naive.yaml"
    click config3 "https://github.com/halsoo/robot-radio-station/blob/main/config/data/smp_naive_debug.yaml"
    click config4 "https://github.com/halsoo/robot-radio-station/blob/main/config/nn_params/decoder_only.yaml"
    click config5 "https://github.com/halsoo/robot-radio-station/blob/main/config/wandb_config/default.yaml"

    %% Click Events for Core Application Module
    click rrs1 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/data_utils.py"
    click rrs2 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/model_zoo.py"
    click rrs3 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/nn.py"
    click rrs4 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/sampling_utils.py"
    click rrs5 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/train_utils.py"
    click rrs6 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/trainer.py"
    click rrs7 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/utils.py"
    click rrs8 "https://github.com/halsoo/robot-radio-station/blob/main/rrs/vocab_utils.py"

    %% Click Events for Execution Scripts
    click exec1 "https://github.com/halsoo/robot-radio-station/blob/main/train.py"
    click exec2 "https://github.com/halsoo/robot-radio-station/blob/main/inference.py"
    click exec3 "https://github.com/halsoo/robot-radio-station/blob/main/inference.sh"
    click exec4 "https://github.com/halsoo/robot-radio-station/blob/main/train_debug.sh"
    click exec5 "https://github.com/halsoo/robot-radio-station/blob/main/train_decoder_only.sh"

    %% Click Events for Experimentation and Analysis
    click note1 "https://github.com/halsoo/robot-radio-station/blob/main/notebooks/naive_split_and_preprocess.ipynb"
    click note2 "https://github.com/halsoo/robot-radio-station/blob/main/notebooks/pda.ipynb"

    %% Click Event for Environment File
    click env "https://github.com/halsoo/robot-radio-station/blob/main/environment.yml"

    %% Styles
    classDef config fill:#AEDFF7,stroke:#1F75FE,stroke-width:2px;
    classDef core fill:#C1F0C1,stroke:#008000,stroke-width:2px;
    classDef exec fill:#FFF2B2,stroke:#FFA500,stroke-width:2px;
    classDef notebook fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef env fill:#D3D3D3,stroke:#696969,stroke-width:2px;
```
