AdaptShotConfig is a frozen (immutable) dataclass that controls every aspect of the AdaptShot pipeline. Once created, its values cannot be changed -- guaranteeing deterministic, reproducible behavior across runs. Create a new instance with dataclasses.replace() if you need different settings.
Feature extractor backbone. "mobilenet_v3_small" is bundled as ONNX and needs no torch; "resnet18" provides higher accuracy at the cost of ~45MB model size and slightly slower inference. "mobilenet_v3_small" is faster and lighter (~12MB) -- recommended for Raspberry Pi and low-RAM deployments. Both are frozen (not fine-tuned).
2
device
Literal["cpu", "cuda", "mps"]
"cpu"
Execution device. v0.1.1 is CPU-first: _validate_config() rejects non-CPU values with ConfigValidationError. CUDA and MPS are opt-in for future releases.
3
seed
int
42
Master random seed. Controls PyTorch (torch.manual_seed), NumPy (np.random.seed), Python (random.seed), and PYTHONHASHSEED. Change this to get different random behavior; fix it to 42 for reproducible benchmarks.
4
verbose
bool
True
Enable INFO-level logging during pipeline execution. Set to False for silent production operation.
5
log_dir
Optional[str]
None
Directory path for log output. When None, logs are written to stderr. Set to a valid directory path to persist logs to file.
Number of classes per episode. Controls the few-shot evaluation format. For production classification, the actual number of classes is determined by the unique labels in load_support_images().
7
k_shot
int
10
Support examples per class. Must be positive. Higher values improve accuracy but increase memory and embedding time. For very constrained deployments, reduce to 3-5.
8
query_size
int
15
Query examples per class for evaluation mode. Used in benchmark scripts. Not directly used in production predict() calls.
Distance metric for comparing embeddings. "euclidean" is faster and works well with normalized embeddings. "cosine" is direction-aware and robust to embedding magnitude differences.
Classification strategy. "nearest_neighbor" finds the single closest support example. "prototypical" computes a class prototype (mean embedding) and compares against it. "contrastive" (v0.2.0) uses contrastively refined prototypes with InfoNCE loss — best with >20 examples per class.
11
use_faiss
bool
False
Enable FAISS-CPU acceleration for similarity search. Improves latency for support sets >100 images. Requires pip install "adaptshot[faiss]". Falls back to NumPy if FAISS is not installed.
12
faiss_nprobe
int
8
FAISS IVF index probing depth. Higher values improve accuracy but increase search time. Only used when use_faiss=True and an IVF index is active.
Enable energy-saving early-exit. When True, the pipeline can exit early if a high-confidence match is found before full similarity computation. Reduces carbon footprint by up to 40% in benchmark testing.
14
early_exit_threshold
float
0.95
Confidence threshold for early-exit. Must be in [0.5, 1.0]. Higher values (e.g., 0.98) are more conservative and exit less often. Lower values (e.g., 0.85) save more energy but may miss subtle distinctions. Only active when eco_mode=True.
Post-hoc confidence calibration strategy. "temperature" applies a single scaling parameter (fast, stable). "scaling_binning" uses bin-wise scaling (more granular). "conformal" provides distribution-free prediction sets (stub in v0.1.1). "none" skips calibration entirely.
16
ece_n_bins
int
15
Number of bins for Expected Calibration Error (ECE) computation. Must be >1. More bins give finer-grained ECE tracking but require more observations for statistical validity.
17
calibration_eval_bins
int
100
Number of bins for calibration evaluation. Must be >= ece_n_bins. Controls the resolution of calibration quality reporting.
18
temperature_init
float
1.0
Initial temperature scaling parameter. Must be positive. A value of 1.0 means no scaling (raw confidence). The calibration engine adjusts this automatically as predictions accumulate.
19
recalibrate_after_feedback
bool
True
Whether to trigger calibration updates after each human correction. When True, the calibration window incorporates new feedback immediately. Set to False to batch calibration updates for efficiency.
Enable out-of-distribution detection. When True, images whose distance to any known prototype exceeds the threshold are flagged and routed for human review. When False, OOD threshold is set to infinity (no images are flagged).
21
ood_threshold_quantile
float
0.98
Quantile threshold for OOD rejection. Must be in [0.5, 1.0]. Uses the p98 distance among support examples (by default) as the cutoff. Higher values are more permissive; lower values flag more images as OOD.
22
ood_absolute_min_distance
float
0.25
Minimum absolute distance for OOD flagging. Must be >= 0.0. Acts as a floor: even if the quantile threshold is lower, images closer than this distance are never flagged.
Maximum replay buffer capacity. Must be >= 10. Controls the number of support embeddings retained in memory. When exceeded, UP-UGF pruning evicts low-utility examples based on uncertainty x recency x redundancy scoring. RAM usage scales linearly with this value (each embedding is ~2KB for ResNet-18 512-dim).
v0.2.0: Target miscoverage rate for conformal prediction sets. Must be in (0.0, 1.0). At alpha=0.05, prediction sets contain the true class with ≥95% probability.
25
conformal_mode
Literal["split", "cross"]
"split"
v0.2.0: Conformal prediction mode for inference-time quantile computation. "split" uses the full calibration buffer. "cross" uses k-fold cross-conformal averaging for more stable thresholds, at the cost of slightly conservative coverage. Note: True leave-one-out (LOO) self-calibration runs automatically at load_support_images() time regardless of this setting — it seeds the calibration buffer with exchangeable scores, enabling valid coverage from the first prediction.
v0.2.0: Uncertainty quantification signal to use. "entropy" = k-NN entropy. "mcdropout" = MC Dropout variance. "mahalanobis" = distance-based. "ensemble" = weighted fusion of all three.
27
explainability_enabled
bool
True
v0.2.0: Enable XAI explanations. When True, FewShotLearner.explain() generates feature attributions, confidence decomposition, counterfactual analysis, and historical penalty tracking.