# ukplab/eacl2024-sociodemographic-prompting architecture

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

- Interactive diagram: https://gitdiagram.com/ukplab/eacl2024-sociodemographic-prompting
- Repository: https://github.com/ukplab/eacl2024-sociodemographic-prompting

## Overview

##### Project Type and Purpose
- This project implements an experimental pipeline for sociodemographic prompting in subjective NLP tasks. It is designed to study how integrating sociodemographic attributes can influence model predictions on tasks like toxicity, hate speech, and stance detection.
- The README frames the repository as research software that executes prompting experiments, particularly emphasizing experimental configurations and the analysis of outcomes. In addition, it supports data sampling and preparation through provided notebooks.

##### Analyzing the File Structure
- Key Files and Directories:
- sd_prompting.py: The primary script for running prompting experiments.
- configs/sd-prompting.yaml: Contains configuration settings (using Hydra) that drive experiment parameters.
- api_client.py: Likely used for interfacing with external models or APIs (e.g., retrieving model predictions from transformer libraries).
- util.py: Provides helper functions and common routines used across the experiment.
- Dataset_Preparation_Sampling.ipynb: A Jupyter notebook for dataset preparation, sampling, and preliminary analysis.
- Other files like LICENSE, README.md, requirements.txt, and .gitignore support project management and setup.
- Although the README mentions directories such as data/, analysis, and scripts, the current file tree highlights the modular core – configuration, main experiment script, API utilities, and utility routines.

##### Main Components and Their Relationships
a. Experiment Runner:
- sd_prompting.py acts as the core component that executes the prompting experiments.
- It uses configuration files (from the ‘configs’ directory) to set up model parameters, data paths, and task-specific settings.
b. Configuration Management:
- The Hydra configuration file (configs/sd-prompting.yaml) centrally manages parameters for each experiment.
- This component feeds into the Experiment Runner to dictate its behavior.
c. API and Utility Components:
- api_client.py represents integration with external services such as fetching model predictions from transformer libraries.
- util.py contains general-purpose, reusable functions to support various operations.
d. Data and Experiment Analysis:
- Although datasets are not visually represented in the small file tree list, the README clarifies that external data sources play a crucial role.

##### Architectural Patterns and Design Principles
- The project follows a modular design where each script or module encapsulates distinct responsibilities:
- Separation between configuration, execution, and data analysis.
- Loose coupling is evident in the way configuration is separated from business logic.
- Usage of Hydra for configuration encourages a clean decoupling of experiment settings from the main code.
- The design supports experimentation: researchers can modify configurations and swap out components (e.g., model names or datasets) without reworking the core logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input"
        ED["External Data Sources"]:::external
        PT["Pre-trained Models"]:::preTrained
    end

    %% Configuration Layer
    subgraph "Configuration"
        CM["Configuration Manager"]:::config
    end

    %% Execution Layer
    subgraph "Execution"
        ER["Experiment Runner"]:::execution
        AC["API Client"]:::execution
        UM["Utility Module"]:::utility
    end

    %% Output & Analysis Layer
    subgraph "Output & Analysis"
        OD["Output Data"]:::analysis
        DA["Data Preparation/Analysis"]:::analysis
    end

    %% Relationships between layers
    CM -->|"informs"| ER
    ED -->|"suppliesData"| ER
    ED -->|"suppliesData"| DA
    ER -->|"callsAPI"| AC
    ER -->|"uses"| UM
    AC -->|"fetchesPredictions"| PT
    ER -->|"writes"| OD
    DA -->|"analyzes"| OD
    DA -->|"uses"| UM

    %% Click events for mapped components
    click CM "https://github.com/ukplab/eacl2024-sociodemographic-prompting/blob/main/configs/sd-prompting.yaml"
    click ER "https://github.com/ukplab/eacl2024-sociodemographic-prompting/blob/main/sd_prompting.py"
    click AC "https://github.com/ukplab/eacl2024-sociodemographic-prompting/blob/main/api_client.py"
    click UM "https://github.com/ukplab/eacl2024-sociodemographic-prompting/blob/main/util.py"
    click DA "https://github.com/ukplab/eacl2024-sociodemographic-prompting/blob/main/Dataset_Preparation_Sampling.ipynb"

    %% Styling definitions
    classDef config fill:#add8e6,stroke:#00008b,stroke-width:2px;
    classDef execution fill:#90ee90,stroke:#006400,stroke-width:2px;
    classDef utility fill:#ffcc80,stroke:#f57c00,stroke-width:2px;
    classDef analysis fill:#f4cccc,stroke:#b22222,stroke-width:2px;
    classDef external fill:#d9d2e9,stroke:#5e239d,stroke-width:2px;
    classDef preTrained fill:#ffe6e6,stroke:#ff0000,stroke-width:2px;
```
