batistado commited on
Commit
76a067d
·
verified ·
1 Parent(s): 24033fa

Publish QuorumGuard controller & vLLM priority-preemption package

Browse files
.gitattributes CHANGED
@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
33
  *.zip 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
 
 
33
  *.zip 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
LICENSE ADDED
@@ -0,0 +1,140 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship.
44
+
45
+ "Contribution" shall mean any work of authorship, including
46
+ the original version of the Work and any modifications or additions
47
+ to that Work or Derivative Works thereof, that is intentionally
48
+ submitted to Licensor for inclusion in the Work by the copyright owner
49
+ or by an individual or Legal Entity authorized to submit on behalf of
50
+ the copyright owner.
51
+
52
+ "Contributor" shall mean Licensor and any individual or Legal Entity
53
+ on behalf of whom a Contribution has been received by Licensor and
54
+ subsequently incorporated within the Work.
55
+
56
+ 2. Grant of Copyright License. Subject to the terms and conditions of
57
+ this License, each Contributor hereby grants to You a perpetual,
58
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
59
+ copyright license to reproduce, prepare Derivative Works of,
60
+ publicly display, publicly perform, sublicense, and distribute the
61
+ Work and such Derivative Works in Source or Object form.
62
+
63
+ 3. Grant of Patent License. Subject to the terms and conditions of
64
+ this License, each Contributor hereby grants to You a perpetual,
65
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
66
+ (except as stated in this section) patent license to make, have made,
67
+ use, offer to sell, sell, import, and otherwise transfer the Work,
68
+ where such license applies only to those patent claims licensable
69
+ by such Contributor that are necessarily infringed by their
70
+ Contribution(s) alone or by combination of their Contribution(s)
71
+ with the Work to which such Contribution(s) was submitted.
72
+
73
+ 4. Redistribution. You may reproduce and distribute copies of the
74
+ Work or Derivative Works thereof in any medium, with or without
75
+ modifications, and in Source or Object form, provided that You
76
+ meet the following conditions:
77
+
78
+ (a) You must give any other recipients of the Work or
79
+ Derivative Works a copy of this License; and
80
+
81
+ (b) You must cause any modified files to carry prominent notices
82
+ stating that You changed the files; and
83
+
84
+ (c) You must retain, in the Source form of any Derivative Works
85
+ that You distribute, all copyright, patent, trademark, and
86
+ attribution notices from the Source form of the Work,
87
+ excluding those notices that do not pertain to any part of
88
+ the Derivative Works; and
89
+
90
+ (d) If the Work includes a "NOTICE" text file as part of its
91
+ distribution, then any Derivative Works that You distribute must
92
+ include a readable copy of the attribution notices contained
93
+ within such NOTICE file.
94
+
95
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
96
+ any Contribution intentionally submitted for inclusion in the Work
97
+ by You to the Licensor shall be under the terms and conditions of
98
+ this License, without any additional terms or conditions.
99
+
100
+ 6. Trademarks. This License does not grant permission to use the trade
101
+ names, trademarks, service marks, or product names of the Licensor,
102
+ except as required for reasonable and customary use in describing the
103
+ origin of the Work and reproducing the content of the NOTICE file.
104
+
105
+ 7. Disclaimer of Warranty. Unless required by applicable law or
106
+ agreed to in writing, Licensor provides the Work (and each
107
+ Contributor provides its Contributions) on an "AS IS" BASIS,
108
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
109
+ implied, including, without limitation, any warranties or conditions
110
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
111
+ PARTICULAR PURPOSE.
112
+
113
+ 8. Limitation of Liability. In no event and under no legal theory,
114
+ whether in tort (including negligence), contract, or otherwise,
115
+ unless required by applicable law (such as deliberate and grossly
116
+ negligent acts) or agreed to in writing, shall any Contributor be
117
+ liable to You for damages, including any direct, indirect, special,
118
+ incidental, or consequential damages of any character arising as a
119
+ result of this License or out of the use or inability to use the
120
+ Work.
121
+
122
+ 9. Accepting Warranty or Additional Liability. While redistributing
123
+ the Work or Derivative Works thereof, You may choose to offer,
124
+ and charge a fee for, acceptance of support, warranty, indemnity,
125
+ or other liability obligations and/or rights consistent with this
126
+ License.
127
+
128
+ Copyright 2026 Mohammed Kamran Syed
129
+
130
+ Licensed under the Apache License, Version 2.0 (the "License");
131
+ you may not use this file except in compliance with the License.
132
+ You may obtain a copy of the License at
133
+
134
+ http://www.apache.org/licenses/LICENSE-2.0
135
+
136
+ Unless required by applicable law or agreed to in writing, software
137
+ distributed under the License is distributed on an "AS IS" BASIS,
138
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
139
+ See the License for the specific language governing permissions and
140
+ limitations under the License.
README.md ADDED
@@ -0,0 +1,33 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
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
+
29
+ ## Install
30
+
31
+ ```bash
32
+ pip install git+https://github.com/batistado/quorumguard.git
33
+ ```
fig0_architecture.png ADDED

