adaptshot 0.1.1

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.1.1 is the current stable release, hardened with 52 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 ensures the model knows when it's unsure.
• Human-in-the-Loop: Integrated FeedbackRouter for real-time model adaptation through human expert corrections.
• Continual Learning: Implements CA-EWC (Class-Aware Elastic Weight Consolidation) and UP-UGF (Uncertainty-Guided Forgetting) for stable, long-term learning without catastrophic forgetting.
• 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%

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:

• 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.1.1

• Energy Profiling & Eco Mode: Track joules per inference and enable early-exit thresholds to reduce carbon footprint by up to 40%
• EmbeddingCache Isolation: Instance-scoped cache prevents cross-learner contamination in multi-model workflows
• Dynamic Dimension Inference: Backbone output dimensions are auto-detected from the model, not hardcoded
• OOD Detection: Built-in out-of-distribution detection flags images too far from known support distributions
• String Label Corrections: correct() now accepts human-readable string labels directly (e.g. "maize_blight")
• Prototypical Inference: New prototype-based classification mode alongside nearest-neighbor search
• 574 Downloads on PyPI: v0.1.0 reached researchers and practitioners in over 30 countries

🛠️ 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 or prototypical)
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

---

☁️ 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.1 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 |