parliament-of-owls 0.1.0

Query multiple LLMs and deep research APIs in parallel, post results to GitHub Issues

Parliament of Owls

Query multiple LLMs and deep research APIs in parallel.
Post each response as a comment on a GitHub Issue.

---

Built on Simon Willison's llm for standard model access, with direct API integrations for deep research endpoints. Supports dozens of free models via OpenRouter.

Install

# From source
pip install -e .

# Or globally with pipx (recommended)
pipx install .

Quick Start

# 1. Configure your council (interactive picker)
owl council

# 2. Ask the council
owl ask "What are the tradeoffs between Redis and Memcached for session storage?"

# 3. Read from a file
owl ask -f research_question.md

# 4. Pipe from stdin
echo "Explain quantum computing" | owl ask

# 5. Post to a GitHub issue
owl ask "..." --gh owner/repo
owl ask "..." --gh owner/repo --issue 42

Setting Up Models

Standard Models (via llm)

Install llm plugins and set their API keys:

# OpenAI
llm install llm-openai          # included by default with llm
llm keys set openai              # paste your OpenAI API key

# Anthropic (Claude)
llm install llm-anthropic
llm keys set anthropic           # paste your Anthropic API key

# Google Gemini
llm install llm-gemini
llm keys set gemini              # paste your Google AI API key

# Mistral
llm install llm-mistral
llm keys set mistral             # paste your Mistral API key

# Grok (xAI)
llm install llm-grok
llm keys set grok                # paste your xAI API key

# DeepSeek
llm install llm-deepseek
llm keys set deepseek            # paste your DeepSeek API key

# Cohere
llm install llm-command-r
llm keys set cohere              # paste your Cohere API key

# OpenRouter (dozens of models, many free — no credit card needed)
llm install llm-openrouter
llm keys set openrouter          # paste your OpenRouter API key

# Local models via Ollama
llm install llm-ollama
# No key needed — just have Ollama running

Verify your installed models:

llm models                       # list all available models

Keys are stored in ~/Library/Application Support/io.datasette.llm/keys.json (macOS) or ~/.config/io.datasette.llm/keys.json (Linux).

You can also pass keys via environment variables (e.g. OPENAI_API_KEY) or inline with --key.

See the full llm plugin directory for more providers.

Free Models via OpenRouter

Sign up at openrouter.ai (no credit card required) and get a free API key. Many powerful models are completely free:

• Claude 4.6 Opus / Claude 4.5 Sonnet (Anthropic)
• GPT-5 Nano / GPT-4o Mini (OpenAI)
• Gemini 3 Flash / Gemma 3 27B (Google)
• Grok 4.1 Fast (xAI)
• DeepSeek V3.2 (DeepSeek)
• GLM-4.5 Air (Z.ai)
• Llama 3.3 70B (Meta)
• Mistral Small 3.1 (Mistral)
• Many more — run llm models | grep ":free" to see all

Rate limits: ~20 req/min, ~200 req/day per free model. Owl staggers requests to stay within limits.

Deep Research APIs

Deep research models use direct API calls (not llm plugins). Set their keys as environment variables:

export OPENAI_API_KEY=sk-...        # o3-deep-research, o4-mini-deep-research
export PERPLEXITY_API_KEY=pplx-...  # sonar-deep-research
export GOOGLE_API_KEY=AI...         # Gemini Deep Research Agent
export DEEPSEEK_API_KEY=sk-...      # deepseek-reasoner
export XAI_API_KEY=xai-...          # Grok agentic search

Add these to your ~/.zshrc or ~/.bashrc to persist them.

GitHub Integration

For posting results to GitHub Issues, owl uses your gh CLI auth or a GITHUB_TOKEN:

# Option A: gh CLI (recommended)
gh auth login

# Option B: environment variable
export GITHUB_TOKEN=ghp_...

Commands

owl ask "prompt"                          # Query all council members
owl ask -f prompt.md                      # Read prompt from file
cat prompt.txt | owl ask                  # Read from stdin
owl ask "prompt" --gh owner/repo          # Create new issue with responses
owl ask "prompt" --gh owner/repo --issue 42  # Post to existing issue
owl council                               # Interactive TUI to select council members
owl council-list                          # Show current council
owl models                                # Show all available models

Council Configuration

Run owl council to open the interactive selector:

🦉 Parliament of Owls — Select Your Council

 #   Model                      Source        Description
     Standard Models (via llm)
 1  ☑ gpt-5                     llm
 2  ☑ claude-sonnet-4.6         llm
 3  ☐ gemini-2.5-pro            llm
     Deep Research
 4  ☑ o3-deep-research          openai-deep   OpenAI Deep Research
 5  ☑ sonar-deep-research       perplexity    Perplexity Deep Research
 6  ☐ gemini-deep-research      google-deep   Gemini Deep Research Agent
 7  ☐ deepseek-reasoner         deepseek      DeepSeek Reasoner
 8  ☐ grok-agentic              xai           Grok 4.1 agentic search

Enter number to toggle, a=all, n=none, s=save, q=quit:

Saved to ~/.owl/config.yaml.

How Deep Research Works

Each provider implements deep research differently:

Provider	What Happens	API
OpenAI	Separate model (o3-deep-research) that searches the web and synthesizes reports	Responses API
Perplexity	Separate model (sonar-deep-research) with multi-step retrieval and citations	/chat/completions
Google Gemini	Async agent that plans, searches, reads, and reasons (can take minutes)	Interactions API
DeepSeek	Reasoning model with chain-of-thought (deepseek-reasoner)	/chat/completions
xAI Grok	Grok 4.1 with agentic web + X search and thinking mode	Chat Completions + tools

Security

• API keys are stored via llm's key management or environment variables — never in the owl config file
• The ~/.owl/config.yaml only stores model names and sources, no secrets
• GitHub tokens are read from gh CLI auth or GITHUB_TOKEN env var
• All API calls use HTTPS
• Deep research providers use 5-minute timeouts with retry on transient failures

Development

git clone https://github.com/joelio/owl.git
cd owl
pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-owl)
3. Make your changes with tests
4. Ensure ruff check and pytest pass
5. Open a PR

License

MIT — see LICENSE.