Merge pull request #405 from openai-php/add-assistants-v2-api

Implement vector store endpoints and add assistants API v2 support

Author: gehrisandro

README.md

@@ -6,6 +6,7 @@
 
 use OpenAI\Contracts\ClientContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
+use OpenAI\Contracts\Resources\VectorStoresContract;
 use OpenAI\Contracts\TransporterContract;
 use OpenAI\Resources\Assistants;
 use OpenAI\Resources\Audio;
@@ -21,6 +22,7 @@
 use OpenAI\Resources\Models;
 use OpenAI\Resources\Moderations;
 use OpenAI\Resources\Threads;
+use OpenAI\Resources\VectorStores;
 
 final class Client implements ClientContract
 {
@@ -174,4 +176,14 @@ public function batches(): Batches
     {
         return new Batches($this->transporter);
     }
+
+    /**
+     * Create and update vector stores that assistants can interact with
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores
+     */
+    public function vectorStores(): VectorStoresContract
+    {
+        return new VectorStores($this->transporter);
+    }
 }

src/Client.php

@@ -16,6 +16,7 @@
 use OpenAI\Contracts\Resources\ModelsContract;
 use OpenAI\Contracts\Resources\ModerationsContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
+use OpenAI\Contracts\Resources\VectorStoresContract;
 
 interface ClientContract
 {
@@ -121,4 +122,11 @@ public function threads(): ThreadsContract;
      * @see https://platform.openai.com/docs/api-reference/batch
      */
     public function batches(): BatchesContract;
+
+    /**
+     * Create and update vector stores that assistants can interact with
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores
+     */
+    public function vectorStores(): VectorStoresContract;
 }

src/Contracts/ClientContract.php

@@ -11,7 +11,7 @@ interface AssistantsContract
     /**
      * Create an assistant with a model and instructions.
      *
-     * @see https://platform.openai.com/docs/api-reference/assistants/object
+     * @see https://platform.openai.com/docs/api-reference/assistants/createAssistant
      *
      * @param  array<string, mixed>  $parameters
      */
@@ -48,11 +48,4 @@ public function delete(string $id): AssistantDeleteResponse;
      * @param  array<string, mixed>  $parameters
      */
     public function list(array $parameters = []): AssistantListResponse;
-
-    /**
-     * Manage files attached to an assistant.
-     *
-     * @see https://platform.openai.com/docs/api-reference/assistants
-     */
-    public function files(): AssistantsFilesContract;
 }

src/Contracts/Resources/AssistantsContract.php

@@ -40,11 +40,4 @@ public function modify(string $threadId, string $messageId, array $parameters):
      * @param  array<string, mixed>  $parameters
      */
     public function list(string $threadId, array $parameters = []): ThreadMessageListResponse;
-
-    /**
-     * Manage files attached to a thread message.
-     *
-     * @see https://platform.openai.com/docs/api-reference/messages/file-object
-     */
-    public function files(): ThreadsMessagesFilesContract;
 }

src/Contracts/Resources/AssistantsFilesContract.php

@@ -0,0 +1,63 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\VectorStores\VectorStoreDeleteResponse;
+use OpenAI\Responses\VectorStores\VectorStoreListResponse;
+use OpenAI\Responses\VectorStores\VectorStoreResponse;
+
+interface VectorStoresContract
+{
+    /**
+     * Create a vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters): VectorStoreResponse;
+
+    /**
+     * Returns a list of vector stores.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/list
+     */
+    public function list(): VectorStoreListResponse;
+
+    /**
+     * Retrieves a vector store.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/retrieve
+     */
+    public function retrieve(string $vectorStore): VectorStoreResponse;
+
+    /**
+     * Modify a vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores/modify
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function modify(string $vectorStore, array $parameters): VectorStoreResponse;
+
+    /**
+     * Delete a vector store.
+     *
+     * https://platform.openai.com/docs/api-reference/vector-stores/delete
+     */
+    public function delete(string $vectorStore): VectorStoreDeleteResponse;
+
+    /**
+     * Manage the files related to the vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-files
+     */
+    public function files(): VectorStoresFilesContract;
+
+    /**
+     * Manage the file batches related to the vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches
+     */
+    public function batches(): VectorStoresFileBatchesContract;
+}

src/Contracts/Resources/ThreadsMessagesContract.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\VectorStores\FileBatches\VectorStoreFileBatchResponse;
+use OpenAI\Responses\VectorStores\Files\VectorStoreFileListResponse;
+
+interface VectorStoresFileBatchesContract
+{
+    /**
+     * Create a file batch on a vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches/createBatch
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $vectorStoreId, array $parameters): VectorStoreFileBatchResponse;
+
+    /**
+     * Retrieves a file batch within a vector store.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches/getBatch
+     */
+    public function retrieve(string $vectorStoreId, string $fileBatchId): VectorStoreFileBatchResponse;
+
+    /**
+     * Cancel a vector store file batch
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches/cancelBatch
+     */
+    public function cancel(string $vectorStoreId, string $fileBatchId): VectorStoreFileBatchResponse;
+
+    /**
+     * Lists the files within a file batch within a vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-file-batches/listBatchFiles
+     */
+    public function listFiles(string $vectorStoreId, string $fileBatchId): VectorStoreFileListResponse;
+}

