Provider base and implementation for Anthropic, Google, and OpenAI via common abstractions

.gitattributes

@@ -2,6 +2,7 @@
 .gitattributes         export-ignore
 /.github/              export-ignore
 .gitignore             export-ignore
+/cli.php               export-ignore
 /*.md                  export-ignore
 /LICENSE.md           -export-ignore
 /README.md            -export-ignore

cli.php

@@ -0,0 +1,181 @@
+<?php
+/**
+ * CLI script for interacting with the AI client.
+ *
+ * This script allows users to send prompts to the AI and receive responses.
+ * It supports named arguments for provider and model selection.
+ *
+ * Usage:
+ *   GOOGLE_API_KEY=123456 php cli.php 'Your prompt here' --providerId=google --modelId=gemini-2.5-flash
+ *   OPENAI_API_KEY=123456 php cli.php 'Your prompt here' --providerId=openai
+ *   GOOGLE_API_KEY=123456 OPENAI_API_KEY=123456 php cli.php 'Your prompt here'
+ */
+
+declare(strict_types=1);
+
+use WordPress\AiClient\AiClient;
+use WordPress\AiClient\Providers\Http\Exception\ResponseException;
+use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
+
+require_once __DIR__ . '/vendor/autoload.php';
+
+/**
+ * Prints the output to stdout.
+ *
+ * @param string $output The output to print.
+ */
+function printOutput(string $output): void
+{
+    echo $output . PHP_EOL;
+}
+
+/**
+ * Logs an informational message to stderr.
+ *
+ * @param string $message The message to log.
+ */
+function logInfo(string $message): void
+{
+    fwrite(STDERR, '[INFO] ' . $message . PHP_EOL);
+}
+
+/**
+ * Logs a warning message to stderr.
+ *
+ * @param string $message The message to log.
+ */
+function logWarning(string $message): void
+{
+    fwrite(STDERR, '[WARNING] ' . $message . PHP_EOL);
+}
+
+/**
+ * Logs an error message to stderr and terminates the script.
+ *
+ * @param string $message The message to log.
+ * @param int    $exit_code The exit code to use.
+ */
+function logError(string $message, int $exit_code = 1): void
+{
+    fwrite(STDERR, '[ERROR] ' . $message . PHP_EOL);
+    exit($exit_code);
+}
+
+// --- Argument parsing ---
+
+$positional_args = [];
+$named_args      = [];
+
+for ($i = 1; $i < $argc; $i++) {
+    $arg = $argv[$i];
+    if (str_starts_with($arg, '--')) {
+        $parts = explode('=', substr($arg, 2), 2);
+        $key   = $parts[0];
+        $value = $parts[1] ?? true;
+        if (empty($key)) {
+            logWarning("Ignoring invalid named argument: {$arg}");
+            continue;
+        }
+        $named_args[$key] = $value;
+    } else {
+        $positional_args[] = $arg;
+    }
+}
+
+// --- Input validation ---
+
+if (empty($positional_args[0])) {
+    logError('Missing required positional argument "prompt input".');
+}
+
+// Prompt input. Allow complex input as a JSON string.
+$promptInput = $positional_args[0];
+if (strpos($promptInput, '{') === 0 || strpos($promptInput, '[') === 0) {
+    $decodedInput = json_decode($promptInput, true);
+    if ($decodedInput) {
+        $promptInput = $decodedInput;
+    }
+}
+
+// Provider ID, model ID, and output format.
+$providerId = $named_args['providerId'] ?? null;
+$modelId = $named_args['modelId'] ?? null;
+$outputFormat = $named_args['outputFormat'] ?? 'message-text';
+
+// Any model configuration options.
+$schema = ModelConfig::getJsonSchema()['properties'];
+$model_config_data = [];
+foreach ($named_args as $key => $value) {
+    if (!isset($schema[$key])) {
+        continue;
+    }
+
+    $property_schema = $schema[$key];
+    $type = $property_schema['type'] ?? null;
+
+    $processed_value = $value;
+    if ($type === 'array' || $type === 'object') {
+        $decoded = json_decode((string) $value, true);
+        if (json_last_error() !== JSON_ERROR_NONE) {
+            logWarning("Invalid JSON for argument --{$key}: " . json_last_error_msg());
+            continue;
+        }
+        $processed_value = $decoded;
+    } elseif ($type === 'integer') {
+        $processed_value = (int) $value;
+    } elseif ($type === 'number') {
+        $processed_value = (float) $value;
+    } elseif ($type === 'boolean') {
+        $processed_value = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
+        if (null === $processed_value) {
+            logWarning("Invalid boolean for argument --{$key}: {$value}");
+            continue;
+        }
+    }
+
+    $model_config_data[$key] = $processed_value;
+}
+
+// --- Main logic ---
+
+try {
+    $modelConfig = ModelConfig::fromArray($model_config_data);
+
+    $promptBuilder = AiClient::prompt($promptInput);
+    $promptBuilder = $promptBuilder->usingModelConfig($modelConfig);
+    if ($providerId && $modelId) {
+        $providerClassName = AiClient::defaultRegistry()->getProviderClassName($providerId);
+        $promptBuilder = $promptBuilder->usingModel($providerClassName::model($modelId));
+    } elseif ($providerId) {
+        $promptBuilder = $promptBuilder->usingProvider($providerId);
+    }
+} catch (InvalidArgumentException $e) {
+    logError('Invalid arguments while trying to set up prompt builder: ' . $e->getMessage());
+} catch (ResponseException $e) {
+    logError('Request failed while trying to set up prompt builder: ' . $e->getMessage());
+}
+
+try {
+    $result = $promptBuilder->generateTextResult();
+} catch (InvalidArgumentException $e) {
+    logError('Invalid arguments while trying to generate text result: ' . $e->getMessage());
+} catch (ResponseException $e) {
+    logError('Request failed while trying to generate text result: ' . $e->getMessage());
+}
+
+logInfo("Using provider ID: \"{$result->getProviderMetadata()->getId()}\"");
+logInfo("Using model ID: \"{$result->getModelMetadata()->getId()}\"");
+
+switch ($outputFormat) {
+    case 'result-json':
+        $output = json_encode($result, JSON_PRETTY_PRINT);
+        break;
+    case 'candidates-json':
+        $output = json_encode($result->getCandidates(), JSON_PRETTY_PRINT);
+        break;
+    case 'message-text':
+    default:
+        $output = $result->toText();
+}
+
+printOutput($output);

