Add fluent API code examples to architecture documentation

This proposed set of changes to #2 and is doing a few things:

1. Adding Fluent API code examples (similar to those suggested by @JasonTheAdams [here](#2 (comment))) alongside the Traditional API examples.
2. Proposing a handful of helper methods to simplify the usage of Candidate Count and avoid implementers from needing to understand what _Candidate Count_ means.
3. Representing @JasonTheAdams' suggestion of `AiClient::withImage(string $mimeType, string $base64Blob)` to mimic the input simplicity that the Traditional API supports.
4. Adding the `AiClient::asJsonResponse()` and `AiClient::asArrayResponse()` as a helper methods for `usingOutputMime('application/json')`
5. Adding helper methods for specifying models that support a certain capability or option.

Author: borkweb

docs/ARCHITECTURE.md

@@ -19,6 +19,13 @@ The following examples indicate how this SDK could eventually be used.
 
 #### Generate text using any suitable model from any provider (most basic example)
 
+##### Fluent API
+```php
+$text = AiClient::prompt('Write a 2-verse poem about PHP.')
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $text = AiClient::generateTextResult(
     'Write a 2-verse poem about PHP.'
@@ -27,6 +34,14 @@ $text = AiClient::generateTextResult(
 
 #### Generate text using a Google model
 
+##### Fluent API
+```php
+$text = AiClient::prompt('Write a 2-verse poem about PHP.')
+    ->usingModel('gemini-2.5-flash')
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $text = AiClient::generateTextResult(
     'Write a 2-verse poem about PHP.',
@@ -36,6 +51,14 @@ $text = AiClient::generateTextResult(
 
 #### Generate multiple text candidates using an Anthropic model
 
+##### Fluent API
+```php
+$texts = AiClient::prompt('Write a 2-verse poem about PHP.')
+    ->usingModel('claude-3.7-sonnet')
+    ->generateTexts(4);
+```
+
+##### Traditional API
 ```php
 $texts = AiClient::generateTextResult(
     'Write a 2-verse poem about PHP.',
@@ -48,6 +71,15 @@ $texts = AiClient::generateTextResult(
 
 #### Generate an image using any suitable OpenAI model
 
+##### Fluent API
+```php
+$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
+    ->usingProvider('openai')
+    ->usingModelSupportingImages() // Optional.
+    ->generateImage();
+```
+
+##### Traditional API
 ```php
 $modelsMetadata = AiClient::defaultRegistry()->findProviderModelsMetadataForSupport(
     'openai',
@@ -64,6 +96,14 @@ $imageFile = AiClient::generateImageResult(
 
 #### Generate an image using any suitable model from any provider
 
+##### Fluent API
+```php
+$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
+    ->usingModelSupportingImages() // Optional.
+    ->generateImage();
+```
+
+##### Traditional API
 ```php
 $providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
     new AiModelRequirements([AiCapability::IMAGE_GENERATION])
@@ -81,6 +121,14 @@ $imageFile = AiClient::generateImageResult(
 
 _Note: This does effectively the exact same as [the first code example](#generate-text-using-any-suitable-model-from-any-provider-most-basic-example), but more verbosely. In other words, if you omit the model parameter, the SDK will do this internally._
 
+##### Fluent API
+```php
+$text = AiClient::prompt('Write a 2-verse poem about PHP.')
+    ->usingModelSupportingText() // Optional.
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
     new AiModelRequirements([AiCapability::TEXT_GENERATION])
@@ -98,6 +146,14 @@ $text = AiClient::generateTextResult(
 
 _Note: Since this omits the model parameter, the SDK will automatically determine which models are suitable and use any of them, similar to [the first code example](#generate-text-using-any-suitable-model-from-any-provider-most-basic-example). Since it knows the input includes an image, it can internally infer that the model needs to not only support `AiCapability::TEXT_GENERATION`, but also `AiOption::INPUT_MODALITIES => ['text', 'image']`._
 
+##### Fluent API
+```php
+$text = AiClient::prompt('Generate alternative text for this image.')
+    ->withImage('image/png', $base64blob)
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $text = AiClient::generateTextResult(
     [
@@ -116,6 +172,17 @@ $text = AiClient::generateTextResult(
 
 _Note: Similarly to the previous example, even without specifying the model here, the SDK will be able to infer required model capabilities because it can detect that multiple chat messages are passed. Therefore it will internally only consider models that support `AiCapability::TEXT_GENERATION` as well as `AiCapability::CHAT_HISTORY`._
 
+##### Fluent API
+```php
+$text = AiClient::prompt('Can you repeat that please?')
+    ->withHistory(
+        new UserMessage('Do you spell it WordPress or Wordpress?'),
+        new AgentMessage('The correct spelling is WordPress.')
+    )
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $text = AiClient::generateTextResult(
     [
@@ -139,6 +206,21 @@ $text = AiClient::generateTextResult(
 
 _Note: Unlike the previous two examples, to require JSON output it is necessary to go the verbose route, since it is impossible for the SDK to detect whether you require JSON output purely from the prompt input. Therefore this code example contains the logic to manually search for suitable models and then use one of them for the task._
 
+##### Fluent API
+```php
+// Verbose.
+$text = AiClient::prompt('Transform the following CSV content into a JSON array of row data.')
+    ->asJsonResponse()
+    ->usingOutputSchema(['name' => 'string', 'age' => 'integer'])
+    ->generateText();
+
+// Simple.
+$text = AiClient::prompt('Transform the following CSV content into a JSON array of row data.')
+    ->asJsonResponse(['name' => 'string', 'age' => 'integer'])
+    ->generateText();
+```
+
+##### Traditional API
 ```php
 $providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
     new AiModelRequirements(
@@ -178,6 +260,13 @@ $jsonString = AiClient::generateTextResult(
 
 #### Generate embeddings using any suitable model from any provider
 
+##### Fluent API
+```php
+$embeddings = AiClient::prompt('A very long text.', 'Another very long text.', 'More long text.')
+    ->generateEmbeddings();
+```
+
+##### Traditional API
 ```php
 $providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
     new AiModelRequirements([AiCapability::EMBEDDING_GENERATION])
@@ -217,19 +306,34 @@ classDiagram
 direction LR
     namespace Ai {
         class AiClient {
-            +prompt(?string $text) PromptBuilder$
-            +message(?string $text) MessageBuilder$
+            +prompt(...string $text) PromptBuilder$
+            +message(...string $text) MessageBuilder$
         }
 
         class PromptBuilder {
             +withText(string $text) self
+            +withImage(string $mimeType, string $base64Blob) self
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
             +withVideoFile(File $file) self
             +withFunctionResponse(FunctionResponse $functionResponse) self
             +withMessageParts(...MessagePart $part) self
             +withHistory(...Message $messages) self
             +usingModel(AiModel $model) self
+            +usingModelSupporting(...AiCapability|AiOption $aiCapabilityOrOption) self
+            +usingModelSupportingCapability(...AiCapability $aiCapability) self
+            +usingModelSupportingOption(...AiOption $aiOption) self
+            +usingModelSupportingAudio() self
+            +usingModelSupportingHistory() self
+            +usingModelSupportingEmbeddings() self
+            +usingModelSupportingImages() self
+            +usingModelSupportingJsonOutput() self
+            +usingModelSupportingMusic() self
+            +usingModelSupportingOutputSchema() self
+            +usingModelSupportingSpeech() self
+            +usingModelSupportingText() self
+            +usingModelSupportingTextToSpeech() self
+            +usingModelSupportingVideo() self
             +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self
             +usingMaxTokens(int $maxTokens) self
             +usingTemperature(float $temperature) self
@@ -240,24 +344,41 @@ direction LR
             +usingOutputMime(string $mimeType) self
             +usingOutputSchema(array< string, mixed > $schema) self
             +usingOutputModalities(...AiModality $modalities) self
+            +asArrayResponse(?array< string, mixed > $schema) self
+            +asJsonResponse(?array< string, mixed > $schema) self
             +generateResult() GenerativeAiResult
+            +generateResults(int $candidateCount) GenerativeAiResult[]
             +generateOperation() GenerativeAiOperation
+            +generateOperations(int $candidateCount) GenerativeAiOperation[]
             +generateTextResult() GenerativeAiResult
+            +generateTextResults(int $candidateCount) GenerativeAiResult[]
             +streamGenerateTextResult() Generator< GenerativeAiResult >
             +generateImageResult() GenerativeAiResult
+            +generateImageResults(int $candidateCount) GenerativeAiResult[]
             +convertTextToSpeechResult() GenerativeAiResult
+            +convertTextToSpeechResults(int $candidateCount) GenerativeAiResult[]
             +generateSpeechResult() GenerativeAiResult
+            +generateSpeechResults(int $candidateCount) GenerativeAiResult[]
             +generateEmbeddingsResult() EmbeddingResult
+            +generateEmbeddingsResults(int $candidateCount) EmbeddingResult[]
             +generateTextOperation() GenerativeAiOperation
+            +generateTextOperations(int $candidateCount) GenerativeAiOperation[]
             +generateImageOperation() GenerativeAiOperation
+            +generateImageOperations(int $candidateCount) GenerativeAiOperation[]
             +convertTextToSpeechOperation() GenerativeAiOperation
             +generateSpeechOperation() GenerativeAiOperation
+            +generateSpeechOperations(int $candidateCount) GenerativeAiOperation[]
             +generateEmbeddingsOperation() EmbeddingOperation
+            +generateEmbeddingsOperations(int $candidateCount) EmbeddingOperation[]
             +generateText() string
+            +generateTexts(int $candidateCount) string[]
             +streamGenerateText() Generator< string >
             +generateImage() File
+            +generateImages(int $candidateCount) File[]
             +convertTextToSpeech() File
+            +convertTextToSpeeches(int $candidateCount) File[]
             +generateSpeech() File
+            +generateSpeeches(int $candidateCount) File[]
             +generateEmbeddings() Embedding[]
             +getModelRequirements() AiModelRequirements
             +isSupported() bool
@@ -266,6 +387,7 @@ direction LR
         class MessageBuilder {
             +usingRole(MessageRole $role) self
             +withText(string $text) self
+            +withImage(string $mimeType, string $base64Blob) self
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
             +withVideoFile(File $file) self
@@ -356,8 +478,8 @@ classDiagram
 direction LR
     namespace Ai {
         class AiClient {
-            +prompt(?string $text) PromptBuilder$
-            +message(?string $text) MessageBuilder$
+            +prompt(...string $text) PromptBuilder$
+            +message(...string $text) MessageBuilder$
             +defaultRegistry() AiProviderRegistry$
             +isConfigured(AiProviderAvailability $availability) bool$
             +generateResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
@@ -377,13 +499,28 @@ direction LR
 
         class PromptBuilder {
             +withText(string $text) self
+            +withImage(string $mimeType, string $base64Blob) self
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
             +withVideoFile(File $file) self
             +withFunctionResponse(FunctionResponse $functionResponse) self
             +withMessageParts(...MessagePart $part) self
             +withHistory(...Message $messages) self
             +usingModel(AiModel $model) self
+            +usingModelSupporting(...AiCapability|AiOption $aiCapabilityOrOption) self
+            +usingModelSupportingCapability(...AiCapability $aiCapability) self
+            +usingModelSupportingOption(...AiOption $aiOption) self
+            +usingModelSupportingAudio() self
+            +usingModelSupportingHistory() self
+            +usingModelSupportingEmbeddings() self
+            +usingModelSupportingImages() self
+            +usingModelSupportingJsonOutput() self
+            +usingModelSupportingMusic() self
+            +usingModelSupportingOutputSchema() self
+            +usingModelSupportingSpeech() self
+            +usingModelSupportingText() self
+            +usingModelSupportingTextToSpeech() self
+            +usingModelSupportingVideo() self
             +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self
             +usingMaxTokens(int $maxTokens) self
             +usingTemperature(float $temperature) self
@@ -394,24 +531,41 @@ direction LR
             +usingOutputMime(string $mimeType) self
             +usingOutputSchema(array< string, mixed > $schema) self
             +usingOutputModalities(...AiModality $modalities) self
+            +asArrayResponse(?array< string, mixed > $schema) self
+            +asJsonResponse(?array< string, mixed > $schema) self
             +generateResult() GenerativeAiResult
+            +generateResults(int $candidateCount) GenerativeAiResult[]
             +generateOperation() GenerativeAiOperation
+            +generateOperations(int $candidateCount) GenerativeAiOperation[]
             +generateTextResult() GenerativeAiResult
+            +generateTextResults(int $candidateCount) GenerativeAiResult[]
             +streamGenerateTextResult() Generator< GenerativeAiResult >
             +generateImageResult() GenerativeAiResult
+            +generateImageResults(int $candidateCount) GenerativeAiResult[]
             +convertTextToSpeechResult() GenerativeAiResult
+            +convertTextToSpeechResults(int $candidateCount) GenerativeAiResult[]
             +generateSpeechResult() GenerativeAiResult
+            +generateSpeechResults(int $candidateCount) GenerativeAiResult[]
             +generateEmbeddingsResult() EmbeddingResult
+            +generateEmbeddingsResults(int $candidateCount) EmbeddingResult[]
             +generateTextOperation() GenerativeAiOperation
+            +generateTextOperations(int $candidateCount) GenerativeAiOperation[]
             +generateImageOperation() GenerativeAiOperation
+            +generateImageOperations(int $candidateCount) GenerativeAiOperation[]
             +convertTextToSpeechOperation() GenerativeAiOperation
             +generateSpeechOperation() GenerativeAiOperation
+            +generateSpeechOperations(int $candidateCount) GenerativeAiOperation[]
             +generateEmbeddingsOperation() EmbeddingOperation
+            +generateEmbeddingsOperations(int $candidateCount) EmbeddingOperation[]
             +generateText() string
+            +generateTexts(int $candidateCount) string[]
             +streamGenerateText() Generator< string >
             +generateImage() File
+            +generateImages(int $candidateCount) File[]
             +convertTextToSpeech() File
+            +convertTextToSpeeches(int $candidateCount) File[]
             +generateSpeech() File
+            +generateSpeeches(int $candidateCount) File[]
             +generateEmbeddings() Embedding[]
             +getModelRequirements() AiModelRequirements
             +isSupported() bool
@@ -420,6 +574,7 @@ direction LR
         class MessageBuilder {
             +usingRole(MessageRole $role) self
             +withText(string $text) self
+            +withImage(string $mimeType, string $base64Blob) self
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
             +withVideoFile(File $file) self