Getting started

Install

# pip
python -m pip install llmswap

# isolated CLI with uv
uv tool install llmswap

# Homebrew
brew tap llmswap/tap
brew install llmswap

The optional browser Arena requires the web extra:

python -m pip install "llmswap[web]"

Configure one provider

export OPENAI_API_KEY="your-key"
# or ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, XAI_API_KEY,
# COHERE_API_KEY, PERPLEXITY_API_KEY, SARVAM_API_KEY, or WATSONX_API_KEY

IBM watsonx also requires WATSONX_PROJECT_ID. Ollama does not use an API key, but its local server must be running and the configured model must be pulled.

Diagnose the installation

llmswap --version
llmswap doctor
llmswap providers

Use a real connectivity check only when a provider request is acceptable:

llmswap doctor --provider openai --live

doctor reports whether credentials exist but does not print their values.

Ask, chat, and synthesize

# One answer
llmswap --provider openai ask "Explain this contract in plain language"

# Interactive conversation
llmswap --provider openai chat

# Three independent drafts plus one judge request
llmswap --provider openai best \
  "Which rollout plan has the lowest operational risk?"

For automation-friendly Best Answer output:

llmswap --provider openai best "Assess this proposal" --format json

Compare in the Arena

llmswap web

Select models, run a comparison, and choose Create Best Answer to synthesize the responses already produced. This adds one judge request rather than regenerating candidates.

Python quick start

from llmswap import LLMClient

client = LLMClient(provider="openai", model="gpt-5.6")
response = client.query("Summarize the trade-offs in this decision")
print(response.content)

result = client.best_answer("Which option is most robust and why?")
print(result.best_answer)
print(result.disagreements)
print(result.cautions)

Keys in `~/.env`

Ordinary CLI commands read exported environment variables. Load a key file into your current shell before running them:

set -a
source ~/.env
set +a

Best Answer and doctor additionally discover .env in the current directory and ~/.env without overriding exported values.