# alvi-uiu/multihaludet architecture

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

- Interactive diagram: https://gitdiagram.com/alvi-uiu/multihaludet
- Repository: https://github.com/alvi-uiu/multihaludet

## Overview

MultiHaluDet is a research pipeline for detecting hallucinations in multilingual question-answer pairs by probing frozen LLM hidden states, training a deep detector, and stacking its out-of-fold features in a calibrated ensemble. The main workflow runs through `run_pipeline.py`: load a dataset, extract and persist features, train across folds and persist embeddings, then predict, evaluate, and plot results. The graph includes the documented model, loss, and augmentation capabilities; unsampled subsystem wiring is limited to what the README documents.

Main entry points: [`run_pipeline.py`](https://github.com/alvi-uiu/multihaludet/blob/main/run_pipeline.py) (Pipeline stages), [`src/training/trainer.py`](https://github.com/alvi-uiu/multihaludet/blob/main/src/training/trainer.py) (Fold training), [`src/data/feature_extractor.py`](https://github.com/alvi-uiu/multihaludet/blob/main/src/data/feature_extractor.py) (Hidden-state probing), [`src/data/loader.py`](https://github.com/alvi-uiu/multihaludet/blob/main/src/data/loader.py) (Dataset loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Data and probing"]
  node_pipeline["Pipeline stages<br/>[run_pipeline.py]"]
  node_config["Model registry<br/>[config.py]"]
  node_loader["Dataset loader<br/>[loader.py]"]
  node_extractor["Hidden-state probing"]
  node_feature_store["Feature artifacts"]
end

subgraph group_deep["Deep detection"]
  node_trainer["Fold training<br/>[trainer.py]"]
  node_model["MultiHaluDet<br/>[multihaludet.py]"]
  node_losses["Training losses<br/>[losses.py]"]
  node_augmentations["MixUp and CutMix<br/>[augmentations.py]"]
  node_oof_store["OOF embeddings"]
end

subgraph group_results["Ensemble and evaluation"]
  node_ensemble["Log-odds stacker<br/>[meta_learner.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_visualization["Result plots<br/>[visualization.py]"]
  node_results_store["Result artifacts"]
end

node_user(("Pipeline user"))
node_datasets["Dataset sources"]
node_llm["Frozen LLM"]

node_user -->|"selects stages"| node_pipeline
node_pipeline -->|"gets configuration"| node_config
node_pipeline -->|"loads samples"| node_loader
node_loader -.->|"loads dataset"| node_datasets
node_pipeline -->|"loads model"| node_llm
node_pipeline -->|"extracts features"| node_extractor
node_extractor -->|"probes hidden states"| node_llm
node_pipeline -->|"writes and reads"| node_feature_store
node_pipeline -->|"trains folds"| node_trainer
node_trainer -->|"optimizes and evaluates"| node_model
node_trainer -->|"computes loss"| node_losses
node_trainer -->|"augments batches"| node_augmentations
node_trainer -->|"uses hybrid dataset"| node_extractor
node_pipeline -->|"writes and reads"| node_oof_store
node_pipeline -->|"fits and predicts"| node_ensemble
node_pipeline -->|"evaluates probabilities"| node_metrics
node_pipeline -->|"plots results"| node_visualization
node_pipeline -->|"writes plots"| node_results_store

click node_pipeline "https://github.com/alvi-uiu/multihaludet/blob/main/run_pipeline.py"
click node_config "https://github.com/alvi-uiu/multihaludet/blob/main/src/config.py"
click node_loader "https://github.com/alvi-uiu/multihaludet/blob/main/src/data/loader.py"
click node_extractor "https://github.com/alvi-uiu/multihaludet/blob/main/src/data/feature_extractor.py"
click node_trainer "https://github.com/alvi-uiu/multihaludet/blob/main/src/training/trainer.py"
click node_model "https://github.com/alvi-uiu/multihaludet/blob/main/src/models/multihaludet.py"
click node_losses "https://github.com/alvi-uiu/multihaludet/blob/main/src/models/losses.py"
click node_augmentations "https://github.com/alvi-uiu/multihaludet/blob/main/src/training/augmentations.py"
click node_ensemble "https://github.com/alvi-uiu/multihaludet/blob/main/src/ensemble/meta_learner.py"
click node_metrics "https://github.com/alvi-uiu/multihaludet/blob/main/src/utils/metrics.py"
click node_visualization "https://github.com/alvi-uiu/multihaludet/blob/main/src/utils/visualization.py"

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_pipeline,node_config,node_loader,node_extractor,node_feature_store,node_user toneBlue
class node_trainer,node_model,node_losses,node_augmentations,node_oof_store toneAmber
class node_ensemble,node_metrics,node_visualization,node_results_store toneMint
class node_datasets,node_llm toneIndigo
```

## Components

### Data and probing

- [Pipeline stages](https://github.com/alvi-uiu/multihaludet/blob/main/run_pipeline.py): `run_pipeline.py`
- [Model registry](https://github.com/alvi-uiu/multihaludet/blob/main/src/config.py): `src/config.py`
- [Dataset loader](https://github.com/alvi-uiu/multihaludet/blob/main/src/data/loader.py): `src/data/loader.py`
- [Hidden-state probing](https://github.com/alvi-uiu/multihaludet/blob/main/src/data/feature_extractor.py): `src/data/feature_extractor.py`
- **Feature artifacts**

### Deep detection

- [Fold training](https://github.com/alvi-uiu/multihaludet/blob/main/src/training/trainer.py): `src/training/trainer.py`
- [MultiHaluDet](https://github.com/alvi-uiu/multihaludet/blob/main/src/models/multihaludet.py): `src/models/multihaludet.py`
- [Training losses](https://github.com/alvi-uiu/multihaludet/blob/main/src/models/losses.py): `src/models/losses.py`
- [MixUp and CutMix](https://github.com/alvi-uiu/multihaludet/blob/main/src/training/augmentations.py): `src/training/augmentations.py`
- **OOF embeddings**

### Ensemble and evaluation

- [Log-odds stacker](https://github.com/alvi-uiu/multihaludet/blob/main/src/ensemble/meta_learner.py): `src/ensemble/meta_learner.py`
- [Evaluation metrics](https://github.com/alvi-uiu/multihaludet/blob/main/src/utils/metrics.py): `src/utils/metrics.py`
- [Result plots](https://github.com/alvi-uiu/multihaludet/blob/main/src/utils/visualization.py): `src/utils/visualization.py`
- **Result artifacts**

### Other components

- **Pipeline user**
- **Dataset sources**
- **Frozen LLM**

## Connections

- Pipeline user → Pipeline stages: selects stages
- Pipeline stages → Model registry: gets configuration
- Pipeline stages → Dataset loader: loads samples
- Dataset loader → Dataset sources: loads dataset
- Pipeline stages → Frozen LLM: loads model
- Pipeline stages → Hidden-state probing: extracts features
- Hidden-state probing → Frozen LLM: probes hidden states
- Pipeline stages → Feature artifacts: writes and reads
- Pipeline stages → Fold training: trains folds
- Fold training → MultiHaluDet: optimizes and evaluates
- Fold training → Training losses: computes loss
- Fold training → MixUp and CutMix: augments batches
- Fold training → Hidden-state probing: uses hybrid dataset
- Pipeline stages → OOF embeddings: writes and reads
- Pipeline stages → Log-odds stacker: fits and predicts
- Pipeline stages → Evaluation metrics: evaluates probabilities
- Pipeline stages → Result plots: plots results
- Pipeline stages → Result artifacts: writes plots