adaptshot 0.1.1__tar.gz → 0.2.0.dev0__tar.gz

{adaptshot-0.1.1/src/adaptshot.egg-info → adaptshot-0.2.0.dev0}/PKG-INFO

@@ -1,16 +1,15 @@
 Metadata-Version: 2.4
 Name: adaptshot
-Version: 0.1.1
+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: MIT
+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: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -19,10 +18,11 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: torch>=2.0.0
-Requires-Dist: torchvision>=0.15.0
 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
@@ -32,6 +32,7 @@ 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"
@@ -39,7 +40,7 @@ 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]; extra == "all"
+Requires-Dist: adaptshot[dev,faiss,gui,torch]; extra == "all"
 Dynamic: license-file
 
 
@@ -71,16 +72,19 @@ Dynamic: license-file
 
 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.
+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 ensures the model knows when it's unsure.
+*   **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 **CA-EWC** (Class-Aware Elastic Weight Consolidation) and **UP-UGF** (Uncertainty-Guided Forgetting) for stable, long-term learning without catastrophic forgetting.
+*   **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.
 
@@ -106,10 +110,19 @@ $ pip install adaptshot
 
 </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)
@@ -155,15 +168,21 @@ if result.uncertainty_flag:
 
 ---
 
-## 🆕 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
+## 🆕 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
 
@@ -191,7 +210,7 @@ AdaptShot uses a strictly typed, immutable `AdaptShotConfig` to ensure reproduci
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `similarity_metric` | `str` | `"euclidean"` | Distance metric (`cosine` or `euclidean`) |
-| `inference_mode` | `str` | `"prototypical"` | Classification mode (`nearest_neighbor` or `prototypical`) |
+| `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 |
 
@@ -227,6 +246,15 @@ AdaptShot uses a strictly typed, immutable `AdaptShotConfig` to ensure reproduci
 | `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
@@ -280,8 +308,6 @@ Built in Mbeya, Tanzania 🇹🇿
 <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
@@ -292,7 +318,7 @@ Built in Mbeya, Tanzania 🇹🇿
 | ✅ 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 |
+| ✅ 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.1.1 → adaptshot-0.2.0.dev0}/README.md

@@ -27,16 +27,19 @@
 
 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.
+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 ensures the model knows when it's unsure.
+*   **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 **CA-EWC** (Class-Aware Elastic Weight Consolidation) and **UP-UGF** (Uncertainty-Guided Forgetting) for stable, long-term learning without catastrophic forgetting.
+*   **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.
 
@@ -62,10 +65,19 @@ $ pip install adaptshot
 
 </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)
@@ -111,15 +123,21 @@ if result.uncertainty_flag:
 
 ---
 
-## 🆕 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
+## 🆕 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
 
@@ -147,7 +165,7 @@ AdaptShot uses a strictly typed, immutable `AdaptShotConfig` to ensure reproduci
 | Parameter | Type | Default | Description |
 | :--- | :--- | :--- | :--- |
 | `similarity_metric` | `str` | `"euclidean"` | Distance metric (`cosine` or `euclidean`) |
-| `inference_mode` | `str` | `"prototypical"` | Classification mode (`nearest_neighbor` or `prototypical`) |
+| `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 |
 
@@ -183,6 +201,15 @@ AdaptShot uses a strictly typed, immutable `AdaptShotConfig` to ensure reproduci
 | `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
@@ -236,8 +263,6 @@ Built in Mbeya, Tanzania 🇹🇿
 <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
@@ -248,7 +273,7 @@ Built in Mbeya, Tanzania 🇹🇿
 | ✅ 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 |
+| ✅ 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.1.1 → adaptshot-0.2.0.dev0}/pyproject.toml

@@ -4,16 +4,15 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "adaptshot"
-version = "0.1.1"
+version = "0.2.0-dev"
 description = "Human-aligned few-shot vision learning for resource-constrained environments"
 readme = "README.md"
-license = {text = "MIT"}
+license = "MIT"
 requires-python = ">=3.9"
 authors = [{name = "Johnson Christopher Hassan", email = "johnson2006christopher@gmail.com"}]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -21,16 +20,15 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Artificial Intelligence",
 ]
 dependencies = [
-    "torch>=2.0.0",
-    "torchvision>=0.15.0",
     "numpy>=1.24.0",
     "Pillow>=9.0.0",
 ]
 
 [project.optional-dependencies]
+torch = ["torch>=2.0.0", "torchvision>=0.15.0"]
 faiss = ["faiss-cpu>=1.7.4"]
 ui = ["gradio>=3.50.0"]
