# cicada-33-01/gambit architecture

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

- Interactive diagram: https://gitdiagram.com/cicada-33-01/gambit
- Repository: https://github.com/cicada-33-01/gambit

## Overview

##### Main Components
- Entry Points: Illustrate the executable scripts:
- Run_GAMBIT.py and GAMBIT/run.py are your starting points.
- Model Setup: The module (GAMBIT/utils/model_setup.py) is responsible for configuring and loading the models.
- Fine-Tuning Pipelines:
- finetune_Cheater.py: Manages fine-tuning of the Cheater LLM.
- finetune_Detective.py: Handles fine-tuning of the Detective LLM.
- finetune_pipeline.py: Orchestrates the overall fine-tuning workflow.
- Interaction Modules:
- detection.py: Implements detection logic.
- generate_answer.py and generate_question.py: Handle input/output generation, simulating adversarial game interactions.
- response_filter.py: Applies filtering on model responses.
- Data Management: Although not explicitly separated into its own module, the README describes heap-based clustering and dynamic queuing for managing datasets (HC3 and QRECC), so include a generic “Data Manager” or “Dataset Handler” component.
- Supporting Utilities: The misc.py file and any other utility modules that help with minor tasks.

##### Relationships and Interactions
- That the entry points invoke the pipeline, which then calls upon model_setup to initialize the models.
- Generation modules (generate_question and generate_answer) with the respective models to illustrate the adversarial interaction. Incorporate detection.py to represent the evaluation loop.
- Integration with external models and datasets (e.g., pointing out the usage of models available on Hugging Face and data from HC3 and QRECC).

##### Architectural Patterns and Design Principles
- The system follows a modular pattern with distinct modules for fine-tuning, detection, and data management.
- It uses a pipeline approach, where data flows sequentially from model setup, through fine-tuning and generation phases, to finally be evaluated by the detection module.
- Innovative data handling strategies such as heap-based clustering and dynamic queue updates as side components that interact with the fine-tuning process.

##### Relevant Technologies and Frameworks
- Mention that the project utilizes reinforcement learning with human feedback (RLHF) and Low-Rank Adaptation (LoRA) techniques in the fine-tuning process.
- The project is Python-based, so dependencies from requirements.txt are in use. You may want to list key libraries if known (such as any ML frameworks like PyTorch or TensorFlow, if used internally, or Transformers from Hugging Face).

##### Elements
- From the entry script to the orchestration module.
- Between model setup, generation, fine-tuning, and detection.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Entry Points"
        EP1["Entry Point – Run Script (Run_GAMBIT.py)"]:::entry
        EP2["Entry Point – GAMBIT Main Runner (GAMBIT/run.py)"]:::entry
    end

    subgraph "Model & Pipeline"
        MS["Model Setup (GAMBIT/utils/model_setup.py)"]:::processing
        FTP["Fine-Tuning Pipeline Orchestrator (GAMBIT/utils/finetune_pipeline.py)"]:::processing
        CT["Cheater Fine-Tuning (GAMBIT/utils/finetune_Cheater.py)"]:::processing
        DT["Detective Fine-Tuning (GAMBIT/utils/finetune_Detective.py)"]:::processing
    end

    subgraph "Interaction Modules"
        GQ["Adversarial Generation (Question) (GAMBIT/utils/generate_question.py)"]:::interaction
        GA["Adversarial Generation (Answer) (GAMBIT/utils/generate_answer.py)"]:::interaction
        DM["Detection Module (GAMBIT/utils/detection.py)"]:::interaction
        RF["Response Filtering (GAMBIT/utils/response_filter.py)"]:::interaction
    end

    subgraph "Supporting & Data Management"
        SU["Supporting Utilities (GAMBIT/utils/misc.py)"]:::utilities
        DMgr["Data Manager"]:::data
    end

    subgraph "External Dependencies"
        HF["Hugging Face Models"]:::external
        DS["Datasets: HC3 & QRECC"]:::external
    end

    %% Connections: Entry Points to Pipeline
    EP1 -->|"initiates"| FTP
    EP2 -->|"initiates"| FTP

    %% Pipeline flow
    FTP -->|"calls"| MS
    FTP -->|"orchestrates"| CT
    FTP -->|"orchestrates"| DT

    %% Model Setup uses External Models
    MS -->|"loads"| HF

    %% Fine-tuning Modules trigger adversarial interactions
    CT -->|"triggers_generation"| GQ
    CT -->|"triggers_generation"| GA
    DT -->|"receives_from"| GQ
    DT -->|"receives_from"| GA

    %% Interaction Modules: Detection and Filtering
    DM -->|"evaluates"| CT
    DM -->|"evaluates"| DT
    RF -->|"filters"| GA

    %% Data Management integration
    DMgr -->|"updates_dataset"| CT
    DMgr -->|"updates_dataset"| DT
    DS -->|"provides_data"| DMgr

    %% Feedback loop from Detection back to Pipeline
    DM -- "feedback" --> FTP

    %% Supporting Utilities assist Model Setup and Pipeline
    SU --> MS
    SU --> FTP

    %% External Dependencies connected to Model Setup and Data Manager
    HF -->|"supplies_models"| MS

    %% Click Events for Components
    click EP1 "https://github.com/cicada-33-01/gambit/blob/main/Run_GAMBIT.py"
    click EP2 "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/run.py"
    click MS "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/model_setup.py"
    click FTP "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/finetune_pipeline.py"
    click CT "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/finetune_Cheater.py"
    click DT "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/finetune_Detective.py"
    click DM "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/detection.py"
    click GA "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/generate_answer.py"
    click GQ "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/generate_question.py"
    click RF "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/response_filter.py"
    click SU "https://github.com/cicada-33-01/gambit/blob/main/GAMBIT/utils/misc.py"

    %% Style definitions
    classDef entry fill:#f9d423,stroke:#333,stroke-width:2px;
    classDef processing fill:#a3c4dc,stroke:#333,stroke-width:2px;
    classDef interaction fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef utilities fill:#d3f9d8,stroke:#333,stroke-width:2px;
    classDef data fill:#c1f0c1,stroke:#333,stroke-width:2px;
    classDef external fill:#e2e0f2,stroke:#333,stroke-width:2px;
```
