From b13e0705f2bef98de882eaa1d3de0f292094cec5 Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Wed, 9 Jul 2025 22:06:40 -0700 Subject: [PATCH 1/4] Revise class diagrams to include fluent API infrastructure, and reorganize overview diagrams for easier understanding. --- docs/ARCHITECTURE.md | 169 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 157 insertions(+), 12 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 1add048..ba20517 100644 --- a/docs/ARCHITECTURE.md +++ b/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) PromptFacade$ + +message(?string $text) MessageFacade$ + } + + class PromptFacade { + +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 + +textToSpeechResult() GenerativeAiResult + +generateSpeechResult() GenerativeAiResult + +generateEmbeddingsResult() EmbeddingResult + +generateTextOperation() GenerativeAiOperation + +generateImageOperation() GenerativeAiOperation + +textToSpeechOperation() GenerativeAiOperation + +generateSpeechOperation() GenerativeAiOperation + +generateEmbeddingsOperation() EmbeddingOperation + +generateText() string + +streamGenerateText() Generator< string > + +generateImage() File + +textToSpeech() File + +generateSpeech() File + +generateEmbeddings() Embedding[] + } + + class MessageFacade { + +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 .. PromptFacade : creates + AiEntrypoint .. MessageFacade : 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,8 +286,6 @@ 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$ @@ -236,6 +301,26 @@ direction LR +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,7 +348,9 @@ classDiagram direction LR namespace Ai { class AiEntrypoint { - +defaultRegistry() AiProviderRegistry + +prompt(?string $text) PromptFacade$ + +message(?string $text) MessageFacade$ + +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$ @@ -279,6 +366,57 @@ direction LR +generateSpeechOperation(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiOperation$ +generateEmbeddingsOperation(string[]|Message[] $input, AiModel $model) EmbeddingOperation$ } + + class PromptFacade { + +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 + +textToSpeechResult() GenerativeAiResult + +generateSpeechResult() GenerativeAiResult + +generateEmbeddingsResult() EmbeddingResult + +generateTextOperation() GenerativeAiOperation + +generateImageOperation() GenerativeAiOperation + +textToSpeechOperation() GenerativeAiOperation + +generateSpeechOperation() GenerativeAiOperation + +generateEmbeddingsOperation() EmbeddingOperation + +generateText() string + +streamGenerateText() Generator< string > + +generateImage() File + +textToSpeech() File + +generateSpeech() File + +generateEmbeddings() Embedding[] + } + + class MessageFacade { + +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 .. PromptFacade : creates + AiEntrypoint .. MessageFacade : creates AiEntrypoint .. GenerativeAiResult : creates AiEntrypoint .. EmbeddingResult : creates AiEntrypoint .. GenerativeAiOperation : creates AiEntrypoint .. EmbeddingOperation : creates + PromptFacade .. GenerativeAiResult : creates + PromptFacade .. EmbeddingResult : creates + PromptFacade .. GenerativeAiOperation : creates + PromptFacade .. EmbeddingOperation : creates + MessageFacade .. 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 --- From 24285c40526a6d73d50804052d251def8ea5c725 Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Thu, 10 Jul 2025 08:57:25 -0700 Subject: [PATCH 2/4] Rename Facade classes to Builder classes, as more suitable name despite not formally using the builder pattern. --- docs/ARCHITECTURE.md | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index ba20517..b7654c6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -212,11 +212,11 @@ classDiagram direction LR namespace Ai { class AiEntrypoint { - +prompt(?string $text) PromptFacade$ - +message(?string $text) MessageFacade$ + +prompt(?string $text) PromptBuilder$ + +message(?string $text) MessageBuilder$ } - class PromptFacade { + class PromptBuilder { +withText(string $text) self +withImageFile(File $file) self +withAudioFile(File $file) self @@ -255,7 +255,7 @@ direction LR +generateEmbeddings() Embedding[] } - class MessageFacade { + class MessageBuilder { +usingRole(MessageRole $role) self +withText(string $text) self +withImageFile(File $file) self @@ -268,8 +268,8 @@ direction LR } } - AiEntrypoint .. PromptFacade : creates - AiEntrypoint .. MessageFacade : creates + AiEntrypoint .. PromptBuilder : creates + AiEntrypoint .. MessageBuilder : creates ``` ### Overview: Traditional method call API for AI consumption @@ -348,8 +348,8 @@ classDiagram direction LR namespace Ai { class AiEntrypoint { - +prompt(?string $text) PromptFacade$ - +message(?string $text) MessageFacade$ + +prompt(?string $text) PromptBuilder$ + +message(?string $text) MessageBuilder$ +defaultRegistry() AiProviderRegistry$ +isConfigured(AiProviderAvailability $availability) bool$ +generateResult(string|MessagePart|MessagePart[]|Message|Message[] $prompt, AiModel $model) GenerativeAiResult$ @@ -367,7 +367,7 @@ direction LR +generateEmbeddingsOperation(string[]|Message[] $input, AiModel $model) EmbeddingOperation$ } - class PromptFacade { + class PromptBuilder { +withText(string $text) self +withImageFile(File $file) self +withAudioFile(File $file) self @@ -406,7 +406,7 @@ direction LR +generateEmbeddings() Embedding[] } - class MessageFacade { + class MessageBuilder { +usingRole(MessageRole $role) self +withText(string $text) self +withImageFile(File $file) self @@ -592,17 +592,17 @@ direction LR AiEntrypoint .. Message : receives AiEntrypoint .. MessagePart : receives - AiEntrypoint .. PromptFacade : creates - AiEntrypoint .. MessageFacade : creates + AiEntrypoint .. PromptBuilder : creates + AiEntrypoint .. MessageBuilder : creates AiEntrypoint .. GenerativeAiResult : creates AiEntrypoint .. EmbeddingResult : creates AiEntrypoint .. GenerativeAiOperation : creates AiEntrypoint .. EmbeddingOperation : creates - PromptFacade .. GenerativeAiResult : creates - PromptFacade .. EmbeddingResult : creates - PromptFacade .. GenerativeAiOperation : creates - PromptFacade .. EmbeddingOperation : creates - MessageFacade .. Message : 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 From 920db773ee3cffc54cf4869d0f8059ce8f485d6f Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Thu, 10 Jul 2025 17:14:17 -0700 Subject: [PATCH 3/4] Use variadic parameter for messages. --- docs/ARCHITECTURE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b7654c6..cb3febd 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -223,7 +223,7 @@ direction LR +withVideoFile(File $file) self +withFunctionResponse(FunctionResponse $functionResponse) self +withMessageParts(...MessagePart $part) self - +withHistory(Message[] $messages) self + +withHistory(...Message $messages) self +usingModel(AiModel $model) self +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self +usingTemperature(float $temperature) self @@ -374,7 +374,7 @@ direction LR +withVideoFile(File $file) self +withFunctionResponse(FunctionResponse $functionResponse) self +withMessageParts(...MessagePart $part) self - +withHistory(Message[] $messages) self + +withHistory(...Message $messages) self +usingModel(AiModel $model) self +usingSystemInstruction(string|MessagePart[]|Message $systemInstruction) self +usingTemperature(float $temperature) self From 8fa8b210be7f90f26f5fbb5f8098b0732b37dbf5 Mon Sep 17 00:00:00 2001 From: Felix Arntz Date: Fri, 11 Jul 2025 11:21:28 -0700 Subject: [PATCH 4/4] Rename `textToSpeech` methods to `convertTextToSpeech` and relevant interfaces to use `TextToSpeechConversion`. --- docs/ARCHITECTURE.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index cb3febd..3b4b5f6 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -239,18 +239,18 @@ direction LR +generateTextResult() GenerativeAiResult +streamGenerateTextResult() Generator< GenerativeAiResult > +generateImageResult() GenerativeAiResult - +textToSpeechResult() GenerativeAiResult + +convertTextToSpeechResult() GenerativeAiResult +generateSpeechResult() GenerativeAiResult +generateEmbeddingsResult() EmbeddingResult +generateTextOperation() GenerativeAiOperation +generateImageOperation() GenerativeAiOperation - +textToSpeechOperation() GenerativeAiOperation + +convertTextToSpeechOperation() GenerativeAiOperation +generateSpeechOperation() GenerativeAiOperation +generateEmbeddingsOperation() EmbeddingOperation +generateText() string +streamGenerateText() Generator< string > +generateImage() File - +textToSpeech() File + +convertTextToSpeech() File +generateSpeech() File +generateEmbeddings() Embedding[] } @@ -291,12 +291,12 @@ direction LR +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$ } @@ -357,12 +357,12 @@ direction LR +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$ } @@ -390,18 +390,18 @@ direction LR +generateTextResult() GenerativeAiResult +streamGenerateTextResult() Generator< GenerativeAiResult > +generateImageResult() GenerativeAiResult - +textToSpeechResult() GenerativeAiResult + +convertTextToSpeechResult() GenerativeAiResult +generateSpeechResult() GenerativeAiResult +generateEmbeddingsResult() EmbeddingResult +generateTextOperation() GenerativeAiOperation +generateImageOperation() GenerativeAiOperation - +textToSpeechOperation() GenerativeAiOperation + +convertTextToSpeechOperation() GenerativeAiOperation +generateSpeechOperation() GenerativeAiOperation +generateEmbeddingsOperation() EmbeddingOperation +generateText() string +streamGenerateText() Generator< string > +generateImage() File - +textToSpeech() File + +convertTextToSpeech() File +generateSpeech() File +generateEmbeddings() Embedding[] } @@ -684,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 @@ -699,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 @@ -764,7 +764,7 @@ direction LR } class ImageGenerationConfig { } - class TextToSpeechConfig { + class TextToSpeechConversionConfig { } class SpeechGenerationConfig { } @@ -829,12 +829,12 @@ direction LR <> WithEmbeddingOperations <> AiTextGenerationModel <> AiImageGenerationModel - <> AiTextToSpeechModel + <> AiTextToSpeechConversionModel <> AiSpeechGenerationModel <> AiEmbeddingGenerationModel <> AiTextGenerationOperationModel <> AiImageGenerationOperationModel - <> AiTextToSpeechOperationModel + <> AiTextToSpeechConversionOperationModel <> AiSpeechGenerationOperationModel <> AiEmbeddingGenerationOperationModel <> WithHttpClient @@ -866,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 ```