Merge pull request #35 from tectalichq/feature/1.6.0

v1.6.0 Release: Adds new fine-tuning API

Author: thejamescollins

CHANGELOG.md

@@ -5,6 +5,55 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.6.0 - 2023-09-06
+
+### Added
+- Add support for OpenAI's new **fine-tuning** API, which allows fine-tuning of GPT 3.5 Turbo. [Fine-tuning guide](https://platform.openai.com/docs/guides/fine-tuning). [Announcement](https://openai.com/blog/gpt-3-5-turbo-fine-tuning-and-api-updates).
+- Add new `FineTuningJobs` Handler, which creates and lists fine-tuning jobs.
+- Add new `FineTuningJobsEvents` Handler, which gets status updates for a given fine-tuning job.
+- Add new `FineTuningJobsCancel` Handler, which cancels an existing fine-tuning job.
+- Add support for new content moderation categories: `harassment/threatening`, `self-harm/intent`, `self-harm/instructions`. [Moderation guide](https://platform.openai.com/docs/guides/moderation).
+
+### Changed
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateRequestFunctionsItem::$parameters` property is now required.
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateRequestMessagesItem::$content` property is now required.
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateRequestMessagesItemFunctionCall` `name` and `arguments` properties are now required.
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateResponseChoicesItem` `index`, `message` and `finish_reason` properties are now required.
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateResponseChoicesItemMessage::$content` property is now required.
+- The `\Tectalic\OpenAi\Models\ChatCompletions\CreateResponseChoicesItemMessageFunctionCall` `name` and `arguments` properties are now required.
+- The `\Tectalic\OpenAi\Models\Edits\CreateResponseChoicesItem` `text`, `index` and `finish_reason` properties are now required.
+- The `\Tectalic\OpenAi\Models\Edits\CreateResponseChoicesItem::$logprobs` property has been removed.
+- The `\Tectalic\OpenAi\Models\Files\CreateResponse::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\Files\ListResponseDataItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\Files\RetrieveResponse::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\CreateResponseHyperparams` model structure is now defined, with the following required properties: `n_epochs`, `batch_size`, `prompt_loss_weight` and `learning_rate_multiplier`.
+- The `\Tectalic\OpenAi\Models\FineTunes\CreateResponseResultFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\CreateResponseTrainingFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\CreateResponseValidationFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\ListResponseDataItemHyperparams` model structure is now defined, with the following required properties: `n_epochs`, `batch_size`, `prompt_loss_weight` and `learning_rate_multiplier`.
+- The `\Tectalic\OpenAi\Models\FineTunes\ListResponseDataItemResultFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\ListResponseDataItemTrainingFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\ListResponseDataItemValidationFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\RetrieveResponseHyperparams` model structure is now defined, with the following required properties: `n_epochs`, `batch_size`, `prompt_loss_weight` and `learning_rate_multiplier`.
+- The `\Tectalic\OpenAi\Models\FineTunes\RetrieveResponseResultFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\RetrieveResponseTrainingFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\RetrieveResponseValidationFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunes\RetrieveResponseValidationFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunesCancel\CancelFineTuneResponseHyperparams` model structure is now defined, with the following required properties: `n_epochs`, `batch_size`, `prompt_loss_weight` and `learning_rate_multiplier`.
+- The `\Tectalic\OpenAi\Models\FineTunesCancel\CancelFineTuneResponseResultFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunesCancel\CancelFineTuneResponseTrainingFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\FineTunesCancel\CancelFineTuneResponseValidationFilesItem::$format` property is now required.
+- The `\Tectalic\OpenAi\Models\Moderations\CreateResponseResultsItemCategories` model now supports `harassment/threatening`, `self-harm/intent`, `self-harm/instructions` information.
+- The `\Tectalic\OpenAi\Models\Moderations\CreateResponseResultsItemCategoryScores` model now supports `harassment/threatening`, `self-harm/intent`, `self-harm/instructions` information.
+- Improved documentation for many model properties.
+- API version updated from 1.3.1 to 2.0.0.
+
+### Deprecated
+- Deprecate the `Edits` Handler. The `ChatCompletions` handler should be used instead. These endpoints will be shut down on January 04, 2024.
+- Deprecate the `FineTunes` Handler. The new `FineTunesJobs` handler should be used instead. These endpoints will be shut down on January 04, 2024.
+- Deprecate the `FineTunesEvents` Handler. The new `FineTunesJobsEvents` handler should be used instead. These endpoints will be shut down on January 04, 2024.
+- Deprecate the `FineTunesCancel` Handler. The new `FineTunesJobsCancel` handler should be used instead. These endpoints will be shut down on January 04, 2024.
+
 ## 1.5.0 - 2023-06-19
 
 ### Added

README.md

@@ -4,7 +4,7 @@
 
 The **Tectalic OpenAI REST API Client** is a package that provides a convenient and straightforward way to interact with the **OpenAI API** from your PHP application.
 
-Supports **ChatGPT**, **GPT-4**, **GPT-3.5**, **GPT-3**, **Codex**, **DALL·E**, **Whisper**, **Embeddings** and **Moderation** models, with fully typed Data Transfer Objects (DTOs) for all requests and responses and IDE autocomplete support.
+Supports **ChatGPT**, **GPT-4**, **GPT-3.5**, **GPT-3**, **Codex**, **DALL·E**, **Whisper**, **Fine-Tuning**, **Embeddings** and **Moderation** models, with fully typed Data Transfer Objects (DTOs) for all requests and responses and IDE autocomplete support.
 
 More information is available from [https://tectalic.com/apis/openai](https://tectalic.com/apis/openai).
 
@@ -291,43 +291,50 @@ In the **Usage** code above, customize the `Authentication` constructor to your
 
 The primary class you will interact with is the `Client` class (`Tectalic\OpenAi\Client`).
 
-This `Client` class also contains the helper methods that let you quickly access the 16 API Handlers.
+This `Client` class also contains the helper methods that let you quickly access the 19 API Handlers.
 
 Please see below for a complete list of supported handlers and methods.
 
 ### Supported API Handlers and Methods
 
-This package supports 23 API Methods, which are grouped into 16 API Handlers.
+This package supports 28 API Methods, which are grouped into 19 API Handlers.
 
 See the table below for a full list of API Handlers and Methods.
 
 
 | API Handler Class and Method Name | Description | API Verb and URL |
 | --------------------------------- | ----------- | ---------------- |
 |`AudioTranscriptions::create()`|Transcribes audio into the input language.|`POST` `/audio/transcriptions`|
-|`AudioTranslations::create()`|Translates audio into into English.|`POST` `/audio/translations`|
+|`AudioTranslations::create()`|Translates audio into English.|`POST` `/audio/translations`|
 |`ChatCompletions::create()`|Creates a model response for the given chat conversation.|`POST` `/chat/completions`|
 |`Completions::create()`|Creates a completion for the provided prompt and parameters.|`POST` `/completions`|
-|`Edits::create()`|Creates a new edit for the provided input, instruction, and parameters.|`POST` `/edits`|
+|~~`Edits::create()`~~|~~Creates a new edit for the provided input, instruction, and parameters.~~|~~`POST` `/edits`~~|
 |`Embeddings::create()`|Creates an embedding vector representing the input text.|`POST` `/embeddings`|
 |`Files::list()`|Returns a list of files that belong to the user's organization.|`GET` `/files`|
 |`Files::create()`|Upload a file that contains document(s) to be used across various endpoints/features. Currently, the size of all the files uploaded by one organization can be up to 1 GB. Please contact us if you need to increase the storage limit.|`POST` `/files`|
 |`Files::retrieve()`|Returns information about a specific file.|`GET` `/files/{file_id}`|
 |`Files::delete()`|Delete a file.|`DELETE` `/files/{file_id}`|
-|`FilesContent::download()`|Returns the contents of the specified file|`GET` `/files/{file_id}/content`|
-|`FineTunes::list()`|List your organization's fine-tuning jobs|`GET` `/fine-tunes`|
-|`FineTunes::create()`|Creates a job that fine-tunes a specified model from a given dataset.<br />Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.<br />Learn more about Fine-tuning|`POST` `/fine-tunes`|
-|`FineTunes::retrieve()`|Gets info about the fine-tune job.<br />Learn more about Fine-tuning|`GET` `/fine-tunes/{fine_tune_id}`|
-|`FineTunesCancel::cancelFineTune()`|Immediately cancel a fine-tune job.|`POST` `/fine-tunes/{fine_tune_id}/cancel`|
-|`FineTunesEvents::listFineTune()`|Get fine-grained status updates for a fine-tune job.|`GET` `/fine-tunes/{fine_tune_id}/events`|
+|`FilesContent::download()`|Returns the contents of the specified file.|`GET` `/files/{file_id}/content`|
+|~~`FineTunes::list()`~~|~~List your organization's fine-tuning jobs~~|~~`GET` `/fine-tunes`~~|
+|~~`FineTunes::create()`~~|~~Creates a job that fine-tunes a specified model from a given dataset.<br />Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.<br />Learn more about fine-tuning~~|~~`POST` `/fine-tunes`~~|
+|~~`FineTunes::retrieve()`~~|~~Gets info about the fine-tune job.<br />Learn more about fine-tuning~~|~~`GET` `/fine-tunes/{fine_tune_id}`~~|
+|~~`FineTunesCancel::cancelFineTune()`~~|~~Immediately cancel a fine-tune job.~~|~~`POST` `/fine-tunes/{fine_tune_id}/cancel`~~|
+|~~`FineTunesEvents::listFineTune()`~~|~~Get fine-grained status updates for a fine-tune job.~~|~~`GET` `/fine-tunes/{fine_tune_id}/events`~~|
+|`FineTuningJobs::listPaginated()`|List your organization's fine-tuning jobs|`GET` `/fine_tuning/jobs`|
+|`FineTuningJobs::create()`|Creates a job that fine-tunes a specified model from a given dataset.<br />Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.<br />Learn more about fine-tuning|`POST` `/fine_tuning/jobs`|
+|`FineTuningJobs::retrieve()`|Get info about a fine-tuning job.<br />Learn more about fine-tuning|`GET` `/fine_tuning/jobs/{fine_tuning_job_id}`|
+|`FineTuningJobsCancel::fineTuning()`|Immediately cancel a fine-tune job.|`POST` `/fine_tuning/jobs/{fine_tuning_job_id}/cancel`|
+|`FineTuningJobsEvents::listFineTuning()`|Get status updates for a fine-tuning job.|`GET` `/fine_tuning/jobs/{fine_tuning_job_id}/events`|
 |`ImagesEdits::createImage()`|Creates an edited or extended image given an original image and a prompt.|`POST` `/images/edits`|
 |`ImagesGenerations::create()`|Creates an image given a prompt.|`POST` `/images/generations`|
 |`ImagesVariations::createImage()`|Creates a variation of a given image.|`POST` `/images/variations`|
 |`Models::list()`|Lists the currently available models, and provides basic information about each one such as the owner and availability.|`GET` `/models`|
 |`Models::retrieve()`|Retrieves a model instance, providing basic information about the model such as the owner and permissioning.|`GET` `/models/{model}`|
-|`Models::delete()`|Delete a fine-tuned model. You must have the Owner role in your organization.|`DELETE` `/models/{model}`|
+|`Models::delete()`|Delete a fine-tuned model. You must have the Owner role in your organization to delete a model.|`DELETE` `/models/{model}`|
 |`Moderations::create()`|Classifies if text violates OpenAI's Content Policy|`POST` `/moderations`|
 
+Deprecated method(s) are listed with ~~strike-through~~ formatting. Please do not use these methods, as they will be removed in a future release.
+
 ### Making a Request
 
 There are two ways to make a request to the nominated API Handler and API Method:

composer.json

@@ -1,6 +1,6 @@
 {
   "name": "tectalic/openai",
-  "description": "An OpenAI REST API Client with support for ChatGPT, GPT-4, GPT-3.5, GPT-3, Codex, DALL·E, Whisper, Embeddings and Moderation models. Includes fully typed Data Transfer Objects (DTOs) for all requests and responses and IDE autocomplete support.",
+  "description": "An OpenAI REST API Client with support for ChatGPT, GPT-4, GPT-3.5, GPT-3, Codex, DALL·E, Whisper, Embeddings, Fine-Tuning and Moderation models. Includes fully typed Data Transfer Objects (DTOs) for all requests and responses and IDE autocomplete support.",
   "type": "library",
   "license": "MIT",
   "keywords": [
@@ -9,6 +9,7 @@
     "chatgpt",
     "dalle",
     "dall-e",
+    "fine-tuning",
     "gpt-3",
     "gpt-3.5",
     "gpt-4",

manifest.json

@@ -1,5 +1,5 @@
 {
-    "libraryVersion": "1.5.0",
-    "apiVersion": "1.3.1",
-    "buildVersion": "1.2.1"
+    "libraryVersion": "1.6.0",
+    "apiVersion": "2.0.0",
+    "buildVersion": "1.2.2"
 }

src/Client.php

@@ -31,6 +31,9 @@
 use Tectalic\OpenAi\Handlers\FineTunes;
 use Tectalic\OpenAi\Handlers\FineTunesCancel;
 use Tectalic\OpenAi\Handlers\FineTunesEvents;
+use Tectalic\OpenAi\Handlers\FineTuningJobs;
+use Tectalic\OpenAi\Handlers\FineTuningJobsCancel;
+use Tectalic\OpenAi\Handlers\FineTuningJobsEvents;
 use Tectalic\OpenAi\Handlers\ImagesEdits;
 use Tectalic\OpenAi\Handlers\ImagesGenerations;
 use Tectalic\OpenAi\Handlers\ImagesVariations;
@@ -96,6 +99,8 @@ public function completions(): Completions
     /**
      * Access to the edits handler.
      *
+     * @deprecated
+     *
      * @api
      * @return Edits
      */
@@ -192,9 +197,44 @@ public function filesContent(): FilesContent
         return new \Tectalic\OpenAi\Handlers\FilesContent($this);
     }
 
+    /**
+     * Access to the fineTuningJobs handler.
+     *
+     * @api
+     * @return FineTuningJobs
+     */
+    public function fineTuningJobs(): FineTuningJobs
+    {
+        return new \Tectalic\OpenAi\Handlers\FineTuningJobs($this);
+    }
+
+    /**
+     * Access to the fineTuningJobsEvents handler.
+     *
+     * @api
+     * @return FineTuningJobsEvents
+     */
+    public function fineTuningJobsEvents(): FineTuningJobsEvents
+    {
+        return new \Tectalic\OpenAi\Handlers\FineTuningJobsEvents($this);
+    }
+
+    /**
+     * Access to the fineTuningJobsCancel handler.
+     *
+     * @api
+     * @return FineTuningJobsCancel
+     */
+    public function fineTuningJobsCancel(): FineTuningJobsCancel
+    {
+        return new \Tectalic\OpenAi\Handlers\FineTuningJobsCancel($this);
+    }
+
     /**
      * Access to the fineTunes handler.
      *
+     * @deprecated
+     *
      * @api
      * @return FineTunes
      */
@@ -206,6 +246,8 @@ public function fineTunes(): FineTunes
     /**
      * Access to the fineTunesCancel handler.
      *
+     * @deprecated
+     *
      * @api
      * @return FineTunesCancel
      */
@@ -217,6 +259,8 @@ public function fineTunesCancel(): FineTunesCancel
     /**
      * Access to the fineTunesEvents handler.
      *
+     * @deprecated
+     *
      * @api
      * @return FineTunesEvents
      */
@@ -406,7 +450,7 @@ private function mergeRequestParts(
 
         $request = $request->withHeader(
             'User-Agent',
-            'Tectalic OpenAI REST API Client/1.5.0'
+            'Tectalic OpenAI REST API Client/1.6.0'
         );
 
         // Merge Headers.

src/Handlers/AudioTranslations.php

@@ -43,7 +43,7 @@ public function __construct(?Client $client = null)
     }
 
     /**
-     * Translates audio into into English.
+     * Translates audio into English.
      *
      * Operation URL: POST /audio/translations
      * Operation ID:  createTranslation

src/Handlers/Edits.php

@@ -23,6 +23,9 @@
 use Tectalic\OpenAi\Models\Edits\CreateResponse;
 use Throwable;
 
+/**
+ * @deprecated
+ */
 final class Edits
 {
     /** @var Client */
@@ -50,6 +53,8 @@ public function __construct(?Client $client = null)
      *
      * @param CreateRequest|array $body
      *
+     * @deprecated
+     *
      * @api
      * @return self
      */

src/Handlers/Files.php

@@ -98,7 +98,7 @@ public function create($body): self
      * Operation URL: GET /files/{file_id}
      * Operation ID:  retrieveFile
      *
-     * @param string $fileId The ID of the file to use for this request
+     * @param string $fileId The ID of the file to use for this request.
      *
      * @api
      * @return self
@@ -121,7 +121,7 @@ public function retrieve($fileId): self
      * Operation URL: DELETE /files/{file_id}
      * Operation ID:  deleteFile
      *
-     * @param string $fileId The ID of the file to use for this request
+     * @param string $fileId The ID of the file to use for this request.
      *
      * @api
      * @return self

src/Handlers/FilesContent.php

@@ -42,12 +42,12 @@ public function __construct(?Client $client = null)
     }
 
     /**
-     * Returns the contents of the specified file
+     * Returns the contents of the specified file.
      *
      * Operation URL: GET /files/{file_id}/content
      * Operation ID:  downloadFile
      *
-     * @param string $fileId The ID of the file to use for this request
+     * @param string $fileId The ID of the file to use for this request.
      *
      * @api
      * @return self

src/Handlers/FineTunes.php

@@ -25,6 +25,9 @@
 use Tectalic\OpenAi\Models\FineTunes\RetrieveResponse;
 use Throwable;
 
+/**
+ * @deprecated
+ */
 final class FineTunes
 {
     /** @var Client */
@@ -50,6 +53,8 @@ public function __construct(?Client $client = null)
      * Operation URL: GET /fine-tunes
      * Operation ID:  listFineTunes
      *
+     * @deprecated
+     *
      * @api
      * @return self
      */
@@ -69,13 +74,15 @@ public function list(): self
      * Creates a job that fine-tunes a specified model from a given dataset.
      * Response includes details of the enqueued job including job status and the name
      * of the fine-tuned models once complete.
-     * Learn more about Fine-tuning
+     * Learn more about fine-tuning
      *
      * Operation URL: POST /fine-tunes
      * Operation ID:  createFineTune
      *
      * @param CreateRequest|array $body
      *
+     * @deprecated
+     *
      * @api
      * @return self
      */
@@ -93,13 +100,15 @@ public function create($body): self
 
     /**
      * Gets info about the fine-tune job.
-     * Learn more about Fine-tuning
+     * Learn more about fine-tuning
      *
      * Operation URL: GET /fine-tunes/{fine_tune_id}
      * Operation ID:  retrieveFineTune
      *
      * @param string $fineTuneId The ID of the fine-tune job
      *
+     * @deprecated
+     *
      * @api
      * @return self
      */