Update ARCHITECTURE.md with latest revisions and high-level proposed HTTP approach

docs/ARCHITECTURE.md

@@ -304,7 +304,6 @@ direction LR
         class PromptBuilder {
             +withText(string $text) self
             +withInlineImage(string $base64Blob, string $mimeType)
-            +withLocalImage(string $path, string $mimeType)
             +withRemoteImage(string $uri, string $mimeType)
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
@@ -340,12 +339,12 @@ direction LR
             +generateText() string
             +generateTexts(?int $candidateCount) string[]
             +streamGenerateText() Generator< string >
-            +generateImage() FileInterface
-            +generateImages(?int $candidateCount) FileInterface[]
-            +convertTextToSpeech() FileInterface
-            +convertTextToSpeeches(?int $candidateCount) FileInterface[]
-            +generateSpeech() FileInterface
-            +generateSpeeches(?int $candidateCount) FileInterface[]
+            +generateImage() File
+            +generateImages(?int $candidateCount) File[]
+            +convertTextToSpeech() File
+            +convertTextToSpeeches(?int $candidateCount) File[]
+            +generateSpeech() File
+            +generateSpeeches(?int $candidateCount) File[]
             +generateEmbeddings() Embedding[]
             +getModelRequirements() ModelRequirements
             +isSupported() bool
@@ -468,7 +467,6 @@ direction LR
         class PromptBuilder {
             +withText(string $text) self
             +withInlineImage(string $base64Blob, string $mimeType)
-            +withLocalImage(string $path, string $mimeType)
             +withRemoteImage(string $uri, string $mimeType)
             +withImageFile(File $file) self
             +withAudioFile(File $file) self
@@ -504,12 +502,12 @@ direction LR
             +generateText() string
             +generateTexts(?int $candidateCount) string[]
             +streamGenerateText() Generator< string >
-            +generateImage() FileInterface
-            +generateImages(?int $candidateCount) FileInterface[]
-            +convertTextToSpeech() FileInterface
-            +convertTextToSpeeches(?int $candidateCount) FileInterface[]
-            +generateSpeech() FileInterface
-            +generateSpeeches(?int $candidateCount) FileInterface[]
+            +generateImage() File
+            +generateImages(?int $candidateCount) File[]
+            +convertTextToSpeech() File
+            +convertTextToSpeeches(?int $candidateCount) File[]
+            +generateSpeech() File
+            +generateSpeeches(?int $candidateCount) File[]
             +generateEmbeddings() Embedding[]
             +getModelRequirements() ModelRequirements
             +isSupported() bool
@@ -535,26 +533,20 @@ direction LR
         }
     }
 
