feat: adds provider interfaces

Author: JasonTheAdams

src/Providers/Contracts/ModelMetadataDirectoryInterface.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Contracts;
+
+use InvalidArgumentException;
+use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
+
+/**
+ * Interface for accessing model metadata within a provider.
+ *
+ * Provides methods to list, check, and retrieve model metadata
+ * for all models supported by a provider.
+ *
+ * @since n.e.x.t
+ */
+interface ModelMetadataDirectoryInterface
+{
+    /**
+     * Lists all available model metadata.
+     *
+     * @since n.e.x.t
+     *
+     * @return list<ModelMetadata> Array of model metadata.
+     */
+    public function listModelMetadata(): array;
+
+    /**
+     * Checks if metadata exists for a specific model.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $modelId Model identifier.
+     * @return bool True if metadata exists, false otherwise.
+     */
+    public function hasModelMetadata(string $modelId): bool;
+
+    /**
+     * Gets metadata for a specific model.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $modelId Model identifier.
+     * @return ModelMetadata Model metadata.
+     * @throws InvalidArgumentException If model metadata not found.
+     */
+    public function getModelMetadata(string $modelId): ModelMetadata;
+}

src/Providers/Contracts/ProviderAvailabilityInterface.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Contracts;
+
+/**
+ * Interface for checking provider availability.
+ *
+ * Determines whether a provider is configured and available
+ * for use based on API keys, credentials, or other requirements.
+ *
+ * @since n.e.x.t
+ */
+interface ProviderAvailabilityInterface
+{
+    /**
+     * Checks if the provider is configured.
+     *
+     * @since n.e.x.t
+     *
+     * @return bool True if the provider is configured and available, false otherwise.
+     */
+    public function isConfigured(): bool;
+}

src/Providers/Contracts/ProviderInterface.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Contracts;
+
+use InvalidArgumentException;
+use WordPress\AiClient\Providers\DTO\ProviderMetadata;
+use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
+use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
+
+/**
+ * Interface for AI providers.
+ *
+ * Providers represent AI services (Google, OpenAI, Anthropic, etc.)
+ * and provide access to models, metadata, and availability information.
+ *
+ * @since n.e.x.t
+ */
+interface ProviderInterface
+{
+    /**
+     * Gets provider metadata.
+     *
+     * @since n.e.x.t
+     *
+     * @return ProviderMetadata Provider metadata.
+     */
+    public static function metadata(): ProviderMetadata;
+
+    /**
+     * Creates a model instance.
+     *
+     * @since n.e.x.t
+     *
+     * @param string                          $modelId     Model identifier.
+     * @param ModelConfig|array<string,mixed> $modelConfig Model configuration.
+     * @return ModelInterface Model instance.
+     * @throws InvalidArgumentException If model not found or configuration invalid.
+     */
+    public static function model(string $modelId, $modelConfig = []): ModelInterface;
+
+    /**
+     * Gets provider availability checker.
+     *
+     * @since n.e.x.t
+     *
+     * @return ProviderAvailabilityInterface Provider availability checker.
+     */
+    public static function availability(): ProviderAvailabilityInterface;
+
+    /**
+     * Gets model metadata directory.
+     *
+     * @since n.e.x.t
+     *
+     * @return ModelMetadataDirectoryInterface Model metadata directory.
+     */
+    public static function modelMetadataDirectory(): ModelMetadataDirectoryInterface;
+}

src/Providers/Models/Contracts/ModelInterface.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\Contracts;
+
+use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
+use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
+
+/**
+ * Interface for AI models.
+ *
+ * Models represent specific AI models from providers and define
+ * their capabilities, configuration, and execution methods.
+ *
+ * @since n.e.x.t
+ */
+interface ModelInterface
+{
+    /**
+     * Gets model metadata.
+     *
+     * @since n.e.x.t
+     *
+     * @return ModelMetadata Model metadata.
+     */
+    public function metadata(): ModelMetadata;
+
+    /**
+     * Sets model configuration.
+     *
+     * @since n.e.x.t
+     *
+     * @param ModelConfig $config Model configuration.
+     * @return void
+     */
+    public function setConfig(ModelConfig $config): void;
+
+    /**
+     * Gets model configuration.
+     *
+     * @since n.e.x.t
+     *
+     * @return ModelConfig Current model configuration.
+     */
+    public function getConfig(): ModelConfig;
+}

src/Providers/Models/Contracts/WithGenerativeAiOperationsInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\Contracts;
+
+use InvalidArgumentException;
+use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
+
+/**
+ * Interface for models that support generative AI operations.
+ *
+ * Provides methods to retrieve and manage long-running generative AI
+ * operations such as text, image, or speech generation.
+ *
+ * @since n.e.x.t
+ */
+interface WithGenerativeAiOperationsInterface
+{
+    /**
+     * Gets a generative AI operation by ID.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $operationId Operation identifier.
+     * @return GenerativeAiOperation The generative AI operation.
+     * @throws InvalidArgumentException If operation not found.
+     */
+    public function getOperation(string $operationId): GenerativeAiOperation;
+}

