Add comprehensive documentation suit

docs/1.intro.md

@@ -0,0 +1,112 @@
+# 1. Introduction & Overview
+
+**Welcome to the PHP AI Client SDK** - A comprehensive, production-ready library that brings the power of multiple AI providers to any PHP application.
+
+## What is the PHP AI Client?
+
+The PHP AI Client SDK is an intelligent, unified interface that automatically handles model selection, provider management, and content generation across multiple AI providers. Built with enterprise-grade reliability and WordPress integration in mind, it provides both modern fluent APIs and traditional function-based approaches.
+
+**Key Features:**
+
+- ** Multi-Provider Support**: OpenAI, Anthropic, Google AI with automatic failover
+- ** Intelligent Model Selection**: Automatically chooses the best model for your content type
+- ** Two API Styles**: Modern fluent API and WordPress-style traditional functions
+- ** Multi-Modal Generation**: Text, images, speech, and audio generation
+- **️ Enterprise Ready**: Full error handling, type safety, and production patterns
+- ** WordPress Optimized**: Deep WordPress integration with hooks and filters
+- ** Usage Analytics**: Built-in tracking and optimization suggestions
+
+## Supported AI Providers & Capabilities
+
+### OpenAI
+- **Text Generation**: GPT models for content creation and conversations
+- **Image Generation**: DALL-E models for visual content creation
+- **Text-to-Speech**: High-quality voice synthesis with multiple voice options
+- **Vision**: Multimodal understanding of images, text, and audio
+- **Function Calling**: Structured tool use and API interactions
+
+### Anthropic
+- **Text Generation**: Claude models for advanced reasoning and long-form content
+- **Vision**: Image understanding and analysis capabilities
+- **Function Calling**: Sophisticated tool use and structured outputs
+- **Web Search**: Real-time web information integration
+
+### Google AI
+- **Text Generation**: Gemini models for conversational AI and content creation
+- **Image Generation**: Imagen models for high-quality visual content
+- **Multimodal Processing**: Native support for text, image, and audio inputs
+- **Web Search**: Integrated real-time information retrieval
+
+## Usage
+
+### Basic Example
+
+```php
+use WordPress\AiClient\AiClient;
+
+// Simple text generation
+$result = AiClient::generateTextResult('Write a product description for artisan coffee');
+echo $result->toText();
+
+// With configuration
+$result = AiClient::prompt('Write a product description')
+    ->usingTemperature(0.7)
+    ->generateTextResult();
+```
+
+### WordPress Integration
+
+```php
+// WordPress plugin example
+add_action('init', function() {
+    $content = AiClient::prompt('Generate blog post about sustainable energy')
+        ->generateTextResult()
+        ->toText();
+});
+```
+
+## Content Types
+
+```php
+// Text generation
+$text = AiClient::prompt('Write about sustainable energy')->generateTextResult();
+
+// Image generation
+$image = AiClient::prompt('Mountain landscape')->generateImageResult();
+
+// Text-to-speech
+$audio = AiClient::convertTextToSpeechResult('Hello world');
+```
+
+## What You Can Build
+
+### PHP Applications
+- **E-commerce Platforms**: Product descriptions, customer service, recommendations
+- **SaaS Applications**: Content generation, user onboarding, feature explanations  
+- **Analytics Tools**: Report generation, insight summaries, trend analysis
+- **Educational Platforms**: Course content, quizzes, personalized learning
+- **Content Management**: Automated publishing, social media, email campaigns
+
+### WordPress Solutions
+- **Content Plugins**: Auto-generate posts, pages, product descriptions
+- **Theme Features**: Dynamic content based on user preferences
+- **Admin Tools**: Bulk content generation, SEO optimization
+- **User Features**: Custom content creation for site visitors
+- **Marketing Tools**: Meta descriptions, social media posts, ad copy
+
+## Key Features
+
+- **Automatic Routing**: Content types are automatically routed to appropriate AI services
+- **Provider Failover**: Built-in reliability with automatic provider switching  
+- **Error Handling**: Comprehensive exception handling for production use
+- **Performance**: Built-in caching and batch processing capabilities
+
+## Getting Started
+
+Choose your path based on your needs:
+
+- ** [Quick Start](2.quick-start.md)** - Get up and running in 5 minutes
+- **️ [PHP Applications](3.php-applications.md)** - Framework integration patterns  
+- ** [WordPress Integration](4.wordpress-integration.md)** - WordPress-specific features
+- ** [Advanced Usage](5.advanced-usage.md)** - Production deployment, custom providers, optimization
+

docs/2.quick-start.md

