File manager - Edit - /home/bdwebsol/public_html/demo.bdwebsolution.com/php-ai-client.zip
Back
PK ?�\0*�a� � src/Builders/MessageBuilder.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Builders; use InvalidArgumentException; use WordPress\AiClient\Files\DTO\File; use WordPress\AiClient\Messages\DTO\Message; use WordPress\AiClient\Messages\DTO\MessagePart; use WordPress\AiClient\Messages\Enums\MessageRoleEnum; use WordPress\AiClient\Tools\DTO\FunctionCall; use WordPress\AiClient\Tools\DTO\FunctionResponse; /** * Fluent builder for constructing AI messages. * * This class provides a fluent interface for building messages with various * content types including text, files, function calls, and function responses. * * @since 0.2.0 * * @phpstan-import-type MessagePartArrayShape from MessagePart * * @phpstan-type Input string|MessagePart|MessagePartArrayShape|File|FunctionCall|FunctionResponse|null */ class MessageBuilder { /** * @var MessageRoleEnum|null The role of the message sender. */ protected ?MessageRoleEnum $role = null; /** * @var list<MessagePart> The parts that make up the message. */ protected array $parts = []; /** * Constructor. * * @since 0.2.0 * * @param Input $input Optional initial content. * @param MessageRoleEnum|null $role Optional role. */ public function __construct($input = null, ?MessageRoleEnum $role = null) { $this->role = $role; if ($input === null) { return; } // Handle different input types if ($input instanceof MessagePart) { $this->parts[] = $input; } elseif (is_string($input)) { $this->withText($input); } elseif ($input instanceof File) { $this->withFile($input); } elseif ($input instanceof FunctionCall) { $this->withFunctionCall($input); } elseif ($input instanceof FunctionResponse) { $this->withFunctionResponse($input); } elseif (is_array($input) && MessagePart::isArrayShape($input)) { $this->parts[] = MessagePart::fromArray($input); } else { throw new InvalidArgumentException('Input must be a string, MessagePart, MessagePartArrayShape, File, FunctionCall, or FunctionResponse.'); } } /** * Creates a deep clone of this builder. * * Clones all MessagePart objects in the parts array to ensure * the cloned builder is independent of the original. * * @since 0.4.2 */ public function __clone() { // Deep clone parts array (MessagePart has __clone) $clonedParts = []; foreach ($this->parts as $part) { $clonedParts[] = clone $part; } $this->parts = $clonedParts; // Note: $role is an enum value object and can be safely shared } /** * Sets the role of the message sender. * * @since 0.2.0 * * @param MessageRoleEnum $role The role to set. * @return self */ public function usingRole(MessageRoleEnum $role): self { $this->role = $role; return $this; } /** * Sets the role to user. * * @since 0.2.0 * * @return self */ public function usingUserRole(): self { return $this->usingRole(MessageRoleEnum::user()); } /** * Sets the role to model. * * @since 0.2.0 * * @return self */ public function usingModelRole(): self { return $this->usingRole(MessageRoleEnum::model()); } /** * Adds text content to the message. * * @since 0.2.0 * * @param string $text The text to add. * @return self * @throws InvalidArgumentException If the text is empty. */ public function withText(string $text): self { if (trim($text) === '') { throw new InvalidArgumentException('Text content cannot be empty.'); } $this->parts[] = new MessagePart($text); return $this; } /** * Adds a file to the message. * * Accepts: * - File object * - URL string (remote file) * - Base64-encoded data string * - Data URI string (data:mime/type;base64,data) * - Local file path string * * @since 0.2.0 * * @param string|File $file The file to add. * @param string|null $mimeType Optional MIME type (ignored if File object provided). * @return self * @throws InvalidArgumentException If the file is invalid. */ public function withFile($file, ?string $mimeType = null): self { $file = $file instanceof File ? $file : new File($file, $mimeType); $this->parts[] = new MessagePart($file); return $this; } /** * Adds a function call to the message. * * @since 0.2.0 * * @param FunctionCall $functionCall The function call to add. * @return self */ public function withFunctionCall(FunctionCall $functionCall): self { $this->parts[] = new MessagePart($functionCall); return $this; } /** * Adds a function response to the message. * * @since 0.2.0 * * @param FunctionResponse $functionResponse The function response to add. * @return self */ public function withFunctionResponse(FunctionResponse $functionResponse): self { $this->parts[] = new MessagePart($functionResponse); return $this; } /** * Adds multiple message parts to the message. * * @since 0.2.0 * * @param MessagePart ...$parts The message parts to add. * @return self */ public function withMessageParts(MessagePart ...$parts): self { foreach ($parts as $part) { $this->parts[] = $part; } return $this; } /** * Builds and returns the Message object. * * @since 0.2.0 * * @return Message The built message. * @throws InvalidArgumentException If the message validation fails. */ public function get(): Message { if (empty($this->parts)) { throw new InvalidArgumentException('Cannot build an empty message. Add content using withText() or similar methods.'); } if ($this->role === null) { throw new InvalidArgumentException('Cannot build a message with no role. Set a role using usingRole() or similar methods.'); } // At this point, we've validated that $this->role is not null /** @var MessageRoleEnum $role */ $role = $this->role; return new Message($role, $this->parts); } } PK ?�\(cBC� C� src/Builders/PromptBuilder.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Builders; use WordPress\AiClientDependencies\Psr\EventDispatcher\EventDispatcherInterface; use WordPress\AiClient\Common\Exception\InvalidArgumentException; use WordPress\AiClient\Common\Exception\RuntimeException; use WordPress\AiClient\Events\AfterGenerateResultEvent; use WordPress\AiClient\Events\BeforeGenerateResultEvent; use WordPress\AiClient\Files\DTO\File; use WordPress\AiClient\Files\Enums\FileTypeEnum; use WordPress\AiClient\Files\Enums\MediaOrientationEnum; use WordPress\AiClient\Messages\DTO\Message; use WordPress\AiClient\Messages\DTO\MessagePart; use WordPress\AiClient\Messages\DTO\UserMessage; use WordPress\AiClient\Messages\Enums\MessageRoleEnum; use WordPress\AiClient\Messages\Enums\ModalityEnum; use WordPress\AiClient\Providers\ApiBasedImplementation\Contracts\ApiBasedModelInterface; use WordPress\AiClient\Providers\Http\DTO\RequestOptions; use WordPress\AiClient\Providers\Models\Contracts\ModelInterface; use WordPress\AiClient\Providers\Models\DTO\ModelConfig; use WordPress\AiClient\Providers\Models\DTO\ModelMetadata; use WordPress\AiClient\Providers\Models\DTO\ModelRequirements; use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum; use WordPress\AiClient\Providers\Models\ImageGeneration\Contracts\ImageGenerationModelInterface; use WordPress\AiClient\Providers\Models\SpeechGeneration\Contracts\SpeechGenerationModelInterface; use WordPress\AiClient\Providers\Models\TextGeneration\Contracts\TextGenerationModelInterface; use WordPress\AiClient\Providers\Models\TextToSpeechConversion\Contracts\TextToSpeechConversionModelInterface; use WordPress\AiClient\Providers\Models\VideoGeneration\Contracts\VideoGenerationModelInterface; use WordPress\AiClient\Providers\ProviderRegistry; use WordPress\AiClient\Results\DTO\GenerativeAiResult; use WordPress\AiClient\Tools\DTO\FunctionDeclaration; use WordPress\AiClient\Tools\DTO\FunctionResponse; use WordPress\AiClient\Tools\DTO\WebSearch; /** * Fluent builder for constructing AI prompts. * * This class provides a fluent interface for building prompts with various * content types and model configurations. It automatically infers model * requirements based on the features used in the prompt. * * @since 0.1.0 * * @phpstan-import-type MessageArrayShape from Message * @phpstan-import-type MessagePartArrayShape from MessagePart * * @phpstan-type Prompt string|MessagePart|Message|MessageArrayShape|list<string|MessagePart|MessagePartArrayShape>|list<Message>|null */ class PromptBuilder { /** * @var ProviderRegistry The provider registry for finding suitable models. */ private ProviderRegistry $registry; /** * @var list<Message> The messages in the conversation. */ protected array $messages = []; /** * @var ModelInterface|null The model to use for generation. */ protected ?ModelInterface $model = null; /** * @var list<string> Ordered list of preference keys to check when selecting a model. */ protected array $modelPreferenceKeys = []; /** * @var string|null The provider ID or class name. */ protected ?string $providerIdOrClassName = null; /** * @var ModelConfig The model configuration. */ protected ModelConfig $modelConfig; /** * @var RequestOptions|null The request options for HTTP transport. */ protected ?RequestOptions $requestOptions = null; /** * @var EventDispatcherInterface|null The event dispatcher for prompt lifecycle events. */ private ?EventDispatcherInterface $eventDispatcher = null; // phpcs:disable Generic.Files.LineLength.TooLong /** * Constructor. * * @since 0.1.0 * * @param ProviderRegistry $registry The provider registry for finding suitable models. * @param Prompt $prompt Optional initial prompt content. * @param EventDispatcherInterface|null $eventDispatcher Optional event dispatcher for lifecycle events. */ // phpcs:enable Generic.Files.LineLength.TooLong public function __construct(ProviderRegistry $registry, $prompt = null, ?EventDispatcherInterface $eventDispatcher = null) { $this->registry = $registry; $this->modelConfig = new ModelConfig(); $this->eventDispatcher = $eventDispatcher; if ($prompt === null) { return; } // Check if it's a list of Messages - set as messages if ($this->isMessagesList($prompt)) { $this->messages = $prompt; return; } // Parse it as a user message $userMessage = $this->parseMessage($prompt, MessageRoleEnum::user()); $this->messages[] = $userMessage; } /** * Creates a deep clone of this builder. * * Clones all mutable state including messages, model configuration, and request options. * Service objects (registry, model, event dispatcher) are intentionally NOT cloned * as they are shared dependencies. * * @since 0.4.2 */ public function __clone() { // Deep clone messages array (Message has __clone) $clonedMessages = []; foreach ($this->messages as $message) { $clonedMessages[] = clone $message; } $this->messages = $clonedMessages; // Clone model config (ModelConfig has __clone) $this->modelConfig = clone $this->modelConfig; // Clone request options if set (contains only primitives) if ($this->requestOptions !== null) { $this->requestOptions = clone $this->requestOptions; } // Note: $registry, $model, and $eventDispatcher are service objects // and are intentionally NOT cloned - they should be shared references. } /** * Adds text to the current message. * * @since 0.1.0 * * @param string $text The text to add. * @return self */ public function withText(string $text): self { $part = new MessagePart($text); $this->appendPartToMessages($part); return $this; } /** * Adds a file to the current message. * * Accepts: * - File object * - URL string (remote file) * - Base64-encoded data string * - Data URI string (data:mime/type;base64,data) * - Local file path string * * @since 0.1.0 * * @param string|File $file The file (File object or string representation). * @param string|null $mimeType The MIME type (optional, ignored if File object provided). * @return self * @throws InvalidArgumentException If the file is invalid or MIME type cannot be determined. */ public function withFile($file, ?string $mimeType = null): self { $file = $file instanceof File ? $file : new File($file, $mimeType); $part = new MessagePart($file); $this->appendPartToMessages($part); return $this; } /** * Adds a function response to the current message. * * @since 0.1.0 * * @param FunctionResponse $functionResponse The function response. * @return self */ public function withFunctionResponse(FunctionResponse $functionResponse): self { $part = new MessagePart($functionResponse); $this->appendPartToMessages($part); return $this; } /** * Adds message parts to the current message. * * @since 0.1.0 * * @param MessagePart ...$parts The message parts to add. * @return self */ public function withMessageParts(MessagePart ...$parts): self { foreach ($parts as $part) { $this->appendPartToMessages($part); } return $this; } /** * Adds conversation history messages. * * Historical messages are prepended to the beginning of the message list, * before the current message being built. * * @since 0.1.0 * * @param Message ...$messages The messages to add to history. * @return self */ public function withHistory(Message ...$messages): self { // Prepend the history messages to the beginning of the messages array $this->messages = array_merge($messages, $this->messages); return $this; } /** * Sets the model to use for generation. * * The model's configuration will be merged with the builder's configuration, * with the builder's configuration taking precedence for any overlapping settings. * * @since 0.1.0 * * @param ModelInterface $model The model to use. * @return self */ public function usingModel(ModelInterface $model): self { $this->model = $model; // Merge model's config with builder's config, with builder's config taking precedence $modelConfigArray = $model->getConfig()->toArray(); $builderConfigArray = $this->modelConfig->toArray(); $mergedConfigArray = array_merge($modelConfigArray, $builderConfigArray); $this->modelConfig = ModelConfig::fromArray($mergedConfigArray); return $this; } /** * Sets preferred models to evaluate in order. * * @since 0.2.0 * * @param string|ModelInterface|array{0:string,1:string} ...$preferredModels The preferred models as model IDs, * model instances, or [provider ID, model ID] tuples. For broader compatibility, it is recommended you specify * only model IDs or model instances, as that will allow for different providers that expose the same model to be * considered. * @return self * * @throws InvalidArgumentException When a preferred model has an invalid type or identifier. */ public function usingModelPreference(...$preferredModels): self { if ($preferredModels === []) { throw new InvalidArgumentException('At least one model preference must be provided.'); } $preferenceKeys = []; foreach ($preferredModels as $preferredModel) { if (is_array($preferredModel)) { // [model identifier, provider ID] tuple if (!array_is_list($preferredModel) || count($preferredModel) !== 2) { throw new InvalidArgumentException('Model preference tuple must contain model identifier and provider ID.'); } [$providerId, $modelId] = $preferredModel; $modelId = $this->normalizePreferenceIdentifier($modelId); $providerId = $this->normalizePreferenceIdentifier($providerId, 'Model preference provider identifiers cannot be empty.'); $preferenceKey = $this->createProviderModelPreferenceKey($providerId, $modelId); } elseif ($preferredModel instanceof ModelInterface) { // Model instance $modelId = $preferredModel->metadata()->getId(); $providerId = $preferredModel->providerMetadata()->getId(); $preferenceKey = $this->createProviderModelPreferenceKey($providerId, $modelId); } elseif (is_string($preferredModel)) { // Model ID $modelId = $this->normalizePreferenceIdentifier($preferredModel); $preferenceKey = $this->createModelPreferenceKey($modelId); } else { // Invalid type throw new InvalidArgumentException('Model preferences must be model identifiers, instances of ModelInterface, ' . 'or provider/model tuples.'); } $preferenceKeys[] = $preferenceKey; } $this->modelPreferenceKeys = $preferenceKeys; return $this; } /** * Sets the model configuration. * * Merges the provided configuration with the builder's configuration, * with builder configuration taking precedence. * * @since 0.1.0 * * @param ModelConfig $config The model configuration to merge. * @return self */ public function usingModelConfig(ModelConfig $config): self { // Convert both configs to arrays $builderConfigArray = $this->modelConfig->toArray(); $providedConfigArray = $config->toArray(); // Merge arrays with builder config taking precedence $mergedArray = array_merge($providedConfigArray, $builderConfigArray); // Create new config from merged array $this->modelConfig = ModelConfig::fromArray($mergedArray); return $this; } /** * Sets the provider to use for generation. * * @since 0.1.0 * * @param string $providerIdOrClassName The provider ID or class name. * @return self */ public function usingProvider(string $providerIdOrClassName): self { $this->providerIdOrClassName = $providerIdOrClassName; return $this; } /** * Sets the system instruction. * * System instructions are stored in the model configuration and guide * the AI model's behavior throughout the conversation. * * @since 0.1.0 * * @param string $systemInstruction The system instruction text. * @return self */ public function usingSystemInstruction(string $systemInstruction): self { $this->modelConfig->setSystemInstruction($systemInstruction); return $this; } /** * Sets the maximum number of tokens to generate. * * @since 0.1.0 * * @param int $maxTokens The maximum number of tokens. * @return self */ public function usingMaxTokens(int $maxTokens): self { $this->modelConfig->setMaxTokens($maxTokens); return $this; } /** * Sets the temperature for generation. * * @since 0.1.0 * * @param float $temperature The temperature value. * @return self */ public function usingTemperature(float $temperature): self { $this->modelConfig->setTemperature($temperature); return $this; } /** * Sets the top-p value for generation. * * @since 0.1.0 * * @param float $topP The top-p value. * @return self */ public function usingTopP(float $topP): self { $this->modelConfig->setTopP($topP); return $this; } /** * Sets the top-k value for generation. * * @since 0.1.0 * * @param int $topK The top-k value. * @return self */ public function usingTopK(int $topK): self { $this->modelConfig->setTopK($topK); return $this; } /** * Sets stop sequences for generation. * * @since 0.1.0 * * @param string ...$stopSequences The stop sequences. * @return self */ public function usingStopSequences(string ...$stopSequences): self { $this->modelConfig->setStopSequences($stopSequences); return $this; } /** * Sets the number of candidates to generate. * * @since 0.1.0 * * @param int $candidateCount The number of candidates. * @return self */ public function usingCandidateCount(int $candidateCount): self { $this->modelConfig->setCandidateCount($candidateCount); return $this; } /** * Sets the function declarations available to the model. * * @since 0.1.0 * * @param FunctionDeclaration ...$functionDeclarations The function declarations. * @return self */ public function usingFunctionDeclarations(FunctionDeclaration ...$functionDeclarations): self { $this->modelConfig->setFunctionDeclarations($functionDeclarations); return $this; } /** * Sets the presence penalty for generation. * * @since 0.1.0 * * @param float $presencePenalty The presence penalty value. * @return self */ public function usingPresencePenalty(float $presencePenalty): self { $this->modelConfig->setPresencePenalty($presencePenalty); return $this; } /** * Sets the frequency penalty for generation. * * @since 0.1.0 * * @param float $frequencyPenalty The frequency penalty value. * @return self */ public function usingFrequencyPenalty(float $frequencyPenalty): self { $this->modelConfig->setFrequencyPenalty($frequencyPenalty); return $this; } /** * Sets the web search configuration. * * @since 0.1.0 * * @param WebSearch $webSearch The web search configuration. * @return self */ public function usingWebSearch(WebSearch $webSearch): self { $this->modelConfig->setWebSearch($webSearch); return $this; } /** * Sets the request options for HTTP transport. * * @since 0.3.0 * * @param RequestOptions $requestOptions The request options. * @return self */ public function usingRequestOptions(RequestOptions $requestOptions): self { $this->requestOptions = $requestOptions; return $this; } /** * Sets the top log probabilities configuration. * * If $topLogprobs is null, enables log probabilities. * If $topLogprobs has a value, enables log probabilities and sets the number of top log probabilities to return. * * @since 0.1.0 * * @param int|null $topLogprobs The number of top log probabilities to return, or null to enable log probabilities. * @return self */ public function usingTopLogprobs(?int $topLogprobs = null): self { // Always enable log probabilities $this->modelConfig->setLogprobs(\true); // If a specific number is provided, set it if ($topLogprobs !== null) { $this->modelConfig->setTopLogprobs($topLogprobs); } return $this; } /** * Sets the output MIME type. * * @since 0.1.0 * * @param string $mimeType The MIME type. * @return self */ public function asOutputMimeType(string $mimeType): self { $this->modelConfig->setOutputMimeType($mimeType); return $this; } /** * Sets the output schema. * * @since 0.1.0 * * @param array<string, mixed> $schema The output schema. * @return self */ public function asOutputSchema(array $schema): self { $this->modelConfig->setOutputSchema($schema); return $this; } /** * Sets the output modalities. * * @since 0.1.0 * * @param ModalityEnum ...$modalities The output modalities. * @return self */ public function asOutputModalities(ModalityEnum ...$modalities): self { $this->modelConfig->setOutputModalities($modalities); return $this; } /** * Sets the output file type. * * @since 0.1.0 * * @param FileTypeEnum $fileType The output file type. * @return self */ public function asOutputFileType(FileTypeEnum $fileType): self { $this->modelConfig->setOutputFileType($fileType); return $this; } /** * Sets the output media orientation. * * @since 1.3.0 * * @param MediaOrientationEnum $orientation The output media orientation. * @return self */ public function asOutputMediaOrientation(MediaOrientationEnum $orientation): self { $this->modelConfig->setOutputMediaOrientation($orientation); return $this; } /** * Sets the output media aspect ratio. * * If set, this supersedes the output media orientation, as it is a more * specific configuration. * * @since 1.3.0 * * @param string $aspectRatio The aspect ratio (e.g. "16:9", "3:2"). * @return self */ public function asOutputMediaAspectRatio(string $aspectRatio): self { $this->modelConfig->setOutputMediaAspectRatio($aspectRatio); return $this; } /** * Sets the output speech voice. * * @since 1.3.0 * * @param string $voice The output speech voice. * @return self */ public function asOutputSpeechVoice(string $voice): self { $this->modelConfig->setOutputSpeechVoice($voice); return $this; } /** * Configures the prompt for JSON response output. * * @since 0.1.0 * * @param array<string, mixed>|null $schema Optional JSON schema. * @return self */ public function asJsonResponse(?array $schema = null): self { $this->asOutputMimeType('application/json'); if ($schema !== null) { $this->asOutputSchema($schema); } return $this; } /** * Infers the capability from configured output modalities. * * @since 0.1.0 * * @return CapabilityEnum The inferred capability. * @throws RuntimeException If the output modality is not supported. */ private function inferCapabilityFromOutputModalities(): CapabilityEnum { // Get the configured output modalities $outputModalities = $this->modelConfig->getOutputModalities(); // Default to text if no output modality is specified if ($outputModalities === null || empty($outputModalities)) { return CapabilityEnum::textGeneration(); } // Multi-modal output (multiple modalities) defaults to text generation. This is temporary // as a multi-modal interface will be implemented in the future. if (count($outputModalities) > 1) { return CapabilityEnum::textGeneration(); } // Infer capability from single output modality $outputModality = $outputModalities[0]; if ($outputModality->isText()) { return CapabilityEnum::textGeneration(); } elseif ($outputModality->isImage()) { return CapabilityEnum::imageGeneration(); } elseif ($outputModality->isAudio()) { return CapabilityEnum::speechGeneration(); } elseif ($outputModality->isVideo()) { return CapabilityEnum::videoGeneration(); } else { // For unsupported modalities, provide a clear error message throw new RuntimeException(sprintf('Output modality "%s" is not yet supported.', $outputModality->value)); } } /** * Infers the capability from a model's implemented interfaces. * * @since 0.1.0 * * @param ModelInterface $model The model to infer capability from. * @return CapabilityEnum|null The inferred capability, or null if none can be inferred. */ private function inferCapabilityFromModelInterfaces(ModelInterface $model): ?CapabilityEnum { // Check model interfaces in order of preference if ($model instanceof TextGenerationModelInterface) { return CapabilityEnum::textGeneration(); } if ($model instanceof ImageGenerationModelInterface) { return CapabilityEnum::imageGeneration(); } if ($model instanceof TextToSpeechConversionModelInterface) { return CapabilityEnum::textToSpeechConversion(); } if ($model instanceof SpeechGenerationModelInterface) { return CapabilityEnum::speechGeneration(); } if ($model instanceof VideoGenerationModelInterface) { return CapabilityEnum::videoGeneration(); } // No supported interface found return null; } /** * Checks if the current prompt is supported by the selected model. * * @since 0.1.0 * @since 0.3.0 Method visibility changed to public. * * @param CapabilityEnum|null $capability Optional capability to check support for. * @return bool True if supported, false otherwise. */ public function isSupported(?CapabilityEnum $capability = null): bool { // If no intended capability provided, infer from output modalities if ($capability === null) { // First try to infer from a specific model if one is set if ($this->model !== null) { $inferredCapability = $this->inferCapabilityFromModelInterfaces($this->model); if ($inferredCapability !== null) { $capability = $inferredCapability; } } // If still no capability, infer from output modalities if ($capability === null) { $capability = $this->inferCapabilityFromOutputModalities(); } } // Build requirements with the specified capability $requirements = ModelRequirements::fromPromptData($capability, $this->messages, $this->modelConfig); // If the model has been set, check if it meets the requirements if ($this->model !== null) { return $requirements->areMetBy($this->model->metadata()); } try { // Check if any models support these requirements $models = $this->registry->findModelsMetadataForSupport($requirements); return !empty($models); } catch (InvalidArgumentException $e) { // No models support the requirements return \false; } } /** * Checks if the prompt is supported for text generation. * * @since 0.1.0 * * @return bool True if text generation is supported. */ public function isSupportedForTextGeneration(): bool { return $this->isSupported(CapabilityEnum::textGeneration()); } /** * Checks if the prompt is supported for image generation. * * @since 0.1.0 * * @return bool True if image generation is supported. */ public function isSupportedForImageGeneration(): bool { return $this->isSupported(CapabilityEnum::imageGeneration()); } /** * Checks if the prompt is supported for text to speech conversion. * * @since 0.1.0 * * @return bool True if text to speech conversion is supported. */ public function isSupportedForTextToSpeechConversion(): bool { return $this->isSupported(CapabilityEnum::textToSpeechConversion()); } /** * Checks if the prompt is supported for video generation. * * @since 0.1.0 * * @return bool True if video generation is supported. */ public function isSupportedForVideoGeneration(): bool { return $this->isSupported(CapabilityEnum::videoGeneration()); } /** * Checks if the prompt is supported for speech generation. * * @since 0.1.0 * * @return bool True if speech generation is supported. */ public function isSupportedForSpeechGeneration(): bool { return $this->isSupported(CapabilityEnum::speechGeneration()); } /** * Checks if the prompt is supported for music generation. * * @since 0.1.0 * * @return bool True if music generation is supported. */ public function isSupportedForMusicGeneration(): bool { return $this->isSupported(CapabilityEnum::musicGeneration()); } /** * Checks if the prompt is supported for embedding generation. * * @since 0.1.0 * * @return bool True if embedding generation is supported. */ public function isSupportedForEmbeddingGeneration(): bool { return $this->isSupported(CapabilityEnum::embeddingGeneration()); } /** * Generates a result from the prompt. * * This is the primary execution method that generates a result (containing * potentially multiple candidates) based on the specified capability or * the configured output modality. * * @since 0.1.0 * * @param CapabilityEnum|null $capability Optional capability to use for generation. * If null, capability is inferred from output modality. * @return GenerativeAiResult The generated result containing candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support the required capability. */ public function generateResult(?CapabilityEnum $capability = null): GenerativeAiResult { $this->validateMessages(); // If capability is not provided, infer it if ($capability === null) { // First try to infer from a specific model if one is set if ($this->model !== null) { $inferredCapability = $this->inferCapabilityFromModelInterfaces($this->model); if ($inferredCapability !== null) { $capability = $inferredCapability; } } // If still no capability, infer from output modalities if ($capability === null) { $capability = $this->inferCapabilityFromOutputModalities(); } } $model = $this->getConfiguredModel($capability); // Dispatch BeforeGenerateResultEvent $this->dispatchEvent(new BeforeGenerateResultEvent($this->messages, $model, $capability)); // Route to the appropriate generation method based on capability $result = $this->executeModelGeneration($model, $capability, $this->messages); // Dispatch AfterGenerateResultEvent $this->dispatchEvent(new AfterGenerateResultEvent($this->messages, $model, $capability, $result)); return $result; } /** * Executes the model generation based on capability. * * @since 0.4.0 * * @param ModelInterface $model The model to use for generation. * @param CapabilityEnum $capability The capability to use. * @param list<Message> $messages The messages to send. * @return GenerativeAiResult The generated result. * @throws RuntimeException If the model doesn't support the required capability. */ private function executeModelGeneration(ModelInterface $model, CapabilityEnum $capability, array $messages): GenerativeAiResult { if ($capability->isTextGeneration()) { if (!$model instanceof TextGenerationModelInterface) { throw new RuntimeException(sprintf('Model "%s" does not support text generation.', $model->metadata()->getId())); } return $model->generateTextResult($messages); } if ($capability->isImageGeneration()) { if (!$model instanceof ImageGenerationModelInterface) { throw new RuntimeException(sprintf('Model "%s" does not support image generation.', $model->metadata()->getId())); } return $model->generateImageResult($messages); } if ($capability->isTextToSpeechConversion()) { if (!$model instanceof TextToSpeechConversionModelInterface) { throw new RuntimeException(sprintf('Model "%s" does not support text-to-speech conversion.', $model->metadata()->getId())); } return $model->convertTextToSpeechResult($messages); } if ($capability->isSpeechGeneration()) { if (!$model instanceof SpeechGenerationModelInterface) { throw new RuntimeException(sprintf('Model "%s" does not support speech generation.', $model->metadata()->getId())); } return $model->generateSpeechResult($messages); } if ($capability->isVideoGeneration()) { if (!$model instanceof VideoGenerationModelInterface) { throw new RuntimeException(sprintf('Model "%s" does not support video generation.', $model->metadata()->getId())); } return $model->generateVideoResult($messages); } // TODO: Add support for other capabilities when interfaces are available throw new RuntimeException(sprintf('Capability "%s" is not yet supported for generation.', $capability->value)); } /** * Generates a text result from the prompt. * * @since 0.1.0 * * @return GenerativeAiResult The generated result containing text candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support text generation. */ public function generateTextResult(): GenerativeAiResult { // Include text in output modalities $this->includeOutputModalities(ModalityEnum::text()); // Generate and return the result with text generation capability return $this->generateResult(CapabilityEnum::textGeneration()); } /** * Generates an image result from the prompt. * * @since 0.1.0 * * @return GenerativeAiResult The generated result containing image candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support image generation. */ public function generateImageResult(): GenerativeAiResult { // Include image in output modalities $this->includeOutputModalities(ModalityEnum::image()); // Generate and return the result with image generation capability return $this->generateResult(CapabilityEnum::imageGeneration()); } /** * Generates a speech result from the prompt. * * @since 0.1.0 * * @return GenerativeAiResult The generated result containing speech audio candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support speech generation. */ public function generateSpeechResult(): GenerativeAiResult { // Include audio in output modalities $this->includeOutputModalities(ModalityEnum::audio()); // Generate and return the result with speech generation capability return $this->generateResult(CapabilityEnum::speechGeneration()); } /** * Converts text to speech and returns the result. * * @since 0.1.0 * * @return GenerativeAiResult The generated result containing speech audio candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support text-to-speech conversion. */ public function convertTextToSpeechResult(): GenerativeAiResult { // Include audio in output modalities $this->includeOutputModalities(ModalityEnum::audio()); // Generate and return the result with text-to-speech conversion capability return $this->generateResult(CapabilityEnum::textToSpeechConversion()); } /** * Generates a video result from the prompt. * * @since 1.3.0 * * @return GenerativeAiResult The generated result containing video candidates. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If the model doesn't support video generation. */ public function generateVideoResult(): GenerativeAiResult { // Include video in output modalities $this->includeOutputModalities(ModalityEnum::video()); // Generate and return the result with video generation capability return $this->generateResult(CapabilityEnum::videoGeneration()); } /** * Generates text from the prompt. * * @since 0.1.0 * * @return string The generated text. * @throws InvalidArgumentException If the prompt or model validation fails. */ public function generateText(): string { return $this->generateTextResult()->toText(); } /** * Generates multiple text candidates from the prompt. * * @since 0.1.0 * * @param int|null $candidateCount The number of candidates to generate. * @return list<string> The generated texts. * @throws InvalidArgumentException If the prompt or model validation fails. */ public function generateTexts(?int $candidateCount = null): array { if ($candidateCount !== null) { $this->usingCandidateCount($candidateCount); } // Generate text result return $this->generateTextResult()->toTexts(); } /** * Generates an image from the prompt. * * @since 0.1.0 * * @return File The generated image file. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no image is generated. */ public function generateImage(): File { return $this->generateImageResult()->toFile(); } /** * Generates multiple images from the prompt. * * @since 0.1.0 * * @param int|null $candidateCount The number of images to generate. * @return list<File> The generated image files. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no images are generated. */ public function generateImages(?int $candidateCount = null): array { if ($candidateCount !== null) { $this->usingCandidateCount($candidateCount); } return $this->generateImageResult()->toFiles(); } /** * Converts text to speech. * * @since 0.1.0 * * @return File The generated speech audio file. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no audio is generated. */ public function convertTextToSpeech(): File { return $this->convertTextToSpeechResult()->toFile(); } /** * Converts text to multiple speech outputs. * * @since 0.1.0 * * @param int|null $candidateCount The number of speech outputs to generate. * @return list<File> The generated speech audio files. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no audio is generated. */ public function convertTextToSpeeches(?int $candidateCount = null): array { if ($candidateCount !== null) { $this->usingCandidateCount($candidateCount); } return $this->convertTextToSpeechResult()->toFiles(); } /** * Generates speech from the prompt. * * @since 0.1.0 * * @return File The generated speech audio file. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no audio is generated. */ public function generateSpeech(): File { return $this->generateSpeechResult()->toFile(); } /** * Generates multiple speech outputs from the prompt. * * @since 0.1.0 * * @param int|null $candidateCount The number of speech outputs to generate. * @return list<File> The generated speech audio files. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no audio is generated. */ public function generateSpeeches(?int $candidateCount = null): array { if ($candidateCount !== null) { $this->usingCandidateCount($candidateCount); } return $this->generateSpeechResult()->toFiles(); } /** * Generates a video from the prompt. * * @since 1.3.0 * * @return File The generated video file. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no video is generated. */ public function generateVideo(): File { return $this->generateVideoResult()->toFile(); } /** * Generates multiple videos from the prompt. * * @since 1.3.0 * * @param int|null $candidateCount The number of videos to generate. * @return list<File> The generated video files. * @throws InvalidArgumentException If the prompt or model validation fails. * @throws RuntimeException If no videos are generated. */ public function generateVideos(?int $candidateCount = null): array { if ($candidateCount !== null) { $this->usingCandidateCount($candidateCount); } return $this->generateVideoResult()->toFiles(); } /** * Appends a MessagePart to the messages array. * * If the last message has a user role, the part is added to it. * Otherwise, a new UserMessage is created with the part. * * @since 0.1.0 * * @param MessagePart $part The part to append. * @return void */ protected function appendPartToMessages(MessagePart $part): void { $lastMessage = end($this->messages); if ($lastMessage instanceof Message && $lastMessage->getRole()->isUser()) { // Replace the last message with a new one containing the appended part array_pop($this->messages); $this->messages[] = $lastMessage->withPart($part); return; } // Create new UserMessage with the part $this->messages[] = new UserMessage([$part]); } /** * Gets the model to use for generation. * * If a model has been explicitly set, validates it meets requirements and returns it. * Otherwise, finds a suitable model based on the prompt requirements. * * @since 0.1.0 * * @param CapabilityEnum $capability The capability the model will be using. * @return ModelInterface The model to use. * @throws InvalidArgumentException If no suitable model is found or set model doesn't meet requirements. */ private function getConfiguredModel(CapabilityEnum $capability): ModelInterface { $requirements = ModelRequirements::fromPromptData($capability, $this->messages, $this->modelConfig); if ($this->model !== null) { // Explicit model was provided via usingModel(); just update config and bind dependencies. $model = $this->model; $model->setConfig($this->modelConfig); $this->registry->bindModelDependencies($model); $this->bindModelRequestOptions($model); return $model; } // Retrieve the candidate models map which satisfies the requirements. $candidateMap = $this->getCandidateModelsMap($requirements); if (empty($candidateMap)) { $message = sprintf('No models found that support %s for this prompt.', $capability->value); if ($this->providerIdOrClassName !== null) { $message = sprintf('No models found for provider "%s" that support %s for this prompt.', $this->providerIdOrClassName, $capability->value); } throw new InvalidArgumentException($message); } // Check if any preferred models match the candidates, in priority order. if (!empty($this->modelPreferenceKeys)) { // Find preferences that match available candidates, preserving preference order. $matchingPreferences = array_intersect_key(array_flip($this->modelPreferenceKeys), $candidateMap); if (!empty($matchingPreferences)) { // Get the first matching preference key $firstMatchKey = key($matchingPreferences); [$providerId, $modelId] = $candidateMap[$firstMatchKey]; $model = $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig); $this->bindModelRequestOptions($model); return $model; } } // No preference matched; fall back to the first candidate discovered. [$providerId, $modelId] = reset($candidateMap); $model = $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig); $this->bindModelRequestOptions($model); return $model; } /** * Binds configured request options to the model if present and supported. * * Request options are only applicable to API-based models that make HTTP requests. * * @since 0.3.0 * * @param ModelInterface $model The model to bind request options to. * @return void */ private function bindModelRequestOptions(ModelInterface $model): void { if ($this->requestOptions !== null && $model instanceof ApiBasedModelInterface) { $model->setRequestOptions($this->requestOptions); } } /** * Builds a map of candidate models that satisfy the requirements for efficient lookup. * * @since 0.2.0 * * @param ModelRequirements $requirements The requirements derived from the prompt. * @return array<string, array{0:string,1:string}> Map of preference keys to [providerId, modelId] tuples. */ private function getCandidateModelsMap(ModelRequirements $requirements): array { if ($this->providerIdOrClassName === null) { // No provider locked in, gather all models across providers that meet requirements. $providerModelsMetadata = $this->registry->findModelsMetadataForSupport($requirements); $candidateMap = []; foreach ($providerModelsMetadata as $providerModels) { $providerId = $providerModels->getProvider()->getId(); $providerMap = $this->generateMapFromCandidates($providerId, $providerModels->getModels()); // Use + operator to merge, preserving keys from $candidateMap (first provider wins for model-only keys) $candidateMap = $candidateMap + $providerMap; } return $candidateMap; } // Provider set, only consider models from that provider. $modelsMetadata = $this->registry->findProviderModelsMetadataForSupport($this->providerIdOrClassName, $requirements); // Ensure we pass the provider ID, not the class name $providerId = $this->registry->getProviderId($this->providerIdOrClassName); return $this->generateMapFromCandidates($providerId, $modelsMetadata); } /** * Generates a candidate map from model metadata with both provider-specific and model-only keys. * * @since 0.2.0 * * @param string $providerId The provider ID. * @param list<ModelMetadata> $modelsMetadata The models metadata to map. * @return array<string, array{0:string,1:string}> Map of preference keys to [providerId, modelId] tuples. */ private function generateMapFromCandidates(string $providerId, array $modelsMetadata): array { $map = []; foreach ($modelsMetadata as $modelMetadata) { $modelId = $modelMetadata->getId(); // Add provider-specific key $providerModelKey = $this->createProviderModelPreferenceKey($providerId, $modelId); $map[$providerModelKey] = [$providerId, $modelId]; // Add model-only key $modelKey = $this->createModelPreferenceKey($modelId); $map[$modelKey] = [$providerId, $modelId]; } return $map; } /** * Normalizes and validates a preference identifier string. * * @since 0.2.0 * * @param mixed $value The value to normalize. * @param string $emptyMessage The message for empty or invalid values. * @return string The normalized identifier. * * @throws InvalidArgumentException If the value is not a non-empty string. */ private function normalizePreferenceIdentifier($value, string $emptyMessage = 'Model preference identifiers cannot be empty.'): string { if (!is_string($value)) { throw new InvalidArgumentException($emptyMessage); } $trimmed = trim($value); if ($trimmed === '') { throw new InvalidArgumentException($emptyMessage); } return $trimmed; } /** * Creates a preference key for a provider/model combination. * * @since 0.2.0 * * @param string $providerId The provider identifier. * @param string $modelId The model identifier. * @return string The generated preference key. */ private function createProviderModelPreferenceKey(string $providerId, string $modelId): string { return 'providerModel::' . $providerId . '::' . $modelId; } /** * Creates a preference key for a model identifier. * * @since 0.2.0 * * @param string $modelId The model identifier. * @return string The generated preference key. */ private function createModelPreferenceKey(string $modelId): string { return 'model::' . $modelId; } /** * Parses various input types into a Message with the given role. * * @since 0.1.0 * * @param mixed $input The input to parse. * @param MessageRoleEnum $defaultRole The role for the message if not specified by input. * @return Message The parsed message. * @throws InvalidArgumentException If the input type is not supported or results in empty message. */ private function parseMessage($input, MessageRoleEnum $defaultRole): Message { // Handle Message input directly if ($input instanceof Message) { return $input; } // Handle single MessagePart if ($input instanceof MessagePart) { return new Message($defaultRole, [$input]); } // Handle string input if (is_string($input)) { if (trim($input) === '') { throw new InvalidArgumentException('Cannot create a message from an empty string.'); } return new Message($defaultRole, [new MessagePart($input)]); } // Handle array input if (!is_array($input)) { throw new InvalidArgumentException('Input must be a string, MessagePart, MessagePartArrayShape, ' . 'a list of string|MessagePart|MessagePartArrayShape, or a Message instance.'); } // Handle MessageArrayShape input if (Message::isArrayShape($input)) { return Message::fromArray($input); } // Check if it's a MessagePartArrayShape if (MessagePart::isArrayShape($input)) { return new Message($defaultRole, [MessagePart::fromArray($input)]); } // It should be a list of string|MessagePart|MessagePartArrayShape if (!array_is_list($input)) { throw new InvalidArgumentException('Array input must be a list array.'); } // Empty array check if (empty($input)) { throw new InvalidArgumentException('Cannot create a message from an empty array.'); } $parts = []; foreach ($input as $item) { if (is_string($item)) { $parts[] = new MessagePart($item); } elseif ($item instanceof MessagePart) { $parts[] = $item; } elseif (is_array($item) && MessagePart::isArrayShape($item)) { $parts[] = MessagePart::fromArray($item); } else { throw new InvalidArgumentException('Array items must be strings, MessagePart instances, or MessagePartArrayShape.'); } } return new Message($defaultRole, $parts); } /** * Validates the messages array for prompt generation. * * Ensures that: * - The first message is a user message * - The last message is a user message * - The last message has parts * * @since 0.1.0 * * @return void * @throws InvalidArgumentException If validation fails. */ private function validateMessages(): void { if (empty($this->messages)) { throw new InvalidArgumentException('Cannot generate from an empty prompt. Add content using withText() or similar methods.'); } $firstMessage = reset($this->messages); if (!$firstMessage->getRole()->isUser()) { throw new InvalidArgumentException('The first message must be from a user role, not from ' . $firstMessage->getRole()->value); } $lastMessage = end($this->messages); if (!$lastMessage->getRole()->isUser()) { throw new InvalidArgumentException('The last message must be from a user role, not from ' . $lastMessage->getRole()->value); } if (empty($lastMessage->getParts())) { throw new InvalidArgumentException('The last message must have content parts. Add content using withText() or similar methods.'); } } /** * Checks if the value is a list of Message objects. * * @since 0.1.0 * * @param mixed $value The value to check. * @return bool True if the value is a list of Message objects. * * @phpstan-assert-if-true list<Message> $value */ private function isMessagesList($value): bool { if (!is_array($value) || empty($value) || !array_is_list($value)) { return \false; } // Check if all items are Messages foreach ($value as $item) { if (!$item instanceof Message) { return \false; } } return \true; } /** * Includes output modalities if not already present. * * Adds the given modalities to the output modalities list if they're not * already included. If output modalities is null, initializes it with * the given modalities. * * @since 0.1.0 * * @param ModalityEnum ...$modalities The modalities to include. * @return void */ private function includeOutputModalities(ModalityEnum ...$modalities): void { $existing = $this->modelConfig->getOutputModalities(); // Initialize if null if ($existing === null) { $this->modelConfig->setOutputModalities($modalities); return; } // Build a set of existing modality values for O(1) lookup $existingValues = []; foreach ($existing as $existingModality) { $existingValues[$existingModality->value] = \true; } // Add new modalities that don't exist $toAdd = []; foreach ($modalities as $modality) { if (!isset($existingValues[$modality->value])) { $toAdd[] = $modality; } } // Update if we have new modalities to add if (!empty($toAdd)) { $this->modelConfig->setOutputModalities(array_merge($existing, $toAdd)); } } /** * Dispatches an event if an event dispatcher is registered. * * @since 0.4.0 * * @param object $event The event to dispatch. * @return void */ private function dispatchEvent(object $event): void { if ($this->eventDispatcher !== null) { $this->eventDispatcher->dispatch($event); } } } PK ?�\ꬖD 9 src/Common/Contracts/WithArrayTransformationInterface.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Contracts; /** * Interface for objects that support array transformation. * * @since 0.1.0 * * @template TArrayShape of array<string, mixed> */ interface WithArrayTransformationInterface { /** * Converts the object to an array representation. * * @since 0.1.0 * * @return TArrayShape The array representation. */ public function toArray(): array; /** * Creates an instance from array data. * * @since 0.1.0 * * @param TArrayShape $array The array data. * @return self<TArrayShape> The created instance. */ public static function fromArray(array $array): self; /** * Checks if the array is a valid shape for this object. * * @since 0.1.0 * * @param array<mixed> $array The array to check. * @return bool True if the array is a valid shape. * @phpstan-assert-if-true TArrayShape $array */ public static function isArrayShape(array $array): bool; } PK ?�\=�5�W W 3 src/Common/Contracts/AiClientExceptionInterface.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Contracts; use Throwable; /** * Base interface for all AI Client exceptions. * * This interface allows callers to catch all AI Client specific exceptions * with a single catch statement. * * @since 0.2.0 */ interface AiClientExceptionInterface extends Throwable { } PK ?�\�ED�b b , src/Common/Contracts/CachesDataInterface.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Contracts; /** * Interface for objects that cache data. * * @since 0.4.0 */ interface CachesDataInterface { /** * Invalidates all caches managed by this object. * * @since 0.4.0 * * @return void */ public function invalidateCaches(): void; } PK ?�\���1^ ^ 0 src/Common/Contracts/WithJsonSchemaInterface.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Contracts; /** * Interface for objects that can provide their JSON schema representation. * * This interface is implemented by DTOs to provide a consistent way to retrieve * their JSON schema for validation and serialization purposes. * * @since 0.1.0 */ interface WithJsonSchemaInterface { /** * Gets the JSON schema representation of the object. * * @since 0.1.0 * * @return array<string, mixed> The JSON schema as an associative array. */ public static function getJsonSchema(): array; } PK ?�\PX�c� � 1 src/Common/Exception/InvalidArgumentException.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Exception; use WordPress\AiClient\Common\Contracts\AiClientExceptionInterface; /** * Exception thrown when an invalid argument is provided. * * This extends PHP's built-in InvalidArgumentException while implementing * the AI Client exception interface for consistent catch handling. * * @since 0.2.0 */ class InvalidArgumentException extends \InvalidArgumentException implements AiClientExceptionInterface { } PK ?�\.�}� � ) src/Common/Exception/RuntimeException.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Exception; use WordPress\AiClient\Common\Contracts\AiClientExceptionInterface; /** * Exception thrown for runtime errors. * * This extends PHP's built-in RuntimeException while implementing * the AI Client exception interface for consistent catch handling. * * @since 0.2.0 */ class RuntimeException extends \RuntimeException implements AiClientExceptionInterface { } PK ?�\�e�,� � 3 src/Common/Exception/TokenLimitReachedException.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Exception; /** * Exception thrown when a token limit is reached during prompt fulfillment. * * Providers should throw this exception when the token usage for a request * exceeds the allowed limit, whether that is the model's context window * or a configured maximum. * * @since 1.0.0 */ class TokenLimitReachedException extends \WordPress\AiClient\Common\Exception\RuntimeException { /** * The token limit that was reached, if known. * * @since 1.0.0 * * @var int|null */ private $maxTokens; /** * Creates a new TokenLimitReachedException. * * @since 1.0.0 * * @param string $message The exception message. * @param int|null $maxTokens The token limit that was reached, if known. * @param \Throwable|null $previous The previous throwable used for exception chaining. */ public function __construct(string $message = '', ?int $maxTokens = null, ?\Throwable $previous = null) { parent::__construct($message, 0, $previous); $this->maxTokens = $maxTokens; } /** * Returns the token limit that was reached, if known. * * @since 1.0.0 * * @return int|null The token limit, or null if not provided. */ public function getMaxTokens(): ?int { return $this->maxTokens; } } PK ?�\�`]� � * src/Common/Traits/WithDataCachingTrait.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common\Traits; use WordPress\AiClient\AiClient; /** * Trait for objects that cache data using PSR-16 cache with in-memory fallback. * * When a PSR-16 cache is configured via AiClient::setCache(), data is stored persistently. * Otherwise, data is cached in-memory for the duration of the request. * * @since 0.4.0 */ trait WithDataCachingTrait { /** * In-memory cache used when no PSR-16 cache is configured. * * @since 0.4.0 * * @var array<string, mixed> */ private array $localCache = []; /** * Gets the cache key suffixes managed by this object. * * @since 0.4.0 * * @return list<string> The cache key suffixes. */ abstract protected function getCachedKeys(): array; /** * Gets the base cache key for this object. * * The base cache key is used as a prefix for all cache keys managed by this object. * It should be unique to the implementing class to avoid cache key collisions. * * @since 0.4.0 * * @return string The base cache key. */ abstract protected function getBaseCacheKey(): string; /** * Checks if a value exists in the cache. * * @since 0.4.0 * * @param string $key The cache key suffix (will be appended to the base key). * @return bool True if the value exists in cache, false otherwise. */ protected function hasCache(string $key): bool { $fullKey = $this->buildCacheKey($key); $cache = AiClient::getCache(); if ($cache !== null) { return $cache->has($fullKey); } return array_key_exists($fullKey, $this->localCache); } /** * Gets a value from the cache, or computes and caches it if not present. * * @since 0.4.0 * * @param string $key The cache key suffix (will be appended to the base key). * @param callable $callback The callback to compute the value if not cached. * @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default. * Ignored for local cache. * @return mixed The cached or computed value. */ protected function cached(string $key, callable $callback, $ttl = null) { if ($this->hasCache($key)) { return $this->getCache($key); } $value = $callback(); $this->setCache($key, $value, $ttl); return $value; } /** * Gets a value from the cache. * * @since 0.4.0 * * @param string $key The cache key suffix (will be appended to the base key). * @param mixed $default The default value to return if the key does not exist. * @return mixed The cached value or the default value if not found. */ protected function getCache(string $key, $default = null) { $fullKey = $this->buildCacheKey($key); $cache = AiClient::getCache(); if ($cache !== null) { return $cache->get($fullKey, $default); } return $this->localCache[$fullKey] ?? $default; } /** * Sets a value in the cache. * * @since 0.4.0 * * @param string $key The cache key suffix (will be appended to the base key). * @param mixed $value The value to cache. * @param int|\DateInterval|null $ttl The TTL for the cache entry, or null for default. Ignored for local cache. * @return bool True on success, false on failure. */ protected function setCache(string $key, $value, $ttl = null): bool { $fullKey = $this->buildCacheKey($key); $cache = AiClient::getCache(); if ($cache !== null) { return $cache->set($fullKey, $value, $ttl); } $this->localCache[$fullKey] = $value; return \true; } /** * Invalidates all caches managed by this object. * * @since 0.4.0 * * @return void */ public function invalidateCaches(): void { foreach ($this->getCachedKeys() as $key) { $this->clearCache($key); } } /** * Clears a value from the cache. * * @since 0.4.0 * * @param string $key The cache key suffix (will be appended to the base key). * @return bool True on success, false on failure. */ protected function clearCache(string $key): bool { $fullKey = $this->buildCacheKey($key); $cache = AiClient::getCache(); if ($cache !== null) { return $cache->delete($fullKey); } unset($this->localCache[$fullKey]); return \true; } /** * Builds the full cache key by combining the base key with the suffix. * * @since 0.4.0 * * @param string $key The cache key suffix. * @return string The full cache key. */ private function buildCacheKey(string $key): string { return $this->getBaseCacheKey() . '_' . $key; } } PK ?�\ �µ} } ) src/Common/AbstractDataTransferObject.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common; use JsonSerializable; use stdClass; use WordPress\AiClient\Common\Contracts\WithArrayTransformationInterface; use WordPress\AiClient\Common\Contracts\WithJsonSchemaInterface; use WordPress\AiClient\Common\Exception\InvalidArgumentException; /** * Abstract base class for all Data Value Objects in the AI Client. * * This abstract class consolidates the common functionality needed by all * data transfer objects: * - Array transformation for data manipulation * - JSON schema support for validation and documentation * - JSON serialization with proper empty object handling * * All DTOs in the AI Client should extend this class to ensure * consistent behavior across the codebase. * * @since 0.1.0 * * @template TArrayShape of array<string, mixed> * @implements WithArrayTransformationInterface<TArrayShape> */ abstract class AbstractDataTransferObject implements WithArrayTransformationInterface, WithJsonSchemaInterface, JsonSerializable { /** * Validates that required keys exist in the array data. * * @since 0.1.0 * * @param array<mixed> $data The array data to validate. * @param string[] $requiredKeys The keys that must be present. * @throws InvalidArgumentException If any required key is missing. */ protected static function validateFromArrayData(array $data, array $requiredKeys): void { $missingKeys = []; foreach ($requiredKeys as $key) { if (!array_key_exists($key, $data)) { $missingKeys[] = $key; } } if (!empty($missingKeys)) { throw new InvalidArgumentException(sprintf('%s::fromArray() missing required keys: %s', static::class, implode(', ', $missingKeys))); } } /** * {@inheritDoc} * * @since 0.1.0 */ public static function isArrayShape(array $array): bool { try { /** @var TArrayShape $array */ static::fromArray($array); return \true; } catch (InvalidArgumentException $e) { return \false; } } /** * Converts the object to a JSON-serializable format. * * This method uses the toArray() method and then processes the result * based on the JSON schema to ensure proper object representation for * empty arrays. * * @since 0.1.0 * * @return mixed The JSON-serializable representation. */ #[\ReturnTypeWillChange] public function jsonSerialize() { $data = $this->toArray(); $schema = static::getJsonSchema(); return $this->convertEmptyArraysToObjects($data, $schema); } /** * Recursively converts empty arrays to stdClass objects where the schema expects objects. * * @since 0.1.0 * * @param mixed $data The data to process. * @param array<mixed, mixed> $schema The JSON schema for the data. * @return mixed The processed data. */ private function convertEmptyArraysToObjects($data, array $schema) { // If data is an empty array and schema expects object, convert to stdClass if (is_array($data) && empty($data) && isset($schema['type']) && $schema['type'] === 'object') { return new stdClass(); } // If data is an array with content, recursively process nested structures if (is_array($data)) { // Handle object properties if (isset($schema['properties']) && is_array($schema['properties'])) { foreach ($data as $key => $value) { if (isset($schema['properties'][$key]) && is_array($schema['properties'][$key])) { $data[$key] = $this->convertEmptyArraysToObjects($value, $schema['properties'][$key]); } } } // Handle array items if (isset($schema['items']) && is_array($schema['items'])) { foreach ($data as $index => $item) { $data[$index] = $this->convertEmptyArraysToObjects($item, $schema['items']); } } // Handle oneOf/anyOf schemas - just use the first one foreach (['oneOf', 'anyOf'] as $keyword) { if (isset($schema[$keyword]) && is_array($schema[$keyword])) { foreach ($schema[$keyword] as $possibleSchema) { if (is_array($possibleSchema)) { return $this->convertEmptyArraysToObjects($data, $possibleSchema); } } } } } return $data; } } PK ?�\�M3Vp, p, src/Common/AbstractEnum.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Common; use BadMethodCallException; use JsonSerializable; use ReflectionClass; use WordPress\AiClient\Common\Exception\InvalidArgumentException; use WordPress\AiClient\Common\Exception\RuntimeException; /** * Abstract base class for enum-like behavior in PHP 7.4. * * This class provides enum-like functionality for PHP versions that don't support native enums. * Child classes should define uppercase snake_case constants for enum values. * * @example * class PersonEnum extends AbstractEnum { * public const FIRST_NAME = 'first'; * public const LAST_NAME = 'last'; * } * * // Usage: * $enum = PersonEnum::from('first'); // Creates instance with value 'first' * $enum = PersonEnum::tryFrom('invalid'); // Returns null * $enum = PersonEnum::firstName(); // Creates instance with value 'first' * $enum->name; // 'FIRST_NAME' * $enum->value; // 'first' * $enum->equals('first'); // Returns true * $enum->is(PersonEnum::firstName()); // Returns true * PersonEnum::cases(); // Returns array of all enum instances * * @property-read string $value The value of the enum instance. * @property-read string $name The name of the enum constant. * * @since 0.1.0 */ abstract class AbstractEnum implements JsonSerializable { /** * @var string The value of the enum instance. */ private string $value; /** * @var string The name of the enum constant. */ private string $name; /** * @var array<string, array<string, string>> Cache for reflection data. */ private static array $cache = []; /** * @var array<string, array<string, self>> Cache for enum instances. */ private static array $instances = []; /** * Constructor is private to ensure instances are created through static methods. * * @since 0.1.0 * * @param string $value The enum value. * @param string $name The constant name. */ final private function __construct(string $value, string $name) { $this->value = $value; $this->name = $name; } /** * Provides read-only access to properties. * * @since 0.1.0 * * @param string $property The property name. * @return mixed The property value. * @throws BadMethodCallException If property doesn't exist. */ final public function __get(string $property) { if ($property === 'value' || $property === 'name') { return $this->{$property}; } throw new BadMethodCallException(sprintf('Property %s::%s does not exist', static::class, $property)); } /** * Prevents property modification. * * @since 0.1.0 * * @param string $property The property name. * @param mixed $value The value to set. * @throws BadMethodCallException Always, as enum properties are read-only. */ final public function __set(string $property, $value): void { throw new BadMethodCallException(sprintf('Cannot modify property %s::%s - enum properties are read-only', static::class, $property)); } /** * Creates an enum instance from a value, throws exception if invalid. * * @since 0.1.0 * * @param string $value The enum value. * @return static The enum instance. * @throws InvalidArgumentException If the value is not valid. */ final public static function from(string $value): self { $instance = self::tryFrom($value); if ($instance === null) { throw new InvalidArgumentException(sprintf('%s is not a valid backing value for enum %s', $value, static::class)); } return $instance; } /** * Tries to create an enum instance from a value, returns null if invalid. * * @since 0.1.0 * * @param string $value The enum value. * @return static|null The enum instance or null. */ final public static function tryFrom(string $value): ?self { $constants = static::getConstants(); foreach ($constants as $name => $constantValue) { if ($constantValue === $value) { return self::getInstance($constantValue, $name); } } return null; } /** * Gets all enum cases. * * @since 0.1.0 * * @return static[] Array of all enum instances. */ final public static function cases(): array { $cases = []; $constants = static::getConstants(); foreach ($constants as $name => $value) { $cases[] = self::getInstance($value, $name); } return $cases; } /** * Checks if this enum has the same value as the given value. * * @since 0.1.0 * * @param string|self $other The value or enum to compare. * @return bool True if values are equal. */ final public function equals($other): bool { if ($other instanceof self) { return $this->is($other); } return $this->value === $other; } /** * Checks if this enum is the same instance type and value as another enum. * * @since 0.1.0 * * @param self $other The other enum to compare. * @return bool True if enums are identical. */ final public function is(self $other): bool { return $this === $other; // Since we're using singletons, we can use identity comparison } /** * Gets all valid values for this enum. * * @since 0.1.0 * * @return string[] List of all enum values. */ final public static function getValues(): array { return array_values(static::getConstants()); } /** * Checks if a value is valid for this enum. * * @since 0.1.0 * * @param string $value The value to check. * @return bool True if value is valid. */ final public static function isValidValue(string $value): bool { return in_array($value, self::getValues(), \true); } /** * Gets or creates a singleton instance for the given value and name. * * @since 0.1.0 * * @param string $value The enum value. * @param string $name The constant name. * @return static The enum instance. */ private static function getInstance(string $value, string $name): self { $className = static::class; if (!isset(self::$instances[$className])) { self::$instances[$className] = []; } if (!isset(self::$instances[$className][$name])) { $instance = new $className($value, $name); self::$instances[$className][$name] = $instance; } /** @var static */ return self::$instances[$className][$name]; } /** * Gets all constants for this enum class. * * @since 0.1.0 * * @return array<string, string> Map of constant names to values. * @throws RuntimeException If invalid constant found. */ final protected static function getConstants(): array { $className = static::class; if (!isset(self::$cache[$className])) { self::$cache[$className] = static::determineClassEnumerations($className); } return self::$cache[$className]; } /** * Determines the class enumerations by reflecting on class constants. * * This method can be overridden by subclasses to customize how * enumerations are determined (e.g., to add dynamic constants). * * @since 0.1.0 * * @param class-string $className The fully qualified class name. * @return array<string, string> Map of constant names to values. * @throws RuntimeException If invalid constant found. */ protected static function determineClassEnumerations(string $className): array { $reflection = new ReflectionClass($className); $constants = $reflection->getConstants(); // Validate all constants $enumConstants = []; foreach ($constants as $name => $value) { // Check if constant name follows uppercase snake_case pattern if (!preg_match('/^[A-Z][A-Z0-9_]*$/', $name)) { throw new RuntimeException(sprintf('Invalid enum constant name "%s" in %s. Constants must be UPPER_SNAKE_CASE.', $name, $className)); } // Check if value is valid type if (!is_string($value)) { throw new RuntimeException(sprintf('Invalid enum value type for constant %s::%s. ' . 'Only string values are allowed, %s given.', $className, $name, gettype($value))); } $enumConstants[$name] = $value; } return $enumConstants; } /** * Handles dynamic method calls for enum checking. * * @since 0.1.0 * * @param string $name The method name. * @param array<mixed> $arguments The method arguments. * @return bool True if the enum value matches. * @throws BadMethodCallException If the method doesn't exist. */ final public function __call(string $name, array $arguments): bool { // Handle is* methods if (str_starts_with($name, 'is')) { $constantName = self::camelCaseToConstant(substr($name, 2)); $constants = static::getConstants(); if (isset($constants[$constantName])) { return $this->value === $constants[$constantName]; } } throw new BadMethodCallException(sprintf('Method %s::%s does not exist', static::class, $name)); } /** * Handles static method calls for enum creation. * * @since 0.1.0 * * @param string $name The method name. * @param array<mixed> $arguments The method arguments. * @return static The enum instance. * @throws BadMethodCallException If the method doesn't exist. */ final public static function __callStatic(string $name, array $arguments): self { $constantName = self::camelCaseToConstant($name); $constants = static::getConstants(); if (isset($constants[$constantName])) { return self::getInstance($constants[$constantName], $constantName); } throw new BadMethodCallException(sprintf('Method %s::%s does not exist', static::class, $name)); } /** * Converts camelCase to CONSTANT_CASE. * * @since 0.1.0 * * @param string $camelCase The camelCase string. * @return string The CONSTANT_CASE version. */ private static function camelCaseToConstant(string $camelCase): string { $snakeCase = preg_replace('/([a-z])([A-Z])/', '$1_$2', $camelCase); if ($snakeCase === null) { return strtoupper($camelCase); } return strtoupper($snakeCase); } /** * Returns string representation of the enum. * * @since 0.1.0 * * @return string The enum value. */ final public function __toString(): string { return $this->value; } /** * Converts the enum to a JSON-serializable format. * * @since 0.1.0 * * @return string The enum value. */ #[\ReturnTypeWillChange] public function jsonSerialize() { return $this->value; } } PK ?�\xE�ک � ( src/Events/BeforeGenerateResultEvent.phpnu ȯ�� <?php declare (strict_types=1); namespace WordPress\AiClient\Events; use WordPress\AiClient\Messages\DTO\Message; use WordPress\AiClient\Providers\Models\Contracts\ModelInterface; use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum; /** * Event dispatched before a prompt is sent to the AI model. * * This event allows listeners to inspect and modify the messages before they * are sent to the model. The event is not stoppable, meaning the model call * will always proceed regardless of listener actions. * * @since 0.4.0 */ class BeforeGenerateResultEvent { /** * @var list<Message> The messages to be sent to the model. */ private array $messages; /** * @var ModelInterface The model that will process the prompt. */ private ModelInterface $model; /** * @var CapabilityEnum|null The capability being used for generation. */ private ?CapabilityEnum $capability; /** * Constructor. * * @since 0.4.0 * * @param list<Message> $messages The messages to be sent to the model. * @param ModelInterface $model The model that will process the prompt. * @param CapabilityEnum|null $capability The capability being used for generation. */ public function __construct(array $messages, ModelInterface $model, ?CapabilityEnum $capability) { $this->messages = $messages; $this->model = $model; $this->capability = $capability; } /** * Gets the messages to be sent to the model. * * @since 0.4.0 * * @return list<Message> The messages. */ public function getMessages(): array { return $this->messages; } /** * Gets the model that will process the prompt. * * @since 0.4.0 * * @return ModelInterface The model. */ public function getModel(): ModelInterface { return $this->model; } /** * Gets the capability being used for generation. * * @since 0.4.0 * * @return CapabilityEnum|null The capability, or null if not specified. */ public function getCapability(): ?CapabilityEnum { return $this->capability; } /** * Performs a deep clone of the event. * * This method ensures that message objects are cloned to prevent * modifications to the cloned event from affecting the original. * The model object is not cloned as it is a service object. * * @since 0.4.2 */ public function __clone() { $clonedMessages = []; foreach ($this->messages as $message) { $clonedMessages[] = clone $message; } $this->messages = $clonedMessages; } } PK ?�\��� � '