AI Recommendations

AI_TASKS_IMPLEMENTATION.md

@@ -0,0 +1,287 @@
+# AI Tasks Client Implementation Summary
+
+## Overview
+
+This document describes the client-side implementation of AI-powered tasks for the Progress Planner WordPress plugin. The implementation enables the plugin to fetch AI tasks from the SaaS server and execute them with real-time AI analysis.
+
+## Architecture
+
+### Components Created
+
+1. **API Client** (`/code/classes/class-ai-tasks.php`)
+   - Handles communication with the SaaS server
+   - Fetches AI tasks from `/wp-json/progress-planner-saas/v1/suggested-todo`
+   - Executes AI tasks via `/wp-json/progress-planner-saas/v1/execute-ai-task`
+   - Implements response caching to avoid repeated API calls
+
+2. **Task Provider** (`/code/classes/suggested-tasks/providers/class-ai-tasks-from-server.php`)
+   - Main provider class that manages AI tasks
+   - Fetches tasks from the server on initialization
+   - Injects AI tasks into the task system
+   - Handles AJAX requests for task execution
+   - Renders the popover UI for AI analysis results
+
+3. **Base AI Task Class** (`/code/classes/suggested-tasks/providers/class-ai-task.php`)
+   - Abstract base class for AI-powered tasks
+   - Can be extended for custom AI task implementations
+   - Provides common functionality for AI task handling
+
+4. **JavaScript Handler** (`/code/assets/js/recommendations/ai-task.js`)
+   - Manages client-side AI task execution
+   - Handles loading states, results display, and error handling
+   - Formats AI responses with basic HTML formatting
+   - Integrates with the existing task management system
+
+5. **Styles** (`/code/assets/css/ai-task.css`)
+   - Visual styling for AI task UI components
+   - Responsive design for mobile and desktop
+   - Loading spinner animations
+   - Result and error state styling
+
+## Integration Points
+
+### 1. Tasks Manager Registration
+
+The AI task provider is registered in `/code/classes/suggested-tasks/class-tasks-manager.php`:
+
+```php
+use Progress_Planner\Suggested_Tasks\Providers\AI_Tasks_From_Server;
+
+// In constructor:
+new AI_Tasks_From_Server(),
+```
+
+### 2. Base Class Method
+
+The AI_Tasks class is accessible via the main plugin instance:
+
+```php
+\progress_planner()->get_ai_tasks()
+```
+
+This is defined in `/code/classes/class-base.php` with the `@method` annotation.
+
+### 3. REST API Metadata
+
+AI task metadata fields are registered in `/code/classes/class-suggested-tasks.php`:
+
+- `is_ai_task` (boolean) - Identifies AI-powered tasks
+- `ai_task_server_id` (number) - Server-side task ID
+- `ai_prompt_template` (string) - Template for AI prompts
+- `ai_provider` (string) - AI provider (e.g., "chatgpt")
+- `ai_max_tokens` (number) - Token limit for AI responses
+- `branding` (string) - Branding identifier for task filtering
+
+## User Flow
+
+1. **Task Discovery**
+   - Plugin fetches AI tasks from SaaS server on initialization
+   - Tasks are injected into the local task database
+   - AI tasks appear in the task list with an "Analyze" button
+
+2. **Task Execution**
+   - User clicks "Analyze" button
+   - Popover opens with task description
+   - User clicks "Analyze" in popover to execute
+   - Loading indicator shows during AI processing (10-30 seconds)
+
+3. **Result Display**
+   - AI response is formatted and displayed in the popover
+   - Response is cached to avoid repeated API calls
+   - User can retry on error
+
+4. **Error Handling**
+   - Network errors display friendly error messages
+   - Retry button appears on errors
+   - Timeout handling for long-running requests
+
+## API Communication
+
+### Fetch AI Tasks
+
+**Request:**
+```
+GET /wp-json/progress-planner-saas/v1/suggested-todo
+Parameters:
+  - site: Current site URL
+  - license_key: Plugin license key
+  - branding: (optional) Branding filter
+```
+
+**Response:**
+```json
+[
+  {
+    "task_id": 123,
+    "title": "Analyze Your Homepage",
+    "is_ai_task": true,
+    "ai_prompt_template": "Analyze the homepage of <url>...",
+    "ai_provider": "chatgpt",
+    "ai_max_tokens": 500,
+    "branding": ""
+  }
+]
+```
+
+### Execute AI Task
+
+**Request:**
+```
+POST /wp-json/progress-planner-saas/v1/execute-ai-task
+Body:
+  - task_id: Server task ID
+  - site_url: Site URL to analyze
+  - license_key: Plugin license key
+```
+
+**Response (Success):**
+```json
+{
+  "success": true,
+  "task_id": 123,
+  "ai_response": "This site appears to be...",
+  "token_usage": {
+    "prompt_tokens": 150,
+    "completion_tokens": 85,
+    "total_tokens": 235
+  }
+}
+```
+
+**Response (Error):**
+```json
+{
+  "code": "ai_execution_failed",
+  "message": "Error description",
+  "data": {"status": 500}
+}
+```
+
+## Caching Strategy
+
+The implementation uses WordPress transients for caching:
+
+- **Cache Key:** `prpl_ai_response_{task_id}`
+- **Cache Duration:** 1 week (WEEK_IN_SECONDS)
+- **Cache Purpose:** Avoid repeated API calls for the same task
+- **Cache Clearing:** Can be manually cleared per task
+
+## Security Considerations
+
+1. **Capability Checks**
+   - Only users with `manage_options` capability can execute AI tasks
+   - Same capability required for viewing and managing tasks
+
+2. **Nonce Verification**
+   - All AJAX requests use WordPress nonce verification
+   - Nonce is generated with `progress_planner` action
+
+3. **Data Sanitization**
+   - All user input is sanitized using WordPress functions
+   - Task IDs validated before API calls
+
+4. **Rate Limiting**
+   - Server-side rate limiting handled by SaaS server
+   - Client-side caching reduces unnecessary requests
+
+## File Structure
+
+```
+/code/
+├── classes/
+│   ├── class-ai-tasks.php                              # API client
+│   ├── class-base.php                                  # Updated with AI_Tasks method
+│   ├── class-suggested-tasks.php                       # Updated with AI metadata
+│   └── suggested-tasks/
+│       ├── class-tasks-manager.php                     # Updated with AI provider
+│       └── providers/
+│           ├── class-ai-task.php                       # Base AI task class
+│           └── class-ai-tasks-from-server.php          # AI task provider
+├── assets/
+│   ├── js/
+│   │   └── recommendations/
+│   │       └── ai-task.js                             # JavaScript handler
+│   └── css/
+│       └── ai-task.css                                # Styles
+└── AI_TASKS_IMPLEMENTATION.md                         # This file
+```
+
+## Testing Checklist
+
+Before deploying, verify:
+
+- [ ] AI tasks are fetched from the SaaS server on plugin load
+- [ ] Tasks appear in the task list with proper styling
+- [ ] "Analyze" button opens the popover correctly
+- [ ] Loading state displays during AI processing
+- [ ] AI responses are formatted and displayed properly
+- [ ] Cached responses show "(Cached result)" indicator
+- [ ] Error messages display correctly on failures
+- [ ] Retry functionality works after errors
+- [ ] Only users with `manage_options` can execute tasks
+- [ ] Nonce verification prevents CSRF attacks
+- [ ] CSS loads properly on Progress Planner and Dashboard pages
+- [ ] JavaScript has no console errors
+- [ ] Mobile responsive design works correctly
+
+## Future Enhancements
+
+Potential improvements for future versions:
+
+1. **Task Completion Tracking**
+   - Mark AI tasks as complete after viewing response
+   - Award points for completing AI tasks
+
+2. **Response History**
+   - Store multiple AI responses per task
+   - Allow users to view previous analyses
+
+3. **Custom AI Prompts**
+   - Allow users to modify AI prompts
+   - Provide prompt templates for common use cases
+
+4. **Branding Integration**
+   - Filter tasks by site branding
+   - Show brand-specific AI recommendations
+
+5. **Analytics Integration**
+   - Track AI task usage and completion rates
+   - Measure effectiveness of AI recommendations
+
+6. **Export Functionality**
+   - Export AI responses to PDF or text
+   - Share responses via email
+
+## Support and Troubleshooting
+
+### Common Issues
+
+1. **Tasks Not Appearing**
+   - Verify license key is set correctly
+   - Check server-side task configuration
+   - Ensure SaaS server is accessible
+
+2. **Execution Failures**
+   - Check network connectivity
+   - Verify API credentials
+   - Review server-side error logs
+
+3. **Styling Issues**
+   - Clear browser cache
+   - Verify CSS file is enqueued
+   - Check for theme conflicts
+
+### Debug Mode
+
+Enable WordPress debug mode to see detailed error messages:
+
+```php
+define('WP_DEBUG', true);
+define('WP_DEBUG_LOG', true);
+```
+
+## Credits
+
+Implementation by: Sculptor AI
+Based on: Progress Planner architecture and SaaS server integration
+Date: 2025-10-28