Metadata-Version: 2.4
Name: council-engine
Version: 0.3.0
Summary: A structured deliberation protocol across diverse AI models
Author-email: Amith Mathew <amith@councilengine.dev>
License-Expression: MIT
Project-URL: Homepage, https://councilengine.dev
Project-URL: Repository, https://github.com/amithmathew/council-engine
Project-URL: Documentation, https://councilengine.dev/architecture
Keywords: ai,llm,multi-model,deliberation,debate,heterogeneous,protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-genai>=1.64.0
Requires-Dist: openai>=1.0.0
Requires-Dist: anthropic>=0.39.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: rich>=13.0.0
Requires-Dist: prompt-toolkit>=3.0.0
Dynamic: license-file

# 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](https://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

```bash
pip install council-engine
```

All providers are included. No optional extras needed.

## Setup

Run the guided setup:

```bash
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:

```toml
[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

```bash
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

```bash
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

```bash
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

```bash
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](https://councilengine.dev/architecture).

## 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
