# allthingssecurity/informationbottleneck architecture

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

- Interactive diagram: https://gitdiagram.com/allthingssecurity/informationbottleneck
- Repository: https://github.com/allthingssecurity/informationbottleneck

## Overview

This is a runnable MNIST research experiment, not a general-purpose information-bottleneck library. A researcher launches the experiment, which loads MNIST and sweeps autoencoder bottleneck sizes; trained models are evaluated and their hidden-layer ReLU regions analyzed for information and compression metrics. The runner then emits plots, tabular results, and a report. The graph preserves the README’s classifier-based prediction measures and the major analysis outputs. Some experiment calls are visible only in partial excerpts or the SOURCE INDEX; edges use the experiment file or README where those relationships are documented.

Main entry points: [`src/infobottleneck/experiment.py`](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py) (Experiment runner), [`src/infobottleneck/report.py`](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/report.py) (Study report), [`src/infobottleneck/models.py`](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/models.py) (Autoencoder and head), [`results/mnist_info_region_study`](https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study) (Result tables)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Experiment entry"]
  node_cli["Experiment CLI<br/>[run_experiment.py]"]
  node_runner["Experiment runner<br/>[experiment.py]"]
end

subgraph group_modeling["Data and modeling"]
  node_mnist[("MNIST dataset")]
  node_loaders["MNIST loaders<br/>[data.py]"]
  node_autoencoder["Autoencoder and head<br/>[models.py]"]
  node_training["Model training<br/>[experiment.py]"]
  node_evaluation["Test evaluation<br/>[experiment.py]"]
end

subgraph group_analysis["Information analysis"]
  node_activation_capture["Activation capture<br/>[analysis.py]"]
  node_region_metrics["Region and MI metrics<br/>[analysis.py]"]
  node_metric_helpers["Discrete metric helpers<br/>[utils.py]"]
  node_correlations["Metric correlations<br/>[analysis.py]"]
end

subgraph group_outputs["Results and interpretation"]
  node_plots["Analysis plots<br/>[plots.py]"]
  node_report["Study report<br/>[report.py]"]
  node_result_tables["Result tables"]
  node_checkpoints["Model checkpoints"]
  node_figures["Generated figures"]
  node_study_report["Generated report<br/>[REPORT.md]"]
end

node_researcher(("Researcher"))

node_researcher -->|"launches"| node_cli
node_cli -->|"invokes"| node_runner
node_runner -->|"builds loaders"| node_loaders
node_loaders -->|"loads"| node_mnist
node_runner -->|"runs sweep"| node_training
node_training -->|"trains"| node_autoencoder
node_runner -->|"evaluates models"| node_evaluation
node_evaluation -->|"evaluates"| node_autoencoder
node_runner -->|"saves models"| node_checkpoints
node_runner -->|"collects activations"| node_activation_capture
node_activation_capture -->|"captures layers"| node_autoencoder
node_runner -->|"builds metrics"| node_region_metrics
node_region_metrics -->|"summarizes IDs"| node_metric_helpers
node_runner -->|"computes correlations"| node_correlations
node_correlations -->|"writes metrics"| node_result_tables
node_runner -->|"writes tables"| node_result_tables
node_runner -->|"generates plots"| node_plots
node_plots -->|"saves figures"| node_figures
node_runner -->|"generates report"| node_report
node_report -->|"reads tables"| node_result_tables
node_report -->|"writes report"| node_study_report

