llm-router

What this skill does

# LLM Router

## Overview

Route AI requests to different LLM providers using SwiftOpenAI-CLI's agent mode. This skill automatically configures the CLI to use the requested provider (OpenAI, Grok, Groq, DeepSeek, or OpenRouter), ensures the tool is installed and up-to-date, and executes one-shot agentic tasks.

## Core Workflow

When a user requests to use a specific LLM provider (e.g., "use grok to explain quantum computing"), follow this workflow:

### Step 1: Ensure SwiftOpenAI-CLI is Ready

Check if SwiftOpenAI-CLI is installed and up-to-date:

```bash
scripts/check_install_cli.sh
```

This script will:
- Check if `swiftopenai` is installed
- Verify the version (minimum 1.4.4)
- Install or update if necessary
- Report the current installation status

### Step 2: Configure the Provider

Based on the user's request, identify the target provider and configure SwiftOpenAI-CLI:

```bash
scripts/configure_provider.sh <provider> [model]
```

**Supported providers:**
- `openai` - OpenAI (GPT-4, GPT-5, etc.)
- `grok` - xAI Grok models
- `groq` - Groq (Llama, Mixtral, etc.)
- `deepseek` - DeepSeek models
- `openrouter` - OpenRouter (300+ models)

**Examples:**

```bash
# Configure for Grok
scripts/configure_provider.sh grok grok-4-0709

# Configure for Groq with Llama
scripts/configure_provider.sh groq llama-3.3-70b-versatile

# Configure for DeepSeek Reasoner
scripts/configure_provider.sh deepseek deepseek-reasoner

# Configure for OpenAI GPT-5
scripts/configure_provider.sh openai gpt-5
```

The script automatically:
- Sets the provider configuration
- Sets the appropriate base URL
- Sets the default model
- Provides guidance on API key configuration

### Step 3: Verify API Key

The configuration script automatically checks if an API key is set and will **stop with clear instructions** if no API key is found.

**If API key is missing:**

The script exits with error code 1 and displays:
- ⚠️ Warning that API key is not set
- Instructions for setting via environment variable
- Instructions for setting via config (persistent)

**Do not proceed to Step 4 if the configuration script fails due to missing API key.**

Instead, inform the user they need to set their API key first:

**Option 1 - Environment variable (session only):**
```bash
export XAI_API_KEY=xai-...           # for Grok
export GROQ_API_KEY=gsk_...          # for Groq
export DEEPSEEK_API_KEY=sk-...       # for DeepSeek
export OPENROUTER_API_KEY=sk-or-...  # for OpenRouter
export OPENAI_API_KEY=sk-...         # for OpenAI
```

**Option 2 - Config file (persistent):**
```bash
swiftopenai config set api-key <api-key-value>
```

After the user sets their API key, re-run the configuration script to verify.

### Step 4: Execute the Agentic Task

Run the user's request using agent mode:

```bash
swiftopenai agent "<user's question or task>"
```

**Agent mode features:**
- One-shot task execution
- Built-in tool calling
- MCP (Model Context Protocol) integration support
- Conversation memory with session IDs
- Multiple output formats

**Examples:**

```bash
# Simple question
swiftopenai agent "What is quantum entanglement?"

# With specific model override
swiftopenai agent "Write a Python function" --model grok-3

# With session for conversation continuity
swiftopenai agent "Remember my name is Alice" --session-id chat-123
swiftopenai agent "What's my name?" --session-id chat-123

# With MCP tools (filesystem example)
swiftopenai agent "Read the README.md file" \
  --mcp-servers filesystem \
  --allowed-tools "mcp__filesystem__*"
```

## Usage Patterns

### Pattern 1: Simple Provider Routing

**User Request:** "Use grok to explain quantum computing"

**Execution:**

```bash
# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for Grok
scripts/configure_provider.sh grok grok-4-0709

# 3. Execute the task
swiftopenai agent "Explain quantum computing"
```

### Pattern 2: Specific Model Selection

**User Request:** "Ask DeepSeek Reasoner to solve this math problem step by step"

