Merge branch 'trunk' into feature/exception-hierarchy

Author: felixarntz

.gitignore

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

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

@@ -11,6 +11,7 @@
 use WordPress\AiClient\ProviderImplementations\Google\GoogleProvider;
 use WordPress\AiClient\ProviderImplementations\OpenAi\OpenAiProvider;
 use WordPress\AiClient\Providers\Contracts\ProviderAvailabilityInterface;
+use WordPress\AiClient\Providers\Contracts\ProviderInterface;
 use WordPress\AiClient\Providers\Http\HttpTransporterFactory;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
@@ -116,14 +117,43 @@ public static function defaultRegistry(): ProviderRegistry
     /**
      * Checks if a provider is configured and available for use.
      *
+     * Supports multiple input formats for developer convenience:
+     * - ProviderAvailabilityInterface: Direct availability check
+     * - string (provider ID): e.g., AiClient::isConfigured('openai')
+     * - string (class name): e.g., AiClient::isConfigured(OpenAiProvider::class)
+     *
+     * When using string input, this method leverages the ProviderRegistry's centralized
+     * dependency management, ensuring HttpTransporter and authentication are properly
+     * injected into availability instances.
+     *
      * @since 0.1.0
+     * @since n.e.x.t Now supports being passed a provider ID or class name.
      *
-     * @param ProviderAvailabilityInterface $availability The provider availability instance to check.
+     * @param ProviderAvailabilityInterface|string|class-string<ProviderInterface> $availabilityOrIdOrClassName
+     *        The provider availability instance, provider ID, or provider class name.
      * @return bool True if the provider is configured and available, false otherwise.
      */
-    public static function isConfigured(ProviderAvailabilityInterface $availability): bool
+    public static function isConfigured($availabilityOrIdOrClassName): bool
     {
-        return $availability->isConfigured();
+        // Handle direct ProviderAvailabilityInterface (backward compatibility)
+        if ($availabilityOrIdOrClassName instanceof ProviderAvailabilityInterface) {
+            return $availabilityOrIdOrClassName->isConfigured();
+        }
+
+        // Handle string input (provider ID or class name) via registry
+        if (is_string($availabilityOrIdOrClassName)) {
+            return self::defaultRegistry()->isProviderConfigured($availabilityOrIdOrClassName);
+        }
+
+        throw new \InvalidArgumentException(
+            'Parameter must be a ProviderAvailabilityInterface instance, provider ID string, or provider class name. ' .
+            sprintf(
+                'Received: %s',
+                is_object($availabilityOrIdOrClassName)
+                    ? get_class($availabilityOrIdOrClassName)
+                    : gettype($availabilityOrIdOrClassName)
+            )
+        );
     }
 
     /**

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleImageGenerationModel.php

@@ -24,7 +24,11 @@
 use WordPress\AiClient\Results\Enums\FinishReasonEnum;
 
 /**
- * Base class for an image generation model for an OpenAI compatible provider.
+ * Base class for an image generation model for providers that implement OpenAI's API format.
+ *
+ * This abstract class is designed to work with any AI provider that offers an OpenAI-compatible
+ * API endpoint for image generation, including but not limited to Anthropic, Google, and other
+ * providers that have adopted OpenAI's image generation API specification as a standard interface.
  *
  * @since 0.1.0
  *

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleModelMetadataDirectory.php

@@ -13,7 +13,11 @@
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
 /**
- * Base class for a model metadata directory for an OpenAI compatible provider.
+ * Base class for a model metadata directory for providers that implement OpenAI's API format.
+ *
+ * This abstract class is designed to work with any AI provider that offers an OpenAI-compatible
+ * models listing endpoint, including but not limited to Anthropic, Google, and other
+ * providers that have adopted OpenAI's models API specification as a standard interface.
  *
  * @since 0.1.0
  */

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php

