# hubbs5/or-gym architecture

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

- Interactive diagram: https://gitdiagram.com/hubbs5/or-gym
- Repository: https://github.com/hubbs5/or-gym

## Overview

##### Project type and purpose
- This is a Python library (“or-gym”) providing a suite of Operations-Research–style environments that implement the OpenAI Gym API.
- It’s intended for researchers and practitioners to train and benchmark RL agents on classic OR problems (knapsack, bin-packing, newsvendor, VRP, supply-chain, portfolio optimization, etc.).

##### File structure
- Top-level:
· .github/workflows/run_env_test.yml → CI that runs tests and environment validation
· setup.py, pyproject.toml → packaging and dependency metadata
· LICENSE, README.md → project documentation
· examples/ → Jupyter notebooks and Python scripts demonstrating use with Gym and RLlib (Ray)
· or_gym/ → core library package
· tests/ → pytest-compatible test suite (env_test.py, rllib_test.py)
- or_gym substructure:
· envs/ → environment modules organized into `classic_or`, `finance`, and `supply_chain` subpackages
· registry.py → central registry of all env IDs to class mappings
· utils.py, version.py → supporting utilities and version information

##### README for additional insights
- Confirms dependencies: Python 3.5+, OpenAI Gym API, Ray RLlib for examples
- Lists all provided env IDs
- Describes quickstart and benchmarking usage (refers to examples folder)

a. Main components
- Core Library (“or_gym” package)
- Env modules (classic_or, finance, supply_chain)
- Registry (env ID ↔ Env class)
- Utilities (common helper functions)
- External APIs & Dependencies
- OpenAI Gym (Env interface)
- Ray RLlib (for example training pipelines)
- Standard Python libs (numpy, scipy, etc.)
- User-facing Examples
- Jupyter notebooks
- Python scripts demonstrating agent training and benchmarking
- Packaging & CI/CD
- setup.py/pyproject.toml → PyPI packaging
- GitHub Actions → test suite, environment validation

