forumkit 0.1.0

Multi-agent debate framework with structured consensus scoring and dissent tracking

forumkit

The only Python multi-agent framework with a structured debate protocol: fan-out → challenge → rebuttal → consensus scoring.

from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole

class MyAnalyst(ResearcherBase):
    async def analyze(self, data):
        # Independent analysis
        return {"position": "...", "confidence": 0.8}

    async def respond_to_challenge(self, challenge, context):
        # Defend your position
        return "Here's why I disagree..."

class MyForum(ForumModeratorBase):
    def _synthesize(self, analyses, consensus, data):
        # Domain-specific consensus logic
        if consensus.agreement_pct >= 66:
            return "accepted", {"action": "approve"}
        return "conditional", {"action": "review"}

# Run a debate
forum = MyForum(config, researchers=[analyst1, analyst2, analyst3])
result = await forum.run_debate_round({"question": "Is X good?"})

print(f"Consensus: {result.consensus.agreement_pct}% agree")
print(f"Dissent: {result.consensus.strongest_dissent}")
print(f"Anomaly?: {result.consensus.unanimous_anomaly}")  # Detects groupthink

Why forumkit?

The problem: CrewAI, PraisonAI, AutoGen, and others assume agents reach consensus by averaging opinions. In reality, minority views often reveal blind spots.

The solution: forumkit enforces dissent:

• Every agent analyzes independently
• Agents actively challenge each other's positions
• Minority opinions are surfaced, not discarded
• Suspicious unanimity is flagged (unanimous_anomaly detection)
• Outcomes are tied to consensus strength, not just majority vote

The result: Better decisions with traceable dissent.

Quick Start

Install

pip install forumkit

5-minute example

import asyncio
from forumkit import ForumModeratorBase, ResearcherBase, AgentConfig, AgentRole, PersonaContext

class Analyst(ResearcherBase):
    async def analyze(self, data):
        # Your LLM call here
        return {
            "persona_id": self.persona.persona_id,
            "position": f"Analysis from {self.persona.name}",
            "confidence": 0.75
        }

    async def respond_to_challenge(self, challenge, context):
        return "I maintain my position because..."

class DebateBoard(ForumModeratorBase):
    def _synthesize(self, analyses, consensus, data):
        synthesis = f"Consensus at {consensus.agreement_pct:.0f}%"
        outcome = "approved" if consensus.agreement_pct >= 50 else "rejected"
        return synthesis, outcome, None

async def main():
    config = AgentConfig(
        agent_id="board-1", team_id=1, role=AgentRole.HEAD,
        model_alias="gpt-4"
    )

    # Create 3 analysts with different personas
    analysts = [
        Analyst(AgentConfig(...), PersonaContext(
            persona_id="p1", name="Optimist", system_prompt="..."
        )),
        # ... more analysts
    ]

    board = DebateBoard(config, analysts)
    result = await board.run_debate_round({"question": "Approve proposal X?"})

    print(f"Outcome: {result.outcome}")
    print(f"Agreement: {result.consensus.agreement_pct}%")
    print(f"Dissent: {result.consensus.dissent_count} voices disagree")
    print(f"Anomaly: {result.consensus.unanimous_anomaly}")

asyncio.run(main())

Concepts

The Forum Protocol

1. Fan-out — Every analyst independently evaluates the question
2. Challenge — Analysts see each other's views and attack weak points
3. Rebuttal — Each analyst responds to challenges
4. Score — Consensus metrics computed: agreement %, confidence, dissent count
5. Synthesize — Domain-specific outcome logic applied

Key Types

• BaseAgent — Foundation for all agents. Role-gated: HEAD can delegate to children, JUNIOR cannot call LLM
• ResearcherBase — Expert with persona, implements analyze() and respond_to_challenge()
• ForumModeratorBase — Orchestrates the debate, computes consensus, applies domain logic
• ConsensusScore — Result includes agreement_pct, dissent_count, unanimous_anomaly (detects suspicious unanimity)

Memory Backends

forumkit supports three memory types:

Backend	Use	Backend
Working	In-session cache	Redis (TTL)
Episodic	Long-term experience	PostgreSQL
Semantic	Vector embeddings	Qdrant

All are optional. Use the facade:

from forumkit.memory import MemoryManager

memory = MemoryManager(
    redis_url="redis://localhost:6379",
    pg_url="postgresql://localhost/mydb",
    qdrant_url="http://localhost:6333"
)

await memory.initialize()
# Use: memory.working.set(), memory.episodic.store(), memory.semantic.search()

Docs

• API Reference — All public types and methods
• Concepts — Architecture deep-dive
• Examples — Working code samples

Testing

pytest tests/unit/ -v
pytest tests/integration/ -v  # Requires Docker (Redis, PostgreSQL)

Security

forumkit includes prompt injection defense:

from forumkit.security import sanitize_for_prompt

clean = sanitize_for_prompt(user_input)
# Applies: NFKC normalize, strip BiDi/control chars, remove injection patterns

Status

v0.1.0 — Alpha. API is stable; docs are being refined. Not yet open source (private beta).

License

MIT

Contact

Issues: GitHub Issues Questions: [e-mail]