Prompt Builder can set model request options

src/Builders/PromptBuilder.php

@@ -13,6 +13,8 @@
 use WordPress\AiClient\Messages\DTO\UserMessage;
 use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
 use WordPress\AiClient\Messages\Enums\ModalityEnum;
+use WordPress\AiClient\Providers\ApiBasedImplementation\Contracts\ApiBasedModelInterface;
+use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
 use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
@@ -75,6 +77,11 @@ class PromptBuilder
      */
     protected ModelConfig $modelConfig;
 
+    /**
+     * @var RequestOptions|null The request options for HTTP transport.
+     */
+    protected ?RequestOptions $requestOptions = null;
+
     // phpcs:disable Generic.Files.LineLength.TooLong
     /**
      * Constructor.
@@ -482,6 +489,20 @@ public function usingWebSearch(WebSearch $webSearch): self
         return $this;
     }
 
+    /**
+     * Sets the request options for HTTP transport.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestOptions $requestOptions The request options.
+     * @return self
+     */
+    public function usingRequestOptions(RequestOptions $requestOptions): self
+    {
+        $this->requestOptions = $requestOptions;
+        return $this;
+    }
+
     /**
      * Sets the top log probabilities configuration.
      *
@@ -1112,9 +1133,11 @@ private function getConfiguredModel(CapabilityEnum $capability): ModelInterface
 
         if ($this->model !== null) {
             // Explicit model was provided via usingModel(); just update config and bind dependencies.
-            $this->model->setConfig($this->modelConfig);
-            $this->registry->bindModelDependencies($this->model);
-            return $this->model;
+            $model = $this->model;
+            $model->setConfig($this->modelConfig);
+            $this->registry->bindModelDependencies($model);
+            $this->bindModelRequestOptions($model);
+            return $model;
         }
 
         // Retrieve the candidate models map which satisfies the requirements.
@@ -1150,14 +1173,35 @@ private function getConfiguredModel(CapabilityEnum $capability): ModelInterface
                 $firstMatchKey = key($matchingPreferences);
                 [$providerId, $modelId] = $candidateMap[$firstMatchKey];
 
-                return $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig);
+                $model = $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig);
+                $this->bindModelRequestOptions($model);
+                return $model;
             }
         }
 
         // No preference matched; fall back to the first candidate discovered.
         [$providerId, $modelId] = reset($candidateMap);
 
-        return $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig);
+        $model = $this->registry->getProviderModel($providerId, $modelId, $this->modelConfig);
+        $this->bindModelRequestOptions($model);
+        return $model;
+    }
+
+    /**
+     * Binds configured request options to the model if present and supported.
+     *
+     * Request options are only applicable to API-based models that make HTTP requests.
+     *
+     * @since n.e.x.t
+     *
+     * @param ModelInterface $model The model to bind request options to.
+     * @return void
+     */
+    private function bindModelRequestOptions(ModelInterface $model): void
+    {
+        if ($this->requestOptions !== null && $model instanceof ApiBasedModelInterface) {
+            $model->setRequestOptions($this->requestOptions);
+        }
     }
 
     /**

src/ProviderImplementations/Anthropic/AnthropicTextGenerationModel.php

@@ -26,7 +26,8 @@ protected function createRequest(HttpMethodEnum $method, string $path, array $he
             $method,
             AnthropicProvider::url($path),
             $headers,
-            $data
+            $data,
+            $this->getRequestOptions()
         );
     }
 }

src/ProviderImplementations/Google/GoogleImageGenerationModel.php

@@ -24,7 +24,8 @@ protected function createRequest(HttpMethodEnum $method, string $path, array $he
             $method,
             GoogleProvider::url('openai/' . ltrim($path, '/')),
             $headers,
-            $data
+            $data,
+            $this->getRequestOptions()
         );
     }
 }

src/ProviderImplementations/Google/GoogleTextGenerationModel.php

@@ -26,7 +26,8 @@ protected function createRequest(HttpMethodEnum $method, string $path, array $he
             $method,
             GoogleProvider::url('openai/' . ltrim($path, '/')),
             $headers,
-            $data
+            $data,
+            $this->getRequestOptions()
         );
     }
 }

src/ProviderImplementations/OpenAi/OpenAiImageGenerationModel.php

@@ -24,7 +24,8 @@ protected function createRequest(HttpMethodEnum $method, string $path, array $he
             $method,
             OpenAiProvider::url($path),
             $headers,
-            $data
+            $data,
+            $this->getRequestOptions()
         );
     }
 

src/ProviderImplementations/OpenAi/OpenAiTextGenerationModel.php

@@ -26,7 +26,8 @@ protected function createRequest(HttpMethodEnum $method, string $path, array $he
             $method,
             OpenAiProvider::url($path),
             $headers,
-            $data
+            $data,
+            $this->getRequestOptions()
         );
     }
 }

src/Providers/ApiBasedImplementation/AbstractApiBasedModel.php

@@ -4,12 +4,13 @@
 
 namespace WordPress\AiClient\Providers\ApiBasedImplementation;
 
+use WordPress\AiClient\Providers\ApiBasedImplementation\Contracts\ApiBasedModelInterface;
 use WordPress\AiClient\Providers\DTO\ProviderMetadata;
 use WordPress\AiClient\Providers\Http\Contracts\WithHttpTransporterInterface;
 use WordPress\AiClient\Providers\Http\Contracts\WithRequestAuthenticationInterface;
+use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
 use WordPress\AiClient\Providers\Http\Traits\WithHttpTransporterTrait;
 use WordPress\AiClient\Providers\Http\Traits\WithRequestAuthenticationTrait;
-use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
 use WordPress\AiClient\Providers\Models\DTO\ModelConfig;
 use WordPress\AiClient\Providers\Models\DTO\ModelMetadata;
 
@@ -22,7 +23,7 @@
  * @since 0.1.0
  */
 abstract class AbstractApiBasedModel implements
