batistado commited on
Commit
a1479d7
·
verified ·
1 Parent(s): 5300e29

Publish QuorumGuard controller & vLLM priority-preemption package

Browse files
.gitattributes CHANGED
@@ -34,3 +34,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
36
  fig0_architecture.png filter=lfs diff=lfs merge=lfs -text
 
 
34
  *.zst filter=lfs diff=lfs merge=lfs -text
35
  *tfevents* filter=lfs diff=lfs merge=lfs -text
36
  fig0_architecture.png filter=lfs diff=lfs merge=lfs -text
37
+ paper/main.pdf filter=lfs diff=lfs merge=lfs -text
README.md CHANGED
@@ -2,27 +2,30 @@
2
  license: apache-2.0
3
  library_name: transformers
4
  tags:
5
- - vllm
6
  - multi-agent-systems
7
  - consensus
8
  - tail-latency
9
  - semantic-entropy
10
  - llm-agents
 
11
  datasets:
12
  - batistado/QuorumBench
13
  base_model:
14
  - Qwen/Qwen2.5-3B-Instruct
15
  - Qwen/Qwen2.5-7B-Instruct
16
  - Qwen/Qwen2.5-Coder-14B-Instruct
 
 
17
  ---
18
 
19
- # QuorumGuard: Claim-Genealogy-Gated Hedged Quorums & vLLM Dissent Preemption
20
 
