# molecularai/reinvent architecture

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

- Interactive diagram: https://gitdiagram.com/molecularai/reinvent
- Repository: https://github.com/molecularai/reinvent

## Overview

##### Project Type and Purpose
- This is an open-source, Python-based command-line tool (REINVENT 3.2) for molecular generative modeling.
- It provides multiple “running modes” (reinforcement learning, curriculum learning, transfer learning, sampling, scoring, create_model, validation), each orchestrated by a runner.
- It leverages key patterns (Strategy, Factory/Builder, DTOs) to allow extensibility and configuration via JSON templates and a Conda environment.

##### File Structure Analysis
- Top level:
- input.py – entry point parsing JSON and invoking the manager
- manager.py – coordinates loading of config and dispatch to the correct constructor
- configs/ – holds example and user configuration JSONs
- running_modes/ – core domain modules, each subfolder implements one mode
- constructors/ – Factory classes that, given a running mode name, build the correct runner + dependencies
- utils/ – shared utilities (configuration parsing, generic helpers)
- main_test.py + unittest_reinvent/ – test harness, fixtures, unit tests
- running_modes/<mode> structure:
- actions/ – low-level steps (sample, train, evaluate)
- learning_strategy/, production_strategy/, scoring_strategy/, curriculum_strategy/ – Strategy pattern implementations
- dto/ – data transfer objects carrying results between components
- logging/ – infrastructure for local/remote/TensorBoard logging
- core_<mode>.py or <mode>.py – central orchestration for that mode

##### README Insights
- Configuration-driven: user provides a JSON file, invoked as “python input.py my_mode.json”.
- Outputs logs to file system and TensorBoard.
- Requires CUDA GPU and optional OpenEye license for certain scoring modes.
- Tests exercise each mode by instantiating runners via config JSON.

