adaptshot 0.1.0

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

🌿 AdaptShot

Zero-config, human-in-the-loop few-shot learning with calibrated uncertainty.
Train reliable vision models on <50 images/class, deploy on CPU, and let human corrections make it smarter in real-time.

---

🎯 Why AdaptShot Exists

Most few-shot libraries assume abundant compute, massive pretraining, or black-box predictions. Real-world deployments don't work that way. Labeled data is scarce. Edge devices are CPU-bound. Mistakes are costly. AdaptShot bridges the gap between research and production by treating human feedback, uncertainty calibration, and resource constraints as first-class citizens.

Feature	Existing Tools	AdaptShot
Training data required	1,000+ images	10–50 images/class
Compute dependency	GPU assumed	CPU-first, <50ms latency
Uncertainty handling	Afterthought or missing	Calibrated ECE < 0.05 out-of-the-box
Human feedback	Offline, custom scaffolding	Built-in active learning loop
Continual learning	Catastrophic forgetting common	CA-EWC + ACT prevent degradation
Transparency	Black-box predictions	Nearest-neighbor explanation + adaptive thresholds

---

⚡ Quick Start

# Install
pip install adaptshot

# Predict & learn in 5 lines
from adaptshot import FewShotLearner, FeedbackRouter

learner = FewShotLearner(backbone="resnet18", classes=["cat", "dog", "bird"], device="cpu")
learner.load_support_images("path/to/fewshot_dataset/")

pred, confidence, neighbor = learner.predict("new_image.jpg")
learner.feedback("new_image.jpg", corrected_label="dog")  # Triggers incremental fine-tuning

---

🧠 How It Works

┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│   Input     │────▶│ Embedding       │────▶│ Similarity       │
│   Image     │     │ (512-dim CPU)   │     │ Search (FAISS/NumPy)│
└─────────────┘     └─────────────────┘     └──────────────────┘
                                                      │
                                                      ▼
┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
│  Human      │◀────│ ACT Threshold   │◀────│ Calibrated       │
│  Feedback   │     │ (Accept/Request)│     │ Confidence (ECE) │
└─────────────┘     └─────────────────┘     └──────────────────┘
        │
        ▼
┌─────────────────────────────────────────────────────────────────┐
│ CA-EWC Fine-Tuning + UP-UGF Memory Pruning → Updated Buffer     │
└─────────────────────────────────────────────────────────────────┘

---

🔑 Core Features

Module	Description
FewShotLearner	Deterministic trainer for N-way K-shot tasks. Freezes backbone, trains classifier head, tracks ECE.
SimilarityEngine	Hybrid NumPy + FAISS-CPU cosine search. O(1) fallback, O(log N) scaling.
FeedbackRouter	Wires ✓/✗ UI inputs to replay buffer + incremental fine-tuning loop.
ACT	Adaptive Confidence Thresholding. Raises decision bar when uncertainty or correction history is high.
CA-EWC	Correction-Aware Elastic Weight Consolidation. Prevents catastrophic forgetting by weighting regularization with human feedback confidence.
UP-UGF	Uncertainty-Guided Forgetting. Prunes low-value embeddings using recency, redundancy, and uncertainty scores.
Benchmarks	CPU-safe latency, ECE, accuracy tracking. CI-ready, reproducible across seeds/hardware.

---

📦 Installation

Stable Release

pip install adaptshot

Optional Dependencies

# FAISS acceleration (CPU)
pip install adaptshot[faiss]

# Development & testing
pip install adaptshot[dev]

# Full stack (docs, examples, benchmarks)
pip install adaptshot[all]

From Source

git clone https://github.com/yourusername/adaptshot.git
cd adaptshot
pip install -e .[dev]
pytest tests/ -v

---

📖 Usage Examples

🔍 Basic Prediction

from adaptshot import FewShotLearner

learner = FewShotLearner(
    backbone="resnet18",
    classes=["apple", "banana", "orange"],
    device="cpu"
)
learner.load_support("dataset/train/", k=10)

pred, conf, neighbor_img = learner.predict("dataset/test/img_042.jpg")
print(f"Prediction: {pred} | Confidence: {conf:.3f}")

🔄 Active Learning Loop

from adaptshot import FeedbackRouter

router = FeedbackRouter(learner, capacity=100, ewc_lambda=0.1)

