[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Builders\Traits;
   5  
   6  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   7  use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
   8  use WordPress\AiClient\Providers\ModelResolver;
   9  use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
  10  /**
  11   * Provides shared model selection methods for builders.
  12   *
  13   * Builders that resolve a model from the available providers (e.g.
  14   * {@see \WordPress\AiClient\Builders\PromptBuilder}) use this trait to expose a consistent fluent API
  15   * for choosing a model, provider, preferences, and request options. Model selection state and logic
  16   * live on the {@see ModelResolver} owned by the builder. Model configuration is handled by the
  17   * composed {@see ModelConfigurationTrait}.
  18   *
  19   * @since 1.4.0
  20   *
  21   * @phpstan-import-type ProviderModelTuple from ModelResolver
  22   */
  23  trait ModelResolutionTrait
  24  {
  25      use \WordPress\AiClient\Builders\Traits\ModelConfigurationTrait;
  26      /**
  27       * @var ModelResolver The resolver that owns model selection state and logic.
  28       */
  29      protected ModelResolver $modelResolver;
  30      /**
  31       * Sets the model to use for generation.
  32       *
  33       * The model's configuration will be merged with the builder's configuration,
  34       * with the builder's configuration taking precedence for any overlapping settings.
  35       *
  36       * @since 0.1.0
  37       *
  38       * @param ModelInterface $model The model to use.
  39       * @return self
  40       */
  41      public function usingModel(ModelInterface $model): self
  42      {
  43          $this->modelResolver->setModel($model);
  44          // Merge model's config with builder's config, with builder's config taking precedence
  45          $this->mergeModelConfig($model->getConfig());
  46          return $this;
  47      }
  48      /**
  49       * Sets preferred models to evaluate in order.
  50       *
  51       * @since 0.2.0
  52       *
  53       * @param string|ModelInterface|ProviderModelTuple ...$preferredModels The preferred models as model IDs,
  54       * model instances, or [provider ID, model ID] tuples. For broader compatibility, it is recommended you specify
  55       * only model IDs or model instances, as that will allow for different providers that expose the same model to be
  56       * considered.
  57       * @return self
  58       *
  59       * @throws InvalidArgumentException When a preferred model has an invalid type or identifier.
  60       */
  61      public function usingModelPreference(...$preferredModels): self
  62      {
  63          $this->modelResolver->setModelPreferences(...$preferredModels);
  64          return $this;
  65      }
  66      /**
  67       * Sets the provider to use for generation.
  68       *
  69       * @since 0.1.0
  70       *
  71       * @param string $providerIdOrClassName The provider ID or class name.
  72       * @return self
  73       */
  74      public function usingProvider(string $providerIdOrClassName): self
  75      {
  76          $this->modelResolver->setProvider($providerIdOrClassName);
  77          return $this;
  78      }
  79      /**
  80       * Sets the request options for HTTP transport.
  81       *
  82       * @since 0.3.0
  83       *
  84       * @param RequestOptions $requestOptions The request options.
  85       * @return self
  86       */
  87      public function usingRequestOptions(RequestOptions $requestOptions): self
  88      {
  89          $this->modelResolver->setRequestOptions($requestOptions);
  90          return $this;
  91      }
  92  }