# MxChat Image Analysis

**Image analysis add-on for MxChat using OpenAI Vision and Grok APIs**

## Overview

MxChat Image Analysis enhances your MxChat chatbot with powerful AI-driven image analysis capabilities. Users can upload images directly in the chat and receive intelligent analysis, descriptions, OCR text extraction, and answers to specific questions about the images.

## Features

- **Multiple AI Models**: Support for OpenAI GPT-4V and Grok Vision
- **Image Editing**: Advanced image editing with Google Gemini 2.5 Flash and Gemini 3 Pro
- **Automatic Retry**: Smart retry mechanism with up to 3 attempts for failed operations
- **Flexible Upload**: File selection, copy/paste, and drag-and-drop support
- **Image Formats**: JPEG, PNG, GIF, and WebP
- **Custom Prompts**: Customize how AI analyzes images with professional templates
- **Chat Integration**: Seamless integration with existing MxChat conversations
- **Chat History**: Image uploads are properly tracked in conversation history
- **Smart Resizing**: Automatic image optimization for faster processing
- **Rate Limiting**: Configurable limits for images per message and file sizes

## Requirements

- **MxChat Basic Plugin**: Must be installed and active
- **MxChat Pro License**: Required for Vision functionality
- **API Keys**: OpenAI API key and/or xAI (Grok) API key, Google Gemini API key (for image editing)
- **WordPress**: 5.8 or higher
- **PHP**: 7.4 or higher

## Installation

1. Upload the `mxchat-vision` folder to `/wp-content/plugins/`
2. Activate the plugin through WordPress admin
3. Configure API keys in MxChat main settings
4. Enable Vision in **MxChat → Vision** settings

## Configuration

### Basic Settings
- **Enable/Disable**: Toggle vision analysis functionality
- **AI Model**: Choose between OpenAI Vision or Grok Vision
- **Max Images**: Set maximum images per message (1-10)
- **Max File Size**: Set maximum file size in MB (1-20)

### Image Editing Mode
- **Editing Models**: Choose between Gemini 2.5 Flash or Gemini 3 Pro
- **Aspect Ratios**: Support for 1:1, 16:9, 9:16, 4:3, and 3:4
- **Resolution Options**: 1K, 2K, 4K, and 8K output sizes (model dependent)
- **Custom Prompts**: Define custom editing instructions for consistent results

### Custom Analysis Prompts
Create custom instructions for how AI should analyze images

## Retry Mechanism

The plugin includes an intelligent retry system for image editing operations:

- **Automatic Retries**: Up to 3 attempts for failed operations
- **Exponential Backoff**: Smart delays between retries (2s, 4s)
- **Error Detection**: Only retries transient errors (timeouts, rate limits, server errors)
- **Detailed Logging**: All retry attempts are logged for troubleshooting
- **Transparent Results**: Response includes attempt count for monitoring

### Retryable Errors
The system automatically retries on:
- Network timeouts and connection issues
- Rate limiting (429 errors)
- Server errors (500, 502, 503, 504)
- Gateway timeouts
- Service unavailability

## Usage

1. **For Users**: Click the camera icon in the chat toolbar
2. **Upload Images**: Select files, paste from clipboard, or drag-and-drop
3. **Ask Questions**: Type specific questions about the uploaded images
4. **Get Analysis**: Receive detailed AI-powered analysis and answers
5. **Edit Images**: Switch to editing mode to transform images with AI

## API Keys Setup

### OpenAI API Key
1. Go to **MxChat → Settings**
2. Set your model to "GPT-4V" or "GPT-4o"
3. Enter your OpenAI API key
4. You can switch back to other models after saving

### Grok API Key (xAI)
1. Go to **MxChat → Settings**
2. Set your model to "Grok"
3. Enter your xAI API key
4. You can switch back to other models after saving

### Google Gemini API Key (for Image Editing)
1. Go to **MxChat → Settings**
2. Set your model to "Gemini"
3. Enter your Google API key
4. Enable image editing mode in Vision settings

## Changelog

= 1.0.6 = 
* Added: Automatic retry mechanism for image editing operations
* Added: Up to 3 retry attempts with exponential backoff
* Added: Intelligent error detection for retryable failures
* Improved: Reliability of image editing feature
* Improved: Error logging and debugging information
* Added: Attempt count in API responses for monitoring

= 1.0.5 = 
* Fixed: Input field now properly clears when image is uploaded in editing mode with "Disable User Input on Upload" enabled
* Fixed: Prevents pre-typed text from being sent with image when input should be disabled

= 1.0.4 = 
* Fixed: Image orientation for photos to display vertically
* Added: New setting to customize message displayed after image has been edited

= 1.0.3 = 
* Added: Image editing feature via Gemini 2.5 and Gemini 3
* Added: Multiple editing models with different capabilities
* Added: Support for various aspect ratios and resolutions

= 1.0.2 =
* Update Test

= 1.0.1 =
* Update Test

= 1.0.0 = 
* Initial Release
* OpenAI Vision (GPT-4V) support
* Grok Vision support
* Multiple image upload capability
* Custom analysis prompts
* Image format support (JPEG, PNG, GIF, WebP)

## File Structure

```
mxchat-vision/
├── mxchat-vision.php                 # Main plugin file
├── includes/
│   ├── class-mxchat-vision-core.php  # Core functionality class
│   ├── class-vision-processor.php    # Handles image analysis logic
│   ├── class-vision-models.php       # Manages OpenAI/Grok/Gemini API calls with retry
│   └── class-mxchat-vision-settings.php  # Settings/admin interface
├── admin/
│   ├── js/
│   │   └── vision-admin.js           # Admin panel JavaScript
│   ├── css/
│   │   └── vision-admin.css          # Admin styling
├── public/
│   ├── js/
│   │   └── vision-frontend.js        # Frontend image handling
│   ├── css/
│   │   └── vision-frontend.css       # Frontend styling
```

## Technical Details

### Retry Logic
The retry mechanism is implemented at two levels:

1. **HTTP Request Level**: Handles network-level failures with retry logic
2. **Image Editing Level**: Handles API-specific failures with intelligent retry

Both levels work together to provide maximum reliability for image editing operations.

### Performance Considerations
- Retry delays use exponential backoff to avoid overwhelming APIs
- Only transient errors trigger retries
- Permanent errors (invalid API keys, malformed requests) fail immediately
- All operations include timeout limits to prevent indefinite waiting

## Support

For support and documentation, visit [https://mxchat.ai/](https://mxchat.ai/)

## License

This plugin is proprietary software. All rights reserved.
