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,398 @@
1
+ """The pass -> tally -> update -> emit loop and its configuration.
2
+
3
+ :class:`ConvergenceRunner` ties the layers together:
4
+
5
+ 1. pull one :class:`PassObservation` from a :class:`Sampler`,
6
+ 2. fold it into :class:`RunState`,
7
+ 3. evaluate every attached :class:`ConvergencePolicy` and :class:`Metric`,
8
+ 4. assemble a flat progress frame, and
9
+ 5. decide whether to stop (burn-in, early-stop on the chosen policy, or a
10
+ trial/pass budget).
11
+
12
+ The progress frame keeps the field names the existing web client consumes
13
+ (``mean``, ``epsilon``, ``target_epsilon``, ``epsilon_converged``,
14
+ ``p01/05/95/99``, ``info_bits_*`` …) filled from the *primary* policy (GBAS
15
+ by default), and adds every policy/metric under its own namespace (``wald_*``,
16
+ ``bayes_*``, ``info_bits_*`` …) so additional streams are available without
17
+ breaking the UI.
18
+
19
+ :class:`ConvergenceConfig` carries the host-side knobs and is built from the
20
+ existing server options dict via :meth:`ConvergenceConfig.from_options`.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ import math
26
+ import time
27
+ from dataclasses import dataclass
28
+ from typing import Any, Callable, Sequence
29
+
30
+ from .metrics import Metric, default_metrics
31
+ from .policies import ConvergencePolicy, PolicyVerdict, make_policy
32
+ from .sampling import Sampler, make_sampler
33
+ from .special import normal_quantile_two_sided
34
+ from .tally import RunContext, RunState
35
+
36
+ ProgressCallback = Callable[[dict[str, Any]], None]
37
+
38
+ # Default primary policy: fills the canonical (un-namespaced) frontend fields.
39
+ PRIMARY_POLICY = "gbas"
40
+
41
+
42
+ def _as_float(value: Any) -> float | None:
43
+ try:
44
+ if value is None:
45
+ return None
46
+ return float(value)
47
+ except (TypeError, ValueError):
48
+ return None
49
+
50
+
51
+ def _as_int(value: Any) -> int | None:
52
+ f = _as_float(value)
53
+ return int(round(f)) if f is not None else None
54
+
55
+
56
+ def _as_bool(value: Any) -> bool:
57
+ if isinstance(value, str):
58
+ return value.strip().lower() in {"1", "true", "yes", "on"}
59
+ return bool(value)
60
+
61
+
62
+ def _sanitize(value: Any) -> Any:
63
+ """Make a progress value safe for strict JSON (browsers reject NaN/Infinity)."""
64
+ if isinstance(value, float):
65
+ return value if math.isfinite(value) else None
66
+ if isinstance(value, dict):
67
+ return {key: _sanitize(item) for key, item in value.items()}
68
+ if isinstance(value, (list, tuple)):
69
+ return [_sanitize(item) for item in value]
70
+ return value
71
+
72
+
73
+ @dataclass(frozen=True)
74
+ class ConvergenceConfig:
75
+ """Host-side convergence configuration (independent of the native settings).
76
+
77
+ Note: intentionally *not* ``slots=True`` -- :meth:`from_options` reads field
78
+ defaults via ``cls.<field>`` (which slots would shadow with descriptors).
79
+ """
80
+
81
+ delta: float = 1.0e-3
82
+ confidence: float = 0.99
83
+ burn_in: int = 0
84
+ max_trials: int = 0 # 0 -> unlimited
85
+ max_passes: int = 0 # 0 -> derive from max_trials, else unbounded
86
+ early_stop: bool = False
87
+ oracle_p: float | None = None
88
+ policies: tuple[str, ...] = ("wald", "bayes")
89
+ stopping_policy: str = "wald"
90
+ event_ids: tuple[int, ...] = ()
91
+ emit_min_interval_s: float = 1.0 / 60.0
92
+ stream_nodes: bool = False
93
+
94
+ @classmethod
95
+ def from_options(cls, options: dict[str, Any] | None) -> "ConvergenceConfig":
96
+ """Build a config from the server's CLI-like options mapping."""
97
+ options = options or {}
98
+ delta = _as_float(options.get("delta"))
99
+ confidence = _as_float(options.get("confidence"))
100
+ burn_in = _as_int(options.get("burn_in"))
101
+ max_trials = _as_int(options.get("num_trials"))
102
+ oracle = _as_float(options.get("oracle"))
103
+ policy = options.get("policy")
104
+ stopping = str(policy).strip().lower() if policy else cls.stopping_policy
105
+ # Always evaluate both policies so Wald and Bayes stats stream together,
106
+ # regardless of which one gates the stop.
107
+ policies: tuple[str, ...] = ("wald", "bayes")
108
+ if stopping not in policies:
109
+ policies = (*policies, stopping)
110
+
111
+ emit_interval = _as_float(options.get("emit_min_interval_s"))
112
+ event_ids = tuple(int(i) for i in options.get("convergence_event_ids", ()) or ())
113
+
114
+ return cls(
115
+ delta=delta if delta is not None and delta > 0 else cls.delta,
116
+ confidence=confidence if confidence is not None else cls.confidence,
117
+ burn_in=max(0, burn_in or 0),
118
+ max_trials=max(0, max_trials or 0),
119
+ max_passes=max(0, _as_int(options.get("max_passes")) or 0),
120
+ early_stop=_as_bool(options.get("early_stop", False)),
121
+ oracle_p=oracle if (oracle is not None and oracle >= 0.0) else None,
122
+ policies=policies,
123
+ stopping_policy=stopping,
124
+ event_ids=event_ids,
125
+ emit_min_interval_s=emit_interval if emit_interval is not None else cls.emit_min_interval_s,
126
+ stream_nodes=_as_bool(options.get("stream_nodes", False)),
127
+ )
128
+
129
+
130
+ @dataclass(slots=True)
131
+ class RunResult:
132
+ """Outcome of a completed (or stopped) convergence run."""
133
+
134
+ state: RunState
135
+ final_progress: dict[str, Any]
136
+ stop_reason: str | None
137
+ converged: bool
138
+ elapsed_s: float
139
+
140
+ @property
141
+ def summary(self) -> dict[str, Any]:
142
+ """A native-``run_probability``-compatible result dict for the worker."""
143
+ target = self.state.target
144
+ mean = target.mean
145
+
146
+ # If the stopping policy publishes its own point estimate (e.g. GBAS's
147
+ # Gamma-corrected ``(k-1)/R``, whose relative error is exactly known),
148
+ # prefer it as the authoritative result over the raw sample proportion.
149
+ stopping = self.final_progress.get("stopping_policy")
150
+ if stopping and self.converged:
151
+ pol_mean = self.final_progress.get(f"{stopping}_mean")
152
+ if isinstance(pol_mean, (int, float)) and math.isfinite(float(pol_mean)):
153
+ mean = float(pol_mean)
154
+
155
+ result: dict[str, Any] = {
156
+ "analysis_time": self.elapsed_s,
157
+ "warnings": "",
158
+ "probabilities": [{"p_total": mean, "analysis_time": self.elapsed_s}],
159
+ "engine": "python",
160
+ "converged": self.converged,
161
+ "stop_reason": self.stop_reason,
162
+ "mean": mean,
163
+ "sample_mean": target.mean,
164
+ "trials": target.total_bits,
165
+ "passes": self.state.pass_count,
166
+ "stopping_policy": stopping,
167
+ }
168
+
169
+ # Carry the stopping policy's confidence interval when it provides one.
170
+ ci_low = self.final_progress.get(f"{stopping}_ci_low") if stopping else None
171
+ ci_high = self.final_progress.get(f"{stopping}_ci_high") if stopping else None
172
+ if isinstance(ci_low, (int, float)) and isinstance(ci_high, (int, float)):
173
+ result["ci_low"] = float(ci_low)
174
+ result["ci_high"] = float(ci_high)
175
+ return result
176
+
177
+
178
+ class ConvergenceRunner:
179
+ """Drives the host-side convergence loop for a single sampler."""
180
+
181
+ def __init__(
182
+ self,
183
+ sampler: Sampler,
184
+ config: ConvergenceConfig,
185
+ *,
186
+ policies: Sequence[ConvergencePolicy] | None = None,
187
+ metrics: Sequence[Metric] | None = None,
188
+ on_progress: ProgressCallback | None = None,
189
+ ) -> None:
190
+ self.sampler = sampler
191
+ self.config = config
192
+ self.on_progress = on_progress
193
+ self.policies: list[ConvergencePolicy] = (
194
+ list(policies) if policies is not None else [make_policy(name) for name in config.policies]
195
+ )
196
+ self.metrics: list[Metric] = (
197
+ list(metrics) if metrics is not None else default_metrics()
198
+ )
199
+ self.state = RunState(target_index=sampler.target_index)
200
+
201
+ z = normal_quantile_two_sided(config.confidence)
202
+ self.ctx = RunContext(
203
+ confidence=config.confidence,
204
+ z=z,
205
+ delta=config.delta,
206
+ trials_per_pass=sampler.shape.trials_per_pass,
207
+ target_index=sampler.target_index,
208
+ oracle_p=config.oracle_p,
209
+ )
210
+
211
+ by_name = {policy.name: policy for policy in self.policies}
212
+ self._primary_name = PRIMARY_POLICY if PRIMARY_POLICY in by_name else self.policies[0].name
213
+ self._stopping_name = (
214
+ config.stopping_policy if config.stopping_policy in by_name else self._primary_name
215
+ )
216
+
217
+ # -- public API --------------------------------------------------------
218
+ def run(self) -> RunResult:
219
+ """Run until a stop condition fires; returns the final :class:`RunResult`."""
220
+ cfg = self.config
221
+ tpp = max(1, self.sampler.shape.trials_per_pass)
222
+ max_passes = cfg.max_passes
223
+ if not max_passes and cfg.max_trials:
224
+ max_passes = math.ceil(cfg.max_trials / tpp)
225
+
226
+ start = time.monotonic()
227
+ last_emit = -math.inf
228
+ last_phase: str | None = None
229
+ final_progress: dict[str, Any] = {}
230
+ stop_reason: str | None = None
231
+ converged = False
232
+
233
+ while True:
234
+ observation = self.sampler.step()
235
+ self.state.update(observation)
236
+ target = self.state.target
237
+
238
+ phase = "burn_in" if target.total_bits < cfg.burn_in else "sampling"
239
+ verdicts = {policy.name: policy.evaluate(target, self.ctx) for policy in self.policies}
240
+
241
+ stopping_converged = verdicts[self._stopping_name].converged and phase == "sampling"
242
+ stop_reason = self._stop_reason(
243
+ phase=phase,
244
+ stopping_converged=stopping_converged,
245
+ total_bits=target.total_bits,
246
+ pass_count=self.state.pass_count,
247
+ max_passes=max_passes,
248
+ )
249
+ converged = stopping_converged
250
+ stopping = stop_reason is not None
251
+
252
+ progress = self._build_progress(phase, verdicts)
253
+ progress["converged"] = stopping_converged
254
+ if stopping:
255
+ progress["stop_reason"] = stop_reason
256
+ final_progress = progress
257
+
258
+ force = stopping or last_phase != phase or self.state.pass_count == 1
259
+ if self.on_progress is not None and (
260
+ force or (observation.wall_time - last_emit) >= cfg.emit_min_interval_s
261
+ ):
262
+ self.on_progress(progress)
263
+ last_emit = observation.wall_time
264
+ last_phase = phase
265
+
266
+ if stopping:
267
+ break
268
+
269
+ return RunResult(
270
+ state=self.state,
271
+ final_progress=final_progress,
272
+ stop_reason=stop_reason,
273
+ converged=converged,
274
+ elapsed_s=time.monotonic() - start,
275
+ )
276
+
277
+ # -- internals ---------------------------------------------------------
278
+ def _stop_reason(
279
+ self,
280
+ *,
281
+ phase: str,
282
+ stopping_converged: bool,
283
+ total_bits: int,
284
+ pass_count: int,
285
+ max_passes: int,
286
+ ) -> str | None:
287
+ if self.config.max_trials and total_bits >= self.config.max_trials:
288
+ return "max_trials"
289
+ if max_passes and pass_count >= max_passes:
290
+ return "max_passes"
291
+ if phase == "sampling" and self.config.early_stop and stopping_converged:
292
+ return "converged"
293
+ return None
294
+
295
+ def _build_progress(
296
+ self, phase: str, verdicts: dict[str, PolicyVerdict]
297
+ ) -> dict[str, Any]:
298
+ target = self.state.target
299
+ tpp = max(1, self.sampler.shape.trials_per_pass)
300
+ total_bits = target.total_bits
301
+
302
+ progress: dict[str, Any] = {
303
+ "phase": phase,
304
+ "pass_index": self.state.pass_count,
305
+ "iterations": self.state.pass_count,
306
+ "trials": total_bits,
307
+ "trials_per_pass": tpp,
308
+ }
309
+
310
+ # Auxiliary metrics (point estimate, info gain, diagnostics).
311
+ for metric in self.metrics:
312
+ progress.update(metric.compute(target, self.ctx))
313
+
314
+ # Primary policy fills the canonical (un-namespaced) fields.
315
+ primary = verdicts[self._primary_name]
316
+ for key, value in primary.metrics.items():
317
+ if value is not None:
318
+ progress[key] = value
319
+ progress["epsilon"] = primary.epsilon
320
+ progress["target_epsilon"] = primary.target_epsilon
321
+ progress["epsilon_converged"] = primary.converged
322
+ # GBAS does not emit Wald percentile bands; keep them on the canonical
323
+ # frame from Wald when both policies are attached.
324
+ if self._primary_name != "wald" and "wald" in verdicts:
325
+ wald_metrics = verdicts["wald"].metrics
326
+ for key in ("std_err", "p01", "p05", "p95", "p99"):
327
+ if progress.get(key) is None:
328
+ value = wald_metrics.get(key)
329
+ if value is not None:
330
+ progress[key] = value
331
+ projected = primary.projected_trials
332
+ progress["projected_trials"] = projected
333
+ progress["projected_iterations"] = math.ceil(projected / tpp) if projected else 0
334
+ remaining = max(0, projected - total_bits)
335
+ progress["remaining_trials"] = remaining
336
+ progress["remaining_iterations"] = math.ceil(remaining / tpp) if remaining else 0
337
+
338
+ # Every policy is emitted under its namespace so multiple convergence
339
+ # criteria stream simultaneously (wald_*, bayes_*, ...). Core verdict
340
+ # fields are written last so they win over any duplicated metric keys.
341
+ for name, verdict in verdicts.items():
342
+ for key, value in verdict.metrics.items():
343
+ progress[f"{name}_{key}"] = value
344
+ progress[f"{name}_converged"] = verdict.converged
345
+ progress[f"{name}_epsilon"] = verdict.epsilon
346
+ progress[f"{name}_target_epsilon"] = verdict.target_epsilon
347
+ progress[f"{name}_projected_trials"] = verdict.projected_trials
348
+
349
+ progress["primary_policy"] = self._primary_name
350
+ progress["stopping_policy"] = self._stopping_name
351
+
352
+ if self.config.stream_nodes and len(self.state.nodes) > 1:
353
+ progress["nodes"] = {
354
+ str(index): {"mean": node.mean, "trials": node.total_bits}
355
+ for index, node in self.state.nodes.items()
356
+ }
357
+
358
+ return {key: _sanitize(value) for key, value in progress.items()}
359
+
360
+
361
+ def run_calculation(
362
+ input_files: list[str],
363
+ options: dict[str, Any] | None,
364
+ on_progress: ProgressCallback | None = None,
365
+ *,
366
+ pcfb: bytes | None = None,
367
+ pcfb_path: str | None = None,
368
+ ) -> dict[str, Any]:
369
+ """Compile, sample, and converge entirely on the host; return a result dict.
370
+
371
+ Default engine is ``.pcfb`` / ``fuzzybits.Session``. Set
372
+ ``FUZZYBITS_SERVER_ENGINE=legacy`` for the in-memory ``run_compile`` path.
373
+ The native engine is used *only* to produce raw per-pass popcounts; all
374
+ convergence and statistics are computed here.
375
+ """
376
+ config = ConvergenceConfig.from_options(options)
377
+ sampler = make_sampler(
378
+ input_files,
379
+ options,
380
+ event_ids=list(config.event_ids) or None,
381
+ pcfb=pcfb,
382
+ pcfb_path=pcfb_path,
383
+ )
384
+ try:
385
+ runner = ConvergenceRunner(sampler, config, on_progress=on_progress)
386
+ result = runner.run()
387
+ finally:
388
+ sampler.close()
389
+ return result.summary
390
+
391
+
392
+ __all__ = [
393
+ "ConvergenceConfig",
394
+ "ConvergenceRunner",
395
+ "RunResult",
396
+ "ProgressCallback",
397
+ "run_calculation",
398
+ ]