entropy-protocol 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. entropy_protocol/__init__.py +11 -0
  2. entropy_protocol/_unicode14.py +120 -0
  3. entropy_protocol/attest.py +62 -0
  4. entropy_protocol/attested/__init__.py +6 -0
  5. entropy_protocol/attested/amd.py +221 -0
  6. entropy_protocol/attested/appraise.py +325 -0
  7. entropy_protocol/attested/attester.py +58 -0
  8. entropy_protocol/attested/authority.py +239 -0
  9. entropy_protocol/attested/azure_cgpu.py +186 -0
  10. entropy_protocol/attested/binding.py +71 -0
  11. entropy_protocol/attested/capture.py +109 -0
  12. entropy_protocol/attested/ear.py +94 -0
  13. entropy_protocol/attested/enroll.py +119 -0
  14. entropy_protocol/attested/evidence.py +106 -0
  15. entropy_protocol/attested/hcl.py +109 -0
  16. entropy_protocol/attested/nvidia.py +168 -0
  17. entropy_protocol/attested/ocsp.py +90 -0
  18. entropy_protocol/attested/pki.py +121 -0
  19. entropy_protocol/attested/rim.py +130 -0
  20. entropy_protocol/attested/service.py +242 -0
  21. entropy_protocol/attested/tpm.py +259 -0
  22. entropy_protocol/backend_hf.py +439 -0
  23. entropy_protocol/batch.py +537 -0
  24. entropy_protocol/calibrate.py +99 -0
  25. entropy_protocol/canon.py +321 -0
  26. entropy_protocol/canongen.py +325 -0
  27. entropy_protocol/cli.py +493 -0
  28. entropy_protocol/cose.py +260 -0
  29. entropy_protocol/crypto.py +140 -0
  30. entropy_protocol/delivery.py +31 -0
  31. entropy_protocol/detect.py +246 -0
  32. entropy_protocol/gateway.py +370 -0
  33. entropy_protocol/hpke.py +105 -0
  34. entropy_protocol/mcp.py +159 -0
  35. entropy_protocol/pack.py +217 -0
  36. entropy_protocol/plain.py +122 -0
  37. entropy_protocol/predicates.py +37 -0
  38. entropy_protocol/profiles.py +45 -0
  39. entropy_protocol/record.py +116 -0
  40. entropy_protocol/scrapi.py +203 -0
  41. entropy_protocol/seal.py +232 -0
  42. entropy_protocol/statements.py +148 -0
  43. entropy_protocol/stats.py +20 -0
  44. entropy_protocol/tlog.py +147 -0
  45. entropy_protocol/ts3161.py +205 -0
  46. entropy_protocol/typography.py +73 -0
  47. entropy_protocol/verify.py +232 -0
  48. entropy_protocol-0.1.0.dist-info/METADATA +255 -0
  49. entropy_protocol-0.1.0.dist-info/RECORD +54 -0
  50. entropy_protocol-0.1.0.dist-info/WHEEL +5 -0
  51. entropy_protocol-0.1.0.dist-info/entry_points.txt +2 -0
  52. entropy_protocol-0.1.0.dist-info/licenses/LICENSE +201 -0
  53. entropy_protocol-0.1.0.dist-info/licenses/NOTICE +4 -0
  54. entropy_protocol-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,537 @@
