Unify options key for structured output to response_format

chr-hertel · chr-hertel · commit 0f13dd376eca · 2025-11-14T21:25:09.000+01:00
diff --git a/docs/components/platform.rst b/docs/components/platform.rst
@@ -310,14 +310,14 @@ To achieve this, the ``Symfony\AI\Platform\StructuredOutput\PlatformSubscriber``
         Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
         Message::ofUser('how can I solve 8x + 7 = -23'),
     );
-    $result = $platform->invoke('mistral-small-latest', $messages, ['output_structure' => MathReasoning::class]);
+    $result = $platform->invoke('mistral-small-latest', $messages, ['response_format' => MathReasoning::class]);
 
     dump($result->asObject()); // returns an instance of `MathReasoning` class
 
 Array Structures as Output
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Also PHP array structures as response_format are supported, which also requires the event subscriber mentioned above. On
+Also PHP array structures as `response_format` are supported, which also requires the event subscriber mentioned above. On
 top this example uses the feature through the agent to leverage tool calling::
 
     use Symfony\AI\Platform\Message\Message;
diff --git a/examples/gemini/structured-output-math.php b/examples/gemini/structured-output-math.php
@@ -27,6 +27,6 @@
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
 
-$result = $platform->invoke('gemini-2.5-flash', $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke('gemini-2.5-flash', $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/examples/mistral/structured-output-math.php b/examples/mistral/structured-output-math.php
@@ -26,6 +26,6 @@
     Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
-$result = $platform->invoke('mistral-small-latest', $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke('mistral-small-latest', $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/examples/ollama/structured-output-math.php b/examples/ollama/structured-output-math.php
@@ -26,6 +26,6 @@
     Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
-$result = $platform->invoke(env('OLLAMA_LLM'), $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke(env('OLLAMA_LLM'), $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/examples/openai/structured-output-list-of-polymorphic-items.php b/examples/openai/structured-output-list-of-polymorphic-items.php
@@ -26,6 +26,6 @@
     Message::forSystem('You are a persona data collector! Return all the data you can gather from the user input.'),
     Message::ofUser('Hi! My name is John Doe, I am 30 years old and I live in Paris.'),
 );
-$result = $platform->invoke('gpt-4o-mini', $messages, ['output_structure' => ListOfPolymorphicTypesDto::class]);
+$result = $platform->invoke('gpt-4o-mini', $messages, ['response_format' => ListOfPolymorphicTypesDto::class]);
 
 dump($result->asObject());
diff --git a/examples/openai/structured-output-math.php b/examples/openai/structured-output-math.php
@@ -27,6 +27,6 @@
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
 
-$result = $platform->invoke('gpt-4o-mini', $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke('gpt-4o-mini', $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/examples/openai/structured-output-union-types.php b/examples/openai/structured-output-union-types.php
@@ -29,6 +29,6 @@
     PROMPT),
     Message::ofUser('What is the current time?'),
 );
-$result = $platform->invoke('gpt-4o-mini', $messages, ['output_structure' => UnionTypeDto::class]);
+$result = $platform->invoke('gpt-4o-mini', $messages, ['response_format' => UnionTypeDto::class]);
 
 dump($result->asObject());
diff --git a/examples/scaleway/structured-output-math.php b/examples/scaleway/structured-output-math.php
@@ -27,6 +27,6 @@
     Message::forSystem('You are a helpful math tutor. Guide the user through the solution step by step.'),
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
-$result = $platform->invoke('gpt-oss-120b', $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke('gpt-oss-120b', $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/examples/vertexai/structured-output-math.php b/examples/vertexai/structured-output-math.php
@@ -27,6 +27,6 @@
     Message::ofUser('how can I solve 8x + 7 = -23'),
 );
 
-$result = $platform->invoke('gemini-2.5-flash-lite', $messages, ['output_structure' => MathReasoning::class]);
+$result = $platform->invoke('gemini-2.5-flash-lite', $messages, ['response_format' => MathReasoning::class]);
 
 dump($result->asObject());
diff --git a/src/agent/src/MultiAgent/MultiAgent.php b/src/agent/src/MultiAgent/MultiAgent.php
@@ -81,7 +81,7 @@ public function call(MessageBag $messages, array $options = []): ResultInterface
         $agentSelectionPrompt = $this->buildAgentSelectionPrompt($userText);
 
         $decision = $this->orchestrator->call(new MessageBag(Message::ofUser($agentSelectionPrompt)), array_merge($options, [
-            'output_structure' => Decision::class,
+            'response_format' => Decision::class,
         ]))->getContent();
 
         if (!$decision instanceof Decision) {
diff --git a/src/agent/tests/MultiAgent/MultiAgentTest.php b/src/agent/tests/MultiAgent/MultiAgentTest.php
@@ -247,7 +247,7 @@ public function testCallPassesOptionsToAgents()
                 $this->isInstanceOf(MessageBag::class),
                 $this->callback(fn ($opts) => isset($opts['temperature']) && 0.7 === $opts['temperature']
                     && isset($opts['max_tokens']) && 100 === $opts['max_tokens']
-                    && isset($opts['output_structure']) && Decision::class === $opts['output_structure']
+                    && isset($opts['response_format']) && Decision::class === $opts['response_format']
                 )
             )
             ->willReturn($orchestratorResult);
diff --git a/src/platform/src/Bridge/Gemini/Gemini/ModelClient.php b/src/platform/src/Bridge/Gemini/Gemini/ModelClient.php
@@ -15,6 +15,7 @@
 use Symfony\AI\Platform\Model;
 use Symfony\AI\Platform\ModelClientInterface;
 use Symfony\AI\Platform\Result\RawHttpResult;
+use Symfony\AI\Platform\StructuredOutput\PlatformSubscriber;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -49,10 +50,10 @@ public function request(Model $model, array|string $payload, array $options = []
             $options['stream'] ?? false ? 'streamGenerateContent' : 'generateContent',
         );
 
-        if (isset($options['response_format']['json_schema']['schema'])) {
+        if (isset($options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'])) {
             $options['responseMimeType'] = 'application/json';
-            $options['responseJsonSchema'] = $options['response_format']['json_schema']['schema'];
-            unset($options['response_format']);
+            $options['responseJsonSchema'] = $options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'];
+            unset($options[PlatformSubscriber::RESPONSE_FORMAT]);
         }
 
         $generationConfig = ['generationConfig' => $options];
diff --git a/src/platform/src/Bridge/Ollama/OllamaClient.php b/src/platform/src/Bridge/Ollama/OllamaClient.php
@@ -15,6 +15,7 @@
 use Symfony\AI\Platform\Model;
 use Symfony\AI\Platform\ModelClientInterface;
 use Symfony\AI\Platform\Result\RawHttpResult;
+use Symfony\AI\Platform\StructuredOutput\PlatformSubscriber;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
 
 /**
@@ -63,9 +64,9 @@ private function doCompletionRequest(array|string $payload, array $options = [])
         // Revert Ollama's default streaming behavior
         $options['stream'] ??= false;
 
-        if (\array_key_exists('response_format', $options) && \array_key_exists('json_schema', $options['response_format'])) {
-            $options['format'] = $options['response_format']['json_schema']['schema'];
-            unset($options['response_format']);
+        if (isset($options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'])) {
+            $options['format'] = $options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'];
+            unset($options[PlatformSubscriber::RESPONSE_FORMAT]);
         }
 
         return new RawHttpResult($this->httpClient->request('POST', \sprintf('%s/api/chat', $this->hostUrl), [
diff --git a/src/platform/src/Bridge/OpenAi/DallE/ResultConverter.php b/src/platform/src/Bridge/OpenAi/DallE/ResultConverter.php
@@ -17,6 +17,7 @@
 use Symfony\AI\Platform\Result\RawResultInterface;
 use Symfony\AI\Platform\Result\ResultInterface;
 use Symfony\AI\Platform\ResultConverterInterface;
+use Symfony\AI\Platform\StructuredOutput\PlatformSubscriber;
 
 /**
  * @see https://platform.openai.com/docs/api-reference/images/create
@@ -40,7 +41,7 @@ public function convert(RawResultInterface $result, array $options = []): Result
 
         $images = [];
         foreach ($result['data'] as $image) {
-            if ('url' === $options['response_format']) {
+            if ('url' === $options[PlatformSubscriber::RESPONSE_FORMAT]) {
                 $images[] = new UrlImage($image['url']);
 
                 continue;
diff --git a/src/platform/src/Bridge/VertexAi/Gemini/ModelClient.php b/src/platform/src/Bridge/VertexAi/Gemini/ModelClient.php
@@ -14,6 +14,7 @@
 use Symfony\AI\Platform\Model as BaseModel;
 use Symfony\AI\Platform\ModelClientInterface;
 use Symfony\AI\Platform\Result\RawHttpResult;
+use Symfony\AI\Platform\StructuredOutput\PlatformSubscriber;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
 use Symfony\Contracts\HttpClient\Exception\TransportExceptionInterface;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -51,11 +52,11 @@ public function request(BaseModel $model, array|string $payload, array $options
             $options['stream'] ?? false ? 'streamGenerateContent' : 'generateContent',
         );
 
-        if (isset($options['response_format']['json_schema']['schema'])) {
+        if (isset($options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'])) {
             $options['generationConfig']['responseMimeType'] = 'application/json';
-            $options['generationConfig']['responseSchema'] = $options['response_format']['json_schema']['schema'];
+            $options['generationConfig']['responseSchema'] = $options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'];
 
-            unset($options['response_format']);
+            unset($options[PlatformSubscriber::RESPONSE_FORMAT]);
         }
 
         if (isset($options['generationConfig'])) {
diff --git a/src/platform/src/StructuredOutput/PlatformSubscriber.php b/src/platform/src/StructuredOutput/PlatformSubscriber.php
@@ -36,7 +36,9 @@
  */
 final class PlatformSubscriber implements EventSubscriberInterface
 {
-    private string $outputStructure;
+    public const RESPONSE_FORMAT = 'response_format';
+
+    private string $outputType;
 
     public function __construct(
         private readonly ResponseFormatFactoryInterface $responseFormatFactory = new ResponseFormatFactory(),
@@ -79,22 +81,27 @@ public function processInput(InvocationEvent $event): void
     {
         $options = $event->getOptions();
 
-        if (!isset($options['output_structure'])) {
+        if (!isset($options[self::RESPONSE_FORMAT])) {
             return;
         }
 
-        if (!$event->getModel()->supports(Capability::OUTPUT_STRUCTURED)) {
-            throw MissingModelSupportException::forStructuredOutput($event->getModel()::class);
-        }
-
         if (true === ($options['stream'] ?? false)) {
             throw new InvalidArgumentException('Streamed responses are not supported for structured output.');
         }
 
-        $options['response_format'] = $this->responseFormatFactory->create($options['output_structure']);
+        if (\is_string($options[self::RESPONSE_FORMAT])) {
+            if (!$event->getModel()->supports(Capability::OUTPUT_STRUCTURED)) {
+                throw MissingModelSupportException::forStructuredOutput($event->getModel()::class);
+            }
 
-        $this->outputStructure = $options['output_structure'];
-        unset($options['output_structure']);
+            if (!class_exists($options[self::RESPONSE_FORMAT])) {
+                throw new InvalidArgumentException(\sprintf('The specified response format class "%s" does not exist.', $options[self::RESPONSE_FORMAT]));
+            }
+
+            $this->outputType = $options[self::RESPONSE_FORMAT];
+
+            $options[self::RESPONSE_FORMAT] = $this->responseFormatFactory->create($options[self::RESPONSE_FORMAT]);
+        }
 
         $event->setOptions($options);
     }
@@ -103,12 +110,12 @@ public function processResult(ResultEvent $event): void
     {
         $options = $event->getOptions();
 
-        if (!isset($options['response_format'])) {
+        if (!isset($options[self::RESPONSE_FORMAT])) {
             return;
         }
 
         $deferred = $event->getDeferredResult();
-        $converter = new ResultConverter($deferred->getResultConverter(), $this->serializer, $this->outputStructure ?? null);
+        $converter = new ResultConverter($deferred->getResultConverter(), $this->serializer, $this->outputType ?? null);
 
         $event->setDeferredResult(new DeferredResult($converter, $deferred->getRawResult(), $options));
     }
diff --git a/src/platform/src/StructuredOutput/ResultConverter.php b/src/platform/src/StructuredOutput/ResultConverter.php
@@ -26,7 +26,7 @@ final class ResultConverter implements ResultConverterInterface
     public function __construct(
         private readonly ResultConverterInterface $innerConverter,
         private readonly SerializerInterface $serializer,
-        private readonly ?string $outputClass = null,
+        private readonly ?string $outputType = null,
     ) {
     }
 
@@ -44,12 +44,12 @@ public function convert(RawResultInterface $result, array $options = []): Result
         }
 
         try {
-            $structure = null === $this->outputClass ? json_decode($innerResult->getContent(), true, flags: \JSON_THROW_ON_ERROR)
-                : $this->serializer->deserialize($innerResult->getContent(), $this->outputClass, 'json');
+            $structure = null === $this->outputType ? json_decode($innerResult->getContent(), true, flags: \JSON_THROW_ON_ERROR)
+                : $this->serializer->deserialize($innerResult->getContent(), $this->outputType, 'json');
         } catch (\JsonException $e) {
             throw new RuntimeException('Cannot json decode the content.', previous: $e);
         } catch (SerializerExceptionInterface $e) {
-            throw new RuntimeException(\sprintf('Cannot deserialize the content into the "%s" class.', $this->outputClass), previous: $e);
+            throw new RuntimeException(\sprintf('Cannot deserialize the content into the "%s" class.', $this->outputType), previous: $e);
         }
 
         $objectResult = new ObjectResult($structure);
diff --git a/src/platform/tests/StructuredOutput/PlatformSubscriberTest.php b/src/platform/tests/StructuredOutput/PlatformSubscriberTest.php
@@ -42,7 +42,9 @@ final class PlatformSubscriberTest extends TestCase
     public function testProcessInputWithOutputStructure()
     {
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory(['some' => 'format']));
-        $event = new InvocationEvent(new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]), new MessageBag(), ['output_structure' => 'SomeStructure']);
+        $event = new InvocationEvent(new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]), new MessageBag(), [
+            'response_format' => SomeStructure::class,
+        ]);
 
         $processor->processInput($event);
 
@@ -66,7 +68,7 @@ public function testProcessInputThrowsExceptionWhenLlmDoesNotSupportStructuredOu
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory());
 
         $model = new Model('gpt-3');
-        $event = new InvocationEvent($model, new MessageBag(), ['output_structure' => 'SomeStructure']);
+        $event = new InvocationEvent($model, new MessageBag(), ['response_format' => 'SomeStructure']);
 
         $processor->processInput($event);
     }
@@ -76,7 +78,7 @@ public function testProcessOutputWithResponseFormat()
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory(['some' => 'format']));
 
         $model = new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]);
-        $options = ['output_structure' => SomeStructure::class];
+        $options = ['response_format' => SomeStructure::class];
         $invocationEvent = new InvocationEvent($model, new MessageBag(), $options);
         $processor->processInput($invocationEvent);
 
@@ -98,7 +100,7 @@ public function testProcessOutputWithComplexResponseFormat()
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory(['some' => 'format']));
 
         $model = new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]);
