# bytedprotein/byprot architecture

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

- Interactive diagram: https://gitdiagram.com/bytedprotein/byprot
- Repository: https://github.com/bytedprotein/byprot

## Overview

##### Project Type and Purpose
- ByProt is essentially a full-fledged research toolkit/library for protein design.
- Its purpose is twofold: (a) to offer a non‐autoregressive ProteinMPNN variant (with conditional masked language modeling) and (b) to provide an official implementation of the LM‐Design system. Both involve significant machine learning on protein structure data.
- The system supports training, evaluation, and inference workflows using configurable pipelines with Hydra.

##### File Structure – Identify Major Components
- Configurations: The “configs” directory holds multiple subdirectories for callbacks, datamodules, experiments, Hydra, logger, trainer, paths, and test settings. This indicates a heavy reliance on user-configurable parameters and a dynamic runtime via Hydra.
- Source Code: The “src/byprot” directory contains:
- Datamodules: responsible for data ingestion/preprocessing (e.g., CATH datasets, multichain datasets).
- Models: several subfolders for “fixedbb” (for fixed-backbone designs), LM-design specific models (ESM variants), ProteinMPNN implementations, and also a “seq2seq” variant.
- Tasks: encapsulating high-level runnable tasks such as training and inference workflows.
- Utility Modules: core functionalities for configuration management, logging, IO, learning rate scheduling, optimization, and registries.
- Top-Level Scripts: Files like train.py, test.py, and design_pdb.py in “scripts” and “examples” show that the toolkit offers both command line scripts and interactive notebooks for training, evaluation, and inference.
- Vendor and Dependencies: The presence of a “vendor” folder and related files (install.sh, requirements.txt, setup.py) hints at modular dependency management and package distribution.

##### Core Components
a. Configuration Management:
- Hydra-based configuration system (from “configs/” and “configs/hydra”), allowing experiments, data modules, logging, and trainer settings to be altered simply.
b. Data Modules:
- Components under “src/byprot/datamodules/” that handle dataset ingestion and preprocessing for various protein datasets (e.g., cath_4.2, cath_4.3, multichain).
c. Models:
- Two principal model families are featured:
- Fixed-backbone models, particularly with LM-Design and ProteinMPNN variants found in “src/byprot/models/fixedbb”.
- Miscellaneous models in “src/byprot/models/seq2seq” that could represent alternative design workflows.
- Modules for adapters and additional transformation layers (like esm2_adapter, gvp_transformer_encoder).
d. Training and Evaluation Pipelines:
- Training pipelines (via train.py, training_pipeline.py) and evaluation/inference (test.py, designer modules in “tasks”) that govern the experiment lifecycle.
e. User Applications/Interfaces:
- Command-line scripts (found in “scripts/”) and Jupyter notebooks (in “examples/”) that allow users to run experiments, design sequences, or inpaint segments.

##### Relationships, Interactions, and Data Flow
- How raw data (PDB files and datasets) are loaded using the data modules.
- Flow of data through preprocessing steps, model inference/training (i.e., how data moves from datamodules into models).
- How configuration files and Hydra’s configuration engine feed parameters into training jobs and evaluation, impacting both model behavior and data module settings.
- End-to-end lifecycle: Data Fetch → Preprocessing (datamodules) → Model (fixedbb: LM-Design or ProteinMPNN) → Training Pipeline → Evaluation/Inference (designer interface).

##### Architectural Patterns and Design Principles
- Modular Design: Separating configurations, models, tasks, and pipelines enhances reusability and extensibility.
- Configurable Workflows: Hydra configuration enables dynamic experiment setups (e.g., switching between datasets like cath or multichain, different model variants).
- Clear Separation of Concerns: Each directory in “src/byprot” (datamodules, models, tasks, utils) is responsible for a narrowly defined set of functions.
- Leveraging External Frameworks: Using PyTorch Lightning as the backbone for training loops and state-of-the-art techniques (like non-autoregressive generation, masked language modeling).

##### Final Recommendation
- Separate blocks for “Data Modules” (loading PDB and dataset configurations), “Model Architectures” (with sub-blocks for fixedbb, LM-Design, ProteinMPNN), and then “Training & Inference Pipelines”.
- “User Interface” block showing both CLI (script execution) and interactive (Jupyter notebooks) export/integration paths.
- Be sure to capture sub-components as much as possible without oversimplifying—this means not merely portraying one single monolithic “model” block, but separating out key elements such as datamodule loaders, different model variants, and task handlers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Configuration Layer"
        CM["Configuration Engine (Hydra)"]:::config
    end

    subgraph "Data Layer"
        DM["Data Modules (Dataset Ingestion)"]:::data
    end

    subgraph "Model Architecture"
        FB["Fixed-backbone Models (LM-Design, ProteinMPNN)"]:::model
        S2S["Seq2Seq Models"]:::model
    end

    subgraph "Pipelines"
        TS["Training Script (train.py)"]:::pipeline
        TP["Training Pipeline (src/byprot/training_pipeline.py)"]:::pipeline
        TES["Test Script (test.py)"]:::pipeline
        TP2["Testing Pipeline (src/byprot/testing_pipeline.py)"]:::pipeline
        TH["Task Handlers (src/byprot/tasks/fixedbb/)"]:::pipeline
    end

    subgraph "User Interface"
        CLI["Command-line Scripts (scripts/)"]:::ui
        NB["Jupyter Notebooks (examples/)"]:::ui
    end

    CM -->|"configures"| DM
    CM -->|"configures"| FB
    CM -->|"configures"| S2S
    DM -->|"feeds_data"| FB
    DM -->|"feeds_data"| S2S
    FB -->|"trains_with"| TS
    FB -->|"trains_with"| TP
    S2S -->|"trains_with"| TS
    S2S -->|"trains_with"| TP
    TS -->|"executes"| TH
    TP -->|"executes"| TH
    TH -->|"triggers"| TES
    TES -->|"executes"| TP2
    TP2 -->|"produces_results"| CLI
    TP2 -->|"produces_results"| NB

    click CM "https://github.com/bytedprotein/byprot/tree/main/configs/"
    click DM "https://github.com/bytedprotein/byprot/tree/main/src/byprot/datamodules/"
    click FB "https://github.com/bytedprotein/byprot/tree/main/src/byprot/models/fixedbb/"
    click S2S "https://github.com/bytedprotein/byprot/tree/main/src/byprot/models/seq2seq/"
    click TS "https://github.com/bytedprotein/byprot/blob/main/train.py"
    click TP "https://github.com/bytedprotein/byprot/blob/main/src/byprot/training_pipeline.py"
    click TES "https://github.com/bytedprotein/byprot/blob/main/test.py"
    click TP2 "https://github.com/bytedprotein/byprot/blob/main/src/byprot/testing_pipeline.py"
    click TH "https://github.com/bytedprotein/byprot/tree/main/src/byprot/tasks/fixedbb/"
    click CLI "https://github.com/bytedprotein/byprot/tree/main/scripts/"
    click NB "https://github.com/bytedprotein/byprot/tree/main/examples/"

    classDef config fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef data fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef model fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef pipeline fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef ui fill:#DDA0DD,stroke:#000,stroke-width:2px;
```
