Skip to content
This repository was archived by the owner on Apr 6, 2026. It is now read-only.

README.md

Latest commit

 

History

History
230 lines (156 loc) · 7.74 KB

README.md

File metadata and controls

230 lines (156 loc) · 7.74 KB
Raw

🏛️ Council AI

Intelligent Advisory Council System — Get advice from a council of AI-powered personas with diverse perspectives and expertise.

Python 3.11+ License: MIT Open in GitHub Codespaces

🚀 Getting Started (5 Minutes)

Option 1: Local LLM (Free, No API Key)

Use a local LLM with LM Studio for cost-free, private consulting:

# 1. Download & start LM Studio, load any model

# 2. Install and run Council AI
pip install -e ".[dev]"
council init          # Detects LM Studio automatically
council run "Should we redesign our API?"

Option 2: Cloud LLM (OpenAI, Anthropic, Gemini)

# Install with your provider
pip install -e ".[anthropic]"    # or [openai], [gemini]

# Set API key
export ANTHROPIC_API_KEY="your-key"

# Run
council init
council run "Your question here"

Need More Guidance?

→ GETTING_STARTED.md — Detailed 5-10 minute setup guide for all platforms

→ REPOSITORY_STRUCTURE.md — Understand council-ai vs council-ai-personal

✨ Features

  • 🎭 14 Built-in Personas — Advisors, red team, specialists with diverse perspectives
  • 🌐 15 Domain Presets — Business, research, engineering, creative, career, legal, medical, and more
  • 🔧 Fully Customizable — Create personas, adjust traits, modify behavior
  • 🤖 Multi-Provider — OpenAI, Anthropic, Google Gemini, Ollama, LM Studio, or custom endpoints
  • 💬 Multiple Modes — Individual, synthesis, debate, vote, sequential, or pattern-based
  • 🔍 Web Search — Live data via Tavily, Serper, or Google Custom Search
  • 🧠 Extended Thinking — Reasoning mode for complex analysis
  • 📝 Session Management — Track and resume consultations
  • 🧭 Web UI — Modern React/TypeScript interface with Dieter Rams design
  • 🎯 Onboarding Wizard — Guided 6-step setup for first-time users
  • 🔊 Text-to-Speech — Voice responses via ElevenLabs or OpenAI
  • 📖 Full API — Use Council AI in your code

📚 Documentation

Need Link
Setup Guide GETTING_STARTED.md
Troubleshooting TROUBLESHOOTING.md
Common Tasks COMMON_TASKS.md
Using Web UI WEB_APP.md
Configuration CONFIGURATION.md
Web Search WEB_SEARCH_AND_REASONING.md
Personas & Domains PERSONAS_AND_DOMAINS.md
Python API API_REFERENCE.md
Contributing CONTRIBUTING.md
All Docs documentation/README.md

📦 Installation & Configuration

Full step-by-step setup → GETTING_STARTED.md

Quick Version

# Clone repository
git clone https://github.com/doronpers/council-ai.git
cd council-ai

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # macOS/Linux: source venv/bin/activate; Windows: .\venv\Scripts\activate.bat

# Install package
pip install -e ".[dev]"

# Run setup wizard (guides you through API key configuration)
council init

# Launch web UI
python launch-council.py --web
# OR launch CLI
council run

Supported API Providers: OpenAI, Anthropic, Google Gemini, Ollama, LM Studio, or custom endpoints.

See REPOSITORY_STRUCTURE.md to understand which repository to use (council-ai vs council-ai-personal).

🎯 Usage Examples

Web UI:

python launch-council.py --web
# Open http://localhost:8000 → Complete onboarding wizard

CLI:

# Interactive session
council run

# One-shot consultation
council run --query "Should we pivot our business model?"

# With specific domain & personas
council run --domain startup --model gpt-4

Python API:

from council_ai import Council

council = Council.for_domain("business", api_key="your-key")
result = council.consult("Should we expand to Europe?")
print(result.synthesis)

For comprehensive examples, see COMMON_TASKS.md and examples/.

🏗️ Persona Architecture (v2.0+)

Council AI uses archetypes — reusable personality templates — combined with specialization for flexible persona management.

Archetypes (Public)

Generic trait-based templates in src/council_ai/personas/archetypes/:

  • quality_advocate — Design philosophy & best practices
  • security_specialist — Adversarial thinking & risk
  • strategic_leader — Long-term strategy
  • risk_analyst — Probabilistic reasoning
  • cognitive_scientist — Human behavior & UX

Specialized Personas (Personal)

In council-ai-personal (private repo, sibling directory):

  • Real-name personas inheriting from archetypes
  • Private configurations
  • Personal customizations

14 Built-in Personas across 3 councils:

  • Advisory Council: Dieter Rams, Daniel Kahneman, Martin Dempsey, Julian Treasure
  • Red Team: Pablo Holman, Nassim Taleb, Andy Grove, and others
  • Specialists: Audio, compliance, fraud, and domain experts

15 Domain Presets: Business, startup, coding, creative, career, audio, medical, legal, and more.

Create custom personas or modify weights to fit your needs.

Reference: PERSONAS_AND_DOMAINS.md

Advanced Features

Feature Documentation
Web Search WEB_SEARCH_AND_REASONING.md
Context Injection CONTEXT_INJECTION_GUIDE.md
LLM Response Review REVIEWER_SETUP.md
Configuration CONFIGURATION.md
Error Handling ERROR_HANDLING.md
Python API API_REFERENCE.md

Support

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=council_ai

# Run specific test
pytest tests/unit/test_core.py

See CONTRIBUTING.md for code quality and testing standards.

License

MIT License — see LICENSE file.

Built with ❤️ for better decisions.