ai-setup

---
name: ai-setup
description: Configure AI model options - budget cloud models (save 80%+) and offline mode (use Dex without internet)
---

## Purpose

Help users configure alternative AI models for Dex:
1. **Budget Cloud** - Cheaper models like Kimi, DeepSeek (80-97% savings)
2. **Offline Mode** - Local models via Ollama (works without internet)
3. **Smart Routing** - Automatically pick the best model per task

This skill is designed for users of ALL technical levels. Use plain language, avoid jargon, and guide step-by-step.

## When to Run

- User types `/ai-setup`
- Mentioned during onboarding (optional advanced setup)
- User asks about reducing AI costs
- User asks about working offline
- User is traveling frequently

---

## Entry Point

Say:

```
**Let's configure your AI options!**

Right now, Dex uses Claude for everything. It's excellent, but it costs money per use and requires internet.

Here are your options:

---

**1. 💰 Budget Cloud Mode** — Cheaper AI when online
   
   **What it is:** Use models like Kimi or DeepSeek that cost 80-97% less than Claude
   
   **The catch:** Requires a small upfront payment (~$5-10) to a service called OpenRouter
   - You'll need a credit card or Apple Pay
   - That $5-10 lasts weeks or months
   - Example: If Claude costs you $90/month, this would cost ~$10-20/month
   
   **Best for:** People who use Dex heavily and want to cut costs

---

**2. ✈️ Offline Mode** — AI that runs on your computer
   
   **What it is:** Download a free AI model that works without internet
   
   **The catch:** Uses your computer's memory and processing power
   - Requires ~8GB RAM minimum (you have 36GB ✅)
   - One-time download of 8-20GB
   - Slightly lower quality than Claude
   
   **Best for:** Travel (planes, trains), privacy, or if you don't want to pay anything
   
   **Cost: Completely free forever**

---

**3. 🎯 Smart Routing** — Automatic model selection
   
   This automatically picks the best model for each task. It works with whatever you set up above — if you only set up offline mode, it'll use that for simple tasks.

---

**Which would you like to set up?**

- "Budget cloud" — I'll walk you through the payment setup
- "Offline" — Free, no payment needed, let's do it
- "Both" — Get the most flexibility
- "Neither" — Stick with Claude for now
```

Wait for user response, then branch accordingly.

### If User Chooses "Both"

```
Great choice — you'll have maximum flexibility!

Let's start with **offline mode** first (it's free and quick), then we'll do budget cloud.

---
```

Then run Branch 2 (Offline), and when complete, transition:

```
**Offline mode is ready!** ✅

Now let's set up budget cloud so you can save money when you're online.

Budget cloud requires adding ~$5-10 to an OpenRouter account.

**Ready to continue, or want to stop here?**
- "Continue" — Let's set up budget cloud
- "Stop here" — Offline is enough for now (you can add budget cloud later)
```

If they continue, run Branch 1. If they stop, skip to smart routing offer.

### Graceful Pivots

If user hesitates on budget cloud or mentions payment concerns:

```
No problem! The offline option is completely free and works great for most daily tasks.

Want to set that up instead? You can always add budget cloud later when it makes sense.
```

If user can't do offline (old hardware, not enough RAM):

```
With your current setup, local AI would be quite slow. 

Your best options are:
1. **Stick with Claude** — Best quality, you're already set up
2. **Budget cloud** — Much cheaper than Claude, but does need that initial payment

What sounds better?
```

---

## Branch 1: Budget Cloud Setup

### Step 1.0: Confirm They're Ready to Pay

Before diving into setup, confirm:

```
**Quick check before we start:**

Budget cloud requires:
✓ Creating an account at OpenRouter.ai
✓ Adding ~$5-10 in credits (credit card or Apple Pay)
✓ About 5 minutes to set up

This is a one-time setup. That $5-10 will last you weeks or months.

**Ready to proceed?**
- "Yes" — Let's do it
- "Actually, let's do offline instead" — No problem, that's free
- "Maybe later" — We can come back to this anytime
```

If they want to pivot to offline, go to Branch 2.

### Step 1.1: Explain the Options (Plain Language)