click node_cli "https://github.com/allthingssecurity/informationbottleneck/blob/main/scripts/run_experiment.py"
click node_runner "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py"
click node_loaders "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/data.py"
click node_autoencoder "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/models.py"
click node_training "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py"
click node_evaluation "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py"
click node_activation_capture "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py"
click node_region_metrics "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py"
click node_metric_helpers "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/utils.py"
click node_correlations "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py"
click node_plots "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/plots.py"
click node_report "https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/report.py"
click node_result_tables "https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study"
click node_checkpoints "https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study/models"
click node_figures "https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study/plots"
click node_study_report "https://github.com/allthingssecurity/informationbottleneck/blob/main/results/mnist_info_region_study/REPORT.md"

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_cli,node_runner toneBlue
class node_mnist,node_loaders,node_autoencoder,node_training,node_evaluation toneAmber
class node_activation_capture,node_region_metrics,node_metric_helpers,node_correlations toneMint
class node_plots,node_report,node_result_tables,node_checkpoints,node_figures,node_study_report toneRose
class node_researcher toneIndigo
```

## Components

### Experiment entry

- [Experiment CLI](https://github.com/allthingssecurity/informationbottleneck/blob/main/scripts/run_experiment.py): `scripts/run_experiment.py`
- [Experiment runner](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py): `src/infobottleneck/experiment.py`

### Data and modeling

- **MNIST dataset**
- [MNIST loaders](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/data.py): `src/infobottleneck/data.py`
- [Autoencoder and head](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/models.py): `src/infobottleneck/models.py`
- [Model training](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py): `src/infobottleneck/experiment.py`
- [Test evaluation](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/experiment.py): `src/infobottleneck/experiment.py`

### Information analysis

- [Activation capture](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py): `src/infobottleneck/analysis.py`
- [Region and MI metrics](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py): `src/infobottleneck/analysis.py`
- [Discrete metric helpers](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/utils.py): `src/infobottleneck/utils.py`
- [Metric correlations](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/analysis.py): `src/infobottleneck/analysis.py`

### Results and interpretation

- [Analysis plots](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/plots.py): `src/infobottleneck/plots.py`
- [Study report](https://github.com/allthingssecurity/informationbottleneck/blob/main/src/infobottleneck/report.py): `src/infobottleneck/report.py`
- [Result tables](https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study): `results/mnist_info_region_study`
- [Model checkpoints](https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study/models): `results/mnist_info_region_study/models`
- [Generated figures](https://github.com/allthingssecurity/informationbottleneck/tree/main/results/mnist_info_region_study/plots): `results/mnist_info_region_study/plots`
- [Generated report](https://github.com/allthingssecurity/informationbottleneck/blob/main/results/mnist_info_region_study/REPORT.md): `results/mnist_info_region_study/REPORT.md`

### Other components

- **Researcher**

## Connections

- Researcher → Experiment CLI: launches (evidence: `README.md`)
- Experiment CLI → Experiment runner: invokes (evidence: `scripts/run_experiment.py`)
- Experiment runner → MNIST loaders: builds loaders (evidence: `src/infobottleneck/experiment.py`)
- MNIST loaders → MNIST dataset: loads (evidence: `src/infobottleneck/data.py`)
- Experiment runner → Model training: runs sweep (evidence: `README.md`)
- Model training → Autoencoder and head: trains (evidence: `src/infobottleneck/experiment.py`)
- Experiment runner → Test evaluation: evaluates models (evidence: `src/infobottleneck/experiment.py`)
- Test evaluation → Autoencoder and head: evaluates (evidence: `src/infobottleneck/experiment.py`)
- Experiment runner → Model checkpoints: saves models (evidence: `src/infobottleneck/experiment.py`)
- Experiment runner → Activation capture: collects activations (evidence: `src/infobottleneck/experiment.py`)
- Activation capture → Autoencoder and head: captures layers (evidence: `src/infobottleneck/analysis.py`)
- Experiment runner → Region and MI metrics: builds metrics (evidence: `src/infobottleneck/experiment.py`)
- Region and MI metrics → Discrete metric helpers: summarizes IDs (evidence: `src/infobottleneck/analysis.py`)
- Experiment runner → Metric correlations: computes correlations (evidence: `src/infobottleneck/experiment.py`)
- Metric correlations → Result tables: writes metrics
- Experiment runner → Result tables: writes tables (evidence: `src/infobottleneck/experiment.py`)
- Experiment runner → Analysis plots: generates plots (evidence: `src/infobottleneck/experiment.py`)
- Analysis plots → Generated figures: saves figures (evidence: `src/infobottleneck/plots.py`)
- Experiment runner → Study report: generates report (evidence: `src/infobottleneck/experiment.py`)
- Study report → Result tables: reads tables (evidence: `src/infobottleneck/report.py`)
- Study report → Generated report: writes report (evidence: `src/infobottleneck/report.py`)
