# molecularai/reinvent4 architecture

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

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

## Overview

##### Project type and purpose
- REINVENT is a full‑stack, command‑line molecular design tool built in Python.
- Its core purpose is to generate small molecules using Reinforcement Learning (RL) or Transfer Learning (TL), scoring them against user‑defined property profiles, and outputting optimized compounds.

##### File structure
- Top‑level CLI entrypoint: `reinvent/__main__.py` and `reinvent/Reinvent.py` expose the `reinvent` command.
- Configuration directory: `configs/toml` and `configs/json` contain sample TOML/JSON runmode configurations.
- Core modules under `reinvent/`:
- `runmodes/` orchestrates the high‑level workflows (RL, TL, sampling, scoring).
- `datapipeline/` handles data cleaning, normalization, tokenization.
- `models/` implements multiple model families (RNN, Transformer) and a factory for instantiation.
- `scoring/` implements the multi‑component scoring plugin system.
- `chemistry/` handles molecule standardization, conversions, and library design.
- `utils/` and `support/` for CLI helpers, config parsing, and external script wrappers.
- Plugins: `reinvent_plugins/` and `contrib/reinvent_plugins/` demonstrate the native‑package scoring plugin system.
- Tests and notebooks cover unit, integration tests and tutorials.

##### README for additional insights
- The workflow is driven via `reinvent sampling|scoring|TL|RL` commands plus a TOML/JSON config.
- GPU/CPU is selected via environment (PyTorch backend).
- Plugins are auto‑discovered under any `reinvent_plugins/components` folder in PYTHONPATH.

a. Main components:
1. CLI & Config Parser
2. Runmode Orchestrator (RL, TL, Sampling, Scoring managers)
3. Model Factory & Model Sampler (RNN/Transformer families)
4. Data Pipeline (filters, normalizers, tokenizers)
5. Chemistry Module (standardizers, library design)
6. Scoring Engine (core + plugin components)
7. Plugin Registry (native‑package loader)
8. Reporting (TensorBoard, CSV, remote)
9. FileSystem / Priors / Config / Logs
10. External Executors (dockers, subprocesses for docking, QSAR, etc.)

b. Relationships & data flow:
- User invokes CLI → Config Parser reads TOML/JSON → Runmode Orchestrator.
- Orchestrator uses Model Factory to load a Prior or Agent model → Data Pipeline converts molecules to tokens.
- Model Sampler proposes new SMILES → Chemistry Module standardizes molecules.
- Scoring Engine computes component scores (invoking plugins in Plugin Registry, external programs, or internal transforms).
- Runmode RL: uses scores to compute reward and update model weights (via PyTorch).
- Runmode TL: fine‑tunes model on provided dataset via Data Pipeline and Model Trainer.
- Results & metrics stream to Reporting subsystem, files on disk, and optionally remote endpoints.
- Priors and pre‑trained models loaded from `priors/`.

c. Architectural patterns & design principles:
- Modular plugin architecture: scoring components auto‑registered using namespace packages.
- Factory pattern: `models/model_factory` to abstract model instantiation.
- Pipeline abstraction: data cleaning and scoring broken into filter/transform chains.
- Separation of concerns: chemistry, modeling, scoring, orchestrator, and I/O live in distinct packages.
- CLI‑driven entrypoint decoupled from core logic.

d. Key technologies & frameworks:
- Python 3.10+
- PyTorch (GPU/CPU) for model definitions and training loops.
- TOML/JSON for configuration.
- RDKit/OpenEye in chemistry and scoring plugins.
- pytest for test suites.
- Jupytext/Jupyter for notebooks.

