adaptshot 0.1.0__py3-none-any.whl

adaptshot/__init__.py

@@ -0,0 +1,19 @@
+"""AdaptShot: Human-Aligned Few-Shot Vision Learning."""
+
+__version__ = "0.1.0"
+
+from .config.settings import AdaptShotConfig
+from .core.learner import FewShotLearner
+from .core.calibration import CalibrationEngine
+from .core.act import ACTEngine
+from .training.feedback_router import FeedbackRouter
+from .training.up_ugf import UPUGFPruner
+
+__all__ = [
+    "AdaptShotConfig",
+    "FewShotLearner",
+    "CalibrationEngine",
+    "ACTEngine",
+    "FeedbackRouter",
+    "UPUGFPruner",
+]

adaptshot/config/settings.py

@@ -0,0 +1,55 @@
+"""Immutable configuration dataclasses for AdaptShot."""
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+import torch
+
+
+@dataclass(frozen=True)
+class AdaptShotConfig:
+    """
+    Central, immutable configuration for the AdaptShot pipeline.
+
+    Using a frozen dataclass guarantees that pipeline hyperparameters cannot be
+    accidentally mutated during inference or training, which is critical for
+    deterministic reproducibility and CI/CD validation.
+    """
+    # Core execution
+    backbone: Literal["resnet18", "mobilenet_v3_small"] = "resnet18"
+    device: Literal["cpu", "cuda", "mps"] = "cpu"  # CPU-first default
+    seed: int = 42
+
+    # Few-shot learning parameters
+    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 search
+    use_faiss: bool = False # Toggle FAISS-CPU acceleration
+    faiss_nprobe: int = 8   # FAISS IVF index probing depth (if used later)
+
+    # Calibration & uncertainty
+    calibration_method: Literal["temperature", "conformal", "none"] = "temperature"
+    ece_n_bins: int = 15    # Number of bins for Expected Calibration Error
+    temperature_init: float = 1.0
+
+    # Memory management (UP-UGF)
+    max_buffer_size: int = 100
+
+    # Logging & debugging
+    verbose: bool = True
+    log_dir: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Validate configuration constraints immediately after creation."""
+        if self.k_shot <= 0 or self.n_way <= 0:
+            raise ValueError("n_way and k_shot must be positive integers.")
+        if self.max_buffer_size < 10:
+            raise ValueError("max_buffer_size must be >= 10 for meaningful few-shot operation.")
+        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
+            )

adaptshot/core/act.py

@@ -0,0 +1,134 @@
+"""Adaptive Confidence Thresholding (ACT) engine for few-shot predictions.
+
+Dynamically adjusts per-class decision thresholds based on real-time
+correction history and model uncertainty, reducing false acceptances
+by requesting human feedback when the model is genuinely unsure.
+"""
+
+import logging
+from typing import Dict, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class ACTEngine:
+    """
+    Adaptive Confidence Thresholding engine.
+
+    Maintains a dynamic threshold τ_k for each class k that adapts based on:
+    - Historical correction rates (incorrect vs. correct)
+    - Model uncertainty signals (entropy/ECE proxies)
+    - Configurable cost of requesting human feedback (γ)
+
+    The engine implements an exponential moving average update rule to
+    prevent oscillation while remaining responsive to distribution shift.
+    """
+
+    def __init__(
+        self,
+        base_threshold: float = 0.65,
+        learning_rate: float = 0.01,
+        feedback_cost_factor: float = 0.5,
+        min_threshold: float = 0.50,
+        max_threshold: float = 0.95,
+        n_classes: int = 100,
+    ) -> None:
+        """
+        Args:
+            base_threshold: Initial decision threshold for all classes
+            learning_rate: Step size for threshold adaptation (η)
+            feedback_cost_factor: Weight penalizing unnecessary human queries (γ)
+            min_threshold: Lower bound for τ_k
+            max_threshold: Upper bound for τ_k
+            n_classes: Preallocated number of class slots
+        """
+        self.eta = learning_rate
+        self.gamma = feedback_cost_factor
+        self.min_threshold = min_threshold
+        self.max_threshold = max_threshold
+
+        # Per-class state: {class_idx: {"threshold": float, "correct": float, "incorrect": float, "total": float}}
+        self._class_state: Dict[int, Dict[str, float]] = {}
+        for k in range(n_classes):
+            self._class_state[k] = {
+                "threshold": base_threshold,
+                "correct": 0.0,
+                "incorrect": 0.0,
+                "total": 0.0,
+            }
+
+    def should_accept(
+        self,
+        confidence: float,
+        class_idx: int,
+        recent_incorrect_rate: float = 0.0,
+        recent_correct_rate: float = 1.0,
+    ) -> Tuple[bool, str]:
+        """
+        Evaluate whether to accept a prediction or request human feedback.
+
+        Args:
+            confidence: Calibrated confidence score [0, 1]
+            class_idx: Predicted class index
+            recent_incorrect_rate: Fraction of recent corrections that were wrong [0, 1]
+            recent_correct_rate: Fraction of recent confirmations that were right [0, 1]
+
+        Returns:
+            (accept: bool, action: str) where action is "ACCEPT" or "REQUEST_FEEDBACK"
+        """
+        # Ensure class state exists (handles dynamic class expansion)
+        if class_idx not in self._class_state:
+            existing_thresholds = [s["threshold"] for s in self._class_state.values()]
+            default_thresh = float(np.mean(existing_thresholds)) if existing_thresholds else 0.65
+            self._class_state[class_idx] = {
+                "threshold": default_thresh,
+                "correct": 0.0,
+                "incorrect": 0.0,
+                "total": 0.0,
+            }
+
+        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
+
+        # Update counters (EMA-style tracking)
+        state["total"] += 1.0
+        if recent_incorrect_rate > 0.5:
+            state["incorrect"] += 1.0
+        else:
+            state["correct"] += 1.0
+
+        accept = confidence >= threshold
+        action = "ACCEPT" if accept else "REQUEST_FEEDBACK"
+
+        logger.debug(
+            f"ACT | Class {class_idx} | Conf: {confidence:.3f} | τ: {threshold:.3f} | Action: {action}"
+        )
+
+        return accept, action
+
+    def get_threshold(self, class_idx: int) -> float:
+        """Return the current adaptive threshold for a given class."""
+        if class_idx in self._class_state:
+            return float(np.clip(self._class_state[class_idx]["threshold"], self.min_threshold, self.max_threshold))
+        existing = [s["threshold"] for s in self._class_state.values()]
+        return float(np.clip(np.mean(existing), self.min_threshold, self.max_threshold)) if existing else 0.65
+
+    def get_all_thresholds(self) -> Dict[int, float]:
+        """Return a snapshot of all current class thresholds."""
+        return {k: self.get_threshold(k) for k in self._class_state}
+
+    def reset_class(self, class_idx: int, base_threshold: float = 0.65) -> None:
+        """Reset adaptation state for a specific class (e.g., after dataset reset)."""
+        if class_idx in self._class_state:
+            self._class_state[class_idx] = {
+                "threshold": base_threshold,
+                "correct": 0.0,
+                "incorrect": 0.0,
+                "total": 0.0,
+            }

adaptshot/core/calibration.py

@@ -0,0 +1,184 @@
+"""Online calibration module for few-shot vision predictions.
+
+Implements temperature scaling, Expected Calibration Error (ECE) tracking,
+and a conformal prediction stub for high-stakes deployment contexts.
+"""
+
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import torch
+
+
+class CalibrationEngine:
+    """
+    Tracks prediction calibration and applies post-hoc scaling to raw confidence scores.
+
+    Designed for streaming few-shot evaluation where a held-out validation set is
+    unavailable or too small. Maintains a sliding window of recent predictions to
+    fit temperature parameters online.
+    """
+
+    def __init__(
+        self,
+        n_bins: int = 15,
+        window_size: int = 100,
+        temperature_init: float = 1.0,
+        method: str = "temperature",
+    ) -> None:
+        """
+        Args:
+            n_bins: Number of bins for ECE computation (default: 15)
+            window_size: Size of sliding window for online temperature fitting
+            temperature_init: Initial temperature value (1.0 = no scaling)
+            method: Calibration method ("temperature" or "conformal")
+        """
+        self.n_bins = n_bins
+        self.window_size = window_size
+        self.temperature = torch.nn.Parameter(torch.tensor(temperature_init))
+        self.method = method
+
+        # Sliding window buffers
+        self._window_confidences: List[float] = []
+        self._window_correct: List[bool] = []
+
+        # ECE tracking state
+        self._ece_history: List[float] = []
+
+    def update(
+        self,
+        raw_confidence: float,
+        predicted_label: int,
+        true_label: int,
+    ) -> None:
+        """
+        Update calibration state with a new prediction and ground truth.
+
+        Maintains a fixed-size sliding window to enable online temperature fitting
+        without requiring a separate validation dataset.
+
+        Args:
+            raw_confidence: Cosine similarity score (unnormalized, typically [-1, 1])
+            predicted_label: Predicted class index
+            true_label: Ground truth class index
+        """
+        # Normalize raw confidence to [0, 1] for temperature scaling
+        norm_conf = (raw_confidence + 1.0) / 2.0
+        self._window_confidences.append(norm_conf)
+        self._window_correct.append(predicted_label == true_label)
+
+        # Maintain fixed window size
+        if len(self._window_confidences) > self.window_size:
+            self._window_confidences.pop(0)
+            self._window_correct.pop(0)
+
+        # Refit temperature if window is sufficiently populated
+        if len(self._window_confidences) >= max(10, self.window_size // 2):
+            self._refit_temperature()
+
+        # Update running ECE
+        current_ece = self.compute_ece(
+            np.array(self._window_confidences),
+            np.array(self._window_correct, dtype=int)
+        )
+        self._ece_history.append(current_ece)
+
+    def calibrate(self, raw_confidence: float) -> float:
+        """
+        Apply calibration to a raw confidence score.
+
+        Args:
+            raw_confidence: Unnormalized cosine similarity score
+
+        Returns:
+            Calibrated confidence in [0, 1]
+        """
+        if self.method == "conformal":
+            # Conformal stub: return conservative lower bound
+            return max(0.0, raw_confidence - 0.1)
+        
+        # Temperature scaling
+        norm_conf = (raw_confidence + 1.0) / 2.0
+        # Clamp to prevent extreme scaling
+        norm_conf = np.clip(norm_conf, 1e-6, 1.0 - 1e-6)
+        # Apply temperature
+        logit = np.log(norm_conf / (1.0 - norm_conf))
+        scaled = 1.0 / (1.0 + np.exp(-logit / float(self.temperature)))
+        return float(np.clip(scaled, 0.0, 1.0))
+
+    def compute_ece(
+        self,
+        confidences: np.ndarray,
+        labels_correct: np.ndarray,
+    ) -> float:
+        """
+        Compute Expected Calibration Error (ECE) on a set of predictions.
+
+        ECE measures the gap between average confidence and average accuracy
+        across confidence bins. Lower is better; <0.05 is the target.
+
+        Args:
+            confidences: Array of predicted confidence scores in [0, 1]
+            labels_correct: Binary array (1 if correct, 0 if incorrect)
+
+        Returns:
+            ECE value in [0, 1]
+        """
+        if len(confidences) == 0:
+            return 0.0
+
+        bin_boundaries = np.linspace(0.0, 1.0, self.n_bins + 1)
+        ece = 0.0
+        total_samples = len(confidences)
+
+        for i in range(self.n_bins):
+            in_bin = (confidences > bin_boundaries[i]) & (confidences <= bin_boundaries[i + 1])
+            prop_in_bin = in_bin.mean()
+
+            if prop_in_bin > 0:
+                avg_confidence = confidences[in_bin].mean()
+                avg_accuracy = labels_correct[in_bin].mean()
+                ece += np.abs(avg_accuracy - avg_confidence) * prop_in_bin
+
+        return float(ece)
+
+    def _refit_temperature(self) -> None:
+        """
+        Refit temperature parameter using NLL loss on the sliding window.
+        Uses a simple gradient-free line search for stability on CPU.
+        """
+        if len(self._window_confidences) < 10:
+            return
+
+        confs = np.array(self._window_confidences, dtype=np.float32)
+        correct = np.array(self._window_correct, dtype=np.float32)
+
+        # Clamp to prevent log(0)
+        confs = np.clip(confs, 1e-6, 1.0 - 1e-6)
+        logits = np.log(confs / (1.0 - confs))
+
+        # Grid search over reasonable temperature range [0.5, 3.0]
+        candidates = np.linspace(0.5, 3.0, 25)
+        best_loss = np.inf
+        best_T = float(self.temperature)
+
+        for T in candidates:
+            scaled_logits = logits / T
+            scaled_confs = 1.0 / (1.0 + np.exp(-scaled_logits))
+            # Binary cross-entropy loss
+            loss = -np.mean(correct * np.log(scaled_confs + 1e-6) + (1 - correct) * np.log(1.0 - scaled_confs + 1e-6))
+            if loss < best_loss:
+                best_loss = loss
+                best_T = T
+
+        self.temperature = torch.nn.Parameter(torch.tensor(best_T))
+
+    @property
+    def current_ece(self) -> float:
+        """Return the most recently computed ECE."""
+        return self._ece_history[-1] if self._ece_history else 0.0
+
+    @property
+    def current_temperature(self) -> float:
+        """Return the current temperature scaling parameter."""
+        return float(self.temperature)

adaptshot/core/extractor.py

@@ -0,0 +1,70 @@
+"""Frozen backbone feature extraction with TorchScript compatibility."""
+
+from typing import Union
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torchvision.models as models
+from PIL import Image
+from torchvision import transforms
+
+from ..config.settings import AdaptShotConfig
+
+# Type alias for flexible image input
+ImageInput = Union[str, np.ndarray, Image.Image, torch.Tensor]
+
+# Registry for backbone factories (extensible without modifying core logic)
+BackboneRegistry = {
+    "resnet18": lambda: models.resnet18(weights=models.ResNet18_Weights.IMAGENET1K_V1),
+    "mobilenet_v3_small": lambda: models.mobilenet_v3_small(
+        weights=models.MobileNet_V3_Small_Weights.IMAGENET1K_V1
+    ),
+}
+
+
+def _get_preprocess_transform(img_size: int = 224) -> transforms.Compose:
+    """Return standard preprocessing transforms for ImageNet-pretrained backbones."""
+    return transforms.Compose([
+        transforms.Resize((img_size, img_size), interpolation=transforms.InterpolationMode.BILINEAR),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+    ])
+
+
+def extract_embedding(
+    image: ImageInput,
+    config: AdaptShotConfig,
+    return_numpy: bool = True,
+) -> Union[torch.Tensor, np.ndarray]:
+    """Extract feature embedding from input image using a frozen backbone."""
+    # Load backbone from registry
+    if config.backbone not in BackboneRegistry:
+        raise ValueError(f"Unknown backbone: {config.backbone}. Available: {list(BackboneRegistry.keys())}")
+
+    backbone = BackboneRegistry[config.backbone]()
+    backbone.fc = nn.Identity()
+    backbone.to(config.device)
+    backbone.eval()
+
+    # Preprocess image
+    preprocess = _get_preprocess_transform()
+    
+    # ✅ ADD THIS: Handle file paths
+    if isinstance(image, str):
+        image = Image.open(image).convert("RGB")
+        
+    if isinstance(image, np.ndarray):
+        image = Image.fromarray(image)
+    elif isinstance(image, torch.Tensor):
+        if image.dim() == 3 and image.shape[0] not in (1, 3):
+            image = image.permute(2, 0, 1)
+        image = transforms.ToPILImage()(image.cpu())
+
+    # Apply transforms and add batch dimension
+    image_tensor = preprocess(image).unsqueeze(0).to(config.device)
+
+    with torch.no_grad():
+        embedding = backbone(image_tensor).squeeze(0)
+
+    return embedding.detach().cpu().numpy() if return_numpy else embedding