council-engine 0.3.0__tar.gz

council_engine-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amith Mathew
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

council_engine-0.3.0/PKG-INFO

@@ -0,0 +1,164 @@
+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

council_engine-0.3.0/README.md

@@ -0,0 +1,135 @@
+# 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

council_engine-0.3.0/council/__init__.py

@@ -0,0 +1,6 @@
+"""Council — Multi-model brainstorm CLI."""
+
+from council.cli import main
+
+__all__ = ["main"]
+__version__ = "0.2.0"