adaptshot 0.1.0__tar.gz → 0.2.0.dev0__tar.gz

adaptshot-0.2.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Johnson Christopher Hassan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adaptshot-0.2.0.dev0/PKG-INFO

@@ -0,0 +1,325 @@
+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 |
+

adaptshot-0.2.0.dev0/README.md

@@ -0,0 +1,280 @@
+
+<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 |
+