# bu-bu-xxx/modelgenerator architecture

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

- Interactive diagram: https://gitdiagram.com/bu-bu-xxx/modelgenerator
- Repository: https://github.com/bu-bu-xxx/modelgenerator

## Overview

##### Project Type & Purpose
- Type: Open-source machine-learning toolkit / framework.
- Purpose: Provide adapters, pretrained backbones, data modules, tasks, and experiment drivers to train/evaluate models on biological sequence and structure tasks.

##### Major Components
A. CLI / Entry Point
– modelgenerator/main.py
– Parses command-line arguments and YAML configs (via hydra or custom loader).
B. Configuration Layer
– configs/defaults.yaml + examples in configs/examples/
– Defines model/hyperparameter/experiment specifications.
C. Core Library Packages
1. adapters/
- Translate between generic task API and various model architectures.
2. backbones/
- Base classes and implementations of neural architectures.
3. data/
- DataModule, Dataset classes for handling sequence and structure data.
4. tasks/
- Task definitions (training, validation, testing loops) and metrics.
5. callbacks.py
- Training callbacks (logging, checkpointing).
6. lr_schedulers.py, metrics.py
- Learning-rate scheduling, evaluation metrics.
D. Pretrained Model Integrations
– huggingface_models/
- cellfoundation, fm4bio, genbio, rnabert, etc.
- Tokenizer, configuration, model classes, and conversion scripts.
E. Specialized Subpackages
1. prot_inv_fold/
- Inverse-folding pipeline using ProteinMPNN; data loaders, adapter, task.
2. rna_inv_fold/
- Similar pipeline for RNA inverse folding; includes gRNAde encoder.
3. rna_ss/
- RNA secondary-structure prediction task.
4. structure_tokenizer/
- Tokenizer models, datasets, callbacks, equiformer and esmfold layers.
F. Experiments Directory
– experiments/…
– Collection of ready-to-run YAML configurations and helper scripts for AIDO benchmarks (DNA, Protein, RNA, StructureTokenizer).
G. Documentation
– docs/ + mkdocs.yml
– API reference, tutorials, experiment design docs.

##### Relationships & Data Flow
- Config files → CLI (main.py)
- CLI → Instantiates Task with:
– DataModule (from data/)
– Backbone model (from backbones/ or huggingface_models/)
– Adapter (from adapters/)
– Callbacks, schedulers, metrics
- Task → Training Loop (PyTorch Lightning style)
- Training Loop ↔ DataModule → Dataset → I/O layer
- Training Loop ↔ Model → Forward/Backward passes
- Callbacks → Logging/Checkpoint → Disk or WandB (external)
- Experiments folder: external scripts call CLI with specific YAML → data artifacts & metrics outputs.
- Documentation site: built separately via mkdocs.

##### Architectural Patterns & Principles
- Modular layering: separation of concerns (adapters, backbones, data, tasks).
- Plugin-style extensibility: new backbones or tasks can be dropped in via directories.
- Configuration-driven execution: YAML config files control entire pipeline.
- Use of PyTorch Lightning conventions (DataModule, Callbacks).
- Integration with HuggingFace Transformers-like patterns for model classes.

