AI Framework Foundation

src/AbstractProvider.php

@@ -0,0 +1,147 @@
+<?php
+
+/**
+ * Part of the Joomla Framework AI Package
+ *
+ */
+
+namespace Joomla\AI;
+
+use Joomla\Http\HttpFactory;
+
+/**
+ * Abstract provider class.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+abstract class AbstractProvider implements ProviderInterface
+{
+    /**
+     * The provider options.
+     *
+     * @var    array|\ArrayAccess
+     */
+    protected $options;
+
+    /**
+     * The HTTP factory instance.
+     *
+     * @var    HttpFactory
+     */
+    protected $httpFactory;
+
+    /**
+     * Constructor.
+     *
+     * @param   array|\ArrayAccess  $options  Provider options array.
+     * @param   HttpFactory   $httpFactory  The http factory
+     * 
+     * @throws  \InvalidArgumentException  If options is not an array or does not implement ArrayAccess.
+     * @since  ___DEPLOY_VERSION___
+     */
+    public function __construct($options = [], ?HttpFactory $httpFactory = null)
+    {
+        // To do: Exception Handeling Code
+        // Validate provider is suported
+        // Validate that $options is an array or implements ArrayAccess
+        if (!\is_array($options) && !($options instanceof \ArrayAccess)) {
+            throw new \InvalidArgumentException(
+                'The options param must be an array or implement the ArrayAccess interface.'
+            );
+        }
+
+        $this->options = $options;
+        $this->httpFactory = $httpFactory ?: new HttpFactory();
+    }
+
+    /**
+     * Get an option from the AI provider.
+     * 
+     * @param   string  $key      The name of the option to get.
+     * @param   mixed   $default  The default value if the option is not set.
+     * 
+     * @return  mixed The option value.
+     */
+    protected function getOption(string $key, $default = null)
+    {
+        return $this->options[$key] ?? $default;
+    }
+
+    /**
+     * Make HTTP GET request to AI provider API.
+     *
+     * @param   string  $url      API endpoint URL
+     * @param   array   $headers  Additional HTTP headers
+     * @param   integer $timeout  Request timeout in seconds
+     *
+     * @return  \Joomla\Http\Response
+     * @throws  \Exception
+     * @since  ___DEPLOY_VERSION___
+     */
+    protected function makeGetRequest(string $url, array $headers = [], $timeout = null)
+    {
+        try {
+            $response = $this->httpFactory->getHttp([])->get($url, $headers, $timeout);
+        } catch (\Exception $e) {
+            throw new \Exception('AI API GET request failed: ' . $e->getMessage(), 0, $e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Make HTTP POST request.
+     *
+     * @param   string   $url      API endpoint URL  
+     * @param   mixed    $data     POST data
+     * @param   array    $headers  HTTP headers
+     * @param   integer  $timeout  Request timeout
+     *
+     * @return  \Joomla\Http\Response
+     * @throws  \Exception
+     * @since  ___DEPLOY_VERSION___
+     */
+    protected function makePostRequest(string $url, $data, array $headers = [], $timeout = null)
+    {
+        try {
+            $response = $this->httpFactory->getHttp([])->post($url, $data, $headers, $timeout);
+        } catch (\Exception $e) {
+            throw new \Exception('AI API POST request failed: ' . $e->getMessage(), 0, $e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Check response code and handle errors
+     *
+     * @param   \Joomla\Http\Response  $response  HTTP response
+     *
+     * @return  boolean  True if successful
+     * @throws  \Exception
+     */
+    protected function validateResponse($response): bool
+    {
+        if ($response->code !== 200) {
+            // To Do: Error Handling Code
+            throw new \Exception('AI API Error: HTTP ' . $response->code . ' - ' . $response->body);
+        }
+
+        return true;
+    }
+
+    /**
+     * Parse JSON response safely
+     */
+    protected function parseJsonResponse(string $jsonString): array
+    {
+        $decoded = json_decode($jsonString, true);
+
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            throw new \Exception('Invalid JSON response: ' . json_last_error_msg());
+        }
+
+        return $decoded;
+    }
+
+}

src/ProviderInterface.php

@@ -0,0 +1,53 @@
+<?php
+
+/**
+ * Part of the Joomla Framework Http Package
+ *
+ */
+
+namespace Joomla\AI;
+
+/**
+ * AI provider class interface.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+interface ProviderInterface
+{
+    /**
+     * Method to check if AI provider is available for using
+     *
+     * @return  boolean  True if available else false
+     *
+     */
+    public static function isSupported();
+
+    /**
+     * Method to get the name of the AI provider.
+     *
+     * @return  string  The name of the AI provider.
+     *
+     */
+    public function getName();
+
+    /**
+     * Send a prompt to the AI provider and return a Response object with the response.
+     * 
+     * @param   string  $prompt     The prompt to send to the AI provider.
+     * @param   array   $options    An associative array of options to send with the request.
+     * @return  Response
+     * 
+     */
+    public function prompt($prompt, $options = []);
+
+    /**
+     * Ask a question to the AI provider and return a Response object with the response.
+     * 
+     * @param   string  $question     The question to send to the AI provider.
+     * @param   array   $options    An associative array of options to send with the request.
+     * @return  Response
+     * 
+     */
+    public function ask($question, $options = []);
+
+}

src/Response.php

@@ -0,0 +1,157 @@
+<?php
+
+/**
+ * Part of the Joomla Framework AI Package
+ *
+ * @copyright  Copyright (C) 2005 - 2025 Open Source Matters, Inc. All rights reserved.
+ * @license    GNU General Public License version 2 or later; see LICENSE
+*/
+
+namespace Joomla\AI;
+
+/**
+ * AI response data object class.
+ *
+ * @since  __DEPLOY_VERSION__
+ */
+class Response
+ {
+    /**
+     * The content of the response.
+     *
+     * @var string
+     * @since  __DEPLOY_VERSION__
+     */
+    private $content;
+
+    /**
+     * The status code of the response.
+     *
+     * @var int
+     * @since  __DEPLOY_VERSION__
+     */
+    private $statusCode;
+
+    /**
+     * The metadata of the response.
+     *
+     * @var array
+     * @since  __DEPLOY_VERSION__
+     */
+    private $metadata;
+
+    /**
+     * The provider of the response.
+     *
+     * @var string
+     * @since  __DEPLOY_VERSION__
+     */
+    private $provider;
+
+    /**
+     * Constructor.
+     *
+     * @param   string  $content   The content of the response.
+     * @param   string  $provider  The provider of the response.
+     * @param   array   $metadata  The metadata of the response.
+     * @param   int     $status    The status code of the response.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function __construct(string $content, string $provider, array $metadata = [], int $status = 200)
+    {
+        $this->content = $content;
+        $this->provider = $provider;
+        $this->metadata = $metadata;
+        $this->statusCode = $status;
+    }
+
+    /**
+     * Get the content of the response.
+     *
+     * @return  string  The content of the response.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+
+    /**
+     * Get the metadata of the response.
+     *
+     * @return  array  The metadata of the response.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getMetadata(): array
+    {
+        return $this->metadata;
+    }
+
+    /**
+     * Get the provider of the response.
+     *
+     * @return  string  The provider of the response.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getProvider(): string
+    {
+        return $this->provider;
+    }
+
+    /**
+     * Get the status code of the response.
+     *
+     * @return  int  The status code of the response.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function getStatusCode(): int
+    {
+        return $this->statusCode;
+    }
+
+    /**
+     * Magic method to access properties of the response object.
+     *
+     * @param   string  $name  The name of the property to get.
+     *
+     * @return  mixed  The value of the property.
+     *
+     * @since  __DEPLOY_VERSION__
+     */
+    public function __get($name)
+    {
+        switch (strtolower($name)) {
+            case 'content':
+                return $this->getContent();
+
+            case 'metadata':
+                return $this->getMetadata();
+
+            case 'provider':
+                return $this->getProvider();
+
+            case 'statuscode':
+                return $this->getStatusCode();
+
+            default:
+                $trace = debug_backtrace();
+
+                trigger_error(
+                    sprintf(
+                        'Undefined property via __get(): %s in %s on line %s',
+                        $name,
+                        $trace[0]['file'],
+                        $trace[0]['line']
+                    ),
+                    E_USER_NOTICE
+                );
+
+                break;
+        }
+    }
+}