# mehradans92/dziner architecture

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

## Overview

##### Project type and purpose
- dZiner is a Python-based, full-stack scientific library for rational inverse design of materials.
- It orchestrates AI agents (LLMs + retrieval), domain knowledge from literature, surrogate property predictors, and optional human feedback into a closed-loop design workflow.

##### File structure
- Top-level:
- dziner/          ← core package (agents, prompts, scoring, surrogates, tools, utils)
- docs/            ← Sphinx documentation source & build config
- examples/        ← Jupyter notebooks as user-facing clients
- gui/             ← minimal Python GUI entry point
- data/papers/     ← local PDF corpus for retrieval‐augmented generation (RAG)
- dziner/surrogates/ ← plugin folders for each surrogate model (CMC, Binding, MOFormer, docking, peptides)
- tests/           ← unit tests that exercise core functionality and fake LLM
- .github/workflows ← CI for docs build and tests
- setup.py, requirements.txt ← packaging & dependencies

##### README for additional insights
- Workflow stages:
a. Input material representation (as text)
b. Dynamic retrieval of design guidelines (RAG via FAISS index over data/papers + Internet)
c. Candidate generation & chemical feasibility check (via docking or SAS scorer)
d. Property estimation via surrogate model (+ uncertainty)
e. Optional human-in-the-loop feedback → modifies constraints or candidates
f. Iteration until convergence

##### Main components & interactions
a. User Interface Layer
- Jupyter notebooks & CLI (examples/)
- GUI app.py
b. Core Agent Layer (dziner package)
- agents.py: orchestrates workflow
- prompts.py: templating for LLM calls
- sascorer.py: synthetic accessibility scoring
- tools.py & utils.py: shared utilities
c. Retrieval Service
- FAISS index built over data/papers/
- External knowledge (web/API calls)
d. Language Model Providers
- OpenAI, Anthropic (via environment-keyed APIs)
e. Surrogate Model Plugins
- Each folder under dziner/surrogates: CMC, Binding, MOFormer, peptides, docking
- Each plugin supplies model loading, inference API
f. Data & Model Storage
- Local: PDF corpus, surrogate model weights/configs
- Remote: Optional external data sources
g. Results & Paper Outputs
- paper/results/: CSV outputs per benchmark
h. Documentation & CI/CD
- docs/: Sphinx static site
- .github/workflows: test.yml, docs.yml

##### Architectural patterns & design principles
- Modular, plugin-based surrogate architecture (each surrogate is a drop-in folder)
- Clear separation of concerns: UI ←→ Controller (agents) ←→ Services (LLM, RAG, Surrogates) ←→ Data
- Retrieval-Augmented Generation (RAG) for domain knowledge
- Iterative, closed-loop control pattern with optional human feedback

