- md5
- 4713c7e6806f2b7354ca77d3061e8c7d
- sha1
- 9811455d2813ae716bc6c812da04e383cdac54bb
- sha256
- 4c3f31d831f62e0f0d266ba183e758c6475f6b59fff5810ae5a009371ad96e37
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390
<?php
declare (strict_types=1);
namespace WordPress\AiClient\Providers\Models\DTO;
use WordPress\AiClient\Common\AbstractDataTransferObject;
use WordPress\AiClient\Common\Exception\InvalidArgumentException;
use WordPress\AiClient\Messages\DTO\Message;
use WordPress\AiClient\Messages\DTO\MessagePart;
use WordPress\AiClient\Messages\Enums\ModalityEnum;
use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
use WordPress\AiClient\Providers\Models\Enums\OptionEnum;
/**
* Represents requirements that implementing code has for AI model selection.
*
* This class defines the capabilities and options that a model must support
* in order to be considered suitable for the implementing code's needs.
*
* @since 0.1.0
*
* @phpstan-import-type RequiredOptionArrayShape from RequiredOption
*
* @phpstan-type ModelRequirementsArrayShape array{
* requiredCapabilities: list<string>,
* requiredOptions: list<RequiredOptionArrayShape>
* }
*
* @phpstan-type UnmetModelRequirementsShape array{
* capabilities: list<CapabilityEnum>,
* options: list<RequiredOption>
* }
*
* @extends AbstractDataTransferObject<ModelRequirementsArrayShape>
*/
class ModelRequirements extends AbstractDataTransferObject
{
public const KEY_REQUIRED_CAPABILITIES = 'requiredCapabilities';
public const KEY_REQUIRED_OPTIONS = 'requiredOptions';
/**
* @var list<CapabilityEnum> The capabilities that the model must support.
*/
protected array $requiredCapabilities;
/**
* @var list<RequiredOption> The options that the model must support with specific values.
*/
protected array $requiredOptions;
/**
* Constructor.
*
* @since 0.1.0
*
* @param list<CapabilityEnum> $requiredCapabilities The capabilities that the model must support.
* @param list<RequiredOption> $requiredOptions The options that the model must support with specific values.
*
* @throws InvalidArgumentException If arrays are not lists.
*/
public function __construct(array $requiredCapabilities, array $requiredOptions)
{
if (!array_is_list($requiredCapabilities)) {
throw new InvalidArgumentException('Required capabilities must be a list array.');
}
if (!array_is_list($requiredOptions)) {
throw new InvalidArgumentException('Required options must be a list array.');
}
$this->requiredCapabilities = $requiredCapabilities;
$this->requiredOptions = $requiredOptions;
}
/**
* Gets the capabilities that the model must support.
*
* @since 0.1.0
*
* @return list<CapabilityEnum> The required capabilities.
*/
public function getRequiredCapabilities(): array
{
return $this->requiredCapabilities;
}
/**
* Gets the options that the model must support with specific values.
*
* @since 0.1.0
*
* @return list<RequiredOption> The required options.
*/
public function getRequiredOptions(): array
{
return $this->requiredOptions;
}
/**
* Checks whether the given model metadata meets these requirements.
*
* @since 0.2.0
*
* @param ModelMetadata $metadata The model metadata to check against.
* @return bool True if the model meets all requirements, false otherwise.
*/
public function areMetBy(\WordPress\AiClient\Providers\Models\DTO\ModelMetadata $metadata): bool
{
$unmetRequirements = $this->getUnmetRequirements($metadata);
return $unmetRequirements['capabilities'] === [] && $unmetRequirements['options'] === [];
}
/**
* Determines which of these requirements the given model metadata does not meet.
*
* Unlike {@see self::areMetBy()}, this method reports the specific capabilities and options that
* are unsupported, so that calling code can explain why a model is unsuitable.
*
* @since 1.5.0
*
* @param ModelMetadata $metadata The model metadata to check against.
* @return UnmetModelRequirementsShape The unsupported capabilities and options. Both lists are empty if the
* model meets all requirements.
*/
public function getUnmetRequirements(\WordPress\AiClient\Providers\Models\DTO\ModelMetadata $metadata): array
{
// Create lookup maps for better performance (instead of nested foreach loops)
$capabilitiesMap = [];
foreach ($metadata->getSupportedCapabilities() as $capability) {
$capabilitiesMap[$capability->value] = $capability;
}
$optionsMap = [];
foreach ($metadata->getSupportedOptions() as $option) {
$optionsMap[$option->getName()->value] = $option;
}
// Collect required capabilities that are not supported, using map lookup
$unmetCapabilities = [];
foreach ($this->requiredCapabilities as $requiredCapability) {
if (!isset($capabilitiesMap[$requiredCapability->value])) {
$unmetCapabilities[] = $requiredCapability;
}
}
// Collect required options that are either unsupported or unsupported with the required value
$unmetOptions = [];
foreach ($this->requiredOptions as $requiredOption) {
// Use map lookup instead of linear search
$supportedOption = $optionsMap[$requiredOption->getName()->value] ?? null;
if ($supportedOption === null || !$supportedOption->isSupportedValue($requiredOption->getValue())) {
$unmetOptions[] = $requiredOption;
}
}
return ['capabilities' => $unmetCapabilities, 'options' => $unmetOptions];
}
/**
* Creates ModelRequirements from prompt data and model configuration.
*
* @since 0.2.0
*
* @param CapabilityEnum $capability The capability the model must support.
* @param list<Message> $messages The messages in the conversation.
* @param ModelConfig $modelConfig The model configuration.
* @return self The created requirements.
*/
public static function fromPromptData(CapabilityEnum $capability, array $messages, \WordPress\AiClient\Providers\Models\DTO\ModelConfig $modelConfig): self
{
// Start with base capability
$capabilities = [$capability];
$inputModalities = [];
// Check if we have chat history (multiple messages)
if (count($messages) > 1) {
$capabilities[] = CapabilityEnum::chatHistory();
}
// Analyze all messages to determine required input modalities
$hasFunctionMessageParts = \false;
foreach ($messages as $message) {
foreach ($message->getParts() as $part) {
$modality = self::inputModalityForPart($part);
if ($modality !== null) {
$inputModalities[] = $modality;
}
// Check for function calls/responses (these might require special capabilities)
if ($part->getType()->isFunctionCall() || $part->getType()->isFunctionResponse()) {
$hasFunctionMessageParts = \true;
}
}
}
// Convert ModelConfig to RequiredOptions
$requiredOptions = self::toRequiredOptions($modelConfig);
// Add additional options based on message analysis
if ($hasFunctionMessageParts) {
$requiredOptions = self::includeInRequiredOptions($requiredOptions, new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::functionDeclarations(), \true));
}
// Add input modalities if we have any inputs
if (!empty($inputModalities)) {
// Remove duplicates
$inputModalities = array_unique($inputModalities, \SORT_REGULAR);
$requiredOptions = self::includeInRequiredOptions($requiredOptions, new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::inputModalities(), array_values($inputModalities)));
}
// Step 6: Return new ModelRequirements
return new self($capabilities, $requiredOptions);
}
/**
* Creates ModelRequirements from embedding input data and model configuration.
*
* Unlike {@see self::fromPromptData()}, embedding inputs are independent items rather than a
* conversation, so no chat history capability is inferred. Each input contributes its input
* modality (text or file) to the requirements.
*
* @since 1.4.0
*
* @param list<MessagePart> $inputs The embedding inputs.
* @param ModelConfig $modelConfig The model configuration.
* @return self The created requirements.
*/
public static function fromEmbeddingData(array $inputs, \WordPress\AiClient\Providers\Models\DTO\ModelConfig $modelConfig): self
{
$capabilities = [CapabilityEnum::embeddingGeneration()];
$inputModalities = [];
// Analyze each input to determine required input modalities. Function call/response parts
// are not valid embedding inputs and are rejected before reaching this point.
foreach ($inputs as $part) {
$modality = self::inputModalityForPart($part);
if ($modality !== null) {
$inputModalities[] = $modality;
}
}
// Convert ModelConfig to RequiredOptions
$requiredOptions = self::toRequiredOptions($modelConfig);
// Add input modalities if we have any inputs
if (!empty($inputModalities)) {
// Remove duplicates
$inputModalities = array_unique($inputModalities, \SORT_REGULAR);
$requiredOptions = self::includeInRequiredOptions($requiredOptions, new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::inputModalities(), array_values($inputModalities)));
}
return new self($capabilities, $requiredOptions);
}
/**
* Determines the input modality contributed by a message part, if any.
*
* @since 1.4.0
*
* @param MessagePart $part The message part to analyze.
* @return ModalityEnum|null The input modality, or null if the part contributes none.
*/
private static function inputModalityForPart(MessagePart $part): ?ModalityEnum
{
// Check for text input
if ($part->getType()->isText()) {
return ModalityEnum::text();
}
// Check for file inputs
if ($part->getType()->isFile()) {
$file = $part->getFile();
if ($file !== null) {
if ($file->isImage()) {
return ModalityEnum::image();
} elseif ($file->isAudio()) {
return ModalityEnum::audio();
} elseif ($file->isVideo()) {
return ModalityEnum::video();
} elseif ($file->isDocument() || $file->isText()) {
return ModalityEnum::document();
}
}
}
return null;
}
/**
* Converts ModelConfig to an array of RequiredOptions.
*
* @since 0.2.0
*
* @param ModelConfig $modelConfig The model configuration.
* @return list<RequiredOption> The required options.
*/
private static function toRequiredOptions(\WordPress\AiClient\Providers\Models\DTO\ModelConfig $modelConfig): array
{
$requiredOptions = [];
// Map properties that have corresponding OptionEnum values
if ($modelConfig->getOutputModalities() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputModalities(), $modelConfig->getOutputModalities());
}
if ($modelConfig->getSystemInstruction() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::systemInstruction(), $modelConfig->getSystemInstruction());
}
if ($modelConfig->getCandidateCount() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::candidateCount(), $modelConfig->getCandidateCount());
}
if ($modelConfig->getMaxTokens() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::maxTokens(), $modelConfig->getMaxTokens());
}
if ($modelConfig->getTemperature() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::temperature(), $modelConfig->getTemperature());
}
if ($modelConfig->getTopP() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::topP(), $modelConfig->getTopP());
}
if ($modelConfig->getTopK() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::topK(), $modelConfig->getTopK());
}
if ($modelConfig->getOutputMimeType() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputMimeType(), $modelConfig->getOutputMimeType());
}
if ($modelConfig->getOutputSchema() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputSchema(), $modelConfig->getOutputSchema());
}
// Handle properties without OptionEnum values as custom options
if ($modelConfig->getStopSequences() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::stopSequences(), $modelConfig->getStopSequences());
}
if ($modelConfig->getPresencePenalty() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::presencePenalty(), $modelConfig->getPresencePenalty());
}
if ($modelConfig->getFrequencyPenalty() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::frequencyPenalty(), $modelConfig->getFrequencyPenalty());
}
if ($modelConfig->getLogprobs() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::logprobs(), $modelConfig->getLogprobs());
}
if ($modelConfig->getTopLogprobs() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::topLogprobs(), $modelConfig->getTopLogprobs());
}
if ($modelConfig->getFunctionDeclarations() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::functionDeclarations(), \true);
}
if ($modelConfig->getWebSearch() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::webSearch(), \true);
}
if ($modelConfig->getOutputFileType() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputFileType(), $modelConfig->getOutputFileType());
}
if ($modelConfig->getOutputMediaOrientation() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputMediaOrientation(), $modelConfig->getOutputMediaOrientation());
}
if ($modelConfig->getOutputMediaAspectRatio() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::outputMediaAspectRatio(), $modelConfig->getOutputMediaAspectRatio());
}
if ($modelConfig->getDimensions() !== null) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::dimensions(), $modelConfig->getDimensions());
}
// Add custom options as individual RequiredOptions
foreach ($modelConfig->getCustomOptions() as $key => $value) {
$requiredOptions[] = new \WordPress\AiClient\Providers\Models\DTO\RequiredOption(OptionEnum::customOptions(), [$key => $value]);
}
return $requiredOptions;
}
/**
* Includes a RequiredOption in the array, ensuring no duplicates based on option name.
*
* @since 0.2.0
*
* @param list<RequiredOption> $requiredOptions The existing required options.
* @param RequiredOption $newOption The new option to include.
* @return list<RequiredOption> The updated required options array.
*/
private static function includeInRequiredOptions(array $requiredOptions, \WordPress\AiClient\Providers\Models\DTO\RequiredOption $newOption): array
{
// Check if we already have this option name
foreach ($requiredOptions as $index => $existingOption) {
if ($existingOption->getName()->equals($newOption->getName())) {
// Replace existing option with new one
$requiredOptions[$index] = $newOption;
return $requiredOptions;
}
}
// Option not found, add it
$requiredOptions[] = $newOption;
return $requiredOptions;
}
/**
* {@inheritDoc}
*
* @since 0.1.0
*/
public static function getJsonSchema(): array
{
return ['type' => 'object', 'properties' => [self::KEY_REQUIRED_CAPABILITIES => ['type' => 'array', 'items' => ['type' => 'string', 'enum' => CapabilityEnum::getValues()], 'description' => 'The capabilities that the model must support.'], self::KEY_REQUIRED_OPTIONS => ['type' => 'array', 'items' => \WordPress\AiClient\Providers\Models\DTO\RequiredOption::getJsonSchema(), 'description' => 'The options that the model must support with specific values.']], 'required' => [self::KEY_REQUIRED_CAPABILITIES, self::KEY_REQUIRED_OPTIONS]];
}
/**
* {@inheritDoc}
*
* @since 0.1.0
*
* @return ModelRequirementsArrayShape
*/
public function toArray(): array
{
return [self::KEY_REQUIRED_CAPABILITIES => array_map(static fn(CapabilityEnum $capability): string => $capability->value, $this->requiredCapabilities), self::KEY_REQUIRED_OPTIONS => array_map(static fn(\WordPress\AiClient\Providers\Models\DTO\RequiredOption $option): array => $option->toArray(), $this->requiredOptions)];
}
/**
* {@inheritDoc}
*
* @since 0.1.0
*/
public static function fromArray(array $array): self
{
static::validateFromArrayData($array, [self::KEY_REQUIRED_CAPABILITIES, self::KEY_REQUIRED_OPTIONS]);
return new self(array_map(static fn(string $capability): CapabilityEnum => CapabilityEnum::from($capability), $array[self::KEY_REQUIRED_CAPABILITIES]), array_map(static fn(array $optionData): \WordPress\AiClient\Providers\Models\DTO\RequiredOption => \WordPress\AiClient\Providers\Models\DTO\RequiredOption::fromArray($optionData), $array[self::KEY_REQUIRED_OPTIONS]));
}
}
The same content is in 6 releases, WordPress 7.2-beta1 to 7.2-RC1. See them all, or every version of this file.