feat: Chat Response - Add logprobs (#533)

klmork · web-flow · commit babb3e10589f · 2025-04-08T06:35:34.000-04:00
* Chat Response: Add class for logprobs content

* Chat response: add logprobs

Only add content for now.

* Chat response: add logprobs to CreateResponse

Now that we have our classes for logprobs (CreateResponseChoiceLogprobs
and CreateResponseChoiceLogbropsContent), let's actually add logprobs in
the CreateResponseChoice / CreateResponse objects.

Update types, fixtures, tests.

* Update readme
diff --git a/README.md b/README.md
@@ -177,6 +177,7 @@ foreach ($response->choices as $choice) {
     $choice->index; // 0
     $choice->message->role; // 'assistant'
     $choice->message->content; // '\n\nHello there! How can I assist you today?'
+    $choice->logprobs; // null
     $choice->finishReason; // 'stop'
 }
 
diff --git a/src/Resources/Chat.php b/src/Resources/Chat.php
@@ -29,7 +29,7 @@ public function create(array $parameters): CreateResponse
 
         $payload = Payload::create('chat/completions', $parameters);
 
-        /** @var Response<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}> $response */
+        /** @var Response<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}> $response */
         $response = $this->transporter->requestObject($payload);
 
         return CreateResponse::from($response->data(), $response->meta());
diff --git a/src/Responses/Chat/CreateResponse.php b/src/Responses/Chat/CreateResponse.php
@@ -12,12 +12,12 @@
 use OpenAI\Testing\Responses\Concerns\Fakeable;
 
 /**
- * @implements ResponseContract<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}>
+ * @implements ResponseContract<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}>
  */
 final class CreateResponse implements ResponseContract, ResponseHasMetaInformationContract
 {
     /**
-     * @use ArrayAccessible<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}>
+     * @use ArrayAccessible<array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}}>
      */
     use ArrayAccessible;
 
@@ -41,7 +41,7 @@ private function __construct(
     /**
      * Acts as static factory, and returns a new Response instance.
      *
-     * @param  array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int, prompt_tokens_details?:array{cached_tokens:int}, completion_tokens_details?:array{audio_tokens?:int, reasoning_tokens:int, accepted_prediction_tokens:int, rejected_prediction_tokens:int}}}  $attributes
+     * @param  array{id: string, object: string, created: int, model: string, system_fingerprint?: string, choices: array<int, array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int, prompt_tokens_details?:array{cached_tokens:int}, completion_tokens_details?:array{audio_tokens?:int, reasoning_tokens:int, accepted_prediction_tokens:int, rejected_prediction_tokens:int}}}  $attributes
      */
     public static function from(array $attributes, MetaInformation $meta): self
     {
diff --git a/src/Responses/Chat/CreateResponseChoice.php b/src/Responses/Chat/CreateResponseChoice.php
@@ -9,29 +9,32 @@ final class CreateResponseChoice
     private function __construct(
         public readonly int $index,
         public readonly CreateResponseMessage $message,
+        public readonly ?CreateResponseChoiceLogprobs $logprobs,
         public readonly ?string $finishReason,
     ) {}
 
     /**
-     * @param  array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}  $attributes
+     * @param  array{index: int, message: array{role: string, content: ?string, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}  $attributes
      */
     public static function from(array $attributes): self
     {
         return new self(
             $attributes['index'],
             CreateResponseMessage::from($attributes['message']),
+            $attributes['logprobs'] ? CreateResponseChoiceLogprobs::from($attributes['logprobs']) : null,
             $attributes['finish_reason'] ?? null,
         );
     }
 
     /**
-     * @return array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, finish_reason: string|null}
+     * @return array{index: int, message: array{role: string, content: string|null, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}, logprobs: ?array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}, finish_reason: string|null}
      */
     public function toArray(): array
     {
         return [
             'index' => $this->index,
             'message' => $this->message->toArray(),
+            'logprobs' => $this->logprobs?->toArray(),
             'finish_reason' => $this->finishReason,
         ];
     }
diff --git a/src/Responses/Chat/CreateResponseChoiceLogprobs.php b/src/Responses/Chat/CreateResponseChoiceLogprobs.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Chat;
+
+final class CreateResponseChoiceLogprobs
+{
+    /**
+     * @param  ?array<int, CreateResponseChoiceLogprobsContent>  $content
+     */
+    private function __construct(
+        public readonly ?array $content,
+    ) {}
+
+    /**
+     * @param  array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        $content = null;
+        if (isset($attributes['content'])) {
+            $content = array_map(fn (array $result): CreateResponseChoiceLogprobsContent => CreateResponseChoiceLogprobsContent::from(
+                $result
+            ), $attributes['content']);
+        }
+
+        return new self(
+            $content,
+        );
+    }
+
+    /**
+     * @return array{content: ?array<int, array{token: string, logprob: float, bytes: ?array<int, int>}>}
+     */
+    public function toArray(): array
+    {
+        return [
+            'content' => $this->content ? array_map(
+                static fn (CreateResponseChoiceLogprobsContent $result): array => $result->toArray(),
+                $this->content,
+            ) : null,
+        ];
+    }
+}
diff --git a/src/Responses/Chat/CreateResponseChoiceLogprobsContent.php b/src/Responses/Chat/CreateResponseChoiceLogprobsContent.php
@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Chat;
+
+final class CreateResponseChoiceLogprobsContent
+{
+    /**
+     * @param  ?array<int, int>  $bytes
+     */
+    private function __construct(
+        public readonly string $token,
+        public readonly float $logprob,
+        public readonly ?array $bytes,
+    ) {}
+
+    /**
+     * @param array{
+     *     token: string,
+     *     logprob: float,
+     *     bytes: ?array<int, int>
+     * } $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            $attributes['token'],
+            $attributes['logprob'],
+            $attributes['bytes'],
+        );
+    }
+
+    /**
+     * @return array{
+     *     token: string,
+     *     logprob: float,
+     *     bytes: ?array<int, int>
+     * }
+     */
+    public function toArray(): array
+    {
+        return [
+            'token' => $this->token,
+            'logprob' => $this->logprob,
+            'bytes' => $this->bytes,
+        ];
+    }
+}
diff --git a/src/Testing/Responses/Fixtures/Chat/CreateResponseFixture.php b/src/Testing/Responses/Fixtures/Chat/CreateResponseFixture.php
@@ -19,6 +19,7 @@ final class CreateResponseFixture
                     'function_call' => null,
                     'tool_calls' => [],
                 ],
+                'logprobs' => null,
                 'finish_reason' => 'stop',
             ],
         ],
diff --git a/tests/Fixtures/Chat.php b/tests/Fixtures/Chat.php
@@ -17,6 +17,7 @@ function chatCompletion(): array
                     'role' => 'assistant',
                     'content' => "\n\nHello there, how may I assist you today?",
                 ],