**Execution:**

```bash
# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for DeepSeek with Reasoner model
scripts/configure_provider.sh deepseek deepseek-reasoner

# 3. Execute with explicit model
swiftopenai agent "Solve x^2 + 5x + 6 = 0 step by step" --model deepseek-reasoner
```

### Pattern 3: Fast Inference with Groq

**User Request:** "Use groq to generate code quickly"

**Execution:**

```bash
# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for Groq (known for fast inference)
scripts/configure_provider.sh groq llama-3.3-70b-versatile

# 3. Execute the task
swiftopenai agent "Write a function to calculate fibonacci numbers"
```

### Pattern 4: Access Multiple Models via OpenRouter

**User Request:** "Use OpenRouter to access Claude"

**Execution:**

```bash
# 1. Check CLI installation
scripts/check_install_cli.sh

# 2. Configure for OpenRouter
scripts/configure_provider.sh openrouter anthropic/claude-3.5-sonnet

# 3. Execute with Claude via OpenRouter
swiftopenai agent "Explain the benefits of functional programming"
```

## Provider-Specific Considerations

### OpenAI (GPT-5 Models)

GPT-5 models support advanced parameters:

```bash
# Minimal reasoning for fast coding tasks
swiftopenai agent "Write a sort function" \
  --model gpt-5 \
  --reasoning minimal \
  --verbose low

# High reasoning for complex problems
swiftopenai agent "Explain quantum mechanics" \
  --model gpt-5 \
  --reasoning high \
  --verbose high
```

**Verbosity levels:** `low`, `medium`, `high`
**Reasoning effort:** `minimal`, `low`, `medium`, `high`

### Grok (xAI)

Grok models are optimized for real-time information and coding:

- `grok-4-0709` - Latest with enhanced reasoning
- `grok-3` - General purpose
- `grok-code-fast-1` - Optimized for code generation

### Groq

Known for ultra-fast inference with open-source models:

- `llama-3.3-70b-versatile` - Best general purpose
- `mixtral-8x7b-32768` - Mixture of experts

### DeepSeek

Specialized in reasoning and coding:

- `deepseek-reasoner` - Advanced step-by-step reasoning
- `deepseek-coder` - Coding specialist
- `deepseek-chat` - General chat

### OpenRouter

Provides access to 300+ models:

- Anthropic Claude models
- OpenAI models
- Google Gemini models
- Meta Llama models
- And many more

## API Key Management

### Recommended: Use Environment Variables for Multiple Providers

The **best practice** for using multiple providers is to set all API keys as environment variables. This allows seamless switching between providers without reconfiguring keys.

**Add to your shell profile** (`~/.zshrc` or `~/.bashrc`):

```bash
# API Keys for LLM Providers
export OPENAI_API_KEY=sk-...
export XAI_API_KEY=xai-...
export GROQ_API_KEY=gsk_...
export DEEPSEEK_API_KEY=sk-...
export OPENROUTER_API_KEY=sk-or-v1-...
```

After adding these, reload your shell:

```bash
source ~/.zshrc  # or source ~/.bashrc
```

**How it works:**
- SwiftOpenAI-CLI automatically uses the **correct provider-specific key** based on the configured provider
- When you switch to Grok, it uses `XAI_API_KEY`
- When you switch to OpenAI, it uses `OPENAI_API_KEY`
- No need to reconfigure keys each time

### Alternative: Single API Key via Config (Not Recommended for Multiple Providers)

If you only use **one provider**, you can store the key in the config file:

```bash
swiftopenai config set api-key <your-key>
```

**Limitation:** The config file only stores ONE api-key. If you switch providers, you'd need to reconfigure the key each time.

### Checking Current API Key

```bash
# View current configuration (API key is masked)
swiftopenai config list

# Get specific API key setting
swiftopenai config get api-key
```

**Priority:** Provider-specific environment variables take precedence over config file settings.

## Advanced Features

### Interactive Configuration

For complex setups, use the interactive wizard:

```bash
swiftopenai config setup
```

This launches a guided se