b. Relationships and interactions
1. User or example script imports `or_gym` → calls `gym.make("Knapsack-v0")`
2. Registry translates ID → Env class in envs/*
3. Env step/​reset uses OR/​simulation logic (classic_or, finance, etc.)
4. Agent (e.g., RLlib trainer) interacts via Gym API (step, reset)
5. Results logged/​benchmarked in notebook
6. Tests exercise environments directly and via RLlib integration
7. CI workflow triggers tests on push/PR

c. Architectural patterns and design principles
- Plugin-style registry: new envs simply register themselves
- Separation of concerns:
- env modules only contain problem logic
- registry centralizes ID management
- utils for cross-cutting concerns
- Examples and tests are decoupled from core logic

d. Key technologies
- Python 3.5+
- OpenAI Gym API
- Ray RLlib (in examples)
- pytest (tests)
- GitHub Actions (CI)

##### Final recommendations
- You capture all env categories (classic_or vs finance vs supply_chain) as separate sub-components

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        GymAPI["OpenAI Gym\nAPI"]:::external
        RLlib["Ray RLlib"]:::external
        PyLibs["Standard Python Libs\n(numpy, scipy, etc.)"]:::external
    end

    %% Core Library
    subgraph "Core Library" 
        direction TB
        CorePkg["or_gym/"]:::code
        Registry["registry.py"]:::code
        Utils["utils.py"]:::code
        Version["version.py"]:::code

        subgraph "Env Modules"
            direction TB
            subgraph "Classic OR"
                direction TB
                BP["binpacking.py"]:::code
                KS["knapsack.py"]:::code
                NV["newsvendor.py"]:::code
                TSP["tsp.py"]:::code
                VRP["vehicle_routing.py"]:::code
                VMP["vmpacking.py"]:::code
            end
            subgraph "Finance"
                direction TB
                PF["portfolio_opt.py"]:::code
            end
            subgraph "Supply Chain"
                direction TB
                IM["inventory_management.py"]:::code
                NM["network_management.py"]:::code
            end
        end
    end

    %% Examples
    subgraph "Examples (Demos & Notebooks)"
        direction TB
        Ex1["ray_rllib_knapsack.py"]:::examples
        Ex2["ray_rllib_taxi_demo.py"]:::examples
        Ex3["how-to-use-rl-to-improve-your-supply-chain.ipynb"]:::examples
        Ex4["inv-management-quickstart.ipynb"]:::examples
        Ex5["rllib-validate-env.py"]:::examples
        Ex6["ray_tests.py"]:::examples
        Ex7["tf_orgym_examples.ipynb"]:::examples
    end

    %% Tests
    subgraph "Tests"
        direction TB
        EnvTest["env_test.py"]:::code
        RLlibTest["rllib_test.py"]:::code
    end

    %% Packaging & CI/CD
    subgraph "Packaging & CI/CD"
        direction TB
        Setup["setup.py"]:::code
        PyProject["pyproject.toml"]:::code
        License["LICENSE"]:::code
        Readme["README.md"]:::code
        CI["run_env_test.yml"]:::ci
    end

    %% Connections
    Ex1 -->|imports & calls gym.make| GymAPI
    Ex2 -->|imports & calls gym.make| GymAPI
    Ex3 -->|imports or_gym & RLlib| RLlib
    Ex4 -->|imports & calls gym.make| GymAPI
    Ex5 -->|validates environments| GymAPI
    Ex6 -->|tests examples| GymAPI
    Ex7 -->|demos with TensorFlow| GymAPI

    GymAPI -->|lookup env ID| Registry
    Registry -->|"instantiates"| BP & KS & NV & TSP & VRP & VMP & PF & IM & NM
    BP & KS & NV & TSP & VRP & VMP & PF & IM & NM -->|step/reset calls| GymAPI

    RLlib -->|trainer interacts via| GymAPI

    EnvTest -->|tests core library| CorePkg
    RLlibTest -->|tests RLlib integration| RLlib

    CI -->|runs| EnvTest
    CI -->|runs| RLlibTest

    Setup -->|packages| CorePkg
    PyProject -->|metadata| CorePkg
    License -->|accompanies| CorePkg
    Readme -->|documents| CorePkg

    %% Click Events
    click CorePkg "https://github.com/hubbs5/or-gym/tree/master/or_gym/"
    click BP "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/binpacking.py"
    click KS "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/knapsack.py"
    click NV "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/newsvendor.py"
    click TSP "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/tsp.py"
    click VRP "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/vehicle_routing.py"
    click VMP "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/classic_or/vmpacking.py"
    click PF "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/finance/portfolio_opt.py"
    click IM "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/supply_chain/inventory_management.py"
    click NM "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/supply_chain/network_management.py"
    click Registry "https://github.com/hubbs5/or-gym/blob/master/or_gym/envs/registry.py"
    click Utils "https://github.com/hubbs5/or-gym/blob/master/or_gym/utils.py"
    click Version "https://github.com/hubbs5/or-gym/blob/master/or_gym/version.py"
    click Ex1 "https://github.com/hubbs5/or-gym/blob/master/examples/ray_rllib_knapsack.py"
    click Ex2 "https://github.com/hubbs5/or-gym/blob/master/examples/ray_rllib_taxi_demo.py"
    click Ex3 "https://github.com/hubbs5/or-gym/blob/master/examples/how-to-use-rl-to-improve-your-supply-chain.ipynb"
    click Ex4 "https://github.com/hubbs5/or-gym/blob/master/examples/inv-management-quickstart.ipynb"
    click Ex5 "https://github.com/hubbs5/or-gym/blob/master/examples/rllib-validate-env.py"
    click Ex6 "https://github.com/hubbs5/or-gym/blob/master/examples/ray_tests.py"
    click Ex7 "https://github.com/hubbs5/or-gym/blob/master/examples/tf_orgym_examples.ipynb"
    click EnvTest "https://github.com/hubbs5/or-gym/blob/master/tests/env_test.py"
    click RLlibTest "https://github.com/hubbs5/or-gym/blob/master/tests/rllib_test.py"
    click CI "https://github.com/hubbs5/or-gym/blob/master/.github/workflows/run_env_test.yml"
    click Setup "https://github.com/hubbs5/or-gym/blob/master/setup.py"
    click PyProject "https://github.com/hubbs5/or-gym/blob/master/pyproject.toml"
    click License "https://github.com/hubbs5/or-gym/tree/master/LICENSE"
    click Readme "https://github.com/hubbs5/or-gym/blob/master/README.md"

    %% Styles
    classDef code fill:#E0F7FA,stroke:#00796B,stroke-width:1px
    classDef external fill:#C8E6C9,stroke:#256029,stroke-width:1px
    classDef examples fill:#FFF9C4,stroke:#F57F17,stroke-width:1px
    classDef ci fill:#ECEFF1,stroke:#607D8B,stroke-width:1px
```
