# tanmaygoyal258/prompt_optimization_slate_bandits architecture

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

- Interactive diagram: https://gitdiagram.com/tanmaygoyal258/prompt_optimization_slate_bandits
- Repository: https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits

## Overview

##### Project Type and Purpose
- This is a research-oriented, CLI-driven Python tool for running prompt‐optimization experiments as described in “Efficient Algorithms for Logistic Slate Contextual Bandits with Bandit Feedback.”
- It is not a full‐stack web app but an open‐source experimental framework that orchestrates data loading, an environment simulator, LLM‐based evaluation, optimization algorithms, and result logging.

##### Logical Component Breakdown
From the file tree and README, group files into these high‐level components:
A. Command‐Line Interface (main.py + configs.sh)
- Parses experiment parameters, seeds, dataset paths, checkpoint options, etc.
- Orchestrates the experiment pipeline.
B. Data Layer (data_utils.py + any dataset definitions)
- Loads train/test splits, example pools, embeddings.
- Handles “warmup” and “test” set slicing.
C. Environment Simulator (PromptOptEnv.py)
- Implements the contextual‐bandit environment that issues slots, collects rewards (bandit feedback), and tracks failure probabilities.
D. LLM Wrapper (basic_LLM.py + ChatGPT.py)
- Provides a thin abstraction over GPT‐style APIs or local LLMs to generate completions given a prompt.
E. Optimization Algorithms (optimization.py + Slate_GLM_OFUL_Prompt_Opt.py)
- Encapsulates the core bandit algorithms (e.g., OFUL, random baseline, separate pools, repeat examples).
- Manages example selection, confidence‐bound updates, and slot‐wise pooling logic.
F. Metrics & Evaluation (accuracy_calculation.py + utils.py)
- Computes accuracy, confidence‐bound failures, logs performance over time.
- General utilities for tensor operations, logging, checkpoint saving/loading.

##### Interactions and Data Flow
- The CLI (main.py) reads arguments → calls Data Layer to load examples → instantiates the Environment Simulator with parameters → wraps the LLM in an API client → passes both to the Optimization Algorithm.
- The Optimization Algorithm requests candidate prompts from the Environment Simulator, queries the LLM Wrapper for responses, receives rewards, updates its internal state, and repeats.
- At each iteration or experiment end, the Metrics module computes performance and writes results/checkpoints.

##### Architectural Patterns & Principles
- Modular Pipeline: clear separation between data ingestion, environment dynamics, model inference, optimization logic, and evaluation.
- Dependency Injection: the main script injects data paths, seeds, and algorithm choices into each component.
- Config‐driven: all hyperparameters live in the CLI interface and configs.sh, enabling reproducibility.

##### Technologies & Frameworks
- Python 3 for all modules.
- Shell script (configs.sh) for environment setup.
- External LLM APIs (wrapped in ChatGPT.py) or local backends (basic_LLM.py).
- Standard data libraries (NumPy, Pandas, possibly PyTorch).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: CLI & Config
    subgraph "Layer 1 (Green): CLI & Config"
        direction TB
        CLI_main["main.py"]:::cli
        CLI_config["configs.sh"]:::cli
    end

    %% Layer 2: Data & Environment
    subgraph "Layer 2 (Blue): Data & Environment"
        direction TB
        Data_utils["data_utils.py"]:::data
        Env["PromptOptEnv.py"]:::env
    end

    %% Layer 3: LLM Interface
    subgraph "Layer 3 (Orange): LLM Interface"
        direction TB
        BasicLLM["basic_LLM.py"]:::llm
        ChatGPT["ChatGPT.py"]:::llm
    end

    %% Layer 4: Optimization Engine
    subgraph "Layer 4 (Purple): Optimization Engine"
        direction TB
        Opt_core["optimization.py"]:::opt
        Opt_oful["Slate_GLM_OFUL_Prompt_Opt.py"]:::opt
    end

    %% Layer 5: Metrics & Storage
    subgraph "Layer 5 (Gray): Metrics & Storage"
        direction TB
        Metrics_acc["accuracy_calculation.py"]:::metric
        Utils["utils.py"]:::metric
        Checkpoints["Checkpoints/Storage"]:::storage
    end

    %% Connections
    CLI_main -->|"load parameters"| Data_utils
    CLI_main -->|"source configs"| CLI_config
    Data_utils -->|"dataset"| Env
    Opt_core -->|"request state"| Env
    Env -->|"reward feedback"| Opt_core
    Opt_core -->|"prompt"| BasicLLM
    Opt_core -->|"prompt"| ChatGPT
    BasicLLM -->|"completion"| Opt_core
    ChatGPT -->|"completion"| Opt_core
    Opt_core -->|"results"| Metrics_acc
    Metrics_acc -->|"use utils"| Utils
    Utils -->|"save checkpoints"| Checkpoints

    %% Click Events
    click CLI_main "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/main.py"
    click CLI_config "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/configs.sh"
    click Data_utils "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/data_utils.py"
    click Env "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/PromptOptEnv.py"
    click BasicLLM "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/basic_LLM.py"
    click ChatGPT "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/ChatGPT.py"
    click Opt_core "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/optimization.py"
    click Opt_oful "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/Slate_GLM_OFUL_Prompt_Opt.py"
    click Metrics_acc "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/accuracy_calculation.py"
    click Utils "https://github.com/tanmaygoyal258/prompt_optimization_slate_bandits/blob/main/utils.py"

    %% Styles
    classDef cli fill:#9f6,stroke:#333;
    classDef data fill:#6cf,stroke:#333;
    classDef env fill:#6cf,stroke:#333;
    classDef llm fill:#f96,stroke:#333;
    classDef opt fill:#c69,stroke:#333;
    classDef metric fill:#aaa,stroke:#333;
    classDef storage fill:#bbb,stroke:#333;
```
