# ai4chems/eunomia architecture

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

## Overview

##### Project Type & Purpose
- Eunomia is a Python package that implements an AI-powered “agent chemist,” designed to extract and curate materials data from scientific documents using an iterative Chain-of-Verification (CoV) process.
- It ships as a PyPI library (`materials-eunomia`), includes Jupyter‐based examples, and supports a Streamlit app (hosted externally).

##### File Structure
- Top-level packaging/CI:
- setup.py, setup.cfg, requirements.txt, MANIFEST.in
- .github/workflows/test.yml, tox.ini, .travis.yml
- Core library (`eunomia/`):
- eunomia.py – CLI / entry point and high-level orchestrator
- agents.py – implements the chain-of-verification orchestrator
- parser.py – document ingestion & parsing (pdf, md, txt → structured text)
- prompts.py – prompt templates for LLM interactions
- tools.py – domain-specific tools (e.g., chemical structure extraction)
- general.py – utility functions (logging, configuration)
- docs_utils/ – Sphinx helpers for generating documentation artifacts
- Examples & data:
- examples/*.ipynb – usage demos (other LLMs, case studies)
- data/case-study-3-ground-truth.csv – sample ground truth dataset
- Tests:
- tests/*.py – unit tests for docs, core functionality, tools; test fixtures under tests/test_files
- Documentation:
- docs/ – Sphinx sources (configuration, usage, installation, changelog)

##### Extract Readme Insights
- Architecture: iterative Chain-of-Verification looping between “plan → act → verify” to reduce hallucination.
- External dependency: OpenAI’s GPT-4 (configurable to other LLMs).
- Deployment: package can be installed via pip; CI tests with pytest & GitHub Actions; live Streamlit app at eunomia.streamlit.app.

##### Main Components & Relationships
a. Core Modules (internal)
- Entry Point (CLI): `eunomia/eunomia.py`
- Agent Orchestrator: `agents.py` – coordinates planning, execution, verification loops
- Document Parser: `parser.py` – ingests documents → cleansed text & metadata
- Prompt Templates: `prompts.py` – constructs messages for LLM API calls
- Tools Layer: `tools.py` – executes domain actions (e.g., chemical formula checks, unit conversions)
- Utilities: `general.py` – logging, config loading
- Docs Utilities: `docs_utils/` – Sphinx extensions for auto-generated docs
b. Data Stores & Artifacts
- Input Documents (PDF, MD, TXT) on local FS or user-provided
- Vector Store (e.g., serialized pickles under tests) for embedding retrieval
- Ground-truth CSV (for benchmarking)
- Generated Outputs: structured datasets, reports
c. External Services
- OpenAI API (GPT-4 or configurable model)
- (Optional) Streamlit hosting for interactive UI
d. CI/CD & Packaging
- GitHub Actions & Travis CI for build/test
- PyPI distribution via setup.py
- Sphinx docs build under docs/

##### Architectural Patterns & Design Principles
- Modular pipeline: each phase (parse → plan → act → verify → output) isolated into its own module.
- Dependency Injection: prompt templates + tools injected into agent orchestrator.
- Extensibility: new Tools or Prompts can be added by dropping modules in `eunomia/tools.py` or `prompts.py`.
- Separation of concerns: parsing, LLM orchestration, domain logic, and docs generation are clearly partitioned.

##### Detailed Elements
- Entry point (CLI) and how it initializes configuration & logging
- The iterative CoV loop inside the Agent Orchestrator
- Interaction between Prompt Templates and the OpenAI API
- Tools module invoking domain-specific checks
- Data persistence (vector store read/write, ground truth comparison)
- Sphinx documentation flow (code + `docs_utils` → built docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Library
    subgraph "Core Library"
        direction TB
        CLI["Entry Point (CLI)"]:::internal
        Parser["Document Parser"]:::internal
        Orchestrator["Agent Orchestrator"]:::internal
        Prompts["Prompt Templates"]:::internal
        Tools["Tools Layer"]:::internal
        Utils["Utility Functions"]:::internal
        CLI -->|"invokes"| Parser
        CLI -->|"loads config & logging"| Utils
        Parser -->|"text chunks"| Orchestrator
        Orchestrator -->|"uses prompts"| Prompts
        Orchestrator -->|"calls tools"| Tools
        Orchestrator -->|"iterative CoV loop"| Orchestrator
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI[/"OpenAI API (GPT-4)"/]:::external
        Streamlit["Streamlit App"]:::external
    end
    Orchestrator -->|"prompt JSON"| OpenAI
    OpenAI -->|"LLM response"| Orchestrator
    CLI -->|"optional UI"| Streamlit

    %% Data Stores & Artifacts
    subgraph "Data Stores & Artifacts"
        direction TB
        VectorStore["Vector Store"]:::data
        GroundTruth["Ground-Truth CSV"]:::data
        Outputs["Generated Outputs"]:::data
        Orchestrator -->|"reads/writes embeddings"| VectorStore
        Orchestrator -->|"benchmarks with"| GroundTruth
        Orchestrator -->|"produces"| Outputs
    end

    %% Documentation
    subgraph "Documentation Pipeline"
        direction TB
        Code["Codebase"]:::internal
        DocsUtils["Docs Utilities"]:::docs
        SphinxSource["Sphinx Docs Source"]:::docs
        BuiltDocs["Built Documentation"]:::docs
        Code -->|"annotations"| DocsUtils
        DocsUtils -->|"generates"| SphinxSource
        SphinxSource -->|"build"| BuiltDocs
    end

    %% Examples & Tests
    subgraph "Examples & Tests"
        direction TB
        Examples["Example Notebooks"]:::example
        TestEunomia["Unit Test: test_eunomia.py"]:::test
        TestTools["Unit Test: test_tools.py"]:::test
        TestDocs["Unit Test: test_docs.py"]:::test
        VectorStore --> Examples
        CLI --> Examples
        CLI --> TestEunomia
        Tools --> TestTools
        DocsUtils --> TestDocs
    end

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        direction TB
        Workflows["CI Workflows"]:::ci
        Packaging["Packaging & Metadata"]:::ci
        Workflows -->|"run tests"| TestEunomia
        Workflows --> TestTools
        Workflows --> TestDocs
        Packaging -->|"publishes to PyPI"| CLI
    end

    %% Click Events
    click CLI "https://github.com/ai4chems/eunomia/blob/main/eunomia/eunomia.py"
    click Parser "https://github.com/ai4chems/eunomia/blob/main/eunomia/parser.py"
    click Orchestrator "https://github.com/ai4chems/eunomia/blob/main/eunomia/agents.py"
    click Prompts "https://github.com/ai4chems/eunomia/blob/main/eunomia/prompts.py"
    click Tools "https://github.com/ai4chems/eunomia/blob/main/eunomia/tools.py"
    click Utils "https://github.com/ai4chems/eunomia/blob/main/eunomia/general.py"
    click DocsUtils "https://github.com/ai4chems/eunomia/blob/main/eunomia/docs_utils/docs.py"
    click Examples "https://github.com/ai4chems/eunomia/tree/main/examples/"
    click GroundTruth "https://github.com/ai4chems/eunomia/blob/main/data/case-study-3-ground-truth.csv"
    click VectorStore "https://github.com/ai4chems/eunomia/blob/main/tests/test_files/test_vector_store.pkl"
    click Workflows "https://github.com/ai4chems/eunomia/blob/main/.github/workflows/test.yml"
    click Packaging "https://github.com/ai4chems/eunomia/blob/main/setup.py"
    click SphinxSource "https://github.com/ai4chems/eunomia/tree/main/docs/"
    click TestEunomia "https://github.com/ai4chems/eunomia/blob/main/tests/test_eunomia.py"
    click TestTools "https://github.com/ai4chems/eunomia/blob/main/tests/test_tools.py"
    click TestDocs "https://github.com/ai4chems/eunomia/blob/main/tests/test_docs.py"

    %% Styles
    classDef internal fill:#cce5ff,stroke:#0062cc,color:#004085
    classDef data fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef docs fill:#e2e3e5,stroke:#b1b1b1,color:#383d41
    classDef example fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef test fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef ci fill:#f0f0f0,stroke:#999999,color:#333333,stroke-dasharray: 5 5
```
