Metadata-Version: 2.4
Name: adaptshot
Version: 0.2.0.dev0
Summary: Human-aligned few-shot vision learning for resource-constrained environments
Author-email: Johnson Christopher Hassan <johnson2006christopher@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/johnson2006christopher/adaptshot
Project-URL: Documentation, https://github.com/johnson2006christopher/adaptshot/docs
Project-URL: Repository, https://github.com/johnson2006christopher/adaptshot.git
Project-URL: Bug Tracker, https://github.com/johnson2006christopher/adaptshot/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: Pillow>=9.0.0
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == "torch"
Requires-Dist: torchvision>=0.15.0; extra == "torch"
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.7.4; extra == "faiss"
Provides-Extra: ui
Requires-Dist: gradio>=3.50.0; extra == "ui"
Provides-Extra: gui
Requires-Dist: gradio>=3.50.0; extra == "gui"
Requires-Dist: pandas>=2.0.0; extra == "gui"
Requires-Dist: onnx>=1.16.0; extra == "gui"
Requires-Dist: onnxscript>=0.3.0; extra == "gui"
Requires-Dist: onnxruntime>=1.14.0; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.4.0; extra == "dev"
Provides-Extra: all
Requires-Dist: adaptshot[dev,faiss,gui,torch]; extra == "all"
Dynamic: license-file


<div align="center">

<img src="docs/images/adaptshot-logo.png" width="300" alt="AdaptShot Logo">

# AdaptShot

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

[![PyPI](https://img.shields.io/pypi/v/adaptshot.svg)](https://pypi.org/project/adaptshot/)
[![GitHub Release](https://img.shields.io/github/v/release/johnson2006christopher/adaptshot?label=GitHub%20Release)](https://github.com/johnson2006christopher/adaptshot/releases)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/adaptshot?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/adaptshot)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-MkDocs-blue)](https://johnson2006christopher.github.io/adaptshot/)
[![Built in Tanzania](https://img.shields.io/badge/Built%20in-Tanzania%20🇹🇿-gold.svg)](https://en.wikipedia.org/wiki/Tanzania)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-black)](https://github.com/astral-sh/ruff)
[![Type Checked: mypy](https://img.shields.io/badge/type--checked-mypy-blue)](https://mypy-lang.org/)

---

**Documentation**: [https://johnson2006christopher.github.io/adaptshot/](https://johnson2006christopher.github.io/adaptshot/)

**Source Code**: [https://github.com/johnson2006christopher/adaptshot](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.

</div>

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

<div class="termy">

```bash
$ pip install adaptshot

---> 100%
```

</div>

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

```bash
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()`.

```python
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](CONTRIBUTING.md).
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](LICENSE)**.

---

## 👤 About the Creator

<div align="center">
<img src="docs/images/johnson.jpeg" width="150" style="border-radius: 50%;" alt="Johnson Christopher Hassan">

**Johnson Christopher Hassan**

*Vision AI Researcher & Software Engineer*

Built in Mbeya, Tanzania 🇹🇿

[GitHub](https://github.com/johnson2006christopher) | [LinkedIn](https://www.linkedin.com/in/johnson-christopher-hassan) | [Email](mailto:johnson2006christopher@gmail.com)

</div>

---

<div align="center">
<p><i>"The best AI doesn't guess confidently. It learns humbly, admits uncertainty, and improves through every human correction."</i></p>
</div>

---

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