##### Detailed capture of architecture
- Don’t omit the Plugin Registry: show how it dynamically imports scoring components.
- Model Factory branching by model type and associated vocabulary/dataset modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Config Parser
    subgraph "CLI & Config Parser"
        CLI_Main["reinvent/__main__.py"]:::core
        CLI_Reinvent["reinvent/Reinvent.py"]:::core
        CLI_CLI["reinvent/utils/cli.py"]:::core
        CLI_Config["reinvent/utils/config_parse.py"]:::core
    end

    %% Runmode Orchestrator
    subgraph "Runmode Orchestrator"
        Handler["handler.py"]:::core
        Adapter["create_adapter.py"]:::core
        ModelAdapter["create_model/"]:::core
        RL_Mode["RL/"]:::core
        TL_Mode["TL/"]:::core
        Samplers_Mode["samplers/"]:::core
        Scoring_Mode["scoring/"]:::core
    end

    %% Model Factory & Sampler
    subgraph "Model Factory & Sampler"
        Factory["reinvent/models/model_factory/"]:::model
        subgraph "Samplers"
            SM_Reinvent["reinvent/runmodes/samplers/reinvent.py"]:::model
            SM_Linkinvent["reinvent/runmodes/samplers/linkinvent.py"]:::model
            SM_Mol2mol["reinvent/runmodes/samplers/mol2mol.py"]:::model
            SM_Libinvent["reinvent/runmodes/samplers/libinvent.py"]:::model
            SM_Pepinvent["reinvent/runmodes/samplers/pepinvent.py"]:::model
        end
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        DP_Core["reinvent/datapipeline/"]:::data
        DP_Filters["reinvent/datapipeline/filters/"]:::data
        DP_Normalizer["reinvent/datapipeline/normalizer/"]:::data
        DP_Preprocess["reinvent/datapipeline/preprocess.py"]:::data
        DP_Tokens["reinvent/datapipeline/tokens.py"]:::data
        DP_Validation["reinvent/datapipeline/validation.py"]:::data
    end

    %% Chemistry Module
    subgraph "Chemistry Module"
        Chem_Core["reinvent/chemistry/"]:::data
        Chem_Conv["reinvent/chemistry/conversions.py"]:::data
        Chem_Std["reinvent/chemistry/standardization/"]:::data
        Chem_Lib["reinvent/chemistry/library_design/"]:::data
    end

    %% Scoring Engine & Plugin Registry
    subgraph "Scoring Engine"
        Scoring_Core["reinvent/scoring/"]:::scoring
        Score_Compute["reinvent/scoring/compute_scores.py"]:::scoring
        Score_Scorer["reinvent/scoring/scorer.py"]:::scoring
        Score_Trans["reinvent/scoring/transforms/"]:::scoring
        Score_Agg["reinvent/scoring/aggregators/"]:::scoring
        Importer["reinvent/scoring/importer.py"]:::scoring
    end

    subgraph "Plugin Registry"
        Plugins_Native["reinvent_plugins/components/"]:::plugin
        Plugins_Contrib["contrib/reinvent_plugins/components/"]:::plugin
    end

    %% Reporting
    subgraph "Reporting"
        Report_RL["reinvent/runmodes/RL/reports/"]:::io
        Report_TL["reinvent/runmodes/TL/reports/"]:::io
        Report_Samp["reinvent/runmodes/samplers/reports/"]:::io
        LogMon["reinvent/utils/logmon.py"]:::io
    end

    %% FileSystem / Priors / Config / Logs
    subgraph "I/O & Config"
        Config_JSON["configs/json/"]:::io
        Config_TOML["configs/toml/"]:::io
        Priors["priors/"]:::io
        Logs["pytest.ini"]:::io
    end

    %% External Executors
    External["support/"]:::external

    %% Flow connections
    CLI_Main --> CLI_Config
    CLI_Reinvent --> CLI_CLI
    CLI_CLI --> Handler
    CLI_Config --> Handler
    Handler --> Adapter
    Adapter --> ModelAdapter
    Adapter --> RL_Mode
    Adapter --> TL_Mode
    Adapter --> Samplers_Mode
    Adapter --> Scoring_Mode

    %% Data pipeline and model
    Adapter --> DP_Preprocess
    DP_Preprocess --> DP_Tokens
    DP_Tokens --> DP_Filters
    DP_Filters --> DP_Normalizer
    DP_Normalizer --> DP_Validation
    DP_Validation --> Factory

    %% Model sampler branch
    Factory --> SM_Reinvent
    Factory --> SM_Linkinvent
    Factory --> SM_Mol2mol
    Factory --> SM_Libinvent
    Factory --> SM_Pepinvent
    SM_Reinvent --> Chem_Core
    SM_Linkinvent --> Chem_Conv
    SM_Mol2mol --> Chem_Std
    SM_Libinvent --> Chem_Lib
    SM_Pepinvent --> Chem_Core

    %% Chemistry to scoring
    Chem_Core --> Score_Compute
    Chem_Conv --> Score_Scorer
    Chem_Std --> Score_Trans
    Chem_Lib --> Score_Agg

    %% Scoring and plugins
    Score_Compute --> Importer
    Importer --> Plugins_Native
    Importer --> Plugins_Contrib

    %% External executors into scoring
    External --> Score_Compute
    External --> Score_Scorer

    %% Reporting and I/O
    RL_Mode --> Report_RL
    TL_Mode --> Report_TL
    Samplers_Mode --> Report_Samp
    Report_RL --> Logs
    Report_TL --> Logs
    Report_Samp --> Logs
    Handler --> Config_JSON
    Handler --> Config_TOML
    Factory --> Priors

    %% Styles
    classDef core fill:#bbe1fa,stroke:#3282b8,color:#0f4c75
    classDef data fill:#d3f8e2,stroke:#38b000,color:#1b4332
    classDef model fill:#ffcbf2,stroke:#c9184a,color:#6a040f
    classDef scoring fill:#e0c3fc,stroke:#5a189a,color:#3c096c
    classDef plugin fill:#fcd5ce,stroke:#9d4edd,color:#590d22
    classDef io fill:#eeeeee,stroke:#adb5bd,color:#495057
    classDef external fill:#fff3bf,stroke:#f08a5d,color:#9b2226

    %% Click events
    click CLI_Main "https://github.com/molecularai/reinvent4/blob/main/reinvent/__main__.py"
    click CLI_Reinvent "https://github.com/molecularai/reinvent4/blob/main/reinvent/Reinvent.py"
    click CLI_CLI "https://github.com/molecularai/reinvent4/blob/main/reinvent/utils/cli.py"
    click CLI_Config "https://github.com/molecularai/reinvent4/blob/main/reinvent/utils/config_parse.py"
    click Handler "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/handler.py"
    click Adapter "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/create_adapter.py"
    click ModelAdapter "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/create_model/"
    click RL_Mode "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/RL/"
    click TL_Mode "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/TL/"
    click Samplers_Mode "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/samplers/"
    click Scoring_Mode "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/scoring/"
    click Factory "https://github.com/molecularai/reinvent4/tree/main/reinvent/models/model_factory/"
    click SM_Reinvent "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/samplers/reinvent.py"
    click SM_Linkinvent "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/samplers/linkinvent.py"
    click SM_Mol2mol "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/samplers/mol2mol.py"
    click SM_Libinvent "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/samplers/libinvent.py"
    click SM_Pepinvent "https://github.com/molecularai/reinvent4/blob/main/reinvent/runmodes/samplers/pepinvent.py"
    click DP_Core "https://github.com/molecularai/reinvent4/tree/main/reinvent/datapipeline/"
    click DP_Filters "https://github.com/molecularai/reinvent4/tree/main/reinvent/datapipeline/filters/"
    click DP_Normalizer "https://github.com/molecularai/reinvent4/tree/main/reinvent/datapipeline/normalizer/"
    click DP_Preprocess "https://github.com/molecularai/reinvent4/blob/main/reinvent/datapipeline/preprocess.py"
    click DP_Tokens "https://github.com/molecularai/reinvent4/blob/main/reinvent/datapipeline/tokens.py"
    click DP_Validation "https://github.com/molecularai/reinvent4/blob/main/reinvent/datapipeline/validation.py"
    click Chem_Core "https://github.com/molecularai/reinvent4/tree/main/reinvent/chemistry/"
    click Chem_Conv "https://github.com/molecularai/reinvent4/blob/main/reinvent/chemistry/conversions.py"
    click Chem_Std "https://github.com/molecularai/reinvent4/tree/main/reinvent/chemistry/standardization/"
    click Chem_Lib "https://github.com/molecularai/reinvent4/tree/main/reinvent/chemistry/library_design/"
    click Scoring_Core "https://github.com/molecularai/reinvent4/tree/main/reinvent/scoring/"
    click Score_Compute "https://github.com/molecularai/reinvent4/blob/main/reinvent/scoring/compute_scores.py"
    click Score_Scorer "https://github.com/molecularai/reinvent4/blob/main/reinvent/scoring/scorer.py"
    click Score_Trans "https://github.com/molecularai/reinvent4/tree/main/reinvent/scoring/transforms/"
    click Score_Agg "https://github.com/molecularai/reinvent4/tree/main/reinvent/scoring/aggregators/"
    click Importer "https://github.com/molecularai/reinvent4/blob/main/reinvent/scoring/importer.py"
    click Plugins_Native "https://github.com/molecularai/reinvent4/tree/main/reinvent_plugins/components/"
    click Plugins_Contrib "https://github.com/molecularai/reinvent4/tree/main/contrib/reinvent_plugins/components/"
    click Report_RL "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/RL/reports/"
    click Report_TL "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/TL/reports/"
    click Report_Samp "https://github.com/molecularai/reinvent4/tree/main/reinvent/runmodes/samplers/reports/"
    click LogMon "https://github.com/molecularai/reinvent4/blob/main/reinvent/utils/logmon.py"
    click Config_JSON "https://github.com/molecularai/reinvent4/tree/main/configs/json/"
    click Config_TOML "https://github.com/molecularai/reinvent4/tree/main/configs/toml/"
    click Priors "https://github.com/molecularai/reinvent4/tree/main/priors/"
    click Logs "https://github.com/molecularai/reinvent4/blob/main/pytest.ini"
    click External "https://github.com/molecularai/reinvent4/tree/main/support/"
```
