fuzzybits-server 0.17.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 (34) hide show
  1. fuzzybits_server/.dockerignore +64 -0
  2. fuzzybits_server/__init__.py +15 -0
  3. fuzzybits_server/app.py +93 -0
  4. fuzzybits_server/config.py +310 -0
  5. fuzzybits_server/convergence/__init__.py +100 -0
  6. fuzzybits_server/convergence/gbas.py +229 -0
  7. fuzzybits_server/convergence/metrics.py +164 -0
  8. fuzzybits_server/convergence/policies.py +387 -0
  9. fuzzybits_server/convergence/runner.py +398 -0
  10. fuzzybits_server/convergence/sampling.py +409 -0
  11. fuzzybits_server/convergence/special.py +280 -0
  12. fuzzybits_server/convergence/tally.py +179 -0
  13. fuzzybits_server/event_hub.py +58 -0
  14. fuzzybits_server/event_log.py +16 -0
  15. fuzzybits_server/fault_tree_payload.py +899 -0
  16. fuzzybits_server/model_oracle_p.json +44 -0
  17. fuzzybits_server/native.py +536 -0
  18. fuzzybits_server/routes.py +408 -0
  19. fuzzybits_server/state.py +67 -0
  20. fuzzybits_server/supervisor.py +193 -0
  21. fuzzybits_server/ui.py +84 -0
  22. fuzzybits_server/webui/.vite/manifest.json +26 -0
  23. fuzzybits_server/webui/assets/Playground-B6V8NzhX.css +1 -0
  24. fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js +5481 -0
  25. fuzzybits_server/webui/assets/Playground-CSpFbzwZ.js.map +1 -0
  26. fuzzybits_server/webui/assets/index-BnegRRhI.css +1 -0
  27. fuzzybits_server/webui/assets/index-C3oGCBE0.js +13 -0
  28. fuzzybits_server/webui/assets/index-C3oGCBE0.js.map +1 -0
  29. fuzzybits_server/webui/index.html +24 -0
  30. fuzzybits_server/worker.py +64 -0
  31. fuzzybits_server-0.17.0.dist-info/METADATA +281 -0
  32. fuzzybits_server-0.17.0.dist-info/RECORD +34 -0
  33. fuzzybits_server-0.17.0.dist-info/WHEEL +4 -0
  34. fuzzybits_server-0.17.0.dist-info/entry_points.txt +2 -0
