council-engine 0.3.0

A structured deliberation protocol across diverse AI models

Council Engine

A structured deliberation protocol across diverse AI models.

Single-model outputs are fluent, fast, and often wrong in the same direction. Council runs a bounded deliberation across different models, processes critique explicitly, and returns a decision you can inspect. The point is not more text. It is better judgment.

Website: councilengine.dev

How it works

Council orchestrates a bounded 3-stage protocol:

1. Proposals — Multiple models respond to the same task independently. Each produces a clear position.
2. Critique — Models review each other through a constrained vocabulary: challenge, alternative, refinement, and question. Silence is treated as approval.
3. Resolution — A lead model classifies the disagreement and produces one of four adaptive outcomes:
   • Recommendation — Council agrees; single clear guidance.
   • Alternatives — Real tradeoffs remain; presented with decision rules.
   • Question — A missing fact is decisive; outputs a clarifying question.
   • Investigate — Evidence is needed; outputs an investigation plan.

Why heterogeneous models

Research shows that multi-agent debate improves reasoning when the agents are actually different. Same-model personas tend to converge on the same errors. Council uses genuinely different foundation models — not different prompts to the same model — because diverse architectures surface conflicting assumptions and different failure modes.

Supported providers

Provider	Auth	Web search
Gemini (Google)	API key (AI Studio or Vertex AI) or ADC	Yes (Google Search)
ChatGPT (OpenAI)	API key	Yes (web_search_preview)
Claude (Anthropic)	API key	No
Ollama (local)	None — runs locally	No

Install

pip install council-engine

All providers are included. No optional extras needed.

Setup

Run the guided setup:

council init

This creates ~/.council/config.toml with your API keys and validates each connection. You need at least one provider configured; for multi-model deliberation, configure two or more.

Manual configuration

Edit ~/.council/config.toml directly:

[providers.gemini]
api_key = "your-google-api-key"       # from https://aistudio.google.com/apikey

[providers.chatgpt]
api_key = "your-openai-api-key"       # from https://platform.openai.com/api-keys

[providers.claude]
api_key = "your-anthropic-api-key"    # from https://console.anthropic.com/settings/keys

[providers.ollama]
host = "http://localhost:11434"       # ollama serve && ollama pull <model>
model = "llama3.1:8b"                 # browse models: https://ollama.com/library

Environment variables override the config file: COUNCIL_GEMINI_API_KEY, COUNCIL_OPENAI_API_KEY, COUNCIL_CLAUDE_API_KEY, COUNCIL_OLLAMA_HOST.

Usage

Interactive REPL

council

Launches a persistent session with tab completion, slash commands, and multi-model deliberation by default. Type a question and press Enter to convene the full council.

• @gemini <msg> — send to a single model
• /attach <file> — attach files for the council to read
• /discuss <prompt> — reconvene after follow-up
• /new — start a new conversation
• /resume <name> — resume a past conversation

Structured deliberation

council discuss --models gemini,claude "Should we use event sourcing or CRUD for our collaborative editor?"

Runs the full 3-stage protocol (Proposals → Critique → Resolution) and outputs the result.

Quick query

council ask --model chatgpt "What are the tradeoffs of gRPC vs REST for internal services?"

Single-model query. Promote to a full conversation with council promote <name>.

Multi-model chat

council chat --models gemini,chatgpt,claude "my-conversation" "Your message here"

Architecture

Council is built with explicit boundaries and auditability:

• Event bus — orchestration decoupled from rendering; same protocol drives terminal UI, plain text, or custom consumers
• Persistent audit trail — every proposal, critique, and resolution stored in SQLite with full metadata
• Chair subsystem — sandboxed file operations with mediated reads (workspace-wide) and writes (council-output/ only)
• Provider abstraction — pluggable model backends with parallel execution via asyncio
• Two integration surfaces — interactive REPL for humans, CLI commands for automation and agent tooling

See the full architecture documentation.

Research

Council's design is informed by research on multi-model deliberation:

1. Du, Y. et al. 2023. Improving Factuality and Reasoning in Language Models through Multiagent Debate.
2. Understanding Agent Scaling in LLM-Based Multi-Agent Systems via Diversity. 2026.
3. If Multi-Agent Debate is the Answer, What is the Question? 2025.
4. Dipper: Diversity in Prompts for Producing Large Language Model Ensembles. 2024.
5. Zheng, et al. 2023. Persona prompting and factual task performance.

License

MIT