```
**Budget Cloud Models — What Are Your Options?**

These are AI models from other companies that cost much less:

| Model | Monthly Savings | Quality | Best For |
|-------|-----------------|---------|----------|
| **Kimi K2.5** | ~80% cheaper | ⭐⭐⭐⭐ Great | General tasks, thinking |
| **DeepSeek V3** | ~95% cheaper | ⭐⭐⭐⭐ Great | Coding, analysis |
| **Gemini Flash** | ~97% cheaper | ⭐⭐⭐ Good | Long documents |

**My recommendation:** Start with **Kimi K2.5** — it's the closest to Claude in quality.

**Real cost example:**
If you currently spend ~$90/month on Claude, Kimi would cost ~$18/month for similar tasks.

Want to set up Kimi? (You can always add others later)
```

### Step 1.2: OpenRouter Setup (The Key Step)

```
**Setting Up Kimi (5-minute setup)**

To use these models, we go through a service called **OpenRouter**. 
Think of it like a phone plan that lets you call different networks.

**Here's what to do:**

**Step 1: Create an OpenRouter account**
   Go to: **https://openrouter.ai/keys**
   Click "Sign up" (Google/GitHub login works)

**Step 2: Add credits**
   - Click "Credits" in the top menu
   - Add $5-10 to start (this lasts weeks/months)
   - They accept cards, Apple Pay, etc.

**Step 3: Create an API key**
   - Go to: https://openrouter.ai/keys
   - Click "Create Key"
   - Give it a name like "Dex"
   - Copy the key (starts with `sk-or-...`)

**Step 4: Paste your key here**

Once you have your key, paste it here and I'll configure everything automatically.

---

*Stuck? Here's what each step looks like:*
- OpenRouter's interface is simple - big blue buttons
- The API key is just a password for your account
- Your credits work for ALL their models (Kimi, DeepSeek, etc.)
```

### Step 1.3: Configure the Key

When user provides key:

```python
# Validate key format
if not key.startswith("sk-or-"):
    respond("Hmm, that doesn't look like an OpenRouter key. They usually start with 'sk-or-'. Can you double-check?")
    return

# Create or update models.json
```

Generate `~/.pi/agent/models.json`:

```json
{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "api": "openai-completions",
      "apiKey": "USER_KEY_HERE",
      "models": [
        {
          "id": "moonshotai/kimi-k2.5",
          "name": "Kimi K2.5 (Budget)",
          "input": ["text"],
          "contextWindow": 262144,
          "maxTokens": 32768,
          "cost": { "input": 0.6, "output": 3, "cacheRead": 0, "cacheWrite": 0 }
        },
        {
          "id": "deepseek/deepseek-chat",
          "name": "DeepSeek V3 (Budget)",
          "input": ["text"],
          "contextWindow": 64000,
          "maxTokens": 8192,
          "cost": { "input": 0.14, "output": 0.28, "cacheRead": 0, "cacheWrite": 0 }
        },
        {
          "id": "google/gemini-2.0-flash-exp:free",
          "name": "Gemini Flash (Free tier)",
          "input": ["text", "image"],
          "contextWindow": 1048576,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}
```

Say:

```
**Done! Budget models are ready.**

I've added three models you can switch to anytime:
- **Kimi K2.5** — Best quality budget option
- **DeepSeek V3** — Super cheap, great for coding
- **Gemini Flash** — Google's free tier (with limits)

**How to use them:**

**Option A: Switch in this session**
   Type `/model` and select one from the list

**Option B: Ask me to switch**
   Just say "use the budget model" or "switch to Kimi"

**Option C: Set as default** (advanced)
   I can make Kimi your default and only use Claude for complex stuff

---

**Quick test:** Want me to do something simple with Kimi right now so you can see it work?
```

### Step 1.4: Update User Profile

Add to `System/user-profile.yaml`:

```yaml
ai_models:
  budget_cloud:
    enabled: true
    provider: openrouter
    primary_model: moonshotai/kimi-k2.5
    configured_date: 2026-02-04
```

---

## Branch 2: Offline Mode Setup

### Step 2.1: Check System Requirements

```
**Offline Mode — Let's Check Your Setup**

To run AI on your computer, I need to know what you're working with.

**Quick question:** What kind of computer are you using?

1. **Mac with Apple Silicon** (M1, M2, M3, M4 chip)
2. **Mac with Intel** (older Mac)
3. **Windows PC**
4. **Linux**
5. **Not sure**

(Most Macs from 2020 onwards have Apple Silicon)
```

Based on response, check RAM:

```
**Great! Now let's check your memory (RAM).**

On Mac:
1. Click the Apple menu (top-left corner)
2. Click "About This Mac"
3. Look for "Memory" — what number do you see?

On Windows:
1. Right-click the Start button
2. Click "System"
3. Look for "Installed RAM"

What does it say? (e.g., "8 GB", "16 GB", "32 GB")
```