docs/ARCHITECTURE.md

@@ -893,7 +893,7 @@ direction LR
             +send(Request $request) Response
         }
         class RequestAuthenticationInterface {
-            +authenticate(Request $request) void
+            +authenticateRequest(Request $request) Request
             +getJsonSchema() array< string, mixed >$
         }
         class WithHttpTransporterInterface {

src/AiClient.php

@@ -5,7 +5,11 @@
 namespace WordPress\AiClient;
 
 use WordPress\AiClient\Builders\PromptBuilder;
+use WordPress\AiClient\ProviderImplementations\Anthropic\AnthropicProvider;
+use WordPress\AiClient\ProviderImplementations\Google\GoogleProvider;
+use WordPress\AiClient\ProviderImplementations\OpenAi\OpenAiProvider;
 use WordPress\AiClient\Providers\Contracts\ProviderAvailabilityInterface;
+use WordPress\AiClient\Providers\Http\HttpTransporterFactory;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
 use WordPress\AiClient\Providers\ProviderRegistry;
@@ -95,12 +99,11 @@ public static function defaultRegistry(): ProviderRegistry
         if (self::$defaultRegistry === null) {
             $registry = new ProviderRegistry();
 
-            // Provider registration will be enabled once concrete provider implementations are available.
-            // This follows the pattern established in the provider registry architecture.
-            //$registry->setHttpTransporter(HttpTransporterFactory::createTransporter());
-            //$registry->registerProvider(AnthropicProvider::class);
-            //$registry->registerProvider(GoogleProvider::class);
-            //$registry->registerProvider(OpenAiProvider::class);
+            // Set up default HTTP transporter and register built-in providers.
+            $registry->setHttpTransporter(HttpTransporterFactory::createTransporter());
+            $registry->registerProvider(AnthropicProvider::class);
+            $registry->registerProvider(GoogleProvider::class);
+            $registry->registerProvider(OpenAiProvider::class);
 
             self::$defaultRegistry = $registry;
         }

src/Builders/PromptBuilder.php

@@ -191,6 +191,9 @@ public function withHistory(Message ...$messages): self
     /**
      * Sets the model to use for generation.
      *
+     * The model's configuration will be merged with the builder's configuration,
+     * with the builder's configuration taking precedence for any overlapping settings.
+     *
      * @since n.e.x.t
      *
      * @param ModelInterface $model The model to use.
@@ -199,6 +202,14 @@ public function withHistory(Message ...$messages): self
     public function usingModel(ModelInterface $model): self
     {
         $this->model = $model;
+
+        // Merge model's config with builder's config, with builder's config taking precedence
+        $modelConfigArray = $model->getConfig()->toArray();
+        $builderConfigArray = $this->modelConfig->toArray();
+        $mergedConfigArray = array_merge($modelConfigArray, $builderConfigArray);
+
+        $this->modelConfig = ModelConfig::fromArray($mergedConfigArray);
+
         return $this;
     }
 
@@ -1009,6 +1020,7 @@ private function getConfiguredModel(CapabilityEnum $capability): ModelInterface
         // If a model has been explicitly set, return it
         if ($this->model !== null) {
             $this->model->setConfig($this->modelConfig);
+            $this->registry->bindModelDependencies($this->model);
             return $this->model;
         }
 

src/Common/AbstractEnum.php

@@ -6,6 +6,7 @@
 
 use BadMethodCallException;
 use InvalidArgumentException;
+use JsonSerializable;
 use ReflectionClass;
 use RuntimeException;
 
@@ -36,7 +37,7 @@
  *
  * @since n.e.x.t
  */
-abstract class AbstractEnum
+abstract class AbstractEnum implements JsonSerializable
 {
     /**
      * @var string The value of the enum instance.
@@ -393,4 +394,17 @@ final public function __toString(): string
     {
         return $this->value;
     }
+
+    /**
+     * Converts the enum to a JSON-serializable format.
+     *
+     * @since n.e.x.t
+     *
+     * @return string The enum value.
+     */
+    #[\ReturnTypeWillChange]
+    public function jsonSerialize()
+    {
+        return $this->value;
+    }
 }

src/Files/ValueObjects/MimeType.php

@@ -72,6 +72,7 @@ final class MimeType
         'ogg' => 'audio/ogg',
         'flac' => 'audio/flac',
         'm4a' => 'audio/m4a',
+        'aac' => 'audio/aac',
 
         // Video
         'mp4' => 'video/mp4',
@@ -130,6 +131,27 @@ public function __construct(string $value)
         $this->value = strtolower($value);
     }
 
