Add fluent API code examples to architecture documentation #12

borkweb · 2025-07-12T14:32:39Z

This proposed set of changes to #2 and is doing a few things:

Adding Fluent API code examples (similar to those suggested by @JasonTheAdams here) alongside the Traditional API examples.
Proposing a handful of helper methods to simplify the usage of Candidate Count and avoid implementers from needing to understand what Candidate Count means.
Representing @JasonTheAdams' suggestion of AiClient::withImage(string $mimeType, string $base64Blob) to mimic the input simplicity that the Traditional API supports.
Adding the AiClient::asJsonResponse() and AiClient::asArrayResponse() as a helper methods for usingOutputMime('application/json')
Adding helper methods for specifying models that support a certain capability or option.

Here's the ARCHITECTURE.md file in a readable format.

@JasonTheAdams

This proposed set of changes to WordPress#2 and is doing a few things: 1. Adding Fluent API code examples (similar to those suggested by @JasonTheAdams [here](WordPress#2 (comment))) alongside the Traditional API examples. 2. Proposing a handful of helper methods to simplify the usage of Candidate Count and avoid implementers from needing to understand what _Candidate Count_ means. 3. Representing @JasonTheAdams' suggestion of `AiClient::withImage(string $mimeType, string $base64Blob)` to mimic the input simplicity that the Traditional API supports. 4. Adding the `AiClient::asJsonResponse()` and `AiClient::asArrayResponse()` as a helper methods for `usingOutputMime('application/json')` 5. Adding helper methods for specifying models that support a certain capability or option.

JasonTheAdams · 2025-07-12T16:30:44Z

Thanks, @borkweb! I believe we're actually only going with the Fluent API at this point, with the idea we can add the other API style later if it makes sense to do so.

Is that right, @felixarntz?

borkweb · 2025-07-12T18:28:56Z

Ha! Excellent. That was going to be a question I was going to ask - maintaining both would be laborious

@JasonTheAdams