+                'logprobs' => null,
                 'finish_reason' => 'stop',
             ],
         ],
@@ -36,6 +37,48 @@ function chatCompletion(): array
     ];
 }
 
+/**
+ * @return array<string, mixed>
+ */
+function chatCompletionWithLogprobs(): array
+{
+    return [
+        'id' => 'chatcmpl-123',
+        'object' => 'chat.completion',
+        'created' => 1677652288,
+        'model' => 'gpt-3.5-turbo',
+        'choices' => [
+            [
+                'index' => 0,
+                'message' => [
+                    'role' => 'assistant',
+                    'content' => 'Hello!',
+                ],
+                'logprobs' => [
+                    'content' => [
+                        [
+                            'token' => 'Hello',
+                            'logprob' => 0.0,
+                            'bytes' => [72, 101, 108, 108, 111],
+                        ],
+                        [
+                            'token' => '!',
+                            'logprob' => -0.0005715019651688635,
+                            'bytes' => [33],
+                        ],
+                    ],
+                ],
+                'finish_reason' => 'stop',
+            ],
+        ],
+        'usage' => [
+            'prompt_tokens' => 18,
+            'completion_tokens' => 3,
+            'total_tokens' => 21,
+        ],
+    ];
+}
+
 /**
  * @return array<string, mixed>
  */
@@ -54,6 +97,7 @@ function chatCompletionWithSystemFingerprint(): array
                     'role' => 'assistant',
                     'content' => "\n\nHello there, how may I assist you today?",
                 ],
+                'logprobs' => null,
                 'finish_reason' => 'stop',
             ],
         ],
@@ -86,6 +130,7 @@ function chatCompletionWithFunction(): array
                         'arguments' => "{\n  \"location\": \"Boston, MA\"\n}",
                     ],
                 ],
+                'logprobs' => null,
                 'finish_reason' => 'function_call',
             ],
         ],
@@ -124,6 +169,7 @@ function chatCompletionWithToolCalls(): array
                         ],
                     ],
                 ],
+                'logprobs' => null,
                 'finish_reason' => 'tool_calls',
             ],
         ],
