feat(OpenAI): Support annotations in Chat response. (Web Search) (#564)

* Planning comments

* Planning notes

* Planning notes

* add support for web_search_options

* Add classes for Response Choice web_search_options

* web_search_options classes to final classes

* Add web_search_options to chat fixtures

* update docblock and make web_search_option nullable in return

* expect webSearchOptions

* Return webSearchOptionContent with content size and user location

* Update dockblocks and add type approximate

* add test for Response Choice WebSearchOptions classes

* fix docblock

* Delete package-lock.json

* Return annotations

* Test fixtures for annotations

* Annotations instead of Web_search_options WIP

* Remove unneeded class

* Update doc blocks

* Update doc block

* CreateResponseChoiceAnnoations class

* CreateResponseChoiceAnnotaionUrlCitations class

* Delete .gitignore

* git-ignore

* Restore .gitignore file

* test createResponseChoiceAnnotations

* chatCompletionWithAnnotations in correct format

* CreateResponseChoice test in correct format

* better from method and return expected type of url_citation

* better testing data for WithAnnotations

* Test CreateResponseChoiceAnnotationsUrlCitationsTest.php

* return url_citation items in the correct order

* Pint

* Move annotations out of createResponseChoice

* Move annotations into createResponseMessage

* Annotations in message for chatCompletionWithAnnotations

* Update test for CreateResponseChoiceAnnotations to pass

* CreateResponseChoiceAnnotations returns annotations array

* Correct doc block for toArray on choice Annotations

* WIP collect annotations array for Response Message

* Return annotations from createResponseChoiceAnnotations class to response message correctly

* Correct order for doc block

* clean up with pint

* expect annotations

* test for web search in messages with url_citations

* Just return annotations, no need for filling another array map

* Handle ResponseChoiceAnnotations as object then use toArray method

* Retun annotations from class as expected

* Correct docblocks

* check urlCitations in createResponseChoiceAnnotaitons

* point to correct item in array for test

* pint

* Correct doc block with single quotes for url_citations

* doc blocks with single quotes for url_citation

* Remove array filter on array map for urlCitations

* Assert toArray with function call

* Annotations treated as arrays on message object

* WIP Type fix with PHPstan

* Fix doc blocks

* fix doc block

* test: augment tests for annotations

Author: Saraphoo

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}}>}, 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}}>
+ * @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, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: 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}}>
  */
 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}}>}, 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<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, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: 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}}>
      */
     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}}>}, 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
+     * @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, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: 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
     {

src/Responses/Chat/CreateResponseChoice.php

@@ -14,7 +14,7 @@ private function __construct(
     ) {}
 
     /**
-     * @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
+     * @param  array{index: int, message: array{role: string, content: ?string, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: 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
     {
@@ -27,7 +27,7 @@ public static function from(array $attributes): self
     }
 
     /**
-     * @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}
+     * @return array{index: int, message: array{role: string, content: string|null, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: 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}
      */
     public function toArray(): array
     {

src/Responses/Chat/CreateResponseChoiceAnnotations.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace OpenAI\Responses\Chat;
+
+final class CreateResponseChoiceAnnotations
+{
+    public function __construct(
+        public readonly string $type,
+        public readonly CreateResponseChoiceAnnotationsUrlCitations $urlCitations
+    ) {}
+
+    /**
+     * @param  array{type: string, url_citation: array{end_index: int, start_index: int, title: string, url: string}}  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            $attributes['type'],
+            CreateResponseChoiceAnnotationsUrlCitations::from($attributes['url_citation'])
+        );
+    }
+
+    /**
+     * @return array{type: string, url_citation: array{end_index: int, start_index: int, title: string, url: string}}
+     */
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type,
+            'url_citation' => $this->urlCitations->toArray(),
+        ];
+    }
+}

src/Responses/Chat/CreateResponseChoiceAnnotationsUrlCitations.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace OpenAI\Responses\Chat;
+
+final class CreateResponseChoiceAnnotationsUrlCitations
+{
+    public function __construct(
+        public readonly int $endIndex,
+        public readonly int $startIndex,
+        public readonly string $title,
+        public readonly string $url,
+    ) {}
+
+    /**
+     * @param  array{end_index: int, start_index: int, title: string, url: string}  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            $attributes['end_index'],
+            $attributes['start_index'],
+            $attributes['title'],
+            $attributes['url'],
+        );
+    }
+
+    /**
+     * @return array{end_index: int, start_index: int, title: string, url: string}
+     */
+    public function toArray(): array
+    {
+        return [
+            'end_index' => $this->endIndex,
+            'start_index' => $this->startIndex,
+            'title' => $this->title,
+            'url' => $this->url,
+        ];
+    }
+}

src/Responses/Chat/CreateResponseMessage.php

