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/AbstractEnum.php

@@ -138,7 +138,7 @@ final public static function from(string $value): self
      */
     final public static function tryFrom(string $value): ?self
     {
-        $constants = self::getConstants();
+        $constants = static::getConstants();
         foreach ($constants as $name => $constantValue) {
             if ($constantValue === $value) {
                 return self::getInstance($constantValue, $name);
@@ -157,7 +157,7 @@ final public static function tryFrom(string $value): ?self
     final public static function cases(): array
     {
         $cases = [];
-        $constants = self::getConstants();
+        $constants = static::getConstants();
         foreach ($constants as $name => $value) {
             $cases[] = self::getInstance($value, $name);
         }
@@ -203,7 +203,7 @@ final public function is(self $other): bool
      */
     final public static function getValues(): array
     {
-        return array_values(self::getConstants());
+        return array_values(static::getConstants());
     }
 
     /**
@@ -258,43 +258,60 @@ final protected static function getConstants(): array
         $className = static::class;
 
         if (!isset(self::$cache[$className])) {
-            $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;
+            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 n.e.x.t
+     *
+     * @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)
+                    )
+                );
             }
 
-            self::$cache[$className] = $enumConstants;
+            $enumConstants[$name] = $value;
         }
 
-        return self::$cache[$className];
+        return $enumConstants;
     }
 
     /**
@@ -312,7 +329,7 @@ final public function __call(string $name, array $arguments): bool
         // Handle is* methods
         if (strpos($name, 'is') === 0) {
             $constantName = self::camelCaseToConstant(substr($name, 2));
-            $constants = self::getConstants();
+            $constants = static::getConstants();
 
             if (isset($constants[$constantName])) {
                 return $this->value === $constants[$constantName];
@@ -337,7 +354,7 @@ final public function __call(string $name, array $arguments): bool
     final public static function __callStatic(string $name, array $arguments): self
     {
         $constantName = self::camelCaseToConstant($name);
-        $constants = self::getConstants();
+        $constants = static::getConstants();
 
         if (isset($constants[$constantName])) {
             return self::getInstance($constants[$constantName], $constantName);

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

@@ -174,6 +174,30 @@ public function getFileType(): FileTypeEnum
         return $this->fileType;
     }
 
+    /**
+     * Checks if the file is an inline file.
+     *
+     * @since n.e.x.t
+     *
+     * @return bool True if the file is inline (base64/data URI).
+     */
+    public function isInline(): bool
+    {
+        return $this->fileType->isInline();
+    }
+
+    /**
+     * Checks if the file is a remote file.
+     *
+     * @since n.e.x.t
+     *
+     * @return bool True if the file is remote (URL).
+     */
+    public function isRemote(): bool
+    {
+        return $this->fileType->isRemote();
+    }
+
     /**
      * Gets the URL for remote files.
      *
@@ -286,6 +310,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

@@ -4,6 +4,7 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
+use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
@@ -45,11 +46,13 @@ class Message extends AbstractDataTransferObject
      *
      * @param MessageRoleEnum $role The role of the message sender.
      * @param MessagePart[] $parts The parts that make up this message.
+     * @throws InvalidArgumentException If parts contain invalid content for the role.
      */
     public function __construct(MessageRoleEnum $role, array $parts)
     {
         $this->role = $role;
         $this->parts = $parts;
+        $this->validateParts();
     }
 
     /**
@@ -76,6 +79,48 @@ 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.
+     * @throws InvalidArgumentException If the part is invalid for the role.
+     */
+    public function withPart(MessagePart $part): Message
+    {
+        $newParts = $this->parts;
+        $newParts[] = $part;
+
+        return new Message($this->role, $newParts);
+    }
+
+    /**
+     * Validates that the message parts are appropriate for the message role.
+     *
+     * @since n.e.x.t
+     *
+     * @return void
+     * @throws InvalidArgumentException If validation fails.
+     */
+    private function validateParts(): void
+    {
+        foreach ($this->parts as $part) {
+            if ($this->role->isUser() && $part->getType()->isFunctionCall()) {
+                throw new InvalidArgumentException(
+                    'User messages cannot contain function calls.'
+                );
+            }
+
+            if ($this->role->isModel() && $part->getType()->isFunctionResponse()) {
+                throw new InvalidArgumentException(
+                    'Model messages cannot contain function responses.'
+                );
+            }
+        }
+    }
+
     /**
      * {@inheritDoc}
      *

src/Messages/DTO/ModelMessage.php

@@ -12,6 +12,10 @@
  * This is a convenience class that automatically sets the role to MODEL.
  * Model messages contain the AI's responses.
  *
+ * Important: Do not rely on `instanceof ModelMessage` to determine the message role.
+ * This is merely a helper class for construction. Always use `$message->getRole()`
+ * to check the role of a message.
+ *
  * @since n.e.x.t
  */
 class ModelMessage extends Message

src/Messages/DTO/UserMessage.php

@@ -11,6 +11,10 @@
  *
  * This is a convenience class that automatically sets the role to USER.
  *
+ * Important: Do not rely on `instanceof UserMessage` to determine the message role.
+ * This is merely a helper class for construction. Always use `$message->getRole()`
+ * to check the role of a message.
+ *
  * @since n.e.x.t
  */
 class UserMessage extends Message