Add the Prompt Builder

src/Common/AbstractDataTransferObject.php

@@ -37,7 +37,7 @@ abstract class AbstractDataTransferObject implements
      *
      * @since n.e.x.t
      *
-     * @param TArrayShape $data The array data to validate.
+     * @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.
      */
@@ -62,6 +62,22 @@ protected static function validateFromArrayData(array $data, array $requiredKeys
         }
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    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.
      *

src/Common/Contracts/WithArrayTransformationInterface.php

@@ -31,4 +31,15 @@ public function toArray(): array;
      * @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 n.e.x.t
+     *
+     * @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;
 }

src/Files/DTO/File.php

@@ -286,6 +286,18 @@ public function isText(): bool
         return $this->mimeType->isText();
     }
 
+    /**
+     * Checks if the file is a document.
+     *
+     * @since n.e.x.t
+     *
+     * @return bool True if the file is a document.
+     */
+    public function isDocument(): bool
+    {
+        return $this->mimeType->isDocument();
+    }
+
     /**
      * Checks if the file is a specific MIME type.
      *

src/Messages/DTO/Message.php

@@ -76,6 +76,22 @@ public function getParts(): array
         return $this->parts;
     }
 
+    /**
+     * Returns a new instance with the given part appended.
+     *
+     * @since n.e.x.t
+     *
+     * @param MessagePart $part The part to append.
+     * @return Message A new instance with the part appended.
+     */
+    public function withPart(MessagePart $part): Message
+    {
+        $newParts = $this->parts;
+        $newParts[] = $part;
+
+        return new Message($this->role, $newParts);
+    }
+
     /**
      * {@inheritDoc}
      *

src/Providers/Models/DTO/ModelConfig.php

@@ -9,6 +9,7 @@
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
+use WordPress\AiClient\Providers\Models\Enums\OptionEnum;
 use WordPress\AiClient\Tools\DTO\FunctionDeclaration;
 use WordPress\AiClient\Tools\DTO\WebSearch;
 
@@ -202,6 +203,36 @@ public function getOutputModalities(): ?array
         return $this->outputModalities;
     }
 
+    /**
+     * Includes an output modality if not already present.
+     *
+     * Adds the given modality to the output modalities list if it's not
+     * already included. If output modalities is null, initializes it with
+     * the given modality.
+     *
+     * @since n.e.x.t
+     *
+     * @param ModalityEnum $modality The modality to include.
+     */
+    public function includeOutputModality(ModalityEnum $modality): void
+    {
+        // Initialize if null
+        if ($this->outputModalities === null) {
+            $this->outputModalities = [$modality];
+            return;
+        }
+
+        // Check if modality already exists
+        foreach ($this->outputModalities as $existingModality) {
+            if ($existingModality === $modality) {
+                return; // Already included
+            }
+        }
+
+        // Add the modality
+        $this->outputModalities[] = $modality;
+    }
+
     /**
      * Sets the system instruction.
      *
@@ -913,6 +944,131 @@ static function (FunctionDeclaration $function_declaration): array {
         return $data;
     }
 
+    /**
+     * Converts the model configuration to required options.
+     *
+     * @since n.e.x.t
+     *
+     * @return list<RequiredOption> The required options.
+     */
+    public function toRequiredOptions(): array
+    {
+        $requiredOptions = [];
+
+        // Map properties that have corresponding OptionEnum values
+        if ($this->outputModalities !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::outputModalities()->value,
+                $this->outputModalities
+            );
+        }
+
+        if ($this->systemInstruction !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::systemInstruction()->value,
+                $this->systemInstruction
+            );
+        }
+
+        if ($this->candidateCount !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::candidateCount()->value,
+                $this->candidateCount
+            );
+        }
+
+        if ($this->maxTokens !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::maxTokens()->value,
+                $this->maxTokens
+            );
+        }
+
+        if ($this->temperature !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::temperature()->value,
+                $this->temperature
+            );
+        }
+
+        if ($this->topP !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::topP()->value,
+                $this->topP
+            );
+        }
+
+        if ($this->topK !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::topK()->value,
+                $this->topK
+            );
+        }
+
+        if ($this->outputMimeType !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::outputMimeType()->value,
+                $this->outputMimeType
+            );
+        }
+
+        if ($this->outputSchema !== null) {
+            $requiredOptions[] = new RequiredOption(
+                OptionEnum::outputSchema()->value,
+                true // Just indicate that schema is required
+            );
+        }
+
+        // Handle properties without OptionEnum values as custom options
+        // These would need to be handled specially by providers
+        if ($this->stopSequences !== null) {
+            $requiredOptions[] = new RequiredOption('stop_sequences', $this->stopSequences);
+        }
+
+        if ($this->presencePenalty !== null) {
+            $requiredOptions[] = new RequiredOption('presence_penalty', $this->presencePenalty);
+        }
+
+        if ($this->frequencyPenalty !== null) {
+            $requiredOptions[] = new RequiredOption('frequency_penalty', $this->frequencyPenalty);
+        }
+
+        if ($this->logprobs !== null) {
+            $requiredOptions[] = new RequiredOption('logprobs', $this->logprobs);
+        }
+
+        if ($this->topLogprobs !== null) {
+            $requiredOptions[] = new RequiredOption('top_logprobs', $this->topLogprobs);
+        }
+
+        if ($this->functionDeclarations !== null) {
+            $requiredOptions[] = new RequiredOption('function_declarations', true);
+        }
+
+        if ($this->webSearch !== null) {
+            $requiredOptions[] = new RequiredOption('web_search', true);
+        }
+
+        if ($this->outputFileType !== null) {
+            $requiredOptions[] = new RequiredOption('output_file_type', $this->outputFileType->value);
+        }
+
+        if ($this->outputMediaOrientation !== null) {
+            $requiredOptions[] = new RequiredOption('output_media_orientation', $this->outputMediaOrientation->value);
+        }
+
+        if ($this->outputMediaAspectRatio !== null) {
+            $requiredOptions[] = new RequiredOption('output_media_aspect_ratio', $this->outputMediaAspectRatio);
+        }
+
+        // Add custom options as individual RequiredOptions
+        foreach ($this->customOptions as $key => $value) {
+            $requiredOptions[] = new RequiredOption($key, $value);
+        }
+
+        return $requiredOptions;
+    }
+
     /**
      * {@inheritDoc}
      *

tests/traits/ArrayTransformationTestTrait.php

@@ -83,4 +83,33 @@ protected function assertArrayNotHasKeys(array $array, array $unexpectedKeys): v
             $this->assertArrayNotHasKey($key, $array, "Array should not contain key: {$key}");
         }
     }
+
+    /**
+     * Tests isArrayShape with valid and invalid arrays.
+     *
+     * @param string $className The class name to test.
+     * @param array $validArray A valid array that should pass isArrayShape.
+     * @param array[] $invalidArrays Arrays that should fail isArrayShape.
+     * @return void
+     */
+    protected function assertIsArrayShapeValidation(string $className, array $validArray, array $invalidArrays): void
+    {
+        // Test valid array
+        $this->assertTrue(
+            $className::isArrayShape($validArray),
+            'isArrayShape() should return true for valid array structure'
+        );
+
+        // Test that fromArray works with the valid array (ensures consistency)
+        $instance = $className::fromArray($validArray);
+        $this->assertInstanceOf($className, $instance);
+
+        // Test invalid arrays
+        foreach ($invalidArrays as $description => $invalidArray) {
+            $this->assertFalse(
+                $className::isArrayShape($invalidArray),
+                "isArrayShape() should return false for: {$description}"
+            );
+        }
+    }
 }