README.md

---
license: other
license_name: arxiv-perpetual-non-exclusive
pipeline_tag: image-classification
tags:
  - few-shot-learning
  - image-classification
  - parameter-efficient
  - pytorch
datasets:
  - cifar-fs
  - mini-imagenet
---

# ALPINE: Adaptive Localization for Parameter- and Sample-Efficient Few-Shot Learning

[![arXiv](https://img.shields.io/badge/arXiv-2609.22323-b31b1b.svg)](https://arxiv.org/abs/2609.22323)
[![GitHub](https://img.shields.io/badge/GitHub-alpine--fewshot-blue.svg)](https://github.com/NeerajYadav-coder/alpine-fewshot)
[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Demo%20Space-blue.svg)](https://huggingface.co/spaces/NJ50/alpine-fewshot)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Official PyTorch checkpoints and reference architecture implementation for the paper:
> **"ALPINE: Adaptive Localization for Parameter- and Sample-Efficient Few-Shot Learning"**  
> *Neeraj Yadav (Independent Researcher, Uttar Pradesh, India)*  
> **ORCID iD**: [0009-0000-7847-0588](https://orcid.org/0009-0000-7847-0588)  
> **arXiv Preprint**: [arXiv:2609.22323](https://arxiv.org/abs/2609.22323) | [PDF](https://arxiv.org/pdf/2609.22323)  
> **GitHub Archive**: [https://github.com/NeerajYadav-coder/alpine-fewshot](https://github.com/NeerajYadav-coder/alpine-fewshot)  
> **Interactive Demo Space**: [https://huggingface.co/spaces/NJ50/alpine-fewshot](https://huggingface.co/spaces/NJ50/alpine-fewshot)

---

## 📌 Abstract

Few-shot learning research is predominantly evaluated on accuracy alone, with limited attention to the parameter and training-sample budgets required to reach that accuracy — a real constraint for practitioners without large-scale compute. We present an ultra-lightweight (22,249–34,917 parameter) spatial-relational architecture for few-shot image classification that combines fixed Gabor edge-energy guidance with a windowed, content-adaptive patch locator. Under a strictly matched, iso-episode-budget protocol (250 meta-training episodes, 5 canonical seeds, 600 evaluation episodes per seed), our architecture achieves statistically significant 5-shot accuracy gains over Prototypical Networks, Relation Networks, and MAML on both CIFAR-FS and MiniImageNet, while using less than half the parameters of any baseline. It also converges in fewer training episodes, generalizes better to an unseen fine-grained domain (CUB-200-2011 birds, zero retraining), and is more robust to 50% occlusion and 25% spatial translation than all three baselines. A series of falsification ablations — zeroing relational tokens at inference and retraining without them entirely — shows that the architecture's pairwise relational computation, while present, is not the primary driver of its performance; the content-adaptive patch locator is. We report this honestly, together with a capacity sweep showing a genuine accuracy plateau near 22–35k parameters, and release full seed-level results and checkpoint hashes for reproducibility.

---

## ⚠️ Important Note: Canonical vs. Optional Variant

This repository provides two clearly differentiated sets of checkpoints:

* **Primary Model: Canonical EXP-F3 (22,249 Parameters)**
  * **Location**: `checkpoints/canonical/`
  * **Role in Paper**: This is the default, reference architecture used for **all primary findings in the paper**, including 5-seed headline benchmarks, learning curve convergence tracking, occlusion robustness (50% masking), translation robustness (25% shift), cross-domain transfer to CUB-200-2011, and mechanistic patch-localization diagnostics.
  * *Always use this checkpoint set when reproducing or building upon the paper's core experimental claims.*

* **Optional Variant: EXP-F3-35k (34,917 Parameters)**
  * **Location**: `checkpoints/variant-35k/`
  * **Role in Paper**: A slightly wider channel configuration ($c_1=15, c_2=19, \text{embed}=32$, 34,917 parameters). It is included in **Table 1 only** as the empirical parameter-capacity "sweet spot."

---

## 🏆 Headline Benchmark Results (Table 1 from Paper)

All models evaluated under a strictly matched **iso-episode-budget protocol** (250 meta-training episodes, 5 canonical seeds `[1, 7, 21, 42, 123]`, 600 evaluation episodes per seed):

| Model | Parameters | CIFAR-FS 1-Shot | CIFAR-FS 5-Shot | MiniImageNet 1-Shot | MiniImageNet 5-Shot |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **ALPINE / EXP-F3-35k (Sweet Spot Variant)** | **34,917** | **40.61 ± 1.34%** | **58.67 ± 1.14%** | **36.76 ± 0.40%** | **53.81 ± 0.62%** |
| **ALPINE / EXP-F3 (Primary Canonical)** | **22,249** | **40.36 ± 1.26%** | **56.39 ± 1.28%** | **35.88 ± 0.88%** | **53.37 ± 0.72%** |
| Prototypical Networks (ProtoNet) [1] | 47,630 | 40.45 ± 0.73% | 53.77 ± 0.34% | 35.25 ± 0.45% | 48.82 ± 0.62% |
| Relation Networks [2] | 49,617 | 37.22 ± 0.72% | 47.60 ± 0.62% | 31.63 ± 1.17% | 38.18 ± 2.48% |
| MAML* [3] (*iso-budget only) | 49,481 | 29.07 ± 1.64% | 34.30 ± 3.04% | 27.90 ± 0.61% | 30.93 ± 1.40% |

---

## 📁 Checkpoints Catalog

This Hugging Face repository provides lean, representative checkpoints (`seed=1`) for both configurations:

### 1. Canonical EXP-F3 (22,249 Parameters)
| File Path | Dataset | Shot | Resolution | Format |
| :--- | :---: | :---: | :---: | :---: |
| `checkpoints/canonical/exp_f3_cifar_1shot_seed1.pt` | CIFAR-FS | 1-Shot | 32×32 | PyTorch state_dict |
| `checkpoints/canonical/exp_f3_cifar_5shot_seed1.pt` | CIFAR-FS | 5-Shot | 32×32 | PyTorch state_dict |
| `checkpoints/canonical/exp_f3_mini_1shot_seed1.pt` | MiniImageNet | 1-Shot | 84×84 | PyTorch state_dict |
| `checkpoints/canonical/exp_f3_mini_5shot_seed1.pt` | MiniImageNet | 5-Shot | 84×84 | PyTorch state_dict |

### 2. Optional Variant EXP-F3-35k (34,917 Parameters)
| File Path | Dataset | Shot | Resolution | Format |
| :--- | :---: | :---: | :---: | :---: |
| `checkpoints/variant-35k/exp_f3_35k_cifar_1shot_seed1.pt` | CIFAR-FS | 1-Shot | 32×32 | PyTorch dict |
| `checkpoints/variant-35k/exp_f3_35k_cifar_5shot_seed1.pt` | CIFAR-FS | 5-Shot | 32×32 | PyTorch dict |
| `checkpoints/variant-35k/exp_f3_35k_mini_1shot_seed1.pt` | MiniImageNet | 1-Shot | 84×84 | PyTorch dict |
| `checkpoints/variant-35k/exp_f3_35k_mini_5shot_seed1.pt` | MiniImageNet | 5-Shot | 84×84 | PyTorch dict |

*(Note: For the complete 5-seed reproducibility archive across all baselines and configurations with SHA-256 integrity verification, see the [GitHub Repository](https://github.com/NeerajYadav-coder/alpine-fewshot)).*

---

## 🚀 Quickstart & Usage

### 1. Clone or Download Repository
```bash
git clone https://huggingface.co/NJ50/alpine-fewshot
cd alpine-fewshot
```

### 2. Loading Checkpoints & Feature Extraction
```python
import torch
from src.models import load_alpine_model

device = "cuda" if torch.cuda.is_available() else "cpu"

# 1. Load Primary Canonical Model (22,249 parameters)
model = load_alpine_model(
    checkpoint_path="checkpoints/canonical/exp_f3_cifar_5shot_seed1.pt",
    model_type="canonical",
    dataset="cifar",
    device=device
)

# 2. Extract Few-Shot Representations
# Input: (Batch, 3, 32, 32)
sample_images = torch.randn(5, 3, 32, 32, device=device)
features = model.extract(sample_images) # Shape: (5, 32)
print("Extracted feature embeddings:", features.shape)

# 3. Inspect Adaptive Gabor-Guided Patch Centers
features, centers, rel_tokens = model.extract_with_rel_tokens(sample_images)
# centers has shape (Batch, 5, 2) in normalized coordinates [-1, 1]
print("Adaptive patch centers:", centers[0])
```

### 3. Run 5-Way Few-Shot Classification
```python
# Compute class prototypes from support set (5 classes x 5 shots)
# support_x: (25, 3, 32, 32), support_y: (25,) with labels [0..4]
prototypes = model.compute_prototypes(support_x, support_y, n=5)

# Predict query set (e.g. 75 query images)
logits = model.predict_proto(query_x, prototypes)
predictions = logits.argmax(dim=-1)
```

You can run the complete end-to-end simulation script:
```bash
python3 inference_example.py
```

---

## 🏔️ Interactive Online Demo

Try the interactive browser visualization of the adaptive patch locator in real-time on Hugging Face Spaces:  
👉 **[Hugging Face Space: NJ50/alpine-fewshot](https://huggingface.co/spaces/NJ50/alpine-fewshot)**

---

## 🔗 Full Reproducibility Archive

For the complete multi-seed reproducibility archive containing:
- All 5 seeds (`[1, 7, 21, 42, 123]`) checkpoints for all configurations and baselines
- SHA-256 and MD5 integrity verification manifests
- Automated benchmark replication scripts
- Publication figure generators

Please visit the official GitHub repository:
👉 **[https://github.com/NeerajYadav-coder/alpine-fewshot](https://github.com/NeerajYadav-coder/alpine-fewshot)**

---

## 📜 Citation

```bibtex
@article{yadav2026alpine,
  title={ALPINE: Adaptive Localization for Parameter- and Sample-Efficient Few-Shot Learning},
  author={Yadav, Neeraj},
  journal={arXiv preprint arXiv:2609.22323},
  year={2026},
  url={https://arxiv.org/abs/2609.22323}
}
```

---

## 📄 License
Checkpoints and code are released under the **MIT License**. Preprints and documentation are licensed under **arXiv perpetual non-exclusive license**.