Merge pull request #10 from WordPress/architecture-revision/fluent-api

Revise proposed architecture PR with fluent API class diagrams

Author: felixarntz

docs/ARCHITECTURE.md

@@ -198,16 +198,83 @@ This section shows comprehensive class diagrams for the proposed architecture. F
 
 **Note:** The class diagrams are also not meant to be comprehensive in terms of any specific configuration keys or parameters which are or will be supported. For now, the relevant definitions don't include any specific parameter names or constants.
 
-### Zoomed out view
+### Overview: Fluent API for AI consumption
 
-Below you find the zoomed out overview class diagram, looking at the two entrypoints for the largely decoupled APIs for:
+This is a subset of the overall class diagram, purely focused on the fluent API for AI consumption.
 
-- Consuming AI capabilities.
-    - This is what the vast majority of developers will use.
-- Registering and implementing AI providers.
-    - This is what only developers that implement additional models or custom providers will use.
+```mermaid
+---
+config:
+  class:
+    hideEmptyMembersBox: true
+---
+classDiagram
+direction LR
+    namespace Ai {
+        class AiEntrypoint {
+            +prompt(?string $text) PromptBuilder$
+            +message(?string $text) MessageBuilder$
+        }
+
+        class PromptBuilder {
+            +withText(string $text) 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
+            +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self
+            +usingTemperature(float $temperature) self
+            +usingTopP(float $topP) self
+            +usingTopK(int $topK) self
+            +usingStopSequences(...string $stopSequences) self
+            +usingCandidateCount(int $candidateCount) self
+            +usingOutputMime(string $mimeType) self
+            +usingOutputSchema(array< string, mixed > $schema) self
+            +usingOutputModalities(...AiModality $modalities) self
+            +generateResult() GenerativeAiResult
+            +generateOperation() GenerativeAiOperation
+            +generateTextResult() GenerativeAiResult
+            +streamGenerateTextResult() Generator< GenerativeAiResult >
+            +generateImageResult() GenerativeAiResult
+            +convertTextToSpeechResult() GenerativeAiResult
+            +generateSpeechResult() GenerativeAiResult
+            +generateEmbeddingsResult() EmbeddingResult
+            +generateTextOperation() GenerativeAiOperation
+            +generateImageOperation() GenerativeAiOperation
+            +convertTextToSpeechOperation() GenerativeAiOperation
+            +generateSpeechOperation() GenerativeAiOperation
+            +generateEmbeddingsOperation() EmbeddingOperation
+            +generateText() string
+            +streamGenerateText() Generator< string >
+            +generateImage() File
+            +convertTextToSpeech() File
+            +generateSpeech() File
+            +generateEmbeddings() Embedding[]
+        }
+
+        class MessageBuilder {
+            +usingRole(MessageRole $role) self
+            +withText(string $text) self
+            +withImageFile(File $file) self
+            +withAudioFile(File $file) self
+            +withVideoFile(File $file) self
+            +withFunctionCall(FunctionCall $functionCall) self
+            +withFunctionResponse(FunctionResponse $functionResponse) self
+            +withMessageParts(...MessagePart $part) self
+            +get() Message
+        }
+    }
+
+    AiEntrypoint .. PromptBuilder : creates
+    AiEntrypoint .. MessageBuilder : creates
+```
 
-Zoomed in views with detailed specifications for both of the APIs are found in the subsequent sections.
+### Overview: Traditional method call API for AI consumption
+
+This is a subset of the overall class diagram, purely focused on the traditional method call API for AI consumption.
 
 ```mermaid
 ---
@@ -219,23 +286,41 @@ classDiagram
 direction LR
     namespace Ai {
         class AiEntrypoint {
-            +defaultRegistry() AiProviderRegistry
-            +isConfigured(AiProviderAvailability $availability) bool$
             +generateResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateTextResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +streamGenerateTextResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) Generator< GenerativeAiResult >$
             +generateImageResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
-            +textToSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
+            +convertTextToSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateEmbeddingsResult(string[]|Message[] $input, AiModel $model) EmbeddingResult$
             +generateTextOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateImageOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
-            +textToSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
+            +convertTextToSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateEmbeddingsOperation(string[]|Message[] $input, AiModel $model) EmbeddingOperation$
         }
     }
+```
+
+### Overview: API for provider registration and implementation
+
+This is a subset of the overall class diagram, purely focused on the API for provider registration and implementation.
+
+```mermaid
+---
+config:
+  class:
+    hideEmptyMembersBox: true
+---
+classDiagram
+direction LR
+    namespace Ai {
+        class AiEntrypoint {
+            +defaultRegistry() AiProviderRegistry$
+            +isConfigured(AiProviderAvailability $availability) bool$
+        }
+    }
     namespace Ai.Providers {
         class AiProviderRegistry {
             +registerProvider(string $className) void
@@ -251,7 +336,7 @@ direction LR
     AiEntrypoint "1" o-- "1..*" AiProviderRegistry
 ```
 
