wp-agentic-writer/docs/architecture/HYBRID-PROVIDER-WALKTHROUGH.md

# Hybrid AI Provider System - User Walkthrough

## Overview

The WP Agentic Writer plugin now supports multiple AI providers for different tasks:

| Provider | Use Case | Cost | Best For |
|----------|----------|------|----------|
| **Local Backend** | Text generation (chat, planning, writing) | **$0** | Daily use, privacy, unlimited generation |
| **Codex** | Alternative text provider | Per-token | When Local Backend unavailable |
| **OpenRouter** | Image generation + fallback | Per-token | Images, fallback when local offline |

**The magic:** Route text tasks to your free local Claude CLI, images to OpenRouter's best models.

---

## Quick Start (5 Minutes)

### Step 1: Check Prerequisites

You need:
- ✅ Claude CLI installed (`claude --version` should work)
- ✅ Node.js 18+ installed (`node --version`)
- ✅ Z.ai subscription or Anthropic API key configured in Claude CLI

Don't have these? Get them first:
- **Claude CLI**: https://claude.ai/code or https://z.ai
- **Node.js**: https://nodejs.org
- **Z.ai**: https://z.ai (free tier available)

### Step 2: Download & Start Local Backend

1. **In WordPress Admin**, go to **Settings → Agentic Writer → Local Backend**
2. Click **"Download Local Backend v1.0.0"**
3. **Extract the ZIP** to a folder on your machine
4. **Open terminal** in that folder
5. **Run:** `./start-proxy.sh`

You'll see output like:
```
🚀 Starting Claude Proxy Server...
📦 Installing dependencies...
✅ Dependencies installed

🌐 Local Backend is running!
   Base URL: http://192.168.1.105:8080
   Health Check: http://192.168.1.105:8080/ping

💡 To test: ./test-connection.sh
💡 To stop: ./stop-proxy.sh
```

**Copy the Base URL** (e.g., `http://192.168.1.105:8080`)

### Step 3: Configure Plugin

1. **In WordPress**, paste the Base URL into **"Base URL"** field
2. Leave **API Key** as `dummy` (ignored by local proxy)
3. Click **"Test Connection"**
4. You should see: ✅ **Connected! Proxy responding correctly.**

### Step 4: Set Provider Routing (Optional)

By default, all text tasks use your Local Backend (free). To customize:

1. In the **Local Backend** tab, scroll to **"Provider Routing"**
2. Choose provider per task:
   - **Chat** → Local Backend (free)
   - **Clarity Check** → Local Backend (free)
   - **Outline Planning** → Local Backend (free)
   - **Article Writing** → Local Backend (free)
   - **Content Refinement** → Local Backend or Codex
   - **Image Generation** → OpenRouter (only option)

3. Click **"Save Settings"**

### Step 5: Generate Content

1. **Open any post** in Gutenberg editor
2. Click the **Agentic Writer** sidebar (🤖 icon)
3. Type a topic like: *"Write about AI trends in 2025"*
4. Watch as content generates with **$0.00 cost**!

---

## Provider Deep Dive

### 🏠 Local Backend (Recommended)

**What it is:** A Node.js proxy running on your machine that connects to your Claude CLI.

**Why use it:**
- 💰 **$0 cost** for unlimited text generation
- 🔒 **Privacy** - content never leaves your machine
- ⚡ **Speed** - LAN latency vs cloud round-trip
- 🎛️ **Same quality** - uses same Claude models as cloud

**How it works:**
```
WordPress → Your Computer (proxy) → Claude CLI → Z.ai/Anthropic
```

**Limitations:**
- One request at a time (Claude CLI limitation)
- Must keep terminal open with proxy running
- Requires your computer to be on and on same network

**Setup:**
```bash
# Terminal 1: Start proxy
cd agentic-writer-local-backend
./start-proxy.sh

# Keep this terminal open while using the plugin
```

### 🔗 Codex (OpenAI)

**What it is:** Direct integration with OpenAI's API.

**Why use it:**
- ☁️ **Cloud reliability** - works from anywhere
- 🎯 **High quality** - excellent for technical content
- 📱 **Mobile friendly** - doesn't require your computer

**How to enable:**
1. Get OpenAI API key: https://platform.openai.com
2. Go to **Settings → Agentic Writer → General**
3. Add **Codex API Key** field (new field in settings)
4. Set task provider to "Codex"

**Cost:** Per OpenAI pricing (~$0.002-0.03 per 1K tokens)

### ☁️ OpenRouter (Fallback)

