# giacomorattazzi/llmspoliticalbias architecture

> Architecture diagram of the GitHub repository giacomorattazzi/llmspoliticalbias, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/giacomorattazzi/llmspoliticalbias
- Repository: https://github.com/giacomorattazzi/llmspoliticalbias

## Overview

This WIP research repository explores political-bias measurement, including generated text scored with PoliticalBiasBERT and validation across several political-text datasets. The principal implemented workflow creates prompts, requests generated content, scores it, and writes CSV results. Separate dataset scripts prepare or retrieve material, while validation and visualization notebooks represent documented but unsampled research branches. Edges reflect only relationships visible in the excerpts; notebook-to-dataset and notebook-to-result connections are omitted where their contents were not shown.

Main entry points: [`code/GPT/generatingContent.py`](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py) (Content Generation), [`data/datasets/Congressional Record/FilteringSpeeches.py`](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Congressional%20Record/FilteringSpeeches.py) (Speech Filtering), [`data/datasets/Manifesto/api_calls.py`](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Manifesto/api_calls.py) (Manifesto Retrieval), [`data/datasets/POLUSA/ClimateChangeArticles.py`](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/POLUSA/ClimateChangeArticles.py) (Article Filtering)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_generation["Text Generation"]
  node_prompting["Prompt Generation"]
  node_content["Content Generation"]
  node_scoring["BERT Scoring"]
  node_score_files["Score CSVs"]
end

subgraph group_preparation["Dataset Preparation"]
  node_congress_prep["Speech Filtering"]
  node_manifesto_fetch["Manifesto Retrieval<br/>[api_calls.py]"]
  node_polusa_match["Article Matching"]
  node_polusa_filter["Article Filtering"]
  node_polusa_lean["Leaning Export<br/>[LeaningArticles.py]"]
end

subgraph group_validation["Model Validation"]
  node_basil_validation["BASIL Validation"]
  node_congress_validation["Speech Validation"]
  node_manifesto_validation["Manifesto Validation"]
  node_polusa_validation["POLUSA Validation"]
end

subgraph group_analysis["Results Analysis"]
  node_text_comparison["Text Comparison"]
  node_result_visualization["Result Visualization"]
  node_gpt_results["GPT Result Data"]
end

node_researcher(("Researcher"))
node_openai{{"OpenAI API"}}

node_researcher -.->|"runs"| node_prompting
node_prompting -->|"supplies prompts"| node_content
node_content -->|"requests completions"| node_openai
node_content -->|"scores each result"| node_scoring
node_content -->|"writes CSVs"| node_score_files
node_scoring -->|"scores batches"| node_content
node_congress_prep -->|"exports filtered data"| node_researcher
node_manifesto_fetch -->|"exports retrieved data"| node_researcher
node_polusa_filter -->|"exports headlines"| node_researcher
node_polusa_lean -->|"exports articles"| node_researcher

click node_prompting "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py"
click node_content "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py"
click node_scoring "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py"
click node_score_files "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/results/GPT_ModelsResults"
click node_congress_prep "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Congressional%20Record/FilteringSpeeches.py"
click node_manifesto_fetch "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Manifesto/api_calls.py"
click node_polusa_match "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/datasets/POLUSA"
click node_polusa_filter "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/POLUSA/ClimateChangeArticles.py"
click node_polusa_lean "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/POLUSA/LeaningArticles.py"
click node_basil_validation "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/BASIL"
click node_congress_validation "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/Congressional%20Record"
click node_manifesto_validation "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/Manifesto%20Project"
click node_polusa_validation "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/POLUSA"
click node_text_comparison "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/ComparingText.ipynb"
click node_result_visualization "https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/ResultsVisualization.ipynb"
click node_gpt_results "https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/results/GPT_ModelsResults"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_prompting,node_content,node_scoring,node_score_files toneBlue
class node_congress_prep,node_manifesto_fetch,node_polusa_match,node_polusa_filter,node_polusa_lean toneAmber
class node_basil_validation,node_congress_validation,node_manifesto_validation,node_polusa_validation,node_openai toneMint
class node_text_comparison,node_result_visualization,node_gpt_results toneRose
class node_researcher toneIndigo
```

## Components

### Text Generation

- [Prompt Generation](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py): `code/GPT/generatingContent.py`
- [Content Generation](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py): `code/GPT/generatingContent.py`
- [BERT Scoring](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/generatingContent.py): `code/GPT/generatingContent.py`
- [Score CSVs](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/results/GPT_ModelsResults): `data/results/GPT_ModelsResults`

### Dataset Preparation

- [Speech Filtering](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Congressional%20Record/FilteringSpeeches.py): `data/datasets/Congressional Record/FilteringSpeeches.py`
- [Manifesto Retrieval](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/Manifesto/api_calls.py): `data/datasets/Manifesto/api_calls.py`
- [Article Matching](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/datasets/POLUSA): `data/datasets/POLUSA`
- [Article Filtering](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/POLUSA/ClimateChangeArticles.py): `data/datasets/POLUSA/ClimateChangeArticles.py`
- [Leaning Export](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/data/datasets/POLUSA/LeaningArticles.py): `data/datasets/POLUSA/LeaningArticles.py`

### Model Validation

- [BASIL Validation](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/BASIL): `code/PoliticalBiasBERT Validation/BASIL`
- [Speech Validation](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/Congressional%20Record): `code/PoliticalBiasBERT Validation/Congressional Record`
- [Manifesto Validation](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/Manifesto%20Project): `code/PoliticalBiasBERT Validation/Manifesto Project`
- [POLUSA Validation](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/code/PoliticalBiasBERT%20Validation/POLUSA): `code/PoliticalBiasBERT Validation/POLUSA`

### Results Analysis

- [Text Comparison](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/ComparingText.ipynb): `code/GPT/ComparingText.ipynb`
- [Result Visualization](https://github.com/giacomorattazzi/llmspoliticalbias/blob/main/code/GPT/ResultsVisualization.ipynb): `code/GPT/ResultsVisualization.ipynb`
- [GPT Result Data](https://github.com/giacomorattazzi/llmspoliticalbias/tree/main/data/results/GPT_ModelsResults): `data/results/GPT_ModelsResults`

### Other components

- **Researcher**
- **OpenAI API**

## Connections

- Researcher → Prompt Generation: runs
- Prompt Generation → Content Generation: supplies prompts (evidence: `code/GPT/generatingContent.py`)
- Content Generation → OpenAI API: requests completions (evidence: `code/GPT/generatingContent.py`)
- Content Generation → BERT Scoring: scores each result (evidence: `code/GPT/generatingContent.py`)
- Content Generation → Score CSVs: writes CSVs (evidence: `code/GPT/generatingContent.py`)
- BERT Scoring → Content Generation: scores batches (evidence: `code/GPT/generatingContent.py`)
- Speech Filtering → Researcher: exports filtered data (evidence: `data/datasets/Congressional Record/FilteringSpeeches.py`)
- Manifesto Retrieval → Researcher: exports retrieved data (evidence: `data/datasets/Manifesto/api_calls.py`)
- Article Filtering → Researcher: exports headlines (evidence: `data/datasets/POLUSA/ClimateChangeArticles.py`)
- Leaning Export → Researcher: exports articles (evidence: `data/datasets/POLUSA/LeaningArticles.py`)