-gui = ["gradio>=3.50.0", "pandas>=2.0.0", "onnx>=1.16.0", "onnxscript>=0.3.0"]
+gui = ["gradio>=3.50.0", "pandas>=2.0.0", "onnx>=1.16.0", "onnxscript>=0.3.0", "onnxruntime>=1.14.0"]
 dev = [
     "pytest>=7.4.0",
     "pytest-cov>=4.1.0",
@@ -38,7 +36,7 @@ dev = [
     "ruff>=0.1.0",
     "pre-commit>=3.4.0",
 ]
-all = ["adaptshot[faiss,gui,dev]"]
+all = ["adaptshot[torch,faiss,gui,dev]"]
 
 [project.scripts]
 adaptshot-studio = "adaptshot.studio.app:launch"
@@ -52,6 +50,9 @@ Repository = "https://github.com/johnson2006christopher/adaptshot.git"
 [tool.setuptools.packages.find]
 where = ["src"]
 
+[tool.setuptools.package-data]
+"adaptshot" = ["data/*.onnx", "data/*.onnx.data"]
+
 [tool.ruff]
 target-version = "py39"
 line-length = 100
@@ -62,6 +63,14 @@ strict = true
 warn_return_any = true
 warn_unused_configs = true
 
+[[tool.mypy.overrides]]
+module = "onnxruntime"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "torchvision.*"
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 # Uncomment if pytest-cov is installed:

{adaptshot-0.1.1 → adaptshot-0.2.0.dev0}/src/adaptshot/__init__.py

@@ -1,11 +1,15 @@
 """AdaptShot: Human-Aligned Few-Shot Vision Learning."""
 
-__version__ = "0.1.1"
+__version__ = "0.2.0-dev"
 
 from .config.settings import AdaptShotConfig
 from .core.learner import FewShotLearner
 from .core.calibration import CalibrationEngine
 from .core.act import ACTEngine
+from .core.conformal import ConformalEngine, ConformalPredictionSet
+from .core.contrastive import ContrastivePrototypeLearner, ContrastiveConfig
+from .core.uncertainty import UncertaintyQuantifier, UncertaintyReport
+from .core.explain import ExplainabilityEngine, ExplanationResult, FeatureAttribution
 from .training.feedback_router import FeedbackRouter
 from .training.up_ugf import UPUGFPruner
 from .utils.exceptions import (
@@ -21,6 +25,15 @@ __all__ = [
     "FewShotLearner",
     "CalibrationEngine",
     "ACTEngine",
+    "ConformalEngine",
+    "ConformalPredictionSet",
+    "ContrastivePrototypeLearner",
+    "ContrastiveConfig",
+    "UncertaintyQuantifier",
+    "UncertaintyReport",
+    "ExplainabilityEngine",
+    "ExplanationResult",
+    "FeatureAttribution",
     "FeedbackRouter",
     "UPUGFPruner",
     "AdaptShotError",

{adaptshot-0.1.1 → adaptshot-0.2.0.dev0}/src/adaptshot/config/settings.py

@@ -3,8 +3,6 @@
 from dataclasses import dataclass
 from typing import Literal, Optional
 
-import torch
-
 
 @dataclass(frozen=True)
 class AdaptShotConfig:
@@ -29,7 +27,7 @@ class AdaptShotConfig:
     use_faiss: bool = False # Toggle FAISS-CPU acceleration
     faiss_nprobe: int = 8   # FAISS IVF index probing depth (if used later)
     similarity_metric: Literal["cosine", "euclidean"] = "euclidean"
-    inference_mode: Literal["nearest_neighbor", "prototypical"] = "prototypical"
+    inference_mode: Literal["nearest_neighbor", "prototypical", "contrastive"] = "prototypical"
 
     # Energy-aware inference
     eco_mode: bool = False
@@ -47,6 +45,16 @@ class AdaptShotConfig:
     ood_threshold_quantile: float = 0.98
     ood_absolute_min_distance: float = 0.25
 
+    # Conformal prediction (v0.2.0)
+    conformal_alpha: float = 0.05
+    conformal_mode: Literal["split", "cross"] = "split"
+
+    # Advanced uncertainty (v0.2.0)
+    uncertainty_mode: Literal["mcdropout", "entropy", "mahalanobis", "ensemble"] = "ensemble"
+
+    # Explainability (v0.2.0)
+    explainability_enabled: bool = True
+
     # Memory management (UP-UGF)
     max_buffer_size: int = 100
 
@@ -70,9 +78,24 @@ class AdaptShotConfig:
             raise ValueError("ood_threshold_quantile must be in [0.5, 1.0].")
         if self.ood_absolute_min_distance < 0.0:
             raise ValueError("ood_absolute_min_distance must be >= 0.0.")
-        if self.device == "cuda" and not torch.cuda.is_available():
-            import warnings
-            warnings.warn(
-                "CUDA requested but not available. Runtime logic will fall back to CPU.",
-                RuntimeWarning
-            )
+        if not 0.0 < self.conformal_alpha < 1.0:
+            raise ValueError("conformal_alpha must be in (0.0, 1.0).")
+        if self.conformal_mode not in ("split", "cross"):
+            raise ValueError("conformal_mode must be 'split' or 'cross'.")
+        if self.device == "cuda":
+            try:
+                import torch
+                if not torch.cuda.is_available():
+                    import warnings
+                    warnings.warn(
+                        "CUDA requested but not available. "
+                        "Runtime logic will fall back to CPU.",
+                        RuntimeWarning,
+                    )
+            except ImportError:
+                import warnings
+                warnings.warn(
+                    "CUDA requested but PyTorch is not installed. "
+                    "Install with: pip install 'adaptshot[torch]'",
+                    RuntimeWarning,
+                )

{adaptshot-0.1.1 → adaptshot-0.2.0.dev0}/src/adaptshot/core/act.py

@@ -48,6 +48,8 @@ class ACTEngine:
         self.gamma = feedback_cost_factor
         self.min_threshold = min_threshold
         self.max_threshold = max_threshold
+        self._base_threshold = base_threshold
+        self._mean_reversion_strength = 0.001  # Slow pull toward base
 
         # Per-class state: {class_idx: {"threshold": float, "correct": float, "incorrect": float, "total": float}}
         self._class_state: Dict[int, Dict[str, float]] = {}
@@ -92,9 +94,22 @@ class ACTEngine:
         state = self._class_state[class_idx]
         threshold = float(np.clip(state["threshold"], self.min_threshold, self.max_threshold))
 
-        # Update threshold: Δτ = η * (incorrect_rate - γ * correct_rate)
-        delta = self.eta * (recent_incorrect_rate - self.gamma * recent_correct_rate)
-        state["threshold"] = threshold + delta
+        # v0.2.0 fix: Symmetric bounded update with mean reversion.
+        # Previous formula (v0.2.0-dev): delta = η * (incorrect - γ * correct)
+        # This monotonically decreased thresholds because γ=0.5 multiplied the
+        # (usually larger) correct rate, creating a permanent downward bias.
+        #
+        # New formula: delta = η * (incorrect_rate - correct_rate) + μ * (base - τ)
+        # - Symmetric: equal weight to incorrect vs correct signals
+        # - Mean-reversion: thresholds drift back toward base_threshold slowly
+        # - Clamped: thresholds stay within [min_threshold, max_threshold]
+        error_signal = recent_incorrect_rate - recent_correct_rate
+        delta = self.eta * error_signal
+        # Mean-reversion toward base (prevents runaway drift)
+        delta += self._mean_reversion_strength * (self._base_threshold - threshold)
+        state["threshold"] = float(np.clip(
+            threshold + delta, self.min_threshold, self.max_threshold
+        ))
 
         # Update counters (EMA-style tracking)
         state["total"] += 1.0
@@ -103,11 +118,15 @@ class ACTEngine:
         else:
             state["correct"] += 1.0
 
-        accept = confidence >= threshold
+        # Re-read threshold after update for decision
+        threshold_updated = float(np.clip(
+            state["threshold"], self.min_threshold, self.max_threshold
+        ))
+        accept = confidence >= threshold_updated
         action = "ACCEPT" if accept else "REQUEST_FEEDBACK"
 
         logger.debug(
-            f"ACT | Class {class_idx} | Conf: {confidence:.3f} | τ: {threshold:.3f} | Action: {action}"
+            f"ACT | Class {class_idx} | Conf: {confidence:.3f} | τ: {threshold_updated:.3f} | Action: {action}"
         )
 
         return accept, action

adaptshot-0.2.0.dev0/src/adaptshot/core/backends/__init__.py

@@ -0,0 +1,11 @@
+"""Backend-agnostic feature extraction for AdaptShot.
+
+Auto-detects the best available backend (ONNX Runtime → PyTorch) and provides
+a unified ``extract_embedding()`` interface. The core library works with the
+lightweight onnxruntime dependency by default; install ``adaptshot[torch]``
+for training and fine-tuning support.
+
+Priority order:
+    1. ONNX Runtime (lightweight, fast install, CPU-optimized)
+    2. PyTorch (full flexibility, required for training)
+"""

adaptshot-0.2.0.dev0/src/adaptshot/core/backends/onnx_backend.py

@@ -0,0 +1,95 @@
+"""ONNX Runtime backend for lightweight feature extraction.
+
+Uses pre-exported ONNX backbone models bundled with the package.
+No PyTorch required – ideal for fast installation and edge deployment.
+
+The ONNX models are generated by: python scripts/export_backbones.py
+"""
+
+from __future__ import annotations
+
+import logging
+from functools import lru_cache
+from pathlib import Path
+from typing import Any, Dict
+
+import numpy as np
+from PIL import Image
+
+try:
+    import onnxruntime as ort
+
+    ONNX_AVAILABLE = True
+except ImportError:  # pragma: no cover – onnxruntime is optional
+    ONNX_AVAILABLE = False
+
+logger = logging.getLogger(__name__)
+
+_MODEL_DIR = Path(__file__).resolve().parent.parent.parent / "data"
+
+_ONNX_MODEL_FILES: Dict[str, str] = {
+    "resnet18": "resnet18.onnx",
+    "mobilenet_v3_small": "mobilenet_v3_small.onnx",
+}
+
+_OUTPUT_DIM: Dict[str, int] = {
+    "resnet18": 512,
+    "mobilenet_v3_small": 576,
+}
+
+_IMAGENET_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+_IMAGENET_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+
+class ONNXBackend:
+    """Feature extraction using ONNX Runtime with bundled backbone models."""
+
+    def __init__(self) -> None:
+        if not ONNX_AVAILABLE:
+            raise ImportError(
+                "onnxruntime is not installed. Run: pip install onnxruntime"
+            )
+
+    @lru_cache(maxsize=4)
+    def _get_session(self, backbone_name: str) -> Any:
+        """Load and cache an ONNX inference session for the given backbone."""
+        if backbone_name not in _ONNX_MODEL_FILES:
+            raise ValueError(
+                f"Unknown backbone: {backbone_name}. "
+                f"Available: {list(_ONNX_MODEL_FILES.keys())}"
+            )
+        model_path = _MODEL_DIR / _ONNX_MODEL_FILES[backbone_name]
+        if not model_path.exists():
+            raise FileNotFoundError(
+                f"ONNX model not found: {model_path}. "
+                f"Run scripts/export_backbones.py to generate it, "
+                f"or install with: pip install 'adaptshot[torch]'"
+            )
+        logger.info("Loading ONNX backbone from %s", model_path)
+        return ort.InferenceSession(
+            str(model_path), providers=["CPUExecutionProvider"]
+        )
+
+    def extract(
+        self, pil_image: Image.Image, backbone_name: str
+    ) -> np.ndarray:
+        """Run inference and return the feature embedding as a numpy array."""
+        session = self._get_session(backbone_name)
+        input_tensor = self._preprocess(pil_image)
+        input_name = session.get_inputs()[0].name
+        outputs = session.run(None, {input_name: input_tensor})
+        return outputs[0].squeeze(0)  # type: ignore[no-any-return]
+
+    @staticmethod
+    def _preprocess(pil_image: Image.Image) -> np.ndarray:
+        """Apply ImageNet-standard preprocessing: resize → normalize → NCHW."""
+        img = pil_image.resize((224, 224), Image.BILINEAR)  # type: ignore[attr-defined]
+        img_array = np.asarray(img, dtype=np.float32) / 255.0
+        img_array = (img_array - _IMAGENET_MEAN) / _IMAGENET_STD
+        img_array = np.transpose(img_array, (2, 0, 1)).astype(np.float32)
+        return img_array[np.newaxis, ...]
+
+    @property
+    def output_dim(self) -> Dict[str, int]:
+        """Return the embedding dimensionality for each supported backbone."""
+        return dict(_OUTPUT_DIM)

{adaptshot-0.1.1 → adaptshot-0.2.0.dev0}/src/adaptshot/core/calibration.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 from typing import Dict, List, Optional
 
 import numpy as np
-import torch
 
 
 class CalibrationEngine:
@@ -25,7 +24,7 @@ class CalibrationEngine:
         self.window_size = max(1, int(window_size))
         self.eval_bins = max(self.n_bins, int(evaluation_bins or self.n_bins))
         self.scaling_binning_bins = max(2, int(scaling_binning_bins or self.n_bins))
-        self.temperature = torch.nn.Parameter(torch.tensor(float(temperature_init), dtype=torch.float32))
+        self.temperature = float(temperature_init)
         self.method = method
 
         self._window_confidences: List[float] = []
@@ -148,7 +147,7 @@ class CalibrationEngine:
                 best_loss = float(loss)
                 best_temp = float(candidate)
 
-        self.temperature = torch.nn.Parameter(torch.tensor(best_temp, dtype=torch.float32))
+        self.temperature = best_temp
 
     def _refit_conformal_margin(self) -> None:
         """Update a conservative conformal-style correction margin."""