a. Main Components
- CLI Layer: input.py
- Configuration Loader: manager.py + utils/configuration.py
- Constructor Layer: constructors/*_mode_constructor.py
- Runner Layer: running_modes/<mode>/… – orchestrates mode logic
- Sub-modules within each mode:
– Actions (sample, train, evaluate)
– Strategies (learning, production, scoring, curriculum)
– DTOs (payload objects between actions/strategies)
– Logging (console, local files, remote/TensorBoard)
- External Services/Libs:
– CUDA/GPU
– TensorBoard
– OpenEye (optional)
– lib_invent C++ backend, link_invent binding
b. Interactions
- User invokes CLI → Configuration Loader reads JSON → Manager picks correct Constructor → Constructor instantiates Runner with configured strategies, actions, loggers → Runner executes sequence of actions via strategies, passing DTOs → Loggers capture metrics and write to local fs / TensorBoard / remote endpoint.
c. Architectural Patterns
- Strategy pattern for learning, production, scoring, curriculum
- Factory/Builder pattern in constructors for decoupled instantiation
- DTOs for decoupling data exchange
- Layered architecture (Presentation → Configuration → Orchestration → Domain → Infrastructure)
d. Key Technologies and Frameworks
- Python 3.7, Conda environment (reinvent.yml)
- GPU/CUDA
- TensorBoard
- Optional OpenEye license for proprietary scoring
- C++ backends (lib_invent, link_invent)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["input.py"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        Manager["manager.py"]:::config
        ConfigUtil["configuration.py"]:::config
        ConfigExamples["configs/*.json"]:::config
    end

    %% Constructor Layer
    subgraph "Constructor Layer"
        direction TB
        BaseRunningModeCtor["base_running_mode.py"]:::constructors
        RunningModeCtor["running_mode.py"]:::constructors
        CreateModelCtor["create_model_mode_constructor.py"]:::constructors
        RLModeCtor["reinforcement_learning_mode_constructor.py"]:::constructors
        CurriculumCtor["curriculum_learning_mode_constructor.py"]:::constructors
        AutoCurriculumCtor["automated_curriculum_learning_mode_constructor.py"]:::constructors
        SamplingCtor["sampling_mode_constructor.py"]:::constructors
        ScoringCtor["scoring_mode_constructor.py"]:::constructors
        TransferCtor["transfer_learning_mode_constructor.py"]:::constructors
        ValidationCtor["validation_mode_constructor.py"]:::constructors
    end

    %% Runner Layer
    subgraph "Runner Layer"
        direction TB
        RLCore["core_reinforcement_learning.py"]:::domain
        CurriculumRunner["curriculum_runner.py"]:::domain
        AutoCurriculumRunner["automated_curriculum_runner.py"]:::domain
        SamplingRunner["sample_from_model.py"]:::domain
        ScoringRunner["scoring_runner.py"]:::domain
        CreateModelRunner["create_model.py"]:::domain
        TransferRunner["transfer_learning_runner.py"]:::domain
        LinkInventTransferRunner["link_invent_transfer_learning_runner.py"]:::domain
        ValidationRunner["validation_runner.py"]:::domain
    end

    %% Sub-modules
    subgraph "Domain Sub-modules"
        direction TB
        Actions["actions/"]:::domain
        Strategies["learning_strategy/, production_strategy/, curriculum_strategy/"]:::domain
        DTOs["dto/"]:::domain
        Logging["logging/"]:::infra
    end

    %% Infrastructure / External
    subgraph "Infrastructure & External"
        direction TB
        TensorBoard["TensorBoard"]:::external
        GPU["CUDA/GPU"]:::external
        OpenEye["OpenEye"]:::external
        LibInvent["lib_invent / link_invent"]:::external
    end

    %% Shared
    subgraph "Shared Utilities & Enums"
        direction TB
        GeneralUtil["general.py"]:::config
        RunningModeEnum["running_mode_enum.py"]:::config
        LearningStrategyEnum["learning_strategy_enum.py"]:::config
        ProductionStrategyEnum["production_strategy_enum.py"]:::config
        ScoringRunnerEnum["scoring_runner_enum.py"]:::config
    end

    %% Test Harness
    subgraph "Tests"
        direction TB
        MainTest["main_test.py"]:::config
        UnitTests["unittest_reinvent/"]:::config
    end

    %% Connections
    CLI -->|"JSON config"| Manager
    Manager -->|"loads JSON"| ConfigUtil
    Manager -->|"selects"| BaseRunningModeCtor
    BaseRunningModeCtor --> RunningModeCtor
    RunningModeCtor --> CreateModelCtor
    RunningModeCtor --> RLModeCtor
    RunningModeCtor --> CurriculumCtor
    RunningModeCtor --> AutoCurriculumCtor
    RunningModeCtor --> SamplingCtor
    RunningModeCtor --> ScoringCtor
    RunningModeCtor --> TransferCtor
    RunningModeCtor --> ValidationCtor

    CreateModelCtor --> CreateModelRunner
    RLModeCtor --> RLCore
    CurriculumCtor --> CurriculumRunner
    AutoCurriculumCtor --> AutoCurriculumRunner
    SamplingCtor --> SamplingRunner
    ScoringCtor --> ScoringRunner
    TransferCtor --> TransferRunner
    TransferRunner --> LinkInventTransferRunner
    ValidationCtor --> ValidationRunner

    %% Runner to sub-modules
    RLCore --> Actions
    RLCore --> Strategies
    RLCore --> DTOs
    RLCore --> Logging

    CurriculumRunner --> Actions
    CurriculumRunner --> Strategies
    CurriculumRunner --> DTOs
    CurriculumRunner --> Logging

    AutoCurriculumRunner --> Actions
    AutoCurriculumRunner --> Strategies
    AutoCurriculumRunner --> DTOs
    AutoCurriculumRunner --> Logging

    SamplingRunner --> Actions
    SamplingRunner --> DTOs
    SamplingRunner --> Logging

    ScoringRunner --> Strategies
    ScoringRunner --> DTOs
    ScoringRunner --> Logging

    CreateModelRunner --> DTOs
    CreateModelRunner --> Logging

    TransferRunner --> Actions
    TransferRunner --> Strategies
    TransferRunner --> DTOs
    TransferRunner --> Logging

    ValidationRunner --> DTOs
    ValidationRunner --> Logging

    %% Logging to external infra
    Logging -->|"metrics"| TensorBoard
    Logging -->|"logs"| GPU
    Logging -->|"license checks"| OpenEye
    TransferRunner -->|"calls C++"| LibInvent

    %% Shared utilities usage
    Manager --> GeneralUtil
    RLCore --> RunningModeEnum
    RLCore --> LearningStrategyEnum
    RLCore --> ProductionStrategyEnum
    ScoringRunner --> ScoringRunnerEnum

    %% Tests
    MainTest --> CreateModelCtor
    MainTest --> RLModeCtor
    MainTest --> CurriculumCtor
    UnitTests --> MainTest

    %% Click Events
    click CLI "https://github.com/molecularai/reinvent/blob/master/input.py"
    click Manager "https://github.com/molecularai/reinvent/blob/master/manager.py"
    click ConfigUtil "https://github.com/molecularai/reinvent/blob/master/running_modes/utils/configuration.py"
    click CreateModelCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/create_model_mode_constructor.py"
    click RLModeCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/reinforcement_learning_mode_constructor.py"
    click CurriculumCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/curriculum_learning_mode_constructor.py"
    click AutoCurriculumCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/automated_curriculum_learning_mode_constructor.py"
    click SamplingCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/sampling_mode_constructor.py"
    click ScoringCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/scoring_mode_constructor.py"
    click TransferCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/transfer_learning_mode_constructor.py"
    click ValidationCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/validation_mode_constructor.py"
    click BaseRunningModeCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/base_running_mode.py"
    click RunningModeCtor "https://github.com/molecularai/reinvent/blob/master/running_modes/constructors/running_mode.py"
    click RLCore "https://github.com/molecularai/reinvent/blob/master/running_modes/reinforcement_learning/core_reinforcement_learning.py"
    click CurriculumRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/curriculum_learning/curriculum_runner.py"
    click AutoCurriculumRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/automated_curriculum_learning/automated_curriculum_runner.py"
    click SamplingRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/sampling/sample_from_model.py"
    click ScoringRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/scoring/scoring_runner.py"
    click CreateModelRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/create_model/create_model.py"
    click TransferRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/transfer_learning/transfer_learning_runner.py"
    click LinkInventTransferRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/transfer_learning/link_invent_transfer_learning_runner.py"
    click ValidationRunner "https://github.com/molecularai/reinvent/blob/master/running_modes/validation/validation_runner.py"
    click GeneralUtil "https://github.com/molecularai/reinvent/blob/master/running_modes/utils/general.py"
    click RunningModeEnum "https://github.com/molecularai/reinvent/blob/master/running_modes/enums/running_mode_enum.py"
    click LearningStrategyEnum "https://github.com/molecularai/reinvent/blob/master/running_modes/enums/learning_strategy_enum.py"
    click ProductionStrategyEnum "https://github.com/molecularai/reinvent/blob/master/running_modes/enums/production_strategy_enum.py"
    click ScoringRunnerEnum "https://github.com/molecularai/reinvent/blob/master/running_modes/enums/scoring_runner_enum.py"
    click Actions "https://github.com/molecularai/reinvent/tree/master/running_modes/reinforcement_learning/actions/"
    click Strategies "https://github.com/molecularai/reinvent/tree/master/running_modes/reinforcement_learning/learning_strategy/"
    click DTOs "https://github.com/molecularai/reinvent/tree/master/running_modes/reinforcement_learning/dto/"
    click Logging "https://github.com/molecularai/reinvent/tree/master/running_modes/reinforcement_learning/logging/"
    click MainTest "https://github.com/molecularai/reinvent/blob/master/main_test.py"
    click UnitTests "https://github.com/molecularai/reinvent/tree/master/unittest_reinvent/"

    %% Styles
    classDef cli fill:#D7BDE2,stroke:#884EA0,color:#1C2833;
    classDef config fill:#85C1E9,stroke:#21618C,color:#1C2833;
    classDef constructors fill:#82E0AA,stroke:#27AE60,color:#1C2833;
    classDef domain fill:#F5B041,stroke:#B9770E,color:#1C2833;
    classDef infra fill:#D5DBDB,stroke:#85929E,color:#1C2833;
    classDef external fill:#BB8FCE,stroke:#7D3C98,color:#1C2833;
```
