[0.8.x] Add Assistant API support (#243)

src/Client.php

@@ -5,7 +5,9 @@
 namespace OpenAI;
 
 use OpenAI\Contracts\ClientContract;
+use OpenAI\Contracts\Resources\ThreadsContract;
 use OpenAI\Contracts\TransporterContract;
+use OpenAI\Resources\Assistants;
 use OpenAI\Resources\Audio;
 use OpenAI\Resources\Chat;
 use OpenAI\Resources\Completions;
@@ -17,6 +19,7 @@
 use OpenAI\Resources\Images;
 use OpenAI\Resources\Models;
 use OpenAI\Resources\Moderations;
+use OpenAI\Resources\Threads;
 
 final class Client implements ClientContract
 {
@@ -140,4 +143,24 @@ public function images(): Images
     {
         return new Images($this->transporter);
     }
+
+    /**
+     * Build assistants that can call models and use tools to perform tasks.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants
+     */
+    public function assistants(): Assistants
+    {
+        return new Assistants($this->transporter);
+    }
+
+    /**
+     * Create threads that assistants can interact with.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads
+     */
+    public function threads(): ThreadsContract
+    {
+        return new Threads($this->transporter);
+    }
 }

src/Contracts/ClientContract.php

@@ -2,6 +2,7 @@
 
 namespace OpenAI\Contracts;
 
+use OpenAI\Contracts\Resources\AssistantsContract;
 use OpenAI\Contracts\Resources\AudioContract;
 use OpenAI\Contracts\Resources\ChatContract;
 use OpenAI\Contracts\Resources\CompletionsContract;
@@ -13,6 +14,7 @@
 use OpenAI\Contracts\Resources\ImagesContract;
 use OpenAI\Contracts\Resources\ModelsContract;
 use OpenAI\Contracts\Resources\ModerationsContract;
+use OpenAI\Contracts\Resources\ThreadsContract;
 
 interface ClientContract
 {
@@ -97,4 +99,18 @@ public function moderations(): ModerationsContract;
      * @see https://platform.openai.com/docs/api-reference/images
      */
     public function images(): ImagesContract;
+
+    /**
+     * Build assistants that can call models and use tools to perform tasks.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants
+     */
+    public function assistants(): AssistantsContract;
+
+    /**
+     * Create threads that assistants can interact with.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads
+     */
+    public function threads(): ThreadsContract;
 }

src/Contracts/Resources/AssistantsContract.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Assistants\AssistantDeleteResponse;
+use OpenAI\Responses\Assistants\AssistantListResponse;
+use OpenAI\Responses\Assistants\AssistantResponse;
+
+interface AssistantsContract
+{
+    /**
+     * Create an assistant with a model and instructions.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/object
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters): AssistantResponse;
+
+    /**
+     * Retrieves an assistant.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/getAssistant
+     */
+    public function retrieve(string $id): AssistantResponse;
+
+    /**
+     * Modifies an assistant.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/modifyAssistant
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function modify(string $id, array $parameters): AssistantResponse;
+
+    /**
+     * Delete an assistant.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/deleteAssistant
+     */
+    public function delete(string $id): AssistantDeleteResponse;
+
+    /**
+     * Returns a list of assistants.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/listAssistants
+     *
+     * @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/AssistantsFilesContract.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Assistants\Files\AssistantFileDeleteResponse;
+use OpenAI\Responses\Assistants\Files\AssistantFileListResponse;
+use OpenAI\Responses\Assistants\Files\AssistantFileResponse;
+
+interface AssistantsFilesContract
+{
+    /**
+     * Create an assistant file by attaching a File to an assistant.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/createAssistantFile
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $assistantId, array $parameters): AssistantFileResponse;
+
+    /**
+     * Retrieves an AssistantFile.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/getAssistantFile
+     */
+    public function retrieve(string $assistantId, string $fileId): AssistantFileResponse;
+
+    /**
+     * Delete an assistant file.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/deleteAssistantFile
+     */
+    public function delete(string $assistantId, string $fileId): AssistantFileDeleteResponse;
+
+    /**
+     * Returns a list of assistant files.
+     *
+     * @see https://platform.openai.com/docs/api-reference/assistants/listAssistantFiles
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $assistantId, array $parameters = []): AssistantFileListResponse;
+}

src/Contracts/Resources/ThreadsContract.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Threads\Runs\ThreadRunResponse;
+use OpenAI\Responses\Threads\ThreadDeleteResponse;
+use OpenAI\Responses\Threads\ThreadListResponse;
+use OpenAI\Responses\Threads\ThreadResponse;
+
+interface ThreadsContract
+{
+    /**
+     * Create a thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads/createThread
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters): ThreadResponse;
+
+    /**
+     * Create a thread and run it in one request.
+     *
+     * @see https://platform.openai.com/docs/api-reference/runs/createThreadAndRun
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function createAndRun(array $parameters): ThreadRunResponse;
+
+    /**
+     * Retrieves a thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads/getThread
+     */
+    public function retrieve(string $id): ThreadResponse;
+
+    /**
+     * Modifies a thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads/modifyThread
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function modify(string $id, array $parameters): ThreadResponse;
+
+    /**
+     * Delete an thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/threads/deleteThread
+     */
+    public function delete(string $id): ThreadDeleteResponse;
+
+    /**
+     * Returns a list of threads.
+     *
+     * @see TBA - there is no documentation yet
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(array $parameters = []): ThreadListResponse;
+
+    /**
+     * Manage messages attached to a thred.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages
+     */
+    public function messages(): ThreadsMessagesContract;
+
+    /**
+     * Represents an execution run on a thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/runs
+     */
+    public function runs(): ThreadsRunsContract;
+}

src/Contracts/Resources/ThreadsMessagesContract.php

@@ -0,0 +1,58 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Threads\Messages\ThreadMessageDeleteResponse;
+use OpenAI\Responses\Threads\Messages\ThreadMessageListResponse;
+use OpenAI\Responses\Threads\Messages\ThreadMessageResponse;
+
+interface ThreadsMessagesContract
+{
+    /**
+     * Create a message.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/createMessage
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $threadId, array $parameters): ThreadMessageResponse;
+
+    /**
+     * Retrieve a message.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/getMessage
+     */
+    public function retrieve(string $threadId, string $messageId): ThreadMessageResponse;
+
+    /**
+     * Modifies a message.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/modifyMessage
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function modify(string $threadId, string $messageId, array $parameters): ThreadMessageResponse;
+
+    /**
+     * Delete an message.
+     *
+     * @see TBD - there is no documentation yet
+     */
+    public function delete(string $threadId, string $messageId): ThreadMessageDeleteResponse;
+
+    /**
+     * Returns a list of messages for a given thread.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/listMessages
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $threadId, array $parameters = []): ThreadMessageListResponse;
+
+    /**
+     * Manage files attached to a thred message.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/file-object
+     */
+    public function files(): ThreadsMessagesFilesContract;
+}

src/Contracts/Resources/ThreadsMessagesFilesContract.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Threads\Messages\Files\ThreadMessageFileListResponse;
+use OpenAI\Responses\Threads\Messages\Files\ThreadMessageFileResponse;
+
+interface ThreadsMessagesFilesContract
+{
+    /**
+     * Retrieves a message file.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/getMessageFile
+     */
+    public function retrieve(string $threadId, string $messageId, string $fileId): ThreadMessageFileResponse;
+
+    /**
+     * Returns a list of message files.
+     *
+     * @see https://platform.openai.com/docs/api-reference/messages/listMessageFiles
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $threadId, string $messageId, array $parameters = []): ThreadMessageFileListResponse;
+}