# jasonkyng/nagl architecture

> Architecture diagram of the GitHub repository jasonkyng/nagl, 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/jasonkyng/nagl
- Repository: https://github.com/jasonkyng/nagl

## Overview

NAGL is a PyTorch few-shot anomaly-detection research implementation. Its main workflow prepares benchmark data and metadata, samples query images with normal and abnormal reference shots, trains the NAGL model, then evaluates anomaly scores and segmentation results on target datasets. The model combines pretrained image features with normal- and abnormal-guided scoring; README documents RM/AFL as central capabilities. Source excerpts establish key training, sampling, detection, and metric interactions; some evaluation and preparation wiring is documented only at a higher level.

Main entry points: [`train.py`](https://github.com/jasonkyng/nagl/blob/main/train.py) (Training entry), [`models/model.py`](https://github.com/jasonkyng/nagl/blob/main/models/model.py) (NAGL model), [`utils/detection.py`](https://github.com/jasonkyng/nagl/blob/main/utils/detection.py) (Anomaly detection), [`dataset_preparation`](https://github.com/jasonkyng/nagl/tree/main/dataset_preparation) (Dataset metadata)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_visa_convert["VisA conversion"]
  node_metadata["Dataset metadata"]
  node_episode_data["Few-shot episodes<br/>[dataset.py]"]
end

subgraph group_learning["Model and training"]
  node_train_entry["Training entry<br/>[train.py]"]
  node_nagl["NAGL model<br/>[model.py]"]
  node_attention["Attention layers<br/>[attention_layer.py]"]
  node_losses["Training losses<br/>[loss.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_train_metrics["Training metrics<br/>[metrics.py]"]
  node_test_entry["Testing entry<br/>[test.py]"]
  node_inference["Anomaly detection<br/>[detection.py]"]
  node_image_metrics["Image metrics<br/>[post_eval.py]"]
  node_seg_metrics["Segmentation metrics"]
end

subgraph group_results["Results"]
  node_saved_results["Saved metrics"]
end

node_researcher(("Researcher"))
node_benchmarks[("Benchmark datasets")]
node_backbone["DINOv2 backbone"]
node_external_model["Pretrained model service"]

node_researcher -->|"configures training"| node_train_entry
node_researcher -->|"starts testing"| node_test_entry
node_benchmarks -->|"provides VisA data"| node_visa_convert
node_visa_convert -->|"reorganizes data"| node_metadata
node_benchmarks -->|"provides benchmark data"| node_metadata
node_metadata -->|"supplies meta.json"| node_episode_data
node_episode_data -->|"supplies episodes"| node_train_entry
node_train_entry -->|"trains model"| node_nagl
node_train_entry -->|"updates metrics"| node_train_metrics
node_train_entry -->|"combines losses"| node_losses
node_nagl -.->|"uses attention layers"| node_attention
node_nagl -.->|"uses loss functions"| node_losses
node_nagl -->|"extracts features"| node_backbone
node_backbone -->|"loads pretrained weights"| node_external_model
node_test_entry -.->|"runs detection"| node_inference
node_inference -->|"scores query images"| node_nagl
node_inference -.->|"evaluates predictions"| node_image_metrics
node_inference -.->|"evaluates maps"| node_seg_metrics
node_image_metrics -->|"writes metrics"| node_saved_results
node_seg_metrics -.->|"produces scores"| node_saved_results

click node_visa_convert "https://github.com/jasonkyng/nagl/blob/main/dataset_preparation/convert_visa_to_mvtec.py"
click node_metadata "https://github.com/jasonkyng/nagl/tree/main/dataset_preparation"
click node_episode_data "https://github.com/jasonkyng/nagl/blob/main/utils/dataset.py"
click node_train_entry "https://github.com/jasonkyng/nagl/blob/main/train.py"
click node_nagl "https://github.com/jasonkyng/nagl/blob/main/models/model.py"
click node_attention "https://github.com/jasonkyng/nagl/blob/main/models/attention_layer.py"
click node_losses "https://github.com/jasonkyng/nagl/blob/main/utils/loss.py"
click node_train_metrics "https://github.com/jasonkyng/nagl/blob/main/utils/metrics.py"
click node_test_entry "https://github.com/jasonkyng/nagl/blob/main/test.py"
click node_inference "https://github.com/jasonkyng/nagl/blob/main/utils/detection.py"
click node_image_metrics "https://github.com/jasonkyng/nagl/blob/main/utils/post_eval.py"
click node_seg_metrics "https://github.com/jasonkyng/nagl/blob/main/utils/post_eval_process.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_visa_convert,node_metadata,node_episode_data toneBlue
class node_train_entry,node_nagl,node_attention,node_losses,node_benchmarks toneAmber
class node_train_metrics,node_test_entry,node_inference,node_image_metrics,node_seg_metrics toneMint
class node_saved_results toneRose
class node_researcher,node_backbone,node_external_model toneIndigo
```

## Components

### Data preparation

- [VisA conversion](https://github.com/jasonkyng/nagl/blob/main/dataset_preparation/convert_visa_to_mvtec.py): `dataset_preparation/convert_visa_to_mvtec.py`
- [Dataset metadata](https://github.com/jasonkyng/nagl/tree/main/dataset_preparation): `dataset_preparation`
- [Few-shot episodes](https://github.com/jasonkyng/nagl/blob/main/utils/dataset.py): `utils/dataset.py`

### Model and training

- [Training entry](https://github.com/jasonkyng/nagl/blob/main/train.py): `train.py`
- [NAGL model](https://github.com/jasonkyng/nagl/blob/main/models/model.py): `models/model.py`
- [Attention layers](https://github.com/jasonkyng/nagl/blob/main/models/attention_layer.py): `models/attention_layer.py`
- [Training losses](https://github.com/jasonkyng/nagl/blob/main/utils/loss.py): `utils/loss.py`

### Evaluation

- [Training metrics](https://github.com/jasonkyng/nagl/blob/main/utils/metrics.py): `utils/metrics.py`
- [Testing entry](https://github.com/jasonkyng/nagl/blob/main/test.py): `test.py`
- [Anomaly detection](https://github.com/jasonkyng/nagl/blob/main/utils/detection.py): `utils/detection.py`
- [Image metrics](https://github.com/jasonkyng/nagl/blob/main/utils/post_eval.py): `utils/post_eval.py`
- [Segmentation metrics](https://github.com/jasonkyng/nagl/blob/main/utils/post_eval_process.py): `utils/post_eval_process.py`

### Results

- **Saved metrics**

### Other components

- **Researcher**
- **Benchmark datasets**
- **DINOv2 backbone**
- **Pretrained model service**

## Connections

- Researcher → Training entry: configures training (evidence: `README.md`)
- Researcher → Testing entry: starts testing (evidence: `README.md`)
- Benchmark datasets → VisA conversion: provides VisA data (evidence: `README.md`)
- VisA conversion → Dataset metadata: reorganizes data (evidence: `README.md`)
- Benchmark datasets → Dataset metadata: provides benchmark data (evidence: `README.md`)
- Dataset metadata → Few-shot episodes: supplies meta.json (evidence: `README.md`)
- Few-shot episodes → Training entry: supplies episodes (evidence: `train.py`)
- Training entry → NAGL model: trains model (evidence: `train.py`)
- Training entry → Training metrics: updates metrics (evidence: `train.py`)
- Training entry → Training losses: combines losses (evidence: `train.py`)
- NAGL model → Attention layers: uses attention layers (evidence: `models/model.py`)
- NAGL model → Training losses: uses loss functions (evidence: `models/model.py`)
- NAGL model → DINOv2 backbone: extracts features (evidence: `models/model.py`)
- DINOv2 backbone → Pretrained model service: loads pretrained weights
- Testing entry → Anomaly detection: runs detection
- Anomaly detection → NAGL model: scores query images (evidence: `utils/detection.py`)
- Anomaly detection → Image metrics: evaluates predictions (evidence: `utils/detection.py`)
- Anomaly detection → Segmentation metrics: evaluates maps
- Image metrics → Saved metrics: writes metrics (evidence: `utils/post_eval.py`)
- Segmentation metrics → Saved metrics: produces scores