### Step 2.2: Recommend Model Based on RAM

```python
if ram <= 8:
    model = "qwen2.5:7b"
    quality = "Good for 70% of tasks"
    size = "4.4 GB download"
elif ram <= 16:
    model = "qwen2.5:14b" 
    quality = "Good for 80% of tasks"
    size = "8.5 GB download"
elif ram <= 32:
    model = "qwen2.5:32b"
    quality = "Near-Claude for most tasks"
    size = "18 GB download"
else:
    model = "qwen2.5:72b"
    quality = "Excellent, close to Claude"
    size = "40 GB download"
```

Say:

```
**Perfect! Here's my recommendation:**

With **{{RAM}} GB** of memory, you can run **Qwen 2.5 {{size}}**.

**What to expect:**
- Quality: {{quality_description}}
- Download size: {{size}}
- Speed: {{speed based on chip}}

**What works great offline:**
✅ Daily planning and reviews
✅ Meeting summaries
✅ Task management
✅ Note organization
✅ Simple analysis

**What's better with Claude:**
⚠️ Complex strategic planning
⚠️ Nuanced writing
⚠️ Multi-step reasoning

Ready to set this up? It takes about 10-15 minutes (mostly download time).
```

### Step 2.3: Install Ollama

Check if Ollama is already installed:

```bash
which ollama || echo "not installed"
```

If not installed:

```
**Step 1: Install Ollama**

Ollama is a free app that runs AI models on your computer.

**On Mac (easiest way):**
1. Go to: **https://ollama.ai/download**
2. Click "Download for macOS"
3. Open the downloaded file
4. Drag Ollama to your Applications folder
5. Open Ollama from Applications (you'll see a llama icon in your menu bar)

**On Windows:**
1. Go to: **https://ollama.ai/download**
2. Click "Download for Windows"
3. Run the installer
4. Follow the prompts

**Let me know when Ollama is installed and running** (you should see a llama icon in your menu bar / system tray).
```

### Step 2.4: Download the Model

Once Ollama is confirmed running:

```
**Step 2: Download the AI model**

Now let's download the model to your computer. This is a one-time download.

**Run this command in Terminal:**

```
ollama pull {{recommended_model}}
```

**How to open Terminal:**
- Mac: Press Cmd+Space, type "Terminal", press Enter
- Windows: Search for "Command Prompt"

**Then paste the command above and press Enter.**

This will download ~{{size}}. It might take 5-15 minutes depending on your internet speed.

Let me know when it says "success"!
```

### Step 2.5: Configure Pi for Offline

Once model is downloaded, update `~/.pi/agent/models.json` to add Ollama:

```json
{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions", 
      "apiKey": "ollama",
      "models": [
        {
          "id": "{{recommended_model}}",
          "name": "{{model_name}} (Offline)",
          "input": ["text"],
          "contextWindow": 32768,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}
```

### Step 2.6: Test Offline Mode

```
**Step 3: Let's test it!**

Try this:
1. Turn off your WiFi (just for testing)
2. In Pi, type `/model` and select "{{model_name}} (Offline)"
3. Ask me something simple like "What day is it?"

If I respond, offline mode works! 🎉

Go ahead and test, then turn WiFi back on and let me know how it went.
```

### Step 2.7: Confirm Success

```
**Offline mode is ready!**

What happens now:
- When you have internet → Dex uses Claude (best quality)
- When you're offline → Dex can use your local model
- You can also manually switch anytime with `/model`

**For your next flight or train ride:**
1. Make sure Ollama is running (llama icon in menu bar)
2. Start Pi/Dex as usual
3. If internet isn't available, switch to your offline model

**Pro tip:** Test it at home once before relying on it during travel!

---

Want to also set up budget cloud models to save money when online?
```

Update `System/user-profile.yaml`:

```yaml
ai_models:
  offline:
    enabled: true
    runner: ollama
    model: qwen2.5:14b
    configured_date: 2026-02-04
```

---

## Branch 3: Smart Routing

### Step 3.1: Check What's Already Configured

First, check what's set up:
- Read `System/user-profile.yaml` for `ai_models` section
- Run `bash $VAULT_PATH/System/scripts/test-ai-connections.sh` silently

Then adapt the explanation:

**If both budget cloud and offline are configured:**