-        $options = ['output_structure' => MathReasoning::class];
+        $options = ['response_format' => MathReasoning::class];
         $invocationEvent = new InvocationEvent($model, new MessageBag(), $options);
         $processor->processInput($invocationEvent);
 
@@ -158,7 +160,7 @@ public function testProcessOutputWithUnionTypeResponseFormat(TextResult $result,
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory(['some' => 'format']));
 
         $model = new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]);
-        $options = ['output_structure' => UnionTypeDto::class];
+        $options = ['response_format' => UnionTypeDto::class];
         $invocationEvent = new InvocationEvent($model, new MessageBag(), $options);
         $processor->processInput($invocationEvent);
 
@@ -205,7 +207,7 @@ public function testProcessOutputWithCorrectPolymorphicTypesResponseFormat()
         $processor = new PlatformSubscriber(new ConfigurableResponseFormatFactory(['some' => 'format']));
 
         $model = new Model('gpt-4', [Capability::OUTPUT_STRUCTURED]);
-        $options = ['output_structure' => ListOfPolymorphicTypesDto::class];
+        $options = ['response_format' => ListOfPolymorphicTypesDto::class];
         $invocationEvent = new InvocationEvent($model, new MessageBag(), $options);
         $processor->processInput($invocationEvent);
 