src/Providers/Models/DTO/ModelMetadata.php

@@ -189,6 +189,60 @@ public function toArray(): array
         ];
     }
 
+    /**
+     * Checks whether this model meets the specified requirements.
+     *
+     * @since n.e.x.t
+     *
+     * @param ModelRequirements $requirements The requirements to check against.
+     * @return bool True if the model meets all requirements, false otherwise.
+     */
+    public function meetsRequirements(ModelRequirements $requirements): bool
+    {
+        // Check if all required capabilities are supported
+        foreach ($requirements->getRequiredCapabilities() as $requiredCapability) {
+            if (!in_array($requiredCapability, $this->supportedCapabilities, true)) {
+                return false;
+            }
+        }
+
+        // Check if all required options are supported with the specified values
+        foreach ($requirements->getRequiredOptions() as $requiredOption) {
+            $supportedOption = $this->findSupportedOption($requiredOption->getName());
+
+            // If the option is not supported at all, fail
+            if ($supportedOption === null) {
+                return false;
+            }
+
+            // Check if the required value is supported by this option
+            if (!$supportedOption->isSupportedValue($requiredOption->getValue())) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /**
+     * Finds a supported option by name.
+     *
+     * @since n.e.x.t
+     *
+     * @param string $name The option name to find.
+     * @return SupportedOption|null The supported option, or null if not found.
+     */
+    private function findSupportedOption(string $name): ?SupportedOption
+    {
+        foreach ($this->supportedOptions as $supportedOption) {
+            if ($supportedOption->getName() === $name) {
+                return $supportedOption;
+            }
+        }
+
+        return null;
+    }
+
     /**
      * {@inheritDoc}
      *

src/Providers/Models/ImageGeneration/Contracts/ImageGenerationModelInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\ImageGeneration\Contracts;
+
+use WordPress\AiClient\Messages\DTO\Message;
+use WordPress\AiClient\Results\DTO\GenerativeAiResult;
+
+/**
+ * Interface for models that support image generation.
+ *
+ * Provides synchronous methods for generating images from text prompts.
+ *
+ * @since n.e.x.t
+ */
+interface ImageGenerationModelInterface
+{
+    /**
+     * Generates images from a prompt.
+     *
+     * @since n.e.x.t
+     *
+     * @param list<Message> $prompt Array of messages containing the image generation prompt.
+     * @return GenerativeAiResult Result containing generated images.
+     */
+    public function generateImageResult(array $prompt): GenerativeAiResult;
+}

src/Providers/Models/ImageGeneration/Contracts/ImageGenerationOperationModelInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\ImageGeneration\Contracts;
+
+use WordPress\AiClient\Messages\DTO\Message;
+use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
+
+/**
+ * Interface for models that support asynchronous image generation operations.
+ *
+ * Provides methods for initiating long-running image generation tasks.
+ *
+ * @since n.e.x.t
+ */
+interface ImageGenerationOperationModelInterface
+{
+    /**
+     * Creates an image generation operation.
+     *
+     * @since n.e.x.t
+     *
+     * @param list<Message> $prompt Array of messages containing the image generation prompt.
+     * @return GenerativeAiOperation The initiated image generation operation.
+     */
+    public function generateImageOperation(array $prompt): GenerativeAiOperation;
+}

src/Providers/Models/SpeechGeneration/Contracts/SpeechGenerationModelInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\SpeechGeneration\Contracts;
+
+use WordPress\AiClient\Messages\DTO\Message;
+use WordPress\AiClient\Results\DTO\GenerativeAiResult;
+
+/**
+ * Interface for models that support speech generation.
+ *
+ * Provides synchronous methods for generating speech from prompts.
+ *
+ * @since n.e.x.t
+ */
+interface SpeechGenerationModelInterface
+{
+    /**
+     * Generates speech from a prompt.
+     *
+     * @since n.e.x.t
+     *
+     * @param list<Message> $prompt Array of messages containing the speech generation prompt.
+     * @return GenerativeAiResult Result containing generated speech audio.
+     */
+    public function generateSpeechResult(array $prompt): GenerativeAiResult;
+}

src/Providers/Models/SpeechGeneration/Contracts/SpeechGenerationOperationModelInterface.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\Models\SpeechGeneration\Contracts;
+
+use WordPress\AiClient\Messages\DTO\Message;
+use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
+
+/**
+ * Interface for models that support asynchronous speech generation operations.
+ *
+ * Provides methods for initiating long-running speech generation tasks.
+ *
+ * @since n.e.x.t
+ */
+interface SpeechGenerationOperationModelInterface
+{
+    /**
+     * Creates a speech generation operation.
+     *
+     * @since n.e.x.t
+     *
+     * @param list<Message> $prompt Array of messages containing the speech generation prompt.
+     * @return GenerativeAiOperation The initiated speech generation operation.
+     */
+    public function generateSpeechOperation(array $prompt): GenerativeAiOperation;
+}