# datos-fundar/sesgos_llm architecture

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

- Interactive diagram: https://gitdiagram.com/datos-fundar/sesgos_llm
- Repository: https://github.com/datos-fundar/sesgos_llm

## Overview

##### Project Type and Purpose
- This is a reproducible data-analysis pipeline, not a web app or microservice. It combines Jupyter notebooks, Python scripts, R scripts, and raw datasets to:
- Prompt multiple Large Language Models (Bard, ChatGPT, Cohere) with adapted Latinobarómetro questions
- Compute distances between model answers and public-opinion survey results
- Run multivariate regression analyses on those distances
- Generate CSV outputs and visual charts
- The README makes clear that the goal is to expose and quantify algorithmic biases in LLMs, in an Argentinian context, using public-opinion data.

##### File Structure Analysis
- Top-level files:
- notebooks: `bard.ipynb`, `chatgpt.ipynb`, `cohere.ipynb`, and a variety of `distances_*.ipynb` under the root and `etc/`
- data directories: `datasets/` (Stata and CSV inputs)
- result directory: `outputs/` (CSV and chart outputs)
- processing scripts: `scripts/` (.py and .R files)
- utility code: `utils.py`
- Patterns:
- “Notebooks” fire API calls and exploratory analyses
- “scripts/” run batch, reproducible statistical models (OLS)
- “etc/” holds extra exploratory notebooks

##### Architecture Insights from README
- Dependencies: Python (pandas, Jupyter, custom utils), R (for .R scripts), external LLM APIs (OpenAI, Google Bard, Cohere).

a. Main Components
1. Data Sources
- Latinobarómetro Stata files (datasets/)
- Categorías and respuestas pickle files
2. Notebook Orchestrators
- LLM-prompt notebooks (bard.ipynb, chatgpt.ipynb, cohere.ipynb)
- Distance-calculation notebooks (distances_*.ipynb)
- Exploratory notebooks (etc/)
3. Scripts and Utils
- Python scripts (`scripts/consolidacion_preguntas_respuestas.py`, `utils.py`)
- R scripts (`scripts/multivariado.R`, `scripts/multivariado_2_lapop.R`)
4. External Services
- OpenAI API (gpt-3.5 turbo etc.)
- Google Bard API
- Cohere API
5. Outputs
- CSVs and charts (outputs/)

b. Relationships and Interactions
- Data Sources feed into Python notebooks and scripts
- Orchestrator notebooks call external LLM APIs
- LLM responses + survey data → distance notebooks
- Distance results feed into R scripts for regression
- Regression outputs and charts are written to outputs/

c. Architectural Patterns and Principles
- Pipeline pattern: sequential ETL-style flow
- Modular separation: data layer, compute layer (LLM calls & distances), modeling layer, reporting layer
- Polyglot: Python for data and API calls, R for statistical modeling

