How bu-bu-xxx/modelgenerator works
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.