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,179 @@
1
+ """Host-side tally state for the Python convergence engine.
2
+
3
+ The native sampler only ever produces *raw counters* per node per pass:
4
+ ``num_one_bits`` (Bernoulli successes) and ``total_bits`` (cumulative trials).
5
+ Everything statistical is derived from these on the host. This module owns the
6
+ state model:
7
+
8
+ * :class:`NodeCounters` — the immutable raw counter pair (the binding's
9
+ ``tally_counter_dict``) for a single node at a single point in time.
10
+ * :class:`PassObservation` — the full output of one sampler pass: counters for
11
+ every tracked node plus pass metadata (index, wall-clock, trials/pass).
12
+ * :class:`NodeState` — accumulates a single node's counters across passes and
13
+ keeps a bounded trajectory ``history`` so per-pass metrics (information gain,
14
+ throughput) can be computed without re-deriving from scratch.
15
+ * :class:`RunState` — the collection of :class:`NodeState` for a run.
16
+ * :class:`RunContext` — immutable per-run configuration shared with every
17
+ policy/metric (confidence ``z``, relative margin ``delta``, oracle, geometry).
18
+
19
+ Estimators and policies consume ``(NodeState, RunContext)`` and never touch the
20
+ sampler, so they are trivially unit-testable.
21
+ """
22
+
23
+ from __future__ import annotations
24
+
25
+ from collections import deque
26
+ from dataclasses import dataclass, field
27
+ from typing import Deque, Iterable, Mapping
28
+
29
+ from .special import DELTA_EPSILON
30
+
31
+ # Default trajectory window. Per-pass metrics only need the last few points;
32
+ # a few thousand bounds memory for unlimited (num_trials=0) live runs.
33
+ DEFAULT_HISTORY: int = 4096
34
+
35
+
36
+ @dataclass(frozen=True, slots=True)
37
+ class NodeCounters:
38
+ """Raw cumulative Bernoulli counters for one node (the ``tally_counter_dict``)."""
39
+
40
+ index: int
41
+ num_one_bits: int
42
+ total_bits: int
43
+
44
+ @property
45
+ def mean(self) -> float:
46
+ """Sample proportion ``p_hat = num_one_bits / total_bits`` (0 if no trials)."""
47
+ return self.num_one_bits / self.total_bits if self.total_bits else 0.0
48
+
49
+ @property
50
+ def num_zero_bits(self) -> int:
51
+ return self.total_bits - self.num_one_bits
52
+
53
+
54
+ @dataclass(frozen=True, slots=True)
55
+ class HistoryPoint:
56
+ """One point on a node's cumulative trajectory."""
57
+
58
+ total_bits: int
59
+ num_one_bits: int
60
+ wall_time: float
61
+
62
+ @property
63
+ def mean(self) -> float:
64
+ return self.num_one_bits / self.total_bits if self.total_bits else 0.0
65
+
66
+
67
+ @dataclass(frozen=True, slots=True)
68
+ class PassObservation:
69
+ """Immutable result of a single sampler pass over all tracked nodes."""
70
+
71
+ pass_index: int # 1-based count of passes executed so far this run
72
+ wall_time: float # time.monotonic() captured right after the device drained
73
+ trials_per_pass: int
74
+ target_index: int
75
+ nodes: Mapping[int, NodeCounters]
76
+
77
+ @property
78
+ def target(self) -> NodeCounters:
79
+ return self.nodes[self.target_index]
80
+
81
+
82
+ @dataclass(slots=True)
83
+ class NodeState:
84
+ """Accumulated state for a single node, with a bounded trajectory buffer."""
85
+
86
+ index: int
87
+ num_one_bits: int = 0
88
+ total_bits: int = 0
89
+ first_wall_time: float | None = None
90
+ last_wall_time: float | None = None
91
+ history: Deque[HistoryPoint] = field(default_factory=lambda: deque(maxlen=DEFAULT_HISTORY))
92
+
93
+ def update(self, counters: NodeCounters, wall_time: float) -> None:
94
+ """Fold a new (cumulative) counter reading into this node's state."""
95
+ self.num_one_bits = counters.num_one_bits
96
+ self.total_bits = counters.total_bits
97
+ if self.first_wall_time is None:
98
+ self.first_wall_time = wall_time
99
+ self.last_wall_time = wall_time
100
+ self.history.append(HistoryPoint(counters.total_bits, counters.num_one_bits, wall_time))
101
+
102
+ # -- derived point estimates ------------------------------------------
103
+ @property
104
+ def counters(self) -> NodeCounters:
105
+ return NodeCounters(self.index, self.num_one_bits, self.total_bits)
106
+
107
+ @property
108
+ def mean(self) -> float:
109
+ return self.num_one_bits / self.total_bits if self.total_bits else 0.0
110
+
111
+ @property
112
+ def mean_guarded(self) -> float:
113
+ """``p_hat`` floored at :data:`DELTA_EPSILON` (for ratios / log scales)."""
114
+ return max(self.mean, DELTA_EPSILON)
115
+
116
+ @property
117
+ def std_err(self) -> float:
118
+ r"""Binomial standard error :math:`\sqrt{\hat p (1-\hat p)/N}`."""
119
+ n = self.total_bits
120
+ if n == 0:
121
+ return 0.0
122
+ p = self.mean
123
+ return (p * (1.0 - p) / n) ** 0.5
124
+
125
+ def previous_point(self) -> HistoryPoint | None:
126
+ """The trajectory point immediately before the latest one, if any."""
127
+ return self.history[-2] if len(self.history) >= 2 else None
128
+
129
+
130
+ @dataclass(frozen=True, slots=True)
131
+ class RunContext:
132
+ """Immutable per-run configuration handed to every policy and metric."""
133
+
134
+ confidence: float
135
+ z: float
136
+ delta: float
137
+ trials_per_pass: int
138
+ target_index: int
139
+ oracle_p: float | None = None
140
+
141
+ @property
142
+ def diagnostics_enabled(self) -> bool:
143
+ return self.oracle_p is not None and self.oracle_p >= 0.0
144
+
145
+
146
+ @dataclass(slots=True)
147
+ class RunState:
148
+ """All node states for a run plus aggregate pass bookkeeping."""
149
+
150
+ target_index: int
151
+ pass_count: int = 0
152
+ nodes: dict[int, NodeState] = field(default_factory=dict)
153
+
154
+ def update(self, observation: PassObservation) -> None:
155
+ self.pass_count = observation.pass_index
156
+ for index, counters in observation.nodes.items():
157
+ node = self.nodes.get(index)
158
+ if node is None:
159
+ node = NodeState(index=index)
160
+ self.nodes[index] = node
161
+ node.update(counters, observation.wall_time)
162
+
163
+ @property
164
+ def target(self) -> NodeState:
165
+ return self.nodes[self.target_index]
166
+
167
+ def iter_nodes(self) -> Iterable[NodeState]:
168
+ return self.nodes.values()
169
+
170
+
171
+ __all__ = [
172
+ "DEFAULT_HISTORY",
173
+ "NodeCounters",
174
+ "HistoryPoint",
175
+ "PassObservation",
176
+ "NodeState",
177
+ "RunContext",
178
+ "RunState",
179
+ ]
@@ -0,0 +1,58 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import threading
5
+ from collections import deque
6
+ from typing import Any
7
+
8
+ from fastapi import WebSocket
9
+
10
+
11
+ class EventHub:
12
+ def __init__(self, max_replay_events: int = 10_000) -> None:
13
+ self._loop: asyncio.AbstractEventLoop | None = None
14
+ self._clients: set[WebSocket] = set()
15
+ self._recent: deque[dict[str, Any]] = deque(maxlen=max_replay_events)
16
+ self._recent_lock = threading.Lock()
17
+
18
+ def bind_loop(self, loop: asyncio.AbstractEventLoop) -> None:
19
+ self._loop = loop
20
+
21
+ async def connect(
22
+ self,
23
+ websocket: WebSocket,
24
+ initial_status: dict[str, Any],
25
+ replay: bool = False,
26
+ ) -> None:
27
+ await websocket.accept()
28
+ self._clients.add(websocket)
29
+ await websocket.send_json({"event": "snapshot", "status": initial_status})
30
+ if replay:
31
+ with self._recent_lock:
32
+ recent = list(self._recent)
33
+ for event in recent:
34
+ await websocket.send_json(event)
35
+
36
+ def disconnect(self, websocket: WebSocket) -> None:
37
+ self._clients.discard(websocket)
38
+
39
+ def publish_from_thread(self, event: dict[str, Any]) -> None:
40
+ if self._loop is None:
41
+ return
42
+ self._loop.call_soon_threadsafe(lambda: asyncio.create_task(self._publish(event)))
43
+
44
+ async def _publish(self, event: dict[str, Any]) -> None:
45
+ with self._recent_lock:
46
+ self._recent.append(event)
47
+ stale: list[WebSocket] = []
48
+ for client in self._clients:
49
+ try:
50
+ await client.send_json(event)
51
+ except RuntimeError:
52
+ stale.append(client)
53
+ for client in stale:
54
+ self.disconnect(client)
55
+
56
+ def clear_replay(self) -> None:
57
+ with self._recent_lock:
58
+ self._recent.clear()
@@ -0,0 +1,16 @@
1
+ from __future__ import annotations
2
+
3
+ import json
4
+ from typing import Any
5
+
6
+ from fuzzybits_server.config import env_bool
7
+
8
+
9
+ def log_events_to_stdout() -> bool:
10
+ return env_bool("MCSCRAM_LOG_EVENTS", False)
11
+
12
+
13
+ def emit(event: str, **payload: Any) -> None:
14
+ if not log_events_to_stdout():
15
+ return
16
+ print(json.dumps({"event": event, **payload}, sort_keys=True), flush=True)