Instructions to use batistado/QuorumGuard with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use batistado/QuorumGuard with Transformers:
# pip install -U transformers accelerate # Load model directly from transformers import AutoModel model = AutoModel.from_pretrained("batistado/QuorumGuard", device_map="auto") - Notebooks
- Google Colab
- Kaggle
Publish QuorumGuard controller & vLLM priority-preemption package
Browse files- .gitattributes +1 -0
- README.md +6 -3
- fig0_architecture.png +2 -2
- paper/highlights.pdf +0 -0
- paper/main.pdf +3 -0
- quorumguard/entropy_gate.py +19 -8
- quorumguard/scheduler.py +29 -18
.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 &
|
| 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
|
| 26 |
|
| 27 |

|
| 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 |

|
| 31 |
|
fig0_architecture.png
CHANGED
|
Git LFS Details
|
|
Git LFS Details
|
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.
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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.
|
| 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 =
|
| 53 |
else:
|
| 54 |
mult = unverified_shallow_discount
|
| 55 |
|
| 56 |
-
return min(max_weight, max(
|
| 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.
|
| 30 |
-
min_lead_margin: float = 0.
|
| 31 |
-
max_fast_normalized_entropy: float = 0.
|
|
|
|
|
|
|
| 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 =
|
| 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(
|
|
|
|
|
|
|
|
|
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 142 |
|
| 143 |
clean_fast_pass = (
|
| 144 |
-
|
|
|
|
| 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 |
-
|
| 151 |
and lead_r >= 2
|
| 152 |
-
and lead_w >= (eff_tau - 0.
|
| 153 |
-
and (lead_w - runner_w) >=
|
| 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 |
-
|
| 184 |
-
|
| 185 |
-
|
| 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:
|