--- 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 2.5 Flash** | ~90% cheaper | ⭐⭐⭐⭐ Great | Long documents, reasoning | **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.5-flash", "name": "Gemini 2.5 Flash (Budget)", "input": ["text", "image"], "contextWindow": 1048576, "maxTokens": 8192, "cost": { "input": 0.3, "output": 2.5, "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 2.5 Flash** — Google's budget option, great for reasoning **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 2.5 Flash** — Google's budget model, very affordable 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 ```