[Platform] Fatal Error: array_merge() called with string payload in ModelClient implementations

[RamyHakam]

Description:

The ModelClientInterface defines $payload as array|string but many implementations use array_merge($payload, $options) without type checking, causing fatal errors when a string payload is passed.

Affected Files

Multiple ModelClient implementations fail to handle string payloads properly,

Current Behavior

Interface allows: request(Model $model, array|string $payload, array $options = [])
Many implementations call: array_merge($payload, $options)
Result: Fatal error when $payload is string: array_merge(): Expected parameter 1 to be an array, string given

Expected Behavior

All implementations should handle both array and string payloads consistently.
Inconsistent Implementation
Some implementations handle this correctly:

Albert/EmbeddingsModelClient.php:45
Albert/GptModelClient.php:50
Cerebras/ModelClient.php:58

These use: \is_array($payload) ? array_merge($payload, $options) : $payload
Or assigning the payload to ['input => $payload] before merge
But many others don't perform this check.

[RamyHakam]

I’ve checked all the implementations of this method, and they all accept the payload as an array. There’s no need to use a string type here.

If we want to support JSON as a string payload input, we can convert the given array to JSON directly. This approach is already used in several implementations of the ModelClientInterface

[chr-hertel]

The ModelClientInterface defines $payload as array|string but many implementations use array_merge($payload, $options) without type checking, causing fatal errors when a string payload is passed.

I agree that this string|array thing is a bit brittle and might be error prone. I'd be interested how you ended up with that fatal error tho - so we can use that as starting point for a solution.

One scenario that I can see is when using code like that:

require_once dirname(__DIR__).'/bootstrap.php';

$platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
$result = $platform->invoke(new Gpt(), 'Hi');

echo $result->asText().\PHP_EOL;

And, to be honest, I would love to enable that kind of usage. Why should I need to create a complex object setup like

$result = $platform->invoke(new Gpt(), new MessageBag(
    Message::ofUser('Hi'),
));

---

in general the platform's contract - especially that argument array|string|object $input and vague ResultPromise return type are not that great at first, but in the end it's still intuitive since you select the model you want to use first anyways

[RamyHakam]

This is exactly how I hit the fatal error.
After checking the implementations, none of these clients validate the payload type before using array_merge()
That affects different clients

OpenAI: GptModelClient, WhisperModelClient, ClaudeModelClient
Anthropic: ModelClient
Azure: LlamaModelClient
Amazon: NovaModelClient
Google: Gemini ModelClient
LmStudio: Completion ModelClient

I agree with supporting the simple string usage - that's what I tried first for convenience.
If we want to support string payloads as promised by the interface, we should either:

Add type checking in each implementation (like what we did in some Clients)
Enforce implementers to implement a new function to generate the Request Payload and handle it with their logic

[chr-hertel]

Okay, if you're up for it, here are the steps that we should do:

1. introduce a similar concept like the Agent's Input-/OutputProcessor in the Platform class - maybe rather event based? like PlatformInvokationEvent that allows subscribers/listeners to mess with the $input var
2. than implement a listener that based on the input type (string) and the models capability (INPUT_MESSAGES) does an upcasting from string to MessageBag similar to this:

   $event->setInput(new MessageBag(Message::ofUser($input)));

that would be my solution strategy here
and the bonus: we could shift some of the functionality from input/output processors that we miss in platform, e.g. structured output (def another PR 😆)

@OskarStark your thoughts on that?