# yeonghun1675/chatmof architecture

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

## Overview

##### Project Type and Purpose
- ChatMOF is an open-source, Python-based AI toolkit (CLI + library) for metal-organic framework (MOF) search, prediction, and generation.
- It is not a web full-stack app but a command-line application and library that orchestrates a planning “Agent,” a set of “Toolkits,” and an “Evaluator,” backed by external LLMs and local data.

##### High-Level Architecture from File Structure & README
- Top-level CLI layer (chatmof/cli) provides commands: install-griday, setup, run, etc.
- Core package “chatmof”:
– agents/ : orchestrates the plan (Agent) → agent.py, prompt templates → prompt.py
– llm/ : wrappers for OpenAI, LLaMA, CodeLlama (API clients, utils)
– tools/ : individual tool adapters (search_csv, predictor, genetic_algorithm, ase_repl, unit_converter, visualizer, python_repl, etc.)
– database/ : Excel-based tables, structure loaders, MOF data structures
– evaluator: post-processes and formats final responses
– config.py, utils.py, setup_module.py hold shared settings and initialization code.
- External services:
– LLM APIs (OpenAI, local LLaMA model via HuggingFace)
– Google Search (optional)
– GRIDAY for MOF generation
– MOFTransformer and PyTorch Lightning for ML-based prediction

