# google-deepmind/bsuite architecture

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

- Interactive diagram: https://gitdiagram.com/google-deepmind/bsuite
- Repository: https://github.com/google-deepmind/bsuite

## Overview

##### Project type and purpose
- This is an open-source Python library (“bsuite”) providing
a suite of reinforcement-learning benchmarks, automated logging,
baseline agent implementations, and analysis/report generation.
- Its goal is to let researchers plug in any RL agent, run a
standardized collection of experiments, record results in CSV
or SQLite, then analyze performance via Jupyter notebooks or
LaTeX reports.

##### File structure
- Top-level components:
- bsuite/ (core library package)
– __init__.py, _metadata.py, bsuite.py (API entrypoints)
– environments/ (DM-Env style environments + tests)
– experiments/ (experiment definitions: env config, sweeps, analysis)
– baselines/ (reference agents in JAX, TF, random, third-party; each with run scripts)
– logging/ (CSV, SQLite, terminal logging implementations + tests)
– utils/ (helpers: dataset loaders, gym_wrapper, plotting, wrappers)
– analysis/ (results Jupyter notebook)
– sweep.py (high-level CLI to run entire suite)
– tests/ (unit tests)
- reports/ (LaTeX templates and images for conference reports)
- run_on_gcp.sh (GCP orchestration script)
- setup.py (packaging)
- .github/workflows (CI/CD)
- CONTRIBUTING.md, LICENSE, README.md (project metadata)

##### README for additional insights
- Core API functions: load_from_id, load_and_record_to_csv/sqlite/terminal
- A plugin-style pattern: experiments define SETTINGS sweeps + analysis.py
- Baseline run scripts accept --bsuite_id flags and multi-process pooling
- Analysis notebook reads logged data & generates radar plots, tables
- Reporting tools produce TeX files for ICLR/ICML/NeurIPS appendices

