# bdsaglam/verifiers architecture

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

- Interactive diagram: https://gitdiagram.com/bdsaglam/verifiers
- Repository: https://github.com/bdsaglam/verifiers

## Overview

##### Main Components
- Core RL and Verification Engine:
- Environments (in src/verifiers/envs): e.g., SimpleEnv, MathEnv, ToolEnv, etc.
- Trainers (in src/verifiers/trainers): GRPOEnvTrainer is a primary example that configures and runs the training loop.
- Prompts and Rubrics (in src/verifiers/prompts and src/verifiers/rubrics): Responsible for few-shot prompting, evaluation rubrics, and formatting checks.
- Parsers and Data Utils (in src/verifiers/parsers, src/verifiers/utils, and src/verifiers/datasets): Handle dataset formatting, XML parsing, and other utility functions.
- Tools (in src/verifiers/tools): Include external functionality like the calculator tool.

- Data and Experiment Management:
- “Data” component (represented by data/, dvc.yaml, dvc.lock, and DVC directories) for managing datasets and model checkpoints.
- “Configs” (configs/ directory) that provide YAML files for environment configuration and training (e.g., DeepSpeed ZeRO 3 configuration).

- Orchestration and Workflows:
- “DSTacks” and Docker Compose: Show that there are containerized workflows (dstacks/ and docker-compose.yml) and services for running different parts of the system (under services/). These include:
- Jupyter notebooks for interactive experiments (nbs/)
- Script-based execution flows (scripts/)
- Containerized services for load testing and running inference (in services/, with Dockerfiles and auxiliary scripts)

- External Integrations:
- Logging and Monitoring integrations (e.g., wandb and possibly the usage of gunicorn for serving inference data).

##### Relationships and Data Flow
- The Environment module (e.g., ToolEnv) which encapsulates the multi-step RL environment.
- The Prompts & Rubrics module, where the few-shot examples and evaluation criteria are applied.

##### Architectural Patterns and Design Highlights
- Modularity: The project is organized into self-contained modules – environments, tools, prompts, and datasets which can be extended or replaced.
- Configuration-Driven Execution: The use of YAML configuration files (configs/zero3.yaml) and DVC for experiment reproducibility.
- Containerization and Service-Oriented Design: With services, Dockerfiles, and DSTacks configuration, the architecture supports deployment across different environments.
- Multi-step Execution and RL Feedback Loop: Highlight the iterative interaction between LLMs and environments wherein the user-defined multi-step environment (inheriting from MultiStepEnv) feeds back into the training loop.

##### Detail Level
- Recursive relationships (such as the feedback loop in RL training) and include any auxiliary services that assist in logging, testing (tests/ folder), or model evaluation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Initiation
    USR["User/Experiment Initiator"]:::external

    %% Workflow & Orchestration
    subgraph "Workflow & Orchestration"
        SC["Scripts"]:::infra
        DST["DSTacks"]:::infra
        DC["Docker Compose"]:::infra
        NB["Notebooks"]:::infra
        SVC["Services"]:::infra
    end

    %% Data & Configuration
    subgraph "Data & Configuration"
        DM["Data Management (DVC)"]:::infra
        CFG["Configurations (YAML)"]:::infra
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ACC["Accelerate"]:::external
        DS["DeepSpeed"]:::external
        HF["HuggingFace"]:::external
        WB["Wandb"]:::external
    end

    %% Verifiers Core Library Container
    VCL["Verifiers Core Library"]:::core

    %% Verifiers Core Components
    subgraph "Verifiers Core Components"
        TRN["GRPOEnvTrainer"]:::core
        ENV["Environments"]:::core
        PRM["Prompts"]:::core
        RBR["Rubrics"]:::core
        PRS["Parsers"]:::core
        UTIL["Data Utils"]:::core
        TLS["Tools"]:::core
        LLM["LLM Model Integration"]:::core
    end

    %% Connections from User to Workflow
    USR --> SC
    DST --> SC
    DC --> SC
    NB --> SC
    SVC --> SC

    %% Workflow to Trainer via Core Library container
    SC --> VCL
    VCL --> TRN

    %% Data & Config flows
    DM --> TRN
    CFG --> TRN
    DM --> ENV

    %% Trainer interactions within core components
    TRN -->|"simulate_reward"| ENV
    ENV -->|"feedback_loop"| TRN

    TRN --> PRM
    TRN --> RBR
    TRN --> PRS
    TRN --> UTIL
    TRN --> TLS

    TRN --> LLM
    LLM -->|"integrates_with"| TRN

    %% External integrations
    ACC --> TRN
    DS --> TRN
    HF --> TRN
    WB --> TRN

    %% Styling Classes
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef infra fill:#A9DFBF,stroke:#145A32,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;

    %% Click Events for Verifiers Core Components
    click VCL "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers"
    click TRN "https://github.com/bdsaglam/verifiers/blob/main/src/verifiers/trainers/grpo_env_trainer.py"
    click ENV "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/envs"
    click PRM "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/prompts"
    click RBR "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/rubrics"
    click PRS "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/parsers"
    click UTIL "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/utils"
    click TLS "https://github.com/bdsaglam/verifiers/tree/main/src/verifiers/tools"

    %% Click Events for Data & Configuration
    click DM "https://github.com/bdsaglam/verifiers/tree/main/data"
    click CFG "https://github.com/bdsaglam/verifiers/tree/main/configs"

    %% Click Events for Workflow & Orchestration
    click SC "https://github.com/bdsaglam/verifiers/tree/main/scripts"
    click DST "https://github.com/bdsaglam/verifiers/tree/main/dstacks"
    click DC "https://github.com/bdsaglam/verifiers/blob/main/docker-compose.yml"
    click NB "https://github.com/bdsaglam/verifiers/tree/main/nbs"
    click SVC "https://github.com/bdsaglam/verifiers/tree/main/services"
```
