# future-house/ether0 architecture

> Architecture diagram of the GitHub repository future-house/ether0, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/future-house/ether0
- Repository: https://github.com/future-house/ether0

## Overview

##### Project type and purpose
- This is an open-source Python library (“ether0”) providing:
- Verifiable reward functions for evaluating scientific reasoning LLMs (chemistry focus)
- Utilities for molecule handling and dataset prompts
- A separate “remotes” microservice for reward functions that require exotic dependencies or third-party models
- It is not a full-stack web app; it is a modular toolkit and CLI/microservice combination designed to integrate into LLM training/evaluation pipelines.

##### File structure
- Top-level directories:
- src/ether0 → core library modules (chat, clients, data, model_prompts, models, rewards, utils)
- packages/remotes → a standalone Python package with a server entrypoint (server.py) for remote reward evaluation
- docs → usage guides, Jupyter notebooks, static assets
- tests → unit tests for core modules; packages/remotes/tests covers the microservice
- Config files: pyproject.toml (build/config), .github/workflows (CI), uv.lock (locks dependencies for uv CLI), pre-commit config

##### README insights
- Describes a training loop (SFT → RLVR → sampling → etc.) but training code is external
- Core deliverables: reward functions (local and remote), data utilities, prompts, data models
- Usage patterns:
- Local Python API: import ether0.rewards, ether0.data, etc.
- Remote service: “ether0-serve” CLI exposing HTTP API for exotic-dependency rewards
- Integration with Hugging Face models and datasets

a. Main components
1. Core Library (src/ether0)
– Modules: Rewards, Data Utilities, Model Prompts, Chat/Client Interfaces, Utils
2. Remote Reward Service (packages/remotes)
– HTTP API (server.py), specialized reward functions requiring heavy deps
3. External Dependencies
– rdkit, third-party LLMs (Hugging Face Transformers, TRL, NeMo-RL)
– HF Model Hub & Dataset Hub
4. User / Consumer
– LLM training pipeline or batch evaluation script (e.g., lmi, aviary, custom)
5. CI/CD & Packaging
– GitHub Actions, pre-commit, pyproject metadata

b. Relationships & Data Flow
- The Consumer invokes local reward functions (ether0.rewards).
- If a reward requires exotic deps, the core library delegates via ether0.remotes.client → HTTP call → Remote Service → processes and returns reward.
- Data utilities (ether0.data) transform SMILES strings ↔ molecule drawings.
- Prompts (ether0.model_prompts, ether0.problem_prompts) generate LLM input.
- CI pipeline runs tests against both core and remotes, publishes packages to PyPI/HF.
- Hugging Face Hub: models and datasets are loaded at runtime by the client.

c. Architectural Patterns & Principles
- Modular packaging: core library is independent of exotic-dependency code
- Microservice separation: remote reward functions live in a separate package/server
- Clear layering: Data → Prompts → Model Interaction → Reward Calculation
- Dependency inversion: core library depends on a thin HTTP interface rather than on heavy deps

