adaptshot 0.2.0.dev0

Human-aligned few-shot vision learning for resource-constrained environments

AdaptShot

Human-Aligned Few-Shot Vision Learning for Resource-Constrained Environments

---

Documentation: https://johnson2006christopher.github.io/adaptshot/

Source Code: https://github.com/johnson2006christopher/adaptshot

---

AdaptShot is a high-performance, CPU-optimized, human-in-the-loop few-shot vision library. It is designed to learn from every human correction, guarantee calibrated uncertainty, and run deterministically on edge hardware with minimal resources.

v0.2.0-dev is the current release, hardened with 92 regression tests, strict type-checking, and a comprehensive benchmark harness. Built in Tanzania by a self-taught engineer with nothing but a laptop and determination.

🚀 Key Features

• CPU-First by Design: Optimized for low-latency inference on standard CPUs, requiring less than 250MB of RAM.
• Trustworthy & Calibrated: Built-in Expected Calibration Error (ECE) minimization and conformal prediction with finite-sample coverage guarantees.
• Human-in-the-Loop: Integrated FeedbackRouter for real-time model adaptation through human expert corrections.
• Continual Learning: Implements head-only CA-EWC (Fisher-regularized classification head fine-tuning, ~2K parameters) and UP-UGF (Uncertainty-Guided Forgetting with LSH-accelerated redundancy scoring) for stable, long-term learning without catastrophic forgetting.
• Multi-Signal Uncertainty: Epistemic (stochastic embedding perturbation sensitivity), aleatoric (k-NN entropy), and distributional (shrinkage-regularized Mahalanobis distance) uncertainty quantification with OOD detection. (Full MC Dropout planned for future torch-dependent release.)
• Explainable AI: Embedding-space feature attribution (which support examples influenced the prediction), confidence decomposition with historical penalty tracking, counterfactual explanations, and per-dimension saliency analysis.
• Contrastive Prototypes: Gradient-trained class representations via InfoNCE contrastive loss with 2-layer MLP projection head and EMA momentum prototype refinement.
• Release Hardened: Zero-config API, strict type safety, and a comprehensive benchmark harness for review and deployment readiness.
• Deterministic: Guaranteed reproducible results across different runs and hardware through strict seed management.

---

🧭 Why AdaptShot?

In many real-world scenarios—from rural clinics in Tanzania to remote agricultural fields—AI must operate under extreme constraints: sparse data, no GPU access, and limited connectivity.

AdaptShot addresses these challenges by prioritizing efficiency, transparency, and human collaboration. It turns the constraint of small data into an opportunity for high-quality, human-guided learning.

---

📦 Installation

$ pip install adaptshot

---> 100%

Core dependencies: numpy, Pillow (~15 MB total). PyTorch is optional — install it only if you need training/fine-tuning:

pip install "adaptshot[torch]"    # adds PyTorch + torchvision for training

Fast install: The base library installs in under 60 seconds on standard connections — no GPU drivers, no CUDA, no 2 GB downloads.

Optional Dependencies

AdaptShot provides optional extras for specialized workflows. The native Python API remains the source of truth; the GUI is an optional wrapper around it:

• PyTorch (Training): pip install "adaptshot[torch]" (Required for CA-EWC fine-tuning and custom backbones)
• FAISS Acceleration: pip install "adaptshot[faiss]" (Recommended for support sets >100 images)
• Gradio UI: pip install "adaptshot[ui]" (For interactive pilots and human-in-the-loop dashboards)
• Studio GUI: pip install "adaptshot[gui]" (For the offline, folder-aware AdaptShot Studio workspace)
• Development: pip install "adaptshot[dev]" (For contributors: testing, linting, and benchmarks)

---

💡 Quick Start

Create a Learner and Predict

It's as simple as initializing the FewShotLearner, loading your support images, and calling predict().

from adaptshot import FewShotLearner
from adaptshot.config.settings import AdaptShotConfig

# 1. Configure for your environment
config = AdaptShotConfig(
    backbone="resnet18",
    device="cpu",
    max_buffer_size=100
)

# 2. Initialize the learner
learner = FewShotLearner(config=config)

# 3. Load support set (examples the model learns from)
image_paths = ["data/healthy_leaf.jpg", "data/blighted_leaf.jpg"]
labels = ["healthy", "blight"]
learner.load_support_images(image_paths, labels)

# 4. Predict on a new image
result = learner.predict("data/query.jpg")

print(f"Prediction: {result.prediction}")
print(f"Confidence: {result.calibrated_confidence:.2%}")

# 5. Handle uncertainty
if result.uncertainty_flag:
    print("⚠️  Model is unsure. Routing for human review...")

---

🆕 What's New in v0.2.0

• Conformal Prediction: Distribution-free prediction sets with true leave-one-out calibration guaranteeing finite-sample coverage at configurable significance levels
• Contrastive Prototype Learning: Gradient-trained InfoNCE class prototypes with 2-layer MLP projection head (full backpropagation through W1/b1/W2/b2)
• Advanced Uncertainty: Three complementary signals — epistemic (stochastic perturbation sensitivity), aleatoric (k-NN entropy), and distributional (shrinkage-regularized Mahalanobis OOD) — fused with mode-gated computation
• XAI Explainability: Embedding-space feature attribution, confidence decomposition with historical penalty tracking, counterfactual analysis, and per-dimension saliency
• Cross-conformal prediction mode: K-fold cross-conformal quantile averaging for more stable prediction sets
• Bootstrap Temperature Calibration: Autonomous LOO grid-search temperature optimization for cold-start scenarios
• UP-UGF LSH Acceleration: Approximate O(N log N) redundancy scoring via random projection locality-sensitive hashing for large buffers (>100 examples)
• Memory Profiling: MemoryTracker with tracemalloc + psutil instrumentation for verifying <250MB RAM operation
• miniImageNet Benchmarks: Standard few-shot benchmarks with baseline references (Prototypical Networks, Matching Networks, MAML)
• ONNX Export: Bundled backbone export script with SHA-256 verification for torch-free inference
• ACT Symmetric Updates: Mean-reverting threshold adaptation prevents monotonic drift in autonomous operation
• 37 new tests (92 total) across conformal, contrastive, uncertainty, and explainability modules
• 12 new documentation pages: Architecture deep-dive, algorithm theory, API reference, 5 tutorials, 2 GUI guides

