recall_guard.mia
recall_guard.mia
Public API for the mia layer of the honest-model-ranking harness.
Re-exports the consumer-facing surface (Req 12.1) so that callers (the qualification notebook, future external scripts, and the harness layers themselves) can import the MIA feature primitives, the per-model control baseline, and the per-model MCS calibrator from the package root::
from recall_guard.mia import (
MiaFeatures, compute_mia_features, LOGPROB_FLOOR,
ControlBaseline, build_baseline, standardise,
MCSCalibrator, train_mcs,
)
train_mcs is the documented public name for the calibrator's training
function (Req 12.1, Task 5.5 brief). The original function is defined as
:func:recall_guard.mia.mcs.train; train_mcs is re-exported as an alias here so
notebook code reads as "train an MCS calibrator" rather than the more
ambiguous bare train. Both names point at the same callable.
LOGPROB_FLOOR
module-attribute
LOGPROB_FLOOR = -30.0
Lower bound for individual logprob values, applied before averaging.
Prevents a single -inf (or extremely negative) per-token logprob from
poisoning loss / min_k / zlib_ratio / ref_delta.
ControlBaseline
dataclass
Per-model baseline distribution of every MIA feature on the OOS control corpus.
Attributes:
| Name | Type | Description |
|---|---|---|
model |
str
|
The NVIDIA model ID this baseline was built for. |
n_valid |
int
|
Number of control rows where |
feature_means |
dict[str, float | None]
|
Per-feature mean across the valid rows. Keys are the five MIA feature
names. |
feature_stds |
dict[str, float | None]
|
Per-feature standard deviation across the valid rows, floored at
|
is_calibrated |
bool
|
|
min_valid |
int
|
The threshold used (default 50, per the Open Defaults in requirements.md). |
Source code in recall_guard/mia/control.py
45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | |
MiaFeatures
dataclass
Five MIA features for one (model, prompt, response) record.
Attributes:
| Name | Type | Description |
|---|---|---|
loss |
float
|
Mean negative logprob of the realised tokens (clipped at floor). Low loss means the model found the text easy to predict, which is what stored text looks like. |
min_k |
float
|
Mean of the bottom |
min_k_pp |
float
|
Mean of the bottom-K per-position z-scores (Min-K%++). Same idea as
|
zlib_ratio |
float
|
|
ref_delta |
float | None
|
|
Source code in recall_guard/mia/features.py
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 | |
MCSCalibrator
dataclass
Per-model logistic-regression calibrator for p(memorized | features).
Attributes:
| Name | Type | Description |
|---|---|---|
model |
str
|
The NVIDIA model ID this calibrator was trained for. |
classifier |
LogisticRegression
|
The fitted |
feature_order |
list[str]
|
Canonical order used to flatten the standardised feature dict
into the classifier's input vector. Populated at train time and
consumed verbatim by :meth: |
holdout_auc |
float
|
ROC-AUC score of the trained classifier on the 25% held-out portion of the labelled IS/OOS corpus. Reported in the manifest and the per-model evaluation result (Req 5.2). |
is_weak |
bool
|
|
Source code in recall_guard/mia/mcs.py
61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | |
predict_proba
predict_proba(features, baseline)
Return the calibrated probability of "memorized" for one record.
Standardises features against the model's baseline and
feeds the resulting vector to the trained classifier in
self.feature_order.
Returns:
| Type | Description |
|---|---|
float
|
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If any of the four core features standardises to |
Source code in recall_guard/mia/mcs.py
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 | |
build_baseline
build_baseline(
model_lm,
control_rows,
ref_lm,
min_valid=50,
max_workers=1,
)
Build a per-model control-corpus baseline.
For each row in control_rows:
- Call
model_lm.generate(row.prompt). OnTimeoutErrororRuntimeError(e.g., missing logprobs) the row is dropped and a WARNING is logged with the row index. - When
ref_lmis provided, also callref_lm.generate(row.prompt). A reference-side failure does not invalidate the row; it merely setsref_logprobs = Nonefor that row, so the four other features still contribute to the baseline. - Compute :class:
MiaFeaturesvia :func:compute_mia_features.
Per-feature mean and std are aggregated with numpy.mean and
numpy.std(ddof=0). Std is floored at _STD_FLOOR to avoid div-by-zero
in :func:standardise. When every valid row has ref_delta = None
(because ref_lm is None or every reference call failed), the
ref_delta mean and std are stored as None.
is_calibrated is set to n_valid >= min_valid.
Source code in recall_guard/mia/control.py
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 | |
standardise
standardise(features, baseline)
Standardise eval-time MIA features against the model's control baseline.
For each of the four always-present features loss, min_k,
min_k_pp, zlib_ratio returns (value - mean) / max(std, _STD_FLOOR).
For ref_delta returns None whenever either the baseline or the
eval-time features have no reference value to standardise, i.e., the
field stays "off" rather than being silently coerced to 0.0.
Source code in recall_guard/mia/control.py
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 | |
compute_mia_features
compute_mia_features(
response, logprobs, ref_logprobs, k=0.2
)
Compute the five MIA features for one record.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
response
|
str
|
The model's emitted text. Used only for the zlib-ratio denominator. |
required |
logprobs
|
list[TokenLogprob]
|
Per-token logprob entries from |
required |
ref_logprobs
|
list[TokenLogprob] | None
|
Per-token logprobs from a reference model on the same prompt; or
|
required |
k
|
float
|
Fraction of tokens used for the bottom-K slice in Min-K% and Min-K%++. Defaults to 0.2 (the paper's setting). |
0.2
|
Returns:
| Type | Description |
|---|---|
MiaFeatures
|
Frozen dataclass with all five features. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in recall_guard/mia/features.py
155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | |
train_mcs
train_mcs(
model_lm,
is_memorized,
oos_control,
baseline,
ref_lm,
min_auc=0.6,
seed=0,
max_workers=1,
)
Train the MCS classifier for one model.
Drives the LM over both labelled corpora (in parallel when
max_workers > 1), fits a logistic regression on the standardised
features, and reports a held-out AUC. Raises ValueError if either
class ends up empty after per-row skips.
Source code in recall_guard/mia/mcs.py
305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 | |