# rks-2804/bwr_model architecture

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

- Interactive diagram: https://gitdiagram.com/rks-2804/bwr_model
- Repository: https://github.com/rks-2804/bwr_model

## Overview

##### Project type and purpose
- This is an open-source research toolkit and CLI pipeline for performing collaborative model merging via the Best-Worst-Random (BWR) algorithm.
- It orchestrates:
- Population-based search over LoRA/adapters or full-parameter LLM experts
- Multiple merge strategies (weighted average, task arithmetic, TIES, DARE)
- Evaluation on a library of JSON datasets (data/eval)
- Logging/monitoring via WandB and text logs

##### File structure
- Top level:
- search.py – main driver for BWR search
- evaluate.py – evaluation engine (validation/test loops)
- merge.py – implementations of merge methods
- overall_metrics.py – post-search metrics aggregation
- data/ – evaluation datasets (JSON)
- initial_experts/ – starter LoRA adapters or model shards
- search/*.sh – domain-specific bash wrappers that call search.py
- requirements.txt, bwr.yml – environment specs
- Patterns:
- Script-based pipeline: CLI → Python driver → modular functions
- Separation of concerns: search logic (search.py), merge logic (merge.py), evaluation logic (evaluate.py), I/O and logging

##### README for additional insights
- Detailed CLI usage patterns (search_nlgraph.sh, others)
- BWR algorithm description (population init, best/worst update, random reset)
- Merge methods and their parameters
- Instructions to add new data, new models, and new eval types
- External dependencies: HuggingFace (Gemma), WandB, Perspective API, Vertex AI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI Wrappers"
        direction TB
        SC["search_concise.sh"]:::cli
        SHM["search_hindi_math.sh"]:::cli
        SJM["search_japanese_math.sh"]:::cli
        SL["search_legal.sh"]:::cli
        SNG["search_nlgraph.sh"]:::cli
        SPA["search_phd_application.sh"]:::cli
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        SP["search.py"]:::core
        ME["merge.py"]:::core
        EV["evaluate.py"]:::core
        OM["overall_metrics.py"]:::core
    end

    %% Data & Model Stores
    subgraph "Data & Model Stores"
        direction TB
        DE["data/eval/"]:::datastore
        IE["initial_experts/"]:::datastore
        SO["search outputs"]:::datastore
    end

    %% Environment Specs
    subgraph "Environment Specs"
        direction TB
        RQ["requirements.txt"]:::env
        BY["bwr.yml"]:::env
    end

    %% External Services
    subgraph "External Services"
        direction TB
        HF["HuggingFace Hub"]:::external
        WC["WandB"]:::external
        GC["Google Cloud APIs"]:::external
    end

    %% Flows
    SC -->|"invokes"| SP
    SHM -->|"invokes"| SP
    SJM -->|"invokes"| SP
    SL -->|"invokes"| SP
    SNG -->|"invokes"| SP
    SPA -->|"invokes"| SP

    SP -->|"loads population"| IE
    SP -->|"iterative loop"| ME
    ME -->|"produces candidates"| SO
    ME -->|"uses merge methods"| ME
    ME -->|"calls"| SP
    SP -->|"calls"| EV
    EV -->|"reads data"| DE
    EV -->|"scores models"| SP
    SP -->|"writes logs"| WC
    SP -->|"writes logs"| SO
    SP -->|"final summary"| OM
    OM -->|"reads outputs"| SO

    SP -->|"downloads/models"| HF
    EV -->|"calls external API"| GC

    %% Click Events
    click SC "https://github.com/rks-2804/bwr_model/blob/main/search/search_concise.sh"
    click SHM "https://github.com/rks-2804/bwr_model/blob/main/search/search_hindi_math.sh"
    click SJM "https://github.com/rks-2804/bwr_model/blob/main/search/search_japanese_math.sh"
    click SL "https://github.com/rks-2804/bwr_model/blob/main/search/search_legal.sh"
    click SNG "https://github.com/rks-2804/bwr_model/blob/main/search/search_nlgraph.sh"
    click SPA "https://github.com/rks-2804/bwr_model/blob/main/search/search_phd_application.sh"
    click SP "https://github.com/rks-2804/bwr_model/blob/main/search.py"
    click ME "https://github.com/rks-2804/bwr_model/blob/main/merge.py"
    click EV "https://github.com/rks-2804/bwr_model/blob/main/evaluate.py"
    click DE "https://github.com/rks-2804/bwr_model/tree/main/data/eval/"
    click IE "https://github.com/rks-2804/bwr_model/tree/main/initial_experts/"
    click OM "https://github.com/rks-2804/bwr_model/blob/main/overall_metrics.py"
    click RQ "https://github.com/rks-2804/bwr_model/blob/main/requirements.txt"
    click BY "https://github.com/rks-2804/bwr_model/blob/main/bwr.yml"
    click WC "https://github.com/rks-2804/bwr_model/blob/main/search/<run>/log.txt"

    %% Styles
    classDef cli fill:#e0f7fa,stroke:#006064,color:#006064
    classDef core fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef datastore fill:#c8e6c9,stroke:#2e7d32,color:#2e7d32
    classDef env fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100
```