```
**Smart Routing — I'll Pick the Best Model Automatically**

You've got all three tiers set up — nice! Here's how I'll use them:

| Task Type | Model | Why |
|-----------|-------|-----|
| Complex planning, coaching | Claude | Needs deep reasoning |
| Daily tasks, summaries | Kimi (budget) | Good enough, saves money |
| Quick questions | Kimi (budget) | Fast and cheap |
| When you're offline | Qwen (local) | Only option! |

**Want to enable smart routing?**
- "Yes" — I'll pick automatically (you can always override)
- "No" — I'll always ask before switching
```

**If only offline is configured:**

```
**Smart Routing — I'll Pick Based on What You Have**

Since you set up offline mode, here's how routing works:

| Task Type | Model | Why |
|-----------|-------|-----|
| Complex tasks | Claude | When you need the best |
| Simple tasks | Claude | (budget not configured) |
| When you're offline | Qwen (local) | Your backup! |

**Tip:** If you add budget cloud later, I can start using cheaper models for simple tasks automatically.

**Want to enable smart routing?**
- "Yes" — Claude when online, local when offline
- "No" — I'll always ask
```

**If only budget cloud is configured:**

```
**Smart Routing — I'll Pick Based on What You Have**

Since you set up budget cloud, here's how routing works:

| Task Type | Model | Why |
|-----------|-------|-----|
| Complex tasks | Claude | When you need the best |
| Simple tasks | Kimi (budget) | Saves money! |
| Offline | ❌ Not available | (not configured) |

**Tip:** If you add offline mode later, you'll have a backup for travel.

**Want to enable smart routing?**
- "Yes" — Claude for complex, Kimi for simple
- "No" — I'll always ask
```

**If neither is configured:**

```
**Smart Routing — Nothing to Route Yet!**

Smart routing works best when you have alternatives set up. Right now you only have Claude.

Would you like to set up:
- "Offline mode" — Free, works without internet
- "Budget cloud" — Cheaper models, needs ~$5-10 upfront
- "Neither for now" — Stick with Claude
```

### Step 3.2: Configure Smart Routing

Based on what's configured, update `System/user-profile.yaml`:

```yaml
ai_models:
  smart_routing:
    enabled: true
    # Only include models that are actually configured
    rules:
      complex_tasks:
        model: claude-sonnet  # Always available
      routine_tasks:
        model: {{budget_model_if_configured OR "claude-sonnet"}}
      offline:
        model: {{offline_model_if_configured OR null}}
```

**Confirmation message (adapts to setup):**

If budget + offline:
```
**Smart routing is enabled!**

Here's what I'll do:
- Complex tasks (planning, coaching) → Claude
- Simple tasks (summaries, quick questions) → Kimi (saves money)
- When offline → Your local model

You can always override by saying "use Claude for this" or "switch to budget".
```

If only offline:
```
**Smart routing is enabled!**

Here's what I'll do:
- When online → Claude (best quality)
- When offline → Your local model (automatic fallback)

If you add budget cloud later, I can start saving you money on simple tasks.
```

If only budget:
```
**Smart routing is enabled!**

Here's what I'll do:
- Complex tasks → Claude (best quality)
- Simple tasks → Kimi (saves money)

If you add offline mode later, you'll have a backup for travel.
```

---

## Troubleshooting Section

### Ollama Not Starting

```
**Ollama won't start?**

Try these fixes:

**Mac:**
1. Open Applications folder
2. Right-click Ollama → Open
3. If blocked: System Preferences → Security → Allow Ollama

**If still stuck:**
1. Open Terminal
2. Run: `ollama serve`
3. Keep that window open

Let me know if you see any error messages.
```

### OpenRouter Key Not Working

```
**OpenRouter key not working?**

Let's debug:

1. **Check key format** — Should start with `sk-or-`
2. **Check credits** — Go to openrouter.ai/credits, make sure you have balance
3. **Test the key:**
   ```
   curl https://openrouter.ai/api/v1/models \
     -H "Authorization: Bearer YOUR_KEY_HERE"
   ```
   
   You should see a list of models, not an error.

4. **Regenerate key** — Go to openrouter.ai/keys, delete old key, make new one

What do you see when you try the test?
```

### Model Too Slow

```
**Local model running slow?**

This usually means the model is too big for your RAM.

**Fix options:**
1. **Try a smaller model:**
   ```
   ollama pull qwen2.5:7b
   ```
   (smaller = faster, but slightly less capable)

2. **Close other apps** — Free up memory

3. **Check Activity Monitor** (Mac) or Task Manager (Windows)
   - If RAM is maxed out, you need a smaller model

Want me to help you switch to a smaller model?
```