1
+ """Batched sealing, verification and detection (accelerators; the evaluation program at scale).
2
+
3
+ The algorithms are those of seal.seal, verify.verify and detect.detect; only the model work is batched.
4
+
5
+ Generation: one forward pass per step over 2B rows: the B generation contexts (prompt + text, left-padded) and,
6
+ with align="free", the B verification contexts (start token + text), so the weights are read once per step for
7
+ both views. Rows that end leave the batch (the cache is compacted). Sampling runs on the device.
8
+
9
+ Scoring: the verifier's pass (start token + canonical ids) over right-padded batches with no attention mask, as
10
+ the single pass; causal attention keeps a real position from seeing the padding. Per position only what a
11
+ verdict or a detection needs leaves the device: the logit and probability of the token present, its rank,
12
+ the k+1 largest logits and probabilities.
13
+
14
+ Batching changes the order of floating-point reductions, so the logits of a batched pass differ from the
15
+ single pass at the level of numerical noise. That is a configuration effect like a change of hardware: the
16
+ environment of a batched seal or verification reports its batch size, and calibration measures it.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import inspect
21
+ import os
22
+ import time
23
+ from dataclasses import dataclass
24
+
25
+ import torch
26
+
27
+ from . import crypto
28
+ from .backend_hf import PositionStat, first_choice_prob
29
+ from .detect import (Detection, checkpoints, decide_counts, detection_tokens, fold_readings, readings_of,
30
+ unsatisfiable)
31
+ from .record import HIGH, LOW
32
+ from .seal import SealParams, Sealed, check_params, decider, finish, margins, measure
33
+ from .verify import Result, judge, open_record
34
+
35
+
36
+ # ------------------------------------------------------------------------------------------------ sampling
37
+ def _generator(device: str, seed: int | None) -> torch.Generator:
38
+ seed = seed if seed is not None else int.from_bytes(os.urandom(8), "little")
39
+ try:
40
+ g = torch.Generator(device=device)
41
+ except RuntimeError:
42
+ g = torch.Generator(device="cpu")
43
+ g.manual_seed(seed)
44
+ return g
45
+
46
+
47
+ def _multinomial(p: torch.Tensor, g: torch.Generator) -> torch.Tensor:
48
+ """One draw per row of the (unnormalized, non-negative) weights p [n, m] -> [n].
49
+ The device TYPE decides where the draw happens: a generator made for "cuda" reports device cuda, its tensors
50
+ cuda:0, and torch accepts the pair (15.09.2026: comparing whole devices sent CUDA draws to the CPU branch with a
51
+ CUDA generator, and every sampled generation failed on the first GPU run)."""
52
+ if g.device.type != p.device.type:
53
+ return torch.multinomial(p.to(g.device), 1, generator=g).squeeze(1).to(p.device)
54
+ return torch.multinomial(p, 1, generator=g).squeeze(1)
55
+
56
+
57
+ def nucleus_batch(scores: torch.Tensor, temperature: float, top_p: float, g: torch.Generator) -> torch.Tensor:
58
+ """Top-p sampling per row of scores [n, V] (as HFBackend._nucleus); temperature 0 = greedy."""
59
+ if temperature <= 0:
60
+ return scores.argmax(-1)
61
+ p = torch.softmax(scores / temperature, -1)
62
+ sp, si = torch.sort(p, descending=True, dim=-1)
63
+ sp = sp * ((torch.cumsum(sp, -1) - sp) < top_p)
64
+ return si.gather(1, _multinomial(sp, g)[:, None]).squeeze(1)
65
+
66
+
67
+ def high_batch(ref: torch.Tensor, scores: torch.Tensor, k: int, window: int, high_margin: float,
68
+ temperature: float, stop_idx: torch.Tensor, g: torch.Generator, cg=None) -> torch.Tensor:
69
+ """Per row, a token outside the top-k of ``ref`` (at least ``high_margin`` below its k-th value where that
70
+ leaves a choice), drawn among the ``window`` most probable such tokens under ``scores``
71
+ (as HFBackend._high_choice; ``cg``: canonical generation, whose rows never choose a prefix of a top-k token)."""
72
+ topv, topi = torch.topk(ref, k, dim=-1)
73
+ allowed = torch.ones_like(ref, dtype=torch.bool)
74
+ allowed.scatter_(1, topi, False)
75
+ if stop_idx.numel():
76
+ allowed[:, stop_idx] = False
77
+ if cg is not None:
78
+ for r, first in enumerate(topi.tolist()):
79
+ ex = cg.high_exclusion(first)
80
+ if ex:
81
+ allowed[r, ex] = False
82
+ if high_margin > 0:
83
+ strict = allowed & ((topv[:, k - 1:k] - ref) >= high_margin)
84
+ allowed = torch.where(strict.any(-1, keepdim=True), strict, allowed)
85
+ masked = scores.masked_fill(~allowed, float("-inf"))
86
+ cv, ci = torch.topk(masked, window, dim=-1)
87
+ if temperature <= 0:
88
+ return ci[:, 0]
89
+ return ci.gather(1, _multinomial(torch.softmax(cv / temperature, -1), g)[:, None]).squeeze(1)
90
+
91
+
92
+ def _accepts(model, name: str) -> bool:
93
+ return name in inspect.signature(model.forward).parameters
94
+
95
+
96
+ # ---------------------------------------------------------------------------------------------- generation
97
+ @torch.no_grad()
98
+ def generate_batch(backend, prompts: list, decides: list, max_new_tokens: int, temperature: float, top_p: float,
99
+ k: int, high_window: int, seed: int | None = None, min_new_tokens: int = 0,
100
+ high_margin: float = 0.0, align: str = "prompt", free_after: int = 0,
101
+ compact_frac: float = 0.25, gate: float = 0.0, guard: float = 0.0,
102
+ canon_gen: bool = False) -> list[tuple[list[int], dict[int, int]]]:
103
+ """HFBackend.generate over a batch. ``prompts``: strings (tokenized as the single path does) or token id
104
+ lists (e.g. a chat template applied by the caller). ``decides[i](j, gen)`` as in HFBackend.generate."""
105
+ if align not in ("prompt", "free"):
106
+ raise ValueError(f"unknown enforcement context {align!r}")
107
+ if gate and align != "free":
108
+ raise ValueError("the confidence gate is read in the verification context: it needs align='free'")
109
+ dev = backend.device
110
+ B = len(prompts)
111
+ enc = [list(p) if not isinstance(p, str) else backend.tok(p)["input_ids"] for p in prompts]
112
+ free = align == "free"
113
+ seqs = enc + ([[backend.start_id]] * B if free else []) # generation rows, then verification rows
114
+ Lp = max(len(x) for x in seqs)
115
+ model = backend.model
116
+ extra = {"logits_to_keep": 1} if _accepts(model, "logits_to_keep") else {}
117
+ # the prompt pass row by row, without padding (as the single path): in a left-padded pass the padding positions
118
+ # attend to nothing, which in half precision can turn them into NaN (seen on MPS, sdpa and eager alike), and
119
+ # 0 x NaN carries it into the row's real positions. The rows' caches are then left-padded with zeros, which the
120
+ # attention mask leaves at weight exactly 0.
121
+ layers, lasts, legacy = None, [], True
122
+ for x in seqs:
123
+ o = model(input_ids=torch.tensor([x], device=dev), use_cache=True, **extra)
124
+ lasts.append(o.logits[0, -1])
125
+ legacy = not hasattr(o.past_key_values, "to_legacy_cache")
126
+ kv = o.past_key_values if legacy else o.past_key_values.to_legacy_cache()
127
+ if layers is None:
128
+ layers = [([], []) for _ in kv]
129
+ for (ks, vs), (k_, v_) in zip(layers, kv):
130
+ w = Lp - k_.shape[-2]
131
+ ks.append(torch.nn.functional.pad(k_, (0, 0, w, 0)))
132
+ vs.append(torch.nn.functional.pad(v_, (0, 0, w, 0)))
133
+ del o, kv
134
+ kv = tuple((torch.cat(ks, 0), torch.cat(vs, 0)) for ks, vs in layers)
135
+ if legacy:
136
+ past = kv
137
+ else:
138
+ from transformers import DynamicCache
139
+ past = DynamicCache.from_legacy_cache(kv)
140
+ del layers, kv
141
+ last = torch.stack(lasts)
142
+ if not bool(torch.isfinite(last).all()):
143
+ raise FloatingPointError(f"non-finite logits after the prompt pass ({backend.environment['class']}, "
144
+ f"attention {backend.environment['attn']}): precision overflow")
145
+ mask = torch.tensor([[0] * (Lp - len(x)) + [1] * len(x) for x in seqs], dtype=torch.long, device=dev)
146
+ next_pos = torch.tensor([len(x) for x in seqs], dtype=torch.long, device=dev)
147
+ can_compact = hasattr(past, "batch_select_indices")
148
+
149
+ g = _generator(str(dev), seed)
150
+ stops = backend.stop_ids
151
+ stop_idx = torch.tensor(sorted(stops), dtype=torch.long, device=dev)
152
+ gens: list[list[int]] = [[] for _ in range(B)]
153
+ views: list[list[int]] = [[] for _ in range(B)] # the verifier's view of each text (see HFBackend.generate)
154
+ enforced: list[dict[int, int]] = [{} for _ in range(B)]
155
+ cg = backend.canon_guard if canon_gen else None
156
+ cstates = [0] * B # canonical generation: unfinished character per document
157
+ spaced = [False] * B # canonical generation: the text ends in a space or tab
158
+ active = list(range(B)) # document index of each generation row in the batch
159
+ alive = [True] * B # per row: the text has not ended (ended rows wait for compaction)
160
+ for j in range(max_new_tokens):
161
+ nb = len(active)
162
+ props = [decides[d](j, views[d]) if alive[r] else None for r, d in enumerate(active)]
163
+ if gate and any(p is not None for p in props): # confidence gate, read in the verification context
164
+ p1 = first_choice_prob(last[nb:].float()).tolist()
165
+ props = [None if p is not None and p1[r] >= gate else p for r, p in enumerate(props)]
166
+ scores = last[:nb].float()
167
+ if j < min_new_tokens and stop_idx.numel():
168
+ scores[:, stop_idx] = float("-inf")
169
+ if guard and any(p is not None for p in props): # the generation context is confident: leave it alone
170
+ pg = first_choice_prob(scores).tolist()
171
+ props = [None if p is not None and pg[r] >= guard else p for r, p in enumerate(props)]
172
+ bm = None
173
+ if cg is not None: # canonical generation (as HFBackend.generate)
174
+ bm = cg.masks[torch.tensor([cstates[d] for d in active], device=cg.masks.device)]
175
+ if j == 0:
176
+ bm = bm | cg.lead_ban[None, :] # the verifier's first token; and never an empty text
177
+ if stop_idx.numel():
178
+ bm[:, stop_idx.to(bm.device)] = True
179
+ sp_rows = [r for r, d in enumerate(active) if spaced[d]]
180
+ if sp_rows:
181
+ bm[sp_rows] |= cg.nl_start
182
+ first = (last[nb:] if free else last[:nb]).argmax(-1).to(bm.device)
183
+ reach = bm.gather(1, first[:, None]).squeeze(1)
184
+ reach &= torch.tensor([cstates[d] == 0 for d in active], device=bm.device)
185
+ if bool(reach.any()):
186
+ bm[reach] |= cg.partial # reaching for a banned character: no half characters
187
+ scores = scores.masked_fill(bm.to(scores.device), float("-inf"))
188
+ top = scores.argmax(-1)
189
+ samp = nucleus_batch(scores, temperature, top_p, g)
190
+ in_free = free and j >= free_after
191
+ ref = last[nb:].float() if in_free else None
192
+ lowf = ref.argmax(-1) if in_free else None
193
+ high_rows = [r for r in range(nb) if props[r] == HIGH]
194
+ high: dict[int, int] = {}
195
+ if high_rows:
196
+ sel = torch.tensor(high_rows, device=dev)
197
+ if in_free:
198
+ h = high_batch(ref[sel], scores[sel], k, high_window, high_margin, temperature, stop_idx, g, cg=cg)
199
+ else:
200
+ h = high_batch(scores[sel], scores[sel], k, high_window, high_margin if align == "prompt" else 0.0,
201
+ temperature, stop_idx, g, cg=cg)
202
+ high = dict(zip(high_rows, h.tolist()))
203
+ top_l, samp_l = top.tolist(), samp.tolist()
204
+ lowf_l = lowf.tolist() if lowf is not None else None
205
+ low_banned = (bm.to(lowf.device).gather(1, lowf[:, None]).squeeze(1).tolist()
206
+ if bm is not None and lowf is not None else None)
207
+
208
+ def choose(r: int, rejected=()) -> tuple[int | None, int]:
209
+ """(predicate kept, token) for row r; a re-choice after ``rejected`` joins works on the row alone."""
210
+ prop = props[r]
211
+ if not rejected:
212
+ t = top_l[r]
213
+ if prop is not None and t in stops:
214
+ return None, t # the model's first choice is to end: the text ends
215
+ if prop is None:
216
+ return None, samp_l[r]
217
+ if not in_free:
218
+ return prop, (t if prop == LOW else high[r])
219
+ if prop == LOW:
220
+ f = lowf_l[r]
221
+ if f in stops or (low_banned is not None and low_banned[r]): # cannot be satisfied
222
+ return None, samp_l[r]
223
+ return prop, f
224
+ return prop, high[r]
225
+ row = scores[r:r + 1]
226
+ t = int(row.argmax())
227
+ if prop is not None and t in stops:
228
+ return None, t
229
+ if prop is None:
230
+ return None, int(nucleus_batch(row, temperature, top_p, g)[0])
231
+ if not in_free:
232
+ return prop, (t if prop == LOW else int(high_batch(
233
+ row, row, k, high_window, high_margin if align == "prompt" else 0.0, temperature, stop_idx, g,
234
+ cg=cg)[0]))
235
+ if prop == LOW:
236
+ f = lowf_l[r]
237
+ if f in stops or (low_banned is not None and low_banned[r]) or f in rejected:
238
+ return None, int(nucleus_batch(row, temperature, top_p, g)[0])
239
+ return prop, f
240
+ return prop, int(high_batch(ref[r:r + 1], row, k, high_window, high_margin, temperature, stop_idx, g,
241
+ cg=cg)[0])
242
+
243
+ choice = {r: choose(r) for r in range(nb) if alive[r]}
244
+ first_try = dict(choice) # the model's own choices, kept where nothing joins
245
+ if cg is not None and j > 0: # joins the verifier would re-tokenize: banned, chosen again
246
+ rejected: dict[int, list[int]] = {}
247
+ todo = [r for r, (_, t) in choice.items() if t not in stops]
248
+ for attempt in range(backend.JOIN_TRIES):
249
+ bad = [r for r in todo if not cg.joinable(views[active[r]], choice[r][1])]
250
+ if not bad:
251
+ break
252
+ for r in bad:
253
+ rejected.setdefault(r, []).append(choice[r][1])
254
+ scores[r, choice[r][1]] = float("-inf")
255
+ props[r] = choice[r][0]
256
+ if attempt < backend.JOIN_TRIES - 1:
257
+ choice[r] = choose(r, rejected[r])
258
+ continue
259
+ prop_r, avoid = props[r], set() # every choice rejected: the best joinable one
260
+ if prop_r == HIGH:
261
+ top_ref = torch.topk(ref[r] if in_free else scores[r], k).indices.tolist()
262
+ avoid = set(top_ref) | set(cg.high_exclusion(top_ref))
263
+ elif prop_r == LOW:
264
+ prop_r = None
265
+ pick = cg.first_joinable(views[active[r]], scores[r].float().cpu(), avoid, stops)
266
+ choice[r] = (prop_r, pick) if pick is not None else first_try[r]
267
+ todo = [r for r in bad if choice[r][1] not in stops]
268
+ step: list[int] = []
269
+ fstep: list[int] = [] # the verifier's view of this step
270
+ keep: list[int] = []
271
+ for r, d in enumerate(active):
272
+ if not alive[r]:
273
+ step.append(backend.pad_id)
274
+ fstep.append(backend.pad_id)
275
+ continue
276
+ prop, nxt = choice[r]
277
+ if nxt in stops:
278
+ alive[r] = False
279
+ step.append(backend.pad_id)
280
+ fstep.append(backend.pad_id)
281
+ continue
282
+ gens[d].append(nxt)
283
+ views[d].append(int(cg.lead[nxt]) if cg is not None and j == 0 else nxt)
284
+ fstep.append(views[d][-1])
285
+ if cg is not None:
286
+ cstates[d], spaced[d] = cg.state_after(cstates[d], nxt), cg.ends_in_space(nxt)
287
+ if prop is not None:
288
+ enforced[d][len(gens[d]) - 1] = prop
289
+ step.append(nxt)
290
+ keep.append(r)
291
+ if not keep or j == max_new_tokens - 1:
292
+ break
293
+ tokens = torch.tensor(step, device=dev)
294
+ ftokens = torch.tensor(fstep, device=dev)
295
+ if can_compact and nb - len(keep) >= max(1, int(compact_frac * nb)):
296
+ sel = keep + [nb + r for r in keep] if free else keep
297
+ sel_t = torch.tensor(sel, device=dev)
298
+ past.batch_select_indices(sel_t)
299
+ mask, next_pos = mask[sel_t], next_pos[sel_t]
300
+ keep_t = torch.tensor(keep, device=dev)
301
+ tokens, ftokens = tokens[keep_t], ftokens[keep_t]
302
+ active = [active[r] for r in keep]
303
+ alive = [True] * len(active)
304
+ step_ids = torch.cat([tokens, ftokens]) if free else tokens
305
+ mask = torch.cat([mask, torch.ones((mask.shape[0], 1), dtype=mask.dtype, device=dev)], 1)
306
+ out = model(input_ids=step_ids[:, None], attention_mask=mask, position_ids=next_pos[:, None],
307
+ past_key_values=past, use_cache=True)
308
+ past, last = out.past_key_values, out.logits[:, -1, :]
309
+ del out
310
+ next_pos = next_pos + 1
311
+ return list(zip(gens, enforced))
312
+
313
+
314
+ # ------------------------------------------------------------------------------------------------- scoring
315
+ @dataclass
316
+ class Scores:
317
+ """The verifier's pass over one text (start token + ids), per position t (row t scores ids[t])."""
318
+ l_tok: torch.Tensor # [T] logit of the token present
319
+ rank0: torch.Tensor # [T] number of tokens with a strictly larger logit
320
+ top: torch.Tensor # [T, k+1] largest logits, descending
321
+ p_tok: torch.Tensor # [T] probability of the token present
322
+ top_p: torch.Tensor # [T, k+1] largest probabilities, descending
323
+ first: torch.Tensor | None = None # [T] the first choice (token id)
324
+
325
+
326
+ @torch.no_grad()
327
+ def score_batch(backend, id_lists: list[list[int]], k: int, token_budget: int = 16384) -> list[Scores]:
328
+ """The verification pass for many texts, batched by length under a token budget."""
329
+ for ids in id_lists:
330
+ if len(ids) + 1 > backend.max_positions:
331
+ raise ValueError(f"text of {len(ids)} tokens exceeds the model context of {backend.max_positions}")
332
+ dev = backend.device
333
+ out: list[Scores | None] = [None] * len(id_lists)
334
+ order = sorted(range(len(id_lists)), key=lambda i: -len(id_lists[i]))
335
+ i = 0
336
+ while i < len(order):
337
+ L = len(id_lists[order[i]]) + 1
338
+ n = max(1, min(len(order) - i, token_budget // max(1, L)))
339
+ group = order[i:i + n]
340
+ i += n
341
+ inp = torch.full((len(group), L), backend.pad_id, dtype=torch.long)
342
+ for r, d in enumerate(group):
343
+ seq = [backend.start_id] + id_lists[d]
344
+ inp[r, :len(seq)] = torch.tensor(seq)
345
+ split = getattr(backend, "split", None) # head over the hidden state, chunk by chunk (backend_hf)
346
+ if split is not None:
347
+ hidden, logits, step = split[0](input_ids=inp.to(dev), use_cache=False).last_hidden_state, None, backend.HEAD_ROWS
348
+ else:
349
+ hidden, logits, step = None, backend.model(input_ids=inp.to(dev), use_cache=False).logits, 2048
350
+ bad = 0
351
+ for r, d in enumerate(group):
352
+ T = len(id_lists[d])
353
+ parts: list[tuple] = []
354
+ tgt_all = torch.tensor(id_lists[d], device=dev)[:, None]
355
+ for a in range(0, T, step): # bounded memory: one chunk of vocabulary-wide rows at a time
356
+ rows = (split[1](hidden[r, a:min(T, a + step)]) if split is not None
357
+ else logits[r, a:min(T, a + step)]).float()
358
+ # probabilities as the single pass computes them (logsumexp, no full softmax); a non-finite logit
359
+ # (+inf or NaN in the logsumexp, -inf or NaN in the minimum) is a precision overflow
360
+ lse = torch.logsumexp(rows, -1, keepdim=True)
361
+ if not bool((torch.isfinite(lse) & torch.isfinite(rows.amin(-1, keepdim=True))).all()):
362
+ bad += 1
363
+ break
364
+ tgt = tgt_all[a:a + rows.shape[0]]
365
+ l_tok = rows.gather(1, tgt)
366
+ top_l = torch.topk(rows, k + 1, dim=-1).values
367
+ parts.append((l_tok.squeeze(1).cpu(), (rows > l_tok).sum(1).cpu(), top_l.cpu(),
368
+ torch.exp(l_tok - lse).squeeze(1).cpu(), torch.exp(top_l - lse).cpu(),
369
+ rows.argmax(-1).cpu()))
370
+ del rows, lse
371
+ if bad:
372
+ raise FloatingPointError(f"non-finite logits in the verification pass ({backend.environment['class']}): "
373
+ f"precision overflow")
374
+ if not parts:
375
+ z = torch.zeros(0)
376
+ out[d] = Scores(z, z.long(), torch.zeros(0, k + 1), z, torch.zeros(0, k + 1), z.long())
377
+ continue
378
+ out[d] = Scores(*(torch.cat([p[i] for p in parts]) for i in range(6)))
379
+ del logits, hidden
380
+ tidy = getattr(backend, "tidy", None) # the group's vocabulary-wide rows back to the system (MPS)
381
+ if tidy is not None:
382
+ tidy()
383
+ return out
384
+
385
+
386
+ def stats_at(offs, char_offsets: list[int], sc: Scores) -> list[PositionStat | None]:
387
+ """HFBackend.position_stats from a batched pass: for each canonical char offset, the token covering it."""
388
+ cover: dict[int, int] = {}
389
+ for t, (a, b) in enumerate(offs):
390
+ for c in range(a, b):
391
+ cover.setdefault(c, t)
392
+ res: list[PositionStat | None] = []
393
+ for c in char_offsets:
394
+ t = cover.get(c)
395
+ if t is None:
396
+ res.append(None)
397
+ continue
398
+ res.append(PositionStat(t, (int(offs[t][0]), int(offs[t][1])), float(sc.p_tok[t]), int(sc.rank0[t]),
399
+ [float(x) for x in sc.top_p[t]], float(sc.l_tok[t]),
400
+ tuple(float(x) for x in sc.top[t])))
401
+ return res
402
+
403
+
404
+ def _batch_env(backend, n: int) -> dict:
405
+ return {**dict(getattr(backend, "environment", {})), "batch": n}
406
+
407
+
408
+ # ------------------------------------------------------------------------------------------ seal / verify
409
+ def seal_batch(backend, prompts: list, master, params: SealParams = SealParams(),
410
+ doc_ids: list[str] | None = None, seed: int | None = None, token_budget: int = 16384,
411
+ meter=None) -> list[Sealed]:
412
+ """seal.seal for many prompts at once (one generation batch, one batched verification pass).
413
+ ``master``: one master key, or one per prompt (documents of different issuers in one batch).
414
+ ``meter``: a second backend of the same model that makes the record's measurement pass (e.g. generate in
415
+ bf16, measure in fp16); the record then reports the meter's environment. Default: ``backend``."""
416
+ t0 = time.time()
417
+ check_params(params)
418
+ meter = meter or backend
419
+ if (meter.weights_digest, meter.tokenizer_digest) != (backend.weights_digest, backend.tokenizer_digest):
420
+ raise ValueError("the measuring backend must run the generating model")
421
+ doc_ids = doc_ids or [crypto.new_doc_id() for _ in prompts]
422
+ masters = list(master) if isinstance(master, (list, tuple)) else [master] * len(prompts)
423
+ _, _, high_margin = margins(params)
424
+ outs = generate_batch(backend, prompts, [decider(params, m, d) for m, d in zip(masters, doc_ids)],
425
+ params.max_new_tokens,
426
+ params.temperature, params.top_p, params.k, params.high_window, seed,
427
+ params.min_new_tokens, high_margin, params.align, params.free_after, gate=params.gate,
428
+ guard=params.guard, canon_gen=params.canon_gen)
429
+ ms = [measure(backend, ids, enf) for ids, enf in outs]
430
+ encs = [meter.tok(m.ctext, return_offsets_mapping=True, add_special_tokens=False) for m in ms]
431
+ scores = score_batch(meter, [e["input_ids"] for e in encs], params.k, token_budget)
432
+ env = _batch_env(meter, len(prompts))
433
+ per = (time.time() - t0) / max(1, len(prompts))
434
+ sealed = [finish(meter, params, m, stats_at(e["offset_mapping"], m.anchors, sc), mk, d, env=env)
435
+ for m, e, sc, mk, d in zip(ms, encs, scores, masters, doc_ids)]
436
+ return [Sealed(**{**s.__dict__, "seconds": round(per, 3)}) for s in sealed]
437
+
438
+
439
+ def verify_batch(backend, candidates: list[str], tokens: list[str], keys: list[bytes],
440
+ token_budget: int = 16384) -> list[Result]:
441
+ """verify.verify for many (candidate, token, key) triples; one batched verification pass."""
442
+ t0 = time.time()
443
+ env = _batch_env(backend, len(candidates))
444
+ opened = [open_record(backend, c, t, k, env=env, t0=t0) for c, t, k in zip(candidates, tokens, keys)]
445
+ todo = [i for i, o in enumerate(opened) if not isinstance(o, Result) and o.offsets]
446
+ encs = {i: backend.tok(opened[i].ctext, return_offsets_mapping=True, add_special_tokens=False) for i in todo}
447
+ ks = {opened[i].rec.header.k for i in todo}
448
+ scores: dict[int, Scores] = {}
449
+ for kk in ks: # records of one batch normally share k
450
+ grp = [i for i in todo if opened[i].rec.header.k == kk]
451
+ for i, sc in zip(grp, score_batch(backend, [encs[i]["input_ids"] for i in grp], kk, token_budget)):
452
+ scores[i] = sc
453
+ res: list[Result] = []
454
+ for i, o in enumerate(opened):
455
+ if isinstance(o, Result):
456
+ res.append(o)
457
+ elif not o.offsets:
458
+ res.append(judge(o, [], t0))
459
+ else:
460
+ res.append(judge(o, stats_at(encs[i]["offset_mapping"], o.offsets, scores[i]), t0))
461
+ per = round((time.time() - t0) / max(1, len(res)), 3)
462
+ for r in res:
463
+ r.seconds = per # amortized over the batch
464
+ return res
465
+
466
+
467
+ def detect_batch(backend, candidates: list[str], k_wm: bytes, *, interval: int = 5, k: int = 1, context: int = 4,
468
+ tol: float = 0.0, alpha: float = 1e-6, localize: bool = False, min_run: int = 8,
469
+ token_budget: int = 16384, gate: float = 0.0, canon: str | None = None,
470
+ restarts: int = 32) -> list[Detection]:
471
+ """detect.detect for many candidates under one detection key; one batched pass (with ``localize``, one more
472
+ over the paragraph-start readings of all candidates, as detect.detect reads them)."""
473
+ from .canon import CANON_ID
474
+ t0 = time.time()
475
+ toks = [detection_tokens(backend, c, canon or CANON_ID) for c in candidates]
476
+ todo = [i for i, (_, _, n) in enumerate(toks) if n > context]
477
+ scores = dict(zip(todo, score_batch(backend, [toks[i][0] for i in todo], k, token_budget)))
478
+ kw = dict(interval=interval, k=k, context=context, tol=tol, alpha=alpha, min_run=min_run, gate=gate)
479
+ dets = detect_from_scores(toks, scores, k_wm, localize=localize, t0=t0, backend=backend, **kw)
480
+ if localize and restarts:
481
+ readings = [readings_of(backend, c, canon or CANON_ID, restarts) if toks[i][2] > context else []
482
+ for i, c in enumerate(candidates)]
483
+ fold_all(dets, readings, reading_scores(backend, readings, k, token_budget), k_wm, backend=backend, **kw)
484
+ for d in dets:
485
+ d.seconds = round((time.time() - t0) / max(1, len(dets)), 3)
486
+ return dets
487
+
488
+
489
+ def reading_scores(backend, readings: list, k: int, token_budget: int = 16384) -> list[list]:
490
+ """The verifier's pass over every paragraph-start reading (see detect.readings_of), batched; per candidate,
491
+ per reading: Scores, or None for a reading too short to hold a checkpoint."""
492
+ flat = [(i, j) for i, rs in enumerate(readings) for j, (_, ids, _, _) in enumerate(rs) if len(ids) > 4]
493
+ got = dict(zip(flat, score_batch(backend, [readings[i][j][1] for i, j in flat], k, token_budget)))
494
+ return [[got.get((i, j)) for j in range(len(rs))] for i, rs in enumerate(readings)]
495
+
496
+
497
+ def fold_all(dets: list, readings: list, scores: list, k_wm: bytes, *, interval: int, k: int, context: int,
498
+ tol: float, alpha: float, min_run: int, gate: float = 0.0, backend=None) -> list:
499
+ """Fold each candidate's paragraph-start readings into its localized detection under the key ``k_wm``
500
+ (the readings' pass is key-independent: made once, folded under many keys)."""
501
+ for d, rs, scs in zip(dets, readings, scores):
502
+ views = []
503
+ for (shift, ids, offs, n), sc in zip(rs, scs):
504
+ if sc is None:
505
+ continue
506
+ dv = detect_from_scores([(ids, offs, n)], {0: sc}, k_wm, interval=interval, k=k, context=context,
507
+ tol=tol, alpha=alpha, localize=True, min_run=min_run, t0=time.time(), gate=gate,
508
+ backend=backend)[0]
509
+ views.append((shift, dv))
510
+ fold_readings(d, views, alpha)
511
+ return dets
512
+
513
+
514
+ def detect_from_scores(toks, scores: dict, k_wm: bytes, *, interval: int, k: int, context: int, tol: float,
515
+ alpha: float, localize: bool, min_run: int, t0: float, gate: float = 0.0,
516
+ backend=None) -> list[Detection]:
517
+ """Detection decisions from a pass already made (the same pass can be scored under many keys: the
518
+ empirical null over many keys costs one model pass per text). ``backend``: skip the positions where a
519
+ canonically generating sealer could not have emitted the first choice (detect.unsatisfiable)."""
520
+ out: list[Detection] = []
521
+ for i, (ids, offs, n_tok) in enumerate(toks):
522
+ if i not in scores:
523
+ out.append(Detection(False, 1.0, 0, 0, 0, n_tok, alpha, k, interval, context, 0.0, gate=gate))
524
+ continue
525
+ sc = scores[i]
526
+ cps = checkpoints(ids, k_wm, interval, context)
527
+ at = [t for t, _ in cps]
528
+ unsat = (unsatisfiable(backend, ids, at, sc.first[at].tolist())
529
+ if backend is not None and sc.first is not None else None)
530
+ out.append(decide_counts(cps, offs, n_tok, sc.rank0[at].tolist(), sc.l_tok[at].tolist(),
531
+ sc.top[at].tolist(), interval=interval, k=k, context=context, tol=tol,
532
+ alpha=alpha, localize=localize, min_run=min_run, t0=t0,
533
+ p1s=sc.top_p[at, 0].tolist() if gate else None, gate=gate, unsat=unsat))
534
+ per = round((time.time() - t0) / max(1, len(out)), 3)
535
+ for d in out:
536
+ d.seconds = per # amortized over the batch
537
+ return out
@@ -0,0 +1,99 @@
1
+ """Calibration of the verification tolerance (ARCHITECTURE §6a) — measured, not chosen.
2
+
3
+ Every configuration re-reads each calibration text (BOS + text, one pass). At every position and for both
4
+ predicates the signed margin (value of the token present minus the boundary value) is compared with the
5
+ reference configuration:
6
+ delta(config) = max over positions and predicates of |margin_config - margin_reference|
7
+ The positions are those that can hold a checkpoint (index >= from_position; seal.first_checkpoint): the first
8
+ tokens after BOS never carry a record entry or a detector count, and their noise is not the text's (15.09.2026,
9
+ Qwen2.5-7B on an L40S, fp16 batch 32 against batch 1: 1.99 logits at position 3, at most 0.141 from position 4 on;
10
+ the table was 14 times too wide and records kept 1.6% of positions).
11
+ A configuration class (numeric precision of the scoring pass) takes the largest delta of its members, and its
12
+ tolerance is c * delta. The table goes into the record header; the seal keeps a checkpoint only if its margin
13
+ is at least seal_margin_factor times the largest tolerance of the table.
14
+
15
+ Space "logit": values are logits, so a margin is a log-probability ratio (log p_tok - log p_boundary); numerical
16
+ noise is then of the same size for the most probable token and for tail tokens, and one tolerance fits both
17
+ predicates. Space "prob": values are probabilities (kept for the records that name it).
18
+ """
19
+ from __future__ import annotations
20
+
21
+ from dataclasses import dataclass, field
22
+
23
+ import torch
24
+
25
+
26
+ @torch.no_grad()
27
+ def margin_matrix(backend, ids: list[int], k: int, space: str) -> torch.Tensor:
28
+ """Signed margins [T, 2] (column 0: LOW, column 1: HIGH) at every position of BOS + ids."""
29
+ inp = torch.tensor([[backend.start_id] + ids], device=backend.device)
30
+ logits = backend.model(inp).logits[0, :-1].float().cpu()
31
+ vals = logits if space == "logit" else torch.softmax(logits, -1)
32
+ tgt = torch.tensor(ids)[:, None]
33
+ rank0 = (logits > logits.gather(1, tgt)).sum(1)
34
+ v_tok = vals.gather(1, tgt).squeeze(1)
35
+ top = torch.topk(vals, k + 1, dim=-1).values
36
+ low_b = torch.where(rank0 == 0, top[:, 1], top[:, 0])
37
+ high_b = torch.where(rank0 < k, top[:, k], top[:, k - 1])
38
+ return torch.stack([v_tok - low_b, v_tok - high_b], 1)
39
+
40
+
41
+ @dataclass
42
+ class Calibration:
43
+ space: str
44
+ c: float
45
+ k: int
46
+ reference: str
47
+ positions: int
48
+ delta: dict = field(default_factory=dict) # "device:dtype" -> max |delta margin|
49
+ errors: dict = field(default_factory=dict) # "device:dtype" -> reason (e.g. non-finite logits)
50
+ from_position: int = 0 # positions before this index are not measured
51
+
52
+ def table(self, classes: list[str] | None = None) -> dict:
53
+ """Configuration class -> tolerance, for the classes requested (default: every measured class)."""
54
+ by_class: dict[str, float] = {}
55
+ for cfg, d in self.delta.items():
56
+ cls = _class_of(cfg.split(":")[1])
57
+ by_class[cls] = max(by_class.get(cls, 0.0), d)
58
+ ref_cls = _class_of(self.reference.split(":")[1])
59
+ by_class.setdefault(ref_cls, 0.0)
60
+ wanted = classes or sorted(by_class)
61
+ missing = [c for c in wanted if c not in by_class]
62
+ if missing:
63
+ raise ValueError(f"no measurement for configuration classes {missing}")
64
+ return {cls: round(self.c * by_class[cls], 6) for cls in wanted}
65
+
66
+
67
+ def _class_of(dtype_name: str) -> str:
68
+ return {"float32": "fp32", "float16": "fp16", "bfloat16": "bf16"}.get(dtype_name, dtype_name)
69
+
70
+
71
+ def calibrate(reference, configs: dict, corpus: list[list[int]], k: int = 10, space: str = "logit",
72
+ c: float = 3.0, from_position: int = 0) -> Calibration:
73
+ """``reference`` is a backend; ``configs`` maps "device:dtype" to a backend of the same model or to a
74
+ zero-argument loader (configurations are then loaded and released one at a time). ``from_position``: the
75
+ first checkpoint position of the parameters the table will serve (seal.first_checkpoint); 0 measures all."""
76
+ ref_name = f"{reference.device}:{str(reference.dtype).replace('torch.', '')}"
77
+ corpus = [ids for ids in corpus if ids] # a text may end at its first token: nothing to compare
78
+ ref_m = [margin_matrix(reference, ids, k, space) for ids in corpus]
79
+ cal = Calibration(space=space, c=c, k=k, reference=ref_name, from_position=from_position,
80
+ positions=sum(max(0, len(ids) - from_position) for ids in corpus))
81
+ for name, b in configs.items():
82
+ try:
83
+ backend = b() if callable(b) else b
84
+ except Exception as exc: # noqa: BLE001 - an unavailable device is reported, not fatal
85
+ cal.errors[name] = f"unavailable: {str(exc)[:160]}"
86
+ continue
87
+ d = 0.0
88
+ for ids, rm in zip(corpus, ref_m):
89
+ m = margin_matrix(backend, ids, k, space)
90
+ if not torch.isfinite(m).all():
91
+ cal.errors[name] = "non-finite values in the scoring pass"
92
+ break
93
+ diff = (m - rm)[from_position:]
94
+ if diff.numel():
95
+ d = max(d, float(diff.abs().max()))
96
+ else:
97
+ cal.delta[name] = d
98
+ del backend
99
+ return cal