# fabian57fabian/prototypical-networks-few-shot-learning architecture

> Architecture diagram of the GitHub repository fabian57fabian/prototypical-networks-few-shot-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fabian57fabian/prototypical-networks-few-shot-learning
- Repository: https://github.com/fabian57fabian/prototypical-networks-few-shot-learning

## Overview

##### Project type and purpose
- This is an open-source Python toolkit for few-shot image classification using Prototypical Networks.
- It provides command-line scripts for meta-training, meta-testing, centroid learning, and prediction against multiple image datasets.

##### File structure
- Top-level scripts:
- meta_train.py – orchestrates episode-based training
- meta_test.py – runs evaluation episodes on a saved model
- learn_centroids.py – computes class centroids from a trained embedding
- predict.py – classifies new images using stored centroids
- Core library in src/:
- cfg/defaults.yaml – configuration defaults loader
- core.py – main training/validation loop
- data/… – dataset interfaces (AbstractClassificationDataset, CustomDataset, specific datasets)
- prototypical_net.py – embedding network definition
- prototypical_loss.py – loss/metric implementation
- utils.py, EarlyStopping.py, centroids.py – helpers for training, checkpointing, and centroid computation
- Persistence:
- models/ – saved PyTorch model checkpoints
- results/ – logged training and evaluation outputs
- Tests:
- tests/ – unit tests for each core component
- Configuration files, CI workflow, and docs provide setup and reproducibility.

##### README for additional insights
- Confirms usage patterns, supported datasets, and script parameters (number of ways, shots, query samples, optimization settings).
- Highlights extensibility by allowing a “toy” custom dataset via the CustomDataset interface.

##### Main components and interactions
- MetaTrain Script
- MetaTest Script
- LearnCentroids Script
- Predict Script
- Configuration Loader (cfg)
- Data Loader (AbstractClassificationDataset + Specific Datasets)
- Embedding Network (prototypical_net)
- Loss & Metric (prototypical_loss)
- Training Engine (core)
- Utilities (utils, EarlyStopping, centroids)
- Model Checkpoints (models/)
- Centroid Files (runs/centroids_*)
- Results & Logs (results/)
- PyTorch / TorchVision
- File System / Dataset Storage (train/val/test folders)

- CLI → Configuration Loader: scripts parse CLI args and load defaults
- Configuration Loader → Training Engine / Data Loader
- Data Loader → Training Engine: yields episodes of (support, query) image tensors
- Training Engine → Embedding Network & Loss: forward pass, loss computation, backward pass
- Training Engine → Model Checkpoints: save best checkpoints via EarlyStopping
- LearnCentroids Script → Embedding Network → centroids utility → Centroid Files
- Predict Script → Embedding Network + Centroid Files → classification outputs → Results
- MetaTest Script uses same pipeline as MetaTrain but skips weight updates, writes evaluation metrics to Results

##### Architectural patterns and design principles
- Modular separation: CLI, configuration, data abstraction, model, loss, utilities
- Plugin-style dataset interfaces for extensibility
- Clean pipeline orchestration in core.py following the “engine” pattern
- Isolation of metric computation (prototypical_loss) from model definition
- Reusable utilities for early stopping and centroid computation

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Scripts"
        MT["MetaTrain Script"]:::cli
        MTe["MetaTest Script"]:::cli
        LC["LearnCentroids Script"]:::cli
        P["Predict Script"]:::cli
    end

    subgraph "Core Modules"
        CFG["Configuration Loader"]:::core
        subgraph "Data Loader"
            ABS["AbstractClassificationDataset"]:::core
            CUST["CustomDataset"]:::core
            FLOW["Flowers102Dataset"]:::core
            MINI["MiniImagenetDataset"]:::core
            OMNI["OmniglotDataset"]:::core
            CARS["StanfordCarsDataset"]:::core
        end
        ENG["Training Engine"]:::core
        EMB["Embedding Network"]:::core
        LOS["Loss & Metric"]:::core
        subgraph "Utilities"
            UT["General Helpers"]:::core
            ES["EarlyStopping"]:::core
            CNTUTIL["Centroid Computation"]:::core
        end
    end

    subgraph "Persistence/Outputs"
        MODELS["Model Checkpoints"]:::per
        CENT["Centroid Files"]:::per
        RESULTS["Results & Logs"]:::per
    end

    subgraph "External Dependencies"
        TORCH["PyTorch / TorchVision"]:::ext
        FS["File System / Dataset Storage"]:::ext
    end

    MT --> CFG
    MTe --> CFG
    LC --> CFG
    P --> CFG

    CFG --> ENG
    CFG --> ABS

    ABS --> ENG
    CUST --> ABS
    FLOW --> ABS
    MINI --> ABS
    OMNI --> ABS
    CARS --> ABS

    ENG --> EMB
    ENG --> LOS
    ENG --> ES
    ES --> MODELS
    ENG --> MODELS

    MTe --> ENG
    ENG --> RESULTS

    LC --> EMB
    EMB --> CNTUTIL
    CNTUTIL --> CENT

    P --> EMB
    P --> CENT
    EMB --> RESULTS
    CENT --> RESULTS

    ABS --> FS
    ENG --> TORCH
    EMB --> TORCH

    click MT "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/meta_train.py"
    click MTe "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/meta_test.py"
    click LC "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/learn_centroids.py"
    click P "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/predict.py"
    click CFG "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/cfg/defaults.yaml"
    click ABS "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/AbstractClassificationDataset.py"
    click CUST "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/CustomDataset.py"
    click FLOW "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/Flowers102Dataset.py"
    click MINI "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/MiniImagenetDataset.py"
    click OMNI "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/OmniglotDataset.py"
    click CARS "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/StanfordCarsDataset.py"
    click EMB "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/prototypical_net.py"
    click LOS "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/prototypical_loss.py"
    click ENG "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/core.py"
    click UT "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/utils.py"
    click ES "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/EarlyStopping.py"
    click CNTUTIL "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/blob/main/src/data/centroids.py"
    click MODELS "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/tree/main/models/"
    click RESULTS "https://github.com/fabian57fabian/prototypical-networks-few-shot-learning/tree/main/results/"

    classDef cli fill:#add8e6,stroke:#000,stroke-width:1px
    classDef core fill:#90ee90,stroke:#000,stroke-width:1px
    classDef per fill:#dda0dd,stroke:#000,stroke-width:1px
    classDef ext fill:#d3d3d3,stroke:#000,stroke-width:1px
```
