# evo-design/protein-dpo architecture

> Architecture diagram of the GitHub repository evo-design/protein-dpo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/evo-design/protein-dpo
- Repository: https://github.com/evo-design/protein-dpo

## Overview

##### Project type and purpose
- This is an open-source, command-line protein inference and scoring toolkit (ProteinDPO) built in Python.
- It provides two primary functions:
- Sampling new protein sequences given a structure (sample.py)
- Scoring mutant protein sequences against experimental fitness data (score.py, score_complex.py)

##### File structure
- Top-level scripts:
- sample.py – entry point for structure-conditioned sequence sampling
- score.py – entry point for scoring a single mutation dataset
- score_complex.py – extension for more advanced scoring workflows
- Support files/directories:
- weights/ – holds pretrained model artifacts (ProteinDPO weights, vanilla ESM-IF1 weights)
- example/ – sample CSV inputs
- environment.yml – Conda environment specification
- README.md, LICENSE – documentation and licensing
- No “src” directory: all logic lives in the root scripts or imported modules from the installed esm package.
- External dependency: the ESM inverse-folding library (installed via pip from GitHub).

##### README for additional insights
- Describes a two-stage pipeline:
a. Sampling (structure → new sequence proposals)
b. Scoring (sequence dataset → likelihood/fitness scores)
- Lists command‐line arguments and expected file formats (PDB, CSV)
- Specifies where to download and place model weights

##### Detail without over-splitting
- Logical components (script, model, data, env)
- Avoid down-to-the-line-of-code granularity; focus on modules and interactions
- Every input, process, and output is represented clearly

## Diagram (Mermaid)

```mermaid
graph TB
    User(("User")):::actor

    subgraph "Environment & Deployment"
        EnvFile["environment.yml"]:::env
        Doc["README.md"]:::doc
        License["LICENSE"]:::doc
    end

    subgraph "Data Repositories"
        PDBFiles[[PDB Files]]:::data
        CSVInputs[[CSV Datasets]]:::data
        Weights[[Model Weights Store]]:::data
        OutputSeq[[Sampled FASTA Sequences]]:::data
        OutputScores[[Scored CSVs]]:::data
    end

    subgraph "CLI Layer"
        Sampling["sample.py"]:::cli
        Scoring["score.py"]:::cli
        ComplexScoring["score_complex.py"]:::cli
    end

    subgraph "Core Inference Engine"
        ProteinDPO[(ProteinDPO Model)]:::model
        ESMIF1[(ESM-IF1 Library)]:::model
    end

    User -->|"runs CLI"| Sampling
    User -->|"runs CLI"| Scoring
    User -->|"runs CLI"| ComplexScoring

    EnvFile -->|"provides environment"| Sampling
    EnvFile -->|"provides environment"| Scoring
    EnvFile -->|"provides environment"| ComplexScoring

    PDBFiles -->|"input PDB"| Sampling
    CSVInputs -->|"input CSV"| Scoring
    CSVInputs -->|"input CSV"| ComplexScoring

    Weights -->|"loads weights"| ProteinDPO
    ESMIF1 -->|"inverse-folding API"| ProteinDPO

    Sampling -->|"invokes inference"| ProteinDPO
    Scoring -->|"invokes inference"| ProteinDPO
    ComplexScoring -->|"invokes inference"| ProteinDPO

    ProteinDPO -->|"outputs sequences"| OutputSeq
    ProteinDPO -->|"outputs scores"| OutputScores

    Doc -.-> User
    License -.-> User

    click Sampling "https://github.com/evo-design/protein-dpo/blob/main/sample.py"
    click Scoring "https://github.com/evo-design/protein-dpo/blob/main/score.py"
    click ComplexScoring "https://github.com/evo-design/protein-dpo/blob/main/score_complex.py"
    click Weights "https://github.com/evo-design/protein-dpo/tree/main/weights/"
    click CSVInputs "https://github.com/evo-design/protein-dpo/tree/main/example/"
    click EnvFile "https://github.com/evo-design/protein-dpo/blob/main/environment.yml"
    click Doc "https://github.com/evo-design/protein-dpo/blob/main/README.md"
    click License "https://github.com/evo-design/protein-dpo/tree/main/LICENSE"

    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef cli fill:#bbf,stroke:#333,stroke-width:1px
    classDef model fill:#bfb,stroke:#333,stroke-width:1px
    classDef data fill:#fdd,stroke:#333,stroke-width:1px
    classDef env fill:#ffb,stroke:#333,stroke-width:1px
    classDef doc fill:#ffd,stroke:#333,stroke-width:1px
```