This is a presumptive change based on [the comment](WordPress#12 (comment)) by @JasonTheAdams in WordPress#12 regarding a potential decision to just go fluent. If that is the intent, then this PR is stripping out the Traditional approach for the implementer API.

felixarntz · 2025-07-12T20:52:48Z

@JasonTheAdams @borkweb

I believe we're actually only going with the Fluent API at this point, with the idea we can add the other API style later if it makes sense to do so.

I think the decision on Thursday was to go with both, in order to compare developer interest/usage in them and eventually decide on the final approach based on that.

The fluent API should be the baseline, and we should start with building that, but the traditional method call API should still be part of the planned architecture. I don't think it's a big lift to wrap the fluent API with it anyway.

I understand and even share your preference for the fluent API, but as discussed on Thursday we should properly consider both APIs with developers especially in the early stages of this SDK.

felixarntz

@borkweb Thank you for the PR! Overall the examples look great, and they very much clarify how to use the fluent API and how the two APIs differ.

I think there are a few things here that need to be revised, please see my comments below.

Note: For the class diagrams, I didn't leave all the same comments again on the duplicate instances of AiClient, PromptBuilder, and MessageBuilder, but please make sure to keep them in sync after making changes. :)

docs/ARCHITECTURE.md

Co-authored-by: Felix Arntz <[email protected]>

…ration methods have a singular return type.

…line images

JasonTheAdams · 2025-07-13T02:53:47Z

I think the decision on Thursday was to go with both, in order to compare developer interest/usage in them and eventually decide on the final approach based on that.

Ah, then I misread what you were saying in Slack. I interpreted that as:

Build this with a Fluent API
Assess how it would be to add a "traditional" API that uses the builder under the hood
Determine whether we do it now or later

docs/ARCHITECTURE.md

felixarntz

A few last follow up questions, but no real blockers. The key thing to decide on still is #12 (comment).

docs/ARCHITECTURE.md

felixarntz · 2025-07-14T17:30:50Z

For reference, sharing here the directly related discussion that happened on Slack: https://wordpress.slack.com/archives/C08TJ8BPULS/p1752512797654719

JasonTheAdams · 2025-07-14T17:32:54Z

docs/ARCHITECTURE.md

+$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(
+    new AiModelRequirements([AiCapability::TEXT_GENERATION])
+);
+
+$text = AiClient::prompt('Write a 2-verse poem about PHP.')
+    ->withModel(
+        AiClient::defaultRegistry()->getProviderModel(
+            $providerModelsMetadata[0]->getProvider()->getId(),
+            $providerModelsMetadata[0]->getModels()[0]->getId()
+        )
+    )
+    ->generateText();


We can simplify this nicely!

Suggested change

$providerModelsMetadata = AiClient::defaultRegistry()->findModelsMetadataForSupport(

new AiModelRequirements([AiCapability::TEXT_GENERATION])

);

$text = AiClient::prompt('Write a 2-verse poem about PHP.')

->withModel(

AiClient::defaultRegistry()->getProviderModel(

$providerModelsMetadata[0]->getProvider()->getId(),

$providerModelsMetadata[0]->getModels()[0]->getId()

)

)

->generateText();

$text = AiClient::prompt('Write a 2-verse poem about PHP.')

->withModelRequirements(AiCapability::TEXT_GENERATION)

->generateText();

@JasonTheAdams I commented before that this is explicitly in a section that shows what happens under the hood / how to do it more verbosely. Since that's the intention here, I don't think we should simplify it again.

That's related to this thread: #12 (comment)

Ahhh, I see. That's true. I'd like to change the wording in the example itself. I can do that in a subsequent PR.

felixarntz

@borkweb Thanks for bearing with me here - this looks excellent! 🎉

JasonTheAdams

It's so fluent and beautiful! 🥹

borkweb mentioned this pull request Jul 12, 2025

Simplify architecture usage down to the Fluent API #13

Closed

felixarntz requested changes Jul 12, 2025

View reviewed changes

Explicitly declare which provider the model is coming from

aa21ba8

Co-authored-by: Felix Arntz <[email protected]>

felixarntz added the [Type] Developer Documentation Documentation for developers label Jul 12, 2025

borkweb added 7 commits July 12, 2025 18:31

Remove the superfluous usingModelSupporting*() methods

b3a0d9c

Use the full schema declaration for JSON

1163c9f

Remove asArrayResponse()

523e811

Remove invalid generate methods and ensure remaining non Result & Ope…

871fc06

…ration methods have a singular return type.

Use withImageFile() along with new InlineFile() for specifying in…

1d0c10f

…line images

Make the chat history example read better top-to-bottom

b86d6d8

Fix order of variadic dots

f5873f7

JasonTheAdams reviewed Jul 13, 2025

View reviewed changes

docs/ARCHITECTURE.md Show resolved Hide resolved

felixarntz reviewed Jul 13, 2025

View reviewed changes

borkweb added 4 commits July 14, 2025 08:50

Adding image convenience methods

985cd42

Use a different prompt structure for chat history to show flexibility

fb446e4

Return multiples when there are multiple candidates

4571237

Set prompt() arg to string|Message. Remove variadic from message()

7e0cbfd

felixarntz reviewed Jul 14, 2025

View reviewed changes

docs/ARCHITECTURE.md Outdated Show resolved Hide resolved

docs/ARCHITECTURE.md Outdated Show resolved Hide resolved

docs/ARCHITECTURE.md Outdated Show resolved Hide resolved

docs/ARCHITECTURE.md Outdated Show resolved Hide resolved

borkweb added 3 commits July 14, 2025 12:57

Keep message() arg optional

8a1a2b8

Make $candidateCount optional for plural generate termination methods

b234aa1

Remove embedding examples - too soon to know what we want

c046ece

Make prompt() non-variadic

1187c10

JasonTheAdams requested changes Jul 14, 2025

View reviewed changes

felixarntz approved these changes Jul 14, 2025

View reviewed changes

JasonTheAdams approved these changes Jul 14, 2025

View reviewed changes

felixarntz merged commit 6a29ffc into WordPress:add/architecture-definition Jul 14, 2025

borkweb deleted the add/fluent-code-examples branch July 14, 2025 17:48

Add fluent API code examples to architecture documentation #12

Add fluent API code examples to architecture documentation #12

Uh oh!

Conversation

borkweb commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JasonTheAdams commented Jul 12, 2025

Uh oh!

borkweb commented Jul 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixarntz commented Jul 12, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

JasonTheAdams commented Jul 13, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz commented Jul 14, 2025

Uh oh!

JasonTheAdams Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

borkweb Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Jul 14, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

borkweb commented Jul 12, 2025 •

edited

Loading

borkweb commented Jul 12, 2025 •

edited

Loading