[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\ApiBasedImplementation;
   5  
   6  use WordPress\AiClient\AiClient;
   7  use WordPress\AiClient\Common\Contracts\CachesDataInterface;
   8  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   9  use WordPress\AiClient\Common\Traits\WithDataCachingTrait;
  10  use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;
  11  use WordPress\AiClient\Providers\Http\Contracts\WithHttpTransporterInterface;
  12  use WordPress\AiClient\Providers\Http\Contracts\WithRequestAuthenticationInterface;
  13  use WordPress\AiClient\Providers\Http\Traits\WithHttpTransporterTrait;
  14  use WordPress\AiClient\Providers\Http\Traits\WithRequestAuthenticationTrait;
  15  use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
  16  /**
  17   * Base class for an API-based model metadata directory for a provider.
  18   *
  19   * @since 0.1.0
  20   */
  21  abstract class AbstractApiBasedModelMetadataDirectory implements ModelMetadataDirectoryInterface, WithHttpTransporterInterface, WithRequestAuthenticationInterface, CachesDataInterface
  22  {
  23      use WithHttpTransporterTrait;
  24      use WithRequestAuthenticationTrait;
  25      use WithDataCachingTrait;
  26      /**
  27       * The cache key suffix for the models list.
  28       *
  29       * @since 0.4.0
  30       *
  31       * @var string
  32       */
  33      private const MODELS_CACHE_KEY = 'models';
  34      /**
  35       * Request-local cache for explicit model metadata lookups.
  36       *
  37       * @since 1.5.0
  38       *
  39       * @var array<string, ModelMetadata|null>
  40       */
  41      private array $explicitModelMetadataCache = [];
  42      /**
  43       * {@inheritDoc}
  44       *
  45       * @since 0.1.0
  46       */
  47      final public function listModelMetadata(): array
  48      {
  49          $modelsMetadata = $this->getModelMetadataMap();
  50          $explicitModelsMetadata = $this->getExplicitModelMetadataMap(array_keys($modelsMetadata));
  51          return array_values(array_replace($modelsMetadata, $explicitModelsMetadata));
  52      }
  53      /**
  54       * {@inheritDoc}
  55       *
  56       * @since 0.1.0
  57       */
  58      final public function hasModelMetadata(string $modelId): bool
  59      {
  60          if (isset($this->getExplicitModelMetadataMap([$modelId])[$modelId])) {
  61              return \true;
  62          }
  63          $modelsMetadata = $this->getModelMetadataMap();
  64          return isset($modelsMetadata[$modelId]);
  65      }
  66      /**
  67       * {@inheritDoc}
  68       *
  69       * @since 0.1.0
  70       */
  71      final public function getModelMetadata(string $modelId): ModelMetadata
  72      {
  73          $explicitModelsMetadata = $this->getExplicitModelMetadataMap([$modelId]);
  74          if (isset($explicitModelsMetadata[$modelId])) {
  75              return $explicitModelsMetadata[$modelId];
  76          }
  77          $modelsMetadata = $this->getModelMetadataMap();
  78          if (!isset($modelsMetadata[$modelId])) {
  79              throw new InvalidArgumentException(sprintf('No model with ID %s was found in the provider', $modelId));
  80          }
  81          return $modelsMetadata[$modelId];
  82      }
  83      /**
  84       * Gets explicit model metadata using request-local memoization.
  85       *
  86       * @since 1.5.0
  87       *
  88       * @param list<string> $modelIds Model IDs for which to get explicit metadata.
  89       * @return array<string, ModelMetadata> Map of model ID to explicit model metadata.
  90       */
  91      private function getExplicitModelMetadataMap(array $modelIds): array
  92      {
  93          $uncheckedModelIds = [];
  94          foreach ($modelIds as $modelId) {
  95              if (!array_key_exists($modelId, $this->explicitModelMetadataCache)) {
  96                  $uncheckedModelIds[] = $modelId;
  97              }
  98          }
  99          if ($uncheckedModelIds) {
 100              $explicitModelsMetadata = $this->createModelMetadataForExplicitModelIds($uncheckedModelIds);
 101              foreach ($uncheckedModelIds as $modelId) {
 102                  $this->explicitModelMetadataCache[$modelId] = $explicitModelsMetadata[$modelId] ?? null;
 103              }
 104          }
 105          return array_filter(array_intersect_key($this->explicitModelMetadataCache, array_flip($modelIds)));
 106      }
 107      /**
 108       * Returns the map of model ID to model metadata for all models from the provider.
 109       *
 110       * @since 0.1.0
 111       *
 112       * @return array<string, ModelMetadata> Map of model ID to model metadata.
 113       */
 114      private function getModelMetadataMap(): array
 115      {
 116          /** @var array<string, ModelMetadata> */
 117          return $this->cached(self::MODELS_CACHE_KEY, fn() => $this->sendListModelsRequest(), 86400);
 118      }
 119      /**
 120       * {@inheritDoc}
 121       *
 122       * @since 0.4.0
 123       */
 124      protected function getCachedKeys(): array
 125      {
 126          return [self::MODELS_CACHE_KEY];
 127      }
 128      /**
 129       * {@inheritDoc}
 130       *
 131       * @since 0.4.0
 132       */
 133      protected function getBaseCacheKey(): string
 134      {
 135          return 'ai_client_' . AiClient::VERSION . '_' . md5(static::class);
 136      }
 137      /**
 138       * Creates metadata for explicit model IDs without listing provider models.
 139       *
 140       * Providers whose APIs accept arbitrary/current model IDs can override this to avoid a live list-models request
 141       * when callers already know the model ID they want to instantiate.
 142       *
 143       * @since 1.5.0
 144       *
 145       * @param list<string> $modelIds The explicit model IDs.
 146       * @return array<string, ModelMetadata> Map of model ID to model metadata. Omit IDs that should fall back to the
 147       *                                                provider models list.
 148       */
 149      protected function createModelMetadataForExplicitModelIds(array $modelIds): array
 150      {
 151          return [];
 152      }
 153      /**
 154       * Sends the API request to list models from the provider and returns the map of model ID to model metadata.
 155       *
 156       * @since 0.1.0
 157       *
 158       * @return array<string, ModelMetadata> Map of model ID to model metadata.
 159       */
 160      abstract protected function sendListModelsRequest(): array;
 161  }