asimov 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c50684e3e690496248b87a912334da4b3ace87c83dec1c05e2d8b33349c5d16d
-  data.tar.gz: 6ab91367f32fa02d4582018fd6cad490ba4e78db92c86e231b64323a3389d88f
+  metadata.gz: b71726c0c67788a649dc1c01ca5763ab13d41f31118d6f8b093795a3a92e0ca8
+  data.tar.gz: 5d5eb6dd51099aadf9418ff1c11c7ea6688a06a5e07b5a39bd376a48538ac79a
 SHA512:
-  metadata.gz: 859bbbfccff90fdddac6708846bc03b2a6f175bf83fd7ad9329a3de86d8830444e34d822eeeb65d4ba054678b1cda15312b85ca52b4dea2e43dc83cc2554e908
-  data.tar.gz: 169621c5fe064acc1ba293a01da9473c75aae65f7a650139c377319990140f2295fdae39d5b231fae7f3df7a506224d99e9f7d64acfb46af6967841ec46072c5
+  metadata.gz: b20449b89964c2b2b77de68726aef47bc09e65871ba04c80ad2f607e58bc5b6322ff6106c801f01ef68377056a55010d74e6481f883ad57793eca5366a438acd
+  data.tar.gz: fdfe13acb265341e7c568874a8696ce520b6da8fbdc77ae694b3ba56deb97d44a65aac82935a3ad3f356258aa0375358349540c17cd54bfd0f9a3a746d40b807

data/CHANGELOG.md

@@ -5,9 +5,35 @@ 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).
 
+## Unreleased
+
+## [1.0.0] - 2023-01-24
+
+This version has complete coverage of the OpenAI API (except for stream: true behavior), has
+no known errors and has full test coverage.  At this point there are no anticipated changes
+to existing endpoints.
+
+### Fixed
+
+- Fixed handling of authentication errors
+
+### Changed
+
+- Properly distinguished public and private methods to ensure proper documentation.
+- Renamed events to list_events for consistency
+- Updated file arguments to take path strings or File-like objects
+- Adjusted endpoints to make required parameters more explicit
+
+### Added
+
+- Code level documentation for all public classes and methods.
+- Error for the unsupported stream: true case
+- Error mapping for 409 and 429 errors
+- Specs for authentication
+
 ## [0.1.0] - 2023-01-14
 
-This initial version of the gem is now suitable for use.  API endpoint method naming may shift slightly, 
+This initial version of the gem is now suitable for use.  API endpoint method naming may shift slightly.
 
 ### Changed
 

data/Gemfile

@@ -2,4 +2,13 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "simplecov", require: false, group: :test
+group :development, :test do
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.12"
+  gem "rubocop", "~> 1.44"
+  gem "rubocop-rake"
+  gem "rubocop-rspec"
+  gem "simplecov", require: false
+  gem "vcr", "~> 6.1.0"
+  gem "webmock", "~> 3.18.1"
+end

data/README.md

@@ -1,5 +1,6 @@
 # Asimov
 