##### Main Components & Their Interactions
A. User Interface / CLI Layer
- chatmof run (or streamlit app) invokes the ChatMOF application entrypoint (app.py → main.py).
- Passes user query, options (model name, temperature).
B. Agent Layer
- The Agent module reads the query, constructs a plan via prompt templates, and decides which Toolkit(s) to invoke.
- Sequence: receive user input → generate “plan” (e.g., “search CSV → parse results”) → dispatch to Toolkit.
C. Toolkit Layer
- Each Toolkit implements a standardized interface:
– base.py defines how to receive plan instructions and call LLM or local logic
– prompt.py holds tool-specific prompt templates
– tool.py orchestrates data retrieval, LLM calls, or local computations
- Toolkits may interact with:
– database module for structure lookup or parameter loading
– llm module for LLM calls
– external packages (ase_repl, GRIDAY, unit converter)
D. LLM Service Layer
- llm/openai.py, llama.py, codellama.py expose API methods to send prompts and get completions.
E. Data Layer
- database/tables/*.xlsx and database/structures core load static MOF data into in-memory Python objects.
F. Evaluator Layer
- evaluator (in main or in app.py) collects toolkit outputs, runs validation, scoring, and composes the final user response.
G. External Dependencies
- OpenAI API, HuggingFace models, Google Search API, GRIDAY library, MOFTransformer (PyTorch), etc.

##### Architectural Patterns & Design Principles
- Modular “Agent–Tool” pipeline: Agent is a dispatcher, Toolkits are interchangeable plugins.
- Interface segregation: each toolkit implements a common interface (inherit from base classes).
- Dependency injection: llm wrappers and database loaders are injected into toolkits via config.
- Separation of concerns: CLI, agent logic, tool implementations, data, and evaluation are each in their own package.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Run["run.py"]:::control
        CLI_Setup["setup.py"]:::control
        CLI_Install["install_griday.py"]:::control
        CLI_Main["main.py"]:::control
    end

    %% Agent Layer
    subgraph "Agent Layer"
        Agent["agent.py"]:::control
        AgentPrompt["prompt.py"]:::control
    end

    %% Toolkit Layer
    subgraph "Toolkit Layer"
        ToolUtils["tool_utils.py"]:::plugin
        subgraph ASE_REPL["ase_repl"]
            ASE_Base["base.py"]:::plugin
            ASE_Prompt["prompt.py"]:::plugin
            ASE_Tool["tool.py"]:::plugin
        end
        subgraph Genetic["genetic_algorithm"]
            GA_Base["base.py"]:::plugin
            GA_Prompt["prompt.py"]:::plugin
            GA_Tool["tool.py"]:::plugin
            GA_CIF["cif_generate.py"]:::plugin
            GA_Algo["genetic_algorithm.py"]:::plugin
        end
        subgraph Predictor["predictor"]
            Pred_Base["base.py"]:::plugin
            Pred_Prompt["prompt.py"]:::plugin
            Pred_Tool["tool.py"]:::plugin
            Pred_Run["runner.py"]:::plugin
            Pred_DS["dataset.py"]:::plugin
            Pred_Utils["utils.py"]:::plugin
        end
        subgraph PythonREPL["python_repl"]
            PY_Base["base.py"]:::plugin
            PY_Tool["tool.py"]:::plugin
        end
        subgraph CSVSearch["search_csv"]
            CSV_Base["base.py"]:::plugin
            CSV_Prompt["prompt.py"]:::plugin
            CSV_Tool["tool.py"]:::plugin
        end
        subgraph UnitConverter["unit_converter"]
            UC_Base["base.py"]:::plugin
            UC_Prompt["prompt.py"]:::plugin
            UC_Tool["tool.py"]:::plugin
        end
        subgraph Visualizer["visualizer"]
            V_Base["base.py"]:::plugin
            V_Prompt["prompt.py"]:::plugin
            V_Tool["tool.py"]:::plugin
        end
    end

    %% LLM Service Layer
    subgraph "LLM Service Layer"
        LLM_OpenAI["openai.py"]:::plugin
        LLM_Llama["llama.py"]:::plugin
        LLM_CodeLlama["codellama.py"]:::plugin
        LLM_Utils["utils.py"]:::plugin
    end

    %% Data Layer
    subgraph "Database Layer"
        DB_LoadModel["load_model/"]:::data
        DB_Structures["structures/coremof/"]:::data
        DB_Tables["coremof.xlsx"]:::data
    end

    %% Evaluator Layer
    subgraph "Evaluator & Orchestration"
        App["app.py"]:::evaluation
        Main["main.py"]:::evaluation
        SetupMod["setup_module.py"]:::evaluation
        Config["config.py"]:::evaluation
        Utils["utils.py"]:::evaluation
    end

    %% External Services
    subgraph "External Services"
        Ext_OpenAI["OpenAI API"]:::external
        Ext_HF["HuggingFace LLaMA"]:::external
        Ext_Google["Google Search API"]:::external
        Ext_GRIDAY["GRIDAY Library"]:::external
        Ext_Transformer["MOFTransformer"]:::external
    end

    %% Connections
    User -->|"invokes"| CLI_Run
    User --> CLI_Main

    CLI_Run -->|calls| Agent
    CLI_Main -->|env setup| SetupMod
    Agent -->|uses| AgentPrompt
    Agent -->|dispatches to| ToolUtils
    Agent -->|"selects"| ASE_Base
    Agent -->|"selects"| GA_Base
    Agent -->|"selects"| Pred_Base
    Agent -->|"selects"| PY_Base
    Agent -->|"selects"| CSV_Base
    Agent -->|"selects"| UC_Base
    Agent -->|"selects"| V_Base

    %% Toolkit interactions
    ASE_Tool -->|calls| DB_LoadModel
    ASE_Tool -->|executes| Ext_GRIDAY
    GA_Tool -->|uses| GA_Algo
    GA_Tool -->|loads| DB_Tables
    Pred_Tool -->|calls| Ext_Transformer
    Pred_Tool -->|reads| DB_Structures
    PY_Tool -->|spawns| PythonREPL
    CSV_Tool -->|reads| DB_Tables
    UC_Tool -->|converts via| Ext_GRIDAY
    V_Tool -->|visualizes| DB_Structures

    %% Toolkit to LLM
    ASE_Tool -->|uses| LLM_OpenAI
    GA_Tool -->|uses| LLM_Llama
    Pred_Tool -->|uses| LLM_CodeLlama
    CSV_Tool -->|uses| LLM_OpenAI
    UC_Tool -->|uses| LLM_OpenAI
    V_Tool -->|uses| LLM_Utils

    %% LLM to external
    LLM_OpenAI -->|API call| Ext_OpenAI
    LLM_Llama -->|local model| Ext_HF
    LLM_CodeLlama -->|local model| Ext_HF

    %% Evaluation flow
    ASE_Tool -->|output| App
    GA_Tool -->|output| App
    Pred_Tool -->|output| App
    CSV_Tool -->|output| App
    UC_Tool -->|output| App
    V_Tool -->|output| App
    App -->|validates| Main
    Main -->|responds to| User

    %% Click Events
    click CLI_Run "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/cli/run.py"
    click CLI_Setup "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/cli/setup.py"
    click CLI_Install "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/cli/install_griday.py"
    click CLI_Main "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/cli/main.py"
    click Agent "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/agents/agent.py"
    click AgentPrompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/agents/prompt.py"
    click ToolUtils "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/tool_utils.py"
    click ASE_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/ase_repl/base.py"
    click ASE_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/ase_repl/prompt.py"
    click ASE_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/ase_repl/tool.py"
    click GA_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/genetic_algorithm/base.py"
    click GA_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/genetic_algorithm/prompt.py"
    click GA_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/genetic_algorithm/tool.py"
    click GA_CIF "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/genetic_algorithm/cif_generate.py"
    click GA_Algo "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/genetic_algorithm/genetic_algorithm.py"
    click Pred_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/base.py"
    click Pred_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/prompt.py"
    click Pred_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/tool.py"
    click Pred_Run "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/runner.py"
    click Pred_DS "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/dataset.py"
    click Pred_Utils "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/predictor/utils.py"
    click PY_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/python_repl/base.py"
    click PY_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/python_repl/tool.py"
    click CSV_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/search_csv/base.py"
    click CSV_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/search_csv/prompt.py"
    click CSV_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/search_csv/tool.py"
    click UC_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/unit_converter/base.py"
    click UC_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/unit_converter/prompt.py"
    click UC_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/unit_converter/tool.py"
    click V_Base "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/visualizer/base.py"
    click V_Prompt "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/visualizer/prompt.py"
    click V_Tool "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/tools/visualizer/tool.py"
    click LLM_OpenAI "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/llm/openai.py"
    click LLM_Llama "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/llm/llama.py"
    click LLM_CodeLlama "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/llm/codellama.py"
    click LLM_Utils "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/llm/utils.py"
    click DB_LoadModel "https://github.com/yeonghun1675/chatmof/tree/master/chatmof/database/load_model/"
    click DB_Structures "https://github.com/yeonghun1675/chatmof/tree/master/chatmof/database/structures/coremof/"
    click DB_Tables "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/database/tables/coremof.xlsx"
    click App "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/app.py"
    click Main "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/main.py"
    click SetupMod "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/setup_module.py"
    click Config "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/config.py"
    click Utils "https://github.com/yeonghun1675/chatmof/blob/master/chatmof/utils.py"

    %% Styles
    classDef control fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef plugin fill:#d4edda,stroke:#28a745,color:#000;
    classDef data fill:#fff3cd,stroke:#ffcc00,color:#000;
    classDef external fill:#f8d7da,stroke:#dc3545,color:#000;
    classDef evaluation fill:#e2e3e5,stroke:#6c757d,color:#000;
```
