Skip to content

Commit 71f3594

Browse files
JasonTheAdamsJasonTheAdams
committed
Merge remote-tracking branch 'origin/trunk' into add-http-client-and-auth
2 parents b9af770 + b1999c1 commit 71f3594

File tree

10 files changed

+391
-85
lines changed

10 files changed

+391
-85
lines changed

‎CONTRIBUTING.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ The following naming conventions must be followed for consistency and autoloadin
1616
- Traits are suffixed with `Trait`.
1717
- Enums are suffixed with `Enum`.
1818
- File names are the same as the class, trait, and interface name for PSR-4 autoloading.
19-
- Classes, interfaces, and traits, and namespaces are not prefixed with `Ai`, exluding the root namespace.
19+
- Classes, interfaces, and traits, and namespaces are not prefixed with `Ai`, excluding the root namespace.
2020

2121
## Documentation standards
2222

‎docs/ARCHITECTURE.md

Lines changed: 103 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ $texts = AiClient::generateTextResult(
7373

7474
##### Fluent API
7575
```php
76-
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
76+
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Caribbean sea.')
7777
->usingProvider('openai')
7878
->generateImage();
7979
```
@@ -85,7 +85,7 @@ $modelsMetadata = AiClient::defaultRegistry()->findProviderModelsMetadataForSupp
8585
new ModelRequirements([CapabilityEnum::IMAGE_GENERATION])
8686
);
8787
$imageFile = AiClient::generateImageResult(
88-
'Generate an illustration of the PHP elephant in the Carribean sea.',
88+
'Generate an illustration of the PHP elephant in the Caribbean sea.',
8989
AiClient::defaultRegistry()->getProviderModel(
9090
'openai',
9191
$modelsMetadata[0]->getId()
@@ -97,7 +97,7 @@ $imageFile = AiClient::generateImageResult(
9797

9898
##### Fluent API
9999
```php
100-
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
100+
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Caribbean sea.')
101101
->generateImage();
102102
```
103103

@@ -107,7 +107,7 @@ $providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupp
107107
new ModelRequirements([CapabilityEnum::IMAGE_GENERATION])
108108
);
109109
$imageFile = AiClient::generateImageResult(
110-
'Generate an illustration of the PHP elephant in the Carribean sea.',
110+
'Generate an illustration of the PHP elephant in the Caribbean sea.',
111111
AiClient::defaultRegistry()->getProviderModel(
112112
$providerModelsMetadata[0]->getProvider()->getId(),
113113
$providerModelsMetadata[0]->getModels()[0]->getId()
@@ -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 {
537+
class File {
538+
+getFileType() FileTypeEnum
545539
+getMimeType() string
546-
+getBase64Data() string
540+
+getUrl() ?string
541+
+getBase64Data() ?string
547542
+getJsonSchema() array< string, mixed >$
548543
}
549-
class LocalFile {
550-
+getMimeType() string
551-
+getPath() string
552-
+getJsonSchema() array< string, mixed >$
553-
}
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
@@ -985,23 +970,25 @@ direction LR
985970
}
986971
987972
namespace AiClientNamespace.Providers.Contracts {
988-
class AuthenticationInterface {
989-
+authenticate(Request $request) void
990-
+getJsonSchema() array< string, mixed >$
991-
}
992973
class ModelMetadataDirectoryInterface {
993974
+listModelMetadata() ModelMetadata[]
994975
+hasModelMetadata(string $modelId) bool
995976
+getModelMetadata(string $modelId) ModelMetadata
996977
}
978+
class ProviderAvailabilityInterface {
979+
+isConfigured() bool
980+
}
997981
class ProviderInterface {
998982
+metadata() ProviderMetadata$
999983
+model(string $modelId, ModelConfig|array< string, mixed > $modelConfig) ModelInterface$
1000984
+availability() ProviderAvailabilityInterface$
1001985
+modelMetadataDirectory() ModelMetadataDirectoryInterface$
1002986
}
1003-
class ProviderAvailabilityInterface {
1004-
+isConfigured() bool
987+
class ProviderOperationsHandlerInterface {
988+
+getOperation(string $operationId) OperationInterface
989+
}
990+
class ProviderWithOperationsHandlerInterface {
991+
+operationsHandler() ProviderOperationsHandlerInterface$
1005992
}
1006993
}
1007994
@@ -1031,19 +1018,51 @@ direction LR
10311018
}
10321019
}
10331020
1021+
namespace AiClientNamespace.Providers.Http.Contracts {
1022+
class HttpTransporterInterface {
1023+
+send(Request $request) Response
1024+
}
1025+
class RequestAuthenticationInterface {
1026+
+authenticate(Request $request) void
1027+
+getJsonSchema() array< string, mixed >$
1028+
}
1029+
class WithHttpTransporterInterface {
1030+
+setHttpTransporter(HttpTransporterInterface $transporter) void
1031+
+getHttpTransporter() HttpTransporterInterface
1032+
}
1033+
class WithRequestAuthenticationInterface {
1034+
+setRequestAuthentication(RequestAuthenticationInterface $authentication) void
1035+
+getRequestAuthentication() RequestAuthenticationInterface
1036+
}
1037+
}
1038+
1039+
namespace AiClientNamespace.Providers.Http.DTO {
1040+
class Request {
1041+
+getMethod() string
1042+
+getUri() string
1043+
+getHeaders() array< string, string[] >
1044+
+getBody() ?string
1045+
+getData() ?array< string, mixed >
1046+
+getJsonSchema() array< string, mixed >$
1047+
}
1048+
1049+
class Response {
1050+
+getStatusCode() int
1051+
+getHeaders() array< string, string[] >
1052+
+getBody() ?string
1053+
+getData() ?array< string, mixed >
1054+
+getJsonSchema() array< string, mixed >$
1055+
}
1056+
}
1057+
10341058
namespace AiClientNamespace.Providers.Models.Contracts {
10351059
class ModelInterface {
10361060
+metadata() ModelMetadata
10371061
+setConfig(ModelConfig $config) void
10381062
+getConfig() ModelConfig
10391063
}
1040-
class WithAuthenticationInterface {
1041-
+setAuthentication(AuthenticationInterface $authentication) void
1042-
+getAuthentication() AuthenticationInterface
1043-
}
1044-
class WithHttpTransporterInterface {
1045-
+setHttpTransporter(HttpTransporterInterface $transporter) void
1046-
+getHttpTransporter() HttpTransporterInterface
1064+
class WithEmbeddingOperationsInterface {
1065+
+getOperation(string $operationId) EmbeddingOperation
10471066
}
10481067
}
10491068
@@ -1192,6 +1211,9 @@ direction LR
11921211
<<interface>> ModelInterface
11931212
<<interface>> ProviderAvailabilityInterface
11941213
<<interface>> ModelMetadataDirectoryInterface
1214+
<<interface>> ProviderOperationsHandlerInterface
1215+
<<interface>> ProviderWithOperationsHandlerInterface
1216+
<<interface>> WithEmbeddingOperationsInterface
11951217
<<interface>> TextGenerationModelInterface
11961218
<<interface>> ImageGenerationModelInterface
11971219
<<interface>> TextToSpeechConversionModelInterface
@@ -1200,9 +1222,11 @@ direction LR
12001222
<<interface>> ImageGenerationOperationModelInterface
12011223
<<interface>> TextToSpeechConversionOperationModelInterface
12021224
<<interface>> SpeechGenerationOperationModelInterface
1225+
<<interface>> EmbeddingGenerationOperationModelInterface
1226+
<<interface>> HttpTransporterInterface
12031227
<<interface>> WithHttpTransporterInterface
1204-
<<interface>> WithAuthenticationInterface
1205-
<<interface>> AuthenticationInterface
1228+
<<interface>> RequestAuthenticationInterface
1229+
<<interface>> WithRequestAuthenticationInterface
12061230
<<Enumeration>> CapabilityEnum
12071231
<<Enumeration>> OptionEnum
12081232
<<Enumeration>> ProviderTypeEnum
@@ -1211,6 +1235,7 @@ direction LR
12111235
ProviderInterface "1" *-- "1" ProviderMetadata
12121236
ProviderInterface "1" *-- "1" ProviderAvailabilityInterface
12131237
ProviderInterface "1" *-- "1" ModelMetadataDirectoryInterface
1238+
ProviderWithOperationsHandlerInterface "1" *-- "1" ProviderOperationsHandlerInterface
12141239
ModelInterface "1" *-- "1" ModelMetadata
12151240
ModelInterface "1" *-- "1" ModelConfig
12161241
ProviderModelsMetadata "1" o-- "1" ProviderMetadata

‎docs/REQUIREMENTS.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ There are two primary developer audiences this client is intended for. This is i
88

99
### Extenders
1010

11-
Extenders are the folks that will be adding providers, models, and otherwise extending the functionality of the client itself. These are highly technical people who likely have a stronger understanding of how models and model APIs work. Given their capabilities, these APIs will be more technical and formal in nature, using things such as interfaces, traits, and so forth, relying on a knowledge of inheritence and composition.
11+
Extenders are the folks that will be adding providers, models, and otherwise extending the functionality of the client itself. These are highly technical people who likely have a stronger understanding of how models and model APIs work. Given their capabilities, these APIs will be more technical and formal in nature, using things such as interfaces, traits, and so forth, relying on a knowledge of inheritance and composition.
1212

1313
### Implementers
1414

0 commit comments

Comments
 (0)