🛠️ Configuration

AdaptShot uses a strictly typed, immutable AdaptShotConfig to ensure reproducibility.

Core Execution

Parameter	Type	Default	Description
backbone	str	"resnet18"	Feature extractor (resnet18 or mobilenet_v3_small)
device	str	"cpu"	Execution device (cpu, cuda, or mps)
seed	int	42	Random seed for deterministic reproducibility
verbose	bool	True	Enable INFO-level logging

Few-Shot Learning

Parameter	Type	Default	Description
n_way	int	5	Number of classes per episode
k_shot	int	10	Support examples per class
query_size	int	15	Query examples per class for evaluation

Similarity & Inference

Parameter	Type	Default	Description
similarity_metric	str	"euclidean"	Distance metric (cosine or euclidean)
inference_mode	str	"prototypical"	Classification mode (nearest_neighbor, prototypical, or contrastive)
use_faiss	bool	False	Enable FAISS-CPU acceleration for large support sets
faiss_nprobe	int	8	FAISS IVF index probing depth

Energy-Aware Inference

Parameter	Type	Default	Description
eco_mode	bool	False	Enable energy-saving early-exit thresholds
early_exit_threshold	float	0.95	Confidence threshold for early-exit (0.5-1.0)

Calibration & Uncertainty

Parameter	Type	Default	Description
calibration_method	str	"temperature"	Method: temperature, scaling_binning, conformal, or none
ece_n_bins	int	15	Bins for Expected Calibration Error
calibration_eval_bins	int	100	Bins for calibration evaluation
temperature_init	float	1.0	Initial temperature scaling parameter
recalibrate_after_feedback	bool	True	Recalibrate after each human correction

OOD Detection

Parameter	Type	Default	Description
enable_ood_detection	bool	True	Flag images outside known support distribution
ood_threshold_quantile	float	0.98	Quantile threshold for OOD rejection (0.5-1.0)
ood_absolute_min_distance	float	0.25	Minimum absolute distance for OOD flagging

Memory Management

Parameter	Type	Default	Description
max_buffer_size	int	100	Maximum replay buffer capacity (enforced by UP-UGF)
log_dir	Optional[str]	None	Optional log output directory

Advanced Algorithms (v0.2.0)

Parameter	Type	Default	Description
conformal_alpha	float	0.05	Significance level for conformal prediction sets (0.01-0.50)
conformal_mode	str	"split"	Conformal prediction mode (split or cross)
uncertainty_mode	str	"ensemble"	Uncertainty mode (mcdropout, entropy, mahalanobis, or ensemble)
explainability_enabled	bool	True	Enable XAI explainability for predictions

---

☁️ Deployment

Cloud Environments

AdaptShot is ideal for cost-effective cloud deployments on standard CPU instances (e.g., AWS t3.medium, GCP e2-standard-2). Since it doesn't require GPUs, you can significantly reduce operational costs while maintaining high-throughput inference.

On-Premise & Edge

Designed for the edge, AdaptShot runs seamlessly on:

• Single Board Computers: Raspberry Pi 4+, Jetson Nano (CPU mode).
• Legacy Hardware: Older laptops and desktops with limited RAM.
• Offline Stations: Fully functional without internet access once the backbone weights are cached.

---

🤝 Contributing

We welcome contributions of all kinds! Whether you're fixing a bug, adding a new backbone, or improving documentation.

1. Check the Contributing Guidelines.
2. Install development dependencies: pip install -e ".[dev]".
3. Run tests to ensure everything is working: pytest tests/.
4. Submit a Pull Request.

---

📜 License

AdaptShot is open-source software licensed under the MIT License.

---

👤 About the Creator

Johnson Christopher Hassan

Vision AI Researcher & Software Engineer

Built in Mbeya, Tanzania 🇹🇿

GitHub | LinkedIn | Email

---

"The best AI doesn't guess confidently. It learns humbly, admits uncertainty, and improves through every human correction."

---

🔍 Summary of Key Updates

Change	Why It Matters
✅ Added GitHub Release badge	Points to the eventual packaged release assets
✅ Updated Docs badge to live MkDocs URL	Users can access accurate, searchable documentation immediately
✅ Fixed installation instructions to match pyproject.toml extras	Prevents user confusion; ensures pip install adaptshot[faiss] works
✅ Corrected API signatures to match actual code (FewShotLearner, PredictionResult)	Developers can copy-paste examples with confidence
✅ Marked v0.1.2 content as stable / released	Confirms publication status is accurate
✅ Removed placeholder links (arXiv:2604.XXXXX, adaptshot.dev/docs)	No broken links; only verified, working resources
✅ Kept the native API as the primary workflow	Reinforces code-first usage even with the optional GUI
✅ Standardized citation format to GitHub + version	Academically sound; reproducible referencing