@@ -0,0 +1,387 @@
1
+ """Convergence policies: decide *when* a run has reached the requested precision.
2
+
3
+ A :class:`ConvergencePolicy` maps an immutable ``(NodeState, RunContext)`` to a
4
+ :class:`PolicyVerdict` carrying a ``converged`` flag plus the precision
5
+ statistics characteristic of that policy (current half-width ``epsilon``, target
6
+ ``target_epsilon``, projected sample size, and a flat ``metrics`` dict for
7
+ emission).
8
+
9
+ Two policies are provided, mirroring the native ``ConvergencePolicy``
10
+ specializations:
11
+
12
+ * :class:`WaldLinearPolicy` — classical normal-approximation interval on the
13
+ linear probability scale. ``epsilon = z * SE``, target ``= delta * p_hat``.
14
+ This is the engine's default *primary* policy: it fills the canonical progress
15
+ fields the web client already consumes. (Linear only, per requirements; the
16
+ log10 band is still computed and emitted for context but does not gate the
17
+ stop.)
18
+ * :class:`BayesPolicy` — Jeffreys ``Beta(1/2, 1/2)`` posterior credible interval.
19
+ ``epsilon`` is the half-width of the central credible interval at the same
20
+ confidence; target ``= delta * posterior_mean``.
21
+ * :class:`GBASPolicy` — Huber's Gamma Bernoulli Approximation Scheme (2017).
22
+ Instead of gating on a moving ``delta * p_hat`` interval width, it fixes a
23
+ target success count ``k`` up front (from the *same* ``delta``/``confidence``
24
+ spec) such that the estimate ``p_hat = (k-1)/R`` has an *exactly known*,
25
+ ``p``-independent relative error ``p/p_hat ~ Gamma(k, k-1)``; it converges the
26
+ instant ``num_one_bits >= k`` and reports an exact confidence interval. Here
27
+ ``epsilon`` is the current relative standard deviation ``1/sqrt(successes-2)``
28
+ and target ``= 1/sqrt(k-2)``, so ``epsilon <= target`` iff ``successes >= k``.
29
+
30
+ The runner can attach any number of policies; one is designated the *stopping*
31
+ policy. All are evaluated every pass and emitted under their namespace, so e.g.
32
+ Wald, Bayes, and GBAS statistics stream simultaneously.
33
+
34
+ Most policies are stateless; :class:`GBASPolicy` keeps a little state (the solved
35
+ ``k``, an RNG, and the estimate materialized at the first crossing) because the
36
+ GBAS estimate is a randomized quantity defined *at the stopping time*.
37
+ """
38
+
39
+ from __future__ import annotations
40
+
41
+ import math
42
+ from dataclasses import dataclass, field
43
+ from typing import Any, Protocol, runtime_checkable
44
+
45
+ from . import special
46
+ from .special import DELTA_EPSILON
47
+ from .tally import NodeState, RunContext
48
+
49
+ _Z95 = 1.959963984540054
50
+ _Z99 = 2.5758293035489004
51
+
52
+ # Fixed two-sided significance levels for the 95% / 99% GBAS bands streamed
53
+ # alongside the client-requested level (parity with the p05-p95 / p01-p99 display).
54
+ _ALPHA95 = 0.05
55
+ _ALPHA99 = 0.01
56
+
57
+
58
+ @dataclass(frozen=True, slots=True)
59
+ class PolicyVerdict:
60
+ """Outcome of evaluating one convergence policy for one node."""
61
+
62
+ name: str
63
+ converged: bool
64
+ epsilon: float
65
+ target_epsilon: float
66
+ projected_trials: int
67
+ metrics: dict[str, Any] = field(default_factory=dict)
68
+
69
+
70
+ @runtime_checkable
71
+ class ConvergencePolicy(Protocol):
72
+ """Decides convergence and reports precision statistics for one node."""
73
+
74
+ name: str
75
+
76
+ def evaluate(self, node: NodeState, ctx: RunContext) -> PolicyVerdict:
77
+ ...
78
+
79
+
80
+ class WaldLinearPolicy:
81
+ """Wald (normal-approximation) convergence on the linear probability scale."""
82
+
83
+ name = "wald"
84
+
85
+ def evaluate(self, node: NodeState, ctx: RunContext) -> PolicyVerdict:
86
+ z = ctx.z
87
+ n = node.total_bits
88
+ p_hat = node.mean
89
+ p_guard = max(p_hat, DELTA_EPSILON)
90
+ std_err = node.std_err
91
+
92
+ epsilon = z * std_err
93
+ target_epsilon = ctx.delta * p_guard
94
+ converged = epsilon > 0.0 and epsilon <= target_epsilon
95
+
96
+ # log10-scale band (emitted for context; does not gate the stop).
97
+ epsilon_log10 = (z * std_err) / (p_guard * special.LN10) if n else 0.0
98
+ target_epsilon_log10 = ctx.delta
99
+ log10_converged = epsilon_log10 > 0.0 and epsilon_log10 <= target_epsilon_log10
100
+
101
+ projected_trials = special.required_trials_two_sided(p_hat, target_epsilon, z)
102
+ projected_trials_log10 = special.required_trials_log10_two_sided(
103
+ p_guard, target_epsilon_log10, z
104
+ )
105
+
106
+ hw95 = _Z95 * std_err
107
+ hw99 = _Z99 * std_err
108
+ metrics: dict[str, Any] = {
109
+ "std_err": std_err,
110
+ "epsilon": epsilon,
111
+ "target_epsilon": target_epsilon,
112
+ "epsilon_converged": converged,
113
+ "epsilon_log10": epsilon_log10,
114
+ "target_epsilon_log10": target_epsilon_log10,
115
+ "epsilon_log10_converged": log10_converged,
116
+ "projected_trials": projected_trials,
117
+ "projected_trials_log10": projected_trials_log10,
118
+ "p01": special.clamp(p_hat - hw99, 0.0, 1.0),
119
+ "p05": special.clamp(p_hat - hw95, 0.0, 1.0),
120
+ "p95": special.clamp(p_hat + hw95, 0.0, 1.0),
121
+ "p99": special.clamp(p_hat + hw99, 0.0, 1.0),
122
+ }
123
+ return PolicyVerdict(
124
+ name=self.name,
125
+ converged=converged,
126
+ epsilon=epsilon,
127
+ target_epsilon=target_epsilon,
128
+ projected_trials=max(projected_trials, projected_trials_log10),
129
+ metrics=metrics,
130
+ )
131
+
132
+
133
+ class BayesPolicy:
134
+ """Jeffreys ``Beta(1/2, 1/2)`` posterior credible-interval convergence."""
135
+
136
+ name = "bayes"
137
+
138
+ def __init__(self, *, alpha0: float = 0.5, beta0: float = 0.5) -> None:
139
+ self._alpha0 = alpha0
140
+ self._beta0 = beta0
141
+ self._prior_mass = alpha0 + beta0 + 1.0 # effective prior sample size
142
+
143
+ def evaluate(self, node: NodeState, ctx: RunContext) -> PolicyVerdict:
144
+ z = ctx.z
145
+ successes = node.num_one_bits
146
+ failures = node.total_bits - node.num_one_bits
147
+ alpha = self._alpha0 + successes
148
+ beta = self._beta0 + failures
149
+ total = alpha + beta
150
+
151
+ posterior_mean = alpha / total
152
+ posterior_var = (alpha * beta) / (total * total * (total + 1.0))
153
+ posterior_sd = posterior_var**0.5
154
+
155
+ # Central credible interval at the same two-sided confidence encoded by z.
156
+ cred_level = special.clamp(2.0 * special.normal_cdf(z) - 1.0, 0.0, 1.0)
157
+ tail = (1.0 - cred_level) / 2.0
158
+ lower = special.beta_quantile(tail, alpha, beta)
159
+ upper = special.beta_quantile(1.0 - tail, alpha, beta)
160
+ epsilon = 0.5 * (upper - lower)
161
+
162
+ p_guard = max(posterior_mean, DELTA_EPSILON)
163
+ target_epsilon = ctx.delta * p_guard
164
+ converged = epsilon > 0.0 and epsilon <= target_epsilon
165
+
166
+ # Required N from the Wald-style inversion used by the native bayes update,
167
+ # corrected for the effective prior sample size and floored at current N.
168
+ var_term = posterior_mean * (1.0 - posterior_mean)
169
+ if target_epsilon > 0.0:
170
+ rhs = (z * z * var_term) / (target_epsilon * target_epsilon)
171
+ projected = math.ceil(max(0.0, rhs - self._prior_mass))
172
+ else:
173
+ projected = 0
174
+ projected = max(projected, node.total_bits)
175
+
176
+ metrics: dict[str, Any] = {
177
+ "mean": posterior_mean,
178
+ "std_err": posterior_sd,
179
+ "epsilon": epsilon,
180
+ "target_epsilon": target_epsilon,
181
+ "ci_low": lower,
182
+ "ci_high": upper,
183
+ "alpha": alpha,
184
+ "beta": beta,
185
+ "projected_trials": projected,
186
+ }
187
+ return PolicyVerdict(
188
+ name=self.name,
189
+ converged=converged,
190
+ epsilon=epsilon,
191
+ target_epsilon=target_epsilon,
192
+ projected_trials=projected,
193
+ metrics=metrics,
194
+ )
195
+
196
+
197
+ class GBASPolicy:
198
+ """Huber GBAS (2017): exact relative-error control via a success-count stopping time.
199
+
200
+ The relative tolerance and failure probability reuse the engine's existing
201
+ spec rather than introducing a new knob:
202
+
203
+ * ``epsilon`` := ``ctx.delta`` (relative tolerance)
204
+ * ``delta_fail`` := ``1 - ctx.confidence`` (failure probability)
205
+
206
+ On the first evaluation ``k`` is solved once via :func:`gbas.solve_k`. Every
207
+ pass reports progress (current/target relative SD, projected trials); once
208
+ ``num_one_bits >= k`` the GBAS estimate ``(k-1)/R`` and its exact confidence
209
+ interval are materialized (and cached, since the estimate is randomized and
210
+ defined at the crossing). Pass ``seed`` for reproducible randomization.
211
+ """
212
+
213
+ name = "gbas"
214
+
215
+ def __init__(
216
+ self,
217
+ *,
218
+ epsilon: float | None = None,
219
+ delta_fail: float | None = None,
220
+ seed: int | None = None,
221
+ ) -> None:
222
+ self._epsilon = epsilon
223
+ self._delta_fail = delta_fail
224
+ self._seed = seed
225
+ self._rng: Any = None
226
+ self._k: int | None = None
227
+ self._eps: float = 0.0
228
+ self._delta: float = 0.0
229
+ self._achieved_delta: float | None = None
230
+ self._target_rel_sd: float = math.inf
231
+ self._estimate: Any = None # gbas.GBASEstimate, cached at first crossing
232
+
233
+ def _configure(self, ctx: RunContext) -> None:
234
+ if self._k is not None:
235
+ return
236
+ import numpy as np
237
+
238
+ from . import gbas
239
+
240
+ self._eps = float(self._epsilon if self._epsilon is not None else ctx.delta)
241
+ self._delta = float(
242
+ self._delta_fail if self._delta_fail is not None else (1.0 - ctx.confidence)
243
+ )
244
+ self._k = gbas.solve_k(self._eps, self._delta)
245
+ self._achieved_delta = gbas.relative_error_tail(self._k, self._eps)
246
+ self._target_rel_sd = gbas.relative_sd(self._k)
247
+ self._rng = np.random.default_rng(self._seed)
248
+
249
+ def evaluate(self, node: NodeState, ctx: RunContext) -> PolicyVerdict:
250
+ from . import gbas
251
+
252
+ self._configure(ctx)
253
+ k = self._k
254
+ assert k is not None # set by _configure
255
+ successes = node.num_one_bits
256
+ total = node.total_bits
257
+ converged = successes >= k
258
+
259
+ current_rel_sd = gbas.relative_sd(successes)
260
+
261
+ if successes > 0:
262
+ projected = max(total, math.ceil(total * k / successes))
263
+ else:
264
+ projected = 0
265
+
266
+ # Running GBAS confidence bands: the *exact* relative interval at the current
267
+ # success count, scaled by the running mean. This is a "precision so far"
268
+ # envelope (independent of p) that shrinks toward the exact interval the
269
+ # estimate settles into at the stopping time. We emit the client-requested
270
+ # level (``run_ci_*``) plus fixed 95%/99% bands so the GBAS plot has the same
271
+ # nested-CI presentation the client uses elsewhere (p05-p95 / p01-p99).
272
+ def _running_band(ci_alpha: float) -> tuple[float | None, float | None]:
273
+ if successes < gbas.K_MIN:
274
+ return None, None
275
+ rel_lo, rel_hi = gbas.relative_interval(successes, ci_alpha)
276
+ run_mean = node.mean
277
+ return max(0.0, run_mean * rel_lo), min(1.0, run_mean * rel_hi)
278
+
279
+ run_ci_low, run_ci_high = _running_band(self._delta)
280
+ run_ci95_low, run_ci95_high = _running_band(_ALPHA95)
281
+ run_ci99_low, run_ci99_high = _running_band(_ALPHA99)
282
+
283
+ metrics: dict[str, Any] = {
284
+ "k": k,
285
+ "successes": successes,
286
+ "target_delta": self._delta,
287
+ "achieved_delta": self._achieved_delta,
288
+ "relative_tolerance": self._eps,
289
+ "rel_sd": current_rel_sd,
290
+ "rel_sd_target": self._target_rel_sd,
291
+ "projected_trials": projected,
292
+ "run_ci_low": run_ci_low,
293
+ "run_ci_high": run_ci_high,
294
+ "run_ci95_low": run_ci95_low,
295
+ "run_ci95_high": run_ci95_high,
296
+ "run_ci99_low": run_ci99_low,
297
+ "run_ci99_high": run_ci99_high,
298
+ "mean": None,
299
+ "std_err": None,
300
+ "ci_low": None,
301
+ "ci_high": None,
302
+ "ci95_low": None,
303
+ "ci95_high": None,
304
+ "ci99_low": None,
305
+ "ci99_high": None,
306
+ "rel_low": None,
307
+ "rel_high": None,
308
+ "n_star": None,
309
+ "gamma_r": None,
310
+ }
311
+
312
+ if converged:
313
+ if self._estimate is None:
314
+ prev = node.previous_point()
315
+ prev_total = prev.total_bits if prev is not None else 0
316
+ prev_ones = prev.num_one_bits if prev is not None else 0
317
+ if prev_ones >= k: # defensive: policy attached after the crossing
318
+ prev_total, prev_ones = 0, 0
319
+ self._estimate = gbas.estimate_at_crossing(
320
+ k=k,
321
+ prev_total=prev_total,
322
+ prev_ones=prev_ones,
323
+ cur_total=total,
324
+ cur_ones=successes,
325
+ ci_alpha=self._delta,
326
+ rng=self._rng,
327
+ )
328
+ est = self._estimate
329
+ # Posterior-free relative SD of the *estimator* (exact, p-independent).
330
+ std_err = est.p_hat * self._target_rel_sd if math.isfinite(self._target_rel_sd) else None
331
+ # Exact intervals at the stopping time: the client level (cached on the
332
+ # estimate) plus fixed 95%/99% pivots on the same realized R.
333
+ ci95_low, ci95_high = gbas.confidence_interval(k, est.gamma_r, _ALPHA95)
334
+ ci99_low, ci99_high = gbas.confidence_interval(k, est.gamma_r, _ALPHA99)
335
+ metrics.update(
336
+ mean=est.p_hat,
337
+ std_err=std_err,
338
+ ci_low=est.ci_low,
339
+ ci_high=est.ci_high,
340
+ ci95_low=ci95_low,
341
+ ci95_high=ci95_high,
342
+ ci99_low=ci99_low,
343
+ ci99_high=ci99_high,
344
+ rel_low=est.rel_low,
345
+ rel_high=est.rel_high,
346
+ n_star=est.n_star,
347
+ gamma_r=est.gamma_r,
348
+ )
349
+
350
+ return PolicyVerdict(
351
+ name=self.name,
352
+ converged=converged,
353
+ epsilon=current_rel_sd,
354
+ target_epsilon=self._target_rel_sd,
355
+ projected_trials=projected,
356
+ metrics=metrics,
357
+ )
358
+
359
+
360
+ # Registry so config strings ("wald", "bayes", "gbas") resolve to policy factories.
361
+ POLICY_REGISTRY: dict[str, type[ConvergencePolicy]] = {
362
+ WaldLinearPolicy.name: WaldLinearPolicy,
363
+ BayesPolicy.name: BayesPolicy,
364
+ GBASPolicy.name: GBASPolicy,
365
+ }
366
+
367
+
368
+ def make_policy(name: str) -> ConvergencePolicy:
369
+ """Instantiate a policy by name (``"wald"`` / ``"bayes"``)."""
370
+ try:
371
+ factory = POLICY_REGISTRY[name.strip().lower()]
372
+ except KeyError as exc:
373
+ raise ValueError(
374
+ f"unknown convergence policy {name!r}; known: {sorted(POLICY_REGISTRY)}"
375
+ ) from exc
376
+ return factory()
377
+
378
+
379
+ __all__ = [
380
+ "PolicyVerdict",
381
+ "ConvergencePolicy",
382
+ "WaldLinearPolicy",
383
+ "BayesPolicy",
384
+ "GBASPolicy",
385
+ "POLICY_REGISTRY",
386
+ "make_policy",
387
+ ]