# ur-whitelab/chemcrow-public architecture

> Architecture diagram of the GitHub repository ur-whitelab/chemcrow-public, 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/ur-whitelab/chemcrow-public
- Repository: https://github.com/ur-whitelab/chemcrow-public

## Overview

##### Project type and purpose
- ChemCrow is an open-source Python package (library) that augments large-language models with chemistry-specific tools.
- It exposes a “ChemCrow” agent API (built on LangChain) that orchestrates calls to chemistry tool wrappers (RDKit, ChemSpace, reaction predictors, etc.), external APIs (OpenAI, SerpApi, RXN4Chem), and optional self-hosted microservices (Docker images for retrosynthesis and molecular-transformer).
- It also provides a lightweight Streamlit frontend for interactive use.

##### File structure
- Top-level:
- chemcrow/agents – orchestrator classes and prompt definitions
- chemcrow/tools – wrappers around chemistry libraries and external services
- chemcrow/data – static CSV datasets (e.g. chem_wep.csv)
- chemcrow/docker – Docker configurations for two self-hosted services (aizynthfinder and molecular-transformer)
- chemcrow/frontend – Streamlit callback handler and UI utilities
- tests/ – unit tests validating agents and tools
- dev-requirements.txt, setup.py – build and dependency definitions
- GitHub workflows for CI/CD
- The structure suggests a modular, plugin-style architecture: Agent layer → Tool layer → Data/external services.

##### README for additional insights
- The README emphasizes:
- Core functionality: instantiate ChemCrow(model, …).run(“task”)
- Dependencies on OpenAI API, SerpApi, RXN4Chem (or self-hosted alternatives)
- Optional microservices launched via Docker to replace hosted RXN4Chem endpoints
- A Streamlit demo on HuggingFace Spaces