**What it is:** The original cloud provider (still works great!).

**Primary use:**
- 🖼️ **Image generation** (FLUX, Recraft, GPT-4o)
- 🔄 **Automatic fallback** when Local Backend is offline

**You already have this configured** - it's the original system.

---

## Configuration Examples

### Example 1: All Local (Maximum Savings)

**Goal:** Pay $0 for all text generation

**Settings:**
```
Provider Routing:
  Chat       → Local Backend
  Clarity    → Local Backend
  Planning   → Local Backend
  Writing    → Local Backend
  Refinement → Local Backend
  Image      → OpenRouter
```

**Expected cost:** $0 for text, ~$0.05 per image

### Example 2: Hybrid (Balanced)

**Goal:** Free for most tasks, cloud for refinement

**Settings:**
```
Provider Routing:
  Chat       → Local Backend
  Clarity    → Local Backend
  Planning   → Local Backend
  Writing    → Local Backend
  Refinement → Codex (cloud quality)
  Image      → OpenRouter
```

**Expected cost:** ~$0.10-0.30 per article (refinement only)

### Example 3: Cloud Production (No Local)

**Goal:** Works from anywhere, no local setup

**Settings:**
```
Provider Routing:
  All tasks → OpenRouter
```

**Expected cost:** ~$0.50-2.00 per article

---

## Troubleshooting

### ❌ "Connection failed" when testing

**Symptoms:** Red error message in settings

**Solutions:**

1. **Is proxy running?**
   ```bash
   # Check if Node.js process is running
   ps aux | grep claude-proxy
   
   # If not, start it:
   ./start-proxy.sh
   ```

2. **Wrong IP address?**
   ```bash
   # Find your correct local IP
   ./get-local-ip.sh
   
   # Or manually:
   # macOS: ifconfig | grep "inet "
   # Linux: ip addr show
   # Windows: ipconfig
   ```

3. **Firewall blocking?**
   - **macOS:** System Preferences → Security → Firewall → Allow Node.js
   - **Linux:** `sudo ufw allow 8080`
   - **Windows:** Windows Defender → Allow app → Node.js

### ❌ "Claude CLI not responding"

**Symptoms:** Proxy starts but AI calls fail

**Solutions:**

1. **Test Claude CLI directly:**
   ```bash
   echo "Say hello" | claude
   ```
   
   If this fails, Claude CLI isn't configured properly.

2. **Check Z.ai/Anthropic setup:**
   ```bash
   claude config get apiKey
   ```
   
   Should show your API key. If empty:
   ```bash
   claude config set apiKey YOUR_API_KEY
   ```

3. **Re-authenticate:**
   ```bash
   claude auth login
   ```

### ❌ "Proxy responded but with unexpected format"

**Symptoms:** Ping works but inference fails

**Solutions:**

1. **Check proxy logs:**
   ```bash
   # In proxy folder
   cat proxy.log
   ```

2. **Restart proxy:**
   ```bash
   ./stop-proxy.sh
   ./start-proxy.sh
   ```

3. **Test manually:**
   ```bash
   ./test-connection.sh
   ```

### ❌ Content generates but cost shows in dashboard

**Symptoms:** Expecting $0 but seeing charges

**Check:**
1. Go to **Settings → Local Backend → Provider Routing**
2. Verify tasks are set to "Local Backend" not "OpenRouter"
3. Check that **Local Backend URL** is saved (not empty)
4. Test connection - should show ✅

**Fallback behavior:** If Local Backend is unreachable, plugin auto-switches to OpenRouter (and charges apply).

---

## Advanced Tips

### Tip 1: Running Proxy on a Different Machine

You can run the proxy on a dedicated machine (e.g., home server) and connect WordPress from anywhere:

**On server (192.168.1.50):**
```bash
./start-proxy.sh
# Shows: http://192.168.1.50:8080
```

**In WordPress:**
```
Base URL: http://192.168.1.50:8080
```

**Requirements:**
- Both on same network (or VPN)
- Server has Claude CLI + Z.ai configured
- Port 8080 open on server firewall

### Tip 2: Using with Cloud-Hosted WordPress

**The challenge:** Your WordPress is on a server, but proxy needs to be on your machine.

**Solutions:**

**Option A: VPN/Network Bridge**
- Install Tailscale or similar on both machines
- WordPress connects via Tailscale IP

**Option B: SSH Tunnel**
```bash
# From your local machine
ssh -R 8080:localhost:8080 user@wordpress-server
```