-### Class diagram zoomed in on AI consumption
+### Details: Class diagram for AI consumption
 
 ```mermaid
 ---
@@ -263,22 +348,75 @@ classDiagram
 direction LR
     namespace Ai {
         class AiEntrypoint {
-            +defaultRegistry() AiProviderRegistry
+            +prompt(?string $text) PromptBuilder$
+            +message(?string $text) MessageBuilder$
+            +defaultRegistry() AiProviderRegistry$
             +isConfigured(AiProviderAvailability $availability) bool$
             +generateResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateTextResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +streamGenerateTextResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) Generator< GenerativeAiResult >$
             +generateImageResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
-            +textToSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
+            +convertTextToSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateSpeechResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$
             +generateEmbeddingsResult(string[]|Message[] $input, AiModel $model) EmbeddingResult$
             +generateTextOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateImageOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
-            +textToSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
+            +convertTextToSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$
             +generateEmbeddingsOperation(string[]|Message[] $input, AiModel $model) EmbeddingOperation$
         }
+
+        class PromptBuilder {
+            +withText(string $text) 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
+            +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self
+            +usingTemperature(float $temperature) self
+            +usingTopP(float $topP) self
+            +usingTopK(int $topK) self
+            +usingStopSequences(...string $stopSequences) self
+            +usingCandidateCount(int $candidateCount) self
+            +usingOutputMime(string $mimeType) self
+            +usingOutputSchema(array< string, mixed > $schema) self
+            +usingOutputModalities(...AiModality $modalities) self
+            +generateResult() GenerativeAiResult
+            +generateOperation() GenerativeAiOperation
+            +generateTextResult() GenerativeAiResult
+            +streamGenerateTextResult() Generator< GenerativeAiResult >
+            +generateImageResult() GenerativeAiResult
+            +convertTextToSpeechResult() GenerativeAiResult
+            +generateSpeechResult() GenerativeAiResult
+            +generateEmbeddingsResult() EmbeddingResult
+            +generateTextOperation() GenerativeAiOperation
+            +generateImageOperation() GenerativeAiOperation
+            +convertTextToSpeechOperation() GenerativeAiOperation
+            +generateSpeechOperation() GenerativeAiOperation
+            +generateEmbeddingsOperation() EmbeddingOperation
+            +generateText() string
+            +streamGenerateText() Generator< string >
+            +generateImage() File
+            +convertTextToSpeech() File
+            +generateSpeech() File
+            +generateEmbeddings() Embedding[]
+        }
+
+        class MessageBuilder {
+            +usingRole(MessageRole $role) self
+            +withText(string $text) self
+            +withImageFile(File $file) self
+            +withAudioFile(File $file) self
+            +withVideoFile(File $file) self
+            +withFunctionCall(FunctionCall $functionCall) self
+            +withFunctionResponse(FunctionResponse $functionResponse) self
+            +withMessageParts(...MessagePart $part) self
+            +get() Message
+        }
     }
     namespace Ai.Types {
         class Message {
@@ -454,10 +592,17 @@ direction LR
 
     AiEntrypoint .. Message : receives
     AiEntrypoint .. MessagePart : receives
+    AiEntrypoint .. PromptBuilder : creates
+    AiEntrypoint .. MessageBuilder : creates
     AiEntrypoint .. GenerativeAiResult : creates
     AiEntrypoint .. EmbeddingResult : creates
     AiEntrypoint .. GenerativeAiOperation : creates
     AiEntrypoint .. EmbeddingOperation : creates
+    PromptBuilder .. GenerativeAiResult : creates
+    PromptBuilder .. EmbeddingResult : creates
+    PromptBuilder .. GenerativeAiOperation : creates
+    PromptBuilder .. EmbeddingOperation : creates
+    MessageBuilder .. Message : creates
     Message "1" *-- "1..*" MessagePart
     MessagePart "1" o-- "0..1" InlineFile
     MessagePart "1" o-- "0..1" RemoteFile
@@ -484,7 +629,7 @@ direction LR
     Result <|-- EmbeddingResult
 ```
 