##### Elements
- Blue for internal components (Agent, Tool Wrappers)
- Green for local libraries/data
- Orange for external APIs
- Purple for Docker microservices
- Grey for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface
    subgraph "User Interface" 
        UI_CLI["CLI / Streamlit Frontend"]:::internal
        StreamlitHandler["streamlit_callback_handler.py"]:::internal
        UIUtils["utils.py"]:::internal
    end

    %% Agent Layer
    subgraph "ChemCrow Agent" 
        ChemCrow["chemcrow.py"]:::internal
        AgentPrompts["prompts.py"]:::internal
        AgentToolsDef["tools.py"]:::internal
    end

    %% Tool Wrappers
    subgraph "Tool Wrappers" 
        RDKit["rdkit.py"]:::internal
        ChemSpace["chemspace.py"]:::internal
        Converters["converters.py"]:::internal
        Reactions["reactions.py"]:::internal
        RXN4ChemWrapper["rxn4chem.py"]:::internal
        Safety["safety.py"]:::internal
        Search["search.py"]:::internal
        ToolPrompts["prompts.py"]:::internal
    end

    %% Data Layer
    subgraph "Data Layer" 
        ChemWEP["chem_wep.csv"]:::data
        ChemWEP_SMI["chem_wep_smi.csv"]:::data
    end

    %% External APIs
    subgraph "External APIs" 
        OpenAI["OpenAI API"]:::external
        SerpApi["SerpApi"]:::external
        RXN4ChemAPI["RXN4Chem"]:::external
    end

    %% Docker Microservices
    subgraph "Self-Hosted Microservices" 
        AIZynthFinder["AIZynthFinder Service"]:::micro
        MTService["Molecular-Transformer Service"]:::micro
    end

    %% Versioning & Packaging
    subgraph "Versioning & Packaging"
        SetupPy["setup.py"]:::internal
        VersionPy["version.py"]:::internal
    end

    %% CI/CD
    subgraph "CI/CD & Tests"
        TestAgent["test_agent.py"]:::ci
        TestConverters["test_converters.py"]:::ci
        TestRDKit["test_rdkit.py"]:::ci
        TestSafety["test_safety_tools.py"]:::ci
        TestSearch["test_search.py"]:::ci
        WorkflowBuild["build.yml"]:::ci
        WorkflowTests["tests.yml"]:::ci
    end

    %% Connections
    UI_CLI -->|"user prompt"| ChemCrow
    StreamlitHandler -->|"user prompt"| ChemCrow
    ChemCrow -->|"selects tools"| RDKit & ChemSpace & Converters & Reactions & RXN4ChemWrapper & Safety & Search
    ToolPrompts -->|provides prompts| ChemCrow
    RDKit -->|"calls library"| ChemSpace & Converters & Reactions
    Converters -->|"uses data"| ChemWEP & ChemWEP_SMI
    Reactions -->|"remote or local"| OpenAI & SerpApi & RXN4ChemAPI & AIZynthFinder & MTService
    RXN4ChemWrapper -->|"HTTP requests"| RXN4ChemAPI & AIZynthFinder
    Search -->|"HTTP requests"| SerpApi
    Safety -->|"local checks"| ChemWEP
    ChemCrow -->|"returns response"| UI_CLI
    ChemCrow -->|"returns response"| StreamlitHandler
    SetupPy -->|"defines package"| ChemCrow
    VersionPy -->|"defines version"| ChemCrow
    TestAgent & TestConverters & TestRDKit & TestSafety & TestSearch -->|"validate"| ChemCrow & RDKit & Converters & Safety & Search
    WorkflowBuild & WorkflowTests -->|"CI runs"| TestAgent & TestConverters & TestRDKit & TestSafety & TestSearch

    %% Click Events
    click StreamlitHandler "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/frontend/streamlit_callback_handler.py"
    click UIUtils "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/frontend/utils.py"
    click ChemCrow "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/agents/chemcrow.py"
    click AgentPrompts "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/agents/prompts.py"
    click AgentToolsDef "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/agents/tools.py"
    click RDKit "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/rdkit.py"
    click ChemSpace "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/chemspace.py"
    click Converters "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/converters.py"
    click Reactions "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/reactions.py"
    click RXN4ChemWrapper "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/rxn4chem.py"
    click Safety "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/safety.py"
    click Search "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/search.py"
    click ToolPrompts "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/tools/prompts.py"
    click ChemWEP "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/data/chem_wep.csv"
    click ChemWEP_SMI "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/data/chem_wep_smi.csv"
    click AIZynthFinder "https://github.com/ur-whitelab/chemcrow-public/tree/main/chemcrow/docker/aizynthfinder/Dockerfile"
    click AIZynthFinder "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/docker/aizynthfinder/app.py"
    click AIZynthFinder "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/docker/aizynthfinder/config.yml"
    click MTService "https://github.com/ur-whitelab/chemcrow-public/tree/main/chemcrow/docker/molecular-transformer/Dockerfile"
    click MTService "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/docker/molecular-transformer/app.py"
    click SetupPy "https://github.com/ur-whitelab/chemcrow-public/blob/main/setup.py"
    click VersionPy "https://github.com/ur-whitelab/chemcrow-public/blob/main/chemcrow/version.py"
    click TestAgent "https://github.com/ur-whitelab/chemcrow-public/blob/main/tests/test_agent.py"
    click TestConverters "https://github.com/ur-whitelab/chemcrow-public/blob/main/tests/test_converters.py"
    click TestRDKit "https://github.com/ur-whitelab/chemcrow-public/blob/main/tests/test_rdkit.py"
    click TestSafety "https://github.com/ur-whitelab/chemcrow-public/blob/main/tests/test_safety_tools.py"
    click TestSearch "https://github.com/ur-whitelab/chemcrow-public/blob/main/tests/test_search.py"
    click WorkflowBuild "https://github.com/ur-whitelab/chemcrow-public/blob/main/.github/workflows/build.yml"
    click WorkflowTests "https://github.com/ur-whitelab/chemcrow-public/blob/main/.github/workflows/tests.yml"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#004085,color:#004085
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#ffe5b4,stroke:#d97706,color:#b45309
    classDef micro fill:#e5dbff,stroke:#5a31f4,color:#5a31f4
    classDef ci fill:#f2f2f2,stroke:#6c757d,color:#6c757d
```
