Migrate from OpenAI chat completions to Responses

Chat completions is deprecated. Responses is the recommended API to use
now.

See: https://platform.openai.com/docs/guides/migrate-to-responses

Author: paulinevos

examples/openai/audio-input.php

@@ -9,14 +9,11 @@
  * file that was distributed with this source code.
  */
 
-use Symfony\AI\Platform\Bridge\OpenAi\PlatformFactory;
-use Symfony\AI\Platform\Message\Content\Audio;
-use Symfony\AI\Platform\Message\Message;
-use Symfony\AI\Platform\Message\MessageBag;
+use Symfony\AI\Platform\Exception\RuntimeException;
 
 require_once dirname(__DIR__).'/bootstrap.php';
 
-throw new RuntimeException('This example is temporarily unavailable due to migration to Responses API (which does not support audio yet)');
+throw new RuntimeException('This example is temporarily unavailable due to migration to Responses API (which does not support audio yet).');
 // $platform = PlatformFactory::create(env('OPENAI_API_KEY'), http_client());
 //
 // $messages = new MessageBag(
@@ -25,6 +22,7 @@
 //        Audio::fromFile(dirname(__DIR__, 2).'/fixtures/audio.mp3'),
 //    ),
 // );
+//
 // $result = $platform->invoke('gpt-4o-audio-preview', $messages);
 //
 // echo $result->asText().\PHP_EOL;

examples/openai/chat-with-string-options.php

@@ -21,6 +21,6 @@
     Message::forSystem('You are a pirate and you write funny.'),
     Message::ofUser('What is the Symfony framework?'),
 );
-$result = $platform->invoke('gpt-4o-mini?max_tokens=7', $messages);
+$result = $platform->invoke('gpt-4o-mini?max_output_tokens=16', $messages);
 
 echo $result->asText().\PHP_EOL;

examples/openai/chat.php

@@ -22,7 +22,7 @@
     Message::ofUser('What is the Symfony framework?'),
 );
 $result = $platform->invoke('gpt-4o-mini', $messages, [
-    'max_tokens' => 500, // specific options just for this call
+    'max_output_tokens' => 500, // specific options just for this call
 ]);
 
 echo $result->asText().\PHP_EOL;

examples/openai/structured-output-clock.php

@@ -33,21 +33,19 @@
 $agent = new Agent($platform, 'gpt-4o-mini', [$toolProcessor], [$toolProcessor]);
 
 $messages = new MessageBag(Message::ofUser('What date and time is it?'));