##### Detail
- Sub-system, its entrypoints, and its outputs.
- Plugin interfaces (e.g., sweep.SWEEP constant → experiment sweep loop).
- Test modules as part of CI pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI / Orchestration
    subgraph "CLI / Orchestration" 
        direction TB
        SweepPy["sweep.py"]:::script
        RunGCP["run_on_gcp.sh"]:::script
        TestSh["test.sh"]:::script
    end

    %% Core API Layer
    subgraph "Core API Layer" 
        direction TB
        Init["__init__.py"]:::core
        Metadata["_metadata.py"]:::core
        BsuitePy["bsuite.py"]:::core
        SweepCore["sweep.py"]:::core
        SweepTest["sweep_test.py"]:::core
    end

    %% Experiment Definitions
    subgraph "Experiment Definitions" 
        direction TB
        ExpDir["bsuite/experiments/"]:::exp
        SumAnalysis["summary_analysis.py"]:::exp
        SumAnalysisTest["summary_analysis_test.py"]:::exp
    end

    %% Environments
    subgraph "Environments Implementation"
        direction TB
        EnvsDir["bsuite/environments/"]:::env
        EnvBase["base.py"]:::env
        EnvOthers["*.py"]:::env
    end

    %% Logging Subsystem
    subgraph "Logging Subsystem"
        direction TB
        LogDir["bsuite/logging/"]:::logging
        LogBase["base.py"]:::logging
        CsvLog["csv_logging.py"]:::logging
        SqliteLog["sqlite_logging.py"]:::logging
        TermLog["terminal_logging.py"]:::logging
        CsvLoad["csv_load.py"]:::logging
        SqlLoad["sqlite_load.py"]:::logging
    end

    %% Baseline Agents
    subgraph "Baseline Agents"
        direction TB
        BasDir["bsuite/baselines/"]:::baseline
        BasBase["base.py"]:::baseline
        BasExp["experiment.py"]:::baseline
        JaxDir["jax/"]:::baseline
        TfDir["tf/"]:::baseline
        RandomDir["random/"]:::baseline
        ThirdParty["third_party/"]:::baseline
        BasUtils["utils/"]:::baseline
    end

    %% Utility Modules
    subgraph "Utility Modules"
        direction TB
        UtilDir["bsuite/utils/"]:::util
        Datasets["datasets.py"]:::util
        GymWrap["gym_wrapper.py"]:::util
        Plotting["plotting.py"]:::util
        Smoothers["smoothers.py"]:::util
        Wrappers["wrappers.py"]:::util
    end

    %% Analysis & Reporting
    subgraph "Analysis & Reporting"
        direction TB
        Notebook["results.ipynb"]:::analysis
        ReportsDir["reports/"]:::analysis
    end

    %% Storage
    CSV["CSV Output"]:::storage
    SQLite["SQLite DB"]:::storage

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        direction TB
        CIci[".github/workflows/ci.yml"]:::ci
        CIrel[".github/workflows/release.yml"]:::ci
    end

    %% Packaging & Metadata
    subgraph "Packaging & Installation"
        direction TB
        Setup["setup.py"]:::pkg
        Readme["README.md"]:::pkg
        License["LICENSE"]:::pkg
        Contrib["CONTRIBUTING.md"]:::pkg
        Gitignore[".gitignore"]:::pkg
    end

    %% Relationships
    SweepPy -->|invokes| BsuitePy
    RunGCP -->|invokes| SweepCore
    TestSh -->|runs tests| SweepTest

    BsuitePy -->|loads| ExpDir
    BsuitePy -->|loads| EnvsDir

    ExpDir -->|defines| EnvOthers
    EnvBase -->|base interface| EnvsDir

    EnvsDir -->|emits steps| LogBase
    CsvLog -->|writes| CSV
    SqliteLog -->|writes| SQLite
    TermLog -->|writes| Terminal

    BasExp -->|uses| BsuitePy
    BasDir -->|implements| BasExp
    JaxDir --> BasDir
    TfDir --> BasDir
    RandomDir --> BasDir
    ThirdParty --> BasDir
    BasUtils -->|helpers| BasDir

    UtilDir -->|adapts| EnvsDir
    GymWrap -->|wraps| EnvsDir
    Plotting -->|visualizes| CSV
    Smoothers -->|processes| CSV
    Wrappers -->|wraps| EnvsDir

    CSV -->|loaded by| Notebook
    SQLite -->|loaded by| Notebook
    Notebook -->|generates| ReportsDir

    CIci -->|tests| Init
    CIci -->|tests| ExpDir
    CIci -->|tests| LogDir
    CIrel -->|publishes| Setup

    Setup -->|includes| Init
    Readme -->|docs| Setup
    License -->|contains| Setup
    Contrib -->|guides| Setup

    %% Click Events
    click Init "https://github.com/google-deepmind/bsuite/blob/main/bsuite/__init__.py"
    click Metadata "https://github.com/google-deepmind/bsuite/blob/main/bsuite/_metadata.py"
    click BsuitePy "https://github.com/google-deepmind/bsuite/blob/main/bsuite/bsuite.py"
    click SweepCore "https://github.com/google-deepmind/bsuite/blob/main/bsuite/sweep.py"
    click SweepTest "https://github.com/google-deepmind/bsuite/blob/main/bsuite/sweep_test.py"
    click ExpDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/experiments/"
    click SumAnalysis "https://github.com/google-deepmind/bsuite/blob/main/bsuite/experiments/summary_analysis.py"
    click SumAnalysisTest "https://github.com/google-deepmind/bsuite/blob/main/bsuite/experiments/summary_analysis_test.py"
    click EnvsDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/environments/"
    click EnvBase "https://github.com/google-deepmind/bsuite/blob/main/bsuite/environments/base.py"
    click LogDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/logging/"
    click LogBase "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/base.py"
    click CsvLog "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/csv_logging.py"
    click SqliteLog "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/sqlite_logging.py"
    click TermLog "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/terminal_logging.py"
    click CsvLoad "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/csv_load.py"
    click SqlLoad "https://github.com/google-deepmind/bsuite/blob/main/bsuite/logging/sqlite_load.py"
    click BasDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/"
    click BasBase "https://github.com/google-deepmind/bsuite/blob/main/bsuite/baselines/base.py"
    click BasExp "https://github.com/google-deepmind/bsuite/blob/main/bsuite/baselines/experiment.py"
    click JaxDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/jax/"
    click TfDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/tf/"
    click RandomDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/random/"
    click ThirdParty "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/third_party/"
    click BasUtils "https://github.com/google-deepmind/bsuite/tree/main/bsuite/baselines/utils/"
    click UtilDir "https://github.com/google-deepmind/bsuite/tree/main/bsuite/utils/"
    click Datasets "https://github.com/google-deepmind/bsuite/blob/main/bsuite/utils/datasets.py"
    click GymWrap "https://github.com/google-deepmind/bsuite/blob/main/bsuite/utils/gym_wrapper.py"
    click Plotting "https://github.com/google-deepmind/bsuite/blob/main/bsuite/utils/plotting.py"
    click Smoothers "https://github.com/google-deepmind/bsuite/blob/main/bsuite/utils/smoothers.py"
    click Wrappers "https://github.com/google-deepmind/bsuite/blob/main/bsuite/utils/wrappers.py"
    click Notebook "https://github.com/google-deepmind/bsuite/blob/main/bsuite/analysis/results.ipynb"
    click ReportsDir "https://github.com/google-deepmind/bsuite/tree/main/reports/"
    click CIci "https://github.com/google-deepmind/bsuite/blob/main/.github/workflows/ci.yml"
    click CIrel "https://github.com/google-deepmind/bsuite/blob/main/.github/workflows/release.yml"
    click Setup "https://github.com/google-deepmind/bsuite/blob/main/setup.py"
    click Readme "https://github.com/google-deepmind/bsuite/blob/main/README.md"
    click License "https://github.com/google-deepmind/bsuite/tree/main/LICENSE"
    click Contrib "https://github.com/google-deepmind/bsuite/blob/main/CONTRIBUTING.md"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef exp fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef env fill:#c8e6c9,stroke:#388e3c,color:#1b5e20;
    classDef logging fill:#fff9c4,stroke:#f9a825,color:#f57f17;
    classDef baseline fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef util fill:#b2ebf2,stroke:#0097a7,color:#006064;
    classDef analysis fill:#e1bee7,stroke:#8e24aa,color:#4a148c;
    classDef storage fill:#d7ccc8,stroke:#5d4037,color:#3e2723,shape:cylinder;
    classDef script fill:#eeeeee,stroke:#616161,color:#212121,shape:parallelogram;
    classDef ci fill:#e0e0e0,stroke:#757575,color:#212121;
    classDef pkg fill:#f5f5f5,stroke:#9e9e9e,color:#212121;
```
