Merge branch 'trunk' into explore/alternative-agents

Author: felixarntz

.gitignore

@@ -25,9 +25,13 @@ vendor/
 ############
 
 .claude/
-CLAUDE.md
+.clinerules
 .clinerules/
+.codex/
 .cursor/
+.gemini/
+.windsurf/
+CLAUDE.md
 GEMINI.md
 
 ############

AGENTS.md

@@ -68,6 +68,8 @@ For a more detailed overview, refer to the `docs/ARCHITECTURE.md` file.
 
 ## Agent Guidelines
 
+### Naming conventions
+
 ### DO:
 
 *   **Read the Docs:** Before making any changes, thoroughly read `CONTRIBUTING.md` and `docs/ARCHITECTURE.md`.
@@ -83,6 +85,15 @@ For a more detailed overview, refer to the `docs/ARCHITECTURE.md` file.
 *   **Introduce Out-of-Scope Features:** Do not add features that are out of scope for this project, such as agents or the Model Context Protocol (MCP), as noted in `docs/REQUIREMENTS.md`.
 *   **Duplicate Documentation:** Avoid duplicating PHPDoc descriptions for methods that implement an interface.
 
+### 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
+
 ## Common Pitfalls
 
 *   **Direct HTTP Client Usage:** A common mistake is to instantiate a PSR-18 client directly in a model. This is incorrect. Instead, the model should receive an `HttpTransporter` instance and use it to send requests.

docs/REQUIREMENTS.md

@@ -4,15 +4,15 @@ This document outlines the functional requirements for the PHP AI Client, as wel
 
 ## Target Audiences
 
-There are two primary developer audiences this client is intended for. This is important to understand as it significantly influences the thinking and complexity around the APIs introduced in this library.a
+There are two primary developer audiences this client is intended for. This is important to understand as it significantly influences the thinking and complexity around the APIs introduced in this library.
 
 ### Extenders
 
 Extenders are the folks that will be adding providers, models, and otherwise extending the functionality of the client itself. These are highly technical people who likely have a stronger understanding of how models and model APIs work. Given their capabilities, these APIs will be more technical and formal in nature, using things such as interfaces, traits, and so forth, relying on a knowledge of inheritance and composition.
 
 ### Implementers
 
-Implementors are the folks that will be utilizing the client to take advantage of AI features. These developers know their own codebase well, but their technical and model knowledge varies. It is important not to rely on this knowledge for them to get significant value from the client. The APIs for these people will be simpler, straightforward, readable, and composable, so they can interact with the model with only what they need to know in mind.
+Implementers are the folks that will be utilizing the client to take advantage of AI features. These developers know their own codebase well, but their technical and model knowledge varies. It is important not to rely on this knowledge for them to get significant value from the client. The APIs for these people will be simpler, straightforward, readable, and composable, so they can interact with the model with only what they need to know in mind.
 
 ## Objective
 

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
+{
+}