Add AI writing assistant plugin with local backend, brave search, and image generation support

- Implement local backend AI provider with Ollama integration - Add Brave Search API integration for real-time search suggestions - Add image generation manager with multiple AI providers - Create hybrid provider system with local/cloud fallback - Add comprehensive settings UI with provider management - Implement Gutenberg sidebar with writing assistance controls - Add SEO schema generation for AI-generated content - Multiple provider support: OpenRouter, local backend, Codex
2026-05-17 10:48:05 +07:00
parent 97426d5ab1
commit d2c10756ab
61 changed files with 18725 additions and 806 deletions
--- a/HYBRID-PROVIDER-WALKTHROUGH.md
+++ b/HYBRID-PROVIDER-WALKTHROUGH.md
@@ -0,0 +1,500 @@
+# 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*