asimov 0.1.0 → 1.1.0

data/lib/asimov/api_v1/finetunes.rb

@@ -4,28 +4,54 @@ module Asimov
     # Class interface for API methods in the "/fine-tunes" URI subspace.
     ##
     class Finetunes < Base
-      URI_PREFIX = "/fine-tunes".freeze
+      RESOURCE = "fine-tunes".freeze
+      private_constant :RESOURCE
 
+      ##
+      # Lists the set of fine-tuning jobs for this API key and (optionally) organization.
+      ##
       def list
-        http_get(path: URI_PREFIX)
+        rest_index(resource: RESOURCE)
       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)
+        rest_create_w_json_params(resource: RESOURCE,
+                                  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}")
+        rest_get(resource: RESOURCE, id: 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")
+        rest_create_w_multipart_params(resource: [RESOURCE, fine_tune_id, "cancel"])
       end
 
-      def events(fine_tune_id:)
-        http_get(path: "#{URI_PREFIX}/#{fine_tune_id}/events")
+      ##
+      # 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:)
+        rest_index(resource: [RESOURCE, fine_tune_id, "events"])
       end
     end
   end

data/lib/asimov/api_v1/images.rb

@@ -6,22 +6,49 @@ module Asimov
     # Class interface for API methods in the "/images" URI subspace.
     ##
     class Images < Base
-      URI_PREFIX = "/images".freeze
+      RESOURCE = "images".freeze
+      private_constant :RESOURCE
 
-      def create(parameters:)
-        raise MissingRequiredParameterError.new(:prompt) unless parameters[:prompt]
+      ##
+      # 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)
+        rest_create_w_json_params(resource: [RESOURCE, "generations"],
+                                  parameters: parameters.merge({ prompt: prompt }))
       end
 
-      def create_edit(parameters:)
-        raise MissingRequiredParameterError.new(:prompt) unless parameters[:prompt]
+      ##
+      # 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))
+        rest_create_w_multipart_params(resource: [RESOURCE, "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: {})
+        rest_create_w_multipart_params(resource: [RESOURCE, "variations"],
+                                       parameters: open_files(parameters.merge({ image: image })))
       end
 
       private
@@ -30,7 +57,7 @@ module Asimov
         raise MissingRequiredParameterError.new(:image) unless parameters[:image]
 
         parameters = parameters.merge(image: Utils::FileManager.open(parameters[:image]))
-        parameters.merge!(mask: Utils::FileManager.open(parameters[:mask])) if parameters[:mask]
+        parameters[:mask] = Utils::FileManager.open(parameters[:mask]) if parameters[:mask]
         parameters
       end
     end

data/lib/asimov/api_v1/models.rb

@@ -4,18 +4,35 @@ module Asimov
     # Class interface for API methods in the "/models" URI subspace.
     ##
     class Models < Base
-      URI_PREFIX = "/models".freeze
+      RESOURCE = "models".freeze
+      private_constant :RESOURCE
 
+      ##
+      # Lists the models accessible to this combination of OpenAI API
+      # key and organization id.
+      ##
       def list
-        http_get(path: URI_PREFIX)
+        rest_index(resource: RESOURCE)
       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}")
+        rest_get(resource: RESOURCE, id: 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}")
+        rest_delete(resource: RESOURCE, id: model_id)
       end
     end
   end

data/lib/asimov/api_v1/moderations.rb

@@ -4,10 +4,17 @@ 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)
+        rest_create_w_json_params(resource: "moderations",
+                                  parameters: parameters.merge({ input: input }))
       end
     end
   end

data/lib/asimov/client.rb

@@ -3,6 +3,8 @@ require "httparty"
 require_relative "headers_factory"
 require_relative "utils/request_options_validator"
 require_relative "api_v1/base"
+require_relative "api_v1/audio"
+require_relative "api_v1/chat"
 require_relative "api_v1/completions"
 require_relative "api_v1/edits"
 require_relative "api_v1/embeddings"
@@ -20,7 +22,7 @@ module Asimov
   class Client
     extend Forwardable
 
-    attr_reader :api_key, :organization_id, :api_version, :request_options
+    attr_reader :api_key, :organization_id, :api_version, :request_options, :openai_api_base
 
     ##
     # Creates a new Asimov::Client. Includes several optional named parameters:
@@ -29,17 +31,36 @@ module Asimov
     #           defaults to the application-wide configuration
     # organization_id - The OpenAI organization identifier that this Asimov::Client instance
     #                   will use. If unspecified, defaults to the application-wide configuration.
+    # request_options - HTTParty request options that will be passed to the underlying network
+    #                   client.  Merges (and overrides) global configuration value.
+    # openai_api_base - Custom base URI for the API calls made by this client. Defaults to global
+    #            configuration value.
     ##
     def initialize(api_key: nil, organization_id: HeadersFactory::NULL_ORGANIZATION_ID,
-                   request_options: {})
+                   request_options: {}, openai_api_base: nil)
       @headers_factory = HeadersFactory.new(api_key,
                                             organization_id)
       @request_options = Asimov.configuration.request_options
                                .merge(Utils::RequestOptionsValidator.validate(request_options))
                                .freeze