21
  * **Benchmark Dataset:** [`batistado/QuorumBench`](https://huggingface.co/datasets/batistado/QuorumBench)
22
  * **Interactive Simulator Space:** [`batistado/QuorumGuard-Explorer`](https://huggingface.co/spaces/batistado/QuorumGuard-Explorer)
 
23
  * **Source Code & Paper:** [`github.com/batistado/quorumguard`](https://github.com/batistado/quorumguard)
24
 
25
- `QuorumGuard` is a model-agnostic consensus controller and GPU priority-preemption scheduler for asynchronous multi-agent LLM committees. It requires zero weight modifications and operates directly on pre-commitment option logits, provenance DAGs, and `vLLM` request priorities.
26
 
27
  ![QuorumGuard Overview](fig0_architecture.png)
28
 
 
2
  license: apache-2.0
3
  library_name: transformers
4
  tags:
 
5
  - multi-agent-systems
6
  - consensus
7
  - tail-latency
8
  - semantic-entropy
9
  - llm-agents
10
+ - vllm
11
  datasets:
12
  - batistado/QuorumBench
13
  base_model:
14
  - Qwen/Qwen2.5-3B-Instruct
15
  - Qwen/Qwen2.5-7B-Instruct
16
  - Qwen/Qwen2.5-Coder-14B-Instruct
17
+ - HuggingFaceTB/SmolLM2-1.7B-Instruct
18
+ - ibm-granite/granite-3.1-8b-instruct
19
  ---
20
 
21
+ # QuorumGuard: Claim-Genealogy-Gated Hedged Quorums & Priority Dissent Preemption
22
 
23
  * **Benchmark Dataset:** [`batistado/QuorumBench`](https://huggingface.co/datasets/batistado/QuorumBench)
24
  * **Interactive Simulator Space:** [`batistado/QuorumGuard-Explorer`](https://huggingface.co/spaces/batistado/QuorumGuard-Explorer)
25
+ * **Paper PDF (10 pages):** [`paper/main.pdf`](paper/main.pdf)
26
  * **Source Code & Paper:** [`github.com/batistado/quorumguard`](https://github.com/batistado/quorumguard)
27
 
28
+ `QuorumGuard` is a model-agnostic consensus controller and quantum-preemptive priority scheduler for asynchronous multi-agent LLM committees. It requires zero weight modifications and operates on pre-commitment option logits, provenance DAGs, and priority-preemptive decode quanta (`Priority = -10` in both our live PyTorch MPS `DynamicCache` server and `vLLM`-compatible priority schedulers).
29
 
30
  ![QuorumGuard Overview](fig0_architecture.png)
31
 
fig0_architecture.png CHANGED

Git LFS Details

  • SHA256: a21c8306b6452dd22ca459e9b8792d7a7e066a519bfa098d7c9f1329c079ac7b
  • Pointer size: 131 Bytes
  • Size of remote file: 291 kB

Git LFS Details

  • SHA256: 6173ac12c5297e3737a82a294829aa725e5148fae82a5bf8bdc90309043d9bfb
  • Pointer size: 131 Bytes
  • Size of remote file: 281 kB
paper/highlights.pdf ADDED
Binary file (54.4 kB). View file
 
paper/main.pdf ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:8e4b6e94ea1c3c8dc2c14eb015d3bfbb5fbadce444f3a1ff90de96c5469a1bd3
3
+ size 589422
quorumguard/entropy_gate.py CHANGED
@@ -32,28 +32,39 @@ class EpistemicSignals:
32
 
33
  def compute_epistemic_weight(
34
  signals: EpistemicSignals,
35
- margin_scale: float = 3.0,
36
- unverified_shallow_discount: float = 0.84,
37
- tool_verified_bonus: float = 1.25,
38
- max_weight: float = 1.15,
 
 
 
 
 
 
 
 
39
  ) -> float:
40
  """
41
- Map raw logit/entropy & verification signals into calibrated vote weight w_i.
 
42
  """
43
  norm_ent = signals.normalized_option_entropy
44
  ent_certainty = 1.0 - norm_ent
45
  margin_certainty = math.tanh(max(0.0, signals.logit_margin) / max(1e-6, margin_scale))
46
- seq_penalty = 1.0 / (1.0 + 0.12 * max(0.0, signals.seq_token_entropy - 0.6))
47
 
48
  base = (0.55 * ent_certainty + 0.45 * margin_certainty) * seq_penalty
49
  if signals.tool_verified:
50
  mult = tool_verified_bonus
 
 
51
  elif signals.has_cot_trace:
52
- mult = 1.00
53
  else:
54
  mult = unverified_shallow_discount
55
 
56
- return min(max_weight, max(0.05, base * mult))
57
 
58
 
59
  def posterior_entropy_and_margin_from_logits(logits: Sequence[float]) -> tuple[float, float, list[float]]:
 
32
 
33
  def compute_epistemic_weight(
34
  signals: EpistemicSignals,
35
+ margin_scale: float = 3.5,
36
+ seq_alpha: float = 0.12,
37
+ seq_threshold: float = 0.60,
38
+ unverified_shallow_discount: float = 0.76,
39
+ short_cot_mult: float = 0.85,
40
+ cot_mult: float = 1.12,
41
+ deep_unverified_mult: float = 1.18,
42
+ tool_verified_bonus: float = 1.38,
43
+ max_weight: float = 1.35,
44
+ min_weight: float = 0.05,
45
+ is_deep_verifier: bool = False,
46
+ is_short_cot: bool = False,
47
  ) -> float:
48
  """
49
+ Map raw logit/entropy & verification signals into calibrated vote weight w_i
50
+ matching Eq. (10) in the QuorumGuard paper (default range [0.05, 1.35]).
51
  """
52
  norm_ent = signals.normalized_option_entropy
53
  ent_certainty = 1.0 - norm_ent
54
  margin_certainty = math.tanh(max(0.0, signals.logit_margin) / max(1e-6, margin_scale))
55
+ seq_penalty = 1.0 / (1.0 + max(0.0, seq_alpha) * max(0.0, signals.seq_token_entropy - seq_threshold))
56
 
57
  base = (0.55 * ent_certainty + 0.45 * margin_certainty) * seq_penalty
58
  if signals.tool_verified:
59
  mult = tool_verified_bonus
60
+ elif is_deep_verifier:
61
+ mult = deep_unverified_mult
62
  elif signals.has_cot_trace:
63
+ mult = short_cot_mult if is_short_cot else cot_mult
64
  else:
65
  mult = unverified_shallow_discount
66
 
67
+ return min(max_weight, max(min_weight, base * mult))
68
 
69
 
70
  def posterior_entropy_and_margin_from_logits(logits: Sequence[float]) -> tuple[float, float, list[float]]:
quorumguard/scheduler.py CHANGED
@@ -26,9 +26,11 @@ VLLM_PRIORITY_BACKGROUND_SPECULATIVE: int = 5
26
  @dataclass(frozen=True)
27
  class QuorumGuardConfig:
28
  min_independent_roots: int = 3
29
- tau_effective_quorum: float = 2.22
30
- min_lead_margin: float = 0.95
31
- max_fast_normalized_entropy: float = 0.22
 
 
32
  dissent_trigger_min_arrivals: int = 3
33
  priority_boost_speedup: float = 3.2
34
  max_boost_slots_per_stage: int = 2
@@ -62,7 +64,7 @@ class PriorityBudgetPool:
62
  so priority elevation cannot cause priority-inversion storms under heavy load.
63
  """
64
 
65
- def __init__(self, max_budget_tokens: float = 10.0, refill_per_stage: float = 1.2) -> None:
66
  self.max_budget = max_budget_tokens
67
  self.refill_per_stage = refill_per_stage
68
  self.available = max_budget_tokens
@@ -126,7 +128,10 @@ class QuorumGuardController:
126
  (
127
  aid,
128
  vote_map[aid].claim,
129
- compute_epistemic_weight(vote_map[aid].signals),
 
 
 
130
  )
131
  for aid in observed_ids
132
  ]
@@ -138,19 +143,29 @@ class QuorumGuardController:
138
 
139
  supporters = [vote_map[aid] for aid in observed_ids if vote_map[aid].claim == lead_claim]
140
  mean_ent = sum(s.signals.normalized_option_entropy for s in supporters) / max(1, len(supporters))
141
- has_deep_cert = any(s.signals.tool_verified or s.is_deep_verifier for s in supporters)
 
 
 
 
 
 
 
 
 
142
 
143
  clean_fast_pass = (
144
- lead_r >= min_roots
 
145
  and lead_w >= eff_tau
146
- and (lead_w - runner_w) >= cfg.min_lead_margin
147
  and mean_ent <= cfg.max_fast_normalized_entropy
 
148
  )
149
  verified_pass = (
150
- has_deep_cert
151
  and lead_r >= 2
152
- and lead_w >= (eff_tau - 0.18)
153
- and (lead_w - runner_w) >= 0.65
154
  )
155
 
156
  if clean_fast_pass or verified_pass:
@@ -180,13 +195,9 @@ class QuorumGuardController:
180
  comp_t = t_now + (dyn_arrival[aid_boost] - t_now) / max(1.0, cfg.priority_boost_speedup)
181
  dyn_arrival[aid_boost] = max(floor_t, comp_t)
182
  else:
183
- weighted_tuples = [
184
- (aid, vote_map[aid].claim, compute_epistemic_weight(vote_map[aid].signals))
185
- for aid in observed_ids
186
- ]
187
- claim_weights, claim_roots = self.dag.compute_effective_support(weighted_tuples)
188
- commit_claim, commit_weight = max(claim_weights.items(), key=lambda kv: kv[1])
189
- commit_roots = claim_roots[commit_claim]
190
  commit_time = max(dyn_arrival.values())
191
 
192
  if self.budget_pool is not None:
 
26
  @dataclass(frozen=True)
27
  class QuorumGuardConfig:
28
  min_independent_roots: int = 3
29
+ tau_effective_quorum: float = 2.12
30
+ min_lead_margin: float = 0.72
31
+ max_fast_normalized_entropy: float = 0.08
32
+ min_fast_logit_margin: float = 3.2
33
+ dissent_runner_threshold: float = 0.35
34
  dissent_trigger_min_arrivals: int = 3
35
  priority_boost_speedup: float = 3.2
36
  max_boost_slots_per_stage: int = 2
 
64
  so priority elevation cannot cause priority-inversion storms under heavy load.
65
  """
66
 
67
+ def __init__(self, max_budget_tokens: float = 6.0, refill_per_stage: float = 0.64) -> None:
68
  self.max_budget = max_budget_tokens
69
  self.refill_per_stage = refill_per_stage
70
  self.available = max_budget_tokens
 
128
  (
129
  aid,
130
  vote_map[aid].claim,
131
+ compute_epistemic_weight(
132
+ vote_map[aid].signals,
133
+ is_deep_verifier=vote_map[aid].is_deep_verifier,
134
+ ),
135
  )
136
  for aid in observed_ids
137
  ]
 
143
 
144
  supporters = [vote_map[aid] for aid in observed_ids if vote_map[aid].claim == lead_claim]
145
  mean_ent = sum(s.signals.normalized_option_entropy for s in supporters) / max(1, len(supporters))
146
+ min_margin = min(s.signals.logit_margin for s in supporters)
147
+ dissent = len(ranked) >= 2 and runner_w >= cfg.dissent_runner_threshold
148
+ deep_supporter_roots: Set[str] = set()
149
+ for aid in observed_ids:
150
+ v = vote_map[aid]
151
+ if v.claim == lead_claim and (
152
+ v.signals.tool_verified or v.is_deep_verifier or v.signals.has_cot_trace
153
+ ):
154
+ deep_supporter_roots.update(self.dag.resolve_roots(aid))
155
+ r_deep = len(deep_supporter_roots)
156
 
157
  clean_fast_pass = (
158
+ (not dissent)
159
+ and lead_r >= min_roots
160
  and lead_w >= eff_tau
 
161
  and mean_ent <= cfg.max_fast_normalized_entropy
162
+ and min_margin >= cfg.min_fast_logit_margin
163
  )
164
  verified_pass = (
165
+ (r_deep >= 2 or (r_deep >= 1 and not dissent))
166
  and lead_r >= 2
167
+ and lead_w >= (eff_tau - 0.15)
168
+ and (lead_w - runner_w) >= cfg.min_lead_margin
169
  )
170
 
171
  if clean_fast_pass or verified_pass:
 
195
  comp_t = t_now + (dyn_arrival[aid_boost] - t_now) / max(1.0, cfg.priority_boost_speedup)
196
  dyn_arrival[aid_boost] = max(floor_t, comp_t)
197
  else:
198
+ commit_claim = lead_claim
199
+ commit_weight = lead_w
200
+ commit_roots = lead_r
 
 
 
 
201
  commit_time = max(dyn_arrival.values())
202
 
203
  if self.budget_pool is not None: