@bhanquier/chorus

Status: Research prototype (v0.4.0). Suitable for experiments and demos. Production use requires Phase 4 (security, persistence, NAT traversal).

Federated multi-agent debate system with P2P networking and MCP support.

What is this?

Chorus enables AI agents on different machines to debate together and reach consensus through a structured protocol. Agents are peers—no central orchestrator.

Key features:

• P2P networking via libp2p + GossipSub
• 3-phase debate: Proposals → Critiques → Votes
• Quadratic voting to prevent vote manipulation
• Multi-dimensional reputation tracking
• Apache AGE graph for consensus analysis
• MCP bridge for remote agents

Installation

npm install @bhanquier/chorus

Quick Start

Single-Node Debate

import { Debate } from '@ds9/chorus';
import { ClaudeAdapter, OllamaAdapter } from '@ds9/chorus/agents';
import { AGEClient } from '@ds9/chorus/graph';

// Setup agents
const agents = [
  new ClaudeAdapter({ apiKey: process.env.ANTHROPIC_API_KEY }),
  new OllamaAdapter({ model: 'qwen2.5:3b' })
];

// Setup graph storage
const ageClient = new AGEClient({
  host: 'localhost',
  database: 'postgres',
  graphName: 'debates'
});

// Run debate
const debate = new Debate(agents, ageClient);
const result = await debate.start({
  topic: 'What architecture should we use?',
  context: { scale: 'medium', complexity: 'high' },
  threshold: 0.6
});

console.log(result.consensus); // { reached: true, proposal: {...} }

Federated P2P Debate

import { P2PNode, FederatedDebate } from '@ds9/chorus/network';
import { OllamaAdapter, MCPBridgeAdapter } from '@ds9/chorus/agents';

// Setup P2P node
const node = new P2PNode({
  nodeId: 'my-node',
  listenAddrs: ['/ip4/0.0.0.0/tcp/9000'],
  bootstrapPeers: ['/ip4/bootstrap-ip/tcp/9000/p2p/bootstrap-peer-id']
});

await node.start();

// Setup local agents
const localAgents = [
  new OllamaAdapter({ model: 'qwen2.5:3b' })
];

// Setup federated debate
const debate = new FederatedDebate({
  p2pNode: node,
  ageClient: ageClient,
  localAgents: localAgents
});

// Start debate (will sync with other nodes)
const result = await debate.start({
  topic: 'Should we migrate to TypeScript?',
  context: { codebase_size: 'large' },
  threshold: 0.5
});

Architecture

┌─────────────────────────────────────────────────────┐
│              Federated Debate Network                │
│                                                      │
│  ┌──────────┐         P2P          ┌──────────┐    │
│  │  Node 1  │◄──────GossipSub──────►│  Node 2  │    │
│  │          │                        │          │    │
│  │ Agent A  │                        │ Agent C  │    │
│  │ Agent B  │                        │ Agent D  │    │
│  └────┬─────┘                        └────┬─────┘    │
│       │                                    │          │
│       └────────────┬───────────────────────┘          │
│                    ▼                                  │
│            ┌───────────────┐                          │
│            │   AGE Graph   │                          │
│            │  (Consensus)  │                          │
│            └───────────────┘                          │
└─────────────────────────────────────────────────────┘
                     ▲
                     │ MCP Bridge
                     │
             ┌───────┴────────┐
             │  Remote Agent  │
             │   (via MCP)    │
             └────────────────┘

Features

Core Protocol

• 3-phase debate: Proposals → Critiques → Votes
• Quadratic voting: Cost = weight², prevents manipulation
• Reputation tracking: Multi-dimensional reputation vectors
• Consensus detection: Threshold-based consensus

P2P Networking

• libp2p v3 with GossipSub for reliable message propagation
• Bootstrap discovery for fast peer connection (2-3s)
• mDNS discovery for local network auto-detection
• Federated orchestration: Debates across multiple nodes

Agent Adapters

Built-in support for:

• Claude (Anthropic API)
• OpenAI (GPT-4, etc.)
• Ollama (Local LLMs)
• Gemini (Google AI)
• Groq (Fast inference)
• Mistral
• MCP Bridge (Any agent via Model Context Protocol)

Graph Storage

• Apache AGE (PostgreSQL extension) for graph queries
• Event sourcing for full debate history
• Cypher queries for complex consensus analysis

Examples

See examples/ directory:

• federated-debate-test.ts - Multi-node debate with 3 agents
• mcp-bridge-test.ts - Local + remote agent collaboration
• p2p-bootstrap-test.ts - P2P mesh formation

API Reference

Exports

// Core
import { Debate } from '@ds9/chorus';

// Agents
import { ClaudeAdapter, OllamaAdapter, MCPBridgeAdapter } from '@ds9/chorus/agents';

// P2P Network
import { P2PNode, FederatedDebate, MessageType } from '@ds9/chorus/network';

// Graph
import { AGEClient } from '@ds9/chorus/graph';

// Voting
import { QuadraticVoting } from '@ds9/chorus/voting';

// Reputation
import { ReputationTracker } from '@ds9/chorus/reputation';

Configuration

P2PNode

interface P2PConfig {
  nodeId: string;                    // Unique node identifier
  listenAddrs: string[];             // Multiaddrs to listen on
  bootstrapPeers?: string[];         // Bootstrap node multiaddrs
  mdns?: boolean;                    // Enable mDNS discovery (default: true)
  debateTopic?: string;              // GossipSub topic (default: 'chorus-debates')
  allowlist?: string[];              // Allowed peer IDs
  denylist?: string[];               // Blocked peer IDs
}

FederatedDebate

interface FederatedDebateConfig {
  p2pNode: IP2PNode;                 // P2P node instance
  ageClient: AGEClient;              // Graph storage client
  localAgents: AgentAdapter[];       // Local agents
  timeout?: number;                  // Debate timeout (default: 5 min)
}

Reputation System

Multi-dimensional reputation (all dimensions 0-1):

• Correctness: Frequency of correct proposals
• Novelty: Original proposals that gain acceptance
• Synthesis: Successful conflict resolutions
• Humility: Accepts critiques, revises opinions
• Domain: Expertise in specific domains

Quadratic Voting

Vote cost increases quadratically to prevent wealthy agents from dominating:

| Weight | Cost | Influence | |--------|------|-----------| | 1 | 1 | Linear | | 2 | 4 | Sublinear | | 3 | 9 | Sublinear | | 5 | 25 | Expensive | | 10 | 100 | Very expensive |

Voting budget = 100 × reputation_multiplier (50-200 credits)

Requirements

• Node.js 18+
• PostgreSQL 13+ with AGE extension
• Network ports open for P2P (if using federated mode)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

# Run examples
pnpm example:mock    # Mock agents
pnpm example:real    # Real LLM agents

Roadmap

Phase 1: Core ✅ COMPLETE

• Core debate logic
• AGE client (PostgreSQL + AGE)
• Quadratic voting
• Multi-dimensional reputation
• Agent adapters (Claude, Ollama, etc.)
• MCP integration

Phase 2: Consensus Improvements ✅ COMPLETE

• Groq support
• Consensus normalization fix
• Bug fixes + deployment

Phase 3: P2P Network ✅ COMPLETE (v0.4.0)

• libp2p v3 + GossipSub
• Federated debate orchestration
• MCP bridge adapter
• E2E tests passing

Phase 4: Security (Future)

• Message signing (Ed25519)
• Peer verification
• NAT traversal
• Debate persistence

Status

v0.4.0 - Phase 3 complete. Research-ready with limitations:

Working:

• ✅ P2P networking (libp2p + GossipSub)
• ✅ Federated debate orchestration
• ✅ MCP bridge adapter
• ✅ E2E tests passing

Limitations (acceptable for research/demos):

• Message signatures not implemented (placeholder)
• Peer verification not enforced
• No NAT traversal (local network only)
• Debates stored in-memory (not persisted)

Production use requires Phase 4 (security + scalability).

License

MIT

Contributing

Research project. Contributions welcome via issues and PRs.