src/Contracts/Resources/ThreadsMessagesFilesContract.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\VectorStores\Files\VectorStoreFileDeleteResponse;
+use OpenAI\Responses\VectorStores\Files\VectorStoreFileListResponse;
+use OpenAI\Responses\VectorStores\Files\VectorStoreFileResponse;
+
+interface VectorStoresFilesContract
+{
+    /**
+     * Create a file on a vector store
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-files/createFile
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $vectorStoreId, array $parameters): VectorStoreFileResponse;
+
+    /**
+     * Returns a list of files within a vector store.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-files/listFiles
+     */
+    public function list(string $vectorStoreId): VectorStoreFileListResponse;
+
+    /**
+     * Retrieves a file within a vector store.
+     *
+     * @see https://platform.openai.com/docs/api-reference/vector-stores-files/getFile
+     */
+    public function retrieve(string $vectorStoreId, string $fileId): VectorStoreFileResponse;
+
+    /**
+     * Delete a file within a vector store.
+     *
+     * https://platform.openai.com/docs/api-reference/vector-stores/delete
+     */
+    public function delete(string $vectorStoreId, string $fileId): VectorStoreFileDeleteResponse;
+}

src/Contracts/Resources/VectorStoresContract.php

@@ -15,7 +15,7 @@ public static function client(string $apiKey, ?string $organization = null): Cli
         return self::factory()
             ->withApiKey($apiKey)
             ->withOrganization($organization)
-            ->withHttpHeader('OpenAI-Beta', 'assistants=v1')
+            ->withHttpHeader('OpenAI-Beta', 'assistants=v2')
             ->make();
     }
 

src/Contracts/Resources/VectorStoresFileBatchesContract.php

@@ -5,7 +5,6 @@
 namespace OpenAI\Resources;
 
 use OpenAI\Contracts\Resources\AssistantsContract;
-use OpenAI\Contracts\Resources\AssistantsFilesContract;
 use OpenAI\Responses\Assistants\AssistantDeleteResponse;
 use OpenAI\Responses\Assistants\AssistantListResponse;
 use OpenAI\Responses\Assistants\AssistantResponse;
@@ -19,15 +18,15 @@ final class Assistants implements AssistantsContract
     /**
      * Create an assistant with a model and instructions.
      *
-     * @see https://platform.openai.com/docs/api-reference/assistants/object
+     * @see https://platform.openai.com/docs/api-reference/assistants/createAssistant
      *
      * @param  array<string, mixed>  $parameters
      */
     public function create(array $parameters): AssistantResponse
     {
         $payload = Payload::create('assistants', $parameters);
 
-        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'retrieval'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, file_ids: array<int, string>, metadata: array<string, string>}> $response */
+        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'file_search'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, tool_resources: array{code_interpreter?: array{file_ids: array<int,string>}, file_search?: array{vector_store_ids: array<int,string>}}, metadata: array<string, string>, temperature: ?float, top_p: ?float, response_format: string|array{type: 'text'|'json_object'}}> $response */
         $response = $this->transporter->requestObject($payload);
 
         return AssistantResponse::from($response->data(), $response->meta());
@@ -42,7 +41,7 @@ public function retrieve(string $id): AssistantResponse
     {
         $payload = Payload::retrieve('assistants', $id);
 
-        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'retrieval'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, file_ids: array<int, string>, metadata: array<string, string>}> $response */
+        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'file_search'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, tool_resources: array{code_interpreter?: array{file_ids: array<int,string>}, file_search?: array{vector_store_ids: array<int,string>}}, metadata: array<string, string>, temperature: ?float, top_p: ?float, response_format: string|array{type: 'text'|'json_object'}}> $response */
         $response = $this->transporter->requestObject($payload);
 
         return AssistantResponse::from($response->data(), $response->meta());
@@ -59,7 +58,7 @@ public function modify(string $id, array $parameters): AssistantResponse
     {
         $payload = Payload::modify('assistants', $id, $parameters);
 
-        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'retrieval'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, file_ids: array<int, string>, metadata: array<string, string>}> $response */
+        /** @var Response<array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'file_search'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, tool_resources: array{code_interpreter?: array{file_ids: array<int,string>}, file_search?: array{vector_store_ids: array<int,string>}}, metadata: array<string, string>, temperature: ?float, top_p: ?float, response_format: string|array{type: 'text'|'json_object'}}> $response */
         $response = $this->transporter->requestObject($payload);
 
         return AssistantResponse::from($response->data(), $response->meta());
@@ -91,19 +90,9 @@ public function list(array $parameters = []): AssistantListResponse
     {
         $payload = Payload::list('assistants', $parameters);
 
-        /** @var Response<array{object: string, data: array<int, array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'retrieval'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, file_ids: array<int, string>, metadata: array<string, string>}>, first_id: ?string, last_id: ?string, has_more: bool}> $response */
+        /** @var Response<array{object: string, data: array<int, array{id: string, object: string, created_at: int, name: ?string, description: ?string, model: string, instructions: ?string, tools: array<int, array{type: 'code_interpreter'}|array{type: 'file_search'}|array{type: 'function', function: array{description: string, name: string, parameters: array<string, mixed>}}>, tool_resources: array{code_interpreter?: array{file_ids: array<int,string>}, file_search?: array{vector_store_ids: array<int,string>}}, metadata: array<string, string>, temperature: ?float, top_p: ?float, response_format: string|array{type: 'text'|'json_object'}}>, first_id: ?string, last_id: ?string, has_more: bool}> $response */
         $response = $this->transporter->requestObject($payload);
 
         return AssistantListResponse::from($response->data(), $response->meta());
     }
-
-    /**
-     * Manage files attached to an assistant.
-     *
-     * @see https://platform.openai.com/docs/api-reference/assistants
-     */
-    public function files(): AssistantsFilesContract
-    {
-        return new AssistantsFiles($this->transporter);
-    }
 }