d. Key Technologies & Frameworks
- Python 3.11+, pyproject.toml/PEP-517 packaging
- FastAPI or similar (implicit) in server.py for HTTP API
- rdkit for chemistry utilities
- Hugging Face Transformers & Datasets APIs
- uv (University Versioning) CLI for local sync & packaging
- pytest for tests, GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Layer
    Consumer["Consumer Script / Pipeline"]:::consumer

    %% Core Library Layer
    subgraph "Core Library" 
        direction TB
        Rewards["Rewards Module"]:::core
        DataUtils["Data Utilities"]:::core
        ModelPrompts["Model Prompts"]:::core
        ProblemPrompts["Problem Prompts"]:::core
        Chat["Chat Interface"]:::core
        Clients["Client Interface (remotes HTTP)"]:::core
        Models["Data Models"]:::core
        Utils["Utility Functions"]:::core
        Fingerprints["Bloom Filters"]:::core
    end

    %% Remote Service Layer
    subgraph "Remote Reward Service" 
        direction TB
        Server["HTTP API Server"]:::remote
        RemotesProj["Remotes Package Metadata"]:::remote
        TestsRemote["Remote Service Tests"]:::remote
    end

    %% Documentation Layer
    subgraph "Documentation & Examples"
        direction TB
        DocsGuide["adding_tokens.ipynb"]:::docs
        DocsTemplate["updated_mistral_chat_template.jinja"]:::docs
        Assets["docs/assets"]:::docs
    end

    %% External Services
    ModelHub(["Hugging Face Model Hub"]):::external
    DatasetHub(["Hugging Face Dataset Hub"]):::external
    RDKit(["rdkit Chemistry Lib"]):::external

    %% CI/CD Layer
    subgraph "CI/CD & Packaging"
        direction TB
        ConfigRoot["pyproject.toml"]:::ci
        Workflow[".github/workflows/lint-test.yaml"]:::ci
        PreCommit[".pre-commit-config.yaml"]:::ci
        UVLock["uv.lock"]:::ci
    end

    %% Relationships
    Consumer -->|"invoke valid_mol_eval()"| Rewards
    Consumer -->|"draw_molecule()"| DataUtils
    Consumer -->|"generate prompts"| ModelPrompts
    Consumer -->|"generate prompts"| ProblemPrompts
    Consumer -->|"chat interactions"| Chat
    Consumer -->|"load_model()"| ModelHub
    Consumer -->|"load_dataset()"| DatasetHub

    Rewards -->|"requires exotic deps"| Clients
    Clients -->|"HTTP POST /reward"| Server
    Server -->|"return reward"| Clients
    Clients -->|"return result"| Rewards

    DataUtils -->|"use chemistry utils"| RDKit

    CI/CD & Packaging -->|runs tests on| Rewards
    CI/CD & Packaging -->|runs tests on| TestsRemote

    %% Click Events
    click Rewards "https://github.com/future-house/ether0/blob/main/src/ether0/rewards.py"
    click DataUtils "https://github.com/future-house/ether0/blob/main/src/ether0/data.py"
    click ModelPrompts "https://github.com/future-house/ether0/blob/main/src/ether0/model_prompts.py"
    click ProblemPrompts "https://github.com/future-house/ether0/blob/main/src/ether0/problem_prompts.py"
    click Chat "https://github.com/future-house/ether0/blob/main/src/ether0/chat.py"
    click Clients "https://github.com/future-house/ether0/blob/main/src/ether0/clients.py"
    click Models "https://github.com/future-house/ether0/blob/main/src/ether0/models.py"
    click Utils "https://github.com/future-house/ether0/blob/main/src/ether0/utils.py"
    click Fingerprints "https://github.com/future-house/ether0/blob/main/src/ether0/fingerprints.bloom"
    click Server "https://github.com/future-house/ether0/blob/main/packages/remotes/src/ether0/server.py"
    click RemotesProj "https://github.com/future-house/ether0/blob/main/packages/remotes/pyproject.toml"
    click TestsRemote "https://github.com/future-house/ether0/tree/main/packages/remotes/tests/"
    click DocsGuide "https://github.com/future-house/ether0/blob/main/docs/adding_tokens.ipynb"
    click DocsTemplate "https://github.com/future-house/ether0/blob/main/docs/updated_mistral_chat_template.jinja"
    click Assets "https://github.com/future-house/ether0/tree/main/docs/assets/"
    click ConfigRoot "https://github.com/future-house/ether0/blob/main/pyproject.toml"
    click Workflow "https://github.com/future-house/ether0/blob/main/.github/workflows/lint-test.yaml"
    click PreCommit "https://github.com/future-house/ether0/blob/main/.pre-commit-config.yaml"
    click UVLock "https://github.com/future-house/ether0/blob/main/uv.lock"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#084b8a,color:#084b8a;
    classDef remote fill:#fde4cf,stroke:#9c4221,color:#9c4221;
    classDef external fill:#d5e8d4,stroke:#82b366,color:#82b366;
    classDef consumer fill:#e0e0e0,stroke:#6e6e6e,color:#6e6e6e,stroke-dasharray: 5 5;
    classDef docs fill:#fff2cc,stroke:#b38f00,color:#b38f00;
    classDef ci fill:#e1bee7,stroke:#6a1b9a,color:#6a1b9a;
```
