# saifh-github/conservative-bayesian-public architecture

> Architecture diagram of the GitHub repository saifh-github/conservative-bayesian-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saifh-github/conservative-bayesian-public
- Repository: https://github.com/saifh-github/conservative-bayesian-public

## Overview

##### Project Type & Purpose
- This is an experimental research codebase in Python, organized as a small “experiment pipeline” rather than a full‐stack web app.
- Its purpose is to run two main experiments (non-IID and tightness), simulate Bayesian agents interacting with environments, and produce the figures for the Bengio et al. (2024) paper.

##### File Structure
- Top-level scripts:
- run_non_iid_experiment.py / .sh
- run_tightness_experiment.py / .sh
- plotting drivers: make_non_iid_plots.py, make_tightness_plots.py, etc.
- Core modules:
- agents/ – defines Agent classes and the guardrails logic.
- envs/ – defines the environment interface and a specific “exploding_bandit” environment.
- utils/ – general helpers and plotting routines.
- Config & tooling:
- environment.yaml – conda dependencies (numpy, pytest, matplotlib, etc.)
- test_guardrails.py – unit tests for guardrail logic.

##### Extract Key Architectural Insights from README
- Two experiment entry points correspond directly to Figures 1 and 2.
- There is no external service; everything runs locally under the conda environment.
- Outputs are static plot files.

##### Main Components & Their Interactions
a. Entry-point Scripts
- run_non_iid_experiment.py
- run_tightness_experiment.py
→ These orchestrate experiments: instantiate environments and agents, loop simulation steps, collect results.
b. Agent Module (agents/)
- agents.py: base Agent classes (e.g., Bayesian Oracle)
- guardrails.py: logic to constrain or modify agent actions
c. Environment Module (envs/)
- exploding_bandit.py: environment dynamics, reward generation
- Experiment wrappers handle batching / non-IID/tightness parameters
d. Utilities (utils/)
- utils.py: data-collection, metrics
- plotting.py: figure creation, styling
e. Plot Scripts
- make_*.py: load experiment outputs, call utils.plotting to recreate manuscript figures
f. Test Suite
- test_guardrails.py: verify guardrail behavior in isolation

##### Architectural Patterns & Design Principles
- Modular separation by concern:
- Orchestration (scripts) vs. Domain logic (agents/envs) vs. Presentation (plotting).
- Clear dependency direction: scripts → core modules → utils
- Single Responsibility: each module does one thing (simulate, constrain, plot).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Orchestration Layer
    subgraph "Orchestration"
        direction TB
        RNIS("run_non_iid_experiment.sh"):::orchestration
        RNIP("run_non_iid_experiment.py"):::orchestration
        RTIS("run_tightness_experiment.sh"):::orchestration
        RTIP("run_tightness_experiment.py"):::orchestration
        MNIP("make_non_iid_plots.py"):::orchestration
        MTIP("make_tightness_plots.py"):::orchestration
        MTNIP("make_transposed_non_iid_plots.py"):::orchestration
    end

    %% Domain Logic Layer
    subgraph "Domain Logic"
        direction TB
        subgraph Agents
            AG("agents/agents.py"):::domain
            GR("agents/guardrails.py"):::domain
        end
        subgraph Environments
            EB("envs/exploding_bandit.py"):::domain
        end
    end

    %% Utilities Layer
    subgraph "Utilities"
        direction TB
        UT("utils/utils.py"):::utils
        UP("utils/plotting.py"):::utils
    end

    %% Output Layer
    FIG("Figure Files (PNG/PDF)"):::output

    %% QA & Config
    subgraph "QA & Config"
        direction TB
        ENV("environment.yaml"):::qa
        TST("test_guardrails.py"):::qa
    end

    %% Connections
    RNIS --> RNIP
    RTIS --> RTIP
    RNIP --> AG
    RNIP --> GR
    RNIP --> EB
    RTIP --> AG
    RTIP --> GR
    RTIP --> EB

    AG --> UT
    GR --> UT
    EB --> UT
    UT --> UP

    MNIP --> UP
    MTIP --> UP
    MTNIP --> UP

    UP --> FIG

    ENV -.-> RNIP
    ENV -.-> RTIP
    TST -.-> GR

    %% Click Events
    click RNIS "https://github.com/saifh-github/conservative-bayesian-public/blob/main/run_non_iid_experiment.sh"
    click RNIP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/run_non_iid_experiment.py"
    click RTIS "https://github.com/saifh-github/conservative-bayesian-public/blob/main/run_tightness_experiment.sh"
    click RTIP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/run_tightness_experiment.py"
    click MNIP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/make_non_iid_plots.py"
    click MTIP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/make_tightness_plots.py"
    click MTNIP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/make_transposed_non_iid_plots.py"
    click AG "https://github.com/saifh-github/conservative-bayesian-public/blob/main/agents/agents.py"
    click GR "https://github.com/saifh-github/conservative-bayesian-public/blob/main/agents/guardrails.py"
    click EB "https://github.com/saifh-github/conservative-bayesian-public/blob/main/envs/exploding_bandit.py"
    click UT "https://github.com/saifh-github/conservative-bayesian-public/blob/main/utils/utils.py"
    click UP "https://github.com/saifh-github/conservative-bayesian-public/blob/main/utils/plotting.py"
    click ENV "https://github.com/saifh-github/conservative-bayesian-public/blob/main/environment.yaml"
    click TST "https://github.com/saifh-github/conservative-bayesian-public/blob/main/test_guardrails.py"

    %% Styles
    classDef orchestration fill:#8ab6d6,stroke:#333,stroke-width:1px
    classDef domain fill:#a8d5ba,stroke:#333,stroke-width:1px
    classDef utils fill:#ffe699,stroke:#333,stroke-width:1px
    classDef output fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef qa fill:#f0f0f0,stroke:#333,stroke-width:1px
```
