Implement Exception Hierarchy For Better Error Handling

AGENTS.md

@@ -83,6 +83,15 @@ The production code in `src` follows a structured namespace hierarchy under the
 
 All parameters, return values, and properties must use explicit type hints, except in cases where providing the correct type hint would be impossible given limitations of backward compatibility with PHP 7.4. In any case, concrete type annotations using PHPStan should be present.
 
+### Exception handling
+
+All exceptions must use the project's custom exception classes rather than PHP built-in exceptions. This includes:
+
+- Use the custom primitive exceptions in `WordPress\AiClient\Common\Exception\` instead of the PHP primitive exceptions
+- If a PHP primitive exception is needed that doesn't have a custom exception counterpart, then create one that extends the primitive and implements AiClientExceptionInterface
+- All custom exceptions implement `WordPress\AiClient\Exceptions\AiClientExceptionInterface` for unified exception handling
+- Follow usage-driven design: only implement static factory methods that are actually used in the codebase
+
 ### Naming conventions
 
 The following naming conventions must be followed for consistency and autoloading:

src/AiClient.php

@@ -5,6 +5,8 @@
 namespace WordPress\AiClient;
 
 use WordPress\AiClient\Builders\PromptBuilder;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\ProviderImplementations\Anthropic\AnthropicProvider;
 use WordPress\AiClient\ProviderImplementations\Google\GoogleProvider;
 use WordPress\AiClient\ProviderImplementations\OpenAi\OpenAiProvider;
@@ -312,7 +314,7 @@ public static function generateSpeechResult(
      */
     public static function message(?string $text = null)
     {
-        throw new \RuntimeException(
+        throw new RuntimeException(
             'MessageBuilder is not yet available. This method depends on builder infrastructure. ' .
             'Use direct generation methods (generateTextResult, generateImageResult, etc.) for now.'
         );
@@ -332,7 +334,7 @@ private static function validateModelOrConfigParameter($modelOrConfig): void
             && !$modelOrConfig instanceof ModelInterface
             && !$modelOrConfig instanceof ModelConfig
         ) {
-            throw new \InvalidArgumentException(
+            throw new InvalidArgumentException(
                 'Parameter must be a ModelInterface instance (specific model), ' .
                 'ModelConfig instance (for auto-discovery), or null (default auto-discovery). ' .
                 sprintf('Received: %s', is_object($modelOrConfig) ? get_class($modelOrConfig) : gettype($modelOrConfig))

src/Builders/PromptBuilder.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Builders;
 
-use InvalidArgumentException;
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Messages\DTO\Message;

src/Common/AbstractDataTransferObject.php

@@ -4,11 +4,11 @@
 
 namespace WordPress\AiClient\Common;
 
-use InvalidArgumentException;
 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.

src/Common/AbstractEnum.php

@@ -5,10 +5,10 @@
 namespace WordPress\AiClient\Common;
 
 use BadMethodCallException;
-use InvalidArgumentException;
 use JsonSerializable;
 use ReflectionClass;
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 
 /**
  * Abstract base class for enum-like behavior in PHP 7.4.

src/Common/Contracts/AiClientExceptionInterface.php

@@ -0,0 +1,19 @@
+<?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 n.e.x.t
+ */
+interface AiClientExceptionInterface extends Throwable
+{
+}

src/Common/Exception/InvalidArgumentException.php

@@ -0,0 +1,19 @@
+<?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 n.e.x.t
+ */
+class InvalidArgumentException extends \InvalidArgumentException implements AiClientExceptionInterface
+{
+}

src/Common/Exception/RuntimeException.php

@@ -0,0 +1,19 @@
+<?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 n.e.x.t
+ */
+class RuntimeException extends \RuntimeException implements AiClientExceptionInterface
+{
+}

src/Files/DTO/File.php

@@ -4,9 +4,9 @@
 
 namespace WordPress\AiClient\Files\DTO;
 
-use InvalidArgumentException;
-use RuntimeException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\ValueObjects\MimeType;
 

src/Files/ValueObjects/MimeType.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Files\ValueObjects;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 
 /**
  * Value object representing a MIME type.

src/Messages/DTO/Message.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 
 /**
@@ -188,7 +188,7 @@ final public static function fromArray(array $array): self
             return new ModelMessage($parts);
         } else {
             // Only USER and MODEL roles are supported
-            throw new \InvalidArgumentException('Invalid message role: ' . $role->value);
+            throw new InvalidArgumentException('Invalid message role: ' . $role->value);
         }
     }
 }

src/Messages/DTO/MessagePart.php

@@ -4,9 +4,9 @@
 
 namespace WordPress\AiClient\Messages\DTO;
 
-use InvalidArgumentException;
-use RuntimeException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Files\DTO\File;
 use WordPress\AiClient\Messages\Enums\MessagePartChannelEnum;
 use WordPress\AiClient\Messages\Enums\MessagePartTypeEnum;

src/ProviderImplementations/Anthropic/AnthropicModelMetadataDirectory.php

@@ -4,13 +4,13 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Anthropic;
 
-use RuntimeException;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Providers\Http\Contracts\RequestAuthenticationInterface;
 use WordPress\AiClient\Providers\Http\DTO\ApiKeyRequestAuthentication;
 use WordPress\AiClient\Providers\Http\DTO\Request;
 use WordPress\AiClient\Providers\Http\DTO\Response;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
+use WordPress\AiClient\Providers\Http\Exception\ResponseException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 use WordPress\AiClient\Providers\Models\DTO\SupportedOption;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
@@ -71,9 +71,7 @@ protected function parseResponseToModelMetadataList(Response $response): array
         /** @var ModelsResponseData $responseData */
         $responseData = $response->getData();
         if (!isset($responseData['data']) || !$responseData['data']) {
-            throw new RuntimeException(
-                'Unexpected API response: Missing the data key.'
-            );
+            throw ResponseException::fromMissingData('Anthropic', 'data');
         }
 
         // Unfortunately, the Anthropic API does not return model capabilities, so we have to hardcode them here.

src/ProviderImplementations/Anthropic/AnthropicProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Anthropic;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/ProviderImplementations/Google/GoogleModelMetadataDirectory.php

@@ -4,7 +4,6 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Google;
 
-use RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
@@ -13,6 +12,7 @@
 use WordPress\AiClient\Providers\Http\DTO\Request;
 use WordPress\AiClient\Providers\Http\DTO\Response;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
+use WordPress\AiClient\Providers\Http\Exception\ResponseException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 use WordPress\AiClient\Providers\Models\DTO\SupportedOption;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
@@ -87,9 +87,7 @@ protected function parseResponseToModelMetadataList(Response $response): array
         /** @var ModelsResponseData $responseData */
         $responseData = $response->getData();
         if (!isset($responseData['models']) || !$responseData['models']) {
-            throw new RuntimeException(
-                'Unexpected API response: Missing the models key.'
-            );
+            throw ResponseException::fromMissingData('Google', 'models');
         }
 
         $geminiCapabilities = [

src/ProviderImplementations/Google/GoogleProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\Google;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/ProviderImplementations/OpenAi/OpenAiModelMetadataDirectory.php

@@ -4,13 +4,13 @@
 
 namespace WordPress\AiClient\ProviderImplementations\OpenAi;
 
-use RuntimeException;
 use WordPress\AiClient\Files\Enums\FileTypeEnum;
 use WordPress\AiClient\Files\Enums\MediaOrientationEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
 use WordPress\AiClient\Providers\Http\DTO\Request;
 use WordPress\AiClient\Providers\Http\DTO\Response;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
+use WordPress\AiClient\Providers\Http\Exception\ResponseException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 use WordPress\AiClient\Providers\Models\DTO\SupportedOption;
 use WordPress\AiClient\Providers\Models\Enums\CapabilityEnum;
@@ -53,9 +53,7 @@ protected function parseResponseToModelMetadataList(Response $response): array
         /** @var ModelsResponseData $responseData */
         $responseData = $response->getData();
         if (!isset($responseData['data']) || !$responseData['data']) {
-            throw new RuntimeException(
-                'Unexpected API response: Missing the data key.'
-            );
+            throw ResponseException::fromMissingData('OpenAI', 'data');
         }
 
         // Unfortunately, the OpenAI API does not return model capabilities, so we have to hardcode them here.

src/ProviderImplementations/OpenAi/OpenAiProvider.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\ProviderImplementations\OpenAi;
 
-use RuntimeException;
+use WordPress\AiClient\Common\Exception\RuntimeException;
 use WordPress\AiClient\Providers\AbstractProvider;
 use WordPress\AiClient\Providers\ApiBasedImplementation\ListModelsApiBasedProviderAvailability;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;

src/Providers/ApiBasedImplementation/AbstractApiBasedModelMetadataDirectory.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\ApiBasedImplementation;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Contracts\ModelMetadataDirectoryInterface;
 use WordPress\AiClient\Providers\Http\Contracts\WithHttpTransporterInterface;
 use WordPress\AiClient\Providers\Http\Contracts\WithRequestAuthenticationInterface;

src/Providers/Contracts/ModelMetadataDirectoryInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
 /**

src/Providers/Contracts/ProviderInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\DTO\ProviderMetadata;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;

src/Providers/Contracts/ProviderOperationsHandlerInterface.php

@@ -4,7 +4,7 @@
 
 namespace WordPress\AiClient\Providers\Contracts;
 
-use InvalidArgumentException;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Operations\Contracts\OperationInterface;
 
 /**

src/Providers/DTO/ProviderModelsMetadata.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Providers\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
 /**

src/Providers/Http/DTO/Request.php

@@ -4,9 +4,10 @@
 
 namespace WordPress\AiClient\Providers\Http\DTO;
 
-use InvalidArgumentException;
 use JsonException;
+use Psr\Http\Message\RequestInterface;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
 use WordPress\AiClient\Providers\Http\Enums\HttpMethodEnum;
 
@@ -355,4 +356,29 @@ public static function fromArray(array $array): self
             $array[self::KEY_BODY] ?? null
         );
     }
+
+    /**
+     * Creates a Request instance from a PSR-7 RequestInterface.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestInterface $psrRequest The PSR-7 request to convert.
+     * @return self A new Request instance.
+     * @throws InvalidArgumentException If the HTTP method is not supported.
+     */
+    public static function fromPsrRequest(RequestInterface $psrRequest): self
+    {
+        $method = HttpMethodEnum::from($psrRequest->getMethod());
+        $uri = (string) $psrRequest->getUri();
+
+        // Convert PSR-7 headers to array format expected by our constructor
+        /** @var array<string, list<string>> $headers */
+        $headers = $psrRequest->getHeaders();
+
+        // Get body content
+        $body = $psrRequest->getBody()->getContents();
+        $bodyOrData = !empty($body) ? $body : null;
+
+        return new self($method, $uri, $headers, $bodyOrData);
+    }
 }

src/Providers/Http/DTO/Response.php

@@ -4,8 +4,8 @@
 
 namespace WordPress\AiClient\Providers\Http\DTO;
 
-use InvalidArgumentException;
 use WordPress\AiClient\Common\AbstractDataTransferObject;
+use WordPress\AiClient\Common\Exception\InvalidArgumentException;
 use WordPress\AiClient\Providers\Http\Collections\HeadersCollection;
 
 /**