-### Class diagram zoomed in on AI provider registration and implementation
+### Details: Class diagram for AI provider registration and implementation
 
 ```mermaid
 ---
@@ -539,8 +684,8 @@ direction LR
         class AiImageGenerationModel {
             +generateImageResult(Message[] $prompt) GenerativeAiResult
         }
-        class AiTextToSpeechModel {
-            +textToSpeechResult(Message[] $prompt) GenerativeAiResult
+        class AiTextToSpeechConversionModel {
+            +convertTextToSpeechResult(Message[] $prompt) GenerativeAiResult
         }
         class AiSpeechGenerationModel {
             +generateSpeechResult(Message[] $prompt) GenerativeAiResult
@@ -554,8 +699,8 @@ direction LR
         class AiImageGenerationOperationModel {
             +generateImageOperation(Message[] $prompt) GenerativeAiOperation
         }
-        class AiTextToSpeechOperationModel {
-            +textToSpeechOperation(Message[] $prompt) GenerativeAiOperation
+        class AiTextToSpeechConversionOperationModel {
+            +convertTextToSpeechOperation(Message[] $prompt) GenerativeAiOperation
         }
         class AiSpeechGenerationOperationModel {
             +generateSpeechOperation(Message[] $prompt) GenerativeAiOperation
@@ -619,7 +764,7 @@ direction LR
         }
         class ImageGenerationConfig {
         }
-        class TextToSpeechConfig {
+        class TextToSpeechConversionConfig {
         }
         class SpeechGenerationConfig {
         }
@@ -684,12 +829,12 @@ direction LR
     <<interface>> WithEmbeddingOperations
     <<interface>> AiTextGenerationModel
     <<interface>> AiImageGenerationModel
-    <<interface>> AiTextToSpeechModel
+    <<interface>> AiTextToSpeechConversionModel
     <<interface>> AiSpeechGenerationModel
     <<interface>> AiEmbeddingGenerationModel
     <<interface>> AiTextGenerationOperationModel
     <<interface>> AiImageGenerationOperationModel
-    <<interface>> AiTextToSpeechOperationModel
+    <<interface>> AiTextToSpeechConversionOperationModel
     <<interface>> AiSpeechGenerationOperationModel
     <<interface>> AiEmbeddingGenerationOperationModel
     <<interface>> WithHttpClient
@@ -721,17 +866,17 @@ direction LR
     AiModelMetadata ..> AiFeature
     AiModel <|-- AiTextGenerationModel
     AiModel <|-- AiImageGenerationModel
-    AiModel <|-- AiTextToSpeechModel
+    AiModel <|-- AiTextToSpeechConversionModel
     AiModel <|-- AiSpeechGenerationModel
     AiModel <|-- AiEmbeddingGenerationModel
     AiModel <|-- AiTextGenerationOperationModel
     AiModel <|-- AiImageGenerationOperationModel
-    AiModel <|-- AiTextToSpeechOperationModel
+    AiModel <|-- AiTextToSpeechConversionOperationModel
     AiModel <|-- AiSpeechGenerationOperationModel
     AiModel <|-- AiEmbeddingGenerationOperationModel
     GenerationConfig <|-- TextGenerationConfig
     GenerationConfig <|-- ImageGenerationConfig
-    GenerationConfig <|-- TextToSpeechConfig
+    GenerationConfig <|-- TextToSpeechConversionConfig
     GenerationConfig <|-- SpeechGenerationConfig
     GenerationConfig <|-- EmbeddingGenerationConfig
 ```