Merge pull request #35 from WordPress/provider-contracts

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 $modelConfig Model configuration.
+     * @return ModelInterface Model instance.
+     * @throws InvalidArgumentException If model not found or configuration invalid.
+     */
+    public static function model(string $modelId, ?ModelConfig $modelConfig = null): 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/DTO/ModelMetadata.php

@@ -54,6 +54,16 @@ class ModelMetadata extends AbstractDataTransferObject
      */
     protected array $supportedOptions;
 
+    /**
+     * @var array<string, true> Map of supported capabilities for O(1) lookups.
+     */
+    private array $capabilitiesMap = [];
+
+    /**
+     * @var array<string, SupportedOption> Map of supported options by name for O(1) lookups.
+     */
+    private array $optionsMap = [];
+
     /**
      * Constructor.
      *
@@ -80,6 +90,16 @@ public function __construct(string $id, string $name, array $supportedCapabiliti
         $this->name = $name;
         $this->supportedCapabilities = $supportedCapabilities;
         $this->supportedOptions = $supportedOptions;
+
+        // Build capability map for efficient lookups
+        foreach ($supportedCapabilities as $capability) {
+            $this->capabilitiesMap[$capability->value] = true;
+        }
+
+        // Build options map for efficient lookups
+        foreach ($supportedOptions as $option) {
+            $this->optionsMap[$option->getName()] = $option;
+        }
     }
 
     /**
@@ -189,6 +209,42 @@ 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 using map lookup
+        foreach ($requirements->getRequiredCapabilities() as $requiredCapability) {
+            if (!isset($this->capabilitiesMap[$requiredCapability->value])) {
+                return false;
+            }
+        }
+
+        // Check if all required options are supported with the specified values
+        foreach ($requirements->getRequiredOptions() as $requiredOption) {
+            // Use map lookup instead of linear search
+            if (!isset($this->optionsMap[$requiredOption->getName()])) {
+                return false;
+            }
+
+            $supportedOption = $this->optionsMap[$requiredOption->getName()];
+
+            // Check if the required value is supported by this option
+            if (!$supportedOption->isSupportedValue($requiredOption->getValue())) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+
     /**
      * {@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;
+}