Skip to content

Commit b1999c1

Browse files
JasonTheAdamsJasonTheAdams
authored
Merge pull request #46 from WordPress/update/architecture-docs
2 parents f9c202b + dd245b1 commit b1999c1

File tree

4 files changed

+104
-93
lines changed

4 files changed

+104
-93
lines changed

‎docs/ARCHITECTURE.md‎

Lines changed: 96 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,6 @@ direction LR
304304
class PromptBuilder {
305305
+withText(string $text) self
306306
+withInlineImage(string $base64Blob, string $mimeType)
307-
+withLocalImage(string $path, string $mimeType)
308307
+withRemoteImage(string $uri, string $mimeType)
309308
+withImageFile(File $file) self
310309
+withAudioFile(File $file) self
@@ -340,12 +339,12 @@ direction LR
340339
+generateText() string
341340
+generateTexts(?int $candidateCount) string[]
342341
+streamGenerateText() Generator< string >
343-
+generateImage() FileInterface
344-
+generateImages(?int $candidateCount) FileInterface[]
345-
+convertTextToSpeech() FileInterface
346-
+convertTextToSpeeches(?int $candidateCount) FileInterface[]
347-
+generateSpeech() FileInterface
348-
+generateSpeeches(?int $candidateCount) FileInterface[]
342+
+generateImage() File
343+
+generateImages(?int $candidateCount) File[]
344+
+convertTextToSpeech() File
345+
+convertTextToSpeeches(?int $candidateCount) File[]
346+
+generateSpeech() File
347+
+generateSpeeches(?int $candidateCount) File[]
349348
+generateEmbeddings() Embedding[]
350349
+getModelRequirements() ModelRequirements
351350
+isSupported() bool
@@ -468,7 +467,6 @@ direction LR
468467
class PromptBuilder {
469468
+withText(string $text) self
470469
+withInlineImage(string $base64Blob, string $mimeType)
471-
+withLocalImage(string $path, string $mimeType)
472470
+withRemoteImage(string $uri, string $mimeType)
473471
+withImageFile(File $file) self
474472
+withAudioFile(File $file) self
@@ -504,12 +502,12 @@ direction LR
504502
+generateText() string
505503
+generateTexts(?int $candidateCount) string[]
506504
+streamGenerateText() Generator< string >
507-
+generateImage() FileInterface
508-
+generateImages(?int $candidateCount) FileInterface[]
509-
+convertTextToSpeech() FileInterface
510-
+convertTextToSpeeches(?int $candidateCount) FileInterface[]
511-
+generateSpeech() FileInterface
512-
+generateSpeeches(?int $candidateCount) FileInterface[]
505+
+generateImage() File
506+
+generateImages(?int $candidateCount) File[]
507+
+convertTextToSpeech() File
508+
+convertTextToSpeeches(?int $candidateCount) File[]
509+
+generateSpeech() File
510+
+generateSpeeches(?int $candidateCount) File[]
513511
+generateEmbeddings() Embedding[]
514512
+getModelRequirements() ModelRequirements
515513
+isSupported() bool
@@ -535,26 +533,20 @@ direction LR
535533
}
536534
}
537535
538-
namespace AiClientNamespace.Files.Contracts {
539-
class FileInterface {
540-
}
541-
}
542-
543536
namespace AiClientNamespace.Files.DTO {
544-
class InlineFile {
545-
+getMimeType() string
546-
+getBase64Data() string
547-
+getJsonSchema() array< string, mixed >$
548-
}
549-
class LocalFile {
537+
class File {
538+
+getFileType() FileTypeEnum
550539
+getMimeType() string
551-
+getPath() string
540+
+getUrl() ?string
541+
+getBase64Data() ?string
552542
+getJsonSchema() array< string, mixed >$
553543
}
554-
class RemoteFile {
555-
+getMimeType() string
556-
+getUrl() string
557-
+getJsonSchema() array< string, mixed >$
544+
}
545+
546+
namespace AiClientNamespace.Files.Enums {
547+
class FileTypeEnum {
548+
INLINE
549+
REMOTE
558550
}
559551
}
560552
@@ -567,8 +559,7 @@ direction LR
567559
class MessagePart {
568560
+getType() MessagePartTypeEnum
569561
+getText() string?
570-
+getInlineFile() InlineFile?
571-
+getRemoteFile() RemoteFile?
562+
+getFile() File?
572563
+getFunctionCall() FunctionCall?
573564
+getFunctionResponse() FunctionResponse?
574565
+getJsonSchema() array< string, mixed >$
@@ -584,8 +575,7 @@ direction LR
584575
namespace AiClientNamespace.Messages.Enums {
585576
class MessagePartTypeEnum {
586577
TEXT
587-
INLINE_FILE
588-
REMOTE_FILE
578+
FILE
589579
FUNCTION_CALL
590580
FUNCTION_RESPONSE
591581
}
@@ -667,14 +657,14 @@ direction LR
667657
+getJsonSchema() array< string, mixed >$
668658
%% The following utility methods transform the result candidates into a specific shape.
669659
+toText() string
670-
+toImageFile() FileInterface
671-
+toAudioFile() FileInterface
672-
+toVideoFile() FileInterface
660+
+toImageFile() File
661+
+toAudioFile() File
662+
+toVideoFile() File
673663
+toMessage() Message
674664
+toTexts() string[]
675-
+toImageFiles() FileInterface[]
676-
+toAudioFiles() FileInterface[]
677-
+toVideoFiles() FileInterface[]
665+
+toImageFiles() File[]
666+
+toAudioFiles() File[]
667+
+toVideoFiles() File[]
678668
+toMessages() Message[]
679669
}
680670
class TokenUsage {
@@ -697,8 +687,8 @@ direction LR
697687
698688
namespace AiClientNamespace.Tools.DTO {
699689
class FunctionCall {
700-
+getId() string
701-
+getName() string
690+
+getId() ?string
691+
+getName() ?string
702692
+getArgs() array< string, mixed >
703693
+getJsonSchema() array< string, mixed >$
704694
}
@@ -709,8 +699,8 @@ direction LR
709699
+getJsonSchema() array< string, mixed >$
710700
}
711701
class FunctionResponse {
712-
+getId() string
713-
+getName() string
702+
+getId() ?string
703+
+getName() ?string
714704
+getResponse() mixed
715705
+getJsonSchema() array< string, mixed >$
716706
}
@@ -730,26 +720,25 @@ direction LR
730720
namespace AiClientNamespace.Util {
731721
class CandidatesUtil {
732722
+toTexts(Candidate[] $candidates) string[]$
733-
+toImageFiles(Candidate[] $candidates) FileInterface[]$
734-
+toAudioFiles(Candidate[] $candidates) FileInterface[]$
735-
+toVideoFiles(Candidate[] $candidates) FileInterface[]$
723+
+toImageFiles(Candidate[] $candidates) File[]$
724+
+toAudioFiles(Candidate[] $candidates) File[]$
725+
+toVideoFiles(Candidate[] $candidates) File[]$
736726
+toFirstText(Candidate[] $candidates) string$
737-
+toFirstImageFile(Candidate[] $candidates) FileInterface$
738-
+toFirstAudioFile(Candidate[] $candidates) FileInterface$
739-
+toFirstVideoFile(Candidate[] $candidates) FileInterface$
727+
+toFirstImageFile(Candidate[] $candidates) File$
728+
+toFirstAudioFile(Candidate[] $candidates) File$
729+
+toFirstVideoFile(Candidate[] $candidates) File$
740730
}
741731
class MessageUtil {
742732
+toText(Message $message) string$
743-
+toImageFile(Message $message) FileInterface$
744-
+toAudioFile(Message $message) FileInterface$
745-
+toVideoFile(Message $message) FileInterface$
733+
+toImageFile(Message $message) File$
734+
+toAudioFile(Message $message) File$
735+
+toVideoFile(Message $message) File$
746736
}
747737
class RequirementsUtil {
748738
+inferRequirements(Message[] $messages, ModelConfig $modelConfig) ModelRequirements$
749739
}
750740
}
751741
752-
<<interface>> FileInterface
753742
<<interface>> OperationInterface
754743
<<interface>> ResultInterface
755744
<<Enumeration>> MessageRoleEnum
@@ -772,8 +761,7 @@ direction LR
772761
PromptBuilder .. EmbeddingOperation : creates
773762
MessageBuilder .. Message : creates
774763
Message "1" *-- "1..*" MessagePart
775-
MessagePart "1" o-- "0..1" InlineFile
776-
MessagePart "1" o-- "0..1" RemoteFile
764+
MessagePart "1" o-- "0..1" File
777765
MessagePart "1" o-- "0..1" FunctionCall
778766
MessagePart "1" o-- "0..1" FunctionResponse
779767
GenerativeAiOperation "1" o-- "0..1" GenerativeAiResult
@@ -788,9 +776,6 @@ direction LR
788776
OperationInterface ..> OperationStateEnum
789777
GenerativeAiOperation ..> OperationStateEnum
790778
Candidate ..> FinishReasonEnum
791-
FileInterface <|-- InlineFile
792-
FileInterface <|-- RemoteFile
793-
FileInterface <|-- LocalFile
794779
Message <|-- UserMessage
795780
Message <|-- ModelMessage
796781
Message <|-- SystemMessage
@@ -825,27 +810,25 @@ direction LR
825810
}
826811
827812
namespace AiClientNamespace.Providers.Contracts {
828-
class AuthenticationInterface {
829-
+authenticate(RequestInterface $request) void
830-
+getJsonSchema() array< string, mixed >$
831-
}
832-
class HttpClientInterface {
833-
+send(RequestInterface $request, array< string, mixed > $options) ResponseInterface
834-
+request(string $method, string $uri, array< string, mixed > $options) ResponseInterface
835-
}
836813
class ModelMetadataDirectoryInterface {
837814
+listModelMetadata() ModelMetadata[]
838815
+hasModelMetadata(string $modelId) bool
839816
+getModelMetadata(string $modelId) ModelMetadata
840817
}
818+
class ProviderAvailabilityInterface {
819+
+isConfigured() bool
820+
}
841821
class ProviderInterface {
842822
+metadata() ProviderMetadata$
843823
+model(string $modelId, ModelConfig|array< string, mixed > $modelConfig) ModelInterface$
844824
+availability() ProviderAvailabilityInterface$
845825
+modelMetadataDirectory() ModelMetadataDirectoryInterface$
846826
}
847-
class ProviderAvailabilityInterface {
848-
+isConfigured() bool
827+
class ProviderOperationsHandlerInterface {
828+
+getOperation(string $operationId) OperationInterface
829+
}
830+
class ProviderWithOperationsHandlerInterface {
831+
+operationsHandler() ProviderOperationsHandlerInterface$
849832
}
850833
}
851834
@@ -875,26 +858,52 @@ direction LR
875858
}
876859
}
877860
861+
namespace AiClientNamespace.Providers.Http.Contracts {
862+
class HttpTransporterInterface {
863+
+send(Request $request) Response
864+
}
865+
class RequestAuthenticationInterface {
866+
+authenticate(Request $request) void
867+
+getJsonSchema() array< string, mixed >$
868+
}
869+
class WithHttpTransporterInterface {
870+
+setHttpTransporter(HttpTransporterInterface $transporter) void
871+
+getHttpTransporter() HttpTransporterInterface
872+
}
873+
class WithRequestAuthenticationInterface {
874+
+setRequestAuthentication(RequestAuthenticationInterface $authentication) void
875+
+getRequestAuthentication() RequestAuthenticationInterface
876+
}
877+
}
878+
879+
namespace AiClientNamespace.Providers.Http.DTO {
880+
class Request {
881+
+getMethod() string
882+
+getUri() string
883+
+getHeaders() array< string, string[] >
884+
+getBody() ?string
885+
+getData() ?array< string, mixed >
886+
+getJsonSchema() array< string, mixed >$
887+
}
888+
889+
class Response {
890+
+getStatusCode() int
891+
+getHeaders() array< string, string[] >
892+
+getBody() ?string
893+
+getData() ?array< string, mixed >
894+
+getJsonSchema() array< string, mixed >$
895+
}
896+
}
897+
878898
namespace AiClientNamespace.Providers.Models.Contracts {
879899
class ModelInterface {
880900
+metadata() ModelMetadata
881901
+setConfig(ModelConfig $config) void
882902
+getConfig() ModelConfig
883903
}
884-
class WithAuthenticationInterface {
885-
+setAuthentication(AuthenticationInterface $authentication) void
886-
+getAuthentication() AuthenticationInterface
887-
}
888904
class WithEmbeddingOperationsInterface {
889905
+getOperation(string $operationId) EmbeddingOperation
890906
}
891-
class WithGenerativeAiOperationsInterface {
892-
+getOperation(string $operationId) GenerativeAiOperation
893-
}
894-
class WithHttpClientInterface {
895-
+setHttpClient(HttpClientInterface $client) void
896-
+getHttpClient() HttpClientInterface
897-
}
898907
}
899908
900909
namespace AiClientNamespace.Providers.Models.DTO {
@@ -1050,7 +1059,8 @@ direction LR
10501059
<<interface>> ModelInterface
10511060
<<interface>> ProviderAvailabilityInterface
10521061
<<interface>> ModelMetadataDirectoryInterface
1053-
<<interface>> WithGenerativeAiOperationsInterface
1062+
<<interface>> ProviderOperationsHandlerInterface
1063+
<<interface>> ProviderWithOperationsHandlerInterface
10541064
<<interface>> WithEmbeddingOperationsInterface
10551065
<<interface>> TextGenerationModelInterface
10561066
<<interface>> ImageGenerationModelInterface
@@ -1062,10 +1072,10 @@ direction LR
10621072
<<interface>> TextToSpeechConversionOperationModelInterface
10631073
<<interface>> SpeechGenerationOperationModelInterface
10641074
<<interface>> EmbeddingGenerationOperationModelInterface
1065-
<<interface>> WithHttpClientInterface
1066-
<<interface>> HttpClientInterface
1067-
<<interface>> WithAuthenticationInterface
1068-
<<interface>> AuthenticationInterface
1075+
<<interface>> HttpTransporterInterface
1076+
<<interface>> WithHttpTransporterInterface
1077+
<<interface>> RequestAuthenticationInterface
1078+
<<interface>> WithRequestAuthenticationInterface
10691079
<<Enumeration>> CapabilityEnum
10701080
<<Enumeration>> OptionEnum
10711081
<<Enumeration>> ProviderTypeEnum
@@ -1074,6 +1084,7 @@ direction LR
10741084
ProviderInterface "1" *-- "1" ProviderMetadata
10751085
ProviderInterface "1" *-- "1" ProviderAvailabilityInterface
10761086
ProviderInterface "1" *-- "1" ModelMetadataDirectoryInterface
1087+
ProviderWithOperationsHandlerInterface "1" *-- "1" ProviderOperationsHandlerInterface
10771088
ModelInterface "1" *-- "1" ModelMetadata
10781089
ModelInterface "1" *-- "1" ModelConfig
10791090
ProviderModelsMetadata "1" o-- "1" ProviderMetadata

‎src/Providers/Contracts/ProviderOperationsHandlerInterface.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
namespace WordPress\AiClient\Providers\Contracts;
66

77
use InvalidArgumentException;
8-
use WordPress\AiClient\Operations\DTO\GenerativeAiOperation;
8+
use WordPress\AiClient\Operations\Contracts\OperationInterface;
99

1010
/**
1111
* Interface for handling provider-level operations.
@@ -24,8 +24,8 @@ interface ProviderOperationsHandlerInterface
2424
* @since n.e.x.t
2525
*
2626
* @param string $operationId Operation identifier.
27-
* @return GenerativeAiOperation The operation.
27+
* @return OperationInterface The operation.
2828
* @throws InvalidArgumentException If operation not found.
2929
*/
30-
public function getOperation(string $operationId): GenerativeAiOperation;
30+
public function getOperation(string $operationId): OperationInterface;
3131
}

‎src/Tools/DTO/FunctionCall.php‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ public function __construct(?string $id = null, ?string $name = null, array $arg
6565
*
6666
* @since n.e.x.t
6767
*
68-
* @return string|null The unique identifier.
68+
* @return string|null The function call ID.
6969
*/
7070
public function getId(): ?string
7171
{

‎src/Tools/DTO/FunctionResponse.php‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -59,9 +59,9 @@ public function __construct(string $id, string $name, $response)
5959
*
6060
* @since n.e.x.t
6161
*
62-
* @return string The function call ID.
62+
* @return string|null The function call ID.
6363
*/
64-
public function getId(): string
64+
public function getId(): ?string
6565
{
6666
return $this->id;
6767
}
@@ -71,9 +71,9 @@ public function getId(): string
7171
*
7272
* @since n.e.x.t
7373
*
74-
* @return string The function name.
74+
* @return string|null The function name.
7575
*/
76-
public function getName(): string
76+
public function getName(): ?string
7777
{
7878
return $this->name;
7979
}

0 commit comments

Comments
 (0)