# lamm-mit/sciagentsdiscovery architecture

> Architecture diagram of the GitHub repository lamm-mit/sciagentsdiscovery, 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/lamm-mit/sciagentsdiscovery
- Repository: https://github.com/lamm-mit/sciagentsdiscovery

## Overview

##### Project type and purpose
- SciAgents is an open-source Python library plus accompanying Jupyter notebooks that implements a modular, multi-agent pipeline for automated scientific discovery via graph reasoning. It is not a web app or microservice platform but rather a research tool and framework you run locally or in a cloud notebook.

##### File structure
- Top-level:
- setup.py – package installer
- README.md – project overview, architecture figures, usage
- LICENSE.txt
- Notebooks/ – two example workflows (non-automated and automated)
- ScienceDiscovery/ – core Python package modules
- Core modules inside ScienceDiscovery/:
- graph.py – loads and manages the ontological knowledge graph
- agents.py – orchestrates multi-agent interactions (Ontologist, Scientist1, Scientist2, Critic, Planner, Assistant)
- llm_config.py – configuration and wrapper for LLM calls (OpenAI, AG2)
- utils.py – common helpers (I/O, formatting, JSON)
- No web server, no database server—graph files and embeddings are downloaded on demand via Hugging Face Hub. External APIs: OpenAI, Semantic Scholar, AG2.

##### Extract architecture insights from README
- Two pipelines:
a. Pre-programmed multi-agent sequence
b. Fully automated, flexible multi-agent sequence
- Dependencies: GraphReasoning (AG2), Hugging Face Hub, OpenAI API, Semantic Scholar API, wkhtmltopdf (for PDF generation).

##### Main components and their relationships
a. Entry points (Notebooks)
- Import ScienceDiscovery package
- Configure LLM and API keys
- Trigger either the non-automated or automated agent pipeline
b. Core Library (ScienceDiscovery)
- Graph Module: loads the global knowledge graph from local cache or HF Hub
- Embedding Module (via utils + HF Hub): fetches precomputed embeddings
- LLM Config Module: sets up calls to OpenAI or AG2 agents
- Agents Module: defines each agent role and orchestrates their interactions in sequence or dynamically
- Utils Module: handles I/O, JSON structure, PDF generation
c. External Services
- OpenAI API – LLM completions
- Semantic Scholar API – paper metadata retrieval
- Hugging Face Hub – graph files and embeddings storage
- AG2 Framework – underpins the multi-agent execution environment
d. Output
- Structured JSON draft → refined text → PDF/HTML report via wkhtmltopdf

##### Architectural patterns and design principles
- Modular pipeline: each logical step is its own module, enabling replacement or extension
- Agent-based orchestration: roles encapsulated as classes, sequence defined in agents.py
- Data-driven: external graph and embeddings fetched at runtime, no hard-coded data
- Separation of concerns: graph management, LLM configuration, agent logic, and utilities are clearly separated

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry Points
    subgraph "Entry Points"
        direction TB
        NB_auto["Automated Notebook"]:::entry
        NB_non["Non-Automated Notebook"]:::entry
        CLI["setup.py (CLI)"]:::entry
        README["README.md"]:::entry
    end

    %% ScienceDiscovery Package Modules
    subgraph "ScienceDiscovery Package"
        direction TB
        PKG["__init__.py"]:::library
        GL["graph.py<br/>Graph Loader"]:::library
        EM["utils.py<br/>Embedding & Utils"]:::library
        LM["llm_config.py<br/>LLM Config"]:::library
        AM["agents.py<br/>Agent Orchestrator"]:::library
    end

    %% Storage
    subgraph "Storage"
        direction TB
        LocalCache["Local Cache"]:::storage
        HFA["Hugging Face Hub"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI API"]:::external
        SemSch["Semantic Scholar API"]:::external
        AG2["AG2 Framework"]:::external
    end

    %% Output
    subgraph "Output"
        direction TB
        JSON["JSON Draft"]:::output
        PDF["PDF/HTML Report<br/>wkhtmltopdf"]:::output
    end

    %% Connections
    NB_auto -->|"import & configure"| PKG
    NB_non -->|"import & configure"| PKG
    CLI -->|"install & entry"| PKG
    README -->|"reference"| PKG

    PKG -->|"initialize modules"| GL
    PKG -->|"initialize modules"| EM
    PKG -->|"initialize modules"| LM
    PKG -->|"initialize modules"| AM

    GL -->|"load .graphml"| LocalCache
    GL -->|"load .graphml"| HFA
    GL -->|"subgraph sampling"| AM

    EM -->|"fetch embeddings"| HFA

    AM -->|"invoke LLM"| LM
    AM -->|"retrieve metadata"| SemSch
    AM -->|"orchestrate agents"| AG2

    LM -->|"call LLM"| OpenAI
    LM -->|"call LLM"| AG2

    AM -->|"produce JSON"| JSON
    JSON -->|"format & save"| EM
    EM -->|"generate PDF"| PDF

    %% Click Events
    click NB_auto "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/Notebooks/SciAgents_ScienceDiscovery_GraphReasoning_automated.ipynb"
    click NB_non "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/Notebooks/SciAgents_ScienceDiscovery_GraphReasoning_non-automated.ipynb"
    click CLI "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/setup.py"
    click README "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/README.md"
    click PKG "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/ScienceDiscovery/__init__.py"
    click GL "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/ScienceDiscovery/graph.py"
    click EM "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/ScienceDiscovery/utils.py"
    click LM "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/ScienceDiscovery/llm_config.py"
    click AM "https://github.com/lamm-mit/sciagentsdiscovery/blob/main/ScienceDiscovery/agents.py"

    %% Styles
    classDef library fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#333,stroke-width:1px
    classDef entry fill:#FFA500,stroke:#333,stroke-width:1px
    classDef output fill:#FFD700,stroke:#333,stroke-width:1px
```