-    ModelInterface,
+    ApiBasedModelInterface,
     WithHttpTransporterInterface,
     WithRequestAuthenticationInterface
 {
@@ -44,6 +45,11 @@ abstract class AbstractApiBasedModel implements
      */
     private ModelConfig $config;
 
+    /**
+     * @var RequestOptions|null The request options for HTTP transport.
+     */
+    private ?RequestOptions $requestOptions = null;
+
     /**
      * Constructor.
      *
@@ -98,4 +104,24 @@ final public function getConfig(): ModelConfig
     {
         return $this->config;
     }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    final public function setRequestOptions(RequestOptions $requestOptions): void
+    {
+        $this->requestOptions = $requestOptions;
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @since n.e.x.t
+     */
+    final public function getRequestOptions(): ?RequestOptions
+    {
+        return $this->requestOptions;
+    }
 }

src/Providers/ApiBasedImplementation/Contracts/ApiBasedModelInterface.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace WordPress\AiClient\Providers\ApiBasedImplementation\Contracts;
+
+use WordPress\AiClient\Providers\Http\DTO\RequestOptions;
+use WordPress\AiClient\Providers\Models\Contracts\ModelInterface;
+
+/**
+ * Interface for API-based AI models that support HTTP transport configuration.
+ *
+ * This interface extends ModelInterface to add request options support
+ * for models that communicate with external APIs via HTTP.
+ *
+ * @since n.e.x.t
+ */
+interface ApiBasedModelInterface extends ModelInterface
+{
+    /**
+     * Sets the request options for HTTP transport.
+     *
+     * @since n.e.x.t
+     *
+     * @param RequestOptions $requestOptions The request options to use.
+     * @return void
+     */
+    public function setRequestOptions(RequestOptions $requestOptions): void;
+
+    /**
+     * Gets the request options for HTTP transport.
+     *
+     * @since n.e.x.t
+     *
+     * @return RequestOptions|null The request options, or null if not set.
+     */
+    public function getRequestOptions(): ?RequestOptions;
+}

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleImageGenerationModel.php

@@ -249,6 +249,9 @@ protected function prepareSizeParam(?MediaOrientationEnum $orientation, ?string
     /**
      * Creates a request object for the provider's API.
      *
+     * Implementations should use $this->getRequestOptions() to attach any
+     * configured request options to the Request.
+     *
      * @since 0.1.0
      *
      * @param HttpMethodEnum $method The HTTP method.

src/Providers/OpenAiCompatibleImplementation/AbstractOpenAiCompatibleTextGenerationModel.php

@@ -536,6 +536,9 @@ protected function prepareResponseFormatParam(?array $outputSchema): array
     /**
      * Creates a request object for the provider's API.
      *
+     * Implementations should use $this->getRequestOptions() to attach any
+     * configured request options to the Request.
+     *
      * @since 0.1.0
      *
      * @param HttpMethodEnum $method The HTTP method.

tests/mocks/MockOpenAiCompatibleImageGenerationModel.php

@@ -26,7 +26,7 @@ protected function createRequest(
         array $headers = [],
         $data = null
     ): Request {
-        return new Request($method, $path, $headers, $data);
+        return new Request($method, $path, $headers, $data, $this->getRequestOptions());
     }
 
     /**

tests/unit/Providers/OpenAiCompatibleImplementation/MockOpenAiCompatibleTextGenerationModel.php

@@ -82,7 +82,7 @@ protected function createRequest(
         array $headers = [],
         $data = null
     ): Request {
-        return new Request($method, 'https://example.com/' . $path, $headers, $data);
+        return new Request($method, 'https://example.com/' . $path, $headers, $data, $this->getRequestOptions());
     }
 
     /**