# trustworthy-ml-lab/label-free-cbm architecture

> Architecture diagram of the GitHub repository trustworthy-ml-lab/label-free-cbm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trustworthy-ml-lab/label-free-cbm
- Repository: https://github.com/trustworthy-ml-lab/label-free-cbm

## Overview

LF-CBM is a research codebase for turning a pretrained image model into a concept bottleneck model without labeled concept data. The documented workflow is to create or select a concept set, train a concept projection and sparse classifier, then evaluate accuracy and inspect decision explanations. The graph also includes the standard-model training baseline and model-editing experiments. Some notebook and evaluation internals are unsampled; those links reflect README documentation rather than inspected implementation.

Main entry points: [`train_cbm.py`](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_cbm.py) (LF-CBM training), [`train_standard.py`](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_standard.py) (Standard training), [`clip/clip.py`](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/clip.py) (CLIP loading and transforms), [`utils.py`](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/utils.py) (Feature extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_concepts["Concept preparation"]
  node_gpt_init["GPT concept drafts"]
  node_conceptnet["ConceptNet concepts"]
  node_concept_filter["Concept filtering"]
  node_concept_files["Concept sets"]
end

subgraph group_training["Data and training"]
  node_dataset[("Image datasets<br/>[data_utils.py]")]
  node_cbm_train["LF-CBM training<br/>[train_cbm.py]"]
  node_standard_train["Standard training<br/>[train_standard.py]"]
  node_features["Feature extraction<br/>[utils.py]"]
  node_similarity["Concept similarity<br/>[similarity.py]"]
  node_sparse_solver["Sparse classifier<br/>[elasticnet.py]"]
end

subgraph group_models["Model runtime"]
  node_clip_api["CLIP loading and transforms<br/>[clip.py]"]
  node_clip_net["CLIP encoders<br/>[model.py]"]
  node_tokenizer["Text tokenizer"]
  node_cbm_runtime["CBM inference<br/>[cbm.py]"]
end

subgraph group_analysis["Evaluation and explanations"]
  node_evaluation["CBM evaluation<br/>[evaluate_cbm.ipynb]"]
  node_plots["Decision plots<br/>[plots.py]"]
  node_colors["Plot color maps<br/>[_colors.py]"]
  node_experiments["Model editing"]
end

node_researcher(("Researcher"))

node_researcher -->|"drafts concepts"| node_gpt_init
node_gpt_init -->|"processes drafts"| node_concept_filter
node_researcher -->|"selects alternative"| node_conceptnet
node_concept_filter -->|"produces sets"| node_concept_files
node_conceptnet -->|"produces sets"| node_concept_files
node_researcher -->|"starts training"| node_cbm_train
node_concept_files -->|"provides concepts"| node_cbm_train
node_dataset -->|"provides data"| node_cbm_train
node_cbm_train -->|"extracts activations"| node_features
node_cbm_train -->|"computes similarity"| node_similarity
node_cbm_train -->|"fits classifier"| node_sparse_solver
node_features -->|"loads data"| node_dataset
node_features -->|"loads CLIP"| node_clip_api
node_clip_api -->|"builds model"| node_clip_net
node_clip_api -->|"tokenizes text"| node_tokenizer
node_researcher -->|"starts baseline"| node_standard_train
node_standard_train -->|"loads data"| node_dataset
node_standard_train -->|"loads CLIP"| node_clip_api
node_standard_train -->|"fits classifier"| node_sparse_solver
node_researcher -->|"evaluates model"| node_evaluation
node_cbm_train -.->|"saves model"| node_cbm_runtime
node_evaluation -->|"evaluates model"| node_cbm_runtime
node_evaluation -->|"creates explanations"| node_plots
node_plots -->|"uses color maps"| node_colors
node_researcher -->|"runs experiments"| node_experiments

click node_gpt_init "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/GPT_initial_concepts.ipynb"
click node_conceptnet "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/ConceptNet_conceptset.ipynb"
click node_concept_filter "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/GPT_conceptset_processor.ipynb"
click node_concept_files "https://github.com/trustworthy-ml-lab/label-free-cbm/tree/main/data/concept_sets"
click node_dataset "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/data_utils.py"
click node_cbm_train "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_cbm.py"
click node_standard_train "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_standard.py"
click node_features "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/utils.py"
click node_similarity "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/similarity.py"
click node_sparse_solver "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/glm_saga/elasticnet.py"
click node_clip_api "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/clip.py"
click node_clip_net "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/model.py"
click node_tokenizer "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/simple_tokenizer.py"
click node_cbm_runtime "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/cbm.py"
click node_evaluation "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/evaluate_cbm.ipynb"
click node_plots "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/plots.py"
click node_colors "https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/colors/_colors.py"
click node_experiments "https://github.com/trustworthy-ml-lab/label-free-cbm/tree/main/experiments"

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_gpt_init,node_conceptnet,node_concept_filter,node_concept_files toneBlue
class node_dataset,node_cbm_train,node_standard_train,node_features,node_similarity,node_sparse_solver toneAmber
class node_clip_api,node_clip_net,node_tokenizer,node_cbm_runtime toneMint
class node_evaluation,node_plots,node_colors,node_experiments toneRose
class node_researcher toneIndigo
```

## Components

### Concept preparation

- [GPT concept drafts](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/GPT_initial_concepts.ipynb): `GPT_initial_concepts.ipynb`
- [ConceptNet concepts](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/ConceptNet_conceptset.ipynb): `ConceptNet_conceptset.ipynb`
- [Concept filtering](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/GPT_conceptset_processor.ipynb): `GPT_conceptset_processor.ipynb`
- [Concept sets](https://github.com/trustworthy-ml-lab/label-free-cbm/tree/main/data/concept_sets): `data/concept_sets`

### Data and training

- [Image datasets](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/data_utils.py): `data_utils.py`
- [LF-CBM training](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_cbm.py): `train_cbm.py`
- [Standard training](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/train_standard.py): `train_standard.py`
- [Feature extraction](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/utils.py): `utils.py`
- [Concept similarity](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/similarity.py): `similarity.py`
- [Sparse classifier](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/glm_saga/elasticnet.py): `glm_saga/elasticnet.py`

### Model runtime

- [CLIP loading and transforms](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/clip.py): `clip/clip.py`
- [CLIP encoders](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/model.py): `clip/model.py`
- [Text tokenizer](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/clip/simple_tokenizer.py): `clip/simple_tokenizer.py`
- [CBM inference](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/cbm.py): `cbm.py`

### Evaluation and explanations

- [CBM evaluation](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/evaluate_cbm.ipynb): `evaluate_cbm.ipynb`
- [Decision plots](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/plots.py): `plots.py`
- [Plot color maps](https://github.com/trustworthy-ml-lab/label-free-cbm/blob/main/colors/_colors.py): `colors/_colors.py`
- [Model editing](https://github.com/trustworthy-ml-lab/label-free-cbm/tree/main/experiments): `experiments`

### Other components

- **Researcher**

## Connections

- Researcher → GPT concept drafts: drafts concepts (evidence: `README.md`)
- GPT concept drafts → Concept filtering: processes drafts (evidence: `README.md`)
- Researcher → ConceptNet concepts: selects alternative (evidence: `README.md`)
- Concept filtering → Concept sets: produces sets (evidence: `README.md`)
- ConceptNet concepts → Concept sets: produces sets (evidence: `README.md`)
- Researcher → LF-CBM training: starts training (evidence: `README.md`)
- Concept sets → LF-CBM training: provides concepts (evidence: `README.md`)
- Image datasets → LF-CBM training: provides data (evidence: `README.md`)
- LF-CBM training → Feature extraction: extracts activations (evidence: `train_cbm.py`)
- LF-CBM training → Concept similarity: computes similarity (evidence: `train_cbm.py`)
- LF-CBM training → Sparse classifier: fits classifier (evidence: `train_cbm.py`)
- Feature extraction → Image datasets: loads data (evidence: `utils.py`)
- Feature extraction → CLIP loading and transforms: loads CLIP (evidence: `utils.py`)
- CLIP loading and transforms → CLIP encoders: builds model (evidence: `clip/clip.py`)
- CLIP loading and transforms → Text tokenizer: tokenizes text (evidence: `clip/clip.py`)
- Researcher → Standard training: starts baseline (evidence: `README.md`)
- Standard training → Image datasets: loads data (evidence: `train_standard.py`)
- Standard training → CLIP loading and transforms: loads CLIP (evidence: `train_standard.py`)
- Standard training → Sparse classifier: fits classifier (evidence: `train_standard.py`)
- Researcher → CBM evaluation: evaluates model (evidence: `README.md`)
- LF-CBM training → CBM inference: saves model
- CBM evaluation → CBM inference: evaluates model (evidence: `README.md`)
- CBM evaluation → Decision plots: creates explanations (evidence: `README.md`)
- Decision plots → Plot color maps: uses color maps (evidence: `plots.py`)
- Researcher → Model editing: runs experiments (evidence: `README.md`)
