# sepehrilami/lfb architecture

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

- Interactive diagram: https://gitdiagram.com/sepehrilami/lfb
- Repository: https://github.com/sepehrilami/lfb

## Overview

- Data Sources and Datasets:
- Directories such as /data (with subdirectories like context and game prompts), /new contexts, and /factory_ready.json (original fine-tuning dataset in LLaMafactory syntax).
- Specialized datasets for different experiments (in-sample, out-of-sample, public good game experimental data from directories /ood_game, /oos_context, /pgg).
- Experiment Orchestration and Model Pipeline:
- Main experiment execution is orchestrated by mainloop.py and the fine-tuning run from webui.ipynb.
- The fine-tuned model is housed in the /l2tune directory, complete with its adapter configurations and prebuilt model weights.
- Reference the usage of external models (LLaMa2-7b and 70b from Huggingface) and the local fine-tuned model.
- Analysis and Visualization:
- Notebooks directory houses various Jupyter notebooks (e.g., in-sample-context-analysis.ipynb, ood_game_analysis.ipynb, oos_analysis.ipynb, pgg_analysis.ipynb) that perform comparative analysis and visualization.
- The visualization outputs and figures are stored in directories such as /new_figs, /ood_game_figs, /oos_context_figs, and /pgg_figs.
- Results Storage:
- Components like /results, /results_llama3, and associated data summary files (e.g., .csv, .pkl, .txt) which record experiment metrics and aggregated outputs.

##### Component Interactions and Data Flow
- The data layer (raw data files and context/game prompts) flows into the experiment orchestration layer where models are either fine-tuned or evaluated.
- How input datasets from /data and /new contexts are fed to the fine-tuning procedure.
- The transitions from the fine-tuning phase (executed in mainloop.py and webui.ipynb) to benchmark evaluation using both standard LLaMa2 models (fetched via Huggingface) and the fine-tuned model.
- How experimental outputs are stored in the /results-related directories, and then how these results are analyzed via the Jupyter notebooks.
- External dependencies (such as Groq platform requirements and Huggingface model APIs) as additional nodes connected to the experiment execution component.

##### Architectural Patterns and Design Principles
- Modular nature of the project:
- Data is clearly separated by type (context vs. game, in-sample versus out-of-sample).
- The experiment pipeline is divided into training/fine-tuning and evaluation, with distinct directories for execution scripts (mainloop.py and notebooks).
- Use of configuration files (e.g., requirements.txt for dependency management, adapter_config.json for model fine-tuning) that provide a reproducible environment.
- Design choice of using various file formats (.txt, .csv, .pkl, .ipynb) for different components, reflecting a data-driven and iterative research approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources"
        A1["/data"]:::data
        A1c["/data/context"]:::data
        A1g["/data/game"]:::data
        A2["/new contexts"]:::data
        A3["factory_ready.json"]:::data
        A4["/ood_game"]:::data
        A5["/oos_context"]:::data
        A6["/pgg"]:::data
    end

    subgraph "Experiment Orchestration"
        B1["mainloop.py"]:::orchestration
        B2["webui.ipynb"]:::orchestration
        B5["requirements.txt"]:::config
        subgraph "Fine-Tuning Module"
            C1["/l2tune"]:::pipeline
        end
        B3["Huggingface LLM"]:::external
        B4["Groq Platform"]:::external
    end

    subgraph "Results Storage"
        D1["/results"]:::results
        D2["/results_llama3"]:::results
    end

    subgraph "Analysis & Visualization"
        E1["Notebooks (/notebooks)"]:::analysis
        subgraph "Visualization Outputs"
            E2["/new_figs"]:::analysis
            E3["/ood_game_figs"]:::analysis
            E4["/oos_context_figs"]:::analysis
            E5["/pgg_figs"]:::analysis
        end
    end

    F["Data Ingestion"]:::data

    %% Data flows from individual data sources to the Data Ingestion node
    A1 --> F
    A1c --> F
    A1g --> F
    A2 --> F
    A3 --> F
    A4 --> F
    A5 --> F
    A6 --> F

    %% Data ingestion feeds into experiment execution scripts
    F --> B1
    F --> B2

    %% Configuration influences the experiment orchestration
    B5 --> B1
    B5 --> B2

    %% Experiment execution triggers fine-tuning and external LLM evaluations
    B1 --> C1
    B2 --> C1
    B1 --> B3
    B2 --> B3
    B1 --> B4
    B2 --> B4

    %% Fine-tuned model and external LLM feed into results storage
    C1 --> D1
    B3 --> D1
    B4 --> D1
    C1 --> D2
    B3 --> D2
    B4 --> D2

    %% Results feed into analysis and visualization
    D1 --> E1
    D2 --> E1
    E1 --> E2
    E1 --> E3
    E1 --> E4
    E1 --> E5

    %% Click Events
    click A1 "https://github.com/sepehrilami/lfb/tree/main//data"
    click A1c "https://github.com/sepehrilami/lfb/tree/main//data/context"
    click A1g "https://github.com/sepehrilami/lfb/tree/main//data/game"
    click A2 "https://github.com/sepehrilami/lfb/tree/main//new contexts"
    click A3 "https://github.com/sepehrilami/lfb/blob/main/factory_ready.json"
    click A4 "https://github.com/sepehrilami/lfb/tree/main//ood_game"
    click A5 "https://github.com/sepehrilami/lfb/tree/main//oos_context"
    click A6 "https://github.com/sepehrilami/lfb/tree/main//pgg"
    click B1 "https://github.com/sepehrilami/lfb/blob/main/mainloop.py"
    click B2 "https://github.com/sepehrilami/lfb/blob/main/webui.ipynb"
    click C1 "https://github.com/sepehrilami/lfb/tree/main//l2tune"
    click B5 "https://github.com/sepehrilami/lfb/blob/main/requirements.txt"
    click E1 "https://github.com/sepehrilami/lfb/tree/main//notebooks"
    click E2 "https://github.com/sepehrilami/lfb/tree/main//new_figs"
    click E3 "https://github.com/sepehrilami/lfb/tree/main//ood_game_figs"
    click E4 "https://github.com/sepehrilami/lfb/tree/main//oos_context_figs"
    click E5 "https://github.com/sepehrilami/lfb/tree/main//pgg_figs"
    click D1 "https://github.com/sepehrilami/lfb/tree/main//results"
    click D2 "https://github.com/sepehrilami/lfb/tree/main//results_llama3"

    %% Styles
    classDef data fill:#f9ddbb,stroke:#d65c00,stroke-width:2px;
    classDef orchestration fill:#cce0ff,stroke:#003399,stroke-width:2px;
    classDef pipeline fill:#ffebcc,stroke:#cc6600,stroke-width:2px;
    classDef results fill:#d5f5e3,stroke:#239b56,stroke-width:2px;
    classDef analysis fill:#fdebd0,stroke:#cd853f,stroke-width:2px;
    classDef config fill:#e2e2e2,stroke:#808080,stroke-width:2px;
    classDef external fill:#f2d7d5,stroke:#a93226,stroke-width:2px;
```