**Option C: Use Codex/OpenRouter**
- Skip Local Backend for cloud WordPress
- Use Codex or OpenRouter (cloud providers)

### Tip 3: Auto-Start Proxy

**macOS (LaunchAgent):**
```xml
<!-- ~/Library/LaunchAgents/com.agenticwriter.proxy.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agenticwriter.proxy</string>
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/agentic-writer-local-backend/start-proxy.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>
```

**Linux (systemd):**
```ini
# ~/.config/systemd/user/claude-proxy.service
[Unit]
Description=Claude Proxy for WP Agentic Writer

[Service]
Type=simple
WorkingDirectory=/path/to/agentic-writer-local-backend
ExecStart=/path/to/agentic-writer-local-backend/start-proxy.sh
Restart=always

[Install]
WantedBy=default.target
```

### Tip 4: Monitoring Proxy

**Check if proxy is running:**
```bash
# Quick check
curl http://192.168.1.105:8080/ping
# Should return: pong
```

**Watch logs:**
```bash
# In proxy folder
tail -f proxy.log
```

**Auto-restart if crashed:**
```bash
# Add to crontab
*/5 * * * * /path/to/agentic-writer-local-backend/start-proxy.sh >/dev/null 2>&1
```

---

## Cost Comparison

| Scenario | Monthly Usage | Old Cost (OpenRouter) | New Cost (Hybrid) | Savings |
|----------|---------------|----------------------|---------------------|---------|
| Light blogger | 10 articles | $5-10 | $0-2 | 80% |
| Content agency | 100 articles | $50-100 | $5-10 | 90% |
| Heavy user | 500 articles | $250-500 | $20-40 | 92% |
| Image-heavy | 50 images | $2.50 | $2.50 | 0% |

**Assumptions:**
- Text tasks use Local Backend (free)
- Images use OpenRouter ($0.05 each)
- Occasional Codex refinement ($0.20 per article)

---

## FAQ

### Q: Is Local Backend really free?

**A:** Yes! It uses your existing Claude CLI + Z.ai/Anthropic subscription. The proxy just connects WordPress to your local Claude. Your Z.ai subscription covers the usage.

### Q: What if my computer is off?

**A:** The plugin automatically falls back to OpenRouter. You'll see a notice: "Local Backend unavailable, using OpenRouter."

### Q: Can multiple WordPress sites use one proxy?

**A:** Yes! Just point all sites to the same `http://your-ip:8080`. Only one request processes at a time (Claude CLI limitation).

### Q: Is my content private?

**A:** With Local Backend, yes! Content goes:
- WordPress → Your Computer → Claude CLI → Z.ai

Never passes through our servers or third-party APIs (except Z.ai/Anthropic which you already use).

### Q: Can I use Ollama instead of Claude CLI?

**A:** Not currently. The proxy is designed for Claude CLI. Future versions may support Ollama.

### Q: Why is streaming not working?

**A:** Local Backend currently uses non-streaming (full response). This is a Claude CLI limitation. Codex and OpenRouter support streaming.

### Q: How do I update the proxy?

**A:** Download the latest ZIP from plugin settings and replace your proxy folder. Your configuration (Base URL in WordPress) stays the same.

---

## Migration from Old System

**If you were using OpenRouter only:**

1. ✅ **Nothing breaks** - plugin defaults to OpenRouter
2. ✅ **All settings preserved** - API key, models, etc.
3. ➕ **New option** - add Local Backend anytime

**To add Local Backend:**
1. Follow **Quick Start** above
2. No need to change existing content or settings
3. Gradually switch tasks to Local Backend

---

## Getting Help

### Documentation
- **This walkthrough** (you're reading it!)
- **TROUBLESHOOTING.md** (in proxy package)
- **README.md** (in proxy package)

### Community
- GitHub Issues: [plugin-repo]/issues
- Discord: [community-link]

### Debug Info
When reporting issues, include:
```
1. Proxy version: cat package.json | grep version
2. Claude version: claude --version
3. Node version: node --version
4. Connection test result: ./test-connection.sh
5. WordPress version
6. Plugin version
```

---

## Next Steps

1. ✅ [Download Local Backend](#step-2-download--start-local-backend)
2. ✅ [Configure Plugin](#step-3-configure-plugin)
3. ✅ [Test Generation](#step-5-generate-content)
4. 📖 [Read Troubleshooting](#troubleshooting) if needed
5. 🚀 Enjoy unlimited free AI generation!

---

*Last updated: 2026-02-27*
*Plugin version: 0.3.0*
*Proxy version: 1.0.0*