---

## Edge Cases

### User Has No Credit Card

```
**No credit card for OpenRouter?**

Some alternatives:

1. **Gemini Flash Free Tier** — Google offers free usage (with limits)
   I can set that up instead

2. **Offline Only** — Skip budget cloud, just use local models
   Free forever, works without internet

3. **Anthropic Direct** — If you have Claude credits already, we can optimize usage

Which works for you?
```

### User on Very Old Hardware

```
**Older computer detected**

With {{RAM}} GB RAM, local AI will be very slow.

**Better options for you:**
1. **Budget cloud only** — Uses internet, but works on any computer
2. **Stick with Claude** — Best quality, works everywhere

Offline mode really needs 8GB+ RAM to be useful.

Want to set up budget cloud instead?
```

---

## Success Metrics

After setup, track in `System/usage_log.md`:
- [ ] Configured budget cloud models
- [ ] Configured offline mode  
- [ ] Enabled smart routing
- [ ] Used budget model for a task
- [ ] Used offline model

---

## Post-Setup Summary

After any setup completes, show an adaptive summary and offer smart routing:

### If only offline was set up:

```
**Setup Complete!** ✅

| Mode | Status |
|------|--------|
| Premium (Claude) | ✅ Always available |
| Budget Cloud | ❌ Not configured |
| Offline Mode | ✅ Ready (Qwen 2.5) |

**How to use offline mode:**
- When you're online: Dex uses Claude (best quality)
- When you're offline: Switch with `/model` or say "use offline model"
- Or I can switch automatically when I detect you're offline

**Want to enable smart routing?** (I'll automatically use your local model when offline)
- "Yes" — Enable automatic switching
- "No" — I'll ask before switching

You can add budget cloud later with `/ai-setup` if you want to save money.
```

### If only budget cloud was set up:

```
**Setup Complete!** ✅

| Mode | Status |
|------|--------|
| Premium (Claude) | ✅ Always available |
| Budget Cloud | ✅ Ready (Kimi K2.5) |
| Offline Mode | ❌ Not configured |

**How to use budget models:**
- Say "use budget model" or "use Kimi"
- Or use `/model` to switch manually
- Or I can pick automatically based on task complexity

**Want to enable smart routing?** (I'll use Kimi for simple tasks, Claude for complex ones)
- "Yes" — Enable automatic switching
- "No" — I'll ask before switching

You can add offline mode later with `/ai-setup` for travel.
```

### If both were set up:

```
**Setup Complete!** ✅

| Mode | Status | Model |
|------|--------|-------|
| Premium | ✅ | Claude Sonnet |
| Budget | ✅ | Kimi K2.5 |
| Offline | ✅ | Qwen 2.5 |

**You have maximum flexibility!**

**Want to enable smart routing?** 
I'll automatically:
- Use Claude for complex tasks (planning, coaching)
- Use Kimi for simple tasks (summaries, quick questions) — saves money
- Use your local model when offline — automatic fallback

- "Yes" — Enable smart routing
- "No" — I'll ask each time

**Quick reference:**
- "Use Kimi" → Switch to budget
- "Use Claude" → Switch to premium
- `/model` → Manual picker
- `/ai-status` → Check configuration
```

## Track Usage (Silent)

Update `System/usage_log.md` to mark AI setup as used.

**Analytics (Silent):**

Call `track_event` with event_name `ai_setup_completed` and properties:
- `mode` (budget_cloud/offline/smart_routing)

This only fires if the user has opted into analytics. No action needed if it returns "analytics_disabled".

---

## Follow-up Skill: /ai-status

Users can check their AI setup anytime:

```
/ai-status

**Your AI Configuration**

| Mode | Status | Model |
|------|--------|-------|
| Premium | ✅ | Claude Sonnet |
| Budget | {{✅ / ❌}} | {{Kimi K2.5 / Not configured}} |
| Offline | {{✅ / ❌}} | {{Qwen 2.5 / Not configured}} |
| Smart Routing | {{✅ Enabled / ❌ Disabled}} | |

**This session:** Using {{current_model}}
{{If OpenRouter configured:}} **OpenRouter credits:** ${{balance}} remaining
{{If Ollama configured:}} **Ollama status:** {{Running ✅ / Not running ⚠️}}

**Quick actions:**
- `/model` — Switch models
- `/ai-setup` — Configure more options
- "Use budget model" — Quick switch
```