+[![Gem Version](https://badge.fury.io/rb/asimov.svg)](https://badge.fury.io/rb/asimov)
 [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/petergoldstein/asimov/blob/main/LICENSE.txt)
 [![Tests](https://github.com/petergoldstein/asimov/actions/workflows/ci.yml/badge.svg)](https://github.com/petergoldstein/asimov/actions/workflows/ci.yml)
 

data/lib/asimov/api_v1/api_error_translator.rb

@@ -8,26 +8,47 @@ module Asimov
     # fragile.
     ##
     class ApiErrorTranslator
+      ##
+      # This method raises an appropriate Asimov::RequestError
+      # subclass if the response corresponds to an HTTP error.
+      #
+      # @param [HTTParty::Response] resp the response (or fragment) object
+      # encapsulating the server response.
+      ##
       def self.translate(resp)
+        return if resp.code == 200
+
         match_400(resp)
         match_401(resp)
         match_404(resp)
+        match_409(resp)
+        match_429(resp)
+
+        raise Asimov::RequestError, error_message(resp)
       end
 
       # rubocop:disable Naming/VariableNumber
       # rubocop:disable Metrics/MethodLength
+
+      # Prefix for OpenAI error message when an invalid key is provided.
       INVALID_API_KEY_PREFIX = "Incorrect API key provided: ".freeze
+
+      # Prefix for OpenAI error message when an organization cannot be found.
       INVALID_ORGANIZATION_PREFIX = "No such organization: ".freeze
       def self.match_401(resp)
         return unless resp.code == 401
 
         msg = error_message(resp)
         raise Asimov::InvalidApiKeyError, msg if msg.start_with?(INVALID_API_KEY_PREFIX)
-        raise Asimov::InvalidOrganizationError, msg if msg.start_with?(INVALID_API_KEY_PREFIX)
+        raise Asimov::InvalidOrganizationError, msg if msg.start_with?(INVALID_ORGANIZATION_PREFIX)
 
-        raise Asimov::UnauthorizedError
+        raise Asimov::AuthorizationError
       end
+      private_class_method :match_401
+      private_constant :INVALID_API_KEY_PREFIX
+      private_constant :INVALID_ORGANIZATION_PREFIX
 
+      # Prefix for OpenAI error message when training file format cannot be validated.
       INVALID_TRAINING_EXAMPLE_PREFIX = "Expected file to have JSONL format with " \
                                         "prompt/completion keys. Missing".freeze
       ADDITIONAL_PROPERTIES_ERROR_PREFIX = "Additional properties are not allowed".freeze
@@ -39,28 +60,6 @@ module Asimov
         return unless resp.code == 400
 
         msg = error_message(resp)
-        # 400
-        # {"error"=>{"message"=>"'moose' is not one of ['fine-tune', 'answers', 'search', " \
-        #                       "'classifications'] - 'purpose'", "type"=>"invalid_request_error",
-        #                       "param"=>nil, "code"=>nil}}
-        # {"error"=>{"code"=>nil, "message"=>"'8x8' is not one of ['256x256', '512x512', " \
-        #                                    "'1024x1024'] - 'size'", "param"=>nil,
-        #            "type"=>"invalid_request_error"}}
-        # {"error"=>{"message"=>"Incorrect format for purpose=classifications. Please check " \
-        #                       "the openai documentation and try again",
-        #            "type"=>"invalid_request_error", "param"=>nil, "code"=>nil}}
-        # {"error"=>{"message"=>"Expected file to have the JSONL format with 'text' key " \
-        #                       "and (optional) 'metadata' key.",
-        #            "type"=>"invalid_request_error", "param"=>nil, "code"=>nil}}
-        # {"error"=>{"message"=>"Additional properties are not allowed ('moose' was unexpected)",
-        #            "type"=>"invalid_request_error", "param"=>nil, "code"=>nil}}
-        # {"error"=>{"message"=>"Additional properties are not allowed ('moose', 'squirrel' were " \
-        #                       "unexpected)",
-        #            "type"=>"invalid_request_error", "param"=>nil, "code"=>nil}}
-        # {"error"=>{"code"=>nil, "message"=>"-1 is less than the minimum of 1 - 'n'",
-        #  "param"=>nil, "type"=>"invalid_request_error"}}
-        # {"error"=>{"code"=>nil, "message"=>"20 is greater than the maximum of 10 - 'n'",
-        #  "param"=>nil, "type"=>"invalid_request_error"}}
 
         if msg.start_with?(INVALID_TRAINING_EXAMPLE_PREFIX)
           raise Asimov::InvalidTrainingExampleError,
@@ -78,6 +77,50 @@ module Asimov
 
         raise Asimov::RequestError, msg
       end
+      private_class_method :match_400
+      private_constant :INVALID_TRAINING_EXAMPLE_PREFIX
+      private_constant :ADDITIONAL_PROPERTIES_ERROR_PREFIX
+      private_constant :INVALID_PARAMETER_VALUE_STRING
+      private_constant :INVALID_PARAMETER_VALUE_PREFIX_2
+      private_constant :BELOW_MINIMUM_STRING
+      private_constant :ABOVE_MAXIMUM_STRING
+
+      def self.match_409(resp)
+        return unless resp.code == 409
+
+        raise Asimov::RequestError, error_message(resp)
+      end
+      private_class_method :match_409
+
+      QUOTA_EXCEEDED_MESSAGE = "You exceeded your current quota".freeze
+      RATE_LIMIT_REACHED_MESSAGE = "Rate limit reached".freeze
+      ENGINE_OVERLOADED_MESSAGE = "The engine is currently overloaded".freeze
+      def self.match_429(resp)
+        return unless resp.code == 429
+
+        msg = error_message(resp)
+
+        if msg.start_with?(QUOTA_EXCEEDED_MESSAGE)
+          raise Asimov::QuotaExceededError,
+                msg
+        end
+
+        if msg.start_with?(RATE_LIMIT_REACHED_MESSAGE)
+          raise Asimov::RateLimitError,
+                msg
+        end
+
+        if msg.start_with?(ENGINE_OVERLOADED_MESSAGE)
+          raise Asimov::ApiOverloadedError,
+                msg
+        end
+
+        raise Asimov::TooManyRequestsError, msg
+      end
+      private_class_method :match_429
+      private_constant :QUOTA_EXCEEDED_MESSAGE
+      private_constant :RATE_LIMIT_REACHED_MESSAGE
+      private_constant :ENGINE_OVERLOADED_MESSAGE
 
       def self.match_invalid_parameter_value?(msg)
         msg.include?(INVALID_PARAMETER_VALUE_STRING) ||
@@ -85,17 +128,15 @@ module Asimov
           msg.include?(ABOVE_MAXIMUM_STRING) ||
           msg.start_with?(INVALID_PARAMETER_VALUE_PREFIX_2)
       end
+      private_class_method :match_invalid_parameter_value?
 
       def self.match_404(resp)
         return unless resp.code == 404
 
         msg = error_message(resp)
-        # {"error"=>{"message"=>"That model does not exist", "type"=>"invalid_request_error",
-        #  "param"=>"model", "code"=>nil}}
-        # {"error"=>{"message"=>"No such File object: file-BWp1k9EVJRq5Ybjr3Mb0tDXW",
-        #  "type"=>"invalid_request_error", "param"=>"id", "code"=>nil}}
         raise Asimov::NotFoundError, msg
       end
+      private_class_method :match_404
 
       # rubocop:enable Naming/VariableNumber
       # rubocop:enable Metrics/MethodLength
@@ -110,6 +151,7 @@ module Asimov
 
         pr["error"]["message"] || ""
       end
+      private_class_method :error_message
     end
   end
 end

data/lib/asimov/api_v1/base.rb

@@ -2,6 +2,10 @@ require_relative "./api_error_translator"
 require_relative "./network_error_translator"
 
 module Asimov
+  ##
+  # Classes and method associated with the requests, responses, and
+  # errors associated with v1 of the OpenAI API.
+  ##
   module ApiV1
     ##
     # Base class for API interface implementations. Currently
@@ -18,6 +22,12 @@ module Asimov
       end
       def_delegators :@client, :headers, :request_options
 
+      ##
+      # Executes an HTTP DELETE on the specified path.
+      #
+      # @param [String] path the URI (when combined with the
+      # base_uri) against which the DELETE is executed.
+      ##
       def http_delete(path:)
         wrap_response_with_error_handling do
           self.class.delete(
@@ -27,6 +37,12 @@ module Asimov
         end
       end
 
+      ##
+      # Executes an HTTP GET on the specified path.
+      #
+      # @param [String] path the URI (when combined with the
+      # base_uri) against which the GET is executed.
+      ##
       def http_get(path:)
         wrap_response_with_error_handling do
           self.class.get(
@@ -36,6 +52,12 @@ module Asimov
         end
       end
 
+      ##
+      # Executes an HTTP POST with JSON-encoded parameters on the specified path.
+      #
+      # @param [String] path the URI (when combined with the
+      # base_uri) against which the POST is executed.
+      ##
       def json_post(path:, parameters:)
         wrap_response_with_error_handling do
           self.class.post(
@@ -46,6 +68,12 @@ module Asimov
         end
       end
 
+      ##
+      # Executes an HTTP POST with multipart encoded parameters on the specified path.
+      #
+      # @param [String] path the URI (when combined with the
+      # base_uri) against which the POST is executed.
+      ##
       def multipart_post(path:, parameters: nil)
         wrap_response_with_error_handling do
           self.class.post(
@@ -56,20 +84,27 @@ module Asimov
         end
       end
 
+      ##
+      # Executes an HTTP GET on the specified path, streaming the resulting body
+      # to the writer in case of success.
+      #
+      # @param [String] path the URI (when combined with the
+      # base_uri) against which the POST is executed.
+      # @param [Writer] writer an object, typically a File, that responds to a `write` method
+      ##
       def http_streamed_download(path:, writer:)
         self.class.get(path,
                        { headers: headers,
                          stream_body: true }.merge!(request_options)) do |fragment|
           fragment.code == 200 ? writer.write(fragment) : check_for_api_error(fragment)
         end
-      rescue Asimov::RequestError => e
-        # Raise any translated API errors
-        raise e
       rescue StandardError => e
-        # Otherwise translate the error to a network error
+        # Any error raised by the HTTP call is a network error
         NetworkErrorTranslator.translate(e)
       end
 
+      private
+
       def wrap_response_with_error_handling
         resp = begin
           yield
@@ -84,7 +119,6 @@ module Asimov
         return if resp.code == 200
 
         ApiErrorTranslator.translate(resp)
-        resp
       end
     end
   end

data/lib/asimov/api_v1/completions.rb

@@ -4,10 +4,17 @@ module Asimov
     # Class interface for API methods in the "/completions" URI subspace.
     ##
     class Completions < Base
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:model) unless parameters[:model]
+      ##
+      # Calls the /completions POST endpoint with the specified parameters.
+      #
+      # @param [String] model the model to use for the completion
+      # @param [Hash] parameters the set of parameters being passed to the API
+      ##
+      def create(model:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+        raise StreamingResponseNotSupportedError if parameters[:stream]
 
-        json_post(path: "/completions", parameters: parameters)
+        json_post(path: "/completions", parameters: parameters.merge({ model: model }))
       end
     end
   end

data/lib/asimov/api_v1/edits.rb

@@ -4,11 +4,18 @@ module Asimov
     # Class interface for API methods in the "/edits" URI subspace.
     ##
     class Edits < Base
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:model) unless parameters[:model]
-        raise MissingRequiredParameterError.new(:instruction) unless parameters[:instruction]
+      ##
+      # Calls the /edits POST endpoint with the specified parameters.
+      #
+      # @param [Hash] parameters the set of parameters being passed to the API
+      ##
+      def create(model:, instruction:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+        raise MissingRequiredParameterError.new(:instruction) unless instruction
 
-        json_post(path: "/edits", parameters: parameters)
+        json_post(path: "/edits",
+                  parameters: parameters.merge({ model: model,
+                                                 instruction: instruction }))
       end
     end
   end

data/lib/asimov/api_v1/embeddings.rb

@@ -4,11 +4,16 @@ module Asimov
     # Class interface for API methods in the "/embeddings" URI subspace.
     ##
     class Embeddings < Base
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:model) unless parameters[:model]
-        raise MissingRequiredParameterError.new(:input) unless parameters[:input]
+      ##
+      # Calls the /embeddings POST endpoint with the specified parameters.
+      #
+      # @param [Hash] parameters the set of parameters being passed to the API
+      ##
+      def create(model:, input:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+        raise MissingRequiredParameterError.new(:input) unless input
 
-        json_post(path: "/embeddings", parameters: parameters)
+        json_post(path: "/embeddings", parameters: parameters.merge({ model: model, input: input }))
       end
     end
   end

data/lib/asimov/api_v1/files.rb

@@ -11,6 +11,7 @@ module Asimov
     ##
     class Files < Base
       URI_PREFIX = "/files".freeze
+      private_constant :URI_PREFIX
 
       ##
       # Lists files that have been uploaded to OpenAI
@@ -19,26 +20,50 @@ module Asimov
         http_get(path: URI_PREFIX)
       end
 
-      def upload(parameters:)
-        raise MissingRequiredParameterError.new(:file) unless parameters[:file]
-        raise MissingRequiredParameterError.new(:purpose) unless parameters[:purpose]
+      ##
+      # Uploads a file to the /files endpoint with the specified parameters.
+      #
+      # @param [String] file file name  or a File-like object to be uploaded
+      # @param [Hash] parameters the set of parameters being passed to the API
+      ##
+      def upload(file:, purpose:, parameters: {})
+        raise MissingRequiredParameterError.new(:file) unless file
+        raise MissingRequiredParameterError.new(:purpose) unless purpose
 
-        validate(parameters[:file], parameters[:purpose])
+        validate(file, purpose)
 
         multipart_post(
           path: URI_PREFIX,
-          parameters: parameters.merge(file: Utils::FileManager.open(parameters[:file]))
+          parameters: parameters.merge(file: Utils::FileManager.open(file), purpose: purpose)
         )
       end
 
+      ##
+      # Retrieves the file with the specified file_id from OpenAI.
+      #
+      # @param [String] file_id the id of the file to be retrieved
+      ##
       def retrieve(file_id:)
         http_get(path: "#{URI_PREFIX}/#{file_id}")
       end
 
+      ##
+      # Deletes the file with the specified file_id from OpenAI.
+      #
+      # @param [String] file_id the id of the file to be deleted
+      ##
       def delete(file_id:)
         http_delete(path: "#{URI_PREFIX}/#{file_id}")
       end
 
+      ##
+      # Retrieves the contents of the file with the specified file_id from OpenAI
+      # and passes those contents to the writer in a chunked manner.
+      #
+      # @param [String] file_id the id of the file to be retrieved
+      # @param [Writer] writer the Writer that will process the chunked content
+      # as it is received from the API
+      ##
       def content(file_id:, writer:)
         http_streamed_download(path: "#{URI_PREFIX}/#{file_id}/content", writer: writer)
       end

data/lib/asimov/api_v1/finetunes.rb

@@ -5,26 +5,51 @@ module Asimov
     ##
     class Finetunes < Base
       URI_PREFIX = "/fine-tunes".freeze
+      private_constant :URI_PREFIX
 
+      ##
+      # Lists the set of fine-tuning jobs for this API key and (optionally) organization.
+      ##
       def list
         http_get(path: URI_PREFIX)
       end
 
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:training_file) unless parameters[:training_file]
+      ##
+      # Creates a new fine-tuning job with the specified parameters.
+      #
+      # @param [String] training_file the id of the training file to use for fine tuning
+      # @param [Hash] parameters the parameters passed with the fine tuning job
+      ##
+      def create(training_file:, parameters: {})
+        raise MissingRequiredParameterError.new(:training_file) unless training_file
 
-        json_post(path: URI_PREFIX, parameters: parameters)
+        json_post(path: URI_PREFIX, parameters: parameters.merge(training_file: training_file))
       end
 
+      ##
+      # Retrieves the details of a fine-tuning job with the specified id.
+      #
+      # @param [String] fine_tune_id the id of fine tuning job
+      ##
       def retrieve(fine_tune_id:)
         http_get(path: "#{URI_PREFIX}/#{fine_tune_id}")
       end
 
+      ##
+      # Cancels the details of a fine-tuning job with the specified id.
+      #
+      # @param [String] fine_tune_id the id of fine tuning job
+      ##
       def cancel(fine_tune_id:)
         multipart_post(path: "#{URI_PREFIX}/#{fine_tune_id}/cancel")
       end
 
-      def events(fine_tune_id:)
+      ##
+      # Lists the events associated with a fine-tuning job with the specified id.
+      #
+      # @param [String] fine_tune_id the id of fine tuning job
+      ##
+      def list_events(fine_tune_id:)
         http_get(path: "#{URI_PREFIX}/#{fine_tune_id}/events")
       end
     end

data/lib/asimov/api_v1/images.rb

@@ -7,21 +7,45 @@ module Asimov
     ##
     class Images < Base
       URI_PREFIX = "/images".freeze
-
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:prompt) unless parameters[:prompt]
-
-        json_post(path: "#{URI_PREFIX}/generations", parameters: parameters)
+      private_constant :URI_PREFIX
+
+      ##
+      # Creates an image using the specified prompt.
+      #
+      # @param [String] prompt the prompt used to create the image
+      # @param [Hash] parameters additional parameters passed to the API
+      ##
+      def create(prompt:, parameters: {})
+        raise MissingRequiredParameterError.new(:prompt) unless prompt
+
+        json_post(path: "#{URI_PREFIX}/generations",
+                  parameters: parameters.merge({ prompt: prompt }))
       end
 
-      def create_edit(parameters:)
-        raise MissingRequiredParameterError.new(:prompt) unless parameters[:prompt]
-
-        multipart_post(path: "#{URI_PREFIX}/edits", parameters: open_files(parameters))
+      ##
+      # Creates edits of the specified image based on the prompt.
+      #
+      # @param [String] image file name  or a File-like object of the base image
+      # @param [String] prompt the prompt used to guide the edit
+      # @param [Hash] parameters additional parameters passed to the API
+      ##
+      def create_edit(image:, prompt:, parameters: {})
+        raise MissingRequiredParameterError.new(:prompt) unless prompt
+
+        multipart_post(path: "#{URI_PREFIX}/edits",
+                       parameters: open_files(parameters.merge({ image: image, prompt: prompt })))
       end
 
-      def create_variation(parameters:)
-        multipart_post(path: "#{URI_PREFIX}/variations", parameters: open_files(parameters))
+      ##
+      # Creates variations of the specified image.
+      #
+      # @param [String] image file name or a File-like object of the base image
+      # @param [Hash] parameters additional parameters passed to the API
+      # @option parameters [String] :mask mask file name or a File-like object
+      ##
+      def create_variation(image:, parameters: {})
+        multipart_post(path: "#{URI_PREFIX}/variations",
+                       parameters: open_files(parameters.merge({ image: image })))
       end
 
       private

data/lib/asimov/api_v1/models.rb

@@ -5,15 +5,32 @@ module Asimov
     ##
     class Models < Base
       URI_PREFIX = "/models".freeze
+      private_constant :URI_PREFIX
 
+      ##
+      # Lists the models accessible to this combination of OpenAI API
+      # key and organization id.
+      ##
       def list
         http_get(path: URI_PREFIX)
       end
 
+      ##
+      # Retrieve information about the model with the specified
+      # model_id.
+      #
+      # @param [String] model_id the id of the model to be retrieved
+      ##
       def retrieve(model_id:)
         http_get(path: "#{URI_PREFIX}/#{model_id}")
       end
 
+      ##
+      # Deletes the model with the specified model_id.  Only
+      # works on models created via fine tuning.
+      #
+      # @param [String] model_id the id of the model to be deleted
+      ##
       def delete(model_id:)
         http_delete(path: "#{URI_PREFIX}/#{model_id}")
       end

data/lib/asimov/api_v1/moderations.rb

@@ -4,10 +4,16 @@ module Asimov
     # Class interface for API methods in the "/moderations" URI subspace.
     ##
     class Moderations < Base
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:input) unless parameters[:input]
+      ##
+      # Calls the /moderations POST endpoint with the specified parameters.
+      #
+      # @param [String] input the text being evaluated by the API
+      # @param [Hash] parameters the set of parameters being passed to the API
+      ##
+      def create(input:, parameters: {})
+        raise MissingRequiredParameterError.new(:input) unless input
 
-        json_post(path: "/moderations", parameters: parameters)
+        json_post(path: "/moderations", parameters: parameters.merge({ input: input }))
       end
     end
   end

data/lib/asimov/configuration.rb

@@ -11,16 +11,26 @@ module Asimov
 
     attr_reader :request_options
 
+    ##
+    # Initializes the Configuration object and resets it to default values.
+    ##
     def initialize
       reset
     end
 
+    ##
+    # Reset the configuration to default values.  Mostly used for testing.
+    ##
     def reset
       @api_key = nil
       @organization_id = nil
       @request_options = {}
     end
 
+    ##
+    # Sets the request_options on the Configuration.  Typically not invoked
+    # directly, but rather through use of `Asimov.configure`.
+    ##
     def request_options=(val)
       @request_options = Utils::RequestOptionsValidator.validate(val)
     end

data/lib/asimov/error.rb

@@ -9,6 +9,10 @@ module Asimov
   ##
   class ConfigurationError < Error; end
 
+  ##
+  # Error that occurs when there is no configured
+  # API key for a newly created Asimov::Client.
+  ##
   class MissingApiKeyError < ConfigurationError; end
 
   ##
@@ -56,6 +60,18 @@ module Asimov
   ##
   class AuthorizationError < RequestError; end
 
+  ##
+  # Error that occurs because the provided API key is not
+  # valid.
+  ##
+  class InvalidApiKeyError < AuthorizationError; end
+
+  ##
+  # Error that occurs because the provided API key is not
+  # valid.
+  ##
+  class InvalidOrganizationError < AuthorizationError; end
+
   ##
   # Errors that occur because of issues with the
   # parameters of a request.  Typically these correspond
@@ -87,26 +103,54 @@ module Asimov
       @system_message = system_message
     end
 
+    ##
+    # Returns the error message based on the file name and the wrapped error.
+    ##
     def message
       "The file #{@file_name} could not be opened for upload because of the " \
         "following error - #{@system_message}."
     end
   end
 
+  ##
+  # Error that occurs when a JSONL file is expected
+  # and it cannot be parsed.
+  ##
   class JsonlFileCannotBeParsedError < FileDataError; end
 
+  ##
+  # Error that occurs when an invalid training example
+  # is found in a training file.
+  ##
   class InvalidTrainingExampleError < FileDataError; end
 
+  ##
+  # Error that occurs when an invalid text entry
+  # is found in a text entry file.
+  ##
   class InvalidTextEntryError < FileDataError; end
 
+  ##
+  # Error that occurs when an invalid classification
+  # is found in a classifications file.
+  ##
   class InvalidClassificationError < FileDataError; end
 
+  ##
+  # Error that occurs when an invalid value is provided
+  # for an expected parameter in a request.
+  ##
   class InvalidParameterValueError < RequestError; end
 
+  ##
+  # Error that occurs when an unexpected parameter is
+  # provided in a request.
+  ##
   class UnsupportedParameterError < RequestError; end
 
   ##
-  #
+  # Error raised when a required parameter is not included
+  # in the request.
   ##
   class MissingRequiredParameterError < RequestError
     def initialize(parameter_name)
@@ -114,6 +158,9 @@ module Asimov
       @parameter_name = parameter_name
     end
 
+    ##
+    # Returns the error message based on the missing parameter name.
+    ##
     def message
       "The parameter #{@parameter_name} is required."
     end
@@ -126,4 +173,39 @@ module Asimov
   # an object in the OpenAI system.
   ##
   class NotFoundError < RequestError; end
+
+  ##
+  # Errors that occur because the OpenAI API returned
+  # an HTTP code 429.  This typically occurs because
+  # you have hit a rate limit or quota limit, or
+  # because the engine is overloaded.
+  ##
+  class TooManyRequestsError < RequestError; end
+
+  ##
+  # Error that occurs when the quota for an API key
+  # is exceeded.
+  ##
+  class QuotaExceededError < TooManyRequestsError; end
+
+  ##
+  # Error that occurs when the rate limit for requests
+  # is exceeded.
+  ##
+  class RateLimitError < TooManyRequestsError; end
+
+  ##
+  # Error that occurs when the API itself is
+  # overloaded and temporarily cannot accept additional
+  # requests.
+  ##
+  class ApiOverloadedError < TooManyRequestsError; end
+
+  ##
+  # Raised when a non-false stream parameter is passed
+  # to certain API methods.  Processing of server-side
+  # events using the stream parameter is currently not
+  # supported.
+  ##
+  class StreamingResponseNotSupportedError < RequestError; end
 end

data/lib/asimov/utils/classifications_file_validator.rb

@@ -1,6 +1,9 @@
 require "json"
 
 module Asimov
+  ##
+  # Set of utilities, primarily intended for internal library use.
+  ##
   module Utils
     ##
     # Validates that a file is in the "classifications" format
@@ -8,8 +11,13 @@ module Asimov
     # "text" and "label" keys for each line that have string
     # values and an optional "metadata" key that can have
     # any value.  No other keys are permitted.
+    #
+    # The only method that clients should call on instances
+    # of this class is `validate`
     ##
     class ClassificationsFileValidator < JsonlValidator
+      private
+
       def validate_line(line, idx)
         parsed = JSON.parse(line)
         validate_classification(parsed, idx)

data/lib/asimov/utils/file_manager.rb

@@ -8,11 +8,23 @@ module Asimov
     # Not intended for client use.
     ##
     class FileManager
-      def self.open(filename)
-        File.open(filename)
+      ##
+      # Returns the file corresponding to the file_or_path.  If the argument is a
+      # file, then just returns the argument.  Otherwise calls File.open with the
+      # argument.  Raises an error if the file cannot be opened.
+      #
+      # @param [File/String] file_or_path the path to the file to be opened
+      ##
+      def self.open(file_or_path)
+        file?(file_or_path) ? file_or_path : File.open(file_or_path)
       rescue SystemCallError => e
-        raise Asimov::FileCannotBeOpenedError.new(filename, e.message)
+        raise Asimov::FileCannotBeOpenedError.new(file_or_path, e.message)
       end
+
+      def self.file?(object)
+        object.respond_to?(:path) && object.respond_to?(:read)
+      end
+      private_class_method :file?
     end
   end
 end

data/lib/asimov/utils/jsonl_validator.rb

@@ -7,13 +7,23 @@ module Asimov
     # more specific file validators.
     ##
     class JsonlValidator
-      def validate(file)
-        file.each_line.with_index { |line, idx| validate_line(line, idx) }
+      ##
+      # Validate that the IO object (typically a File) is properly
+      # formatted.  Entry method for this class and its subclasses.
+      # Required format will depend on the class.
+      #
+      # @param [IO] io IO object, typically a file, whose contents
+      # are to be format checked.
+      ##
+      def validate(io)
+        io.each_line.with_index { |line, idx| validate_line(line, idx) }
         true
       rescue JSON::ParserError
         raise JsonlFileCannotBeParsedError, "Expected file to have the JSONL format."
       end
 
+      private
+
       def validate_line(line, idx)
         JSON.parse(line)
       rescue JSON::ParserError

data/lib/asimov/utils/request_options_validator.rb

@@ -14,6 +14,16 @@ module Asimov
       ALLOWED_OPTIONS = %i[timeout open_timeout read_timeout write_timeout local_host local_port
                            verify verify_peer ssl_ca_file ssl_ca_path ssl_version ciphers
                            http_proxyaddr http_proxyport http_proxyuser http_proxypass].freeze
+
+      ##
+      # Validates that the options are allowed request
+      # options.  Currently checks the keys - both that they are symbols and that
+      # they are allowed options.  Does not validate values.
+      #
+      # Only entry point for this class.
+      #
+      #  @param [Hash] options the set of request options to validate
+      ##
       def self.validate(options)
         unless options.is_a?(Hash)
           raise Asimov::ConfigurationError,
@@ -32,6 +42,7 @@ module Asimov
         end
         unsupported_options
       end
+      private_class_method :generate_unsupported_options
 
       def self.check_unsupported_options(unsupported_options)
         return if unsupported_options.empty?
@@ -40,6 +51,7 @@ module Asimov
         raise Asimov::ConfigurationError,
               "The options #{quoted_keys.join(',')} are not supported."
       end
+      private_class_method :check_unsupported_options
 
       def self.supported_option?(key)
         ALLOWED_OPTIONS.include?(key)
@@ -51,6 +63,7 @@ module Asimov
         raise Asimov::ConfigurationError,
               "Request options keys must be symbols.  The key '#{key}' is not a symbol."
       end
+      private_class_method :check_symbol
     end
   end
 end

data/lib/asimov/utils/text_entry_file_validator.rb

@@ -10,6 +10,8 @@ module Asimov
     # any value.  No other keys are permitted.
     ##
     class TextEntryFileValidator < JsonlValidator
+      private
+
       def validate_line(line, idx)
         parsed = JSON.parse(line)
         validate_text_entry(parsed, idx)

data/lib/asimov/utils/training_file_validator.rb

@@ -9,6 +9,8 @@ module Asimov
     # values.  No other keys are permitted.
     ##
     class TrainingFileValidator < JsonlValidator
+      private
+
       def validate_line(line, idx)
         parsed = JSON.parse(line)
         validate_training_example(parsed, idx)

data/lib/asimov/version.rb

@@ -1,3 +1,4 @@
 module Asimov
-  VERSION = "0.1.0".freeze
+  # Current gem version
+  VERSION = "1.0.0".freeze
 end

data/lib/asimov.rb

@@ -4,7 +4,7 @@ require_relative "asimov/error"
 require_relative "asimov/client"
 
 ##
-# Client library for using the OpenAI API.
+# Top level module for the Asimov client library for using the OpenAI API.
 ##
 module Asimov
   ##

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: asimov
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Peter M. Goldstein
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-14 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -30,105 +30,8 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.22.0
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.12'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.12'
-- !ruby/object:Gem::Dependency
-  name: rubocop
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.43.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 1.43.0
-- !ruby/object:Gem::Dependency
-  name: rubocop-rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubocop-rspec
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: vcr
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.1.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 6.1.0
-- !ruby/object:Gem::Dependency
-  name: webmock
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.18.1
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.18.1
-description: A Ruby client for the OpenAI API
+description: A Ruby client for the OpenAI API support for multiple API configurations
+  in a single app, robust and simple error handling, and network-level configuration.
 email:
 - peter.m.goldstein@gmail.com
 executables: []
@@ -185,8 +88,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.3
+rubygems_version: 3.4.5
 signing_key:
 specification_version: 4
-summary: A Ruby client for the OpenAI API
+summary: A Ruby client for the OpenAI API support for multiple API configurations
+  in a single app, robust and simple error handling, and network-level configuration.
 test_files: []