@@ -0,0 +1,60 @@
+# 2. Quick Start Guide
+
+## Installation
+
+```bash
+composer require wordpress/php-ai-client
+```
+
+## Basic Usage
+
+```php
+use WordPress\AiClient\AiClient;
+
+// Simple text generation
+$result = AiClient::generateTextResult('Write a haiku about coding');
+echo $result->toText();
+
+// With configuration
+$result = AiClient::prompt('Write a product description')
+    ->usingTemperature(0.7)
+    ->generateTextResult();
+
+// Image generation
+$image = AiClient::generateImageResult('Mountain landscape');
+echo $image->toImageFile()->getUrl();
+```
+## Provider Authentication
+
+```php
+use WordPress\AiClient\AiClient;
+
+// Set up API keys
+$registry = AiClient::defaultRegistry();
+$registry->setProviderRequestAuthentication('openai', $_ENV['OPENAI_API_KEY']);
+$registry->setProviderRequestAuthentication('anthropic', $_ENV['ANTHROPIC_API_KEY']);
+
+// Use the SDK
+$result = AiClient::prompt('Write a product description')->generateTextResult();
+```
+
+## WordPress Integration
+
+```php
+// WordPress plugin
+add_action('init', function() {
+    $content = AiClient::prompt('Generate blog content')
+        ->generateTextResult()
+        ->toText();
+});
+```
+
+## Error Handling
+
+```php
+try {
+    $result = AiClient::prompt('Generate content')->generateTextResult();
+    echo $result->toText();
+} catch (Exception $e) {
+    error_log('AI generation failed: ' . $e->getMessage());
+}

docs/3.php-applications.md

@@ -0,0 +1,66 @@
+# 3. PHP Applications
+
+## Laravel Integration
+
+```php
+// config/services.php
+return [
+    'ai' => [
+        'openai_key' => env('OPENAI_API_KEY'),
+        'anthropic_key' => env('ANTHROPIC_API_KEY'),
+    ],
+];
+
+// app/Services/AiService.php
+class AiService {
+    public function generateText(string $prompt): string {
+        return AiClient::prompt($prompt)->generateTextResult()->toText();
+    }
+}
+```
+
+## Symfony Integration
+
+```php
+// services.yaml
+services:
+    app.ai_service:
+        class: App\Service\AiService
+        arguments:
+            $openaiKey: '%env(OPENAI_API_KEY)%'
+
+// src/Service/AiService.php
+class AiService {
+    public function __construct(private string $openaiKey) {
+        // Setup AI client
+    }
+
+    public function generate(string $prompt): string {
+        return AiClient::prompt($prompt)->generateTextResult()->toText();
+    }
+}
+```
+
+## Production Considerations
+
+```php
+// Rate limiting
+$result = AiClient::prompt($prompt)
+    ->usingMaxTokens(500)
+    ->generateTextResult();
+
+// Error handling
+try {
+    $result = AiClient::prompt($prompt)->generateTextResult();
+} catch (AiClientException $e) {
+    // Handle AI-specific errors
+    return 'Content generation unavailable';
+}
+
+// Caching
+$key = 'ai_' . md5($prompt);
+if (!$cached = cache()->get($key)) {
+    $cached = AiClient::prompt($prompt)->generateTextResult()->toText();
+    cache()->put($key, $cached, 3600);
+}
+```

docs/4.wordpress-integration.md

@@ -0,0 +1,77 @@
+# 4. WordPress Integration
+
+## Basic WordPress Plugin
+
+```php
+<?php
+/*
+Plugin Name: AI Content Generator
+Description: Generate content using AI
+*/
+
+use WordPress\AiClient\AiClient;
+
+class AiContentPlugin {
+    public function __construct() {
+        add_action('init', [$this, 'init']);
+        add_shortcode('ai_generate', [$this, 'shortcode']);
+    }
+
+    public function init() {
+        // SDK automatically detects WordPress API key options
+    }
+
+    public function shortcode($atts) {
+        $atts = shortcode_atts(['prompt' => 'Write helpful content'], $atts);
+
+        $result = AiClient::prompt($atts['prompt'])->generateTextResult();
+        return wp_kses_post($result->toText());
+    }
+}
+
+new AiContentPlugin();
+```
+
+## WordPress Hooks
+
+```php
+// Modify content before generation
+add_filter('wp_ai_content_prompt', function($prompt) {
+    return "WordPress site context: " . $prompt;
+});
+
+// Process generated content
+add_filter('wp_ai_generated_content', function($content) {
+    return wpautop($content);
+});
+```
+
+## Admin Integration
+
+```php
+// Add AI settings to WordPress admin
+add_action('admin_menu', function() {
+    add_options_page(
+        'AI Settings',
+        'AI Settings', 
+        'manage_options',
+        'ai-settings',
+        'ai_settings_page'
+    );
+});
+
+function ai_settings_page() {
+    // API key settings form
+}
+```
+
+## WP-CLI Commands
+
+```php
+if (defined('WP_CLI') && WP_CLI) {
+    WP_CLI::add_command('ai generate', function($args) {
+        $content = AiClient::prompt($args[0])->generateTextResult()->toText();
+        WP_CLI::success($content);
+    });
+}
+```

docs/5.advanced-usage.md

@@ -0,0 +1,67 @@
+# 5. Advanced Usage
+
+## Custom Providers
+
+```php
+// Implement ProviderInterface
+class CustomAiProvider implements ProviderInterface {
+    public function getId(): string {
+        return 'custom-ai';
+    }
+
+    // Implement other required methods...
+}
+
+// Register custom provider
+$registry = AiClient::defaultRegistry();
+$registry->registerProvider(CustomAiProvider::class);
+```
+
+## Configuration
+
+```php
+// Custom model selection
+$result = AiClient::prompt('Generate content')
+    ->usingModel('specific-model-id')
+    ->usingTemperature(0.8)
+    ->generateTextResult();
+
+// Batch processing
+$prompts = ['Prompt 1', 'Prompt 2', 'Prompt 3'];
+$results = AiClient::batchProcess($prompts)->generateTextResults();
+```
+
+## Performance Optimization
+
+```php
+// Connection pooling
+$registry->setHttpClientOptions([
+    'pool_size' => 10,
+    'timeout' => 30
+]);
+
+// Response streaming
+$result = AiClient::prompt('Long content generation')
+    ->withStreaming()
+    ->generateTextResult();
+
+// Memory management
+$result = AiClient::prompt('Generate content')
+    ->usingMaxTokens(1000)
+    ->generateTextResult();
+```
+
+## Monitoring
+
+```php
+// Usage tracking
+add_action('ai_client_after_generation', function($result, $prompt) {
+    // Log usage metrics
+    error_log("AI generation: {$prompt} -> {$result->getTokenUsage()}");
+});
+
+// Performance monitoring
+$start = microtime(true);
+$result = AiClient::prompt('Generate content')->generateTextResult();
+$duration = microtime(true) - $start;
+```