Git LFS Details

  • SHA256: a21c8306b6452dd22ca459e9b8792d7a7e066a519bfa098d7c9f1329c079ac7b
  • Pointer size: 131 Bytes
  • Size of remote file: 291 kB
pyproject.toml ADDED
@@ -0,0 +1,37 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ [build-system]
2
+ requires = ["setuptools>=68.0"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "quorumguard"
7
+ version = "0.1.0"
8
+ description = "Claim-Genealogy-Gated Hedged Quorums and Priority-Budget Straggler Boosting for Asynchronous Multi-Agent LLM Consensus"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ authors = [
12
+ { name = "Mohammed Kamran Syed", email = "syed.kamran@live.com" },
13
+ ]
14
+ keywords = [
15
+ "multi-agent-systems",
16
+ "llm-consensus",
17
+ "quorum-systems",
18
+ "tail-latency",
19
+ "epistemic-uncertainty",
20
+ "error-cascades",
21
+ ]
22
+ classifiers = [
23
+ "Development Status :: 4 - Beta",
24
+ "Intended Audience :: Science/Research",
25
+ "Programming Language :: Python :: 3",
26
+ "Programming Language :: Python :: 3.11",
27
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
28
+ "Topic :: System :: Distributed Computing",
29
+ ]
30
+ dependencies = []
31
+
32
+ [project.optional-dependencies]
33
+ pilot = ["numpy>=1.24", "torch>=2.1", "transformers>=4.45"]
34
+ dev = ["pytest>=7.0"]
35
+
36
+ [tool.setuptools.packages.find]
37
+ include = ["quorumguard*"]
quorumguard/__init__.py ADDED
@@ -0,0 +1,35 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """QuorumGuard: Claim-Genealogy-Gated Hedged Quorums for Asynchronous Multi-Agent LLM Consensus."""
2
+
3
+ from .entropy_gate import (
4
+ EpistemicSignals,
5
+ compute_epistemic_weight,
6
+ posterior_entropy_and_margin_from_logits,
7
+ )
8
+ from .genealogy import ProvenanceDAG, ProvenanceNode
9
+ from .scheduler import (
10
+ VLLM_PRIORITY_BACKGROUND_SPECULATIVE,
11
+ VLLM_PRIORITY_DISSENT_BOOST,
12
+ VLLM_PRIORITY_NORMAL,
13
+ AgentVote,
14
+ PriorityBudgetPool,
15
+ QuorumGuardConfig,
16
+ QuorumGuardController,
17
+ StageCommitResult,
18
+ )
19
+
20
+ __all__ = [
21
+ "AgentVote",
22
+ "EpistemicSignals",
23
+ "PriorityBudgetPool",
24
+ "ProvenanceDAG",
25
+ "ProvenanceNode",
26
+ "QuorumGuardConfig",
27
+ "QuorumGuardController",
28
+ "StageCommitResult",
29
+ "VLLM_PRIORITY_BACKGROUND_SPECULATIVE",
30
+ "VLLM_PRIORITY_DISSENT_BOOST",
31
+ "VLLM_PRIORITY_NORMAL",
32
+ "compute_epistemic_weight",
33
+ "posterior_entropy_and_margin_from_logits",
34
+ ]
35
+ __version__ = "0.1.0"
quorumguard/entropy_gate.py ADDED
@@ -0,0 +1,73 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Epistemic Confidence & Token-Level Semantic Entropy Gating.
3
+ ===========================================================
4
+ Evaluates calibrated per-agent epistemic confidence weights w_i from:
5
+ 1. Candidate-hypothesis posterior Shannon entropy H_ans,
6
+ 2. Top-2 decision logit margin Delta = z_(1) - z_(2),
7
+ 3. Reasoning-trace token predictive entropy H_seq, and
8
+ 4. Deterministic tool-execution verification certificates.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ import math
14
+ from dataclasses import dataclass
15
+ from typing import Mapping, Sequence
16
+
17
+
18
+ @dataclass(frozen=True)
19
+ class EpistemicSignals:
20
+ option_entropy_nats: float
21
+ num_options: int = 4
22
+ logit_margin: float = 2.0
23
+ seq_token_entropy: float = 0.25
24
+ tool_verified: bool = False
25
+ has_cot_trace: bool = False
26
+
27
+ @property
28
+ def normalized_option_entropy(self) -> float:
29
+ denom = math.log(max(2, self.num_options))
30
+ return min(1.0, max(0.0, self.option_entropy_nats / denom))
31
+
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]]:
60
+ """
61
+ Compute exact Shannon entropy (in nats), top-2 logit margin, and normalized
62
+ probabilities from a vector of candidate option logits.
63
+ """
64
+ if not logits:
65
+ raise ValueError("logits must be non-empty")
66
+ m = max(logits)
67
+ exps = [math.exp(z - m) for z in logits]
68
+ z_sum = sum(exps)
69
+ probs = [e / z_sum for e in exps]
70
+ ent = -sum(p * math.log(max(p, 1e-15)) for p in probs)
71
+ s_logits = sorted(logits, reverse=True)
72
+ margin = (s_logits[0] - s_logits[1]) if len(s_logits) >= 2 else float("inf")
73
+ return ent, margin, probs
quorumguard/genealogy.py ADDED
@@ -0,0 +1,115 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Claim-Genealogy Independence & Provenance Lineage Tracking.
3
+ ===========================================================
4
+ Prevents correlated upstream context echoes from masquerading as independent
5
+ fast-quorum consensus votes. Given a provenance DAG G = (V, E) linking upstream
6
+ retrieval chunks, triage summaries, and agent responses, computes each agent's
7
+ minimal upstream provenance root set and evaluates genealogy-deduplicated
8
+ effective quorum support N_eff(t, c; G).
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import dataclass, field
14
+ from typing import Dict, FrozenSet, Iterable, List, Mapping, Optional, Sequence, Set, Tuple
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class ProvenanceNode:
19
+ node_id: str
20
+ kind: str = "source" # "source", "summary", "agent"
21
+ parents: Tuple[str, ...] = ()
22
+
23
+
24
+ class ProvenanceDAG:
25
+ """
26
+ Tracks information lineage from raw independent sources/verifiers to agent votes.
27
+
28
+ If two fast agents consume the same intermediate summary `S_1` derived from
29
+ source `R_0`, both trace back to `{R_0}` and collectively contribute at most
30
+ one source root's epistemic capacity toward early quorum closure.
31
+ """
32
+
33
+ def __init__(self) -> None:
34
+ self._nodes: Dict[str, ProvenanceNode] = {}
35
+ self._root_cache: Dict[str, FrozenSet[str]] = {}
36
+
37
+ def add_node(self, node_id: str, kind: str = "source", parents: Sequence[str] = ()) -> None:
38
+ self._nodes[node_id] = ProvenanceNode(
39
+ node_id=node_id, kind=kind, parents=tuple(dict.fromkeys(parents))
40
+ )
41
+ self._root_cache.clear()
42
+
43
+ def register_agent_lineage(self, agent_node_id: str, upstream_sources: Sequence[str]) -> None:
44
+ for src in upstream_sources:
45
+ if src not in self._nodes:
46
+ self._nodes[src] = ProvenanceNode(node_id=src, kind="source", parents=())
47
+ self.add_node(agent_node_id, kind="agent", parents=upstream_sources)
48
+
49
+ def resolve_roots(self, node_id: str) -> FrozenSet[str]:
50
+ """Return minimal ancestor nodes (indegree 0) in the provenance DAG."""
51
+ if node_id in self._root_cache:
52
+ return self._root_cache[node_id]
53
+ if node_id not in self._nodes or not self._nodes[node_id].parents:
54
+ res = frozenset([node_id])
55
+ self._root_cache[node_id] = res
56
+ return res
57
+
58
+ visited: Set[str] = set()
59
+ roots: Set[str] = set()
60
+ stack = [node_id]
61
+ while stack:
62
+ cur = stack.pop()
63
+ if cur in visited:
64
+ continue
65
+ visited.add(cur)
66
+ node = self._nodes.get(cur)
67
+ if node is None or not node.parents:
68
+ roots.add(cur)
69
+ else:
70
+ for p in node.parents:
71
+ stack.append(p)
72
+ res = frozenset(roots)
73
+ self._root_cache[node_id] = res
74
+ return res
75
+
76
+ def compute_effective_support(
77
+ self,
78
+ votes: Sequence[Tuple[str, str, float]],
79
+ ) -> Tuple[Dict[str, float], Dict[str, int]]:
80
+ """
81
+ Compute genealogy-deduplicated effective support N_eff(c; G) and distinct
82
+ independent root counts per candidate claim `c`.
83
+
84
+ Args:
85
+ votes: Sequence of `(agent_node_id, claim, calibrated_weight)` tuples.
86
+
87
+ Returns:
88
+ `(claim_weights, claim_distinct_roots)` where each provenance root `r`
89
+ can contribute at most unit capacity across agents sharing `r`. When an
90
+ agent depends on `m` roots `{r_1, ..., r_m}`, its weight `w_i` is split
91
+ equally (`w_i / m`) across its supporting roots before per-root max
92
+ aggregation, preserving submodularity and single-root exactness.
93
+ """
94
+ root_claim_cap: Dict[Tuple[str, str], float] = {}
95
+ claim_root_sets: Dict[str, Set[str]] = {}
96
+
97
+ for agent_id, claim, weight in votes:
98
+ if weight <= 0.0:
99
+ continue
100
+ roots = self.resolve_roots(agent_id)
101
+ share = float(weight) / max(1, len(roots))
102
+ claim_root_sets.setdefault(claim, set())
103
+ for r in roots:
104
+ key = (r, claim)
105
+ root_claim_cap[key] = max(root_claim_cap.get(key, 0.0), share)
106
+ claim_root_sets[claim].add(r)
107
+
108
+ claim_weights: Dict[str, float] = {}
109
+ for (_, claim), cap in root_claim_cap.items():
110
+ claim_weights[claim] = claim_weights.get(claim, 0.0) + cap
111
+
112
+ claim_distinct_roots: Dict[str, int] = {
113
+ c: len(rset) for c, rset in claim_root_sets.items()
114
+ }
115
+ return claim_weights, claim_distinct_roots
quorumguard/scheduler.py ADDED
@@ -0,0 +1,204 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ Event-Driven QuorumGuard Adaptive Consensus Controller & Priority-Budget Scheduler.
3
+ ===================================================================================
4
+ Implements Theorem 3's adaptive stopping time:
5
+ tau_QG = inf { t : N_eff(t, G) >= k*(H_t) }
6
+ coupled with Priority-Budget Dissent Boosting for in-flight deep verification
7
+ stragglers whenever fast arrivals exhibit genealogy correlation, disagreement,
8
+ or elevated semantic entropy. Includes vLLM priority-scheduling request hooks.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from dataclasses import dataclass, field
14
+ from typing import Callable, Dict, List, Mapping, Optional, Sequence, Set, Tuple
15
+
16
+ from .entropy_gate import EpistemicSignals, compute_epistemic_weight
17
+ from .genealogy import ProvenanceDAG
18
+
19
+
20
+ # Standard vLLM priority levels (lower integer = higher scheduling priority in vLLM Scheduler)
21
+ VLLM_PRIORITY_NORMAL: int = 0
22
+ VLLM_PRIORITY_DISSENT_BOOST: int = -10
23
+ VLLM_PRIORITY_BACKGROUND_SPECULATIVE: int = 5
24
+
25
+
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
35
+
36
+
37
+ @dataclass
38
+ class AgentVote:
39
+ agent_id: str
40
+ claim: str
41
+ arrival_time_s: float
42
+ signals: EpistemicSignals
43
+ is_deep_verifier: bool = False
44
+ irreducible_exec_floor_s: float = 0.0
45
+
46
+
47
+ @dataclass
48
+ class StageCommitResult:
49
+ committed_claim: str
50
+ commit_time_s: float
51
+ agents_observed: int
52
+ effective_quorum_weight: float
53
+ independent_roots: int
54
+ dissent_boost_triggered: bool
55
+ boosted_agent_ids: Tuple[str, ...]
56
+ early_closed: bool
57
+
58
+
59
+ class PriorityBudgetPool:
60
+ """
61
+ Token-bucket priority budget bounding cluster-wide straggler priority boosts
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
69
+
70
+ def try_acquire(self, slots: int = 1) -> int:
71
+ granted = min(slots, int(self.available))
72
+ self.available -= float(granted)
73
+ return max(0, granted)
74
+
75
+ def on_stage_complete(self) -> None:
76
+ self.available = min(self.max_budget, self.available + self.refill_per_stage)
77
+
78
+
79
+ class QuorumGuardController:
80
+ """
81
+ Stateful online quorum gate + straggler boost controller for a single stage.
82
+ """
83
+
84
+ def __init__(
85
+ self,
86
+ dag: ProvenanceDAG,
87
+ config: Optional[QuorumGuardConfig] = None,
88
+ budget_pool: Optional[PriorityBudgetPool] = None,
89
+ on_vllm_priority_update: Optional[Callable[[str, int], None]] = None,
90
+ ) -> None:
91
+ self.dag = dag
92
+ self.config = config or QuorumGuardConfig()
93
+ self.budget_pool = budget_pool
94
+ self.on_vllm_priority_update = on_vllm_priority_update
95
+
96
+ def evaluate_asynchronous_pool(
97
+ self,
98
+ pool_votes: Sequence[AgentVote],
99
+ ) -> StageCommitResult:
100
+ if not pool_votes:
101
+ raise ValueError("pool_votes must be non-empty")
102
+
103
+ n_total = len(pool_votes)
104
+ cfg = self.config
105
+ min_roots = cfg.min_independent_roots if n_total >= 6 else max(2, cfg.min_independent_roots - 1)
106
+ eff_tau = cfg.tau_effective_quorum if n_total >= 6 else max(1.50, cfg.tau_effective_quorum * 0.70)
107
+
108
+ dyn_arrival: Dict[str, float] = {v.agent_id: v.arrival_time_s for v in pool_votes}
109
+ vote_map: Dict[str, AgentVote] = {v.agent_id: v for v in pool_votes}
110
+ observed_ids: List[str] = []
111
+ boost_triggered = False
112
+ boosted_ids: List[str] = []
113
+ early_closed = False
114
+ commit_claim = ""
115
+ commit_time = 0.0
116
+ commit_weight = 0.0
117
+ commit_roots = 0
118
+
119
+ while len(observed_ids) < n_total:
120
+ remaining = [aid for aid in dyn_arrival if aid not in observed_ids]
121
+ next_aid = min(remaining, key=lambda aid: dyn_arrival[aid])
122
+ t_now = dyn_arrival[next_aid]
123
+ observed_ids.append(next_aid)
124
+
125
+ weighted_tuples = [
126
+ (
127
+ aid,
128
+ vote_map[aid].claim,
129
+ compute_epistemic_weight(vote_map[aid].signals),
130
+ )
131
+ for aid in observed_ids
132
+ ]
133
+ claim_weights, claim_roots = self.dag.compute_effective_support(weighted_tuples)
134
+ ranked = sorted(claim_weights.items(), key=lambda kv: kv[1], reverse=True)
135
+ lead_claim, lead_w = ranked[0]
136
+ runner_w = ranked[1][1] if len(ranked) > 1 else 0.0
137
+ lead_r = claim_roots[lead_claim]
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:
157
+ commit_claim = lead_claim
158
+ commit_time = t_now
159
+ commit_weight = lead_w
160
+ commit_roots = lead_r
161
+ early_closed = (len(observed_ids) < n_total)
162
+ break
163
+
164
+ if (not boost_triggered) and len(observed_ids) >= cfg.dissent_trigger_min_arrivals:
165
+ boost_triggered = True
166
+ in_flight_verifiers = [
167
+ aid
168
+ for aid in remaining
169
+ if aid != next_aid and vote_map[aid].is_deep_verifier and dyn_arrival[aid] > t_now
170
+ ]
171
+ in_flight_verifiers.sort(key=lambda aid: dyn_arrival[aid])
172
+ desired = min(cfg.max_boost_slots_per_stage, len(in_flight_verifiers))
173
+ granted = self.budget_pool.try_acquire(desired) if self.budget_pool else desired
174
+
175
+ for aid_boost in in_flight_verifiers[:granted]:
176
+ boosted_ids.append(aid_boost)
177
+ if self.on_vllm_priority_update is not None:
178
+ self.on_vllm_priority_update(aid_boost, VLLM_PRIORITY_DISSENT_BOOST)
179
+ floor_t = t_now + 0.45 * vote_map[aid_boost].irreducible_exec_floor_s
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:
193
+ self.budget_pool.on_stage_complete()
194
+
195
+ return StageCommitResult(
196
+ committed_claim=commit_claim,
197
+ commit_time_s=round(commit_time, 5),
198
+ agents_observed=len(observed_ids),
199
+ effective_quorum_weight=round(commit_weight, 5),
200
+ independent_roots=commit_roots,
201
+ dissent_boost_triggered=boost_triggered,
202
+ boosted_agent_ids=tuple(boosted_ids),
203
+ early_closed=early_closed,
204
+ )