##### Essential Elements Checklist
– Configurations (YAML) clearly feed into the orchestration layer.
– External services (HuggingFace models, WandB, filesystem) are shown.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Artifacts"
        Defaults["defaults.yaml"]:::config
        Examples["configs/examples/"]:::config
    end

    %% Experiments
    Experiments["experiments/"]:::config

    %% Entry Point
    CLI["modelgenerator/main.py"]:::process

    %% Core Library
    subgraph "Core Library"
        Adapters["adapters/"]:::code
        Backbones["backbones/"]:::code
        DataModule["data/"]:::code
        Tasks["tasks/"]:::code
        Callbacks["callbacks.py"]:::code
        Schedulers["lr_schedulers.py"]:::code
        Metrics["metrics.py"]:::code
    end

    %% Pretrained Integrations
    subgraph "Pretrained Model Integrations"
        HFModels["huggingface_models/"]:::external
    end

    %% Specialized Pipelines
    subgraph "Specialized Pipelines"
        ProtInv["prot_inv_fold/"]:::code
        RNAInv["rna_inv_fold/"]:::code
        RNASS["rna_ss/"]:::code
        StructTok["structure_tokenizer/"]:::code
    end

    %% Training Loop & Storage
    TrainingLoop(["Training Loop<br/>(PyTorch Lightning)"]):::process
    Dataset[(Dataset)]:::storage
    Checkpoints[(Checkpoints)]:::storage
    WandB["WandB"]:::external
    FileSystem["File System"]:::external

    %% Documentation
    subgraph "Documentation"
        DocsSite["docs/"]:::docs
        Mkdocs["mkdocs.yml"]:::docs
    end

    %% Connections
    Defaults -->|reads| CLI
    Examples -->|reads| CLI
    Experiments -->|invokes| CLI
    CLI -->|instantiates| Tasks
    CLI -->|loads| Adapters
    CLI -->|loads| Backbones
    CLI -->|loads| DataModule
    CLI -->|configures| Callbacks
    CLI -->|configures| Schedulers
    CLI -->|configures| Metrics

    Tasks <-->|uses| DataModule
    DataModule -->|loads| Dataset
    Tasks <-->|trains on| Dataset
    Tasks <-->|forwards/backwards| Backbones
    Tasks <-->|integrates| HFModels
    Tasks -->|runs| TrainingLoop
    TrainingLoop -->|saves| Checkpoints
    TrainingLoop -->|logs| WandB
    TrainingLoop -->|writes| FileSystem
    Callbacks -->|writes| Checkpoints
    Schedulers -->|adjusts| Backbones

    %% Click Events
    click CLI "https://github.com/bu-bu-xxx/modelgenerator/blob/main/modelgenerator/main.py"
    click Defaults "https://github.com/bu-bu-xxx/modelgenerator/blob/main/configs/defaults.yaml"
    click Examples "https://github.com/bu-bu-xxx/modelgenerator/tree/main/configs/examples/"
    click Adapters "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/adapters/"
    click Backbones "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/backbones/"
    click DataModule "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/data/"
    click Tasks "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/tasks/"
    click Callbacks "https://github.com/bu-bu-xxx/modelgenerator/blob/main/modelgenerator/callbacks.py"
    click Schedulers "https://github.com/bu-bu-xxx/modelgenerator/blob/main/modelgenerator/lr_schedulers.py"
    click Metrics "https://github.com/bu-bu-xxx/modelgenerator/blob/main/modelgenerator/metrics.py"
    click HFModels "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/huggingface_models/"
    click ProtInv "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/prot_inv_fold/"
    click RNAInv "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/rna_inv_fold/"
    click RNASS "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/rna_ss/"
    click StructTok "https://github.com/bu-bu-xxx/modelgenerator/tree/main/modelgenerator/structure_tokenizer/"
    click Experiments "https://github.com/bu-bu-xxx/modelgenerator/tree/main/experiments/"
    click DocsSite "https://github.com/bu-bu-xxx/modelgenerator/tree/main/docs/"
    click Mkdocs "https://github.com/bu-bu-xxx/modelgenerator/blob/main/docs/mkdocs.yml"

    %% Styles
    classDef code fill:#e0f7e9,stroke:#2e7d32,stroke-width:1px
    classDef external fill:#e3f2fd,stroke:#1565c0,stroke-width:1px
    classDef config fill:#fff9c4,stroke:#fbc02d,stroke-width:1px
    classDef docs fill:#eceff1,stroke:#607d8b,stroke-width:1px
    classDef process fill:#f3e5f5,stroke:#6a1b9a,stroke-width:1px
    classDef storage fill:#fff3e0,stroke:#ef6c00,stroke-width:1px
```
