Add AIFactory and AI class. Update doc accordingly

Author: charvimehradu

README.md

@@ -43,9 +43,9 @@ Each provider is instantiated with its configuration (API key, defaults such as
 
 ### OpenAI:
 ```php
-use Joomla\AI\Provider\OpenAIProvider;
+use Joomla\AI\AIFactory;
 
-$openai = new OpenAIProvider([
+$openai = AIFactory::getAI('openai', [
   'api_key' => getenv('OPENAI_API_KEY'),
   // Optional defaults:
   // 'model' => 'gpt-4o',
@@ -55,19 +55,19 @@ $openai = new OpenAIProvider([
 
 ### Anthropic:
 ```php
-use Joomla\AI\Provider\AnthropicProvider;
+use Joomla\AI\AIFactory;
 
-$anthropic = new AnthropicProvider([
+$anthropic = AIFactory::getAI('anthropic', [
   'api_key' => getenv('ANTHROPIC_API_KEY'),
   // 'model' => 'claude-3-5-sonnet',
 ]);
 ```
 
 ### Ollama (local):
 ```php
-use Joomla\AI\Provider\OllamaProvider;
+use Joomla\AI\AIFactory;
 
-$ollama = new OllamaProvider([
+$ollama = AIFactory::getAI('ollama', [
   // 'base_url' => 'http://localhost:11434',
   // 'model' => 'llama3',
 ]);

Tests/FactoryTest.php

@@ -0,0 +1,96 @@
+<?php
+
+require_once '../vendor/autoload.php';
+
+use Joomla\AI\AIFactory;
+use Joomla\AI\Exception\ProviderException;
+
+$configFile = __DIR__ . '/../config.json';
+$config = json_decode(file_get_contents($configFile), true);
+$api_key = $config['openai_api_key'] ?? null;
+$anthropic_api_key = $config['anthropic_api_key'] ?? null;
+
+echo "=== AI Factory Test Suite ===\n\n";
+
+// Test Case 1: Invalid Provider
+echo "1. Testing invalid provider 'abcd':\n";
+try {
+    $options = [
+        'api_key' => $anthropic_api_key
+    ];
+    
+    $ai = AIFactory::getAI('abcd', $options);
+    $response = $ai->chat("Hey");
+    echo $response->getContent();
+
+} catch (ProviderException $e) {
+    echo "Caught expected exception: " . $e->getMessage() . "\n";
+}
+echo "\n";
+
+// Test Case 2: Valid Provider Creation
+echo "2. Testing valid provider creation (anthropic):\n";
+try {
+    $options = [
+        'api_key' => $anthropic_api_key
+    ];
+    
+    $ai = AIFactory::getAI('anthropic', $options);
+    echo "Provider name: " . $ai->getProvider()->getName() . "\n";
+    $response = $ai->chat("Hey");
+    echo $response->getContent();
+} catch (Exception $e) {
+    echo "Failed to create Anthropic provider: " . $e->getMessage() . "\n";
+}
+echo "\n";
+
+// Test Case 3: Non-existent Method Call
+echo "3. Testing non-existent method call:\n";
+try {
+    $options = [
+        'api_key' => $anthropic_api_key
+    ];
+    
+    $ai = AIFactory::getAI('anthropic', $options);
+    $response = $ai->nonExistentMethod("test");
+    echo $response->getContent();
+} catch (ProviderException $e) {
+    echo "Caught expected Exception for non-existent method: " . $e->getMessage() . "\n";
+}
+echo "\n";
+
+// Test Case 4: Available Providers
+echo "4. Testing available providers:\n";
+try {
+    $availableProviders = AIFactory::getAvailableProviders();
+    echo "Available providers: " . implode(', ', $availableProviders) . "\n";
+    
+    // Test each provider availability
+    foreach ($availableProviders as $provider) {
+        $isAvailable = AIFactory::isProviderAvailable($provider);
+        echo "Provider '$provider' is available: " . ($isAvailable ? 'Yes' : 'No') . "\n";
+    }
+    
+    // Test non-existent provider
+    $isAvailable = AIFactory::isProviderAvailable('non-existent');
+    echo "Provider 'non-existent' is available: " . ($isAvailable ? 'Yes' : 'No') . "\n";
+} catch (Exception $e) {
+    echo "Failed to get available providers: " . $e->getMessage() . "\n";
+}
+echo "\n";
+
+// Test Case 5: Valid Method Call
+echo "5. Testing valid method calls:\n";
+try {
+    $options = [
+        'api_key' => $anthropic_api_key
+    ];
+
+    $ai = AIFactory::getAI('anthropic', $options);
+    $response = $ai->chat("Hey");
+    echo $response->getContent();
+} catch (Exception $e) {
+    echo "Test Failed: " . $e->getMessage() . "\n";
+}
+
+echo "\n=== Test Suite Complete ===\n";

docs/getting-started.md

@@ -59,10 +59,10 @@ You should not hardcode your API keys into your program code. Make them configur
 <?php
 require_once 'vendor/autoload.php';
 
-use Joomla\AI\Provider\OpenAIProvider;
+use Joomla\AI\AIFactory;
 
 // Create provider instance
-$openai = new OpenAIProvider([
+$openai = AIFactory::getAI('openai', [
     'api_key' => getenv('OPENAI_API_KEY')
 ]);
 
@@ -81,15 +81,13 @@ echo "Provider: " . $response->getProvider() . "\n";
 <?php
 require_once 'vendor/autoload.php';
 
-use Joomla\AI\Provider\OpenAIProvider;
-use Joomla\AI\Provider\AnthropicProvider;
-use Joomla\AI\Provider\OllamaProvider;
+use Joomla\AI\AIFactory;
 
 // Configure multiple providers
 $providers = [
-    'openai' => new OpenAIProvider(['api_key' => getenv('OPENAI_API_KEY')]),
-    'anthropic' => new AnthropicProvider(['api_key' => getenv('ANTHROPIC_API_KEY')]),
-    'ollama' => new OllamaProvider() // Local server, no API key needed
+    'openai' => $openai = AIFactory::getAI('openai', ['api_key' => getenv('OPENAI_API_KEY')]),
+    'anthropic' => nAIFactory::getAI('anthropic', ['api_key' => getenv('ANTHROPIC_API_KEY')]),
+    'ollama' => AIFactory::getAI('ollama', []) // Local server, no API key needed
 ];
 
 $question = "What is Joomla?";
@@ -110,9 +108,9 @@ foreach ($providers as $name => $provider) {
 ### Image Generation
 
 ```php
-use Joomla\AI\Provider\OpenAIProvider;
+use Joomla\AI\AIFactory;
 
-$openai = new OpenAIProvider(['api_key' => getenv('OPENAI_API_KEY')]);
+$openai = AIFactory::getAI('openai', ['api_key' => getenv('OPENAI_API_KEY')]);
 
 // Generate an image
 $image = $openai->generateImage("A beautiful sunset over mountains", [
@@ -155,7 +153,7 @@ echo "Vision analysis: " . $vision->getContent() . "\n";
 Avoid repeating model names by setting defaults:
 
 ```php
-$openai = new OpenAIProvider(['api_key' => getenv('OPENAI_API_KEY')]);
+$openai = AIFactory::getAI('openai', ['api_key' => getenv('OPENAI_API_KEY')]);
 
 // Set a default model for all chat requests
 $openai->setDefaultModel('gpt-4o-mini');
@@ -212,9 +210,9 @@ For local AI without API costs:
 3. **Use in your code**:
 
 ```php
-use Joomla\AI\Provider\OllamaProvider;
+use Joomla\AI\AIFactory;
 
-$ollama = new OllamaProvider();
+$ollama = AIFactory::getAI('ollama');
 
 $response = $ollama->chat("Hello!", ['model' => 'llama3']);
 echo $response->getContent();

docs/overview.md

@@ -35,6 +35,15 @@ Centralizes common functionality:
 - Error mapping (401→Auth, 429→RateLimit/Quota, etc.)
 - JSON response parsing
 
+**AI Factory** (`/src/AIFactory.php`)
+Centralized provider instantiation and management:
+- `getAI($provider, $options)` - Creates provider instances by name
+- Provider registry with supported providers ('openai', 'anthropic', 'ollama')
+- Simplifies provider switching and configuration management
+
+**AI Class** (`/src/AI.php`)
+- Wrapper providing access to all AI capabilities.
+
 **Response Object** (`/src/Response/Response.php`)
 Unified response wrapper that extends Joomla's HttpResponse:
 - `getContent()` - Primary result (text, base64 image, binary audio)
@@ -62,8 +71,8 @@ All exceptions inherit from [`AIException`](../src/Exception/AIException.php):
 ### Provider Abstraction
 ```php
 // Same interface, different providers
-$openai = new OpenAIProvider(['api_key' => $key]);
-$anthropic = new AnthropicProvider(['api_key' => $key]);
+$openai = AIFactory::getAI('openai', ['api_key' => $key]);
+$anthropic = AIFactory::getAI('anthropic', ['api_key' => $anthropic_key]);
 
 // Identical usage
 $response1 = $openai->chat("Hello!");

docs/providers/anthropic.md

@@ -13,9 +13,9 @@ The Anthropic Provider ([`AnthropicProvider`](../../src/Provider/AnthropicProvid
 ## Configuration
 
 ```php
-use Joomla\AI\Provider\AnthropicProvider;
+use Joomla\AI\AIFactory;
 
-$anthropic = new AnthropicProvider([
+$anthropic = AIFactory::getAI('anthropic', [
     'api_key' => getenv('ANTHROPIC_API_KEY'),
     'model' => 'claude-3-5-sonnet' // Optional: default model
 ]);

docs/providers/ollama.md

@@ -14,9 +14,9 @@ The Ollama Provider ([`OllamaProvider`](../../src/Provider/OllamaProvider.php))
 ## Configuration
 
 ```php
-use Joomla\AI\Provider\OllamaProvider;
+use Joomla\AI\AIFactory;
 
-$ollama = new OllamaProvider([
+$ollama = AIFactory::getAI('ollama', [
     'base_url' => 'http://localhost:11434', // Default Ollama server
     'model' => 'llama3' // Optional: default model
 ]);

docs/providers/openai.md

@@ -21,9 +21,9 @@ The OpenAI Provider ([`OpenAIProvider`](../../src/Provider/OpenAIProvider.php))
 ## Configuration
 
 ```php
-use Joomla\AI\Provider\OpenAIProvider;
+use Joomla\AI\AIFactory;
 
-$openai = new OpenAIProvider([
+$openai = AIFactory::getAI('openai', [
     'api_key' => getenv('OPENAI_API_KEY'),
     'base_url' => 'https://api.openai.com/v1', // Optional: custom endpoint
     'model' => 'gpt-4o-mini' // Optional: default model

src/AI.php

@@ -0,0 +1,73 @@
+<?php
+
+/**
+ * Part of the Joomla Framework AI Package
+ *
+ * @copyright  Copyright (C) 2025 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+ */
+
+namespace Joomla\AI;
+
+use Joomla\AI\Exception\ProviderException;
+
+/**
+ * AI client class.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class AI
+{
+    /**
+     * The AI provider object to use for AI requests.
+     *
+     * @var AbstractProvider
+     * @since  __DEPLOY_VERSION__
+     */
+    protected AbstractProvider $provider;
+
+    /**
+     * Constructor.
+     *
+     * @param   AbstractProvider  $provider  The AI provider object.
+     *
+     * @since   __DEPLOY_VERSION__
+     */
+    public function __construct(AbstractProvider $provider)
+    {
+        $this->provider = $provider;
+    }
+
+    /**
+     * Magic method to delegate all calls to the provider.
+     *
+     * @param   string  $method     The method name being called
+     * @param   array   $arguments  The arguments passed to the method
+     *
+     * @return  mixed
+     * @throws  \ProviderException  If the provider doesn't have the method
+     * @since   __DEPLOY_VERSION__
+     */
+    public function __call(string $method, array $arguments)
+    {
+        if (method_exists($this->provider, $method)) {
+            return $this->provider->$method(...$arguments);
+        }
+
+        throw new ProviderException(
+            $this->provider->getName(),
+            ['message' => 'Method ' . $method . ' is not supported by ' . $this->provider->getName()],
+        );
+    }
+
+    /**
+     * Get the underlying provider instance.
+     *
+     * @return  AbstractProvider
+     * @since   __DEPLOY_VERSION__
+     */
+    public function getProvider(): AbstractProvider
+    {
+        return $this->provider;
+    }
+}