Skip to content

Commit 6a29ffc

Browse files
felixarntzfelixarntz
authored
Merge pull request #12 from borkweb/add/fluent-code-examples
Add fluent API code examples to architecture documentation
2 parents 2d981a6 + 1187c10 commit 6a29ffc

File tree

1 file changed

+115
-21
lines changed

1 file changed

+115
-21
lines changed

‎docs/ARCHITECTURE.md

Lines changed: 115 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,13 @@ The following examples indicate how this SDK could eventually be used.
1919

2020
#### Generate text using any suitable model from any provider (most basic example)
2121

22+
##### Fluent API
23+
```php
24+
$text = AiClient::prompt('Write a 2-verse poem about PHP.')
25+
->generateText();
26+
```
27+
28+
##### Traditional API
2229
```php
2330
$text = AiClient::generateTextResult(
2431
'Write a 2-verse poem about PHP.'
@@ -27,6 +34,14 @@ $text = AiClient::generateTextResult(
2734

2835
#### Generate text using a Google model
2936

37+
##### Fluent API
38+
```php
39+
$text = AiClient::prompt('Write a 2-verse poem about PHP.')
40+
->usingModel(Google::model('gemini-2.5-flash'))
41+
->generateText();
42+
```
43+
44+
##### Traditional API
3045
```php
3146
$text = AiClient::generateTextResult(
3247
'Write a 2-verse poem about PHP.',
@@ -36,6 +51,14 @@ $text = AiClient::generateTextResult(
3651

3752
#### Generate multiple text candidates using an Anthropic model
3853

54+
##### Fluent API
55+
```php
56+
$texts = AiClient::prompt('Write a 2-verse poem about PHP.')
57+
->usingModel(Anthropic::model('claude-3.7-sonnet'))
58+
->generateTexts(4);
59+
```
60+
61+
##### Traditional API
3962
```php
4063
$texts = AiClient::generateTextResult(
4164
'Write a 2-verse poem about PHP.',
@@ -48,6 +71,14 @@ $texts = AiClient::generateTextResult(
4871

4972
#### Generate an image using any suitable OpenAI model
5073

74+
##### Fluent API
75+
```php
76+
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
77+
->usingProvider('openai')
78+
->generateImage();
79+
```
80+
81+
##### Traditional API
5182
```php
5283
$modelsMetadata = AiClient::defaultRegistry()->findProviderModelsMetadataForSupport(
5384
'openai',
@@ -64,6 +95,13 @@ $imageFile = AiClient::generateImageResult(
6495

6596
#### Generate an image using any suitable model from any provider
6697

98+
##### Fluent API
99+
```php
100+
$imageFile = AiClient::prompt('Generate an illustration of the PHP elephant in the Carribean sea.')
101+
->generateImage();
102+
```
103+
104+
##### Traditional API
67105
```php
68106
$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
69107
new AiModelRequirements([AiCapability::IMAGE_GENERATION])
@@ -81,6 +119,23 @@ $imageFile = AiClient::generateImageResult(
81119

82120
_Note: This does effectively the exact same as [the first code example](#generate-text-using-any-suitable-model-from-any-provider-most-basic-example), but more verbosely. In other words, if you omit the model parameter, the SDK will do this internally._
83121

122+
##### Fluent API
123+
```php
124+
$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
125+
new AiModelRequirements([AiCapability::TEXT_GENERATION])
126+
);
127+
128+
$text = AiClient::prompt('Write a 2-verse poem about PHP.')
129+
->withModel(
130+
AiClient::defaultRegistry()->getProviderModel(
131+
$providerModelsMetadata[0]->getProvider()->getId(),
132+
$providerModelsMetadata[0]->getModels()[0]->getId()
133+
)
134+
)
135+
->generateText();
136+
```
137+
138+
##### Traditional API
84139
```php
85140
$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
86141
new AiModelRequirements([AiCapability::TEXT_GENERATION])
@@ -98,6 +153,14 @@ $text = AiClient::generateTextResult(
98153

99154
_Note: Since this omits the model parameter, the SDK will automatically determine which models are suitable and use any of them, similar to [the first code example](#generate-text-using-any-suitable-model-from-any-provider-most-basic-example). Since it knows the input includes an image, it can internally infer that the model needs to not only support `AiCapability::TEXT_GENERATION`, but also `AiOption::INPUT_MODALITIES => ['text', 'image']`._
100155

156+
##### Fluent API
157+
```php
158+
$text = AiClient::prompt('Generate alternative text for this image.')
159+
->withInlineImage($base64Blob, 'image/png')
160+
->generateText();
161+
```
162+
163+
##### Traditional API
101164
```php
102165
$text = AiClient::generateTextResult(
103166
[
@@ -116,6 +179,18 @@ $text = AiClient::generateTextResult(
116179

117180
_Note: Similarly to the previous example, even without specifying the model here, the SDK will be able to infer required model capabilities because it can detect that multiple chat messages are passed. Therefore it will internally only consider models that support `AiCapability::TEXT_GENERATION` as well as `AiCapability::CHAT_HISTORY`._
118181

182+
##### Fluent API
183+
```php
184+
$text = AiClient::prompt()
185+
->withHistory(
186+
new UserMessage('Do you spell it WordPress or Wordpress?'),
187+
new AgentMessage('The correct spelling is WordPress.'),
188+
)
189+
->withText('Can you repeat that please?')
190+
->generateText();
191+
```
192+
193+
##### Traditional API
119194
```php
120195
$text = AiClient::generateTextResult(
121196
[
@@ -139,6 +214,28 @@ $text = AiClient::generateTextResult(
139214

140215
_Note: Unlike the previous two examples, to require JSON output it is necessary to go the verbose route, since it is impossible for the SDK to detect whether you require JSON output purely from the prompt input. Therefore this code example contains the logic to manually search for suitable models and then use one of them for the task._
141216

217+
##### Fluent API
218+
```php
219+
$text = AiClient::prompt('Transform the following CSV content into a JSON array of row data.')
220+
->asJsonResponse()
221+
->usingOutputSchema([
222+
'type' => 'array',
223+
'items' => [
224+
'type' => 'object',
225+
'properties' => [
226+
'name' => [
227+
'type' => 'string',
228+
],
229+
'age' => [
230+
'type' => 'integer',
231+
],
232+
],
233+
],
234+
])
235+
->generateText();
236+
```
237+
238+
##### Traditional API
142239
```php
143240
$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
144241
new AiModelRequirements(
@@ -176,25 +273,6 @@ $jsonString = AiClient::generateTextResult(
176273
)->toText();
177274
```
178275

179-
#### Generate embeddings using any suitable model from any provider
180-
181-
```php
182-
$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
183-
new AiModelRequirements([AiCapability::EMBEDDING_GENERATION])
184-
);
185-
$embeddings = AiClient::generateEmbeddingsResult(
186-
[
187-
'A very long text.',
188-
'Another very long text.',
189-
'More long text.',
190-
],
191-
AiClient::defaultRegistry()->getProviderModel(
192-
$providerModelsMetadata[0]->getProvider()->getId(),
193-
$providerModelsMetadata[0]->getModels()[0]->getId()
194-
)
195-
)->getEmbeddings();
196-
```
197-
198276
## Class diagrams
199277

200278
This section shows comprehensive class diagrams for the proposed architecture. For explanation on specific terms, see the [glossary](./GLOSSARY.md).
@@ -217,12 +295,15 @@ classDiagram
217295
direction LR
218296
namespace AiClient {
219297
class AiClient {
220-
+prompt(?string $text) PromptBuilder$
298+
+prompt(string|Message|null $text = null) PromptBuilder$
221299
+message(?string $text) MessageBuilder$
222300
}
223301
224302
class PromptBuilder {
225303
+withText(string $text) self
304+
+withInlineImage(string $base64Blob, string $mimeType)
305+
+withLocalImage(string $path, string $mimeType)
306+
+withRemoteImage(string $uri, string $mimeType)
226307
+withImageFile(File $file) self
227308
+withAudioFile(File $file) self
228309
+withVideoFile(File $file) self
@@ -240,6 +321,7 @@ direction LR
240321
+usingOutputMime(string $mimeType) self
241322
+usingOutputSchema(array< string, mixed > $schema) self
242323
+usingOutputModalities(...AiModality $modalities) self
324+
+asJsonResponse(?array< string, mixed > $schema) self
243325
+generateResult() GenerativeAiResult
244326
+generateOperation() GenerativeAiOperation
245327
+generateTextResult() GenerativeAiResult
@@ -254,10 +336,14 @@ direction LR
254336
+generateSpeechOperation() GenerativeAiOperation
255337
+generateEmbeddingsOperation() EmbeddingOperation
256338
+generateText() string
339+
+generateTexts(?int $candidateCount) string[]
257340
+streamGenerateText() Generator< string >
258341
+generateImage() File
342+
+generateImages(?int $candidateCount) File[]
259343
+convertTextToSpeech() File
344+
+convertTextToSpeeches(?int $candidateCount) File[]
260345
+generateSpeech() File
346+
+generateSpeeches(?int $candidateCount) File[]
261347
+generateEmbeddings() Embedding[]
262348
+getModelRequirements() AiModelRequirements
263349
+isSupported() bool
@@ -356,7 +442,7 @@ classDiagram
356442
direction LR
357443
namespace AiClient {
358444
class AiClient {
359-
+prompt(?string $text) PromptBuilder$
445+
+prompt(string|Message|null $text = null) PromptBuilder$
360446
+message(?string $text) MessageBuilder$
361447
+defaultRegistry() AiProviderRegistry$
362448
+isConfigured(AiProviderAvailability $availability) bool$
@@ -377,6 +463,9 @@ direction LR
377463
378464
class PromptBuilder {
379465
+withText(string $text) self
466+
+withInlineImage(string $base64Blob, string $mimeType)
467+
+withLocalImage(string $path, string $mimeType)
468+
+withRemoteImage(string $uri, string $mimeType)
380469
+withImageFile(File $file) self
381470
+withAudioFile(File $file) self
382471
+withVideoFile(File $file) self
@@ -394,6 +483,7 @@ direction LR
394483
+usingOutputMime(string $mimeType) self
395484
+usingOutputSchema(array< string, mixed > $schema) self
396485
+usingOutputModalities(...AiModality $modalities) self
486+
+asJsonResponse(?array< string, mixed > $schema) self
397487
+generateResult() GenerativeAiResult
398488
+generateOperation() GenerativeAiOperation
399489
+generateTextResult() GenerativeAiResult
@@ -408,10 +498,14 @@ direction LR
408498
+generateSpeechOperation() GenerativeAiOperation
409499
+generateEmbeddingsOperation() EmbeddingOperation
410500
+generateText() string
501+
+generateTexts(?int $candidateCount) string[]
411502
+streamGenerateText() Generator< string >
412503
+generateImage() File
504+
+generateImages(?int $candidateCount) File[]
413505
+convertTextToSpeech() File
506+
+convertTextToSpeeches(?int $candidateCount) File[]
414507
+generateSpeech() File
508+
+generateSpeeches(?int $candidateCount) File[]
415509
+generateEmbeddings() Embedding[]
416510
+getModelRequirements() AiModelRequirements
417511
+isSupported() bool

0 commit comments

Comments
 (0)