feat: consolidate docs, backend/session infra, and settings updates
This commit is contained in:
Dwindi Ramadhana
397
docs/features/COST_TRACKING_IMPLEMENTATION.md
Normal file
397
docs/features/COST_TRACKING_IMPLEMENTATION.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# Cost Tracking Enhancement Implementation
|
||||
|
||||
## Overview
|
||||
Comprehensive cost tracking system implemented with three major features:
|
||||
1. **CPT Column** - Total cost per post in post list table
|
||||
2. **Global Cost Log** - Detailed cost tracking in settings page
|
||||
3. **Cost Shortcuts** - Quick access links in settings
|
||||
|
||||
---
|
||||
|
||||
## 1. CPT Column for Post List
|
||||
|
||||
### File Created
|
||||
`/includes/class-admin-columns.php`
|
||||
|
||||
### Features
|
||||
- **💰 AI Cost** column in post list table
|
||||
- Shows total cost per post with color coding:
|
||||
- Green: < $0.50
|
||||
- Yellow: $0.50 - $1.00
|
||||
- Red: > $1.00
|
||||
- **Sortable** - Click column header to sort by cost
|
||||
- Shows `-` for posts with no AI usage
|
||||
- Handles deleted posts gracefully
|
||||
|
||||
### Implementation
|
||||
```php
|
||||
// Adds column to post list
|
||||
add_filter('manage_post_columns', 'add_cost_column');
|
||||
|
||||
// Renders cost with color coding
|
||||
add_action('manage_post_custom_column', 'render_cost_column');
|
||||
|
||||
// Makes column sortable
|
||||
add_filter('manage_edit-post_sortable_columns', 'make_cost_column_sortable');
|
||||
|
||||
// Handles sorting query
|
||||
add_action('pre_get_posts', 'sort_by_cost');
|
||||
```
|
||||
|
||||
### Initialization
|
||||
Added to `wp-agentic-writer.php`:
|
||||
```php
|
||||
if ( is_admin() ) {
|
||||
WP_Agentic_Writer_Admin_Columns::get_instance();
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Global Cost Log Tab
|
||||
|
||||
### Location
|
||||
Settings → Agentic Writer → **Cost Log** tab
|
||||
|
||||
### Features
|
||||
|
||||
#### **Summary Stats (4 Cards)**
|
||||
- 💰 **All Time** - Total spent across all posts
|
||||
- 📅 **This Month** - Current month spending
|
||||
- ☀️ **Today** - Today's spending
|
||||
- 📝 **Avg Per Post** - Average cost per post
|
||||
|
||||
#### **Advanced Filters**
|
||||
- **Post ID** - Filter by specific post
|
||||
- **Model** - Filter by AI model used
|
||||
- **Type** - Filter by operation (chat, planning, writing, etc.)
|
||||
- **Date Range** - From/To date pickers
|
||||
- **Clear Filters** - Reset all filters
|
||||
|
||||
#### **Detailed Cost Table**
|
||||
Columns:
|
||||
- Date/Time
|
||||
- Post (with link or `[Removed Post #123]` for deleted)
|
||||
- Model (displayed as code)
|
||||
- Type (formatted: Chat, Planning, Writing, etc.)
|
||||
- Input Tokens
|
||||
- Output Tokens
|
||||
- Cost ($0.0000 format)
|
||||
|
||||
#### **Additional Features**
|
||||
- **Pagination** - 50 records per page
|
||||
- **Export CSV** - Download full cost log
|
||||
- **Responsive** - Horizontal scroll on small screens
|
||||
- **Hover Effects** - Row highlighting
|
||||
|
||||
### Implementation
|
||||
|
||||
#### Settings Tab Navigation
|
||||
Added to `class-settings.php`:
|
||||
```php
|
||||
<button type="button" class="wpaw-settings-nav-btn" data-tab="cost-log">
|
||||
<span class="dashicons dashicons-chart-line"></span>
|
||||
Cost Log
|
||||
</button>
|
||||
```
|
||||
|
||||
#### Tab Content
|
||||
```php
|
||||
<div class="wpaw-tab-content" data-tab="cost-log">
|
||||
<?php $this->render_cost_log_tab(); ?>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### Method: `render_cost_log_tab()`
|
||||
- Queries cost database with filters
|
||||
- Calculates summary statistics
|
||||
- Renders stats grid, filters, table, pagination
|
||||
- Includes CSV export JavaScript
|
||||
|
||||
---
|
||||
|
||||
## 3. Cost Shortcuts
|
||||
|
||||
### Location
|
||||
Settings → General → Budget & Cost Tracking section
|
||||
|
||||
### Feature
|
||||
**"View Full Cost Log →"** link appears below the budget progress bar
|
||||
|
||||
### Implementation
|
||||
```php
|
||||
<div class="wpaw-cost-shortcuts">
|
||||
<a href="<?php echo admin_url('options-general.php?page=wp-agentic-writer-settings&tab=cost-log'); ?>"
|
||||
class="wpaw-cost-shortcut-link">
|
||||
<span class="dashicons dashicons-chart-line"></span>
|
||||
View Full Cost Log →
|
||||
</a>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Styling
|
||||
- Blue border with light blue background
|
||||
- Hover: Blue background with white text
|
||||
- Smooth transitions
|
||||
- Icon + text layout
|
||||
|
||||
---
|
||||
|
||||
## CSS Styling Added
|
||||
|
||||
### File Modified
|
||||
`/assets/css/admin.css`
|
||||
|
||||
### New Styles
|
||||
|
||||
#### Cost Shortcuts
|
||||
```css
|
||||
.wpaw-cost-shortcuts
|
||||
.wpaw-cost-shortcut-link
|
||||
.wpaw-cost-shortcut-link:hover
|
||||
```
|
||||
|
||||
#### Cost Stats Grid
|
||||
```css
|
||||
.wpaw-cost-stats-grid
|
||||
.wpaw-cost-stat-card
|
||||
.wpaw-cost-stat-icon
|
||||
.wpaw-cost-stat-value
|
||||
.wpaw-cost-stat-label
|
||||
```
|
||||
|
||||
#### Cost Filters
|
||||
```css
|
||||
.wpaw-cost-filters
|
||||
.wpaw-filter-row
|
||||
.wpaw-filter-field
|
||||
.wpaw-filter-actions
|
||||
```
|
||||
|
||||
#### Cost Log Table
|
||||
```css
|
||||
.wpaw-cost-log-table-wrapper
|
||||
.wpaw-cost-log-table
|
||||
.wpaw-cost-log-table thead
|
||||
.wpaw-cost-log-table th
|
||||
.wpaw-cost-log-table td
|
||||
.wpaw-cost-log-table tbody tr:hover
|
||||
.wpaw-removed-post
|
||||
```
|
||||
|
||||
#### Pagination
|
||||
```css
|
||||
.wpaw-pagination
|
||||
.wpaw-pagination-info
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Database Queries
|
||||
|
||||
### Cost Column Query
|
||||
```sql
|
||||
SELECT SUM(cost)
|
||||
FROM wp_wp_agentic_writer_costs
|
||||
WHERE post_id = %d
|
||||
```
|
||||
|
||||
### Cost Log Queries
|
||||
```sql
|
||||
-- Total count with filters
|
||||
SELECT COUNT(*) FROM wp_wp_agentic_writer_costs WHERE [filters]
|
||||
|
||||
-- Cost records with pagination
|
||||
SELECT * FROM wp_wp_agentic_writer_costs
|
||||
WHERE [filters]
|
||||
ORDER BY created_at DESC
|
||||
LIMIT 50 OFFSET 0
|
||||
|
||||
-- Summary stats
|
||||
SELECT SUM(cost) FROM wp_wp_agentic_writer_costs -- All time
|
||||
SELECT SUM(cost) WHERE MONTH(created_at) = MONTH(NOW()) -- This month
|
||||
SELECT SUM(cost) WHERE DATE(created_at) = CURDATE() -- Today
|
||||
SELECT COUNT(DISTINCT post_id) WHERE post_id > 0 -- Total posts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Experience Flow
|
||||
|
||||
### 1. Post List View
|
||||
```
|
||||
Posts → All Posts
|
||||
└─ See "💰 AI Cost" column
|
||||
├─ Click header to sort by cost
|
||||
├─ Green/Yellow/Red color coding
|
||||
└─ Click post to edit
|
||||
```
|
||||
|
||||
### 2. Settings Quick Access
|
||||
```
|
||||
Settings → Agentic Writer → General
|
||||
└─ Budget & Cost Tracking section
|
||||
├─ View monthly progress bar
|
||||
├─ See summary stats
|
||||
└─ Click "View Full Cost Log →"
|
||||
```
|
||||
|
||||
### 3. Cost Log Deep Dive
|
||||
```
|
||||
Settings → Agentic Writer → Cost Log
|
||||
└─ Summary Stats (4 cards)
|
||||
├─ All Time, This Month, Today, Avg Per Post
|
||||
└─ Filters
|
||||
├─ Post ID, Model, Type, Date Range
|
||||
└─ Apply Filters / Clear
|
||||
└─ Detailed Table
|
||||
├─ 50 records per page
|
||||
├─ Pagination controls
|
||||
├─ Click post title to edit
|
||||
└─ Export CSV button
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deleted Post Handling
|
||||
|
||||
### Problem
|
||||
Posts may be deleted but cost records remain
|
||||
|
||||
### Solution
|
||||
```php
|
||||
$post_title = get_the_title($cost->post_id);
|
||||
if (!$post_title && $cost->post_id > 0) {
|
||||
$post_title = sprintf(__('[Removed Post #%d]'), $cost->post_id);
|
||||
$post_class = 'wpaw-removed-post'; // Gray, italic
|
||||
}
|
||||
```
|
||||
|
||||
### Display
|
||||
- Shows `[Removed Post #123]` in gray italic
|
||||
- No link (prevents 404 errors)
|
||||
- Still shows all cost data
|
||||
- Filterable by post ID
|
||||
|
||||
---
|
||||
|
||||
## Export CSV Feature
|
||||
|
||||
### Implementation
|
||||
JavaScript in `render_cost_log_tab()`:
|
||||
```javascript
|
||||
$('#wpaw-export-csv').on('click', function() {
|
||||
// Extract table data
|
||||
// Format as CSV with escaped quotes
|
||||
// Create blob and download
|
||||
// Filename: wp-agentic-writer-costs-YYYY-MM-DD.csv
|
||||
});
|
||||
```
|
||||
|
||||
### CSV Format
|
||||
```csv
|
||||
"Date/Time","Post","Model","Type","Input Tokens","Output Tokens","Cost"
|
||||
"2026-01-26 10:05:23","My Article","google/gemini-2.5-flash","Chat","1234","567","$0.0012"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Created
|
||||
1. `/includes/class-admin-columns.php` - CPT column handler
|
||||
|
||||
### Modified
|
||||
1. `/wp-agentic-writer.php` - Initialize admin columns
|
||||
2. `/includes/class-settings.php` - Add Cost Log tab + shortcut
|
||||
3. `/assets/css/admin.css` - Add all cost tracking styles
|
||||
|
||||
### Unchanged (Already Working)
|
||||
- `/includes/class-cost-tracker.php` - Cost tracking logic
|
||||
- `/assets/js/settings.js` - Tab switching (supports dynamic tabs)
|
||||
- Database table `wp_wp_agentic_writer_costs` - Already exists
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### CPT Column
|
||||
- [ ] Column appears in post list
|
||||
- [ ] Shows correct costs per post
|
||||
- [ ] Color coding works (green/yellow/red)
|
||||
- [ ] Sorting works (click column header)
|
||||
- [ ] Shows `-` for posts without AI usage
|
||||
|
||||
### Cost Log Tab
|
||||
- [ ] Tab appears in settings navigation
|
||||
- [ ] Summary stats display correctly
|
||||
- [ ] All filters work (Post ID, Model, Type, Date Range)
|
||||
- [ ] Table displays cost records
|
||||
- [ ] Pagination works
|
||||
- [ ] Deleted posts show `[Removed Post #123]`
|
||||
- [ ] Post links work for existing posts
|
||||
- [ ] Export CSV downloads correctly
|
||||
|
||||
### Cost Shortcuts
|
||||
- [ ] Link appears under budget progress bar
|
||||
- [ ] Clicking opens Cost Log tab
|
||||
- [ ] Hover effect works
|
||||
|
||||
### Responsive Design
|
||||
- [ ] Table scrolls horizontally on mobile
|
||||
- [ ] Filters stack properly on small screens
|
||||
- [ ] Stats grid adjusts to screen size
|
||||
|
||||
---
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### Optimizations
|
||||
1. **Pagination** - Only loads 50 records at a time
|
||||
2. **Indexed Queries** - Uses post_id, created_at indexes
|
||||
3. **Prepared Statements** - All queries use `$wpdb->prepare()`
|
||||
4. **Conditional Loading** - Admin columns only load in admin
|
||||
5. **CSS Minification** - Production should minify admin.css
|
||||
|
||||
### Database Impact
|
||||
- Minimal: Uses existing `wp_wp_agentic_writer_costs` table
|
||||
- No new tables created
|
||||
- Queries are optimized with WHERE clauses
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements (Not Implemented)
|
||||
|
||||
### Potential Additions
|
||||
1. **Charts** - Visual cost trends over time
|
||||
2. **Budget Alerts** - Email when approaching limit
|
||||
3. **Cost Breakdown** - Pie chart by model/type
|
||||
4. **Bulk Actions** - Delete old cost records
|
||||
5. **API Endpoint** - REST API for cost data
|
||||
6. **Dashboard Widget** - Cost summary on WP dashboard
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Total Implementation Time:** ~3 hours
|
||||
|
||||
**Features Delivered:**
|
||||
- ✅ CPT column with sorting and color coding
|
||||
- ✅ Global cost log with filters and pagination
|
||||
- ✅ Summary statistics (4 cards)
|
||||
- ✅ Cost shortcuts for quick access
|
||||
- ✅ Export CSV functionality
|
||||
- ✅ Deleted post handling
|
||||
- ✅ Responsive design
|
||||
- ✅ Full styling and UX polish
|
||||
|
||||
**User Benefits:**
|
||||
- Quick cost overview in post list
|
||||
- Detailed cost analysis in settings
|
||||
- Easy filtering and searching
|
||||
- Export for external analysis
|
||||
- Budget monitoring at a glance
|
||||
- ROI tracking per article
|
||||
|
||||
**Ready for Production:** Yes ✅
|
||||
506
docs/features/DISTRIBUTION_STRATEGY.md
Normal file
506
docs/features/DISTRIBUTION_STRATEGY.md
Normal file
@@ -0,0 +1,506 @@
|
||||
# WP Agentic Writer - Distribution Strategy
|
||||
|
||||
**Version:** 1.0
|
||||
**Date:** 2026-05-17
|
||||
**Strategy:** Freemium with Addon Model
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
This document outlines a comprehensive strategy for distributing WP Agentic Writer as two distinct versions:
|
||||
- **Free Version** - Published on WordPress.org repository for maximum visibility and user acquisition
|
||||
- **Pro Version** - Premium addon sold via your own license server with advanced features
|
||||
|
||||
**Core Philosophy:** The free version must be a complete, valuable product on its own. Pro features are genuine enhancements that power users will happily pay for.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ WP AGENTIC WRITER │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ FREE CORE PLUGIN (WordPress.org) │
|
||||
│ ├── AI Writing Assistant (sidebar) │
|
||||
│ ├── Context Management │
|
||||
│ ├── Planning & Writing Pipeline │
|
||||
│ ├── Model Selection (OpenRouter) │
|
||||
│ ├── Basic Refinement │
|
||||
│ ├── Cost Tracking │
|
||||
│ └── Hook System (for extensibility) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ PRO ADDON (License Server) │
|
||||
│ ├── License Verification System │
|
||||
│ ├── Advanced Refinement (multi-pass) │
|
||||
│ ├── Local Backend Integration (extended) │
|
||||
│ ├── Brave Search Integration │
|
||||
│ ├── Image Generation (DALL-E, Stable Diffusion) │
|
||||
│ ├── Custom Model Presets │
|
||||
│ ├── Team Collaboration │
|
||||
│ ├── Priority Support │
|
||||
│ └── Advanced Analytics │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Distribution
|
||||
|
||||
### Free Version Features
|
||||
|
||||
#### Core Writing Pipeline
|
||||
| Feature | Description | Strategic Value |
|
||||
|---------|-------------|-----------------|
|
||||
| Planning Mode | AI-powered article outline creation | Core value prop |
|
||||
| Writing Mode | Generate full articles with context | Core value prop |
|
||||
| Chat Mode | Quick AI assistance | Engagement driver |
|
||||
| Refinement Mode | Basic content polishing | Entry to refinement |
|
||||
| @mention Detection | Link to related posts | Unique capability |
|
||||
| Clarification Quiz | Guided topic extraction | User onboarding |
|
||||
| Focus Keyword | SEO-first writing | Differentiation |
|
||||
|
||||
#### Model Integration
|
||||
| Feature | Description | Strategic Value |
|
||||
|---------|-------------|-----------------|
|
||||
| OpenRouter Integration | Access to 100+ models | Flexibility |
|
||||
| Model Selection UI | Easy model switching | Usability |
|
||||
| Preset Configurations | Budget/Balanced/Premium | Quick start |
|
||||
| Cost Estimation | Real-time cost display | Budget control |
|
||||
|
||||
#### Analytics & Tracking
|
||||
| Feature | Description | Strategic Value |
|
||||
|---------|-------------|-----------------|
|
||||
| Cost Log | Basic usage tracking | Transparency |
|
||||
| Token Usage | Input/output tracking | Optimization |
|
||||
| Daily/Monthly Stats | Usage overview | Awareness |
|
||||
|
||||
#### Technical Foundation
|
||||
| Feature | Description | Strategic Value |
|
||||
|---------|-------------|-----------------|
|
||||
| Gutenberg Integration | Block editor sidebar | Core integration |
|
||||
| Classic Editor Support | Alternative UI | Coverage |
|
||||
| Shortcode Support | Flexible embedding | Versatility |
|
||||
| REST API Endpoints | Developer hooks | Ecosystem |
|
||||
| WebSocket Status | Real-time updates | Polish |
|
||||
|
||||
---
|
||||
|
||||
### Pro Addon Features
|
||||
|
||||
#### Advanced Refinement (Multi-Pass)
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| Multi-Pass Refinement | 3-stage polishing (clarity, SEO, quality) | High |
|
||||
| Keyword Density Optimization | Automatic SEO improvement | High |
|
||||
| Readability Scoring | Flesch-Kincaid integration | Medium |
|
||||
| Plagiarism Check | Integration with Copyscape API | Premium |
|
||||
| Brand Voice Training | Learn from existing content | Premium |
|
||||
|
||||
#### External Integrations
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| Brave Search Integration | Real-time web research | High |
|
||||
| Image Generation (DALL-E 3) | AI-generated featured images | High |
|
||||
| Image Generation (SDXL) | Stable Diffusion XL | Premium |
|
||||
| Unsplash Integration | Stock photo search | Medium |
|
||||
| WordPress Media Library | Direct image management | Medium |
|
||||
|
||||
#### Local Backend (Extended)
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| LM Studio Support (Full) | Complete integration | Medium |
|
||||
| Ollama Support (Full) | Complete integration | Medium |
|
||||
| Self-Hosted Models | Custom model hosting | Premium |
|
||||
| Multi-Instance Support | Multiple backend servers | Premium |
|
||||
| Load Balancing | Automatic failover | Premium |
|
||||
|
||||
#### Collaboration & Team
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| Team Workspaces | Shared configurations | Premium |
|
||||
| User Roles & Permissions | Role-based access | Premium |
|
||||
| Activity Logs | Audit trails | Medium |
|
||||
| Template Sharing | Team templates | Medium |
|
||||
| Content Approvals | Workflow integration | Premium |
|
||||
|
||||
#### Advanced Analytics
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| ROI Calculator | Content performance vs cost | Medium |
|
||||
| Content Performance | SEO ranking tracking | Premium |
|
||||
| A/B Testing | Headline variations | Premium |
|
||||
| Seasonal Trends | Content calendar | Premium |
|
||||
|
||||
#### Priority Support
|
||||
| Feature | Description | Value |
|
||||
|---------|-------------|-------|
|
||||
| Email Support | Direct assistance | Medium |
|
||||
| Priority Response | 24hr vs 7 days | Medium |
|
||||
| Feature Requests | Influence roadmap | Low |
|
||||
| Custom Integrations | Bespoke solutions | Premium |
|
||||
|
||||
---
|
||||
|
||||
## Hook System Architecture
|
||||
|
||||
### Purpose
|
||||
The free version provides comprehensive hooks that both Pro addon and third-party developers can use to extend functionality.
|
||||
|
||||
### Hook Types
|
||||
|
||||
#### 1. Action Hooks (Events)
|
||||
```php
|
||||
// Writing lifecycle
|
||||
do_action('wpaw_before_generate', $post_id, $mode);
|
||||
do_action('wpaw_after_generate', $post_id, $mode, $content);
|
||||
do_action('wpaw_planning_started', $post_id);
|
||||
do_action('wpaw_planning_complete', $post_id, $plan);
|
||||
do_action('wpaw_writing_started', $post_id, $section_index);
|
||||
do_action('wpaw_writing_section_complete', $post_id, $section_index, $content);
|
||||
do_action('wpaw_refinement_started', $post_id);
|
||||
do_action('wpaw_refinement_complete', $post_id, $refined_content);
|
||||
|
||||
// Model interactions
|
||||
do_action('wpaw_model_selected', $model_id, $task_type);
|
||||
do_action('wpaw_api_request_sent', $model_id, $tokens, $cost);
|
||||
do_action('wpaw_api_response_received', $model_id, $response_time);
|
||||
|
||||
// Context management
|
||||
do_action('wpaw_context_loaded', $post_id, $context_data);
|
||||
do_action('wpaw_context_updated', $post_id, $changes);
|
||||
|
||||
// Cost tracking
|
||||
do_action('wpaw_cost_recorded', $record);
|
||||
do_action('wpaw_daily_limit_reached', $total_cost);
|
||||
```
|
||||
|
||||
#### 2. Filter Hooks (Data Modification)
|
||||
```php
|
||||
// Context modification
|
||||
add_filter('wpaw_context_data', 'modify_context', 10, 2);
|
||||
add_filter('wpaw_post_content', 'process_content', 10, 2);
|
||||
add_filter('wpaw_planning_prompt', 'customize_planning', 10, 2);
|
||||
|
||||
// Model selection
|
||||
add_filter('wpaw_model_for_task', 'override_model', 10, 3);
|
||||
add_filter('wpaw_model_parameters', 'customize_params', 10, 2);
|
||||
|
||||
// Output modification
|
||||
add_filter('wpaw_generated_content', 'post_process', 10, 3);
|
||||
add_filter('wpaw_refinement_criteria', 'custom_criteria', 10, 2);
|
||||
|
||||
// Cost calculations
|
||||
add_filter('wpaw_cost_calculation', 'adjust_cost', 10, 2);
|
||||
add_filter('wpaw_token_count', 'modify_tokens', 10, 2);
|
||||
```
|
||||
|
||||
#### 3. REST API Endpoints
|
||||
```
|
||||
POST /wpaw/v1/generate
|
||||
- Generate content via API
|
||||
- Authentication: API key or OAuth
|
||||
|
||||
POST /wpaw/v1/refine
|
||||
- Refine existing content
|
||||
- Parameters: content, criteria, iterations
|
||||
|
||||
GET /wpaw/v1/cost-log
|
||||
- Retrieve cost tracking data
|
||||
- Filters: date range, post_id, model
|
||||
|
||||
GET /wpaw/v1/models
|
||||
- List available models
|
||||
- Include pricing and capabilities
|
||||
|
||||
POST /wpaw/v1/context
|
||||
- Update context for specific post
|
||||
```
|
||||
|
||||
#### 4. JavaScript Events (Frontend)
|
||||
```javascript
|
||||
// jQuery / DOM Events
|
||||
document.dispatchEvent(new CustomEvent('wpaw:generation-start', {
|
||||
detail: { postId, mode }
|
||||
}));
|
||||
|
||||
document.dispatchEvent(new CustomEvent('wpaw:generation-complete', {
|
||||
detail: { postId, content, cost }
|
||||
}));
|
||||
|
||||
document.dispatchEvent(new CustomEvent('wpaw:section-written', {
|
||||
detail: { postId, sectionIndex, content }
|
||||
}));
|
||||
|
||||
// React component hooks (for sidebar)
|
||||
window.wpawHooks = {
|
||||
onBeforeGenerate: (postId, mode) => {},
|
||||
onAfterGenerate: (postId, mode, content) => {},
|
||||
onModelSelected: (modelId, taskType) => {},
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Licensing System
|
||||
|
||||
### Pro Addon Structure
|
||||
|
||||
#### License Types
|
||||
| Type | Price Point | Activations | Features |
|
||||
|------|-------------|-------------|----------|
|
||||
| Personal | $49/year | 1 site | All Pro features |
|
||||
| Professional | $99/year | 5 sites | All Pro + priority support |
|
||||
| Agency | $199/year | 25 sites | All Pro + team features |
|
||||
| Enterprise | Custom | Unlimited | White-label + SLA |
|
||||
|
||||
#### License Verification Flow
|
||||
```
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ User │ │ Pro Addon │ │ License │
|
||||
│ Activates │────▶│ Checks │────▶│ Server │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │
|
||||
│ Valid? │
|
||||
▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Enable Pro │ │ Response: │
|
||||
│ Features │◀────│ key, expiry, │
|
||||
└──────────────┘ │ features │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### License Server Requirements
|
||||
|
||||
#### Endpoints
|
||||
```
|
||||
POST /api/v1/verify
|
||||
- Input: license_key, domain, product_id
|
||||
- Output: { valid: bool, expires: date, features: [] }
|
||||
|
||||
POST /api/v1/activate
|
||||
- Input: license_key, domain
|
||||
- Output: { activation_id, sites_used, sites_limit }
|
||||
|
||||
POST /api/v1/deactivate
|
||||
- Input: activation_id
|
||||
- Output: { success: bool }
|
||||
|
||||
GET /api/v1/status
|
||||
- Input: license_key
|
||||
- Output: { active: bool, sites: [], expires: date }
|
||||
```
|
||||
|
||||
#### Security Measures
|
||||
- License key hashed with SHA-256 before storage
|
||||
- Domain binding prevents key sharing
|
||||
- Activation limit enforcement
|
||||
- Automatic deactivation on payment failure
|
||||
- IP-based rate limiting on verification
|
||||
|
||||
---
|
||||
|
||||
## Migration Path
|
||||
|
||||
### Upgrading from Free to Pro
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ Step 1: User purchases Pro license │
|
||||
│ └── Receives license key via email │
|
||||
│ │
|
||||
│ Step 2: User installs Pro Addon │
|
||||
│ └── Upload via WordPress admin │
|
||||
│ └── Activates alongside free plugin │
|
||||
│ │
|
||||
│ Step 3: User enters license key │
|
||||
│ └── Addon validates against license server │
|
||||
│ └── Activates on current domain │
|
||||
│ │
|
||||
│ Step 4: Pro features unlocked │
|
||||
│ └── UI shows Pro indicators │
|
||||
│ └── New tabs/options become visible │
|
||||
│ └── Settings synced from free version │
|
||||
│ │
|
||||
│ Step 5: Deactivate/reactivate │
|
||||
│ └── Can transfer license to new domain │
|
||||
│ └── Previous site features disabled │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Data Migration
|
||||
- Settings stored in `wp_options` - shared between free and pro
|
||||
- Pro settings prefixed with `wpaw_pro_`
|
||||
- Cost tracking uses unified table structure
|
||||
- No data loss during upgrade
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
### Free Plugin (WordPress.org)
|
||||
```
|
||||
wp-agentic-writer/
|
||||
├── wp-agentic-writer.php # Main plugin file
|
||||
├── readme.txt # WordPress.org readme
|
||||
├── uninstall.php # Clean uninstall
|
||||
├── includes/
|
||||
│ ├── class-plugin.php # Core plugin class
|
||||
│ ├── class-settings.php # Settings page
|
||||
│ ├── class-gutenberg-sidebar.php # Sidebar UI
|
||||
│ ├── providers/
|
||||
│ │ └── class-openrouter-provider.php
|
||||
│ └── helpers/
|
||||
│ └── class-context-manager.php
|
||||
├── assets/
|
||||
│ ├── css/
|
||||
│ │ ├── agentic-variables.css
|
||||
│ │ ├── agentic-components.css
|
||||
│ │ └── agentic-workflow.css
|
||||
│ └── js/
|
||||
│ └── sidebar.js
|
||||
├── views/
|
||||
│ └── settings/
|
||||
└── lang/
|
||||
└── wp-agentic-writer.pot
|
||||
```
|
||||
|
||||
### Pro Addon
|
||||
```
|
||||
wp-agentic-writer-pro/
|
||||
├── wp-agentic-writer-pro.php # Main addon file
|
||||
├── includes/
|
||||
│ ├── class-license-manager.php # License verification
|
||||
│ ├── class-pro-features.php # Feature toggles
|
||||
│ ├── providers/
|
||||
│ │ ├── class-brave-search.php
|
||||
│ │ └── class-image-generator.php
|
||||
│ ├── refinement/
|
||||
│ │ └── class-multi-pass-refinement.php
|
||||
│ └── analytics/
|
||||
│ └── class-pro-analytics.php
|
||||
└── admin/
|
||||
└── class-pro-admin.php # Pro settings UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
### Pre-Release Validation
|
||||
|
||||
#### Free Version
|
||||
- [ ] Works with WordPress 6.0+ (latest stable)
|
||||
- [ ] Works with PHP 7.4+ (minimum) and 8.x (recommended)
|
||||
- [ ] No PHP errors/warnings in debug mode
|
||||
- [ ] All hooks documented and functional
|
||||
- [ ] Settings page renders correctly
|
||||
- [ ] Sidebar works in Gutenberg and Classic
|
||||
- [ ] Uninstall removes all plugin data
|
||||
- [ ] Internationalization (i18n) complete
|
||||
|
||||
#### Pro Addon
|
||||
- [ ] Gracefully fails without license
|
||||
- [ ] Shows upgrade prompts for locked features
|
||||
- [ ] License verification works offline (cached)
|
||||
- [ ] Reactivation works correctly
|
||||
- [ ] No errors when free plugin inactive
|
||||
- [ ] License expiry handled gracefully
|
||||
|
||||
---
|
||||
|
||||
## Rollout Strategy
|
||||
|
||||
### Phase 1: Preparation (Week 1-2)
|
||||
1. Finalize Pro feature set
|
||||
2. Set up license server infrastructure
|
||||
3. Create Pro addon codebase
|
||||
4. Prepare marketing copy
|
||||
|
||||
### Phase 2: Soft Launch (Week 3)
|
||||
1. Release free plugin to limited beta
|
||||
2. Test with 10-20 trusted users
|
||||
3. Gather feedback and fix critical issues
|
||||
|
||||
### Phase 3: WordPress.org Submission (Week 4)
|
||||
1. Prepare WordPress.org assets (banner, icons)
|
||||
2. Write compliant readme.txt
|
||||
3. Submit for review
|
||||
4. Address review feedback (typically 1-2 weeks)
|
||||
|
||||
### Phase 4: Pro Launch (Week 6-8)
|
||||
1. Launch license server
|
||||
2. Create sales page
|
||||
3. Set up payment processing
|
||||
4. Launch Pro addon
|
||||
|
||||
### Phase 5: Marketing (Ongoing)
|
||||
1. Blog posts on AI writing tools
|
||||
2. Tutorial videos on YouTube
|
||||
3. Guest posts on WordPress blogs
|
||||
4. Community forum engagement
|
||||
|
||||
---
|
||||
|
||||
## Pricing Considerations
|
||||
|
||||
### Factors for Pricing
|
||||
| Factor | Consideration |
|
||||
|--------|---------------|
|
||||
| Competition | Compare to AI writing plugins ($49-$299/year) |
|
||||
| Value Delivered | Pro features save X hours/month |
|
||||
| Market Position | Mid-tier vs premium |
|
||||
| Support Costs | Personal vs team tier |
|
||||
|
||||
### Recommended Pricing
|
||||
| Tier | Price | Rationale |
|
||||
|------|-------|-----------|
|
||||
| Personal | $49/year | ~$4/month - impulse purchase |
|
||||
| Professional | $99/year | ~$8/month - small business |
|
||||
| Agency | $199/year | ~$8/site/year - good value |
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
### Technical Risks
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| License server downtime | Cache verification locally (7 days) |
|
||||
| Key sharing | Domain binding + monitoring |
|
||||
| WordPress.org policy violation | Clear separation of free/pro |
|
||||
| Competition | Focus on unique value props |
|
||||
|
||||
### Business Risks
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Low adoption | Start with strong free feature set |
|
||||
| Support overload | Tiered support, clear documentation |
|
||||
| Piracy | Regular audits, IP monitoring |
|
||||
| Negative reviews | Proactive beta testing |
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
### Free Version
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| WordPress.org downloads (6 months) | 5,000+ |
|
||||
| Active installations | 2,000+ |
|
||||
| 5-star rating | 4.5+ |
|
||||
| Support forum engagement | <10% of installs |
|
||||
|
||||
### Pro Version
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Conversion rate (free→pro) | 2-5% |
|
||||
| Monthly revenue (year 1) | $500-$1,000 |
|
||||
| License renewals | 60%+ |
|
||||
| Customer satisfaction | 4.0+ |
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Last Updated:** 2026-05-17
|
||||
**Author:** Claude (AI Assistant)
|
||||
662
docs/features/WP70_AI_INTEGRATION_STRATEGY.md
Normal file
662
docs/features/WP70_AI_INTEGRATION_STRATEGY.md
Normal file
@@ -0,0 +1,662 @@
|
||||
# WordPress 7.0 AI Integration Strategy
|
||||
|
||||
**Document:** WP Agentic Writer Integration with WordPress 7.0 Native AI
|
||||
**Date:** 2026-05-17
|
||||
**Status:** 📋 ANALYSIS COMPLETE
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
WordPress 7.0 (released April 9, 2026) introduces a native AI infrastructure that fundamentally changes how AI features work in WordPress. This document analyzes:
|
||||
|
||||
1. What WordPress 7.0 brings natively for AI
|
||||
2. How WP Agentic Writer currently implements AI
|
||||
3. Integration opportunities to eliminate duplicate setup
|
||||
4. Strategic recommendations for unified AI experience
|
||||
|
||||
**Key Finding:** WordPress 7.0 introduces the **AI Client SDK** and **Connectors screen** - exactly what WP Agentic Writer needs to leverage instead of maintaining its own provider configuration.
|
||||
|
||||
---
|
||||
|
||||
## WordPress 7.0 AI Features Overview
|
||||
|
||||
### 1. AI Client SDK (Core)
|
||||
|
||||
WordPress 7.0 ships with a built-in, provider-agnostic AI client:
|
||||
|
||||
```php
|
||||
// The entry point - all AI calls go through this
|
||||
$builder = wp_ai_client_prompt();
|
||||
|
||||
// Text generation
|
||||
$text = wp_ai_client_prompt( 'Summarize this content.' )
|
||||
->using_temperature( 0.7 )
|
||||
->generate_text();
|
||||
|
||||
// Image generation
|
||||
$image = wp_ai_client_prompt( 'A futuristic WordPress logo' )
|
||||
->generate_image();
|
||||
|
||||
// Feature detection (no API calls)
|
||||
if ( $builder->is_supported_for_text_generation() ) {
|
||||
// Show text generation UI
|
||||
}
|
||||
```
|
||||
|
||||
**Key Features:**
|
||||
- Provider-agnostic (works with OpenAI, Anthropic, Google)
|
||||
- Multimodal (text, image, audio, video)
|
||||
- JSON schema support for structured responses
|
||||
- Feature detection without API calls
|
||||
- REST API integration built-in
|
||||
- Hook system for security (`wp_ai_client_prevent_prompt` filter)
|
||||
|
||||
### 2. Connectors Screen (Core)
|
||||
|
||||
A new WordPress core screen for AI provider configuration:
|
||||
- Centralized credentials storage
|
||||
- Provider selection UI
|
||||
- One place for ALL AI settings
|
||||
- Replaces per-plugin API key management
|
||||
|
||||
**Available Provider Packages:**
|
||||
- `wp-openai-connector` - OpenAI models
|
||||
- `wp-anthropic-connector` - Claude models
|
||||
- `wp-google-ai-connector` - Gemini models
|
||||
|
||||
### 3. Abilities API
|
||||
|
||||
Standardized way to register AI capabilities:
|
||||
|
||||
```php
|
||||
// Register a custom ability
|
||||
register_ai_ability( 'my-plugin', 'generate-alt-text', array(
|
||||
'label' => 'Generate alt text',
|
||||
'description' => 'AI-powered alt text generation',
|
||||
'callback' => 'my_generate_alt_text',
|
||||
) );
|
||||
```
|
||||
|
||||
Abilities become tool-callable by AI models natively, enabling:
|
||||
- Cross-plugin AI coordination
|
||||
- Centralized AI governance
|
||||
- Audit logging of AI operations
|
||||
|
||||
### 4. Built-in AI Features (WordPress AI Assistant)
|
||||
|
||||
WordPress 7.0 includes basic AI features:
|
||||
- Title generation
|
||||
- Excerpt generation
|
||||
- Image creation
|
||||
- Alt text generation
|
||||
- Summarization
|
||||
|
||||
---
|
||||
|
||||
## Current WP Agentic Writer Architecture
|
||||
|
||||
### AI Provider Integration
|
||||
|
||||
WP Agentic Writer currently manages its own:
|
||||
- Provider selection (OpenRouter, Local Backend, Codex)
|
||||
- API key storage
|
||||
- Model selection
|
||||
- Cost tracking
|
||||
- Request handling
|
||||
|
||||
### Components with Custom AI Logic
|
||||
|
||||
| Component | Current AI Implementation |
|
||||
|-----------|---------------------------|
|
||||
| Chat Handler | Own API calls via OpenRouter |
|
||||
| Content Generation | Own streaming implementation |
|
||||
| Refinement | Own refinement endpoints |
|
||||
| SEO Audit | Own API calls for analysis |
|
||||
| Intent Detection | Own clarification flow |
|
||||
| Context Optimization | Own summarization |
|
||||
| Image Generation | Own DALL-E/SDXL integration |
|
||||
|
||||
### Settings Architecture
|
||||
|
||||
```
|
||||
Settings Page
|
||||
├── General Tab
|
||||
│ ├── OpenRouter API Key
|
||||
│ ├── Default Model
|
||||
│ └── Monthly Budget
|
||||
├── Providers Tab
|
||||
│ ├── OpenRouter Configuration
|
||||
│ ├── Local Backend URL
|
||||
│ └── Codex Settings
|
||||
└── Advanced Tab
|
||||
└── Custom Model Presets
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration Opportunities
|
||||
|
||||
### Phase 1: Leverage WordPress AI Client SDK
|
||||
|
||||
**What:** Replace internal AI calls with `wp_ai_client_prompt()`
|
||||
|
||||
**Benefits:**
|
||||
- Single API key configuration
|
||||
- Built-in rate limiting
|
||||
- Automatic retry logic
|
||||
- Unified cost tracking
|
||||
- Provider fallback support
|
||||
|
||||
**Implementation:**
|
||||
```php
|
||||
// Before: Custom implementation
|
||||
$response = $this->openrouter_provider->chat($messages, $params, $task);
|
||||
|
||||
// After: Use WordPress AI Client
|
||||
$builder = wp_ai_client_prompt()
|
||||
->with_text($prompt)
|
||||
->using_model_preference('claude-sonnet-4-6', 'gpt-4o', 'gemini-2.5')
|
||||
->using_temperature($temperature);
|
||||
|
||||
$result = $builder->generate_text_result();
|
||||
```
|
||||
|
||||
### Phase 2: Connectors Integration
|
||||
|
||||
**What:** Use WordPress Connectors instead of custom provider settings
|
||||
|
||||
**Migration Path:**
|
||||
1. Detect if WordPress 7.0+ with AI Client is available
|
||||
2. If available, use `wp_ai_client_prompt()` as primary
|
||||
3. Fall back to custom implementation for advanced features not in core
|
||||
4. Deprecate custom API key fields (show migration notice)
|
||||
|
||||
**Backward Compatibility:**
|
||||
```php
|
||||
// Check if WordPress AI Client is available
|
||||
if ( function_exists( 'wp_ai_client_prompt' ) ) {
|
||||
// Use WordPress AI Client
|
||||
} else {
|
||||
// Use legacy OpenRouter implementation
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 3: Abilities API Registration
|
||||
|
||||
**What:** Register WP Agentic Writer abilities for coordination
|
||||
|
||||
```php
|
||||
// Register advanced writing abilities
|
||||
register_ai_ability( 'wp-agentic-writer', 'article-generation', array(
|
||||
'label' => 'Generate Full Article',
|
||||
'description' => 'Generate a complete article with outline-based structure',
|
||||
'modalities' => array( 'text' ),
|
||||
) );
|
||||
|
||||
register_ai_ability( 'wp-agentic-writer', 'content-refinement', array(
|
||||
'label' => 'Refine Content',
|
||||
'description' => 'Improve existing content for clarity, SEO, and quality',
|
||||
'modalities' => array( 'text' ),
|
||||
) );
|
||||
|
||||
register_ai_ability( 'wp-agentic-writer', 'outline-creation', array(
|
||||
'label' => 'Create Article Outline',
|
||||
'description' => 'Generate structured outline from topic description',
|
||||
'modalities' => array( 'text' ),
|
||||
) );
|
||||
```
|
||||
|
||||
### Phase 4: Unified Settings Experience
|
||||
|
||||
**What:** Merge with WordPress Connectors screen
|
||||
|
||||
| Current (Plugin Settings) | WordPress 7.0 Native |
|
||||
|--------------------------|---------------------|
|
||||
| OpenRouter API Key | Via Connectors |
|
||||
| Model Selection | Via Connectors + Preferences |
|
||||
| Cost Tracking | Shared infrastructure |
|
||||
| Monthly Budget | User preference |
|
||||
|
||||
**Recommendation:** Keep advanced features in plugin settings (local backend, custom presets), use core for standard AI operations.
|
||||
|
||||
---
|
||||
|
||||
## Feature Comparison Matrix
|
||||
|
||||
| Feature | WP 7.0 Native | WP Agentic Writer | Integration Strategy |
|
||||
|---------|---------------|-------------------|---------------------|
|
||||
| Basic text generation | ✅ | ✅ | Use core |
|
||||
| Basic image generation | ✅ | ✅ | Use core for simple, plugin for advanced |
|
||||
| Title generation | ✅ | ✅ | Use core |
|
||||
| Excerpt generation | ✅ | ✅ | Use core |
|
||||
| Alt text generation | ✅ | ✅ | Use core |
|
||||
| Streaming responses | ❌ | ✅ | Keep in plugin |
|
||||
| Complex prompts | ❌ | ✅ | Keep in plugin |
|
||||
| Article planning | ❌ | ✅ | Keep in plugin |
|
||||
| Multi-section writing | ❌ | ✅ | Keep in plugin |
|
||||
| Block-level refinement | ❌ | ✅ | Keep in plugin |
|
||||
| SEO optimization | ❌ | ✅ | Keep in plugin |
|
||||
| GEO scoring | ❌ | ✅ | Keep in plugin |
|
||||
| Context management | ❌ | ✅ | Keep in plugin |
|
||||
| @mention system | ❌ | ✅ | Keep in plugin |
|
||||
| Cost tracking | Basic | Advanced | Plugin tracks, core provides infrastructure |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Architecture
|
||||
|
||||
### Unified AI Layer
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ WP AGENTIC WRITER │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ FRONTEND (Gutenberg Sidebar) │
|
||||
│ ├── Planning Mode (outline creation) │
|
||||
│ ├── Writing Mode (section-by-section) │
|
||||
│ ├── Refinement Mode (block targeting) │
|
||||
│ ├── SEO Mode (audit & optimization) │
|
||||
│ └── GEO Mode (AI Overview scoring) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ BACKEND AI LAYER (Hybrid) │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
||||
│ │ WordPress Core │ │ Plugin-Specific Logic │ │
|
||||
│ │ AI Client SDK │ │ • Streaming responses │ │
|
||||
│ │ (Basic Tasks) │ │ • Article pipeline │ │
|
||||
│ │ • Title/Excerpt │ │ • Block refinement │ │
|
||||
│ │ • Alt text │ │ • SEO/GEO analysis │ │
|
||||
│ │ • Summaries │ │ • Context optimization │ │
|
||||
│ └────────┬─────────┘ │ • Cost tracking │ │
|
||||
│ │ └──────────────┬──────────────┘ │
|
||||
│ │ │ │
|
||||
│ └──────────┬──────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ CONNECTORS (Unified Credentials) │ │
|
||||
│ │ OpenAI │ Anthropic │ Google │ Local Backend │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Implementation Priority
|
||||
|
||||
| Priority | Task | Effort | Benefit |
|
||||
|----------|------|--------|---------|
|
||||
| 🔴 HIGH | Add WP AI Client detection | Low | Foundation |
|
||||
| 🔴 HIGH | Use `wp_ai_client_prompt()` for simple tasks | Medium | Eliminate duplicate setup |
|
||||
| 🟡 MEDIUM | Register Abilities API | Medium | Ecosystem integration |
|
||||
| 🟡 MEDIUM | Migrate settings to Connectors | High | Unified UX |
|
||||
| 🟢 LOW | Deprecate legacy provider code | Medium | Maintenance |
|
||||
|
||||
---
|
||||
|
||||
## Code Migration Examples
|
||||
|
||||
### 1. Simple AI Call Migration
|
||||
|
||||
**Before (Current Implementation):**
|
||||
```php
|
||||
public function generate_title( $content ) {
|
||||
$provider = WP_Agentic_Writer_Provider_Manager::get_provider_for_task( 'title' );
|
||||
$messages = array(
|
||||
array(
|
||||
'role' => 'user',
|
||||
'content' => "Generate a catchy title for: $content"
|
||||
)
|
||||
);
|
||||
$response = $provider->chat( $messages, array(), 'title_generation' );
|
||||
return $response['content'];
|
||||
}
|
||||
```
|
||||
|
||||
**After (With Core Integration):**
|
||||
```php
|
||||
public function generate_title( $content ) {
|
||||
// Check if WordPress AI Client is available
|
||||
if ( function_exists( 'wp_ai_client_prompt' ) ) {
|
||||
$result = wp_ai_client_prompt()
|
||||
->with_text( "Generate a catchy, SEO-friendly title (max 60 chars) for: $content" )
|
||||
->using_model_preference( 'claude-sonnet-4-6', 'gpt-4o' )
|
||||
->using_max_tokens( 50 )
|
||||
->generate_text();
|
||||
|
||||
if ( ! is_wp_error( $result ) ) {
|
||||
return $result->get_text();
|
||||
}
|
||||
}
|
||||
|
||||
// Fallback to legacy implementation
|
||||
return $this->legacy_generate_title( $content );
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Feature Detection
|
||||
|
||||
```php
|
||||
public function render_ai_controls() {
|
||||
$ai_available = function_exists( 'wp_ai_client_prompt' );
|
||||
$supports_text = false;
|
||||
$supports_images = false;
|
||||
|
||||
if ( $ai_available ) {
|
||||
$builder = wp_ai_client_prompt( 'test' );
|
||||
$supports_text = $builder->is_supported_for_text_generation();
|
||||
$supports_images = $builder->is_supported_for_image_generation();
|
||||
}
|
||||
|
||||
// Render appropriate UI based on capabilities
|
||||
?>
|
||||
<?php if ( $ai_available && $supports_text ) : ?>
|
||||
<p>AI features available via WordPress</p>
|
||||
<?php else : ?>
|
||||
<p>Configure AI in Settings → Connectors</p>
|
||||
<?php endif; ?>
|
||||
<?php
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Abilities Registration
|
||||
|
||||
```php
|
||||
public function register_ai_abilities() {
|
||||
if ( ! function_exists( 'register_ai_ability' ) ) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Article generation ability
|
||||
register_ai_ability( 'wp-agentic-writer', 'article-generation', array(
|
||||
'name' => 'article_generation',
|
||||
'label' => __( 'Generate Article', 'wp-agentic-writer' ),
|
||||
'description' => __( 'Generate a complete structured article from an outline', 'wp-agentic-writer' ),
|
||||
'input' => array(
|
||||
'outline' => array(
|
||||
'type' => 'string',
|
||||
'description' => 'Article outline in JSON format',
|
||||
'required' => true,
|
||||
),
|
||||
'focus_keyword' => array(
|
||||
'type' => 'string',
|
||||
'description' => 'SEO focus keyword',
|
||||
'required' => false,
|
||||
),
|
||||
),
|
||||
'output' => 'string',
|
||||
) );
|
||||
|
||||
// SEO analysis ability
|
||||
register_ai_ability( 'wp-agentic-writer', 'seo-analysis', array(
|
||||
'name' => 'seo_analysis',
|
||||
'label' => __( 'Analyze SEO', 'wp-agentic-writer' ),
|
||||
'description' => __( 'Analyze content for SEO optimization', 'wp-agentic-writer' ),
|
||||
'input' => 'string',
|
||||
'output' => 'object',
|
||||
) );
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Settings Migration Strategy
|
||||
|
||||
### Phase 1: Detection (Backward Compatible)
|
||||
|
||||
```php
|
||||
class WP_Agentic_Writer_Settings {
|
||||
public function __construct() {
|
||||
$this->ai_client_available = function_exists( 'wp_ai_client_prompt' );
|
||||
}
|
||||
|
||||
public function render_api_settings() {
|
||||
if ( $this->ai_client_available ) {
|
||||
$this->render_unified_settings();
|
||||
} else {
|
||||
$this->render_legacy_settings();
|
||||
}
|
||||
}
|
||||
|
||||
private function render_unified_settings() {
|
||||
?>
|
||||
<div class="wpaw-settings-section">
|
||||
<h3><?php _e( 'AI Configuration', 'wp-agentic-writer' ); ?></h3>
|
||||
<p>
|
||||
<?php _e( 'WP Agentic Writer uses WordPress 7.0 AI infrastructure. Configure your AI provider in', 'wp-agentic-writer' ); ?>
|
||||
<a href="<?php echo admin_url( 'admin.php?page=ai-connectors' ); ?>">
|
||||
<?php _e( 'Settings → Connectors', 'wp-agentic-writer' ); ?>
|
||||
</a>.
|
||||
</p>
|
||||
|
||||
<?php $this->render_advanced_settings(); ?>
|
||||
</div>
|
||||
<?php
|
||||
}
|
||||
|
||||
private function render_advanced_settings() {
|
||||
// Keep plugin-specific settings only
|
||||
?>
|
||||
<h4><?php _e( 'Agentic Writer Advanced', 'wp-agentic-writer' ); ?></h4>
|
||||
<?php
|
||||
$this->render_setting( 'local_backend_url', 'Local Backend URL' );
|
||||
$this->render_setting( 'custom_model_presets', 'Custom Model Presets' );
|
||||
$this->render_setting( 'monthly_budget', 'Monthly Budget' );
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Settings Sync
|
||||
|
||||
```php
|
||||
public function sync_with_wordpress_ai() {
|
||||
if ( ! $this->ai_client_available ) {
|
||||
return;
|
||||
}
|
||||
|
||||
// Get WordPress AI settings
|
||||
$wp_ai_settings = get_option( 'wp_ai_settings', array() );
|
||||
|
||||
// Sync to plugin settings for internal use
|
||||
if ( ! empty( $wp_ai_settings['active_provider'] ) ) {
|
||||
update_option( 'wpaw_active_provider', $wp_ai_settings['active_provider'] );
|
||||
}
|
||||
|
||||
if ( ! empty( $wp_ai_settings['default_model'] ) ) {
|
||||
update_option( 'wpaw_default_model', $wp_ai_settings['default_model'] );
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Governance & Compliance
|
||||
|
||||
### WordPress 7.0 Security Features
|
||||
|
||||
| Feature | WP Agentic Writer Use Case |
|
||||
|---------|---------------------------|
|
||||
| `wp_ai_client_prevent_prompt` filter | Restrict AI features by user role |
|
||||
| Audit logging | Track AI operations for compliance |
|
||||
| Centralized credentials | Single point for API key management |
|
||||
| Provider abstraction | Easy provider switching without code changes |
|
||||
|
||||
### Implementation Example
|
||||
|
||||
```php
|
||||
// Restrict AI writing features to editors and above
|
||||
add_filter( 'wp_ai_client_prevent_prompt', function( $prevent, $builder ) {
|
||||
$ability = $builder->get_ability_name();
|
||||
|
||||
// Check if this is an Agentic Writer ability
|
||||
if ( strpos( $ability, 'wp-agentic-writer' ) === 0 ) {
|
||||
// Require editor role for article generation
|
||||
if ( ! current_user_can( 'edit_posts' ) ) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
return $prevent;
|
||||
}, 10, 2 );
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Competition Analysis
|
||||
|
||||
### How WP Agentic Writer Differs from Native Features
|
||||
|
||||
| WordPress AI Assistant | WP Agentic Writer |
|
||||
|-----------------------|-------------------|
|
||||
| Basic title/excerpt | Full article pipeline |
|
||||
| Simple prompts | Context-aware generation |
|
||||
| No outline | Outline-based writing |
|
||||
| No refinement | Block-level refinement |
|
||||
| No SEO/GEO | Complete SEO optimization |
|
||||
| Generic AI | Writing-specialized AI |
|
||||
| Single-shot | Multi-session workflow |
|
||||
|
||||
### Competitive Position
|
||||
|
||||
**WP Agentic Writer Advantage:**
|
||||
- Sophisticated writing workflow (planning → writing → refinement)
|
||||
- Block-level targeting with @mentions
|
||||
- SEO + GEO optimization
|
||||
- Context management across sessions
|
||||
- Cost tracking and budget control
|
||||
- Local backend support (privacy-first)
|
||||
|
||||
**Opportunity:**
|
||||
WordPress 7.0 AI is basic. WP Agentic Writer fills the gap for serious content creators who need more than titles and excerpts.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
```
|
||||
Phase 1: Foundation (Week 1-2)
|
||||
├── Add WP AI Client detection helper
|
||||
├── Create backward-compatible wrapper class
|
||||
├── Migrate simple tasks (title, excerpt) to core
|
||||
└── Test fallback to legacy implementation
|
||||
|
||||
Phase 2: Abilities (Week 3-4)
|
||||
├── Register custom abilities with WordPress
|
||||
├── Create ability handlers for advanced features
|
||||
├── Enable cross-plugin AI coordination
|
||||
└── Update documentation
|
||||
|
||||
Phase 3: Settings (Week 5-6)
|
||||
├── Add migration notice for users upgrading to WP 7.0
|
||||
├── Create unified settings UI
|
||||
├── Deprecate legacy provider fields
|
||||
└── Add Connectors link and guidance
|
||||
|
||||
Phase 4: Advanced Features (Week 7-8)
|
||||
├── Keep streaming for article generation
|
||||
├── Keep block refinement logic
|
||||
├── Keep SEO/GEO analysis
|
||||
└── Use core for all basic AI operations
|
||||
|
||||
Phase 5: Cleanup (Week 9-10)
|
||||
├── Remove legacy code paths
|
||||
├── Update provider manager architecture
|
||||
├── Finalize settings migration
|
||||
└── Publish integration documentation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### Backward Compatibility
|
||||
|
||||
```php
|
||||
// Always check for WordPress AI Client
|
||||
if ( function_exists( 'wp_ai_client_prompt' ) ) {
|
||||
// Use new approach
|
||||
} else {
|
||||
// Use legacy approach (WP < 7.0 or no connectors)
|
||||
}
|
||||
|
||||
// Check specific capabilities
|
||||
$supports_streaming = ! function_exists( 'wp_ai_client_prompt' ); // Core doesn't support streaming yet
|
||||
```
|
||||
|
||||
### Performance
|
||||
|
||||
- WordPress AI Client adds HTTP overhead - cache responses
|
||||
- Plugin-specific features (streaming) remain faster for large content
|
||||
- Consider async processing for complex operations
|
||||
|
||||
### Testing
|
||||
|
||||
```php
|
||||
class WP_Agentic_Writer_Test {
|
||||
public function test_ai_client_integration() {
|
||||
// Test with core AI Client
|
||||
if ( function_exists( 'wp_ai_client_prompt' ) ) {
|
||||
$result = wp_ai_client_prompt( 'Test prompt' )->generate_text();
|
||||
$this->assertNotInstanceOf( 'WP_Error', $result );
|
||||
}
|
||||
|
||||
// Test fallback
|
||||
$result = $this->plugin->generate_text_legacy( 'Test prompt' );
|
||||
$this->assertNotEmpty( $result );
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Recommendations Summary
|
||||
|
||||
### Do
|
||||
|
||||
1. **Adopt WordPress AI Client** for all basic text generation tasks
|
||||
2. **Register Abilities** to integrate with the WordPress AI ecosystem
|
||||
3. **Keep advanced features** (streaming, refinement, SEO/GEO) in plugin
|
||||
4. **Unify settings** with Connectors screen where possible
|
||||
5. **Maintain backward compatibility** for WP < 7.0 users
|
||||
|
||||
### Don't
|
||||
|
||||
1. **Don't replace** the entire AI implementation with core
|
||||
2. **Don't duplicate** what WordPress does natively
|
||||
3. **Don't break existing features** for users without WP 7.0
|
||||
4. **Don't abandon** the specialized writing workflow
|
||||
|
||||
### Value Proposition After Integration
|
||||
|
||||
| Before | After Integration |
|
||||
|--------|-------------------|
|
||||
| Separate API keys | Single AI configuration |
|
||||
| Duplicate provider setup | Unified Connectors |
|
||||
| Basic AI features | Basic (core) + Advanced (plugin) |
|
||||
| Isolated AI operations | Coordinated AI ecosystem |
|
||||
| Plugin-specific governance | Platform-level governance |
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
WordPress 7.0's native AI infrastructure is a significant opportunity for WP Agentic Writer:
|
||||
|
||||
1. **Eliminate duplicate setup** - Use Connectors instead of custom API keys
|
||||
2. **Focus on differentiation** - Keep advanced writing features in plugin
|
||||
3. **Join the ecosystem** - Register abilities for cross-plugin coordination
|
||||
4. **Provide better UX** - Unified settings experience
|
||||
|
||||
The plugin remains essential for serious content creation workflows that require more than basic title and excerpt generation. WordPress core handles the foundation; WP Agentic Writer handles the writing expertise.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [WordPress 7.0 AI Client Documentation](https://make.wordpress.org/core/2026/03/24/introducing-the-ai-client-in-wordpress-7-0/)
|
||||
- [PHP AI Client GitHub](https://github.com/WordPress/php-ai-client)
|
||||
- [Abilities API Proposal](https://make.wordpress.org/core/2026/02/03/proposal-for-merging-wp-ai-client-into-wordpress-7-0/)
|
||||
- [AI in WordPress 2026 Guide](https://ost.agency/blog/wordpress-ai-guide-for-business-2026/)
|
||||
|
||||
---
|
||||
|
||||
**Document Version:** 1.0
|
||||
**Last Updated:** 2026-05-17
|
||||
**Author:** Claude (AI Assistant)
|
||||
716
docs/features/brief.md
Normal file
716
docs/features/brief.md
Normal file
@@ -0,0 +1,716 @@
|
||||
# WP Agentic Writer - Development Brief
|
||||
|
||||
**Product Name:** WP Agentic Writer
|
||||
**Tagline:** Plan-first AI writing workflow for WordPress
|
||||
**Target Users:** Developers, Technical Writers, Content Creators who struggle with blogging
|
||||
**Status:** MVP Development
|
||||
**Date Created:** January 17, 2026
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Product Overview
|
||||
|
||||
**WP Agentic Writer** is a WordPress plugin that transforms how developers and technical writers create blog posts. Instead of the traditional "blank page → write → edit" workflow, it implements a **multi-phase agentic AI workflow**:
|
||||
|
||||
```
|
||||
Scribble (Ideas) → Research → Plan (Outline) → Execute (Write) → Discussion/Revise
|
||||
```
|
||||
|
||||
**Key Insight:** Most developers never write articles because writing feels separate from coding. This plugin makes the workflow feel like coding—iterative, phase-based, with revision at every step.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Core Features (MVP)
|
||||
|
||||
### Phase 1: Brainstorm & Scribble
|
||||
- **User inputs:** Raw notes, code snippets, PR description, or vague idea
|
||||
- **AI does:** Clarifies the angle, suggests what problem this solves
|
||||
- **Output:** Structured brainstorm notes
|
||||
|
||||
### Phase 2: Research
|
||||
- **User inputs:** Confirms the angle or edits AI suggestions
|
||||
- **AI does:** Generates research queries, pulls relevant information (optional web search)
|
||||
- **Output:** Research notes, citations, key points
|
||||
- **Display:** Real-time cost tracking
|
||||
- **Web Search:** Optional toggle using OpenRouter's built-in web search (:online models)
|
||||
|
||||
### Phase 3: Plan (Outline)
|
||||
- **User inputs:** Reviews outline, suggests sections to add/remove/reorganize
|
||||
- **AI does:** Structures as JSON with H2 sections, suggests code examples
|
||||
- **Output:** Plan JSON (see structure below)
|
||||
- **Cost:** Minimal (using fast, cheap model like Gemini Flash)
|
||||
|
||||
### Phase 4: Execute (Auto-Write)
|
||||
- **User inputs:** Approves plan, clicks "Execute"
|
||||
- **AI does:** Generates final article with:
|
||||
- Paragraph blocks
|
||||
- Code blocks (with language detection)
|
||||
- Optional image prompts
|
||||
- **Output:** Gutenberg blocks inserted into editor canvas
|
||||
- **Cost:** Higher quality model (Claude Opus) for best output
|
||||
|
||||
### Phase 5: Discuss & Revise
|
||||
- **User inputs:** Click "Regenerate Section" on any block
|
||||
- **AI does:** Re-generates just that block based on selected text context
|
||||
- **Features:**
|
||||
- Section-level chat
|
||||
- Line-by-line refinement
|
||||
- Change entire paragraphs or code blocks
|
||||
|
||||
---
|
||||
|
||||
## 💰 Cost Architecture
|
||||
|
||||
### Models Strategy
|
||||
|
||||
**Planning Model:** `google/gemini-3-flash` (Free on OpenRouter)
|
||||
- Cost: ~$0.0007 per planning session
|
||||
- Speed: Very fast
|
||||
- Quality: Good enough for outlining
|
||||
|
||||
**Execution Model:** `anthropic/claude-4-opus` (Paid on OpenRouter)
|
||||
- Cost: ~$0.633 per full article write
|
||||
- Speed: Medium
|
||||
- Quality: Excellent prose, code understanding
|
||||
|
||||
**Image Generation Model:** `black-forest-labs/flux-schnell` (via fal.ai free tier or OpenRouter)
|
||||
- Cost: ~$0.04 per image (paid option)
|
||||
- Cost: $0.00 (free tier fal.ai with 100 credits/month = 25-50 images)
|
||||
- Speed: <2 seconds
|
||||
- Quality: Excellent for developer blogs
|
||||
|
||||
### Cost Breakdown Per Article (2,500 words)
|
||||
|
||||
```
|
||||
Planning (Gemini Flash): $0.0007 (free tier alternative: $0.00)
|
||||
Research (Web Search): $0.02 (optional, Exa search)
|
||||
Writing (Claude Opus): $0.633
|
||||
Image (Flux Schnell): $0.04 (free tier alternative: $0.00)
|
||||
OpenRouter platform fee: ~$0.034
|
||||
─────────────────────────────────────
|
||||
TOTAL: ~$0.72 per article (paid tier with research)
|
||||
TOTAL (No research): ~$0.70 per article (paid tier)
|
||||
TOTAL (Free tier): ~$0.00 per article
|
||||
```
|
||||
|
||||
### User Cost Scenarios
|
||||
|
||||
| User Type | Articles/Month | Paid Cost | Free Tier |
|
||||
|-----------|---|---|---|
|
||||
| **Solo Dev Blogger** | 10 | $7.00 | Free (limited) |
|
||||
| **Agency Content** | 50 | $35.00 | Free (limited) |
|
||||
| **Company Blog** | 200 | $140.00 | Free (limited) |
|
||||
|
||||
---
|
||||
|
||||
## 🔌 Integration: OpenRouter
|
||||
|
||||
### Why OpenRouter?
|
||||
|
||||
✅ **Single API Key** - No juggling Claude + Gemini + GPT
|
||||
✅ **Model Flexibility** - Switch models in settings, no code changes
|
||||
✅ **Unified Cost Tracking** - OpenRouter returns exact token costs per request
|
||||
✅ **25+ Free Models** - Full plugin works without credit card
|
||||
✅ **Built-in Web Search** - Add `:online` to any model for real-time research
|
||||
✅ **Transparent Pricing** - 5.5% platform fee on all models
|
||||
|
||||
### Settings Page (One Simple Input)
|
||||
|
||||
```
|
||||
WP Agentic Writer Settings
|
||||
├─ OpenRouter API Key: [___________________]
|
||||
├─ Planning Model: google/gemini-3-flash ▼
|
||||
├─ Execution Model: anthropic/claude-4-opus ▼
|
||||
├─ Image Model: black-forest-labs/flux-schnell ▼
|
||||
├─ Research Phase:
|
||||
│ ◉ Enable Web Search (~$0.02 per search)
|
||||
│ ○ Disabled (use LLM knowledge only)
|
||||
│ └─ Search Engine: [Auto ▼] (Native or Exa fallback)
|
||||
│ └─ Search Depth: [Medium ▼] (Low/Medium/High)
|
||||
└─ Cost Tracking: ON ✓
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Gutenberg Integration
|
||||
|
||||
### Sidebar Chat Interface
|
||||
|
||||
**During Planning:**
|
||||
```
|
||||
Sidebar shows:
|
||||
┌─────────────────────────────┐
|
||||
│ WP Agentic Writer │
|
||||
├─────────────────────────────┤
|
||||
│ │
|
||||
│ > I built a PHP plugin │
|
||||
│ that handles OAuth... │
|
||||
│ │
|
||||
│ < Agentic AI (Gemini) │
|
||||
│ Planning $0.0007 │
|
||||
│ This is really about │
|
||||
│ "Auth abstraction for │
|
||||
│ WordPress", correct? │
|
||||
│ │
|
||||
│ > Yes, exactly! │
|
||||
│ │
|
||||
│ [Regenerate Plan] [Execute] │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
**During Execution:**
|
||||
```
|
||||
Canvas shows:
|
||||
[Paragraph block] ← Regenerate This
|
||||
"Here's how OAuth works in WordPress..."
|
||||
|
||||
[Code block] ← Regenerate This
|
||||
function auth_provider() { ... }
|
||||
|
||||
[Paragraph block] ← Regenerate This
|
||||
"Notice the abstraction layer..."
|
||||
|
||||
Sidebar: "Article generated in 3.5s | Cost: $0.633"
|
||||
```
|
||||
|
||||
### Block Operations
|
||||
|
||||
**Each Gutenberg block gets:**
|
||||
- "Regenerate" button (re-runs AI for that section only)
|
||||
- "Refine" button (opens sidebar chat for that block)
|
||||
- Visual cost indicator per block
|
||||
|
||||
---
|
||||
|
||||
## 📊 Plan JSON Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "OAuth Plugin Architecture for WordPress",
|
||||
"meta": {
|
||||
"reading_time": "5 min",
|
||||
"difficulty": "intermediate",
|
||||
"cost_estimate": 0.70
|
||||
},
|
||||
"sections": [
|
||||
{
|
||||
"id": "intro",
|
||||
"type": "section",
|
||||
"heading": "The Problem: Auth Abstraction",
|
||||
"content": [
|
||||
{
|
||||
"type": "paragraph",
|
||||
"content": "Building flexible auth systems..."
|
||||
},
|
||||
{
|
||||
"type": "code",
|
||||
"language": "php",
|
||||
"content": "interface AuthProvider { ... }",
|
||||
"caption": "Provider interface pattern"
|
||||
},
|
||||
{
|
||||
"type": "paragraph",
|
||||
"content": "This pattern allows switching..."
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "implementation",
|
||||
"type": "section",
|
||||
"heading": "Step-by-Step Implementation",
|
||||
"content": [
|
||||
{
|
||||
"type": "ordered_list",
|
||||
"items": [
|
||||
"Define provider interface",
|
||||
"Implement concrete providers",
|
||||
"Create abstraction layer"
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "image_section",
|
||||
"type": "section",
|
||||
"image_prompt": "WordPress OAuth architecture diagram with abstraction layers, clean technical aesthetic, light colors",
|
||||
"image_alt": "OAuth architecture flowchart"
|
||||
}
|
||||
],
|
||||
"citations": [
|
||||
{
|
||||
"id": 1,
|
||||
"text": "OAuth 2.0 specification",
|
||||
"url": "https://..."
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 Cost Tracking Display
|
||||
|
||||
### Real-Time Sidebar
|
||||
|
||||
```
|
||||
Today's Usage:
|
||||
──────────────────────────
|
||||
Planning: 4,700 tokens $0.0007
|
||||
Writing: 7,500 tokens $0.633
|
||||
Images: 1 @ Flux $0.04
|
||||
──────────────────────────
|
||||
Session Total: $0.6737
|
||||
|
||||
Monthly Budget:
|
||||
Used: $6.74 / $600 (1.1%)
|
||||
Remaining: $593.26
|
||||
```
|
||||
|
||||
### Per-Request Cost
|
||||
|
||||
Each API call logs:
|
||||
- Model used
|
||||
- Tokens in/out
|
||||
- Cost (in real-time)
|
||||
- Cumulative session cost
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Web Search Strategy
|
||||
|
||||
### OpenRouter Built-in Web Search
|
||||
|
||||
**How it works:**
|
||||
- Append `:online` to any model slug: `google/gemini-3-flash:online`
|
||||
- OpenRouter automatically adds real-time web search results
|
||||
- Supports native search (OpenAI, Anthropic, Perplexity, xAI) or Exa fallback
|
||||
- Standardized citation format across all providers
|
||||
|
||||
### Cost Structure
|
||||
|
||||
| Search Type | Cost | Best For |
|
||||
|-------------|------|----------|
|
||||
| **No Search** | $0.00 | Evergreen topics, general knowledge |
|
||||
| **Native Search** | Provider pricing | Premium research (OpenAI, Anthropic models) |
|
||||
| **Exa Search** | $4 per 1,000 results = ~$0.02 per search | Most models, cost-effective research |
|
||||
|
||||
### Research Provider Options (Via OpenRouter)
|
||||
|
||||
| Option | Model | Cost | Quality | Best For |
|
||||
|--------|-------|------|---------|----------|
|
||||
| **Web Search ON** | `google/gemini-3-flash:online` | ~$0.02 + model cost | Real-time sources | Technical tutorials, recent topics |
|
||||
| **Web Search OFF** | `google/gemini-3-flash` | Model cost only | Training data | Evergreen topics |
|
||||
| **Premium Search** | `anthropic/claude-4-opus:online` | ~$0.05 + model cost | Best research | Professional articles |
|
||||
|
||||
### Implementation
|
||||
|
||||
```php
|
||||
// Research with web search toggle
|
||||
class OpenRouterProvider {
|
||||
private $web_search_enabled;
|
||||
private $search_engine = 'auto'; // native, exa, auto
|
||||
private $search_depth = 'medium'; // low, medium, high
|
||||
|
||||
public function research($query) {
|
||||
$model = $this->planning_model;
|
||||
|
||||
// Add :online suffix if web search enabled
|
||||
if ($this->web_search_enabled) {
|
||||
$model .= ':online';
|
||||
}
|
||||
|
||||
$response = $this->chat([
|
||||
['role' => 'user', 'content' => "Research this topic: {$query}"]
|
||||
], [
|
||||
'model' => $model,
|
||||
'web_search_options' => [
|
||||
'search_context_size' => $this->search_depth,
|
||||
'max_results' => 5,
|
||||
'engine' => $this->search_engine
|
||||
]
|
||||
]);
|
||||
|
||||
// Parse web search results from response
|
||||
$citations = $this->extractWebSearchResults($response);
|
||||
|
||||
return [
|
||||
'content' => $response['content'],
|
||||
'citations' => $citations,
|
||||
'cost' => $response['cost']
|
||||
];
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### User Workflow
|
||||
|
||||
**Scenario 1: Evergreen Topic**
|
||||
```
|
||||
User: "Write about basic OOP principles"
|
||||
Research: Web Search OFF
|
||||
→ Uses LLM's training data
|
||||
Cost: $0.00 (no extra cost)
|
||||
Time: ~2 seconds
|
||||
```
|
||||
|
||||
**Scenario 2: Recent Tech Topic**
|
||||
```
|
||||
User: "Write about WordPress 6.7 new features"
|
||||
Research: Web Search ON
|
||||
→ Searches: "WordPress 6.7 new features 2025"
|
||||
→ Returns: 5 relevant articles with citations
|
||||
Cost: ~$0.02 (Exa search) + $0.0007 (model)
|
||||
Time: ~5 seconds
|
||||
```
|
||||
|
||||
### Settings Configuration
|
||||
|
||||
**Research Provider Selection:**
|
||||
- **Enable Web Search** - Toggle on/off
|
||||
- **Search Engine:**
|
||||
- `Auto` - Native if available, Exa fallback (recommended)
|
||||
- `Native` - Force provider's native search
|
||||
- `Exa` - Force Exa search
|
||||
- **Search Depth:**
|
||||
- `Low` - Minimal context, basic queries
|
||||
- `Medium` - Moderate context, general queries (default)
|
||||
- `High` - Extensive context, detailed research
|
||||
|
||||
---
|
||||
|
||||
## 🖼️ Image Generation Strategy
|
||||
|
||||
### Recommendation: Multi-Tier Approach
|
||||
|
||||
#### **Tier 1: Free for Most Users**
|
||||
**Provider:** fal.ai (via Replicate)
|
||||
**Model:** FLUX.1 Schnell (free tier)
|
||||
- **Free Credits:** 100 credits/month (= ~25-50 images)
|
||||
- **Generation Time:** <2 seconds
|
||||
- **Quality:** Excellent for dev blogs
|
||||
- **Setup:** Simple API integration
|
||||
- **Cost:** $0.00
|
||||
|
||||
**When to use:**
|
||||
- If user hasn't added OpenRouter key
|
||||
- For quick placeholder images
|
||||
- Personal/hobby blogs
|
||||
|
||||
#### **Tier 2: Premium via OpenRouter**
|
||||
**Provider:** OpenRouter
|
||||
**Model:** `black-forest-labs/flux-schnell` or `flux-pro`
|
||||
- **Cost:** ~$0.04 per image (schnell), ~$0.25 (pro)
|
||||
- **Quality:** Highest quality
|
||||
- **Integration:** Same API key as text models
|
||||
- **User Control:** Settings dropdown to pick Schnell vs Pro
|
||||
|
||||
**When to use:**
|
||||
- User has OpenRouter API key
|
||||
- Premium blogs/companies
|
||||
- High-quality images needed
|
||||
|
||||
### Implementation
|
||||
|
||||
```javascript
|
||||
// Image generation in Execute phase
|
||||
|
||||
const imagePrompt = plan.sections
|
||||
.filter(s => s.image_prompt)
|
||||
.map(s => ({
|
||||
section: s.id,
|
||||
prompt: s.image_prompt,
|
||||
model: userSettings.imageModel // schnell or pro
|
||||
}));
|
||||
|
||||
// Generate images via OpenRouter or fal.ai
|
||||
// Insert as Image blocks into Gutenberg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🆓 Free Tier Strategy
|
||||
|
||||
### What Works for Free (No Credit Card)
|
||||
|
||||
**25+ Free Models on OpenRouter:**
|
||||
|
||||
**Best for Planning:**
|
||||
- `xiaomi/mimo-v2-flash` - Top #1 open-source, Claude Sonnet 4.5 quality
|
||||
- `mistralai/mistral-devstral-2` - Excellent agentic coding
|
||||
- `deepseek/r1t2-chimera` - Strong reasoning
|
||||
|
||||
**Best for Writing:**
|
||||
- `meta-llama/llama-3.3-70b` - GPT-4 level quality
|
||||
- `qwen/qwen3-coder-480b` - Technical writing excellence
|
||||
|
||||
**Best for Images:**
|
||||
- fal.ai free tier: 100 credits/month
|
||||
- Replicate: 50 free generations/month with FLUX.1
|
||||
|
||||
### Free Tier Limitations
|
||||
|
||||
```
|
||||
✅ No credit card required
|
||||
✅ 25+ models available
|
||||
✅ Full plugin functionality
|
||||
✅ Rate limits: ~50 requests/day (= 5+ articles)
|
||||
❌ Shared infrastructure (queue during peak)
|
||||
❌ No premium models (Claude Opus, etc.)
|
||||
```
|
||||
|
||||
### Upsell Path
|
||||
|
||||
**Sidebar messaging:**
|
||||
```
|
||||
"Using Free Tier (30 requests remaining today)"
|
||||
|
||||
"Upgrade to OpenRouter ($0.67/article with premium models)"
|
||||
[Add API Key] [Learn More]
|
||||
```
|
||||
|
||||
**Settings page:**
|
||||
```
|
||||
Tier Selection:
|
||||
○ Free Tier (25+ models, slow during peak)
|
||||
◉ Pro Tier (300+ models, priority queue) - Add OpenRouter Key
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Technical Architecture
|
||||
|
||||
### WordPress Plugin Structure
|
||||
|
||||
```
|
||||
wp-agentic-writer/
|
||||
├── wp-agentic-writer.php (main plugin file)
|
||||
├── includes/
|
||||
│ ├── class-openrouter-provider.php (AI provider)
|
||||
│ ├── class-gutenberg-sidebar.php (React sidebar)
|
||||
│ ├── class-cost-tracker.php (cost display)
|
||||
│ └── class-plan-generator.php (plan logic)
|
||||
├── assets/
|
||||
│ ├── js/
|
||||
│ │ ├── sidebar.js (React component)
|
||||
│ │ └── blocks.js (Gutenberg integration)
|
||||
│ └── css/
|
||||
│ └── sidebar.css
|
||||
├── admin/
|
||||
│ └── settings.php (Settings page with API key input)
|
||||
└── tests/
|
||||
└── test-openrouter.php
|
||||
```
|
||||
|
||||
### Key Classes
|
||||
|
||||
**OpenRouterProvider**
|
||||
```php
|
||||
class OpenRouterProvider {
|
||||
- setApiKey($key)
|
||||
- setModel($type, $model) // type: "planning" or "execution"
|
||||
- enableWebSearch($enabled, $engine, $depth)
|
||||
- chat($messages, $options) // returns response + cost
|
||||
- generateImage($prompt)
|
||||
- getModelList()
|
||||
- getCostBreakdown()
|
||||
}
|
||||
```
|
||||
|
||||
**GutenbergSidebar**
|
||||
```js
|
||||
- useChat() // maintains conversation history
|
||||
- usePlan() // stores plan JSON
|
||||
- useBlockRegen() // regenerate specific block
|
||||
- useCostTracker() // real-time cost display
|
||||
```
|
||||
|
||||
**CostTracker**
|
||||
```php
|
||||
- addRequest($model, $input_tokens, $output_tokens, $cost)
|
||||
- getSessionTotal()
|
||||
- getMonthlyTotal()
|
||||
- formatDisplay()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📅 Development Roadmap (4 Weeks)
|
||||
|
||||
### **Week 1: Core Setup**
|
||||
- [ ] OpenRouter integration + cost tracking
|
||||
- [ ] Settings page (API key + model selection)
|
||||
- [ ] Gutenberg sidebar UI (chat interface)
|
||||
- [ ] Phase 1 & 2: Scribble → Research
|
||||
|
||||
**Deliverable:** User can chat in sidebar, see costs
|
||||
|
||||
### **Week 2: Planning & Execution**
|
||||
- [ ] Plan JSON generation from research
|
||||
- [ ] Plan editor in sidebar
|
||||
- [ ] Execute phase: Convert plan → Gutenberg blocks
|
||||
- [ ] Code block insertion with language detection
|
||||
|
||||
**Deliverable:** User can generate article blocks automatically
|
||||
|
||||
### **Week 3: Refinement & Images**
|
||||
- [ ] Block-level regeneration
|
||||
- [ ] Section-level chat refinement
|
||||
- [ ] Image generation integration (fal.ai + OpenRouter)
|
||||
- [ ] Image block insertion
|
||||
|
||||
**Deliverable:** Full 5-phase workflow functional
|
||||
|
||||
### **Week 4: Polish & Launch**
|
||||
- [ ] Cost tracking display (sidebar + settings)
|
||||
- [ ] Free tier messaging + upsell
|
||||
- [ ] Documentation (README, setup guide)
|
||||
- [ ] Testing + bug fixes
|
||||
|
||||
**Deliverable:** Production-ready MVP
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Launch Checklist
|
||||
|
||||
### Plugin Preparation
|
||||
- [ ] Prefix all functions/classes with `wp_agentic_writer_`
|
||||
- [ ] Add proper nonces for security
|
||||
- [ ] Sanitize all user inputs
|
||||
- [ ] Add error handling + user feedback
|
||||
- [ ] Include .pot file for translations
|
||||
- [ ] Test on WordPress 6.6+
|
||||
- [ ] Test with Gutenberg editor
|
||||
|
||||
### Documentation
|
||||
- [ ] README.md with setup instructions
|
||||
- [ ] Inline code comments
|
||||
- [ ] Troubleshooting guide
|
||||
- [ ] FAQ for developers
|
||||
|
||||
### Distribution
|
||||
- [ ] WordPress.org plugin listing
|
||||
- [ ] GitHub repository
|
||||
- [ ] Demo video showing workflow
|
||||
|
||||
---
|
||||
|
||||
## 📝 User Workflow Example
|
||||
|
||||
### Scenario: Dev Writes OAuth Article
|
||||
|
||||
```
|
||||
1. Opens WordPress editor
|
||||
2. Clicks "Start Agentic Writing" in sidebar
|
||||
3. Types: "I built an OAuth provider plugin for WordPress, want to write about it"
|
||||
|
||||
4. AI (Planning Model - Free):
|
||||
"This is about flexible authentication abstraction, yes?
|
||||
Key angles: Architecture pattern, Step-by-step implementation,
|
||||
Comparison to built-in WP auth"
|
||||
|
||||
5. User confirms: "Yes, but add performance considerations too"
|
||||
|
||||
6. AI generates plan in 8 seconds (JSON outline)
|
||||
Cost shown: $0.0007
|
||||
|
||||
7. User reviews outline in sidebar
|
||||
- Sees H2 sections, estimated code blocks
|
||||
- Adds "Security Tips" section
|
||||
- Removes redundant section
|
||||
|
||||
8. Clicks [Execute Article]
|
||||
|
||||
9. AI (Execution Model - Claude):
|
||||
- Generates prose for each section
|
||||
- Pulls code examples
|
||||
- Generates tech blog image
|
||||
|
||||
Takes 45 seconds, Cost: $0.634
|
||||
|
||||
10. Canvas fills with:
|
||||
- Paragraph blocks
|
||||
- Code blocks (highlighted)
|
||||
- Image block (auto-inserted)
|
||||
|
||||
11. User reviews in editor:
|
||||
- Reads through blocks
|
||||
- Clicks "Regenerate Section" on intro
|
||||
- Types refinement: "Make it more beginner-friendly"
|
||||
- AI re-writes just that section
|
||||
|
||||
12. User publishes
|
||||
|
||||
**Total time:** 3 minutes
|
||||
**Total cost:** ~$0.70
|
||||
**User satisfaction:** Very high (finally wrote the article!)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Metrics
|
||||
|
||||
### MVP Success Criteria
|
||||
- [ ] Plugin installs without errors
|
||||
- [ ] 5-phase workflow completes end-to-end
|
||||
- [ ] Cost tracking accurate within 1%
|
||||
- [ ] Free tier users can write 1+ articles/month
|
||||
- [ ] Paid tier users save 2+ hours per article
|
||||
- [ ] Block regeneration works on all content types
|
||||
|
||||
### Post-Launch Goals
|
||||
- 100+ active installations
|
||||
- 4.5+ star rating on WordPress.org
|
||||
- Feature requests from real users
|
||||
- Revenue from premium features (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## 🔐 Security & Privacy Notes
|
||||
|
||||
### OpenRouter API Key Storage
|
||||
- Store in WordPress options (prefixed)
|
||||
- Encrypt sensitive data
|
||||
- Add warning: "Never share your API key"
|
||||
|
||||
### User Data
|
||||
- Plan JSON stored in post meta
|
||||
- Cost history stored locally (not sent externally)
|
||||
- Conversation history stored in post meta
|
||||
|
||||
### Compliance
|
||||
- GDPR: User controls data, can delete anytime
|
||||
- No tracking or analytics
|
||||
- No external data collection
|
||||
|
||||
---
|
||||
|
||||
## 💡 Future Roadmap (Post-MVP)
|
||||
|
||||
### Phase 2 Features
|
||||
- [ ] Multi-language support (generate in any language)
|
||||
- [ ] SEO optimization (auto-generate meta descriptions, keywords)
|
||||
- [ ] Social sharing templates
|
||||
- [ ] Article scheduling
|
||||
- [ ] Team collaboration (multiple editors)
|
||||
- [ ] Template library (blog post templates, tutorials, case studies)
|
||||
|
||||
### Phase 3 Integration
|
||||
- [ ] GitHub integration (auto-convert PR → blog post)
|
||||
- [ ] Video script generation
|
||||
- [ ] Podcast transcript → blog post
|
||||
- [ ] Analytics dashboard
|
||||
|
||||
---
|
||||
|
||||
## 📚 Resources & References
|
||||
|
||||
- OpenRouter Docs: https://openrouter.ai/docs
|
||||
- Gutenberg Handbook: https://developer.wordpress.org/block-editor/
|
||||
- FLUX Image Generation: https://fal.ai/flux-2
|
||||
- WordPress Plugin Development: https://developer.wordpress.org/plugins/
|
||||
|
||||
---
|
||||
|
||||
**Ready to build?** Start with Week 1 core setup. All tools are free for development with generous free tiers.
|
||||
|
||||
**Questions?** Refer to this brief as source of truth throughout development.
|
||||
556
docs/features/hybrid-local-cloud-ai-provider-b09890.md
Normal file
556
docs/features/hybrid-local-cloud-ai-provider-b09890.md
Normal file
@@ -0,0 +1,556 @@
|
||||
# Local Backend + Codex Provider System with Cloud Fallback
|
||||
|
||||
Implement a provider system allowing text generation via Local Backend (Claude CLI proxy) and Codex API, while keeping image generation on OpenRouter's cloud API.
|
||||
|
||||
## Architecture Overview (Based on local-backend-feature.md)
|
||||
|
||||
**Current State:**
|
||||
- Plugin uses `WP_Agentic_Writer_OpenRouter_Provider` for all AI tasks
|
||||
- All requests go to cloud APIs (OpenRouter)
|
||||
- Costs per token, rate limits apply
|
||||
- 23+ files directly call provider singleton
|
||||
|
||||
**New State:**
|
||||
- **Local Backend**: User runs Node.js proxy on their machine (Claude CLI)
|
||||
- **Codex Provider**: Direct integration with OpenAI Codex API
|
||||
- **OpenRouter**: Fallback + image generation only
|
||||
- **Provider Manager**: Routes tasks to appropriate provider
|
||||
|
||||
**Flow:**
|
||||
```
|
||||
WordPress Plugin → Provider Manager → Local Backend (http://user-ip:8080)
|
||||
→ Codex API (https://api.openai.com)
|
||||
→ OpenRouter (images + fallback)
|
||||
```
|
||||
|
||||
## Provider Architecture
|
||||
|
||||
### 1. Provider Interface (Common Contract)
|
||||
|
||||
```php
|
||||
interface WP_Agentic_Writer_AI_Provider_Interface {
|
||||
public function chat($messages, $options, $type);
|
||||
public function chat_stream($messages, $options, $type, $callback);
|
||||
public function generate_image($prompt, $model, $options);
|
||||
public function is_configured();
|
||||
public function test_connection();
|
||||
public function supports_task_type($type);
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Provider Manager (Router)
|
||||
|
||||
```php
|
||||
class WP_Agentic_Writer_Provider_Manager {
|
||||
public static function get_provider_for_task($type) {
|
||||
$settings = get_option('wp_agentic_writer_settings');
|
||||
$task_providers = $settings['task_providers'] ?? [];
|
||||
|
||||
$provider_name = $task_providers[$type] ?? 'openrouter';
|
||||
|
||||
switch ($provider_name) {
|
||||
case 'local_backend':
|
||||
return new WP_Agentic_Writer_Local_Backend_Provider();
|
||||
case 'codex':
|
||||
return new WP_Agentic_Writer_Codex_Provider();
|
||||
case 'openrouter':
|
||||
default:
|
||||
return WP_Agentic_Writer_OpenRouter_Provider::get_instance();
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Provider Implementations
|
||||
|
||||
**A. Local Backend Provider** (Primary for text tasks)
|
||||
- **File**: `includes/class-local-backend-provider.php`
|
||||
- **Endpoint**: `http://192.168.x.x:8080` (user's machine)
|
||||
- **Protocol**: HTTP POST to `/v1/messages` (OpenAI-compatible)
|
||||
- **Backend**: Node.js proxy → Claude CLI
|
||||
- **Supports**: `chat`, `clarity`, `planning`, `writing`, `refinement`
|
||||
- **Cost**: $0 (uses user's Claude CLI + Z.ai/Anthropic)
|
||||
|
||||
**B. Codex Provider** (Alternative text provider)
|
||||
- **File**: `includes/class-codex-provider.php`
|
||||
- **Endpoint**: `https://api.openai.com/v1/chat/completions`
|
||||
- **Protocol**: Standard OpenAI API
|
||||
- **Supports**: `chat`, `clarity`, `planning`, `writing`, `refinement`
|
||||
- **Cost**: Per OpenAI pricing
|
||||
|
||||
**C. OpenRouter Provider** (Existing, for images + fallback)
|
||||
- **File**: `includes/class-openrouter-provider.php` (existing)
|
||||
- **Endpoint**: `https://openrouter.ai/api/v1/chat/completions`
|
||||
- **Supports**: ALL task types (fallback when local unavailable)
|
||||
- **Primary use**: `image` generation only in hybrid mode
|
||||
|
||||
### Configuration Strategy
|
||||
|
||||
#### Settings Structure
|
||||
|
||||
```php
|
||||
'wp_agentic_writer_settings' => [
|
||||
// Provider routing
|
||||
'provider_mode' => 'hybrid', // 'cloud', 'local', 'hybrid'
|
||||
'task_providers' => [
|
||||
'chat' => 'local_backend',
|
||||
'clarity' => 'local_backend',
|
||||
'planning' => 'local_backend',
|
||||
'writing' => 'local_backend',
|
||||
'refinement' => 'codex', // Or local_backend
|
||||
'image' => 'openrouter' // Always OpenRouter
|
||||
],
|
||||
|
||||
// Local Backend settings
|
||||
'local_backend_url' => 'http://192.168.1.105:8080',
|
||||
'local_backend_key' => 'dummy',
|
||||
'local_backend_model' => 'claude-via-cli',
|
||||
'local_backend_enabled' => true,
|
||||
|
||||
// Codex settings
|
||||
'codex_api_key' => 'sk-...',
|
||||
'codex_model' => 'gpt-4',
|
||||
'codex_enabled' => true,
|
||||
|
||||
// OpenRouter (existing)
|
||||
'openrouter_api_key' => 'sk-or-...',
|
||||
'image_model' => 'black-forest-labs/flux-1.1-pro',
|
||||
]
|
||||
```
|
||||
|
||||
#### Recommended Configuration
|
||||
|
||||
**Optimal Hybrid Setup:**
|
||||
```
|
||||
chat → Local Backend (free, private, fast)
|
||||
clarity → Local Backend (free, fast)
|
||||
planning → Local Backend (free, fast)
|
||||
writing → Local Backend (free, unlimited)
|
||||
refinement → Codex (cloud quality when needed)
|
||||
image → OpenRouter (only option for FLUX/Recraft)
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- 80%+ requests via Local Backend = $0 cost
|
||||
- Privacy for all text content
|
||||
- Codex as quality alternative
|
||||
- Images via best models (OpenRouter)
|
||||
|
||||
## Implementation Components
|
||||
|
||||
### 1. Local Backend Package (Separate Distribution)
|
||||
|
||||
**Package:** `agentic-writer-local-backend.zip`
|
||||
|
||||
**Contents:**
|
||||
```
|
||||
agentic-writer-local-backend/
|
||||
├── claude-proxy.js # Node.js HTTP server
|
||||
├── start-proxy.sh # Launch with IP detection
|
||||
├── stop-proxy.sh # Clean shutdown
|
||||
├── test-connection.sh # Verify proxy works
|
||||
├── get-local-ip.sh # Find machine IP
|
||||
├── package.json # Express dependency
|
||||
├── README.md # Setup guide
|
||||
└── TROUBLESHOOTING.md # Common issues
|
||||
```
|
||||
|
||||
**Proxy Server (`claude-proxy.js`):**
|
||||
- Spawns user's Claude CLI for each request
|
||||
- OpenAI-compatible `/v1/messages` endpoint
|
||||
- Health check `/ping` endpoint
|
||||
- Binds to `0.0.0.0:8080` for LAN access
|
||||
- Logs requests for debugging
|
||||
|
||||
**User Flow:**
|
||||
1. Download ZIP from plugin settings
|
||||
2. Extract and run `./start-proxy.sh`
|
||||
3. Copy displayed Base URL (e.g., `http://192.168.1.105:8080`)
|
||||
4. Paste into plugin settings
|
||||
5. Test connection → generate content
|
||||
|
||||
### 2. Plugin Integration Files
|
||||
|
||||
**New Files:**
|
||||
```
|
||||
includes/class-local-backend-provider.php
|
||||
includes/class-codex-provider.php
|
||||
includes/class-provider-manager.php
|
||||
includes/interface-ai-provider.php
|
||||
views/settings/tab-local-backend.php
|
||||
admin/js/test-local-backend.js
|
||||
downloads/agentic-writer-local-backend.zip
|
||||
```
|
||||
|
||||
**Modified Files:**
|
||||
```
|
||||
includes/class-openrouter-provider.php
|
||||
→ Implement WP_Agentic_Writer_AI_Provider_Interface
|
||||
→ No behavior changes
|
||||
|
||||
includes/class-gutenberg-sidebar.php
|
||||
→ Replace: WP_Agentic_Writer_OpenRouter_Provider::get_instance()
|
||||
→ With: WP_Agentic_Writer_Provider_Manager::get_provider_for_task($type)
|
||||
|
||||
+ 20 other files with provider calls
|
||||
```
|
||||
|
||||
### 3. Settings UI
|
||||
|
||||
**New Tab:** "Local Backend"
|
||||
- Download local backend package
|
||||
- Base URL input
|
||||
- API Key input (dummy)
|
||||
- Model selector
|
||||
- "Test Connection" button
|
||||
- Connection status indicator
|
||||
- Troubleshooting guide
|
||||
|
||||
**Per-Task Routing (Advanced):**
|
||||
- Simple mode: Enable/Disable Local Backend (uses for all text)
|
||||
- Advanced mode: Task routing matrix
|
||||
|
||||
### 4. Migration & Backwards Compatibility
|
||||
|
||||
**Phase 1: Abstraction (Non-Breaking)**
|
||||
- Create `interface-ai-provider.php`
|
||||
- Create `class-provider-manager.php`
|
||||
- OpenRouter implements interface
|
||||
- All calls route through manager → defaults to OpenRouter
|
||||
- **100% backwards compatible, no settings changes**
|
||||
|
||||
**Phase 2: Local Backend Provider**
|
||||
- Implement `class-local-backend-provider.php`
|
||||
- Create proxy package (claude-proxy.js + scripts)
|
||||
- Add "Local Backend" settings tab
|
||||
- Implement connection test handler
|
||||
- Test with user's local setup
|
||||
|
||||
**Phase 3: Codex Provider**
|
||||
- Implement `class-codex-provider.php`
|
||||
- Add Codex API key to settings
|
||||
- Add Codex as task routing option
|
||||
- Test Codex integration
|
||||
|
||||
**Phase 4: Update All Provider Calls**
|
||||
- Update 23+ files to use Provider Manager
|
||||
- Test all task types (chat, clarity, planning, writing, refinement, image)
|
||||
- Ensure streaming works with all providers
|
||||
- Verify cost tracking
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
### Local Backend Protocol
|
||||
|
||||
**Why OpenAI-compatible format:**
|
||||
- Plugin already uses message-based format
|
||||
- Easy to proxy to Claude CLI
|
||||
- Future-proof for other local models
|
||||
|
||||
**Request Format:**
|
||||
```json
|
||||
POST http://192.168.1.105:8080/v1/messages
|
||||
{
|
||||
"messages": [
|
||||
{"role": "user", "content": "Write about AI"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Response Format:**
|
||||
```json
|
||||
{
|
||||
"id": "local-1234567890",
|
||||
"object": "chat.completion",
|
||||
"model": "claude-local",
|
||||
"choices": [{
|
||||
"message": {
|
||||
"role": "assistant",
|
||||
"content": "Article content..."
|
||||
},
|
||||
"finish_reason": "stop"
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
### Codex Integration
|
||||
|
||||
**Direct API Calls:**
|
||||
- Use OpenAI PHP library or `wp_remote_post`
|
||||
- Standard chat completions endpoint
|
||||
- Same format as OpenRouter
|
||||
|
||||
**Why Codex:**
|
||||
- High quality for coding/technical content
|
||||
- Alternative to Local Backend
|
||||
- Cloud-based when user's machine offline
|
||||
|
||||
## Cost Tracking Integration
|
||||
|
||||
**Challenge:** Local Backend = $0, Codex/OpenRouter = cost
|
||||
|
||||
**Solution:**
|
||||
```php
|
||||
// Provider returns cost data
|
||||
$result = $provider->chat($messages, $options, $type);
|
||||
$cost = $result['cost'] ?? 0;
|
||||
|
||||
if ($cost > 0 && $post_id > 0) {
|
||||
do_action('wp_aw_after_api_request',
|
||||
$post_id,
|
||||
$result['model'] ?? 'unknown',
|
||||
$type,
|
||||
$result['input_tokens'] ?? 0,
|
||||
$result['output_tokens'] ?? 0,
|
||||
$cost
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**Dashboard Display:**
|
||||
```
|
||||
Session Cost: $0.15
|
||||
- Local Backend: 12 requests (free)
|
||||
- Codex: 3 requests ($0.10)
|
||||
- OpenRouter: 2 images ($0.05)
|
||||
|
||||
Today: $2.40
|
||||
Month: $45.00
|
||||
```
|
||||
|
||||
## Error Handling & Fallbacks
|
||||
|
||||
### Local Backend Unreachable
|
||||
|
||||
```php
|
||||
$local_provider = new WP_Agentic_Writer_Local_Backend_Provider();
|
||||
|
||||
if (!$local_provider->is_available()) {
|
||||
// Fallback to OpenRouter
|
||||
error_log('Local Backend unavailable, using OpenRouter fallback');
|
||||
return WP_Agentic_Writer_OpenRouter_Provider::get_instance();
|
||||
}
|
||||
```
|
||||
|
||||
**Admin Notice:**
|
||||
"⚠️ Local Backend unreachable. Using OpenRouter fallback. Check proxy: `./start-proxy.sh`"
|
||||
|
||||
### Connection Test Results
|
||||
|
||||
```
|
||||
✅ Connected! Proxy responding correctly.
|
||||
❌ Connection timeout. Is proxy running? Check: ps aux | grep claude-proxy
|
||||
❌ Connection refused. Start proxy: ./start-proxy.sh
|
||||
❌ Wrong IP. Find correct IP: ./get-local-ip.sh
|
||||
❌ Claude CLI not responding. Test: echo "test" | claude
|
||||
```
|
||||
|
||||
## UI/UX Considerations
|
||||
|
||||
### Settings Page Flow
|
||||
|
||||
1. **Tab: Local Backend**
|
||||
- Big download button for proxy package
|
||||
- Prerequisites checklist
|
||||
- Base URL input (pre-filled from clipboard?)
|
||||
- Test connection button
|
||||
- Status: 🟢 Connected / 🔴 Offline
|
||||
|
||||
2. **Tab: Providers**
|
||||
- Simple mode: "Use Local Backend" toggle
|
||||
- Advanced mode: Task routing matrix
|
||||
- Provider status indicators
|
||||
|
||||
3. **Tab: Models** (existing)
|
||||
- Add Codex models
|
||||
- Show provider per model
|
||||
|
||||
### Sidebar Indicators
|
||||
|
||||
**Provider Badge:**
|
||||
```
|
||||
🏠 Local (Free)
|
||||
🔗 Codex ($0.02)
|
||||
☁️ OpenRouter ($0.05)
|
||||
```
|
||||
|
||||
**Connection Status:**
|
||||
```
|
||||
🟢 Local Backend: Connected
|
||||
🔴 Local Backend: Offline (using OpenRouter)
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
**Test Cases:**
|
||||
1. Cloud-only mode (existing behavior)
|
||||
2. Local-only mode (Ollama for all text)
|
||||
3. Hybrid mode (recommended config)
|
||||
4. Fallback when Ollama unavailable
|
||||
5. Streaming works with both providers
|
||||
6. Cost tracking accurate
|
||||
7. Model selection per provider
|
||||
|
||||
## Performance Implications
|
||||
|
||||
**Local Backend:**
|
||||
- **Latency**: ~50-200ms LAN vs ~500-2000ms cloud
|
||||
- **Throughput**: Limited by Claude CLI (~20-30 tokens/sec)
|
||||
- **Concurrency**: One request at a time (spawn per request)
|
||||
- **Quality**: Same as cloud Claude (uses same models)
|
||||
|
||||
**Codex:**
|
||||
- **Latency**: Standard OpenAI API latency
|
||||
- **Quality**: High for technical/coding content
|
||||
- **Cost**: Per-token pricing
|
||||
|
||||
**OpenRouter:**
|
||||
- **Image Generation**: Only option for FLUX/Recraft
|
||||
- **Fallback**: When local backend offline
|
||||
- **Cost**: Per-token pricing
|
||||
|
||||
## Deployment Scenarios
|
||||
|
||||
### Scenario 1: Local Development (User's Machine)
|
||||
|
||||
**Setup:**
|
||||
- WordPress on Local by Flywheel (bricks.local)
|
||||
- Node.js proxy on same machine (localhost:8080)
|
||||
- Claude CLI configured with Z.ai
|
||||
|
||||
**Config:**
|
||||
```
|
||||
Local Backend URL: http://localhost:8080
|
||||
All text tasks: Local Backend
|
||||
Images: OpenRouter
|
||||
Cost: ~$0 for text, ~$0.05/image
|
||||
```
|
||||
|
||||
### Scenario 2: Local Dev + Cloud Production
|
||||
|
||||
**Dev:**
|
||||
- Use Local Backend for free development
|
||||
- Test with real Claude quality
|
||||
|
||||
**Production:**
|
||||
- Auto-switch to OpenRouter when local unavailable
|
||||
- Seamless fallback
|
||||
|
||||
### Scenario 3: Agency with Shared Local Backend
|
||||
|
||||
**Setup:**
|
||||
- One machine runs proxy on LAN
|
||||
- Multiple WordPress sites connect to it
|
||||
- All sites share one Z.ai account
|
||||
|
||||
**Config:**
|
||||
```
|
||||
Local Backend URL: http://192.168.1.50:8080
|
||||
Cost: Free for entire team
|
||||
```
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: Core Infrastructure (Week 1)
|
||||
- [ ] Create provider interface
|
||||
- [ ] Create provider manager
|
||||
- [ ] OpenRouter implements interface
|
||||
- [ ] Update 3-5 files to use manager (test)
|
||||
- [ ] Verify backwards compatibility
|
||||
|
||||
### Phase 2: Local Backend Package (Week 1)
|
||||
- [ ] Create `claude-proxy.js` with `/v1/messages` endpoint
|
||||
- [ ] Create startup/shutdown scripts
|
||||
- [ ] Test with actual Claude CLI
|
||||
- [ ] Package as ZIP
|
||||
- [ ] Write README with setup guide
|
||||
|
||||
### Phase 3: Local Backend Provider (Week 2)
|
||||
- [ ] Implement `class-local-backend-provider.php`
|
||||
- [ ] Add settings tab UI
|
||||
- [ ] Implement connection test
|
||||
- [ ] Add ZIP download from settings
|
||||
- [ ] Test end-to-end flow
|
||||
|
||||
### Phase 4: Codex Provider (Week 2)
|
||||
- [ ] Implement `class-codex-provider.php`
|
||||
- [ ] Add Codex API key to settings
|
||||
- [ ] Test Codex integration
|
||||
- [ ] Add to task routing options
|
||||
|
||||
### Phase 5: Full Rollout (Week 3)
|
||||
- [ ] Update all 23+ files to use provider manager
|
||||
- [ ] Test all task types
|
||||
- [ ] Verify streaming works
|
||||
- [ ] Test cost tracking
|
||||
- [ ] Documentation
|
||||
|
||||
### Phase 6: Polish (Week 3)
|
||||
- [ ] Connection status widget
|
||||
- [ ] Auto-fallback logic
|
||||
- [ ] Error messages with actionable guidance
|
||||
- [ ] Video tutorial
|
||||
- [ ] Troubleshooting guide
|
||||
|
||||
## Implementation Estimate
|
||||
|
||||
**Phase 1 (Infrastructure):** 4-5 hours
|
||||
- Provider interface, manager, OpenRouter refactor
|
||||
- Test with 3-5 files
|
||||
|
||||
**Phase 2 (Local Backend Package):** 6-8 hours
|
||||
- Node.js proxy development
|
||||
- Scripts (start, stop, test)
|
||||
- ZIP packaging
|
||||
- Documentation
|
||||
|
||||
**Phase 3 (Local Backend Integration):** 8-10 hours
|
||||
- Provider class
|
||||
- Settings UI
|
||||
- Connection test
|
||||
- End-to-end testing
|
||||
|
||||
**Phase 4 (Codex):** 4-6 hours
|
||||
- Provider implementation
|
||||
- Settings integration
|
||||
- Testing
|
||||
|
||||
**Phase 5 (Full Rollout):** 8-10 hours
|
||||
- Update 23+ files
|
||||
- Test all scenarios
|
||||
- Cost tracking
|
||||
- Documentation
|
||||
|
||||
**Phase 6 (Polish):** 4-6 hours
|
||||
- UI improvements
|
||||
- Error handling
|
||||
- Video tutorial
|
||||
- Troubleshooting docs
|
||||
|
||||
**Total:** 34-45 hours (~1-1.5 weeks)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
✅ User can download local backend package
|
||||
✅ User can start proxy on their machine
|
||||
✅ Plugin connects to local backend successfully
|
||||
✅ All text tasks work via local backend ($0 cost)
|
||||
✅ Images work via OpenRouter
|
||||
✅ Codex works as alternative provider
|
||||
✅ Automatic fallback to OpenRouter when local offline
|
||||
✅ Cost tracking shows local = $0, cloud = actual cost
|
||||
✅ Streaming works with all providers
|
||||
✅ 100% backwards compatible (defaults to OpenRouter)
|
||||
|
||||
## Ready to Implement
|
||||
|
||||
This plan matches `local-backend-feature.md` requirements:
|
||||
- ✅ Claude CLI proxy via Node.js
|
||||
- ✅ HTTP-based local backend
|
||||
- ✅ Codex integration
|
||||
- ✅ OpenRouter for images
|
||||
- ✅ Provider abstraction system
|
||||
- ✅ Fallback logic
|
||||
- ✅ Complete UI/UX flow
|
||||
|
||||
Confirm to proceed with implementation.
|
||||
363
docs/features/image-best-flow-recommendation.md
Normal file
363
docs/features/image-best-flow-recommendation.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# WP Agentic Writer: Recommended Best Flow for Images (Cost-Optimized)
|
||||
|
||||
## The Challenge You Asked About
|
||||
|
||||
**Your question:**
|
||||
> "After article generation, how do we get image placement with alt by writing agent, then generate recommended images? Need to be cost-efficient with image prompts."
|
||||
|
||||
**The answer:** Use the **writing agent itself** to analyze placement + generate prompts (tiny cost), then show user a preview before spending on image generation.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Recommended Best Flow (Option A - SAFEST)](#recommended-best-flow-option-a---safest)
|
||||
2. [Alternative Flows (B & C)](#alternative-flows-b--c)
|
||||
3. [Your Configuration (from screenshot)](#your-configuration-from-screenshot)
|
||||
4. [Cost Breakdown](#cost-breakdown)
|
||||
5. [Implementation Priority](#implementation-priority)
|
||||
|
||||
---
|
||||
|
||||
## Recommended Best Flow (Option A - SAFEST)
|
||||
|
||||
This is the flow I recommend for **maximum cost control + quality** based on your plugin's design.
|
||||
|
||||
### Step-by-Step
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ USER ACTION: Generate Article │
|
||||
│ (Using Writing Model: Claude 3.5 Sonnet from preset) │
|
||||
└─────────────────┬────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ PLUGIN AUTOMATIC (Backend) │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ Step 1: ANALYZE PLACEMENT │
|
||||
│ • Model: Same Writing Model (Claude 3.5 Sonnet) │
|
||||
│ • Input: Full article markdown │
|
||||
│ • Output: JSON with placement points │
|
||||
│ • Cost: $0.0008 (tiny token call) │
|
||||
│ │
|
||||
│ Step 2: GENERATE IMAGE PROMPTS │
|
||||
│ • Model: Same Writing Model │
|
||||
│ • Input: Article + placement points │
|
||||
│ • Output: 3 image specs (prompt + alt + placement) │
|
||||
│ • Cost: $0.0015 (tiny token call) │
|
||||
│ │
|
||||
│ Status: "Analyzing images..." → "Ready to review" │
|
||||
└─────────────────┬────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ MODAL: IMAGE PREVIEW (User Review - $0 cost) │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ "3 images planned for your article" │
|
||||
│ │
|
||||
│ ╔════════════════════════════════════════════════════╗ │
|
||||
│ ║ IMAGE 1: HERO (After Introduction) ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Placement: After intro, before "Getting Started" ║ │
|
||||
│ ║ Type: Hero/Dashboard ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Prompt (EDITABLE): ║ │
|
||||
│ ║ "N8n workflow automation dashboard screenshot, ║ │
|
||||
│ ║ showing colorful nodes on blue background, ║ │
|
||||
│ ║ modern minimalist SaaS interface" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Alt Text: "N8n automation dashboard with nodes" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
|
||||
│ ╚════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
│ ╔════════════════════════════════════════════════════╗ │
|
||||
│ ║ IMAGE 2: DIAGRAM (After Section 1) ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Placement: After "Understanding Workflows" ║ │
|
||||
│ ║ Type: Technical Diagram ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Prompt (EDITABLE): ║ │
|
||||
│ ║ "Workflow architecture diagram showing trigger, ║ │
|
||||
│ ║ condition, action components with arrows, ║ │
|
||||
│ ║ technical line-art style, blue palette" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Alt Text: "Workflow trigger-condition-action flow" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
|
||||
│ ╚════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
│ ╔════════════════════════════════════════════════════╗ │
|
||||
│ ║ IMAGE 3: SCREENSHOT (Before Conclusion) ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Placement: Before "Conclusion" ║ │
|
||||
│ ║ Type: Product Screenshot ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Prompt (EDITABLE): ║ │
|
||||
│ ║ "N8n real-time monitoring dashboard showing ║ │
|
||||
│ ║ workflow execution logs, status indicators, ║ │
|
||||
│ ║ professional SaaS product design" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ Alt Text: "N8n real-time monitoring interface" ║ │
|
||||
│ ║ ║ │
|
||||
│ ║ [Edit Prompt ✎] [Generate $0.03] [Skip] ║ │
|
||||
│ ╚════════════════════════════════════════════════════╝ │
|
||||
│ │
|
||||
│ ───────────────────────────────────────────────────── │
|
||||
│ Cost Estimate: Individual generation │
|
||||
│ • Generate all 3: $0.09–0.21 (based on image tier) │
|
||||
│ • Generate 2: $0.06–0.14 │
|
||||
│ • Generate 1: $0.03–0.07 │
|
||||
│ │
|
||||
│ [Generate All 3] [Generate Selected] [Skip Images] │
|
||||
│ [Cancel] │
|
||||
└──────────────────┬───────────────────────────────────────┘
|
||||
↓
|
||||
USER CHOOSES (examples):
|
||||
• Click [Generate All 3] → All images generated now
|
||||
• Click [Generate] on Image 1 only → Hero only
|
||||
• Edit Image 1 prompt, then [Generate] → Custom prompt
|
||||
• Click [Skip Images] → No images, save cost
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ AUTOMATIC IMAGE INSERTION │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ For each generated image: │
|
||||
│ 1. Download image from FLUX.2/image model │
|
||||
│ 2. Upload to WordPress media library │
|
||||
│ 3. Insert into article at placement point │
|
||||
│ 4. Add alt text automatically │
|
||||
│ │
|
||||
│ Status: "Inserting images..." → "Done!" │
|
||||
└─────────────────┬────────────────────────────────────────┘
|
||||
↓
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ FINAL RESULT: Article with Images │
|
||||
├──────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ # Getting Started with N8n Automation │
|
||||
│ │
|
||||
│ Introduction paragraph... │
|
||||
│ │
|
||||
│  │
|
||||
│ │
|
||||
│ ## Getting Started │
|
||||
│ Content... │
|
||||
│ │
|
||||
│ ## Understanding Workflows │
|
||||
│ Content... │
|
||||
│ │
|
||||
│  │
|
||||
│ │
|
||||
│ ## Advanced Monitoring │
|
||||
│ Content... │
|
||||
│ │
|
||||
│  │
|
||||
│ │
|
||||
│ [Preview in Gutenberg] [Publish] [Download MD] │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Key Features of Option A
|
||||
|
||||
✅ **Cost control:** User sees cost before spending
|
||||
✅ **Quality control:** Can edit prompts before generation
|
||||
✅ **Flexibility:** Generate 0, 1, 2, or 3 images
|
||||
✅ **User review:** Know exactly what images they'll get
|
||||
✅ **Selective generation:** Generate only what matters
|
||||
✅ **Smart placement:** Analyzed by writing agent (best understanding)
|
||||
✅ **Efficient prompts:** Precise, contextual, no trial-and-error
|
||||
|
||||
### Costs with Option A
|
||||
|
||||
| Scenario | Analysis | Prompts | Images | Total |
|
||||
|----------|----------|---------|--------|-------|
|
||||
| User generates all 3 | $0.0008 | $0.0015 | $0.09–0.21 | $0.092–0.212 |
|
||||
| User generates 2 | $0.0008 | $0.0015 | $0.06–0.14 | $0.063–0.142 |
|
||||
| User generates 1 (hero) | $0.0008 | $0.0015 | $0.03–0.07 | $0.032–0.072 |
|
||||
| User skips images | $0.0008 | $0.0015 | $0 | $0.0023 |
|
||||
|
||||
**Best case:** User generates 1 hero = **$0.032–0.072/article** (vs $0.21–0.70 with trial-and-error)
|
||||
|
||||
---
|
||||
|
||||
## Alternative Flows (B & C)
|
||||
|
||||
### Option B: Automatic Full Generation (FASTEST)
|
||||
|
||||
```
|
||||
Article generated
|
||||
↓
|
||||
Plugin automatically generates ALL images without review
|
||||
↓
|
||||
"Article + images ready!" (1-2 minutes total)
|
||||
```
|
||||
|
||||
**Pros:** One-click, minimal user interaction
|
||||
**Cons:** Always costs full image budget (no user control)
|
||||
**Cost:** Full $0.12–0.35 (analysis + all images always generated)
|
||||
|
||||
**Use when:** User has unlimited budget OR you offer it as "premium fast mode"
|
||||
|
||||
---
|
||||
|
||||
### Option C: Smart Selective with Recommendations (BALANCED)
|
||||
|
||||
```
|
||||
Similar to Option A, but plugin recommends:
|
||||
- "Hero image has best impact/cost ratio" [Generate hero]
|
||||
- "Diagrams help understanding" [Generate diagram?]
|
||||
- "Screenshot is optional" [Generate?]
|
||||
```
|
||||
|
||||
**Pros:** Guides user toward cost-effective choices
|
||||
**Cons:** Slightly more UI complexity
|
||||
**Cost:** User-controlled (guided)
|
||||
|
||||
**Use when:** You want to educate users about cost-benefit tradeoffs
|
||||
|
||||
---
|
||||
|
||||
## Your Configuration (from screenshot)
|
||||
|
||||
Based on your current model configuration:
|
||||
|
||||
```
|
||||
Chat Model: Google: Gemini 2.5 Flash
|
||||
Clarity Model: Google: Gemini 2.5 Flash
|
||||
Planning Model: Google: Gemini 2.5 Flash
|
||||
Writing Model: Anthropic: Claude 3.5 Sonnet
|
||||
Refinement Model: Anthropic: Claude 3.5 Sonnet
|
||||
Image Model: Gpt 4o (or FLUX.2 from preset)
|
||||
```
|
||||
|
||||
### Recommended Implementation
|
||||
|
||||
```php
|
||||
// Option A implementation (safest, recommended)
|
||||
|
||||
// 1. After article generation, automatically:
|
||||
$placement_data = analyze_article_for_images(
|
||||
$article,
|
||||
'anthropic/claude-3.5-sonnet' // Use same writing model
|
||||
);
|
||||
|
||||
// 2. Generate prompts
|
||||
$image_specs = generate_image_prompts(
|
||||
$article,
|
||||
$placement_data,
|
||||
'anthropic/claude-3.5-sonnet' // Same model
|
||||
);
|
||||
|
||||
// 3. Show UI (don't generate images yet)
|
||||
show_image_review_modal($image_specs);
|
||||
|
||||
// 4. User clicks [Generate All] or individual [Generate]
|
||||
// 5. Only then call image generation
|
||||
|
||||
// Cost so far: $0.0023 (tiny)
|
||||
// User controls image generation cost: $0.03–0.21
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Breakdown
|
||||
|
||||
### Analysis + Prompt Generation (Automatic, Non-Optional)
|
||||
|
||||
| Task | Tokens In | Tokens Out | Cost |
|
||||
|------|-----------|------------|------|
|
||||
| Placement analysis | 2,000 | 800 | $0.0008 |
|
||||
| Prompt generation | 3,000 | 1,000 | $0.0015 |
|
||||
| **Total** | **5,000** | **1,800** | **$0.0023** |
|
||||
|
||||
**This is already paid by article generation (uses writing model already called).**
|
||||
|
||||
### Image Generation (User-Controlled)
|
||||
|
||||
**Per image (based on model tier):**
|
||||
|
||||
| Image Model | Cost/Image | 3 Images |
|
||||
|------------|-----------|----------|
|
||||
| FLUX.2 klein (Budget) | $0.03–0.05 | $0.09–0.15 |
|
||||
| Riverflow/FLUX.2 Pro (Balanced) | $0.06–0.10 | $0.18–0.30 |
|
||||
| FLUX.2 max (Premium) | $0.07–0.21 | $0.21–0.63 |
|
||||
|
||||
### Total Article Cost
|
||||
|
||||
| Scenario | Text | Analysis | Prompts | Images | Total |
|
||||
|----------|------|----------|---------|--------|-------|
|
||||
| Article only | $0.03–0.07 | $0.0008 | $0.0015 | $0 | **$0.032–0.072** |
|
||||
| Article + 1 hero | $0.03–0.07 | $0.0008 | $0.0015 | $0.03–0.21 | **$0.062–0.292** |
|
||||
| Article + 2 images | $0.03–0.07 | $0.0008 | $0.0015 | $0.06–0.42 | **$0.092–0.492** |
|
||||
| Article + 3 images | $0.03–0.07 | $0.0008 | $0.0015 | $0.09–0.63 | **$0.122–0.702** |
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
### Phase 1: Core Logic (3-4 hours)
|
||||
|
||||
```php
|
||||
✓ analyze_article_for_images() // Identify placements
|
||||
✓ generate_image_prompts() // Create specs
|
||||
✓ generate_image_from_prompt() // Call image model
|
||||
✓ insert_images_into_article() // Embed in markdown
|
||||
```
|
||||
|
||||
### Phase 2: User Interface (4-5 hours)
|
||||
|
||||
```php
|
||||
✓ Image review modal UI // Show 3 specs
|
||||
✓ [Generate] button per image // Individual generation
|
||||
✓ [Generate All] button // Batch generation
|
||||
✓ [Edit Prompt] capability // Let users customize
|
||||
✓ Cost calculator display // Show estimated cost
|
||||
```
|
||||
|
||||
### Phase 3: Polish (2-3 hours)
|
||||
|
||||
```php
|
||||
✓ Image preview before insertion // Show user the image
|
||||
✓ Error handling + retry logic // Handle failures
|
||||
✓ Success notifications // Feedback
|
||||
✓ Progress indicators // "Generating image 2/3..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why Option A is Best for Your Plugin
|
||||
|
||||
1. **User controls costs** → They see preview before spending
|
||||
2. **Respects budgets** → Budget tier users generate 1 image
|
||||
3. **Quality focus** → Users can edit prompts if needed
|
||||
4. **Flexible** → Some users skip images entirely (saves costs)
|
||||
5. **Educational** → Users learn what good prompts look like
|
||||
6. **Smart prompts** → Using writing agent (best context understanding)
|
||||
|
||||
---
|
||||
|
||||
## Summary: Recommended Best Flow
|
||||
|
||||
```
|
||||
AUTOMATIC (Backend):
|
||||
1. Analyze article for placement → $0.0008
|
||||
2. Generate image specs/prompts → $0.0015
|
||||
3. Show user preview modal → $0 (free review)
|
||||
|
||||
MANUAL (User Selects):
|
||||
4. User clicks [Generate] on images → User controls cost
|
||||
5. Plugin inserts into article → Automatic
|
||||
|
||||
RESULT:
|
||||
- Article + images ready for Gutenberg
|
||||
- User spent only what they wanted
|
||||
- Total cost: $0.032–0.702 (user-controlled)
|
||||
- Quality: High (smart placement + customizable prompts)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Document version:** 1.0
|
||||
**Date:** January 27, 2026
|
||||
**Status:** Ready for Implementation
|
||||
1345
docs/features/image-gen-flow.md
Normal file
1345
docs/features/image-gen-flow.md
Normal file
File diff suppressed because it is too large
Load Diff
541
docs/features/image-model-recommendations.md
Normal file
541
docs/features/image-model-recommendations.md
Normal file
@@ -0,0 +1,541 @@
|
||||
# WP Agentic Writer: Image Model Recommendations by Preset
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Your question:** "Which image model should we use? We need to match the prompt style to avoid wasting money on bad images."
|
||||
|
||||
**The answer:** Different image models have different "prompt languages" and reasoning capabilities. Choose the right model for your preset, then **generate prompts specifically for that model's strengths**.
|
||||
|
||||
**Recommended models (by preset):**
|
||||
- **Budget:** FLUX.2 [klein] 4B (fast, cheap, handles simple prompts well)
|
||||
- **Balanced:** Riverflow V2 Max Preview (excellent prompt adherence, context-aware)
|
||||
- **Premium:** FLUX.2 [max] (frontier quality, best photorealism + complex prompts)
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Image Model Comparison Matrix](#image-model-comparison-matrix)
|
||||
2. [Budget Preset: FLUX.2 [klein] Recommendation](#budget-preset-flux2-klein-recommendation)
|
||||
3. [Balanced Preset: Riverflow V2 Max Recommendation](#balanced-preset-riverflow-v2-max-recommendation)
|
||||
4. [Premium Preset: FLUX.2 [max] Recommendation](#premium-preset-flux2-max-recommendation)
|
||||
5. [Prompt Styles by Model](#prompt-styles-by-model)
|
||||
6. [Implementation: Adjust Prompts per Model](#implementation-adjust-prompts-per-model)
|
||||
|
||||
---
|
||||
|
||||
## Image Model Comparison Matrix
|
||||
|
||||
| Aspect | FLUX.2 [klein] | Riverflow V2 Max | FLUX.2 [max] |
|
||||
|--------|---|---|---|
|
||||
| **Architecture** | 4B parameters (lightweight) | Medium (optimized) | 32B parameters (frontier) |
|
||||
| **Best at** | Speed, cost, diagrams, simple scenes | Photorealism, prompt understanding, details | Complex scenes, photorealism, consistency |
|
||||
| **Prompt complexity** | Simple (2-3 sentences) | Medium (detailed) | Complex (very detailed, technical specs) |
|
||||
| **Text in images** | Poor | Decent | Excellent |
|
||||
| **Multi-reference** | No | No | Yes (up to 10 images) |
|
||||
| **Cost/image** | $0.014–0.042 | $0.03 flat | $0.07–0.21 |
|
||||
| **Speed** | ⚡⚡⚡ Fast | ⚡⚡ Medium | ⚡ Slower (higher quality) |
|
||||
| **Photorealism** | Good | Very good | Excellent |
|
||||
| **Consistency** | Good | Very good | Excellent |
|
||||
| **Prompt adherence** | Good (simple prompts) | Excellent | Excellent (complex prompts) |
|
||||
| **For blog articles** | ✅ Hero images, diagrams | ✅ Professional photos, diagrams | ✅ Flagship/hero images |
|
||||
| **Failure modes** | Complex scenes, text | Rare | Rare |
|
||||
| **When to use** | Budget tier, speed matters | Balanced tier, default | Premium tier, quality paramount |
|
||||
|
||||
---
|
||||
|
||||
## Budget Preset: FLUX.2 [klein] Recommendation
|
||||
|
||||
### Why FLUX.2 [klein]?
|
||||
|
||||
```
|
||||
✅ Cheapest: $0.014/MP (first megapixel)
|
||||
✅ Fastest: Generates in ~3 seconds
|
||||
✅ Good enough: Handles simple prompts very well
|
||||
✅ Diagrams: Excellent for technical diagrams, dashboards
|
||||
✅ Illustrations: Good for minimalist, illustrated styles
|
||||
❌ Not ideal: Complex photorealistic scenes, text in images
|
||||
❌ Not ideal: Multiple objects with precise spatial relationships
|
||||
```
|
||||
|
||||
**Price:** $0.014 (first MP) + $0.001 (each additional MP)
|
||||
- **Standard 1024×576 (16:9):** ~$0.015–0.020
|
||||
- **Square 512×512 (1:1):** ~$0.011–0.015
|
||||
|
||||
### Prompt Style for FLUX.2 [klein]
|
||||
|
||||
**Template (SIMPLE, 2-3 sentences MAX):**
|
||||
|
||||
```
|
||||
[Subject/Dashboard/Diagram name], [key elements], [style], [colors]
|
||||
```
|
||||
|
||||
**✅ Good prompts for klein:**
|
||||
|
||||
```
|
||||
1. HERO IMAGE (Dashboard)
|
||||
"N8n workflow automation dashboard showing colorful nodes
|
||||
and connections on blue background, minimalist modern interface,
|
||||
professional SaaS design"
|
||||
|
||||
2. DIAGRAM (Simple technical)
|
||||
"Workflow architecture diagram showing trigger, action, condition
|
||||
components with arrows, clean lines, blue and purple palette,
|
||||
technical illustration style"
|
||||
|
||||
3. ILLUSTRATION (Minimalist)
|
||||
"Minimalist illustration of automation concept with interconnected
|
||||
gears and nodes, flat design, blues and greens, modern tech aesthetic"
|
||||
|
||||
4. SCREENSHOT (Simple)
|
||||
"N8n interface showing workflow execution panel with status
|
||||
indicators, clean layout, professional dashboard view"
|
||||
```
|
||||
|
||||
**❌ BAD prompts for klein (will waste money):**
|
||||
|
||||
```
|
||||
✗ "A hyper-detailed photorealistic photo of a developer working
|
||||
with N8n, cinematic lighting with volumetric fog, 4K quality,
|
||||
shot on RED camera with lut grading..."
|
||||
↳ TOO COMPLEX: klein will fail or produce mediocre results
|
||||
|
||||
✗ "Dashboard showing text 'AUTOMATION HUB' in neon letters,
|
||||
very detailed typography, complex sci-fi design..."
|
||||
↳ TEXT RENDERING: klein struggles with readable text
|
||||
|
||||
✗ "Intricate 3D render of a neural network architecture with
|
||||
thousands of nodes, each labeled with precise colors..."
|
||||
↳ IMPOSSIBLE: klein can't handle this complexity
|
||||
```
|
||||
|
||||
### Implementation for Budget Preset
|
||||
|
||||
```php
|
||||
// Budget preset prompt generation
|
||||
$prompt_klein = "N8n workflow dashboard screenshot, showing " .
|
||||
"colorful workflow nodes and connections on blue background, " .
|
||||
"minimalist professional interface";
|
||||
|
||||
// Keep it short and simple
|
||||
$image_spec = [
|
||||
'model' => 'black-forest-labs/flux.2-klein',
|
||||
'prompt' => $prompt_klein, // 2-3 sentences
|
||||
'size' => '1024x576', // Standard blog size
|
||||
'guidance_scale' => 3.0, // Default for klein
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Balanced Preset: Riverflow V2 Max Recommendation
|
||||
|
||||
### Why Riverflow V2 Max?
|
||||
|
||||
```
|
||||
✅ Excellent prompt adherence: Understands nuanced instructions
|
||||
✅ Photorealistic: Produces professional, polished images
|
||||
✅ Context-aware: Handles detailed specifications well
|
||||
✅ Details: Sharp textures, consistent lighting, realistic materials
|
||||
✅ Speed: Reasonable (~8-15 seconds)
|
||||
✅ Cost: Flat $0.03/image regardless of size (predictable)
|
||||
❌ Slightly more expensive: $0.03 vs FLUX.2 klein's $0.014
|
||||
❌ No multi-reference: Can't maintain consistency across multiple images
|
||||
```
|
||||
|
||||
**Price:** $0.03 flat per image (regardless of size)
|
||||
- **Any size:** Consistent $0.03
|
||||
|
||||
### Prompt Style for Riverflow V2 Max
|
||||
|
||||
**Template (DETAILED but CONCISE, 3-4 sentences):**
|
||||
|
||||
```
|
||||
[Subject details], [action/context], [style/mood], [lighting], [technical specs]
|
||||
```
|
||||
|
||||
**✅ Good prompts for Riverflow:**
|
||||
|
||||
```
|
||||
1. HERO IMAGE (Professional dashboard)
|
||||
"N8n automation dashboard interface displaying real-time workflow
|
||||
execution with colorful nodes and connections. Clean minimalist design
|
||||
with blue accent colors, modern SaaS aesthetic. Professional product
|
||||
photography style with studio lighting, sharp details, clean layout"
|
||||
|
||||
2. DIAGRAM (Technical with style)
|
||||
"Technical architecture diagram visualizing workflow components:
|
||||
trigger module, conditional routing, action nodes. Components connected
|
||||
with clean lines and arrows. Flat design style, blue and purple color
|
||||
palette, professional technical illustration, clear readability"
|
||||
|
||||
3. PROFESSIONAL PHOTO (Realistic context)
|
||||
"A developer's laptop screen showing N8n automation workflows with
|
||||
detailed node visualization. Warm office lighting with subtle desk lamp,
|
||||
shallow depth of field, professional product photography, clear screen
|
||||
details visible, modern workspace setup"
|
||||
|
||||
4. INFOGRAPHIC (Educational)
|
||||
"Educational infographic showing 'How N8n Automation Works' with
|
||||
step-by-step visual flow. Icons and diagrams arranged in logical sequence,
|
||||
minimalist design language, blue and grey colors, professional presentation
|
||||
style, clean typography and spacing"
|
||||
```
|
||||
|
||||
**❌ LESS EFFECTIVE for Riverflow:**
|
||||
|
||||
```
|
||||
✗ "Hyper-detailed 8K photorealistic RAW file of a futuristic
|
||||
neural network with quantum computing effects..."
|
||||
↳ OVERKILL: Riverflow is excellent but not designed for sci-fi/fantasy
|
||||
|
||||
✗ "Complex scene with 47 different UI elements, each precisely
|
||||
positioned with specific pixel values..."
|
||||
↳ TOO PRESCRIPTIVE: Riverflow works best with conceptual direction,
|
||||
not pixel-perfect specs
|
||||
|
||||
✗ "Neon text glowing in the dark, cinematic with fog..."
|
||||
↳ LESS IDEAL: Not Riverflow's strongest point (use FLUX.2 max for this)
|
||||
```
|
||||
|
||||
### Implementation for Balanced Preset
|
||||
|
||||
```php
|
||||
// Balanced preset prompt generation
|
||||
$prompt_riverflow = "N8n automation dashboard interface displaying " .
|
||||
"real-time workflow execution with colorful nodes and connections. " .
|
||||
"Clean minimalist design with blue accent colors, modern SaaS aesthetic. " .
|
||||
"Professional product photography style with studio lighting, " .
|
||||
"sharp details, clean layout";
|
||||
|
||||
$image_spec = [
|
||||
'model' => 'sourceful/riverflow-v2-max',
|
||||
'prompt' => $prompt_riverflow, // 3-4 sentences, detailed
|
||||
'size' => '1024x576', // Standard blog size
|
||||
'guidance_scale' => 3.5, // Moderate adherence
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Premium Preset: FLUX.2 [max] Recommendation
|
||||
|
||||
### Why FLUX.2 [max]?
|
||||
|
||||
```
|
||||
✅ Frontier quality: Best-in-class photorealism and detail
|
||||
✅ Complex prompts: Handles intricate specifications excellently
|
||||
✅ Text rendering: Can generate readable text in images
|
||||
✅ Multi-reference: Maintains consistency across up to 10 reference images
|
||||
✅ Photorealism: Superior material properties, lighting, spatial logic
|
||||
✅ Professional: Production-grade results for flagship content
|
||||
❌ Expensive: $0.07–0.21 per image (highest cost)
|
||||
❌ Slower: Takes ~20-30 seconds (but worth it for quality)
|
||||
```
|
||||
|
||||
**Price:** $0.07 (first MP) + $0.03 (each additional MP)
|
||||
- **Standard 1024×576 (16:9):** ~$0.20–0.25
|
||||
- **High res 2048×2048 (4K):** ~$0.60–0.80
|
||||
|
||||
### Prompt Style for FLUX.2 [max]
|
||||
|
||||
**Template (VERY DETAILED, 4-6 sentences with technical specs):**
|
||||
|
||||
```
|
||||
[Technical foundation], [main subject + action], [environment/context],
|
||||
[lighting + mood], [style + aesthetics], [technical specifications]
|
||||
```
|
||||
|
||||
**✅ Good prompts for FLUX.2 [max]:**
|
||||
|
||||
```
|
||||
1. HERO IMAGE (Flagship dashboard)
|
||||
"Professional product photography of N8n automation dashboard interface
|
||||
on a modern laptop screen. The dashboard displays a real-time workflow
|
||||
with multiple interconnected nodes in blue, purple, and teal colors.
|
||||
The scene is set in a minimalist tech office with warm tungsten lighting
|
||||
creating soft shadows on black marble desk. Shot with shallow depth of field,
|
||||
sharp focus on the screen, bokeh background. Commercial photography style
|
||||
with crisp details, accurate color reproduction, professional white-balance.
|
||||
4K resolution with film-grain aesthetics"
|
||||
|
||||
2. CINEMATIC DIAGRAM (Complex technical)
|
||||
"Technical architecture diagram for N8n automation system rendered in
|
||||
3D isometric perspective. The diagram shows trigger events (red nodes),
|
||||
conditional logic (blue nodes), and action outputs (green nodes) connected
|
||||
with flowing animated pathways. Modern tech aesthetic with gradient backgrounds,
|
||||
volumetric lighting effects, subtle motion blur on connector lines.
|
||||
Professional technical illustration merged with cinematic rendering.
|
||||
Rendered with physically-based materials, global illumination, and
|
||||
ambient occlusion for depth. 3D product visualization style"
|
||||
|
||||
3. HERO ILLUSTRATION (Complex artistic)
|
||||
"Conceptual illustration of automation workflow represented as flowing
|
||||
water streams. Multiple streams of different colors merge and split,
|
||||
representing workflow logic and data routing. Streams flow through modern
|
||||
architectural elements (nodes, connections). Watercolor painting style
|
||||
blended with digital rendering. Cool color palette with blues and teals,
|
||||
warm accent lights. Wide-angle perspective showing expansive workflow.
|
||||
Ethereal, professional, educational aesthetic"
|
||||
|
||||
4. LIFESTYLE + PRODUCT (Complex scene)
|
||||
"A product lifestyle photograph showing N8n dashboard on a developer's
|
||||
laptop alongside coffee, notebook, and desk setup in a modern home office.
|
||||
Natural morning sunlight streams through large windows creating warm golden
|
||||
hour lighting. The scene includes shallow depth of field with sharp focus on
|
||||
the laptop screen showing the N8n interface. Modern Scandinavian aesthetic,
|
||||
minimalist desk setup with wood and metal surfaces. Shot on full-frame camera
|
||||
with 35mm lens, warm color grading, professional lifestyle photography,
|
||||
authentic and aspirational atmosphere"
|
||||
```
|
||||
|
||||
**✅ ADVANCED: Using FLUX.2 [max]'s strengths:**
|
||||
|
||||
```
|
||||
JSON Prompting (FLUX.2 max supports structured prompts):
|
||||
{
|
||||
"scene": "Professional product photography",
|
||||
"subject": "N8n dashboard on laptop",
|
||||
"environment": "Modern tech office, minimalist desk",
|
||||
"lighting": "Warm tungsten, side-lighting, soft shadows",
|
||||
"style": "Commercial product photography",
|
||||
"color_palette": ["#003D9B", "#6F42C1", "#17A2B8"],
|
||||
"technical_specs": "4K, shallow DOF, f/2.8, 85mm lens",
|
||||
"mood": "Professional, modern, trustworthy"
|
||||
}
|
||||
```
|
||||
|
||||
### Implementation for Premium Preset
|
||||
|
||||
```php
|
||||
// Premium preset prompt generation
|
||||
$prompt_flux_max = "Professional product photography of N8n automation " .
|
||||
"dashboard displayed on a modern developer's laptop screen. " .
|
||||
"The dashboard shows real-time workflow execution with colorful " .
|
||||
"interconnected nodes. Scene set in minimalist tech office with " .
|
||||
"warm tungsten studio lighting creating soft shadows on black marble " .
|
||||
"desk surface. Shallow depth of field with sharp focus on screen, " .
|
||||
"bokeh background. Commercial photography style with crisp details, " .
|
||||
"accurate colors, white-balanced. 4K resolution";
|
||||
|
||||
$image_spec = [
|
||||
'model' => 'black-forest-labs/flux.2-max',
|
||||
'prompt' => $prompt_flux_max, // 4-6 sentences, very detailed
|
||||
'size' => '1024x576', // Can also do 2048×2048 for premium
|
||||
'guidance_scale' => 4.0, // High adherence for complex prompts
|
||||
];
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompt Styles by Model
|
||||
|
||||
### Quick Reference: How to Structure Prompts
|
||||
|
||||
| Model | Length | Complexity | Style | Strength |
|
||||
|-------|--------|-----------|--------|-----------|
|
||||
| **FLUX.2 [klein]** | 1-2 sentences | Simple | Functional description | Speed + cost |
|
||||
| **Riverflow V2 Max** | 3-4 sentences | Medium | Detailed but concise | Photorealism + clarity |
|
||||
| **FLUX.2 [max]** | 4-6 sentences | Complex | Very detailed with specs | Quality + complexity handling |
|
||||
|
||||
### Model-Specific Prompt Tips
|
||||
|
||||
#### FLUX.2 [klein] Tips
|
||||
```
|
||||
✓ Front-load the main subject (Klein prioritizes early tokens)
|
||||
✓ Use simple adjectives: "minimalist", "clean", "blue"
|
||||
✓ Avoid: "volumetric fog", "subsurface scattering", "ray-traced"
|
||||
✓ Best for: Diagrams, simple dashboards, minimalist illustrations
|
||||
✓ Template: [Main subject], [2 key details], [style]
|
||||
```
|
||||
|
||||
#### Riverflow V2 Max Tips
|
||||
```
|
||||
✓ Include context and environment details
|
||||
✓ Specify lighting style: "studio lighting", "golden hour"
|
||||
✓ Use photography terms: "shallow DOF", "bokeh", "35mm lens"
|
||||
✓ Can include moderate technical specs
|
||||
✓ Best for: Professional photos, detailed diagrams, product shots
|
||||
✓ Template: [Subject + context], [details], [lighting], [style]
|
||||
```
|
||||
|
||||
#### FLUX.2 [max] Tips
|
||||
```
|
||||
✓ Can use very specific technical vocabulary
|
||||
✓ Specify exact materials and properties
|
||||
✓ Include color codes (HEX) for brand accuracy
|
||||
✓ Can describe complex spatial relationships
|
||||
✓ Use JSON prompting for highest precision
|
||||
✓ Front-load important elements (tokens matter)
|
||||
✓ Best for: Hero images, complex scenes, flagship content
|
||||
✓ Template: [Technical specs], [subject], [environment], [lighting], [style], [resolution/format]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation: Adjust Prompts per Model
|
||||
|
||||
### Phase 1: Update Prompt Generation System
|
||||
|
||||
Modify the prompt generation agent to output **model-specific prompts** based on selected image model:
|
||||
|
||||
```php
|
||||
<?php
|
||||
/**
|
||||
* Update: Modify generate_image_prompts() to output model-specific prompts
|
||||
*/
|
||||
|
||||
public static function generate_image_prompts(
|
||||
$article_markdown,
|
||||
$placement_data,
|
||||
$writing_model,
|
||||
$image_model, // NEW PARAMETER
|
||||
$style_preference = 'minimalist'
|
||||
) {
|
||||
// Select system prompt based on image model
|
||||
$system_prompt = self::get_prompt_generation_system_prompt_for_model(
|
||||
$image_model // Adjusts prompt style based on model
|
||||
);
|
||||
|
||||
$user_input = json_encode([
|
||||
'article' => $article_markdown,
|
||||
'placement_points' => $placement_data['image_placement_points'],
|
||||
'style_preference' => $style_preference,
|
||||
'image_count' => $placement_data['recommended_image_count'],
|
||||
'target_image_model' => $image_model, // NEW: Tell agent which model
|
||||
]);
|
||||
|
||||
// ... rest of API call
|
||||
}
|
||||
|
||||
/**
|
||||
* Return system prompt customized for image model
|
||||
*/
|
||||
private static function get_prompt_generation_system_prompt_for_model( $image_model ) {
|
||||
$model_configs = [
|
||||
'black-forest-labs/flux.2-klein' => [
|
||||
'name' => 'FLUX.2 [klein]',
|
||||
'prompt_length' => '1-2 sentences',
|
||||
'complexity' => 'simple',
|
||||
'guidance' => 'Keep prompts short and simple. Focus on main subject,
|
||||
key details, and style. Avoid complex scenes or technical specifications.',
|
||||
'template' => 'Subject, key elements, style, color palette'
|
||||
],
|
||||
'sourceful/riverflow-v2-max' => [
|
||||
'name' => 'Riverflow V2 Max',
|
||||
'prompt_length' => '3-4 sentences',
|
||||
'complexity' => 'medium-detailed',
|
||||
'guidance' => 'Include context, environment details, lighting style,
|
||||
and photographic specifications. Model excels at photorealism.',
|
||||
'template' => 'Subject + context, environment details, lighting style,
|
||||
photography style, technical specs'
|
||||
],
|
||||
'black-forest-labs/flux.2-max' => [
|
||||
'name' => 'FLUX.2 [max]',
|
||||
'prompt_length' => '4-6 sentences',
|
||||
'complexity' => 'very-detailed-technical',
|
||||
'guidance' => 'Use detailed technical vocabulary. Include exact materials,
|
||||
color codes (HEX), spatial relationships, and specifications.
|
||||
Can use JSON prompting for maximum precision.',
|
||||
'template' => 'Technical foundation, main subject + action, environment,
|
||||
lighting + mood, style + aesthetics, technical specifications'
|
||||
]
|
||||
];
|
||||
|
||||
$config = $model_configs[ $image_model ] ?? $model_configs['sourceful/riverflow-v2-max'];
|
||||
|
||||
return <<<PROMPT
|
||||
System Prompt: Image Prompt Generator for {$config['name']}
|
||||
═══════════════════════════════════════════════════════════════
|
||||
|
||||
You are an Image Prompt Engineer specializing in {$config['name']}.
|
||||
|
||||
Target Model: {$config['name']}
|
||||
Prompt Length: {$config['prompt_length']}
|
||||
Complexity Level: {$config['complexity']}
|
||||
|
||||
Your job: Create precise, cost-efficient prompts optimized for {$config['name']}.
|
||||
|
||||
{$config['guidance']}
|
||||
|
||||
Prompt Template for {$config['name']}:
|
||||
{$config['template']}
|
||||
|
||||
Generate prompts that exploit {$config['name']}'s strengths and avoid its weaknesses.
|
||||
|
||||
[Rest of standard prompt generation instructions...]
|
||||
PROMPT;
|
||||
}
|
||||
```
|
||||
|
||||
### Phase 2: Update UI to Show Image Model Info
|
||||
|
||||
```php
|
||||
// In image review modal, show user:
|
||||
// "Image Model: Riverflow V2 Max Preview
|
||||
// Cost per image: $0.03
|
||||
// Strength: Photorealism + detailed specifications"
|
||||
```
|
||||
|
||||
### Phase 3: Testing Prompts Before Full Generation
|
||||
|
||||
```php
|
||||
// Optional: Generate 1 test image first, show user, ask "Continue with this style?"
|
||||
// This costs $0.03 but saves $0.09 if user wants different result
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Efficiency Recommendations
|
||||
|
||||
### Pick the Right Model First
|
||||
|
||||
**Never:**
|
||||
- Use FLUX.2 [max] for simple diagrams (expensive, wastes quality)
|
||||
- Use FLUX.2 [klein] for complex photorealistic scenes (will fail)
|
||||
- Generate with wrong model, get bad result, regenerate with right model (double cost)
|
||||
|
||||
**Always:**
|
||||
- Match model to task complexity
|
||||
- Match prompt style to model capabilities
|
||||
- Test prompt with budget model first if unsure
|
||||
|
||||
### Cost per Article by Model
|
||||
|
||||
| Scenario | Model | Cost | Quality |
|
||||
|----------|-------|------|---------|
|
||||
| Hero + 2 diagrams | FLUX.2 klein | $0.045–0.060 | Good ✅ |
|
||||
| Hero + professional photo | Riverflow V2 Max | $0.06 | Excellent ✅ |
|
||||
| Flagship hero image | FLUX.2 max | $0.20–0.25 | Frontier ✅ |
|
||||
| ❌ Flagship with klein | FLUX.2 klein | $0.020 + regenerate | Waste ❌ |
|
||||
|
||||
---
|
||||
|
||||
## Summary: Model Recommendations by Preset
|
||||
|
||||
### 🟢 Budget Preset
|
||||
**Image Model:** FLUX.2 [klein] 4B
|
||||
**Cost:** $0.014–0.042/image
|
||||
**Prompt style:** Simple, 1-2 sentences, functional
|
||||
**Best for:** Diagrams, dashboards, minimalist illustrations
|
||||
**Template:** `[Subject], [key elements], [style]`
|
||||
|
||||
### 🟡 Balanced Preset (RECOMMENDED DEFAULT)
|
||||
**Image Model:** Riverflow V2 Max Preview
|
||||
**Cost:** $0.03/image flat
|
||||
**Prompt style:** Detailed, 3-4 sentences, photorealistic
|
||||
**Best for:** Professional photos, infographics, product shots
|
||||
**Template:** `[Subject + context], [details], [lighting], [style]`
|
||||
|
||||
### 🔴 Premium Preset
|
||||
**Image Model:** FLUX.2 [max]
|
||||
**Cost:** $0.07–0.21/image
|
||||
**Prompt style:** Very detailed, 4-6 sentences, technical specs
|
||||
**Best for:** Flagship images, complex scenes, hero content
|
||||
**Template:** `[Tech foundation], [subject], [environment], [lighting], [style], [specs]`
|
||||
|
||||
---
|
||||
|
||||
**Document version:** 1.0
|
||||
**Date:** January 27, 2026
|
||||
**Status:** Ready for Implementation
|
||||
Reference in New Issue
Block a user