+    /**
+     * Gets the primary known file extension for this MIME type.
+     *
+     * @since n.e.x.t
+     *
+     * @return string The file extension (without the dot).
+     * @throws InvalidArgumentException If no known extension exists for this MIME type.
+     */
+    public function toExtension(): string
+    {
+        // Reverse lookup for the MIME type to find the extension.
+        $extension = array_search($this->value, self::$extensionMap, true);
+        if ($extension === false) {
+            throw new InvalidArgumentException(
+                sprintf('No known extension for MIME type: %s', $this->value)
+            );
+        }
+
+        return $extension;
+    }
+
     /**
      * Creates a MimeType from a file extension.
      *

src/ProviderImplementations/Anthropic/AnthropicApiKeyRequestAuthentication.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\ProviderImplementations\Anthropic;
+
+use WordPress\AiClient\Providers\Http\DTO\ApiKeyRequestAuthentication;
+use WordPress\AiClient\Providers\Http\DTO\Request;
+
+/**
+ * Class for HTTP request authentication using an API key in a Anthropic API compliant way.
+ *
+ * @since n.e.x.t
+ */
+class AnthropicApiKeyRequestAuthentication extends ApiKeyRequestAuthentication
+{
+    public const ANTHROPIC_API_VERSION = '2023-06-01';
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    public function authenticateRequest(Request $request): Request
+    {
+        // Anthropic requires this header to be set for all requests.
+        $request = $request->withHeader('anthropic-version', self::ANTHROPIC_API_VERSION);
+
+        // Add the API key to the request headers.
+        return $request->withHeader('x-api-key', $this->apiKey);
+    }
+}