Add documentation overing overview, getting started guide, and comprehensive provider-specific guides

[charvimehradu]

Added the documentation for the Joomla! AI framework.

Files added:
Overview - Architecture, design principles, and capability matrix
[Getting Started] - Installation, configuration, and first requests
Provider Guides:
[OpenAI Provider]- OpenAI capabilities with examples
[Anthropic Provider] - Claude capabilities with examples
[Ollama Provider]- Ollama capabilities with examples

Please review and let me know if any adjustments are needed.

[Hackwar]

Is this still in planning or do you want to replace that with a link to the providers folder? I think you would have to provide an index.md for that folder then as well.

[charvimehradu]

Hey,
Thank you for reviewing the PR. I have replaced the link with the providers folder. I have also added the index.md file for that folder as well.

[Hackwar]

I fixed the initialisation of phpunit. Without having tested the code, the unittests should look something like this:

<?php

/**
 * @copyright  (C) 2025 Open Source Matters, Inc. <https://www.joomla.org>
 * @license    GNU General Public License version 2 or later; see LICENSE
 */

namespace Joomla\AI\Tests;

use Joomla\AI\Provider\OpenAIProvider;
use PHPUnit\Framework\TestCase;

/**
 * Test class for Joomla\AI\Provider\OpenAIProvider.
 */
class VisionTest extends TestCase
{
    protected $config;

    protected $api_key;

    protected $provider;

    /**
     * Sets up the fixture, for example, opens a network connection.
     * This method is called before a test is executed.
     *
     * @return  void
     *
     * @since   1.0
     */
    protected function setUp(): void
    {
        parent::setUp();

        $configFile    = __DIR__ . '/../config.json';
        $this->config  = json_decode(file_get_contents($configFile), true);
        $this->api_key = $config['openai_api_key'] ?? null;
        // Create provider with your API key
        $this->provider = new OpenAIProvider([
            'api_key' => $this->api_key
        ]);
    }

    public function testVisionWithImageURL()
    {
        $imageUrl = "https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg";

        $response = $this->provider->vision("What do you see in this image?", $imageUrl);

        $this->assertEquals(200, $response->getStatusCode());
        $this->assertTrue(strlen($response->getBody()) > 10);
        $this->assertEquals('OpenAI', $response->getProvider());
        $this->assertArrayHasKey('model', $response->getMetadata());
        $this->assertArrayHasKey('usage', $response->getMetadata());
    }

    public function testVisionWithSpecificModel()
    {
        $imageUrl = "https://upload.wikimedia.org/wikipedia/commons/e/eb/Ash_Tree_-_geograph.org.uk_-_590710.jpg";

        $response = $this->provider->vision(
            "Describe the colors and mood of this image.",
            $imageUrl,
            ['model' => 'gpt-4o', 'max_tokens' => 100]
        );

        echo "Vision API call successful!\n";
        echo "Response: " . $response->getContent() . "\n";
        echo "Provider: " . $response->getProvider() . "\n";

        $metadata = $response->getMetadata();
        if (!empty($metadata)) {
            echo "Model used: " . ($metadata['model']) . "\n";
            if (isset($metadata['usage'])) {
                echo "Tokens used: " . ($metadata['usage']['total_tokens']) . "\n";
            }
        }
    }
}

I'm not sure if you want to test the way you do it right now. I'm not saying that this is the only way to do it, but we've been testing it class by class and not feature by feature. If you would ask me, I would create a subfolder per provider and in there have a file per implemented interface per provider to test the features. Like so:

- Tests
  - Provider
    - OpenAIProvider
      - ChatInterfaceTest.php
      - ModelInterfaceTest.php
      - ImageInterfaceTest.php
      - AudioInterfaceTest.php
      - ModerationInterfaceTest.php