# cong-lab/crispr-gpt-pub architecture

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

- Interactive diagram: https://gitdiagram.com/cong-lab/crispr-gpt-pub
- Repository: https://github.com/cong-lab/crispr-gpt-pub

## Overview

##### Project type and purpose
- CRISPR-GPT is an open-source, agent-based Large Language Model (LLM) application for automating gene-editing experiment design.
- It orchestrates multiple agent components (Planner, Executor, User-Proxy, Tool Providers) to decompose tasks, execute protocols, interact with users, and call external bioinformatics tools/APIs.

##### File structure
- In this case, the only file is `README.md`. All structural and architectural details must be inferred from that document.
- The README describes a four-agent architecture, an optional web front-end (Gradio demo), LLM back-end (OpenAI API), and external tool integrations (Primer3, CRISPResso2, CRISPRitz, search engines, lab automation).

##### Key insights from the README
- Four core agents collaborate:
- LLM Planner Agent
- Task Executor Agent
- LLM User-Proxy Agent
- Tool Provider Agent(s)
- Three user modes: Meta, Auto, QA.
- External services: OpenAI API, bioinformatics tools, databases, search engines, and a demo web UI.

##### Main components
a. Client/User Interface
– Web front-end (Gradio or custom UI) where the user selects mode, inputs requests, and views results.
– QA panel or workflow monitor.
b. LLM Core
– Planner Agent (task decomposition & planning)
– Task Executor Agent (state-machine, instruction generation, feedback loop)
– User-Proxy Agent (mediates user corrections & monitors execution)
c. Tool Provider Layer
– A set of microservices or adapter modules wrapping external bioinformatics tools and APIs (Primer3, CRISPResso2, CRISPRitz, genomic databases, search engines)
d. External Systems
– OpenAI API or other LLM endpoints
– Bioinformatics tool servers/containers
– Databases (e.g., genomic reference, ClinVar)
– Lab automation APIs (future integration)
e. Persistence / Logging (optional)
– Experiment plans, logs, results, user corrections stored in a database or file store.

##### Relationships and interactions
- User → Web UI → User-Proxy Agent
- User-Proxy Agent ↔ Task Executor Agent (instructions, feedback)
- Task Executor Agent ← Planner Agent (plan + state machines)
- Task Executor Agent & User-Proxy Agent → Tool Provider(s) → External tools/APIs
- Task Executor Agent/User-Proxy Agent → Logging/DB
- All internal agents call the LLM API to generate text or parse outputs.

##### Architectural patterns & principles
- Agent-based microservices: each component is a distinct service or module.
- Chain-of-thought / state-machine workflows for reproducibility.
- Adapter/wrapper pattern for external tools.
- Asynchronous calls and callback loops for long-running tasks (e.g., NGS analysis).

##### Detailed elements
- Notes on user modes and how they alter the Planner Agent’s configuration

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        User["User"]:::frontend
        WebUI["Web Front-end (Gradio/UI)\nModes: Meta, Auto, QA"]:::frontend
    end

    %% Agent Layer
    subgraph "Agent Layer"
        Planner["LLM Planner Agent"]:::agent
        Executor["Task Executor Agent"]:::agent
        Proxy["LLM User-Proxy Agent"]:::agent
    end

    %% Tool Provider Layer
    subgraph "Tool Provider Layer"
        Tools["Tool Provider Agent(s)"]:::provider
    end

    %% External Services Layer
    subgraph "External Services"
        OpenAI["OpenAI API"]:::external
        Primer3["Primer3"]:::external
        CRISPResso2["CRISPResso2"]:::external
        CRISPRitz["CRISPRitz"]:::external
        DB["Databases (Genomic, ClinVar)"]:::external
        LabAuto["Lab Automation APIs"]:::external
    end

    %% Persistence
    Persistence["Persistence/Logging (DB or file store)"]:::persistence

    %% Connections - synchronous
    User -->|"interacts with"| WebUI
    WebUI -->|"submits requests"| Proxy
    Proxy -->|"delegates tasks"| Executor
    Executor -->|"requests plan"| Planner

    Planner -->|"LLM API call"| OpenAI
    Executor -->|"LLM API call"| OpenAI
    Proxy -->|"LLM API call"| OpenAI

    Executor -->|"invoke tools"| Tools
    Proxy -->|"invoke tools"| Tools

    Executor -->|"log data"| Persistence
    Proxy -->|"log corrections"| Persistence

    %% Connections - asynchronous
    Tools -.->|"results callback"| Executor
    Tools -.->|"results callback"| Proxy
    Tools --> Primer3
    Tools --> CRISPResso2
    Tools --> CRISPRitz
    Tools --> DB
    Tools --> LabAuto

    %% Click Events
    click Planner "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click Executor "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click Proxy "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click Tools "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click WebUI "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click OpenAI "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click Primer3 "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click CRISPResso2 "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click CRISPRitz "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click DB "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click LabAuto "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"
    click Persistence "https://github.com/cong-lab/crispr-gpt-pub/blob/main/README.md"

    %% Styles
    classDef frontend fill:#D39BF6,stroke:#884EA0,color:#000
    classDef agent fill:#A1C6EA,stroke:#1F618D,color:#000
    classDef provider fill:#B7E4C7,stroke:#2E7D32,color:#000
    classDef external fill:#FFCC80,stroke:#E67E22,color:#000
    classDef persistence fill:#E0E0E0,stroke:#5D6D7E,color:#000
```