-    namespace AiClientNamespace.Files.Contracts {
-        class FileInterface {
-        }
-    }
-
     namespace AiClientNamespace.Files.DTO {
-        class InlineFile {
-            +getMimeType() string
-            +getBase64Data() string
-            +getJsonSchema() array< string, mixed >$
-        }
-        class LocalFile {
+        class File {
+            +getFileType() FileTypeEnum
             +getMimeType() string
-            +getPath() string
+            +getUrl() ?string
+            +getBase64Data() ?string
             +getJsonSchema() array< string, mixed >$
         }
-        class RemoteFile {
-            +getMimeType() string
-            +getUrl() string
-            +getJsonSchema() array< string, mixed >$
+    }
+
+    namespace AiClientNamespace.Files.Enums {
+        class FileTypeEnum {
+            INLINE
+            REMOTE
         }
     }
 
@@ -567,8 +559,7 @@ direction LR
         class MessagePart {
             +getType() MessagePartTypeEnum
             +getText() string?
-            +getInlineFile() InlineFile?
-            +getRemoteFile() RemoteFile?
+            +getFile() File?
             +getFunctionCall() FunctionCall?
             +getFunctionResponse() FunctionResponse?
             +getJsonSchema() array< string, mixed >$
@@ -584,8 +575,7 @@ direction LR
     namespace AiClientNamespace.Messages.Enums {
         class MessagePartTypeEnum {
             TEXT
-            INLINE_FILE
-            REMOTE_FILE
+            FILE
             FUNCTION_CALL
             FUNCTION_RESPONSE
         }
@@ -667,14 +657,14 @@ direction LR
             +getJsonSchema() array< string, mixed >$
             %% The following utility methods transform the result candidates into a specific shape.
             +toText() string
-            +toImageFile() FileInterface
-            +toAudioFile() FileInterface
-            +toVideoFile() FileInterface
+            +toImageFile() File
+            +toAudioFile() File
+            +toVideoFile() File
             +toMessage() Message
             +toTexts() string[]
-            +toImageFiles() FileInterface[]
-            +toAudioFiles() FileInterface[]
-            +toVideoFiles() FileInterface[]
+            +toImageFiles() File[]
+            +toAudioFiles() File[]
+            +toVideoFiles() File[]
             +toMessages() Message[]
         }
         class TokenUsage {
@@ -697,8 +687,8 @@ direction LR
 
     namespace AiClientNamespace.Tools.DTO {
         class FunctionCall {
-            +getId() string
-            +getName() string
+            +getId() ?string
+            +getName() ?string
             +getArgs() array< string, mixed >
             +getJsonSchema() array< string, mixed >$
         }
@@ -709,8 +699,8 @@ direction LR
             +getJsonSchema() array< string, mixed >$
         }
         class FunctionResponse {
-            +getId() string
-            +getName() string
+            +getId() ?string
+            +getName() ?string
             +getResponse() mixed
             +getJsonSchema() array< string, mixed >$
         }
@@ -730,26 +720,25 @@ direction LR
     namespace AiClientNamespace.Util {
         class CandidatesUtil {
             +toTexts(Candidate[] $candidates) string[]$
-            +toImageFiles(Candidate[] $candidates) FileInterface[]$
-            +toAudioFiles(Candidate[] $candidates) FileInterface[]$
-            +toVideoFiles(Candidate[] $candidates) FileInterface[]$
+            +toImageFiles(Candidate[] $candidates) File[]$
+            +toAudioFiles(Candidate[] $candidates) File[]$
+            +toVideoFiles(Candidate[] $candidates) File[]$
             +toFirstText(Candidate[] $candidates) string$
-            +toFirstImageFile(Candidate[] $candidates) FileInterface$
-            +toFirstAudioFile(Candidate[] $candidates) FileInterface$
-            +toFirstVideoFile(Candidate[] $candidates) FileInterface$
+            +toFirstImageFile(Candidate[] $candidates) File$
+            +toFirstAudioFile(Candidate[] $candidates) File$
+            +toFirstVideoFile(Candidate[] $candidates) File$
         }
         class MessageUtil {
             +toText(Message $message) string$
-            +toImageFile(Message $message) FileInterface$
-            +toAudioFile(Message $message) FileInterface$
-            +toVideoFile(Message $message) FileInterface$
+            +toImageFile(Message $message) File$
+            +toAudioFile(Message $message) File$
+            +toVideoFile(Message $message) File$
         }
         class RequirementsUtil {
             +inferRequirements(Message[] $messages, ModelConfig $modelConfig) ModelRequirements$
         }
     }
 
-    <<interface>> FileInterface
     <<interface>> OperationInterface
     <<interface>> ResultInterface
     <<Enumeration>> MessageRoleEnum
@@ -772,8 +761,7 @@ direction LR
     PromptBuilder .. EmbeddingOperation : creates
     MessageBuilder .. Message : creates
     Message "1" *-- "1..*" MessagePart
-    MessagePart "1" o-- "0..1" InlineFile
-    MessagePart "1" o-- "0..1" RemoteFile
+    MessagePart "1" o-- "0..1" File
     MessagePart "1" o-- "0..1" FunctionCall
     MessagePart "1" o-- "0..1" FunctionResponse
     GenerativeAiOperation "1" o-- "0..1" GenerativeAiResult
@@ -788,9 +776,6 @@ direction LR
     OperationInterface ..> OperationStateEnum
     GenerativeAiOperation ..> OperationStateEnum
     Candidate ..> FinishReasonEnum
-    FileInterface <|-- InlineFile
-    FileInterface <|-- RemoteFile
-    FileInterface <|-- LocalFile
     Message <|-- UserMessage
     Message <|-- ModelMessage
     Message <|-- SystemMessage
@@ -825,27 +810,25 @@ direction LR
     }
 
     namespace AiClientNamespace.Providers.Contracts {
-        class AuthenticationInterface {
-            +authenticate(RequestInterface $request) void
-            +getJsonSchema() array< string, mixed >$
-        }
-        class HttpClientInterface {
-            +send(RequestInterface $request, array< string, mixed > $options) ResponseInterface
-            +request(string $method, string $uri, array< string, mixed > $options) ResponseInterface
-        }
         class ModelMetadataDirectoryInterface {
             +listModelMetadata() ModelMetadata[]
             +hasModelMetadata(string $modelId) bool
             +getModelMetadata(string $modelId) ModelMetadata
         }
+        class ProviderAvailabilityInterface {
+            +isConfigured() bool
+        }
         class ProviderInterface {
             +metadata() ProviderMetadata$
             +model(string $modelId, ModelConfig|array< string, mixed > $modelConfig) ModelInterface$
             +availability() ProviderAvailabilityInterface$
             +modelMetadataDirectory() ModelMetadataDirectoryInterface$
         }
-        class ProviderAvailabilityInterface {
-            +isConfigured() bool
+        class ProviderOperationsHandlerInterface {
+            +getOperation(string $operationId) OperationInterface
+        }
+        class ProviderWithOperationsHandlerInterface {
+            +operationsHandler() ProviderOperationsHandlerInterface$
         }
     }
 
@@ -875,26 +858,52 @@ direction LR
         }
     }
 
+    namespace AiClientNamespace.Providers.Http.Contracts {
+        class HttpTransporterInterface {
+            +send(Request $request) Response
+        }
+        class RequestAuthenticationInterface {
+            +authenticate(Request $request) void
+            +getJsonSchema() array< string, mixed >$
+        }
+        class WithHttpTransporterInterface {
+            +setHttpTransporter(HttpTransporterInterface $transporter) void
+            +getHttpTransporter() HttpTransporterInterface
+        }
+        class WithRequestAuthenticationInterface {
+            +setRequestAuthentication(RequestAuthenticationInterface $authentication) void
+            +getRequestAuthentication() RequestAuthenticationInterface
+        }
+    }
+
+    namespace AiClientNamespace.Providers.Http.DTO {
+        class Request {
+            +getMethod() string
+            +getUri() string
+            +getHeaders() array< string, string[] >
+            +getBody() ?string
+            +getData() ?array< string, mixed >
+            +getJsonSchema() array< string, mixed >$
+        }
+
+        class Response {
+            +getStatusCode() int
+            +getHeaders() array< string, string[] >
+            +getBody() ?string
+            +getData() ?array< string, mixed >
+            +getJsonSchema() array< string, mixed >$
+        }
+    }
+
     namespace AiClientNamespace.Providers.Models.Contracts {
         class ModelInterface {
             +metadata() ModelMetadata
             +setConfig(ModelConfig $config) void
             +getConfig() ModelConfig
         }
-        class WithAuthenticationInterface {
-            +setAuthentication(AuthenticationInterface $authentication) void
-            +getAuthentication() AuthenticationInterface
-        }
         class WithEmbeddingOperationsInterface {
             +getOperation(string $operationId) EmbeddingOperation
         }
-        class WithGenerativeAiOperationsInterface {
-            +getOperation(string $operationId) GenerativeAiOperation
-        }
-        class WithHttpClientInterface {
-            +setHttpClient(HttpClientInterface $client) void
-            +getHttpClient() HttpClientInterface
-        }
     }
 
     namespace AiClientNamespace.Providers.Models.DTO {
@@ -1050,7 +1059,8 @@ direction LR
     <<interface>> ModelInterface
     <<interface>> ProviderAvailabilityInterface
     <<interface>> ModelMetadataDirectoryInterface
-    <<interface>> WithGenerativeAiOperationsInterface
+    <<interface>> ProviderOperationsHandlerInterface
+    <<interface>> ProviderWithOperationsHandlerInterface
     <<interface>> WithEmbeddingOperationsInterface
     <<interface>> TextGenerationModelInterface
     <<interface>> ImageGenerationModelInterface
@@ -1062,10 +1072,10 @@ direction LR
     <<interface>> TextToSpeechConversionOperationModelInterface
     <<interface>> SpeechGenerationOperationModelInterface
     <<interface>> EmbeddingGenerationOperationModelInterface
-    <<interface>> WithHttpClientInterface
-    <<interface>> HttpClientInterface
-    <<interface>> WithAuthenticationInterface
-    <<interface>> AuthenticationInterface
+    <<interface>> HttpTransporterInterface
+    <<interface>> WithHttpTransporterInterface
+    <<interface>> RequestAuthenticationInterface
+    <<interface>> WithRequestAuthenticationInterface
     <<Enumeration>> CapabilityEnum
     <<Enumeration>> OptionEnum
     <<Enumeration>> ProviderTypeEnum
@@ -1074,6 +1084,7 @@ direction LR
     ProviderInterface "1" *-- "1" ProviderMetadata
     ProviderInterface "1" *-- "1" ProviderAvailabilityInterface
     ProviderInterface "1" *-- "1" ModelMetadataDirectoryInterface
+    ProviderWithOperationsHandlerInterface "1" *-- "1" ProviderOperationsHandlerInterface
     ModelInterface "1" *-- "1" ModelMetadata
     ModelInterface "1" *-- "1" ModelConfig
     ProviderModelsMetadata "1" o-- "1" ProviderMetadata

src/Providers/Contracts/ProviderOperationsHandlerInterface.php

@@ -5,7 +5,7 @@
 namespace WordPress\AiClient\Providers\Contracts;
 
 use InvalidArgumentException;
-use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
+use WordPress\AiClient\Operations\Contracts\OperationInterface;
 
 /**
  * Interface for handling provider-level operations.
@@ -24,8 +24,8 @@ interface ProviderOperationsHandlerInterface
      * @since n.e.x.t
      *
      * @param string $operationId Operation identifier.
-     * @return GenerativeAiOperation The operation.
+     * @return OperationInterface The operation.
      * @throws InvalidArgumentException If operation not found.
      */
-    public function getOperation(string $operationId): GenerativeAiOperation;
+    public function getOperation(string $operationId): OperationInterface;
 }

src/Tools/DTO/FunctionCall.php

@@ -65,7 +65,7 @@ public function __construct(?string $id = null, ?string $name = null, array $arg
      *
      * @since n.e.x.t
      *
-     * @return string|null The unique identifier.
+     * @return string|null The function call ID.
      */
     public function getId(): ?string
     {

src/Tools/DTO/FunctionResponse.php

@@ -59,9 +59,9 @@ public function __construct(string $id, string $name, $response)
      *
      * @since n.e.x.t
      *
-     * @return string The function call ID.
+     * @return string|null The function call ID.
      */
-    public function getId(): string
+    public function getId(): ?string
     {
         return $this->id;
     }
@@ -71,9 +71,9 @@ public function getId(): string
      *
      * @since n.e.x.t
      *
-     * @return string The function name.
+     * @return string|null The function name.
      */
-    public function getName(): string
+    public function getName(): ?string
     {
         return $this->name;
     }