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