# wenlinyao/hdflow architecture

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

- Interactive diagram: https://gitdiagram.com/wenlinyao/hdflow
- Repository: https://github.com/wenlinyao/hdflow

## Overview

##### Project type and purpose
- This is a research-oriented Python codebase (“HDFlow”) that orchestrates experiments for the paper “HDFlow: Enhancing LLM Complex Problem-Solving with Hybrid Thinking and Dynamic Workflows.”
- It is not a classic web app; instead, it is an orchestration pipeline that:
- Loads/preprocesses mathematical and logic datasets
- Runs “fast thinking” and “slow thinking” passes via LLMs (OpenAI, Anthropic or locally-hosted via vLLM)
- Combines those into “hybrid thinking” trajectories
- Emits results for analysis

##### File-structure analysis
- data/ → raw and intermediate datasets (CSV, JSON) and preprocessing scripts (split.py, process_data.py)
- scripts/ → ancillary scripts for model conversion and vLLM configuration
- src/ → core Python modules:
- hdflow.py & hdflow_hybrid.py (experiment orchestrators)
- load_datasets.py (data I/O)
- model_api.py (abstracts calls to LLM providers)
- experts.py, math_equivalence.py, utils.py, monitor_memory_usage.py, local_exec.py (utility and helper functions)
- src/prompts/ (text‐prompt templates for different reasoning stages)

##### Key README insights
- The pipeline is invoked via CLI (python hdflow.py …, python hdflow_hybrid.py …)
- Supports multiple backends: OpenAI, Azure, Anthropic, and self-hosted Llama-3 via vLLM
- Uses standard Python data libraries (pandas, datasets, tqdm)

##### Main components
A. Data Layer
- Raw Datasets (GameOf24.csv, MetaMathQA JSONs, MathInstruct JSONs)
- Preprocessing Scripts (data/process_data.py, data/split.py)
B. Orchestration Layer (src/)
- Experiment Runner #1: hdflow.py (“fast” & “slow” thinking)
- Experiment Runner #2: hdflow_hybrid.py (“hybrid thinking after”)
- Data Loader: load_datasets.py
- Prompt Manager: src/prompts/ (folders with text templates)
- Utilities: experts.py (LLM chain logic), math_equivalence.py, utils.py, monitor_memory_usage.py, local_exec.py
- Model API Adapter: model_api.py
C. External/Infrastructure Services
- OpenAI/Anthropic API endpoints (cloud)
- Azure OpenAI endpoint (if configured)
- vLLM‐based local Llama‐3 server(s) on custom ports
D. Output Layer
- Solution files / logs (JSON or text results stored by hdflow scripts)
- Training data outputs for hybrid tuning

##### Relationships and data flow
1. CLI input → calls hdflow.py or hdflow_hybrid.py
2. Runner loads dataset via load_datasets.py
3. For each problem instance:
a. Select prompt(s) from src/prompts/
b. Call model_api.py, which dispatches to cloud APIs or local vLLM
c. experts.py encapsulates reasoning steps (fast vs slow chain)
d. monitor_memory_usage.py tracks resource usage
4. Runner writes intermediate outputs (fast_thinking.json, slow_thinking.json)
5. hdflow_hybrid.py ingests those outputs and merges into hybrid_thinking trajectories
6. Final results persist for evaluation