# Simulate human correction
if pred != true_label:
    router.feedback(image_path="dataset/test/img_042.jpg", corrected_label=true_label)
    print(f"✅ Model updated. Buffer size: {len(router.buffer)}")

📊 Calibration & Benchmarking

from adaptshot.evaluation import BenchmarkSuite

suite = BenchmarkSuite(learner)
results = suite.run(test_loader="dataset/test/", n_runs=50)
print(results.table())
# Output: Latency: 12.4ms | Accuracy: 0.74 | ECE: 0.031

---

🔬 Novel Algorithms (The Research Moat)

Algorithm	Patent Status	What It Solves
ACT (Adaptive Confidence Thresholding)	Provisional drafted	Prevents false positives by raising decision thresholds when uncertainty or correction history is high
CA-EWC (Correction-Aware Elastic Weight Consolidation)	Provisional drafted	Scales regularization strength by human feedback confidence, enabling stable continual learning
UP-UGF (Uncertainty-Guided Forgetting)	Provisional drafted	Prunes replay buffer embeddings using uncertainty, recency, and redundancy scores. Keeps memory ≤100 samples

Full methodology, equations, and ablation studies are available in our arXiv preprint and docs/paper/.

---

📈 Performance Benchmarks (CPU: AMD Ryzen 7 5800H)

Task	Images/Class	Accuracy	ECE	Latency (p95)	Memory
CIFAR-10 Subset	10	74.2%	0.031	12.4 ms	142 MB
TinyImageNet	20	68.9%	0.044	18.1 ms	189 MB
Custom Agriculture	50	89.1%	0.028	21.3 ms	210 MB

All results deterministic across seed=42. Benchmarked with python -m benchmarks.run --cpu-only.

---

🛠️ Contributing

AdaptShot is open-source and community-driven. We welcome:

• 🐛 Bug reports & performance profiles
• 📝 Documentation improvements & translations
• 🔬 Algorithm extensions & new backends
• 🎨 UI/UX enhancements & demo notebooks

Getting Started:

1. Fork the repo
2. Create a feature branch: git checkout -b feat/your-feature
3. Commit changes: git commit -m "feat: add your feature"
4. Push & open a Pull Request
5. Ensure pytest, mypy, and ruff pass locally

See CONTRIBUTING.md and CODE_OF_CONDUCT.md for full guidelines.

---

📄 License & Citation

License

AdaptShot is released under the MIT License.
Commercial deployments, enterprise support, or white-label usage require a separate license. Contact [e-mail] for details.

Citation

If you use AdaptShot in research, please cite:

@misc{adaptshot2024,
  title={AdaptShot: Zero-Config Human-in-the-Loop Few-Shot Learning with Calibrated Uncertainty},
  author={Hassan, Johnson},
  year={2024},
  howpublished={\url{https://github.com/yourusername/adaptshot}},
  note={arXiv:2404.XXXXX}
}

---

🗺️ Roadmap

Phase	Status	Deliverables
v0.0.1 Alpha	✅ Complete	Core pipeline, CPU-safe embedding, Gradio demo
v0.1.0 Beta	🟡 In Progress	ACT/CA-EWC/UP-UGF integration, PyPI packaging, CI/CD
v1.0.0 Stable	⏳ Planned	Full docs, HF Spaces deployment, multi-backend support
v2.0.0 Edge	🔮 Future	ONNX/TFLite export, federated learning hooks, mobile SDK

Track progress in ROADMAP.md or open a Discussion for feature requests.

---

🙏 Acknowledgments

• Research Inspiration: Few-shot learning literature, active learning frameworks, uncertainty calibration benchmarks
• Open-Source Ecosystem: PyTorch, Hugging Face, FAISS, Gradio, scikit-learn
• Community: Contributors, testers, early adopters, and everyone who believes AI should be transparent, efficient, and human-aligned

---

📬 Stay Connected

• 🐙 GitHub: github.com/yourusername/adaptshot
• 📄 arXiv: Coming Soon
• 💬 Discord: Join the community
• 🐦 Twitter/X: @yourhandle
• 📧 Contact: [e-mail]

---

"The best AI doesn't guess. It learns, admits uncertainty, and improves with every correction."
— AdaptShot Project Notes

🚀 Star the repo, fork the code, and help us build practical AI for the real world.