feat: search vector store (#559)

* feat(vector-stores): implement search method

* chore(vector-stores): Add search documentation

* test(vectore-stores): search resource and response

* chore: remove extra newlines

Author: lukalocniskar

README.md

@@ -1929,6 +1929,40 @@ foreach ($response->data as $result) {
 $response->toArray(); // ['object' => 'list', ...]]
 ```
 
+#### `search`
+
+Search a vector store for relevant chunks based on a query and file attributes filter.
+
+```php
+$response = $client->vectorStores()->search(
+    vectorStoreId: 'vs_vzfQhlTWVUl38QGqQAoQjeDF',
+    parameters: [
+        'query' => 'What is the return policy?',
+        'max_num_results' => 5,
+        'filters' => [],
+        'rewrite_query' => false
+    ]
+);
+
+$response->object; // 'vector_store.search_results.page'
+$response->searchQuery; // 'What is the return policy?'
+$response->hasMore; // false
+$response->nextPage; // null
+foreach ($response->data as $file) {
+    $result->fileId; // 'file-fUU0hFRuQ1GzhOweTNeJlCXG'
+    $result->filename; // 'return_policy.pdf'
+    $result->score; // 0.95
+    $result->attributes; // ['category' => 'customer_service']
+
+    foreach ($result->content as $content) {
+        $content->type; // 'text'
+        $content->text; // 'Our return policy allows customers to return items within 30 days...'
+    }
+}
+
+$response->toArray(); // ['object' => 'vector_store.search_results.page', ...]
+```
+
 ### `Vector Store File Batches` Resource
 
 #### `create`

src/Contracts/Resources/VectorStoresContract.php

@@ -2,6 +2,7 @@
 
 namespace OpenAI\Contracts\Resources;
 
+use OpenAI\Responses\VectorStores\Search\VectorStoreSearchResponse;
 use OpenAI\Responses\VectorStores\VectorStoreDeleteResponse;
 use OpenAI\Responses\VectorStores\VectorStoreListResponse;
 use OpenAI\Responses\VectorStores\VectorStoreResponse;
@@ -62,4 +63,13 @@ public function files(): VectorStoresFilesContract;
      * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches
      */
     public function batches(): VectorStoresFileBatchesContract;
+
+    /**
+     * Search a vector store for relevant chunks based on a query and file attributes filter.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/search
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function search(string $vectorStoreId, array $parameters = []): VectorStoreSearchResponse;
 }

src/Resources/VectorStores.php

@@ -7,6 +7,7 @@
 use OpenAI\Contracts\Resources\VectorStoresContract;
 use OpenAI\Contracts\Resources\VectorStoresFileBatchesContract;
 use OpenAI\Contracts\Resources\VectorStoresFilesContract;
+use OpenAI\Responses\VectorStores\Search\VectorStoreSearchResponse;
 use OpenAI\Responses\VectorStores\VectorStoreDeleteResponse;
 use OpenAI\Responses\VectorStores\VectorStoreListResponse;
 use OpenAI\Responses\VectorStores\VectorStoreResponse;
@@ -117,4 +118,21 @@ public function batches(): VectorStoresFileBatchesContract
     {
         return new VectorStoresFileBatches($this->transporter);
     }
+
+    /**
+     * Search a vector store for relevant chunks based on a query and file attributes filter.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/search
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function search(string $vectorStoreId, array $parameters = []): VectorStoreSearchResponse
+    {
+        $payload = Payload::create("vector_stores/{$vectorStoreId}/search", $parameters);
+
+        /** @var Response<array{object: string, search_query: string|array<mixed>, data: array<int, array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>, has_more: bool, next_page: ?string}> $response */
+        $response = $this->transporter->requestObject($payload);
+
+        return VectorStoreSearchResponse::from($response->data(), $response->meta());
+    }
 }

src/Responses/VectorStores/Search/VectorStoreSearchResponse.php

@@ -0,0 +1,80 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\VectorStores\Search;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Contracts\ResponseHasMetaInformationContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\Concerns\HasMetaInformation;
+use OpenAI\Responses\Meta\MetaInformation;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @implements ResponseContract<array{object: string, search_query: string|array<mixed>, data: array<int, array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>, has_more: bool, next_page: ?string}>
+ */
+final class VectorStoreSearchResponse implements ResponseContract, ResponseHasMetaInformationContract
+{
+    /**
+     * @use ArrayAccessible<array{object: string, search_query: string|array<mixed>, data: array<int, array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>, has_more: bool, next_page: ?string}>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+    use HasMetaInformation;
+
+    /**
+     * @param  array<int, VectorStoreSearchResponseFile>  $data
+     * @param  string|array<mixed>  $searchQuery
+     */
+    private function __construct(
+        public readonly string $object,
+        public readonly string|array $searchQuery,
+        public readonly array $data,
+        public readonly bool $hasMore,
+        public readonly ?string $nextPage,
+        private readonly MetaInformation $meta,
+    ) {}
+
+    /**
+     * Acts as static factory, and returns a new Response instance.
+     *
+     * @param  array{object: string, search_query: string|array<mixed>, data: array<int, array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>, has_more: bool, next_page: ?string}  $attributes
+     */
+    public static function from(array $attributes, MetaInformation $meta): self
+    {
+        $data = array_map(
+            static fn (array $result): VectorStoreSearchResponseFile => VectorStoreSearchResponseFile::from($result),
+            $attributes['data']
+        );
+
+        return new self(
+            $attributes['object'],
+            $attributes['search_query'],
+            $data,
+            $attributes['has_more'],
+            $attributes['next_page'],
+            $meta,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * @return array{object: string, search_query: string|array<mixed>, data: array<int, array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>, has_more: bool, next_page: ?string}
+     */
+    public function toArray(): array
+    {
+        return [
+            'object' => $this->object,
+            'search_query' => $this->searchQuery,
+            'data' => array_map(
+                static fn (VectorStoreSearchResponseFile $item): array => $item->toArray(),
+                $this->data
+            ),
+            'has_more' => $this->hasMore,
+            'next_page' => $this->nextPage,
+        ];
+    }
+}

src/Responses/VectorStores/Search/VectorStoreSearchResponseContent.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\VectorStores\Search;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @implements ResponseContract<array{type: string, text: string}>
+ */
+final class VectorStoreSearchResponseContent implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<array{type: string, text: string}>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    private function __construct(
+        public readonly string $type,
+        public readonly string $text,
+    ) {}
+
+    /**
+     * Acts as static factory, and returns a new Response instance.
+     *
+     * @param  array{type: string, text: string}  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            $attributes['type'],
+            $attributes['text'],
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'type' => $this->type,
+            'text' => $this->text,
+        ];
+    }
+}

src/Responses/VectorStores/Search/VectorStoreSearchResponseFile.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\VectorStores\Search;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @implements ResponseContract<array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>
+ */
+final class VectorStoreSearchResponseFile implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    /**
+     * @param  array<string, mixed>  $attributes
+     * @param  array<int, VectorStoreSearchResponseContent>  $content
+     */
+    private function __construct(
+        public readonly string $fileId,
+        public readonly string $filename,
+        public readonly float $score,
+        public readonly array $attributes,
+        public readonly array $content,
+    ) {}
+
+    /**
+     * Acts as static factory, and returns a new Response instance.
+     *
+     * @param  array{file_id: string, filename: string, score: float, attributes: array<string, mixed>, content: array<int, array{type: string, text: string}>}  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        $content = array_map(
+            static fn (array $content): VectorStoreSearchResponseContent => VectorStoreSearchResponseContent::from($content),
+            $attributes['content'],
+        );
+
+        return new self(
+            $attributes['file_id'],
+            $attributes['filename'],
+            $attributes['score'],
+            $attributes['attributes'],
+            $content,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'file_id' => $this->fileId,
+            'filename' => $this->filename,
+            'score' => $this->score,
+            'attributes' => $this->attributes,
+            'content' => array_map(
+                static fn (VectorStoreSearchResponseContent $content): array => $content->toArray(),
+                $this->content,
+            ),
+        ];
+    }
+}

src/Testing/Resources/VectorStoresTestResource.php

@@ -6,6 +6,7 @@
 use OpenAI\Contracts\Resources\VectorStoresFileBatchesContract;
 use OpenAI\Contracts\Resources\VectorStoresFilesContract;
 use OpenAI\Resources\VectorStores;
+use OpenAI\Responses\VectorStores\Search\VectorStoreSearchResponse;
 use OpenAI\Responses\VectorStores\VectorStoreDeleteResponse;
 use OpenAI\Responses\VectorStores\VectorStoreListResponse;
 use OpenAI\Responses\VectorStores\VectorStoreResponse;
@@ -45,6 +46,14 @@ public function list(array $parameters = []): VectorStoreListResponse
         return $this->record(__FUNCTION__, func_get_args());
     }
 
+    /**
+     * @param  array<string, mixed>  $parameters
+     */
+    public function search(string $vectorStoreId, array $parameters = []): VectorStoreSearchResponse
+    {
+        return $this->record(__FUNCTION__, func_get_args());
+    }
+
     public function files(): VectorStoresFilesContract
     {
         return new VectorStoresFilesTestResource($this->fake);

src/Testing/Responses/Fixtures/VectorStores/Search/VectorStoreSearchResponseContentFixture.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace OpenAI\Testing\Responses\Fixtures\VectorStores\Search;
+
+final class VectorStoreSearchResponseContentFixture
+{
+    public const ATTRIBUTES = [
+        'type' => 'text',
+        'text' => 'Sample text content from the vector store.',
+    ];
+}

src/Testing/Responses/Fixtures/VectorStores/Search/VectorStoreSearchResponseFileFixture.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace OpenAI\Testing\Responses\Fixtures\VectorStores\Search;
+
+final class VectorStoreSearchResponseFileFixture
+{
+    public const ATTRIBUTES = [
+        'file_id' => 'file_abc123',
+        'filename' => 'document.pdf',
+        'score' => 0.95,
+        'attributes' => [
+            'author' => 'John Doe',
+            'date' => '2023-01-01',
+        ],
+        'content' => [
+            VectorStoreSearchResponseContentFixture::ATTRIBUTES,
+        ],
+    ];
+}

src/Testing/Responses/Fixtures/VectorStores/Search/VectorStoreSearchResponseFixture.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace OpenAI\Testing\Responses\Fixtures\VectorStores\Search;
+
+final class VectorStoreSearchResponseFixture
+{
+    public const ATTRIBUTES = [
+        'object' => 'vector_store.search_results.page',
+        'search_query' => 'What is the return policy?',
+        'data' => [
+            VectorStoreSearchResponseFileFixture::ATTRIBUTES,
+            [
+                'file_id' => 'file_xyz789',
+                'filename' => 'notes.txt',
+                'score' => 0.89,
+                'attributes' => [
+                    'author' => 'Jane Smith',
+                    'date' => '2023-01-02',
+                ],
+                'content' => [
+                    [
+                        'type' => 'text',
+                        'text' => 'Sample text content from the vector store.',
+                    ],
+                ],
+            ],
+        ],
+        'has_more' => false,
+        'next_page' => null,
+    ];
+}