##### Architectural patterns and principles
- Modular orchestration: each runner script delegates to specialized modules
- Adapter pattern in model_api.py for pluggable LLM backends
- Separation of concerns: data I/O, prompting, reasoning logic, and resource monitoring are decoupled
- Reusable prompt library under src/prompts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        subgraph "Raw Datasets"
            Game["GameOf24.csv"]:::dataLayer
            MathIns["MathInstruct/"]:::dataLayer
            MetaMath["MetaMathQA/"]:::dataLayer
        end
        subgraph "Preprocessing Scripts"
            Proc["process_data.py"]:::code
            Split["split.py"]:::code
        end
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Runner1["hdflow.py"]:::code
        Runner2["hdflow_hybrid.py"]:::code
        Loader["load_datasets.py"]:::code
        Prompts["src/prompts/"]:::code
        API["model_api.py"]:::code
        subgraph "Utilities"
            Exp["experts.py"]:::code
            Eq["math_equivalence.py"]:::code
            Utils["utils.py"]:::code
            Mem["monitor_memory_usage.py"]:::code
            Local["local_exec.py"]:::code
        end
    end

    %% External Services
    subgraph "External Services"
        OA["OpenAI/Anthropic API"]:::external
        AZ["Azure OpenAI"]:::external
        vLLM["vLLM Local Llama-3"]:::external
    end

    %% Infrastructure Scripts
    subgraph "Infra Scripts"
        Conv["model_convert_new.py"]:::code
        Config["alphaflow_llama-3-8b-instruct_v10_newconfig.yaml"]:::code
    end

    %% Output Layer
    subgraph "Output Layer"
        Sol["Solution Files / Logs"]:::output
        Train["Training Data Outputs"]:::output
    end

    %% CLI
    CLI["CLI Input"]:::code

    %% Connections
    CLI --> Runner1
    CLI --> Runner2
    Game --> Loader
    MathIns --> Loader
    MetaMath --> Loader
    Loader --> Runner1
    Loader --> Runner2
    Runner1 --> Prompts
    Runner2 --> Prompts
    Prompts --> API
    API --> OA
    API --> AZ
    API --> vLLM
    OA --> API
    AZ --> API
    vLLM --> API
    Runner1 --> Exp
    Runner1 --> Mem
    Runner1 --> API
    Runner2 --> Exp
    Runner2 --> API
    Runner1 --> Sol
    Runner2 --> Train

    %% Click Events
    click Game "https://github.com/wenlinyao/hdflow/blob/main/data/GameOf24.csv"
    click MathIns "https://github.com/wenlinyao/hdflow/tree/main/data/MathInstruct/"
    click MetaMath "https://github.com/wenlinyao/hdflow/tree/main/data/MetaMathQA/"
    click Proc "https://github.com/wenlinyao/hdflow/blob/main/data/MathInstruct/process_data.py"
    click Split "https://github.com/wenlinyao/hdflow/blob/main/data/MetaMathQA/split.py"
    click Runner1 "https://github.com/wenlinyao/hdflow/blob/main/src/hdflow.py"
    click Runner2 "https://github.com/wenlinyao/hdflow/blob/main/src/hdflow_hybrid.py"
    click Loader "https://github.com/wenlinyao/hdflow/blob/main/src/load_datasets.py"
    click Prompts "https://github.com/wenlinyao/hdflow/tree/main/src/prompts/"
    click API "https://github.com/wenlinyao/hdflow/blob/main/src/model_api.py"
    click Exp "https://github.com/wenlinyao/hdflow/blob/main/src/experts.py"
    click Eq "https://github.com/wenlinyao/hdflow/blob/main/src/math_equivalence.py"
    click Utils "https://github.com/wenlinyao/hdflow/blob/main/src/utils.py"
    click Mem "https://github.com/wenlinyao/hdflow/blob/main/src/monitor_memory_usage.py"
    click Local "https://github.com/wenlinyao/hdflow/blob/main/src/local_exec.py"
    click Conv "https://github.com/wenlinyao/hdflow/blob/main/scripts/model_convert_new.py"
    click Config "https://github.com/wenlinyao/hdflow/blob/main/scripts/alphaflow_llama-3-8b-instruct_v10_newconfig.yaml"

    %% Styles
    classDef dataLayer fill:#88cc88,stroke:#2d662d,color:#000;
    classDef code fill:#88aaff,stroke:#1f3f7a,color:#000;
    classDef external fill:#ffcc88,stroke:#7a511a,color:#000;
    classDef output fill:#cc88ff,stroke:#602d7a,color:#000;
```
