How ai4chems/eunomia works
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)