##### Essential elements to capture
- Component labels & module paths

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        NB["Jupyter Notebooks"]:::code
        GUI["GUI (gui/app.py)"]:::code
    end

    %% Core Agent Controller
    subgraph "Core Agent Controller"
        Agent["Agent Controller (dziner/agents.py)"]:::code
        Prompts["Prompt Templating (dziner/prompts.py)"]:::code
        Tools["Tools (dziner/tools.py)"]:::code
        Utils["Utils (dziner/utils.py)"]:::code
        SAS["SAS Scorer (dziner/sascorer.py)"]:::code
        SASData["SAS Data (dziner/sascorer_data/)"]:::storage
    end

    %% Retrieval Service
    subgraph "Retrieval Service"
        RAG["RAG Service (FAISS)"]:::service
        PDF["PDF Corpus"]:::storage
        Web["External Internet"]:::external
    end

    %% LLM Providers
    subgraph "LLM Providers"
        OAI["OpenAI"]:::external
        ANT["Anthropic"]:::external
    end

    %% Surrogate Plugins
    subgraph "Surrogate Plugins"
        CMC["CMC"]:::plugin
        BIND["Binding"]:::plugin
        MOF["MOFormer"]:::plugin
        DOCK["Docking"]:::plugin
        PEP["Peptides"]:::plugin
    end

    %% Results Storage
    RES["Paper Results (paper/results/)"]:::storage

    %% Human Feedback
    HUM["Human-in-the-Loop"]:::external

    %% Documentation & CI/CD
    subgraph "CI/CD"
        CI1["Test Workflow (test.yml)"]:::code
        CI2["Docs Workflow (docs.yml)"]:::code
    end
    Docs["Documentation (docs/)"]:::code
    TEST["Unit Tests (tests/)"]:::code

    %% Data Flows
    NB -->|uses| Agent
    GUI -->|uses| Agent

    Agent -->|templates| Prompts
    Agent -->|retrieves| RAG
    RAG -->|indexes| PDF
    RAG -->|fetches| Web

    Agent -->|calls| OAI
    Agent -->|calls| ANT

    Agent -->|scores| SAS
    SAS -->|reads| SASData

    Agent -->|invokes| CMC
    Agent -->|invokes| BIND
    Agent -->|invokes| MOF
    Agent -->|invokes| DOCK
    Agent -->|invokes| PEP

    CMC -->|returns| Agent
    BIND -->|returns| Agent
    MOF -->|returns| Agent
    DOCK -->|returns| Agent
    PEP -->|returns| Agent

    Agent -->|stores| RES
    RES -->|view results| NB

    Agent ---|feedback| HUM
    HUM ---|adjusts| Agent

    CI1 -->|runs| TEST
    CI2 -->|builds| Docs
    TEST -->|verifies| Agent
    Docs -->|publishes| Docs

    %% Click Events
    click NB "https://github.com/mehradans92/dziner/tree/main/examples/"
    click GUI "https://github.com/mehradans92/dziner/blob/main/gui/app.py"
    click Agent "https://github.com/mehradans92/dziner/blob/main/dziner/agents.py"
    click Prompts "https://github.com/mehradans92/dziner/blob/main/dziner/prompts.py"
    click Tools "https://github.com/mehradans92/dziner/blob/main/dziner/tools.py"
    click Utils "https://github.com/mehradans92/dziner/blob/main/dziner/utils.py"
    click SAS "https://github.com/mehradans92/dziner/blob/main/dziner/sascorer.py"
    click SASData "https://github.com/mehradans92/dziner/tree/main/dziner/sascorer_data/"
    click PDF "https://github.com/mehradans92/dziner/tree/main/data/papers/"
    click CMC "https://github.com/mehradans92/dziner/tree/main/dziner/surrogates/CMC/"
    click BIND "https://github.com/mehradans92/dziner/tree/main/dziner/surrogates/Binding/"
    click MOF "https://github.com/mehradans92/dziner/tree/main/dziner/surrogates/MOFormer/"
    click DOCK "https://github.com/mehradans92/dziner/tree/main/dziner/surrogates/docking/"
    click PEP "https://github.com/mehradans92/dziner/tree/main/dziner/surrogates/peptides/"
    click RES "https://github.com/mehradans92/dziner/tree/main/paper/results/"
    click CI1 "https://github.com/mehradans92/dziner/blob/main/.github/workflows/test.yml"
    click CI2 "https://github.com/mehradans92/dziner/blob/main/.github/workflows/docs.yml"
    click TEST "https://github.com/mehradans92/dziner/tree/main/tests/"
    click Docs "https://github.com/mehradans92/dziner/tree/main/docs/"

    %% Styles
    classDef code fill:#D6EFFF,stroke:#0366D6
    classDef storage fill:#E6FFED,stroke:#22863A
    classDef external fill:#FFE6CC,stroke:#D15704
    classDef service fill:#FFF5B1,stroke:#BF8614
    classDef plugin fill:#F0D6FF,stroke:#6F42C1
```
