[Summary view] [Print] [Text view]

   1  <?php
   2  
   3  declare (strict_types=1);
   4  namespace WordPress\AiClient\Providers\Models\DTO;
   5  
   6  use WordPress\AiClient\Common\AbstractDataTransferObject;
   7  use WordPress\AiClient\Common\Exception\InvalidArgumentException;
   8  use WordPress\AiClient\Files\Enums\FileTypeEnum;
   9  use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
  10  use WordPress\AiClient\Messages\Enums\ModalityEnum;
  11  use WordPress\AiClient\Tools\DTO\FunctionDeclaration;
  12  use WordPress\AiClient\Tools\DTO\WebSearch;
  13  /**
  14   * Represents configuration for an AI model.
  15   *
  16   * This class allows configuring various parameters for model behavior,
  17   * including output modalities, system instructions, generation parameters,
  18   * and tool integrations.
  19   *
  20   * @since 0.1.0
  21   *
  22   * @phpstan-import-type FunctionDeclarationArrayShape from FunctionDeclaration
  23   * @phpstan-import-type WebSearchArrayShape from WebSearch
  24   *
  25   * @phpstan-type ModelConfigArrayShape array{
  26   *     outputModalities?: list<string>,
  27   *     systemInstruction?: string,
  28   *     candidateCount?: int,
  29   *     maxTokens?: int,
  30   *     temperature?: float,
  31   *     topP?: float,
  32   *     topK?: int,
  33   *     stopSequences?: list<string>,
  34   *     presencePenalty?: float,
  35   *     frequencyPenalty?: float,
  36   *     logprobs?: bool,
  37   *     topLogprobs?: int,
  38   *     functionDeclarations?: list<FunctionDeclarationArrayShape>,
  39   *     webSearch?: WebSearchArrayShape,
  40   *     outputFileType?: string,
  41   *     outputMimeType?: string,
  42   *     outputSchema?: array<string, mixed>,
  43   *     outputMediaOrientation?: string,
  44   *     outputMediaAspectRatio?: string,
  45   *     outputSpeechVoice?: string,
  46   *     dimensions?: int,
  47   *     customOptions?: array<string, mixed>
  48   * }
  49   *
  50   * @extends AbstractDataTransferObject<ModelConfigArrayShape>
  51   */
  52  class ModelConfig extends AbstractDataTransferObject
  53  {
  54      public const KEY_OUTPUT_MODALITIES = 'outputModalities';
  55      public const KEY_SYSTEM_INSTRUCTION = 'systemInstruction';
  56      public const KEY_CANDIDATE_COUNT = 'candidateCount';
  57      public const KEY_MAX_TOKENS = 'maxTokens';
  58      public const KEY_TEMPERATURE = 'temperature';
  59      public const KEY_TOP_P = 'topP';
  60      public const KEY_TOP_K = 'topK';
  61      public const KEY_STOP_SEQUENCES = 'stopSequences';
  62      public const KEY_PRESENCE_PENALTY = 'presencePenalty';
  63      public const KEY_FREQUENCY_PENALTY = 'frequencyPenalty';
  64      public const KEY_LOGPROBS = 'logprobs';
  65      public const KEY_TOP_LOGPROBS = 'topLogprobs';
  66      public const KEY_FUNCTION_DECLARATIONS = 'functionDeclarations';
  67      public const KEY_WEB_SEARCH = 'webSearch';
  68      public const KEY_OUTPUT_FILE_TYPE = 'outputFileType';
  69      public const KEY_OUTPUT_MIME_TYPE = 'outputMimeType';
  70      public const KEY_OUTPUT_SCHEMA = 'outputSchema';
  71      public const KEY_OUTPUT_MEDIA_ORIENTATION = 'outputMediaOrientation';
  72      public const KEY_OUTPUT_MEDIA_ASPECT_RATIO = 'outputMediaAspectRatio';
  73      public const KEY_OUTPUT_SPEECH_VOICE = 'outputSpeechVoice';
  74      public const KEY_DIMENSIONS = 'dimensions';
  75      public const KEY_CUSTOM_OPTIONS = 'customOptions';
  76      /*
  77       * Note: This key is not an actual model config key, but specified here for convenience.
  78       * It is relevant for model discovery, to determine which models support which input modalities.
  79       * The actual input modalities are part of the message sent to the model, not the model config.
  80       */
  81      public const KEY_INPUT_MODALITIES = 'inputModalities';
  82      /**
  83       * @var list<ModalityEnum>|null Output modalities for the model.
  84       */
  85      protected ?array $outputModalities = null;
  86      /**
  87       * @var string|null System instruction for the model.
  88       */
  89      protected ?string $systemInstruction = null;
  90      /**
  91       * @var int|null Number of response candidates to generate.
  92       */
  93      protected ?int $candidateCount = null;
  94      /**
  95       * @var int|null Maximum number of tokens to generate.
  96       */
  97      protected ?int $maxTokens = null;
  98      /**
  99       * @var float|null Temperature for randomness (0.0 to 2.0).
 100       */
 101      protected ?float $temperature = null;
 102      /**
 103       * @var float|null Top-p nucleus sampling parameter.
 104       */
 105      protected ?float $topP = null;
 106      /**
 107       * @var int|null Top-k sampling parameter.
 108       */
 109      protected ?int $topK = null;
 110      /**
 111       * @var list<string>|null Stop sequences.
 112       */
 113      protected ?array $stopSequences = null;
 114      /**
 115       * @var float|null Presence penalty for reducing repetition.
 116       */
 117      protected ?float $presencePenalty = null;
 118      /**
 119       * @var float|null Frequency penalty for reducing repetition.
 120       */
 121      protected ?float $frequencyPenalty = null;
 122      /**
 123       * @var bool|null Whether to return log probabilities.
 124       */
 125      protected ?bool $logprobs = null;
 126      /**
 127       * @var int|null Number of top log probabilities to return.
 128       */
 129      protected ?int $topLogprobs = null;
 130      /**
 131       * @var list<FunctionDeclaration>|null Function declarations available to the model.
 132       */
 133      protected ?array $functionDeclarations = null;
 134      /**
 135       * @var WebSearch|null Web search configuration for the model.
 136       */
 137      protected ?WebSearch $webSearch = null;
 138      /**
 139       * @var FileTypeEnum|null Output file type.
 140       */
 141      protected ?FileTypeEnum $outputFileType = null;
 142      /**
 143       * @var string|null Output MIME type.
 144       */
 145      protected ?string $outputMimeType = null;
 146      /**
 147       * @var array<string, mixed>|null Output schema (JSON schema).
 148       */
 149      protected ?array $outputSchema = null;
 150      /**
 151       * @var MediaOrientationEnum|null Output media orientation.
 152       */
 153      protected ?MediaOrientationEnum $outputMediaOrientation = null;
 154      /**
 155       * @var string|null Output media aspect ratio (e.g. 3:2, 16:9).
 156       */
 157      protected ?string $outputMediaAspectRatio = null;
 158      /**
 159       * @var string|null Output speech voice.
 160       */
 161      protected ?string $outputSpeechVoice = null;
 162      /**
 163       * @var int|null Embedding vector dimensions.
 164       */
 165      protected ?int $dimensions = null;
 166      /**
 167       * @var array<string, mixed> Custom provider-specific options.
 168       */
 169      protected array $customOptions = [];
 170      /**
 171       * Creates a deep clone of this configuration.
 172       *
 173       * Clones nested objects (functionDeclarations, webSearch) to ensure
 174       * the cloned configuration is independent of the original.
 175       * Enum value objects (outputModalities, outputFileType, outputMediaOrientation)
 176       * are intentionally shared as they are immutable.
 177       *
 178       * @since 0.4.2
 179       */
 180      public function __clone()
 181      {
 182          // Deep clone function declarations if set
 183          if ($this->functionDeclarations !== null) {
 184              $clonedDeclarations = [];
 185              foreach ($this->functionDeclarations as $declaration) {
 186                  $clonedDeclarations[] = clone $declaration;
 187              }
 188              $this->functionDeclarations = $clonedDeclarations;
 189          }
 190          // Clone web search if set
 191          if ($this->webSearch !== null) {
 192              $this->webSearch = clone $this->webSearch;
 193          }
 194          // Note: Enum value objects (outputModalities, outputFileType, outputMediaOrientation)
 195          // are immutable and can be safely shared.
 196      }
 197      /**
 198       * Sets the output modalities.
 199       *
 200       * @since 0.1.0
 201       *
 202       * @param list<ModalityEnum> $outputModalities The output modalities.
 203       *
 204       * @throws InvalidArgumentException If the array is not a list.
 205       */
 206      public function setOutputModalities(array $outputModalities): void
 207      {
 208          if (!array_is_list($outputModalities)) {
 209              throw new InvalidArgumentException('Output modalities must be a list array.');
 210          }
 211          $this->outputModalities = $outputModalities;
 212      }
 213      /**
 214       * Gets the output modalities.
 215       *
 216       * @since 0.1.0
 217       *
 218       * @return list<ModalityEnum>|null The output modalities.
 219       */
 220      public function getOutputModalities(): ?array
 221      {
 222          return $this->outputModalities;
 223      }
 224      /**
 225       * Sets the system instruction.
 226       *
 227       * @since 0.1.0
 228       *
 229       * @param string $systemInstruction The system instruction.
 230       */
 231      public function setSystemInstruction(string $systemInstruction): void
 232      {
 233          $this->systemInstruction = $systemInstruction;
 234      }
 235      /**
 236       * Gets the system instruction.
 237       *
 238       * @since 0.1.0
 239       *
 240       * @return string|null The system instruction.
 241       */
 242      public function getSystemInstruction(): ?string
 243      {
 244          return $this->systemInstruction;
 245      }
 246      /**
 247       * Sets the candidate count.
 248       *
 249       * @since 0.1.0
 250       *
 251       * @param int $candidateCount The candidate count.
 252       */
 253      public function setCandidateCount(int $candidateCount): void
 254      {
 255          $this->candidateCount = $candidateCount;
 256      }
 257      /**
 258       * Gets the candidate count.
 259       *
 260       * @since 0.1.0
 261       *
 262       * @return int|null The candidate count.
 263       */
 264      public function getCandidateCount(): ?int
 265      {
 266          return $this->candidateCount;
 267      }
 268      /**
 269       * Sets the maximum tokens.
 270       *
 271       * @since 0.1.0
 272       *
 273       * @param int $maxTokens The maximum tokens.
 274       */
 275      public function setMaxTokens(int $maxTokens): void
 276      {
 277          $this->maxTokens = $maxTokens;
 278      }
 279      /**
 280       * Gets the maximum tokens.
 281       *
 282       * @since 0.1.0
 283       *
 284       * @return int|null The maximum tokens.
 285       */
 286      public function getMaxTokens(): ?int
 287      {
 288          return $this->maxTokens;
 289      }
 290      /**
 291       * Sets the temperature.
 292       *
 293       * @since 0.1.0
 294       *
 295       * @param float $temperature The temperature.
 296       */
 297      public function setTemperature(float $temperature): void
 298      {
 299          $this->temperature = $temperature;
 300      }
 301      /**
 302       * Gets the temperature.
 303       *
 304       * @since 0.1.0
 305       *
 306       * @return float|null The temperature.
 307       */
 308      public function getTemperature(): ?float
 309      {
 310          return $this->temperature;
 311      }
 312      /**
 313       * Sets the top-p parameter.
 314       *
 315       * @since 0.1.0
 316       *
 317       * @param float $topP The top-p parameter.
 318       */
 319      public function setTopP(float $topP): void
 320      {
 321          $this->topP = $topP;
 322      }
 323      /**
 324       * Gets the top-p parameter.
 325       *
 326       * @since 0.1.0
 327       *
 328       * @return float|null The top-p parameter.
 329       */
 330      public function getTopP(): ?float
 331      {
 332          return $this->topP;
 333      }
 334      /**
 335       * Sets the top-k parameter.
 336       *
 337       * @since 0.1.0
 338       *
 339       * @param int $topK The top-k parameter.
 340       */
 341      public function setTopK(int $topK): void
 342      {
 343          $this->topK = $topK;
 344      }
 345      /**
 346       * Gets the top-k parameter.
 347       *
 348       * @since 0.1.0
 349       *
 350       * @return int|null The top-k parameter.
 351       */
 352      public function getTopK(): ?int
 353      {
 354          return $this->topK;
 355      }
 356      /**
 357       * Sets the stop sequences.
 358       *
 359       * @since 0.1.0
 360       *
 361       * @param list<string> $stopSequences The stop sequences.
 362       *
 363       * @throws InvalidArgumentException If the array is not a list.
 364       */
 365      public function setStopSequences(array $stopSequences): void
 366      {
 367          if (!array_is_list($stopSequences)) {
 368              throw new InvalidArgumentException('Stop sequences must be a list array.');
 369          }
 370          $this->stopSequences = $stopSequences;
 371      }
 372      /**
 373       * Gets the stop sequences.
 374       *
 375       * @since 0.1.0
 376       *
 377       * @return list<string>|null The stop sequences.
 378       */
 379      public function getStopSequences(): ?array
 380      {
 381          return $this->stopSequences;
 382      }
 383      /**
 384       * Sets the presence penalty.
 385       *
 386       * @since 0.1.0
 387       *
 388       * @param float $presencePenalty The presence penalty.
 389       */
 390      public function setPresencePenalty(float $presencePenalty): void
 391      {
 392          $this->presencePenalty = $presencePenalty;
 393      }
 394      /**
 395       * Gets the presence penalty.
 396       *
 397       * @since 0.1.0
 398       *
 399       * @return float|null The presence penalty.
 400       */
 401      public function getPresencePenalty(): ?float
 402      {
 403          return $this->presencePenalty;
 404      }
 405      /**
 406       * Sets the frequency penalty.
 407       *
 408       * @since 0.1.0
 409       *
 410       * @param float $frequencyPenalty The frequency penalty.
 411       */
 412      public function setFrequencyPenalty(float $frequencyPenalty): void
 413      {
 414          $this->frequencyPenalty = $frequencyPenalty;
 415      }
 416      /**
 417       * Gets the frequency penalty.
 418       *
 419       * @since 0.1.0
 420       *
 421       * @return float|null The frequency penalty.
 422       */
 423      public function getFrequencyPenalty(): ?float
 424      {
 425          return $this->frequencyPenalty;
 426      }
 427      /**
 428       * Sets whether to return log probabilities.
 429       *
 430       * @since 0.1.0
 431       *
 432       * @param bool $logprobs Whether to return log probabilities.
 433       */
 434      public function setLogprobs(bool $logprobs): void
 435      {
 436          $this->logprobs = $logprobs;
 437      }
 438      /**
 439       * Gets whether to return log probabilities.
 440       *
 441       * @since 0.1.0
 442       *
 443       * @return bool|null Whether to return log probabilities.
 444       */
 445      public function getLogprobs(): ?bool
 446      {
 447          return $this->logprobs;
 448      }
 449      /**
 450       * Sets the number of top log probabilities to return.
 451       *
 452       * @since 0.1.0
 453       *
 454       * @param int $topLogprobs The number of top log probabilities.
 455       */
 456      public function setTopLogprobs(int $topLogprobs): void
 457      {
 458          $this->topLogprobs = $topLogprobs;
 459      }
 460      /**
 461       * Gets the number of top log probabilities to return.
 462       *
 463       * @since 0.1.0
 464       *
 465       * @return int|null The number of top log probabilities.
 466       */
 467      public function getTopLogprobs(): ?int
 468      {
 469          return $this->topLogprobs;
 470      }
 471      /**
 472       * Sets the function declarations.
 473       *
 474       * @since 0.1.0
 475       *
 476       * @param list<FunctionDeclaration> $functionDeclarations The function declarations.
 477       *
 478       * @throws InvalidArgumentException If the array is not a list.
 479       */
 480      public function setFunctionDeclarations(array $functionDeclarations): void
 481      {
 482          if (!array_is_list($functionDeclarations)) {
 483              throw new InvalidArgumentException('Function declarations must be a list array.');
 484          }
 485          $this->functionDeclarations = $functionDeclarations;
 486      }
 487      /**
 488       * Gets the function declarations.
 489       *
 490       * @since 0.1.0
 491       *
 492       * @return list<FunctionDeclaration>|null The function declarations.
 493       */
 494      public function getFunctionDeclarations(): ?array
 495      {
 496          return $this->functionDeclarations;
 497      }
 498      /**
 499       * Sets the web search configuration.
 500       *
 501       * @since 0.1.0
 502       *
 503       * @param WebSearch $webSearch The web search configuration.
 504       */
 505      public function setWebSearch(WebSearch $webSearch): void
 506      {
 507          $this->webSearch = $webSearch;
 508      }
 509      /**
 510       * Gets the web search configuration.
 511       *
 512       * @since 0.1.0
 513       *
 514       * @return WebSearch|null The web search configuration.
 515       */
 516      public function getWebSearch(): ?WebSearch
 517      {
 518          return $this->webSearch;
 519      }
 520      /**
 521       * Sets the output file type.
 522       *
 523       * @since 0.1.0
 524       *
 525       * @param FileTypeEnum $outputFileType The output file type.
 526       */
 527      public function setOutputFileType(FileTypeEnum $outputFileType): void
 528      {
 529          $this->outputFileType = $outputFileType;
 530      }
 531      /**
 532       * Gets the output file type.
 533       *
 534       * @since 0.1.0
 535       *
 536       * @return FileTypeEnum|null The output file type.
 537       */
 538      public function getOutputFileType(): ?FileTypeEnum
 539      {
 540          return $this->outputFileType;
 541      }
 542      /**
 543       * Sets the output MIME type.
 544       *
 545       * @since 0.1.0
 546       *
 547       * @param string $outputMimeType The output MIME type.
 548       */
 549      public function setOutputMimeType(string $outputMimeType): void
 550      {
 551          $this->outputMimeType = $outputMimeType;
 552      }
 553      /**
 554       * Gets the output MIME type.
 555       *
 556       * @since 0.1.0
 557       *
 558       * @return string|null The output MIME type.
 559       */
 560      public function getOutputMimeType(): ?string
 561      {
 562          return $this->outputMimeType;
 563      }
 564      /**
 565       * Sets the output schema.
 566       *
 567       * When setting an output schema, this method automatically sets
 568       * the output MIME type to "application/json" if not already set.
 569       *
 570       * @since 0.1.0
 571       *
 572       * @param array<string, mixed> $outputSchema The output schema (JSON schema).
 573       */
 574      public function setOutputSchema(array $outputSchema): void
 575      {
 576          $this->outputSchema = $outputSchema;
 577          // Automatically set outputMimeType to application/json when schema is provided
 578          if ($this->outputMimeType === null) {
 579              $this->outputMimeType = 'application/json';
 580          }
 581      }
 582      /**
 583       * Gets the output schema.
 584       *
 585       * @since 0.1.0
 586       *
 587       * @return array<string, mixed>|null The output schema.
 588       */
 589      public function getOutputSchema(): ?array
 590      {
 591          return $this->outputSchema;
 592      }
 593      /**
 594       * Sets the output media orientation.
 595       *
 596       * @since 0.1.0
 597       *
 598       * @param MediaOrientationEnum $outputMediaOrientation The output media orientation.
 599       */
 600      public function setOutputMediaOrientation(MediaOrientationEnum $outputMediaOrientation): void
 601      {
 602          if ($this->outputMediaAspectRatio) {
 603              $this->validateMediaOrientationAspectRatioCompatibility($outputMediaOrientation, $this->outputMediaAspectRatio);
 604          }
 605          $this->outputMediaOrientation = $outputMediaOrientation;
 606      }
 607      /**
 608       * Gets the output media orientation.
 609       *
 610       * @since 0.1.0
 611       *
 612       * @return MediaOrientationEnum|null The output media orientation.
 613       */
 614      public function getOutputMediaOrientation(): ?MediaOrientationEnum
 615      {
 616          return $this->outputMediaOrientation;
 617      }
 618      /**
 619       * Sets the output media aspect ratio.
 620       *
 621       * If set, this supersedes the output media orientation, as it is a more specific configuration.
 622       *
 623       * @since 0.1.0
 624       *
 625       * @param string $outputMediaAspectRatio The output media aspect ratio (e.g. 3:2, 16:9).
 626       */
 627      public function setOutputMediaAspectRatio(string $outputMediaAspectRatio): void
 628      {
 629          if (!preg_match('/^\d+:\d+$/', $outputMediaAspectRatio)) {
 630              throw new InvalidArgumentException('Output media aspect ratio must be in the format "width:height" (e.g. 3:2, 16:9).');
 631          }
 632          if ($this->outputMediaOrientation) {
 633              $this->validateMediaOrientationAspectRatioCompatibility($this->outputMediaOrientation, $outputMediaAspectRatio);
 634          }
 635          $this->outputMediaAspectRatio = $outputMediaAspectRatio;
 636      }
 637      /**
 638       * Gets the output media aspect ratio.
 639       *
 640       * @since 0.1.0
 641       *
 642       * @return string|null The output media aspect ratio (e.g. 3:2, 16:9).
 643       */
 644      public function getOutputMediaAspectRatio(): ?string
 645      {
 646          return $this->outputMediaAspectRatio;
 647      }
 648      /**
 649       * Validates that the given media orientation and aspect ratio values do not conflict with each other.
 650       *
 651       * @since 0.4.0
 652       *
 653       * @param MediaOrientationEnum $orientation The desired media orientation.
 654       * @param string $aspectRatio The desired media aspect ratio.
 655       */
 656      protected function validateMediaOrientationAspectRatioCompatibility(MediaOrientationEnum $orientation, string $aspectRatio): void
 657      {
 658          $aspectRatioParts = explode(':', $aspectRatio);
 659          if ($orientation->isSquare() && $aspectRatioParts[0] !== $aspectRatioParts[1]) {
 660              throw new InvalidArgumentException('The aspect ratio "' . $aspectRatio . '" is not compatible with the square orientation.');
 661          }
 662          if ($orientation->isLandscape() && $aspectRatioParts[0] <= $aspectRatioParts[1]) {
 663              throw new InvalidArgumentException('The aspect ratio "' . $aspectRatio . '" is not compatible with the landscape orientation.');
 664          }
 665          if ($orientation->isPortrait() && $aspectRatioParts[0] >= $aspectRatioParts[1]) {
 666              throw new InvalidArgumentException('The aspect ratio "' . $aspectRatio . '" is not compatible with the portrait orientation.');
 667          }
 668      }
 669      /**
 670       * Sets the output speech voice.
 671       *
 672       * @since 0.1.0
 673       *
 674       * @param string $outputSpeechVoice The output speech voice.
 675       */
 676      public function setOutputSpeechVoice(string $outputSpeechVoice): void
 677      {
 678          $this->outputSpeechVoice = $outputSpeechVoice;
 679      }
 680      /**
 681       * Gets the output speech voice.
 682       *
 683       * @since 0.1.0
 684       *
 685       * @return string|null The output speech voice.
 686       */
 687      public function getOutputSpeechVoice(): ?string
 688      {
 689          return $this->outputSpeechVoice;
 690      }
 691      /**
 692       * Sets the embedding dimensions.
 693       *
 694       * @since 1.4.0
 695       *
 696       * @param int $dimensions The embedding dimensions.
 697       */
 698      public function setDimensions(int $dimensions): void
 699      {
 700          if ($dimensions < 1) {
 701              throw new InvalidArgumentException('Dimensions must be greater than zero.');
 702          }
 703          $this->dimensions = $dimensions;
 704      }
 705      /**
 706       * Gets the embedding dimensions.
 707       *
 708       * @since 1.4.0
 709       *
 710       * @return int|null The embedding dimensions.
 711       */
 712      public function getDimensions(): ?int
 713      {
 714          return $this->dimensions;
 715      }
 716      /**
 717       * Sets a single custom option.
 718       *
 719       * @since 0.1.0
 720       *
 721       * @param string $key   The option key.
 722       * @param mixed  $value The option value.
 723       */
 724      public function setCustomOption(string $key, $value): void
 725      {
 726          $this->customOptions[$key] = $value;
 727      }
 728      /**
 729       * Sets the custom options.
 730       *
 731       * @since 0.1.0
 732       *
 733       * @param array<string, mixed> $customOptions The custom options.
 734       */
 735      public function setCustomOptions(array $customOptions): void
 736      {
 737          $this->customOptions = $customOptions;
 738      }
 739      /**
 740       * Gets the custom options.
 741       *
 742       * @since 0.1.0
 743       *
 744       * @return array<string, mixed> The custom options.
 745       */
 746      public function getCustomOptions(): array
 747      {
 748          return $this->customOptions;
 749      }
 750      /**
 751       * {@inheritDoc}
 752       *
 753       * @since 0.1.0
 754       */
 755      public static function getJsonSchema(): array
 756      {
 757          return ['type' => 'object', 'properties' => [self::KEY_OUTPUT_MODALITIES => ['type' => 'array', 'items' => ['type' => 'string', 'enum' => ModalityEnum::getValues()], 'description' => 'Output modalities for the model.'], self::KEY_SYSTEM_INSTRUCTION => ['type' => 'string', 'description' => 'System instruction for the model.'], self::KEY_CANDIDATE_COUNT => ['type' => 'integer', 'minimum' => 1, 'description' => 'Number of response candidates to generate.'], self::KEY_MAX_TOKENS => ['type' => 'integer', 'minimum' => 1, 'description' => 'Maximum number of tokens to generate.'], self::KEY_TEMPERATURE => ['type' => 'number', 'minimum' => 0.0, 'maximum' => 2.0, 'description' => 'Temperature for randomness.'], self::KEY_TOP_P => ['type' => 'number', 'minimum' => 0.0, 'maximum' => 1.0, 'description' => 'Top-p nucleus sampling parameter.'], self::KEY_TOP_K => ['type' => 'integer', 'minimum' => 1, 'description' => 'Top-k sampling parameter.'], self::KEY_STOP_SEQUENCES => ['type' => 'array', 'items' => ['type' => 'string'], 'description' => 'Stop sequences.'], self::KEY_PRESENCE_PENALTY => ['type' => 'number', 'description' => 'Presence penalty for reducing repetition.'], self::KEY_FREQUENCY_PENALTY => ['type' => 'number', 'description' => 'Frequency penalty for reducing repetition.'], self::KEY_LOGPROBS => ['type' => 'boolean', 'description' => 'Whether to return log probabilities.'], self::KEY_TOP_LOGPROBS => ['type' => 'integer', 'minimum' => 1, 'description' => 'Number of top log probabilities to return.'], self::KEY_FUNCTION_DECLARATIONS => ['type' => 'array', 'items' => FunctionDeclaration::getJsonSchema(), 'description' => 'Function declarations available to the model.'], self::KEY_WEB_SEARCH => WebSearch::getJsonSchema(), self::KEY_OUTPUT_FILE_TYPE => ['type' => 'string', 'enum' => FileTypeEnum::getValues(), 'description' => 'Output file type.'], self::KEY_OUTPUT_MIME_TYPE => ['type' => 'string', 'description' => 'Output MIME type.'], self::KEY_OUTPUT_SCHEMA => ['type' => 'object', 'additionalProperties' => \true, 'description' => 'Output schema (JSON schema).'], self::KEY_OUTPUT_MEDIA_ORIENTATION => ['type' => 'string', 'enum' => MediaOrientationEnum::getValues(), 'description' => 'Output media orientation.'], self::KEY_OUTPUT_MEDIA_ASPECT_RATIO => ['type' => 'string', 'pattern' => '^\d+:\d+$', 'description' => 'Output media aspect ratio.'], self::KEY_OUTPUT_SPEECH_VOICE => ['type' => 'string', 'description' => 'Output speech voice.'], self::KEY_DIMENSIONS => ['type' => 'integer', 'minimum' => 1, 'description' => 'Embedding vector dimensions.'], self::KEY_CUSTOM_OPTIONS => ['type' => 'object', 'additionalProperties' => \true, 'description' => 'Custom provider-specific options.']], 'additionalProperties' => \false];
 758      }
 759      /**
 760       * {@inheritDoc}
 761       *
 762       * @since 0.1.0
 763       *
 764       * @return ModelConfigArrayShape
 765       */
 766      public function toArray(): array
 767      {
 768          $data = [];
 769          if ($this->outputModalities !== null) {
 770              $data[self::KEY_OUTPUT_MODALITIES] = array_map(static function (ModalityEnum $modality): string {
 771                  return $modality->value;
 772              }, $this->outputModalities);
 773          }
 774          if ($this->systemInstruction !== null) {
 775              $data[self::KEY_SYSTEM_INSTRUCTION] = $this->systemInstruction;
 776          }
 777          if ($this->candidateCount !== null) {
 778              $data[self::KEY_CANDIDATE_COUNT] = $this->candidateCount;
 779          }
 780          if ($this->maxTokens !== null) {
 781              $data[self::KEY_MAX_TOKENS] = $this->maxTokens;
 782          }
 783          if ($this->temperature !== null) {
 784              $data[self::KEY_TEMPERATURE] = $this->temperature;
 785          }
 786          if ($this->topP !== null) {
 787              $data[self::KEY_TOP_P] = $this->topP;
 788          }
 789          if ($this->topK !== null) {
 790              $data[self::KEY_TOP_K] = $this->topK;
 791          }
 792          if ($this->stopSequences !== null) {
 793              $data[self::KEY_STOP_SEQUENCES] = $this->stopSequences;
 794          }
 795          if ($this->presencePenalty !== null) {
 796              $data[self::KEY_PRESENCE_PENALTY] = $this->presencePenalty;
 797          }
 798          if ($this->frequencyPenalty !== null) {
 799              $data[self::KEY_FREQUENCY_PENALTY] = $this->frequencyPenalty;
 800          }
 801          if ($this->logprobs !== null) {
 802              $data[self::KEY_LOGPROBS] = $this->logprobs;
 803          }
 804          if ($this->topLogprobs !== null) {
 805              $data[self::KEY_TOP_LOGPROBS] = $this->topLogprobs;
 806          }
 807          if ($this->functionDeclarations !== null) {
 808              $data[self::KEY_FUNCTION_DECLARATIONS] = array_map(static function (FunctionDeclaration $functionDeclaration): array {
 809                  return $functionDeclaration->toArray();
 810              }, $this->functionDeclarations);
 811          }
 812          if ($this->webSearch !== null) {
 813              $data[self::KEY_WEB_SEARCH] = $this->webSearch->toArray();
 814          }
 815          if ($this->outputFileType !== null) {
 816              $data[self::KEY_OUTPUT_FILE_TYPE] = $this->outputFileType->value;
 817          }
 818          if ($this->outputMimeType !== null) {
 819              $data[self::KEY_OUTPUT_MIME_TYPE] = $this->outputMimeType;
 820          }
 821          if ($this->outputSchema !== null) {
 822              $data[self::KEY_OUTPUT_SCHEMA] = $this->outputSchema;
 823          }
 824          if ($this->outputMediaOrientation !== null) {
 825              $data[self::KEY_OUTPUT_MEDIA_ORIENTATION] = $this->outputMediaOrientation->value;
 826          }
 827          if ($this->outputMediaAspectRatio !== null) {
 828              $data[self::KEY_OUTPUT_MEDIA_ASPECT_RATIO] = $this->outputMediaAspectRatio;
 829          }
 830          if ($this->outputSpeechVoice !== null) {
 831              $data[self::KEY_OUTPUT_SPEECH_VOICE] = $this->outputSpeechVoice;
 832          }
 833          if ($this->dimensions !== null) {
 834              $data[self::KEY_DIMENSIONS] = $this->dimensions;
 835          }
 836          if (!empty($this->customOptions)) {
 837              $data[self::KEY_CUSTOM_OPTIONS] = $this->customOptions;
 838          }
 839          return $data;
 840      }
 841      /**
 842       * {@inheritDoc}
 843       *
 844       * @since 0.1.0
 845       */
 846      public static function fromArray(array $array): self
 847      {
 848          $config = new self();
 849          if (isset($array[self::KEY_OUTPUT_MODALITIES])) {
 850              $config->setOutputModalities(array_map(static fn(string $modality): ModalityEnum => ModalityEnum::from($modality), $array[self::KEY_OUTPUT_MODALITIES]));
 851          }
 852          if (isset($array[self::KEY_SYSTEM_INSTRUCTION])) {
 853              $config->setSystemInstruction($array[self::KEY_SYSTEM_INSTRUCTION]);
 854          }
 855          if (isset($array[self::KEY_CANDIDATE_COUNT])) {
 856              $config->setCandidateCount($array[self::KEY_CANDIDATE_COUNT]);
 857          }
 858          if (isset($array[self::KEY_MAX_TOKENS])) {
 859              $config->setMaxTokens($array[self::KEY_MAX_TOKENS]);
 860          }
 861          if (isset($array[self::KEY_TEMPERATURE])) {
 862              $config->setTemperature($array[self::KEY_TEMPERATURE]);
 863          }
 864          if (isset($array[self::KEY_TOP_P])) {
 865              $config->setTopP($array[self::KEY_TOP_P]);
 866          }
 867          if (isset($array[self::KEY_TOP_K])) {
 868              $config->setTopK($array[self::KEY_TOP_K]);
 869          }
 870          if (isset($array[self::KEY_STOP_SEQUENCES])) {
 871              $config->setStopSequences($array[self::KEY_STOP_SEQUENCES]);
 872          }
 873          if (isset($array[self::KEY_PRESENCE_PENALTY])) {
 874              $config->setPresencePenalty($array[self::KEY_PRESENCE_PENALTY]);
 875          }
 876          if (isset($array[self::KEY_FREQUENCY_PENALTY])) {
 877              $config->setFrequencyPenalty($array[self::KEY_FREQUENCY_PENALTY]);
 878          }
 879          if (isset($array[self::KEY_LOGPROBS])) {
 880              $config->setLogprobs($array[self::KEY_LOGPROBS]);
 881          }
 882          if (isset($array[self::KEY_TOP_LOGPROBS])) {
 883              $config->setTopLogprobs($array[self::KEY_TOP_LOGPROBS]);
 884          }
 885          if (isset($array[self::KEY_FUNCTION_DECLARATIONS])) {
 886              $config->setFunctionDeclarations(array_map(static function (array $functionDeclarationData): FunctionDeclaration {
 887                  return FunctionDeclaration::fromArray($functionDeclarationData);
 888              }, $array[self::KEY_FUNCTION_DECLARATIONS]));
 889          }
 890          if (isset($array[self::KEY_WEB_SEARCH])) {
 891              $config->setWebSearch(WebSearch::fromArray($array[self::KEY_WEB_SEARCH]));
 892          }
 893          if (isset($array[self::KEY_OUTPUT_FILE_TYPE])) {
 894              $config->setOutputFileType(FileTypeEnum::from($array[self::KEY_OUTPUT_FILE_TYPE]));
 895          }
 896          if (isset($array[self::KEY_OUTPUT_MIME_TYPE])) {
 897              $config->setOutputMimeType($array[self::KEY_OUTPUT_MIME_TYPE]);
 898          }
 899          if (isset($array[self::KEY_OUTPUT_SCHEMA])) {
 900              $config->setOutputSchema($array[self::KEY_OUTPUT_SCHEMA]);
 901          }
 902          if (isset($array[self::KEY_OUTPUT_MEDIA_ORIENTATION])) {
 903              $config->setOutputMediaOrientation(MediaOrientationEnum::from($array[self::KEY_OUTPUT_MEDIA_ORIENTATION]));
 904          }
 905          if (isset($array[self::KEY_OUTPUT_MEDIA_ASPECT_RATIO])) {
 906              $config->setOutputMediaAspectRatio($array[self::KEY_OUTPUT_MEDIA_ASPECT_RATIO]);
 907          }
 908          if (isset($array[self::KEY_OUTPUT_SPEECH_VOICE])) {
 909              $config->setOutputSpeechVoice($array[self::KEY_OUTPUT_SPEECH_VOICE]);
 910          }
 911          if (isset($array[self::KEY_DIMENSIONS])) {
 912              $config->setDimensions($array[self::KEY_DIMENSIONS]);
 913          }
 914          if (isset($array[self::KEY_CUSTOM_OPTIONS])) {
 915              $config->setCustomOptions($array[self::KEY_CUSTOM_OPTIONS]);
 916          }
 917          return $config;
 918      }
 919  }