-$result = $agent->call($messages, ['response_format' => [
+$result = $agent->call($messages, ['text' => ['format' => [
     'type' => 'json_schema',
-    'json_schema' => [
-        'name' => 'clock',
-        'strict' => true,
-        'schema' => [
-            'type' => 'object',
-            'properties' => [
-                'date' => ['type' => 'string', 'description' => 'The current date in the format YYYY-MM-DD.'],
-                'time' => ['type' => 'string', 'description' => 'The current time in the format HH:MM:SS.'],
-            ],
-            'required' => ['date', 'time'],
-            'additionalProperties' => false,
+    'name' => 'clock',
+    'strict' => true,
+    'schema' => [
+        'type' => 'object',
+        'properties' => [
+            'date' => ['type' => 'string', 'description' => 'The current date in the format YYYY-MM-DD.'],
+            'time' => ['type' => 'string', 'description' => 'The current time in the format HH:MM:SS.'],
         ],
+        'required' => ['date', 'time'],
+        'additionalProperties' => false,
     ],
-]]);
+]]]);
 
 dump($result->getContent());

examples/openai/token-metadata.php

@@ -25,7 +25,7 @@
     Message::ofUser('What is the Symfony framework?'),
 );
 $result = $agent->call($messages, [
-    'max_tokens' => 500, // specific options just for this call
+    'max_output_tokens' => 500, // specific options just for this call
 ]);
 
 print_token_usage($result->getMetadata());

src/platform/src/Bridge/OpenAi/Contract/OpenAiContract.php

@@ -23,8 +23,16 @@ final class OpenAiContract extends Contract
     public static function create(NormalizerInterface ...$normalizer): Contract
     {
         return parent::create(
+            new Gpt\Message\MessageBagNormalizer(),
+            new Gpt\Message\AssistantMessageNormalizer(),
+            new Gpt\Message\Content\ImageNormalizer(),
+            new Gpt\Message\Content\ImageUrlNormalizer(),
+            new Gpt\Message\Content\TextNormalizer(),
+            new Gpt\ToolNormalizer(),
+            new Gpt\ToolCallNormalizer(),
+            new Gpt\Message\ToolCallMessageNormalizer(),
+            new Gpt\Message\Content\DocumentNormalizer(),
             new AudioNormalizer(),
-            new DocumentNormalizer(),
             ...$normalizer
         );
     }

src/platform/src/Bridge/OpenAi/Gpt/ModelClient.php

@@ -16,6 +16,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\HttpClientInterface;
 
@@ -42,9 +43,18 @@ public function supports(Model $model): bool
 
     public function request(Model $model, array|string $payload, array $options = []): RawHttpResult
     {
-        return new RawHttpResult($this->httpClient->request('POST', self::getBaseUrl($this->region).'/v1/chat/completions', [
+        if (isset($options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema']['schema'])) {
+            $schema = $options[PlatformSubscriber::RESPONSE_FORMAT]['json_schema'];
+            $options['text']['format'] = $schema;
+            $options['text']['format']['name'] = $schema['name'];
+            $options['text']['format']['type'] = $options[PlatformSubscriber::RESPONSE_FORMAT]['type'];
+
+            unset($options[PlatformSubscriber::RESPONSE_FORMAT]);
+        }
+
+        return new RawHttpResult($this->httpClient->request('POST', self::getBaseUrl($this->region).'/v1/responses', [
             'auth_bearer' => $this->apiKey,
-            'json' => array_merge($options, $payload),
+            'json' => array_merge($options, ['model' => $model->getName()], $payload),
         ]));
     }
 }

src/platform/src/Bridge/OpenAi/Gpt/ResultConverter.php

@@ -31,9 +31,17 @@
 /**
  * @author Christopher Hertel <[email protected]>
  * @author Denis Zunke <[email protected]>
+ *
+ * @phpstan-type OutputMessage array{content: array<Refusal|OutputText>, id: string, role: string, type: 'message'}
+ * @phpstan-type OutputText array{type: 'output_text', text: string}
+ * @phpstan-type Refusal array{type: 'refusal', refusal: string}
+ * @phpstan-type FunctionCall array{id: string, arguments: string, call_id: string, name: string, type: 'function_call'}
+ * @phpstan-type Reasoning array{summary: array{text?: string}, id: string}
  */
 final class ResultConverter implements ResultConverterInterface
 {
+    private const KEY_OUTPUT = 'output';
+
     public function supports(Model $model): bool
     {
         return $model instanceof Gpt;
@@ -76,128 +84,114 @@ public function convert(RawResultInterface|RawHttpResult $result, array $options
             throw new RuntimeException(\sprintf('Error "%s"-%s (%s): "%s".', $data['error']['code'], $data['error']['type'], $data['error']['param'], $data['error']['message']));
         }
 
-        if (!isset($data['choices'])) {
-            throw new RuntimeException('Response does not contain choices.');
+        if (!isset($data[self::KEY_OUTPUT])) {
+            throw new RuntimeException('Response does not contain output.');
         }
 
-        $choices = array_map($this->convertChoice(...), $data['choices']);
+        $results = $this->convertOutputArray($data[self::KEY_OUTPUT]);
 
-        return 1 === \count($choices) ? $choices[0] : new ChoiceResult(...$choices);
+        return 1 === \count($results) ? array_pop($results) : new ChoiceResult(...$results);
     }
 
-    private function convertStream(RawResultInterface|RawHttpResult $result): \Generator
+    /**
+     * @param array<OutputMessage|FunctionCall|Reasoning> $output
+     *
+     * @return ResultInterface[]
+     */
+    private function convertOutputArray(array $output): array
     {
-        $toolCalls = [];
-        foreach ($result->getDataStream() as $data) {
-            if ($this->streamIsToolCall($data)) {
-                $toolCalls = $this->convertStreamToToolCalls($toolCalls, $data);
-            }
+        [$toolCallResult, $output] = $this->extractFunctionCalls($output);
 
-            if ([] !== $toolCalls && $this->isToolCallsStreamFinished($data)) {
-                yield new ToolCallResult(...array_map($this->convertToolCall(...), $toolCalls));
-            }
-
-            if (!isset($data['choices'][0]['delta']['content'])) {
-                continue;
-            }
-
-            yield $data['choices'][0]['delta']['content'];
+        $results = array_filter(array_map($this->processOutputItem(...), $output));
+        if ($toolCallResult) {
+            $results[] = $toolCallResult;
         }
+
+        return $results;
     }
 
     /**
-     * @param array<string, mixed> $toolCalls
-     * @param array<string, mixed> $data
-     *
-     * @return array<string, mixed>
+     * @param OutputMessage|Reasoning $item
      */
-    private function convertStreamToToolCalls(array $toolCalls, array $data): array
+    private function processOutputItem(array $item): ?ResultInterface
     {
-        if (!isset($data['choices'][0]['delta']['tool_calls'])) {
-            return $toolCalls;
-        }
+        $type = $item['type'] ?? null;
 
-        foreach ($data['choices'][0]['delta']['tool_calls'] as $i => $toolCall) {
-            if (isset($toolCall['id'])) {
-                // initialize tool call
-                $toolCalls[$i] = [
-                    'id' => $toolCall['id'],
-                    'function' => $toolCall['function'],
-                ];
+        return match ($type) {
+            'message' => $this->convertOutputMessage($item),
+            'reasoning' => $this->convertReasoning($item),
+            default => throw new RuntimeException(\sprintf('Unsupported output type "%s".', $type)),
+        };
+    }
+
+    private function convertStream(RawResultInterface|RawHttpResult $result): \Generator
+    {
+        foreach ($result->getDataStream() as $event) {
+            if (isset($event['delta'])) {
+                yield $event['delta'];
+            }
+            if (!str_contains('completed', $event['type'] ?? '')) {
                 continue;
             }
 
-            // add arguments delta to tool call
-            $toolCalls[$i]['function']['arguments'] .= $toolCall['function']['arguments'];
-        }
+            [$toolCallResult] = $this->extractFunctionCalls($event['response'][self::KEY_OUTPUT] ?? []);
 
-        return $toolCalls;
+            if ($toolCallResult && 'response.completed' === $event['type']) {
+                yield $toolCallResult;
+            }
+        }
     }
 
     /**
-     * @param array<string, mixed> $data
+     * @param array<OutputMessage|FunctionCall|Reasoning> $output
+     *
+     * @return list<ToolCallResult|array<OutputMessage|Reasoning>|null>
      */
-    private function streamIsToolCall(array $data): bool
+    private function extractFunctionCalls(array $output): array
     {
-        return isset($data['choices'][0]['delta']['tool_calls']);
-    }
+        $functionCalls = [];
+        foreach ($output as $key => $item) {
+            if ('function_call' === ($item['type'] ?? null)) {
+                $functionCalls[] = $item;
+                unset($output[$key]);
+            }
+        }
 
-    /**
-     * @param array<string, mixed> $data
-     */
-    private function isToolCallsStreamFinished(array $data): bool
-    {
-        return isset($data['choices'][0]['finish_reason']) && 'tool_calls' === $data['choices'][0]['finish_reason'];
+        $toolCallResult = $functionCalls ? new ToolCallResult(
+            ...array_map($this->convertFunctionCall(...), $functionCalls)
+        ) : null;
+
+        return [$toolCallResult, $output];
     }
 
     /**
-     * @param array{
-     *     index: int,
-     *     message: array{
-     *         role: 'assistant',
-     *         content: ?string,
-     *         tool_calls: array{
-     *             id: string,
-     *             type: 'function',
-     *             function: array{
-     *                 name: string,
-     *                 arguments: string
-     *             },
-     *         },
-     *         refusal: ?mixed
-     *     },
-     *     logprobs: string,
-     *     finish_reason: 'stop'|'length'|'tool_calls'|'content_filter',
-     * } $choice
+     * @param OutputMessage $output
      */
-    private function convertChoice(array $choice): ToolCallResult|TextResult
+    private function convertOutputMessage(array $output): ?TextResult
     {
-        if ('tool_calls' === $choice['finish_reason']) {
-            return new ToolCallResult(...array_map([$this, 'convertToolCall'], $choice['message']['tool_calls']));
+        $content = $output['content'] ?? [];
+        if ([] === $content) {
+            return null;
         }
 
-        if (\in_array($choice['finish_reason'], ['stop', 'length'], true)) {
-            return new TextResult($choice['message']['content']);
+        $content = array_pop($content);
+        if ('refusal' === $content['type']) {
+            return new TextResult(\sprintf('Model refused to generate output: %s', $content['refusal']));
         }
 
-        throw new RuntimeException(\sprintf('Unsupported finish reason "%s".', $choice['finish_reason']));
+        return new TextResult($content['text']);
     }
 
     /**
-     * @param array{
-     *     id: string,
-     *     type: 'function',
-     *     function: array{
-     *         name: string,
-     *         arguments: string
-     *     }
-     * } $toolCall
+     * @param FunctionCall $toolCall
+     *
+     * @throws \JsonException
      */
-    private function convertToolCall(array $toolCall): ToolCall
+    private function convertFunctionCall(array $toolCall): ToolCall
     {
-        $arguments = json_decode($toolCall['function']['arguments'], true, flags: \JSON_THROW_ON_ERROR);
+        $arguments = json_decode($toolCall['arguments'], true, flags: \JSON_THROW_ON_ERROR);
 
-        return new ToolCall($toolCall['id'], $toolCall['function']['name'], $arguments);
+        return new ToolCall($toolCall['id'], $toolCall['name'], $arguments);
     }
 
     /**
@@ -219,4 +213,15 @@ private static function parseResetTime(string $resetTime): ?int
 
         return null;
     }
+
+    /**
+     * @param Reasoning $item
+     */
+    private function convertReasoning(array $item): ?ResultInterface
+    {
+        // Reasoning is sometimes missing if it exceeds the context limit.
+        $summary = $item['summary']['text'] ?? null;
+
+        return $summary ? new TextResult($summary) : null;
+    }
 }