d. Key Technologies
- Jupyter notebooks
- Python (pandas, requests or openai/cohere SDKs)
- R (stats, OLS)
- External LLM APIs (OpenAI, Bard, Cohere)
- Stata file readers (e.g., pandas read_stata)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Data Layer
  subgraph "Data Layer"
    DS["Datasets (Stata, CSV, Pickle)"]:::data
  end
  click DS "https://github.com/datos-fundar/sesgos_llm/tree/main/datasets/"

  %% Compute Layer
  subgraph "Compute Layer"
    subgraph "Prompt Notebooks"
      BN["bard.ipynb"]:::compute
      CN["chatgpt.ipynb"]:::compute
      CohN["cohere.ipynb"]:::compute
    end
    click BN "https://github.com/datos-fundar/sesgos_llm/blob/main/bard.ipynb"
    click CN "https://github.com/datos-fundar/sesgos_llm/blob/main/chatgpt.ipynb"
    click CohN "https://github.com/datos-fundar/sesgos_llm/blob/main/cohere.ipynb"

    subgraph "Distance Notebooks"
      DB["distance_bard.ipynb"]:::compute
      DC["distances_cohere.ipynb"]:::compute
      DG["distances_gpt.ipynb"]:::compute
      DL["distances_latin.ipynb"]:::compute
      DLP["distances_lpop.ipynb"]:::compute
    end
    click DB "https://github.com/datos-fundar/sesgos_llm/blob/main/distance_bard.ipynb"
    click DC "https://github.com/datos-fundar/sesgos_llm/blob/main/distances_cohere.ipynb"
    click DG "https://github.com/datos-fundar/sesgos_llm/blob/main/distances_gpt.ipynb"
    click DL "https://github.com/datos-fundar/sesgos_llm/blob/main/distances_latin.ipynb"
    click DLP "https://github.com/datos-fundar/sesgos_llm/blob/main/distances_lpop.ipynb"

    subgraph "Exploratory Notebooks (etc/)"
      E1["Comparing.ipynb"]:::compute
      E2["Distance_Bard _10percent.ipynb"]:::compute
      E3["Distance_Cohere_10percent.ipynb"]:::compute
      E4["Distance_by_topic.ipynb"]:::compute
      E5["Distance_by_topic_group.ipynb"]:::compute
      E6["Distance_chatGPT_10percent.ipynb"]:::compute
      E7["multivariado.ipynb"]:::compute
      E8["multivariado_2.ipynb"]:::compute
    end
    click E1 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Comparing.ipynb"
    click E2 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Distance_Bard _10percent.ipynb"
    click E3 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Distance_Cohere_10percent.ipynb"
    click E4 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Distance_by_topic.ipynb"
    click E5 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Distance_by_topic_group.ipynb"
    click E6 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/Distance_chatGPT_10percent.ipynb"
    click E7 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/multivariado.ipynb"
    click E8 "https://github.com/datos-fundar/sesgos_llm/blob/main/etc/multivariado_2.ipynb"

    subgraph "Python Scripts & Utils"
      CP["consolidacion_preguntas_respuestas.py"]:::compute
      UT["utils.py"]:::compute
    end
    click CP "https://github.com/datos-fundar/sesgos_llm/blob/main/scripts/consolidacion_preguntas_respuestas.py"
    click UT "https://github.com/datos-fundar/sesgos_llm/blob/main/utils.py"

    subgraph "R Modeling Scripts"
      R1["multivariado.R"]:::compute
      R2["multivariado_2_lapop.R"]:::compute
    end
    click R1 "https://github.com/datos-fundar/sesgos_llm/blob/main/scripts/multivariado.R"
    click R2 "https://github.com/datos-fundar/sesgos_llm/blob/main/scripts/multivariado_2_lapop.R"
  end

  %% External Services
  subgraph "External Services"
    OAI["OpenAI API"]:::external
    BardAPI["Google Bard API"]:::external
    CohAPI["Cohere API"]:::external
  end

  %% Outputs
  subgraph "Outputs"
    OP["outputs/ (CSVs & Charts)"]:::outputs
  end
  click OP "https://github.com/datos-fundar/sesgos_llm/tree/main/outputs/"

  %% Connections
  DS --> BN
  DS --> CN
  DS --> CohN

  BN --> BardAPI
  CN --> OAI
  CohN --> CohAPI

  BardAPI --> BN
  OAI --> CN
  CohAPI --> CohN

  BN --> DB
  CN --> DG
  CohN --> DC

  DB --> R1
  DC --> R1
  DG --> R1
  DL --> R1
  DLP --> R1

  R1 --> OP
  R2 --> OP

  DS --> E1
  E1 --> OP

  %% Utils shared
  UT -.-> BN
  UT -.-> CN
  UT -.-> CohN
  UT -.-> DB
  UT -.-> DC
  UT -.-> DG
  UT -.-> DL
  UT -.-> DLP
  UT -.-> CP
  UT -.-> R1
  UT -.-> R2

  %% Styles
  classDef data fill:#cce5ff,stroke:#3399ff;
  classDef compute fill:#d4edda,stroke:#28a745;
  classDef external fill:#fff3cd,stroke:#ffcd39;
  classDef outputs fill:#e2e3e5,stroke:#6c757d;
```