@@ -27,7 +27,11 @@
 use WordPress\AiClient\Tools\DTO\FunctionDeclaration;
 
 /**
- * Base class for a text generation model for an OpenAI compatible provider.
+ * Base class for a text generation model for providers that implement OpenAI's API format.
+ *
+ * This abstract class is designed to work with any AI provider that offers an OpenAI-compatible
+ * API endpoint, including but not limited to Anthropic, Google, and other providers
+ * that have adopted OpenAI's API specification as a standard interface.
  *
  * @since 0.1.0
  *

src/Results/DTO/GenerativeAiResult.php

@@ -201,6 +201,8 @@ public function hasMultipleCandidates(): bool
     /**
      * Converts the first candidate to text.
      *
+     * Only text from the content channel is considered. Text within model thought or reasoning is ignored.
+     *
      * @since 0.1.0
      *
      * @return string The text content.
@@ -210,8 +212,9 @@ public function toText(): string
     {
         $message = $this->candidates[0]->getMessage();
         foreach ($message->getParts() as $part) {
+            $channel = $part->getChannel();
             $text = $part->getText();
-            if ($text !== null) {
+            if ($channel->isContent() && $text !== null) {
                 return $text;
             }
         }
@@ -222,6 +225,8 @@ public function toText(): string
     /**
      * Converts the first candidate to a file.
      *
+     * Only files from the content channel are considered. Files within model thought or reasoning are ignored.
+     *
      * @since 0.1.0
      *
      * @return File The file.
@@ -231,8 +236,9 @@ public function toFile(): File
     {
         $message = $this->candidates[0]->getMessage();
         foreach ($message->getParts() as $part) {
+            $channel = $part->getChannel();
             $file = $part->getFile();
-            if ($file !== null) {
+            if ($channel->isContent() && $file !== null) {
                 return $file;
             }
         }
@@ -316,7 +322,7 @@ public function toMessage(): Message
     }
 
     /**
-     * Converts all candidates to text array.
+     * Converts all candidates to text.
      *
      * @since 0.1.0
      *
@@ -328,8 +334,9 @@ public function toTexts(): array
         foreach ($this->candidates as $candidate) {
             $message = $candidate->getMessage();
             foreach ($message->getParts() as $part) {
+                $channel = $part->getChannel();
                 $text = $part->getText();
-                if ($text !== null) {
+                if ($channel->isContent() && $text !== null) {
                     $texts[] = $text;
                     break;
                 }
@@ -351,8 +358,9 @@ public function toFiles(): array
         foreach ($this->candidates as $candidate) {
             $message = $candidate->getMessage();
             foreach ($message->getParts() as $part) {
+                $channel = $part->getChannel();
                 $file = $part->getFile();
-                if ($file !== null) {
+                if ($channel->isContent() && $file !== null) {
                     $files[] = $file;
                     break;
                 }

tests/unit/AiClientTest.php

@@ -9,6 +9,7 @@
 use WordPress\AiClient\AiClient;
 use WordPress\AiClient\Messages\DTO\MessagePart;
 use WordPress\AiClient\Messages\DTO\UserMessage;
+use WordPress\AiClient\ProviderImplementations\OpenAi\OpenAiProvider;
 use WordPress\AiClient\Providers\Contracts\ProviderAvailabilityInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
 use WordPress\AiClient\Providers\ProviderRegistry;
@@ -246,6 +247,115 @@ public function testIsConfiguredReturnsFalseWhenProviderIsNotConfigured(): void
         $this->assertFalse($result);
     }
 
+    /**
+     * Tests isConfigured method with provider ID string leverages default registry.
+     */
+    public function testIsConfiguredWithProviderIdString(): void
+    {
+        // This test will use the actual default registry since we can't easily mock static methods
+        // The default registry should have providers registered, so we test the delegation path
+        $result = AiClient::isConfigured('openai');
+
+        // The result will be false because no actual API keys are configured in tests,
+        // but the important thing is that no exception is thrown and the registry delegation works
+        $this->assertIsBool($result);
+    }
+
+    /**
+     * Tests isConfigured method with provider class name leverages default registry.
+     */
+    public function testIsConfiguredWithProviderClassName(): void
+    {
+        // This test will use the actual default registry since we can't easily mock static methods
+        // The default registry should have providers registered, so we test the delegation path
+        $result = AiClient::isConfigured(OpenAiProvider::class);
+
+        // The result will be false because no actual API keys are configured in tests,
+        // but the important thing is that no exception is thrown and the registry delegation works
+        $this->assertIsBool($result);
+    }
+
+    /**
+     * Tests isConfigured method throws exception for invalid parameter types.
+     */
+    public function testIsConfiguredThrowsExceptionForInvalidParameterTypes(): void
+    {
+        $this->expectException(\InvalidArgumentException::class);
+        $this->expectExceptionMessage(
+            'Parameter must be a ProviderAvailabilityInterface instance, provider ID string, or provider class name. ' .
+            'Received: integer'
+        );
+
+        AiClient::isConfigured(123);
+    }
+
+    /**
+     * Data provider for invalid isConfigured parameter types.
+     *
+     * @return array<string, array{mixed, string}>
+     */
+    public function invalidIsConfiguredParameterTypesProvider(): array
+    {
+        return [
+            'integer parameter' => [123, 'integer'],
+            'array parameter' => [['invalid_array'], 'array'],
+            'object parameter' => [new \stdClass(), 'stdClass'],
+            'boolean parameter' => [true, 'boolean'],
+            'null parameter' => [null, 'NULL'],
+        ];
+    }
+
+    /**
+     * Tests that isConfigured rejects all invalid parameter types consistently.
+     *
+     * @dataProvider invalidIsConfiguredParameterTypesProvider
+     * @param mixed $invalidParam
+     */
+    public function testIsConfiguredRejectsInvalidParameterTypes($invalidParam, string $expectedType): void
+    {
+        try {
+            AiClient::isConfigured($invalidParam);
+            $this->fail("Expected InvalidArgumentException for isConfigured with $expectedType");
+        } catch (\InvalidArgumentException $e) {
+            $this->assertStringContainsString(
+                'Parameter must be a ProviderAvailabilityInterface instance, provider ID string, ' .
+                'or provider class name.',
+                $e->getMessage(),
+                "isConfigured should reject invalid parameter type: $expectedType"
+            );
+            $this->assertStringContainsString(
+                "Received: $expectedType",
+                $e->getMessage(),
+                "isConfigured should include received type in error message"
+            );
+        }
+    }
+
+    /**
+     * Tests backward compatibility - isConfigured still works with ProviderAvailabilityInterface.
+     */
+    public function testIsConfiguredBackwardCompatibility(): void
+    {
+        // Test that the original interface-based approach still works exactly as before
+        $mockAvailability = $this->createMock(ProviderAvailabilityInterface::class);
+        $mockAvailability->expects($this->once())
+            ->method('isConfigured')
+            ->willReturn(true);
+
+        // Should work without registry parameter
+        $result = AiClient::isConfigured($mockAvailability);
+        $this->assertTrue($result);
+
+        // Should work in all cases with interface input
+        $mockAvailability2 = $this->createMock(ProviderAvailabilityInterface::class);
+        $mockAvailability2->expects($this->once())
+            ->method('isConfigured')
+            ->willReturn(false);
+
+        $result2 = AiClient::isConfigured($mockAvailability2);
+        $this->assertFalse($result2);
+    }
+
     /**
      * Tests generateResult delegates to generateTextResult when model supports text generation.
      */

tests/unit/Providers/OpenAiCompatibleImplementation/MockOpenAiCompatibleTextGenerationModel.php

@@ -113,9 +113,9 @@ public function exposePrepareGenerateTextParams(array $prompt): array
         return $this->prepareGenerateTextParams($prompt);
     }
 
-    public function exposeMergeSystemInstruction(array $prompt, string $systemInstruction): array
+    public function exposePrepareMessagesParamWithSystemInstruction(array $prompt, string $systemInstruction): array
     {
-        return $this->mergeSystemInstruction($prompt, $systemInstruction);
+        return $this->prepareMessagesParam($prompt, $systemInstruction);
     }
 
     public function exposePrepareMessagesParam(array $messages): array