@@ -166,6 +212,7 @@ function chatCompletionFromVision(): array
                     'role' => 'assistant',
                     'content' => 'The image shows a beautiful, tranquil natural landscape. A wooden boardwalk path stretches',
                 ],
+                'logprobs' => null,
             ],
         ],
         'usage' => [
diff --git a/tests/Responses/Chat/CreateResponseChoice.php b/tests/Responses/Chat/CreateResponseChoice.php
@@ -1,6 +1,7 @@
 <?php
 
 use OpenAI\Responses\Chat\CreateResponseChoice;
+use OpenAI\Responses\Chat\CreateResponseChoiceLogprobs;
 use OpenAI\Responses\Chat\CreateResponseMessage;
 
 test('from', function () {
@@ -9,6 +10,17 @@
     expect($result)
         ->index->toBe(0)
         ->message->toBeInstanceOf(CreateResponseMessage::class)
+        ->logprobs->toBeNull()
+        ->finishReason->toBeIn(['stop', null]);
+});
+
+test('from with logprobs', function () {
+    $result = CreateResponseChoice::from(chatCompletionWithLogprobs()['choices'][0]);
+
+    expect($result)
+        ->index->toBe(0)
+        ->message->toBeInstanceOf(CreateResponseMessage::class)
+        ->logprobs->toBeInstanceOf(CreateResponseChoiceLogprobs::class)
         ->finishReason->toBeIn(['stop', null]);
 });
 
@@ -18,6 +30,7 @@
     expect($result)
         ->index->toBe(0)
         ->message->toBeInstanceOf(CreateResponseMessage::class)
+        ->logprobs->toBeNull()
         ->finishReason->toBeNull();
 });
 
@@ -27,3 +40,10 @@
     expect($result->toArray())
         ->toBe(chatCompletion()['choices'][0]);
 });
+
+test('to array with logprobs', function () {
+    $result = CreateResponseChoice::from(chatCompletionWithLogprobs()['choices'][0]);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithLogprobs()['choices'][0]);
+});
diff --git a/tests/Responses/Chat/CreateResponseChoiceLogprobs.php b/tests/Responses/Chat/CreateResponseChoiceLogprobs.php
@@ -0,0 +1,21 @@
+<?php
+
+use OpenAI\Responses\Chat\CreateResponseChoiceLogprobs;
+use OpenAI\Responses\Chat\CreateResponseChoiceLogprobsContent;
+
+test('from', function () {
+    $result = CreateResponseChoiceLogprobs::from(chatCompletionWithLogprobs()['choices'][0]['logprobs']);
+
+    expect($result)
+        ->toBeInstanceOf(CreateResponseChoiceLogprobs::class)
+        ->content->toBeArray()
+        ->content->toHaveCount(2)
+        ->content->each->toBeInstanceOf(CreateResponseChoiceLogprobsContent::class);
+});
+
+test('to array', function () {
+    $result = CreateResponseChoiceLogprobs::from(chatCompletionWithLogprobs()['choices'][0]['logprobs']);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithLogprobs()['choices'][0]['logprobs']);
+});
diff --git a/tests/Responses/Chat/CreateResponseChoiceLogprobsContent.php b/tests/Responses/Chat/CreateResponseChoiceLogprobsContent.php
@@ -0,0 +1,19 @@
+<?php
+
+use OpenAI\Responses\Chat\CreateResponseChoiceLogprobsContent;
+
+test('from', function () {
+    $result = CreateResponseChoiceLogprobsContent::from(chatCompletionWithLogprobs()['choices'][0]['logprobs']['content'][0]);
+
+    expect($result)
+        ->token->toBe('Hello')
+        ->logprob->toBe(0.0)
+        ->bytes->toBe([72, 101, 108, 108, 111]);
+});
+
+test('to array', function () {
+    $result = CreateResponseChoiceLogprobsContent::from(chatCompletionWithLogprobs()['choices'][0]['logprobs']['content'][0]);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithLogprobs()['choices'][0]['logprobs']['content'][0]);
+});

Original file line number	Diff line number	Diff line change
`@@ -177,6 +177,7 @@ foreach ($response->choices as $choice) {`
`177`	`177`	`$choice->index; // 0`
`178`	`178`	`$choice->message->role; // 'assistant'`
`179`	`179`	`$choice->message->content; // '\n\nHello there! How can I assist you today?'`
	`180`	`+ $choice->logprobs; // null`
`180`	`181`	`$choice->finishReason; // 'stop'`
`181`	`182`	`}`
`182`	`183`