NJ50/alpine-fewshot

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

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
arXiv Preprint: arXiv:2609.22323 | PDF
GitHub Archive: https://github.com/NeerajYadav-coder/alpine-fewshot
Interactive Demo Space: 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).

---

🚀 Quickstart & Usage

1. Clone or Download Repository

git clone https://huggingface.co/NJ50/alpine-fewshot
cd alpine-fewshot

2. Loading Checkpoints & Feature Extraction

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

# 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:

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

---

🔗 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

---

📜 Citation

@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.