+      initialize_openai_api_base(openai_api_base)
     end
     def_delegators :@headers_factory, :api_key, :organization_id, :headers
 
+    ##
+    # Use the audio method to access API calls in the /audio URI space.
+    ##
+    def audio
+      @audio ||= Asimov::ApiV1::Audio.new(client: self)
+    end
+
+    ##
+    # Use the chat method to access API calls in the /chat URI space.
+    ##
+    def chat
+      @chat ||= Asimov::ApiV1::Chat.new(client: self)
+    end
+
     ##
     # Use the completions method to access API calls in the /completions URI space.
     ##
@@ -95,5 +116,17 @@ module Asimov
     def moderations
       @moderations ||= Asimov::ApiV1::Moderations.new(client: self)
     end
+
+    private
+
+    def initialize_openai_api_base(openai_api_base)
+      @openai_api_base = openai_api_base || Asimov.configuration.openai_api_base
+      if @openai_api_base
+        @openai_api_base = HTTParty.normalize_base_uri(@openai_api_base)
+      else
+        raise Asimov::MissingBaseUriError,
+              "No API Base URI was provided for this client."
+      end
+    end
   end
 end

data/lib/asimov/configuration.rb

@@ -9,18 +9,39 @@ module Asimov
   class Configuration
     attr_accessor :api_key, :organization_id
 
-    attr_reader :request_options
+    attr_reader :request_options, :openai_api_base
 
+    DEFAULT_OPENAI_BASE_URI = "https://api.openai.com/v1".freeze
+
+    ##
+    # 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 = {}
+      @openai_api_base = DEFAULT_OPENAI_BASE_URI
+    end
+
+    ##
+    # Sets the openai_api_base on the Configuration.  Typically not invoked
+    # directly, but rather through use of `Asimov.configure`.
+    ##
+    def openai_api_base=(val)
+      @openai_api_base = val ? HTTParty.normalize_base_uri(val) : nil
     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,8 +9,18 @@ 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
 
+  ##
+  # Error that occurs when there is no configured
+  # base URI for a newly created Asimov::Client.
+  ##
+  class MissingBaseUriError < ConfigurationError; end
+
   ##
   # Errors that occur when making an API request.  They
   # can occur either through local validation or
@@ -56,6 +66,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 +109,60 @@ 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 the provided chat messages
+  # parameter is not valid.
+  ##
+  class InvalidChatMessagesError < RequestError; 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 +170,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 +185,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/chat_messages_validator.rb

@@ -0,0 +1,63 @@
+module Asimov
+  module Utils
+    ##
+    # Validator for OpenAI's chat message format
+    ##
+    class ChatMessagesValidator
+      def self.validate_and_normalize(messages)
+        new.validate(messages)
+      end
+
+      def validate(messages)
+        raise InvalidChatMessagesError, "Chat messages cannot be nil." if messages.nil?
+
+        unless messages.is_a?(Array)
+          raise InvalidChatMessagesError,
+                "Chat messages must be an array."
+        end
+
+        messages.map do |message|
+          validate_message(normalize_parsed(message))
+        end
+      rescue JSON::ParserError
+        raise InvalidChatMessagesError, "Chat messages must be valid JSON."
+      end
+
+      def validate_message(message)
+        raise InvalidChatMessagesError, "Chat messages must be hashes." unless message.is_a?(Hash)
+
+        validate_role(message["role"])
+
+        content = message["content"]
+        raise InvalidChatMessagesError, "Chat messages must have content." if content.nil?
+
+        validate_keys(message)
+        message
+      end
+
+      def validate_keys(json)
+        additional_keys = json.keys - %w[role content]
+        return if additional_keys.empty?
+
+        raise InvalidChatMessagesError,
+              "Chat messages must not have additional keys - #{additional_keys.join(', ')}."
+      end
+
+      ALLOWED_ROLES = %w[assistant system user].freeze
+      def validate_role(role)
+        raise InvalidChatMessagesError, "Chat messages must have a role." if role.nil?
+
+        return true if ALLOWED_ROLES.include?(role)
+
+        raise InvalidChatMessagesError,
+              "The value '#{role}' is not a valid role for a chat message."
+      end
+
+      def normalize_parsed(message)
+        return message if message.is_a?(String)
+
+        JSON.parse(message.respond_to?(:to_json) ? message.to_json : message)
+      end
+    end
+  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.1.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
   ##