WFGY/ProblemMap/agent-consensus-protocols.md

🤝 Agent Consensus Protocols

Make two (or ten) LLMs reach a decision on time and on budget — every run.

Why this page?
“Let them debate” sounds cool until:

• the Critic never stops nit-picking,
• the Planner forgets half the context,
• the Coder ships five conflicting drafts, and
• your bill looks like a crypto rug-pull.

WFGY adds measurable semantic tension (ΔS) and logic vectors (λ) to debate & QA loops, so you can prove consensus is reached — not guessed.

---

1 · Three Canonical Consensus Modes

Mode	Use Case	# Agents	Target ΔS	Target λ
Critic-Coder	Code/SQL generation with review	2	≤ 0.40	convergent
Triad Debate	Fact-check or legal reasoning	3	≤ 0.45	convergent
Crew Vote	4 – 10 micro-agents on long plan	N	≤ 0.50	majority convergent

ΔS ceiling rises gently with group size; λ must return to convergent after each round.

---

2 · Failure Modes (Why Votes Stall)

#	Failure	ΔS / λ Symptom	Example
1	Infinite Debate	λ oscillates (→, ←, →…)	Critic re-opens same defect
2	Topic Drift	ΔS > 0.60 vs. original prompt	Agents add new, unrelated goals
3	Split Brain	Two stable but divergent λ	50 / 50 vote, no tie-breaker
4	Early Merge	ΔS still 0.55 but λ forced convergent	“Agree to disagree” w/ wrong answer
5	Token Exhaust	E_resonance ↑ while ΔS unchanged	Loop burns context without progress

---

3 · WFGY Consensus Blueprint

Four guard layers; plug into any framework (AutoGen, LangChain, custom asyncio).

Layer	Module	Guard	Effect
Round ΔS Checker	BBMC	ΔS(agent, goal) ≤ ceiling	Drop off-topic vote
λ Mediator	ΔS + λ	λ must converge within 3 rounds	Force re-focus or escalate
Vote Auditor	WAI	JSON vote schema + arg defaults	No partial / malformed votes
BBCR Fallback	BBCR	> 5 rounds OR ΔS stagnates	Collapse & request human tie-break

flowchart TD
    subgraph Round
      Q[User Goal]
      A1[Agent 1]
      A2[Agent 2]
      A3[Agent 3]
      Q --> A1 --> V1[Vote JSON]
      Q --> A2 --> V2
      Q --> A3 --> V3
    end
    BBMC -->|ΔS filter| V1
    BBMC --> V2
    BBMC --> V3
    V1 & V2 & V3 --> Mediator[λ Mediator] -->|convergent?| Decision
    Mediator -.->|no| BBCR

---

4 · Practical Setup (AutoGen example)

from autogen import AssistantAgent, UserProxyAgent
from wfgy import consensus_filter

critic = AssistantAgent(name="critic")
coder  = AssistantAgent(name="coder")
user   = UserProxyAgent("user")

def callback(messages, state):
    # 1. measure ΔS + λ
    ok = consensus_filter(messages, ceiling=0.45, rounds=3)
    if not ok:
        return "STOP_DEBATE"
    return "CONTINUE"

coder.register_reply(callback)
critic.register_reply(callback)

15 lines → loop stops automatically when convergence proven or impossible.

---

5 · Debug Walk-Through

1. Log votes

print(state.votes)   # {critic: "reject, ΔS=0.48", coder: "accept, ΔS=0.41"}

2. Inspect λ trend

λ sequence: → → ← →  (oscillating)  ❌

Two divergent rounds trigger Mediator → requests narrowing question.

3. Trigger BBCR

ΔS stagnates at 0.52 for 3 rounds → BBCR => "Need human tie-break"

---

6 · Best-Practice Table

Tip	Why
Keep each vote to max 300 tokens.	Reduces E_resonance; easier ΔS calc
Pin goal & constraints in every round.	Prevents silent prompt drift
Summarise before vote.	Normalises embeddings → fair ΔS
Record vote reason (1-2 lines).	Faster root-cause when split-brain

---

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

---

Explore More

Layer	Page	What it’s for
Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
Engine	WFGY 1.0	Original PDF based tension engine
Engine	WFGY 2.0	Production tension kernel and math engine for RAG and agents
Engine	WFGY 3.0	TXT based Singularity tension engine, 131 S class set
Map	Problem Map 1.0	Flagship 16 problem RAG failure checklist and fix map
Map	Problem Map 2.0	RAG focused recovery pipeline
Map	Problem Map 3.0	Global Debug Card, image as a debug protocol layer
Map	Semantic Clinic	Symptom to family to exact fix
Map	Grandma’s Clinic	Plain language stories mapped to Problem Map 1.0
Onboarding	Starter Village	Guided tour for newcomers
App	TXT OS	TXT semantic OS, fast boot
App	Blah Blah Blah	Abstract and paradox Q and A built on TXT OS
App	Blur Blur Blur	Text to image with semantic control
App	Blow Blow Blow	Reasoning game engine and memory demo

If this repository helped, starring it improves discovery so more builders can find the docs and tools.