# qixucen/atom architecture

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

- Interactive diagram: https://gitdiagram.com/qixucen/atom
- Repository: https://github.com/qixucen/atom

## Overview

##### Project Type and Purpose
- The project is a research/experiment framework focused on improving LLM reasoning by decomposing tasks into atomic questions.
- It is an LLM-enhancement tool that works with multiple reasoning datasets (math, gsm8k, hotpotqa, etc.) and supports two operational modes: “atom” for direct reasoning and “plugin” for pre-processing integration with alternate test-time scaling frameworks.
- The README emphasizes reproducibility, resource efficiency, general reasoning capabilities, and eventual integration with external frameworks (for instance, MetaGPT).

##### File Structure
- Top-level files like main.py and llm.py define the control flow and LLM interactions.
- The experiment directory holds core components:
- experiment/dataset.py for dataset loading and pre-processing.
- experiment/module.py, which likely encapsulates the atomic reasoning logic.
- experiment/utils.py for common utilities.
- The experiment/data directory is organized by dataset names (e.g., bbh, gsm8k, hotpotqa, etc.), each containing a test.json, which suggests that the framework is dataset-agnostic and can evaluate performance across various reasoning tasks.
- The experiment/prompter directory contains specialized prompt implementations (e.g., math.py, multichoice.py, multihop.py) that likely define how questions are decomposed, in line with the atomic state concept.
- Additional configuration files (like requirements.txt and sample API key instructions in README) show how dependencies and API settings are managed.

##### Main Components
a. Command-Line Interface / Entry Point:
– main.py: The central entry point that parses command-line arguments (dataset selection, example range, LLM model, and mode).
b. Data Management Layer:
– experiment/data: Dataset files for different reasoning tasks.
– experiment/dataset.py: Manages data ingestion and formatting.
c. Core Reasoning Engine:
– experiment/module.py: Implements the main logic for processing atomic states based on the Markov process.
d. Prompt Generation Subsystem:
– experiment/prompter: Contains modules (math.py, multichoice.py, multihop.py) that generate specific prompts according to the task, which is critical for guiding LLM output.
e. LLM Interface:
– llm.py: Handles communication with the language model and external API interactions.
f. Utility Functions:
– experiment/utils.py: Contains common functions used across modules.
g. API Configuration:
– Although not in the repository, the README instructs users to create an apikey.py, which configures the API endpoint and keys for accessing the LLM service.

##### Relationships and Data Flow
– The entry point (main.py) parses parameters and directs the flow:
- It selects the dataset from experiment/data via the dataset.py module.
- It calls functions from module.py to start the reasoning process.
- Within the reasoning process, the correct prompt generator (from experiment/prompter) is invoked based on the task type (math, multichoice, multihop).
- The LLM interface (llm.py) sends the assembled prompt and receives the LLM output.
- Input from the command-line to main.py.
- Data ingestion from experiment/data → dataset.py.
- Processing flow from main.py → module.py → prompter modules.
- Interaction between module.py and llm.py (showing API calls).
- Output processing with possible feedback loops (especially if in “atom” mode the reasoning progresses step-by-step).

##### Architectural Patterns and Design Principles
– The architecture is modular – separating data handling, prompt-generation, core reasoning logic, and LLM interfacing.
– The design suggests a pipeline/flow-based architecture where data moves sequentially through input, processing, and output stages.
– Atomic decomposition indicates that the project uses a hierarchical (Markov) state-based design, where each atomic question might lead to further subquestions or state transitions.
– A plugin mechanism is provided (via the “plugin” mode) emphasizing extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level Layer: CLI and Utilities
    A["CLI (main.py)"]:::cliStyle
    U["Utility Functions (experiment/utils.py)"]:::utilStyle

    %% Data Management Layer
    subgraph "Data Management Layer"
        B["Dataset Loader (experiment/dataset.py)"]:::dataStyle
        C["Datasets (experiment/data)"]:::dataStyle
    end

    %% Core Reasoning Engine Layer
    subgraph "Core Reasoning Engine"
        D["Atomic Reasoning Engine (experiment/module.py)"]:::engineStyle
    end

    %% Prompt Generation Subsystem Layer
    subgraph "Prompt Generation Subsystem"
        E["Prompt Generators (experiment/prompter)"]:::promptStyle
        E1["Prompt: math module (experiment/prompter/math.py)"]:::promptStyle
        E2["Prompt: multichoice module (experiment/prompter/multichoice.py)"]:::promptStyle
        E3["Prompt: multihop module (experiment/prompter/multihop.py)"]:::promptStyle
    end

    %% LLM Interaction Layer
    subgraph "LLM Interface"
        F["LLM Interface (llm.py)"]:::llmStyle
    end

    %% API Configuration Note (as a note)
    G["API Config (apikey.py)"]:::noteStyle

    %% Connections - main flow
    A -->|"triggers"| B
    B -->|"loads data from"| C
    C -->|"feeds"| D
    A -->|"initiates"| D
    D -->|"calls"| E
    E -->|"selects prompt"| E1
    E -->|"selects prompt"| E2
    E -->|"selects prompt"| E3
    E1 -->|"sends prompt to"| F
    E2 -->|"sends prompt to"| F
    E3 -->|"sends prompt to"| F
    F -->|"returns output to"| D

    %% Utility Functions support (dashed arrows)
    B ---|"utilizes"| U
    D ---|"utilizes"| U
    E ---|"utilizes"| U

    %% API configuration connection (dotted arrow)
    G ---|"configures"| F

    %% Click Events
    click A "https://github.com/qixucen/atom/blob/main/main.py"
    click B "https://github.com/qixucen/atom/blob/main/experiment/dataset.py"
    click C "https://github.com/qixucen/atom/tree/main/experiment/data"
    click D "https://github.com/qixucen/atom/blob/main/experiment/module.py"
    click E "https://github.com/qixucen/atom/tree/main/experiment/prompter"
    click E1 "https://github.com/qixucen/atom/blob/main/experiment/prompter/math.py"
    click E2 "https://github.com/qixucen/atom/blob/main/experiment/prompter/multichoice.py"
    click E3 "https://github.com/qixucen/atom/blob/main/experiment/prompter/multihop.py"
    click F "https://github.com/qixucen/atom/blob/main/llm.py"
    click U "https://github.com/qixucen/atom/blob/main/experiment/utils.py"

    %% Styles
    classDef cliStyle fill:#a29bfe,stroke:#2d3436,stroke-width:2px;
    classDef dataStyle fill:#ffeaa7,stroke:#2d3436,stroke-width:2px;
    classDef engineStyle fill:#55efc4,stroke:#2d3436,stroke-width:2px;
    classDef promptStyle fill:#fdcb6e,stroke:#2d3436,stroke-width:2px;
    classDef llmStyle fill:#74b9ff,stroke:#2d3436,stroke-width:2px;
    classDef utilStyle fill:#fab1a0,stroke:#2d3436,stroke-width:2px;
    classDef noteStyle fill:#dfe6e9,stroke:#b2bec3,stroke-dasharray: 5 5,stroke-width:2px;
```
