# zou-group/virtual-lab architecture

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

- Interactive diagram: https://gitdiagram.com/zou-group/virtual-lab
- Repository: https://github.com/zou-group/virtual-lab

## Overview

The Virtual Lab project is a full-fledged research collaboration platform that orchestrates interactions between human researchers and teams of LLM agents for scientific research. It has a dual nature: a general system framework (located in the src/virtual_lab directory) that manages agent-based “meetings” and a comprehensive demonstration and application (in the nanobody_design directory) that uses a specialized computational pipeline for designing nanobodies against SARS‐CoV‐2.

##### Out the relationships and interactions
– The data processing scripts feed results into models.
– The models (both “original” and “improved”) output scores and predictions.
– Results are logged in directories such as scores and then visualized (via notebooks and figures).
- A feedback loop from experimental data (and discussion files) back to model adjustments and further agent discussions, emphasizing an iterative design and review workflow.

##### Architectural patterns and important design principles
- Separation of Concerns: The core Virtual Lab (under src/virtual_lab) is kept separate from the nanobody-specific code. This separation helps maintain a generic research agent framework versus a domain-specific demonstration.
- Modular Pipelines: The nanobody_design folder is organized into separate subdirectories for data, analysis, modeling, discussions, and deployment scripts (including SLURM batch files), reflecting a pipeline that is modular and extendable.

##### Relevant technologies and frameworks
- Python is the primary language.
- Virtual Lab is published as a pip package with dependencies noted in requirements files.
- External libraries/tools:
– OpenAI’s GPT-4o (via the API).
– Deep learning models like ESM, AlphaFold-Multimer, and Rosetta (the latter with associated XML configuration files).
– Jupyter notebooks for interactive data processing and visualization.
- High-level configuration and build integration (pyproject.toml, conda environment instructions) can be represented at the base or as a global “platform” note.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        HRI["Human Researcher Interface"]:::presentation
    end

    subgraph "Application Logic Layer"
        VLE["Virtual Lab Core Engine"]:::core
        LLM["LLM Agents"]:::core
    end

    subgraph "Nanobody Design Pipeline"
        NP1["Data Processing Scripts"]:::pipeline
        NP2["Models for Prediction"]:::pipeline
        NP3["Discussion and QA Archives"]:::pipeline
        NP4["Experimental Data"]:::pipeline
        NP5["Figures"]:::pipeline
    end

    subgraph "External Dependencies"
        EXT["External Tools and APIs"]:::external
    end

    HRI -->|"initiates_meetings"| VLE
    VLE -->|"communicates_with"| LLM
    VLE -->|"triggers_nanobody_pipeline"| NP1
    NP1 -->|"feeds_into"| NP2
    NP2 -->|"outputs_predictions_to"| NP4
    NP4 -->|"feedback_to"| NP3
    NP3 -->|"iterative_adjustment_to"| NP2
    NP2 -->|"calls"| EXT
    LLM -->|"uses_OpenAI_API"| EXT

    style HRI fill:#f9c74f,stroke:#333,stroke-width:2px
    style VLE fill:#90be6d,stroke:#333,stroke-width:2px
    style LLM fill:#90be6d,stroke:#333,stroke-width:2px
    style NP1 fill:#43aa8b,stroke:#333,stroke-width:2px
    style NP2 fill:#43aa8b,stroke:#333,stroke-width:2px
    style NP3 fill:#43aa8b,stroke:#333,stroke-width:2px
    style NP4 fill:#43aa8b,stroke:#333,stroke-width:2px
    style NP5 fill:#43aa8b,stroke:#333,stroke-width:2px
    style EXT fill:#f94144,stroke:#333,stroke-width:2px

    click VLE "https://github.com/zou-group/virtual-lab/tree/main/src/virtual_lab"
    click LLM "https://github.com/zou-group/virtual-lab/blob/main/src/virtual_lab/agent.py"
    click NP1 "https://github.com/zou-group/virtual-lab/tree/main/nanobody_design/scripts/data_processing"
    click NP2 "https://github.com/zou-group/virtual-lab/tree/main/nanobody_design/scripts/models"
    click NP3 "https://github.com/zou-group/virtual-lab/tree/main/nanobody_design/discussions"
    click NP4 "https://github.com/zou-group/virtual-lab/tree/main/nanobody_design/experimental_data"
    click NP5 "https://github.com/zou-group/virtual-lab/tree/main/nanobody_design/figures"
    click EXT "https://github.com/zou-group/virtual-lab/blob/main/nanobody_design/requirements_nanobody_design_frozen.txt"
```