@@ -8,33 +8,40 @@ final class CreateResponseMessage
 {
     /**
      * @param  array<int, CreateResponseToolCall>  $toolCalls
+     * @param  array<int, CreateResponseChoiceAnnotations>  $annotations
      */
     private function __construct(
         public readonly string $role,
         public readonly ?string $content,
+        public readonly array $annotations,
         public readonly array $toolCalls,
         public readonly ?CreateResponseFunctionCall $functionCall,
     ) {}
 
     /**
-     * @param  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}}>}  $attributes
+     * @param  array{role: string, content: ?string, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: string}}>, function_call: ?array{name: string, arguments: string}, tool_calls: ?array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}  $attributes
      */
     public static function from(array $attributes): self
     {
         $toolCalls = array_map(fn (array $result): CreateResponseToolCall => CreateResponseToolCall::from(
             $result
         ), $attributes['tool_calls'] ?? []);
 
+        $annotations = array_map(fn (array $result): CreateResponseChoiceAnnotations => CreateResponseChoiceAnnotations::from(
+            $result,
+        ), $attributes['annotations'] ?? []);
+
         return new self(
             $attributes['role'],
             $attributes['content'] ?? null,
+            $annotations,
             $toolCalls,
             isset($attributes['function_call']) ? CreateResponseFunctionCall::from($attributes['function_call']) : null,
         );
     }
 
     /**
-     * @return 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}}>}
+     * @return array{role: string, content: string|null, annotations?: array<int, array{type: string, url_citation: array{start_index: int, end_index: int, title: string, url: string}}>, function_call?: array{name: string, arguments: string}, tool_calls?: array<int, array{id: string, type: string, function: array{name: string, arguments: string}}>}
      */
     public function toArray(): array
     {
@@ -43,6 +50,10 @@ public function toArray(): array
             'content' => $this->content,
         ];
 
+        if ($this->annotations !== []) {
+            $data['annotations'] = array_map(fn (CreateResponseChoiceAnnotations $annotations): array => $annotations->toArray(), $this->annotations);
+        }
+
         if ($this->functionCall instanceof CreateResponseFunctionCall) {
             $data['function_call'] = $this->functionCall->toArray();
         }

tests/Fixtures/Chat.php

@@ -237,6 +237,40 @@ function chatCompletionWithoutUsage(): array
     ];
 }
 
+/**
+ * @return array<string, mixed>
+ */
+function chatCompletionWithAnnotations(): array
+{
+    return [
+        'id' => 'chatcmpl-123',
+        'object' => 'chat.completion',
+        'created' => 1677652288,
+        'model' => 'gpt-4o-mini-search-preview',
+        'choices' => [
+            [
+                'index' => 0,
+                'message' => [
+                    'role' => 'assistant',
+                    'content' => 'Hello World',
+                    'annotations' => [
+                        [
+                            'type' => 'url_citation',
+                            'url_citation' => [
+                                'end_index' => 5,
+                                'start_index' => 0,
+                                'title' => 'Hello',
+                                'url' => 'https://example.com',
+                            ],
+                        ],
+                    ],
+                ],
+                'finish_reason' => 'stop',
+            ],
+        ],
+    ];
+}
+
 /**
  * @return array<string, mixed>
  */

tests/Responses/Chat/CreateResponseChoiceAnnotations.php

@@ -0,0 +1,19 @@
+<?php
+
+use OpenAI\Responses\Chat\CreateResponseChoiceAnnotations;
+use OpenAI\Responses\Chat\CreateResponseChoiceAnnotationsUrlCitations;
+
+it('from url_citation annotation', function () {
+    $result = CreateResponseChoiceAnnotations::from(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]);
+
+    expect($result)
+        ->type->toBe('url_citation')
+        ->urlCitations->toBeInstanceOf(CreateResponseChoiceAnnotationsUrlCitations::class);
+});
+
+test('to array', function () {
+    $result = CreateResponseChoiceAnnotations::from(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]);
+});

tests/Responses/Chat/CreateResponseChoiceAnnotationsUrlCitationsTest.php

@@ -0,0 +1,20 @@
+<?php
+
+use OpenAI\Responses\Chat\CreateResponseChoiceAnnotationsUrlCitations;
+
+it('from', function () {
+    $result = CreateResponseChoiceAnnotationsUrlCitations::from(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]['url_citation']);
+
+    expect($result)
+        ->endIndex->toBe(5)
+        ->startIndex->toBe(0)
+        ->title->toBe('Hello')
+        ->url->toBe('https://example.com');
+});
+
+test('to array', function () {
+    $result = CreateResponseChoiceAnnotationsUrlCitations::from(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]['url_citation']);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithAnnotations()['choices'][0]['message']['annotations'][0]['url_citation']);
+});

tests/Responses/Chat/CreateResponseMessage.php

@@ -1,5 +1,6 @@
 <?php
 
+use OpenAI\Responses\Chat\CreateResponseChoiceAnnotations;
 use OpenAI\Responses\Chat\CreateResponseFunctionCall;
 use OpenAI\Responses\Chat\CreateResponseMessage;
 use OpenAI\Responses\Chat\CreateResponseToolCall;
@@ -10,6 +11,7 @@
     expect($result)
         ->role->toBe('assistant')
         ->content->toBe("\n\nHello there, how may I assist you today?")
+        ->annotations->toBeArray()
         ->functionCall->toBeNull();
 });
 
@@ -19,6 +21,7 @@
     expect($result)
         ->role->toBe('assistant')
         ->content->toBeNull()
+        ->annotations->toBeArray()
         ->functionCall->toBeInstanceOf(CreateResponseFunctionCall::class);
 });
 
@@ -33,6 +36,17 @@
         ->toolCalls->each->toBeInstanceOf(CreateResponseToolCall::class);
 });
 
+test('from annotations response', function () {
+    $result = CreateResponseMessage::from(chatCompletionWithAnnotations()['choices'][0]['message']);
+
+    expect($result)
+        ->role->toBe('assistant')
+        ->content->toBe('Hello World')
+        ->annotations->toBeArray()
+        ->annotations->toHaveCount(1)
+        ->annotations->each->toBeInstanceOf(CreateResponseChoiceAnnotations::class);
+});
+
 test('from function response without content', function () {
     $result = CreateResponseMessage::from(chatCompletionMessageWithFunctionAndNoContent());
 
@@ -62,3 +76,10 @@
     expect($result->toArray())
         ->toBe(chatCompletionWithToolCalls()['choices'][0]['message']);
 });
+
+test('to array from annotations response', function () {
+    $result = CreateResponseMessage::from(chatCompletionWithAnnotations()['choices'][0]['message']);
+
+    expect($result->toArray())
+        ->toBe(chatCompletionWithAnnotations()['choices'][0]['message']);
+});