# gen-verse/reasonflux architecture

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

- Interactive diagram: https://gitdiagram.com/gen-verse/reasonflux
- Repository: https://github.com/gen-verse/reasonflux

## Overview

##### Project Type and Purpose
- This is a multi‐module open-source framework for training, evaluating, and deploying “ReasonFlux” LLMs.
- It includes:
- ReasonFlux-v1: template-augmented SFT/RLHF training pipelines (with LLaMA-Factory)
- ReasonFlux-F1: evaluation harness built on lm-evaluation-harness (task definitions, metrics, logging)
- ReasonFlux-Coder: coding LLM inference scripts and template tools
- ReasonFlux-v2: template‐guided inference & dataset evaluation

##### Top-Level Components
- Data & Templates (ReasonFlux_v1/data, template_library.json; ReasonFlux_v2/eval/dataset)
- Training Pipeline (ReasonFlux_v1 directory):
- Template Extractor & Library
- LLaMA-Factory SFT / RLHF workflows (in train/LLaMA-Factory)
- Model Artifacts (huggingface model repos)
- Evaluation Harness (ReasonFlux_F1/eval/lm-evaluation-harness):
- CLI entrypoint for running tasks
- Task definitions (lm_eval/tasks/…)
- Cache, decontamination, loggers (wandb)
- Inference & Deployment
- ReasonFlux-Coder scripts & figures
- ReasonFlux-v2 inference.py & eval.py for JSONL datasets

##### Relationships & Data Flow
- Template Library → SFT/RLHF Trainer → Model Weights
↘ Template Proposer & Reasoner modules internalize templates
- Model Weights → Inference scripts (ReasonFlux-v2, Coder) → Predictions
- Predictions + Ground truth → Evaluation Harness → Metrics & Logging (W&B)
- CI/CD (GitHub workflows) & Docker ensure reproducible builds and tests

##### Architectural Patterns & Principles
- Modular separation of concerns: training vs evaluation vs inference
- Plugin architecture in lm-evaluation-harness for tasks/metrics
- Hierarchical reinforcement learning for template evolution
- Use of standard tools: Docker, pre-commit, GitHub Actions

##### Essential Elements
- Component names and versions (v1, F1, v2, Coder)
- Data sources (datasets JSONL, template_library.json)
- External APIs (Huggingface, OpenAI, W&B)
- CI/CD flows (GitHub Actions), Docker boundaries

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Layer
    Data_v1["Template Library (v1)"]:::data
    Data_v2["Dataset Store (v2)"]:::data

    %% Training Module
    subgraph "Training Module (v1)" 
        Template_Extractor["Template Extractor & Library"]:::training
        Template_Reasoner["Template Proposer & Reasoner"]:::training
        LLaMA["LLaMA-Factory SFT/RLHF Engine"]:::training
        Core_Scripts["Training Core Scripts"]:::training
        Model_Artifacts["Model Artifacts Interface"]:::training
    end

    %% Inference & Deployment
    subgraph "Inference & Deployment"
        Coder["ReasonFlux-Coder Scripts"]:::inference
        V2_Inf["Inference (v2)"]:::inference
        V2_EvalScript["Eval Script (v2)"]:::inference
    end

    %% Evaluation Harness
    subgraph "Evaluation Harness (F1)"
        Eval_CLI["CLI Entrypoint"]:::evaluation
        Eval_Tasks["Task Definitions"]:::evaluation
        Eval_Cache["Cache & Decontamination"]:::evaluation
        Eval_Log["W&B Logger"]:::evaluation
    end

    %% External Services
    HF_API["Huggingface API"]:::external
    OpenAI["OpenAI API"]:::external
    WnB["Weights & Biases"]:::external

    %% CI/CD & Docker
    CI_v1["CI Workflows (v1)"]:::external
    CI_F1["CI Workflows (F1)"]:::external
    Docker["Docker Configurations"]:::external

    %% Data to Training
    Data_v1 -->|"load templates"| Template_Extractor
    Template_Extractor -->|"propose templates"| Template_Reasoner
    Template_Reasoner -->|"feed templates"| LLaMA
    Core_Scripts -->|"invoke engine"| LLaMA
    LLaMA -->|"produce weights"| Model_Artifacts
    Model_Artifacts -->|"push/pull"| HF_API

    %% Data to Inference
    Model_Artifacts -->|"load model"| Coder
    Model_Artifacts -->|"load model"| V2_Inf
    Data_v2 -->|"load dataset"| V2_Inf
    Coder -->|"call inference"| OpenAI
    V2_Inf -->|"call inference"| OpenAI

    %% Inference to Evaluation
    Coder -->|"predictions"| Eval_CLI
    V2_Inf -->|"predictions"| Eval_CLI
    Eval_CLI -->|"run tasks"| Eval_Tasks
    Eval_CLI -->|"use cache"| Eval_Cache
    Eval_CLI -->|"log metrics"| Eval_Log
    Eval_Log -->|"store logs"| WnB

    %% CI/CD & Docker connections
    CI_v1 -->|"tests & build"| Template_Extractor
    CI_v1 -->|"tests & build"| LLaMA
    Docker -->|"containerize engine"| LLaMA
    CI_F1 -->|"tests & build"| Eval_CLI

    %% Click Events
    click Data_v1 "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_v1/data/template_library.json"
    click Data_v2 "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_v2/eval/dataset/"
    click Template_Extractor "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_v1/template_extractor.py"
    click LLaMA "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_v1/train/LLaMA-Factory/"
    click Core_Scripts "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_v1/train/"
    click Model_Artifacts "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_v1/models.py"
    click Eval_CLI "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_F1/eval/lm-evaluation-harness/lm_eval/__main__.py"
    click Eval_Tasks "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_F1/eval/lm-evaluation-harness/lm_eval/tasks/"
    click Eval_Cache "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_F1/eval/lm-evaluation-harness/lm_eval/caching/cache.py"
    click Eval_Log "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_F1/eval/lm-evaluation-harness/lm_eval/loggers/wandb_logger.py"
    click Coder "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_Coder/"
    click V2_Inf "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_v2/inference.py"
    click V2_EvalScript "https://github.com/gen-verse/reasonflux/blob/main/ReasonFlux_v2/eval/eval.py"
    click CI_v1 "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_v1/train/LLaMA-Factory/.github/workflows/"
    click CI_F1 "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_F1/eval/lm-evaluation-harness/.github/workflows/"
    click Docker "https://github.com/gen-verse/reasonflux/tree/main/ReasonFlux_v1/train/LLaMA-Factory/docker/"

    %% Styles
    classDef data fill:#cce5ff,stroke:#66b0ff;
    classDef training fill:#d4edda,stroke:#28a745;
    classDef inference fill:#ffe5b4,stroke:#ff8c00;
    classDef evaluation fill:#e5ccff,stroke:#8a2be2;
    classDef external fill:#f0f0f0,stroke:#999;
```
