asimov 0.1.0

data/lib/asimov/configuration.rb

@@ -0,0 +1,28 @@
+require_relative "utils/request_options_validator"
+
+module Asimov
+  ##
+  # Application-wide configuration for the Asimov library. Should be
+  # configured once using the Asimov.configure method on application
+  # startup.
+  ##
+  class Configuration
+    attr_accessor :api_key, :organization_id
+
+    attr_reader :request_options
+
+    def initialize
+      reset
+    end
+
+    def reset
+      @api_key = nil
+      @organization_id = nil
+      @request_options = {}
+    end
+
+    def request_options=(val)
+      @request_options = Utils::RequestOptionsValidator.validate(val)
+    end
+  end
+end

data/lib/asimov/error.rb

@@ -0,0 +1,129 @@
+module Asimov
+  ##
+  # Parent error for all Asimov gem errors.
+  ##
+  class Error < StandardError; end
+
+  ##
+  # Errors that occur when initializing an Asimov::Client.
+  ##
+  class ConfigurationError < Error; end
+
+  class MissingApiKeyError < ConfigurationError; end
+
+  ##
+  # Errors that occur when making an API request.  They
+  # can occur either through local validation or
+  # as a result of an error returned by the OpenAI API.
+  ##
+  class RequestError < Error; end
+
+  ##
+  # Errors that occur as a result of an error raised
+  # by the underlying network client.  Examples
+  # include Net::OpenTimeout or Net::ReadTimeout
+  ##
+  class NetworkError < RequestError; end
+
+  ##
+  # Errors that occur as a result of a timeout raised
+  # by the underlying network client.  Examples
+  # include Net::OpenTimeout or Net::ReadTimeout
+  ##
+  class TimeoutError < NetworkError; end
+
+  ##
+  # Error that occurs as a result of a Net::OpenTimeout raised
+  # by the underlying network client.
+  ##
+  class OpenTimeout < TimeoutError; end
+
+  ##
+  # Error that occurs as a result of a Net::ReadTimeout raised
+  # by the underlying network client.
+  ##
+  class ReadTimeout < TimeoutError; end
+
+  ##
+  # Error that occurs as a result of a Net::WriteTimeout raised
+  # by the underlying network client.
+  ##
+  class WriteTimeout < TimeoutError; end
+
+  ##
+  # Errors that occur as a result of an HTTP 401
+  # returned by the OpenAI API.
+  ##
+  class AuthorizationError < RequestError; end
+
+  ##
+  # Errors that occur because of issues with the
+  # parameters of a request.  Typically these correspond
+  # to a 400 HTTP return code.  Example causes include missing
+  # parameters, unexpected parameters, invalid parameter
+  # values.
+  #
+  # Errors of this type my be geenrated through local
+  # validation or as a result of an error returned by
+  # the OpenAI API.
+  ##
+  class ParameterError < RequestError; end
+
+  ##
+  # Errors that occur because of a problem with file data
+  # being provided as a part of a multipart form upload.
+  # This can include the file being unreadable, or
+  # formatting problems with the file.
+  ##
+  class FileDataError < RequestError; end
+
+  ##
+  # Error that occurs when a local file cannot be opened.
+  ##
+  class FileCannotBeOpenedError < FileDataError
+    def initialize(file_name, system_message)
+      super()
+      @file_name = file_name
+      @system_message = system_message
+    end
+
+    def message
+      "The file #{@file_name} could not be opened for upload because of the " \
+        "following error - #{@system_message}."
+    end
+  end
+
+  class JsonlFileCannotBeParsedError < FileDataError; end
+
+  class InvalidTrainingExampleError < FileDataError; end
+
+  class InvalidTextEntryError < FileDataError; end
+
+  class InvalidClassificationError < FileDataError; end
+
+  class InvalidParameterValueError < RequestError; end
+
+  class UnsupportedParameterError < RequestError; end
+
+  ##
+  #
+  ##
+  class MissingRequiredParameterError < RequestError
+    def initialize(parameter_name)
+      super()
+      @parameter_name = parameter_name
+    end
+
+    def message
+      "The parameter #{@parameter_name} is required."
+    end
+  end
+
+  ##
+  # Errors that occur because the OpenAI API returned
+  # an HTTP code 400.  This typically occurs because
+  # one or more provided identifiers do not match
+  # an object in the OpenAI system.
+  ##
+  class NotFoundError < RequestError; end
+end

data/lib/asimov/headers_factory.rb

@@ -0,0 +1,67 @@
+module Asimov
+  ##
+  # Configures the set of HTTP headers being sent with requests to
+  # the OpenAI API. These header include authentication and content-type
+  # information.
+  #
+  # Not intended for client use.
+  ##
+  class HeadersFactory
+    ##
+    # Null object used to allow nil override of a default organization_id.
+    ##
+    NULL_ORGANIZATION_ID = Object.new.freeze
+
+    attr_reader :api_key, :organization_id
+
+    def initialize(api_key, organization_id)
+      @api_key = api_key || Asimov.configuration.api_key
+      initialize_organization_id(organization_id)
+
+      return if @api_key
+
+      raise Asimov::MissingApiKeyError,
+            "No OpenAI API key was provided for this client."
+    end
+
+    ##
+    # Returns the headers to use for a request.
+    #
+    # @param content_type The Content-Type header value for the request.
+    ##
+    def headers(content_type = "application/json")
+      {
+        "Content-Type" => content_type
+      }.merge(openai_headers)
+    end
+
+    private
+
+    def initialize_organization_id(organization_id)
+      @organization_id = if organization_id == NULL_ORGANIZATION_ID
+                           Asimov.configuration.organization_id
+                         else
+                           organization_id
+                         end
+    end
+
+    def openai_headers
+      @openai_headers ||=
+        if organization_id.nil?
+          auth_headers
+        else
+          auth_headers.merge(
+            { "OpenAI-Organization" => organization_id }
+          )
+        end
+    end
+
+    def auth_headers
+      @auth_headers ||= { "Authorization" => bearer_header(api_key) }
+    end
+
+    def bearer_header(api_key)
+      "Bearer #{api_key}"
+    end
+  end
+end

data/lib/asimov/utils/classifications_file_validator.rb

@@ -0,0 +1,42 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # Validates that a file is in the "classifications" format
+    # used by OpenAI.  The file is a JSONL file, with
+    # "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.
+    ##
+    class ClassificationsFileValidator < JsonlValidator
+      def validate_line(line, idx)
+        parsed = JSON.parse(line)
+        validate_classification(parsed, idx)
+      end
+
+      def validate_classification(parsed, idx)
+        return if classification?(parsed)
+
+        raise InvalidClassificationError,
+              "Expected file to have JSONL format with text/label and (optional) metadata keys. " \
+              "Invalid format on line #{idx + 1}."
+      end
+
+      def classification?(parsed)
+        return false unless parsed.is_a?(Hash)
+        return false unless includes_required_key_value?("text", parsed)
+        return false unless includes_required_key_value?("label", parsed)
+
+        keys = parsed.keys
+        return false unless keys.size <= 3
+
+        keys.size == 2 ? true : keys.include?("metadata")
+      end
+
+      def includes_required_key_value?(key, parsed)
+        parsed[key]&.is_a?(String)
+      end
+    end
+  end
+end

data/lib/asimov/utils/file_manager.rb

@@ -0,0 +1,18 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # File-related utility methods.
+    #
+    # Not intended for client use.
+    ##
+    class FileManager
+      def self.open(filename)
+        File.open(filename)
+      rescue SystemCallError => e
+        raise Asimov::FileCannotBeOpenedError.new(filename, e.message)
+      end
+    end
+  end
+end

data/lib/asimov/utils/jsonl_validator.rb

@@ -0,0 +1,25 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # Validates that a file is a JSONL file.  Subclassed by
+    # more specific file validators.
+    ##
+    class JsonlValidator
+      def validate(file)
+        file.each_line.with_index { |line, idx| validate_line(line, idx) }
+        true
+      rescue JSON::ParserError
+        raise JsonlFileCannotBeParsedError, "Expected file to have the JSONL format."
+      end
+
+      def validate_line(line, idx)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        raise JsonlFileCannotBeParsedError,
+              "Expected file to have the JSONL format.  Error found on line #{idx + 1}."
+      end
+    end
+  end
+end

data/lib/asimov/utils/request_options_validator.rb

@@ -0,0 +1,56 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # Validates a set of request options that are passed to the application
+    # configuration or on Asimov::Client initialization. Ensures that the
+    # value is a hash, that all keys are symbols, and that all keys correspond
+    # to legitimate options (typically relating to network behavior).  Currently
+    # does not validate the option values.
+    ##
+    class RequestOptionsValidator
+      # This is taken from HTTParty
+      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
+      def self.validate(options)
+        unless options.is_a?(Hash)
+          raise Asimov::ConfigurationError,
+                "Request options must be a hash"
+        end
+
+        check_unsupported_options(generate_unsupported_options(options))
+        options
+      end
+
+      def self.generate_unsupported_options(options)
+        unsupported_options = []
+        options.each_key do |k|
+          check_symbol(k)
+          unsupported_options << k unless supported_option?(k)
+        end
+        unsupported_options
+      end
+
+      def self.check_unsupported_options(unsupported_options)
+        return if unsupported_options.empty?
+
+        quoted_keys = unsupported_options.map { |k| "'#{k}'" }
+        raise Asimov::ConfigurationError,
+              "The options #{quoted_keys.join(',')} are not supported."
+      end
+
+      def self.supported_option?(key)
+        ALLOWED_OPTIONS.include?(key)
+      end
+
+      def self.check_symbol(key)
+        return if key.is_a?(Symbol)
+
+        raise Asimov::ConfigurationError,
+              "Request options keys must be symbols.  The key '#{key}' is not a symbol."
+      end
+    end
+  end
+end

data/lib/asimov/utils/text_entry_file_validator.rb

@@ -0,0 +1,38 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # Validates that a file is in the "answers" or "search" format
+    # used by OpenAI.  The file is a JSONL file, with
+    # a "text" key for each line that has a string
+    # value and an optional "metadata" key that can have
+    # any value.  No other keys are permitted.
+    ##
+    class TextEntryFileValidator < JsonlValidator
+      def validate_line(line, idx)
+        parsed = JSON.parse(line)
+        validate_text_entry(parsed, idx)
+      end
+
+      def validate_text_entry(parsed, idx)
+        return if text_entry?(parsed)
+
+        raise InvalidTextEntryError,
+              "Expected file to have the JSONL format with 'text' key and (optional) " \
+              "'metadata' key. Invalid format on line #{idx + 1}."
+      end
+
+      def text_entry?(parsed)
+        return false unless parsed.is_a?(Hash)
+
+        keys = parsed.keys
+        return false unless keys.size >= 1 && keys.size <= 2
+        return false unless keys.include?("text")
+        return false unless parsed["text"].is_a?(String)
+
+        keys.size == 1 ? true : keys.include?("metadata")
+      end
+    end
+  end
+end

data/lib/asimov/utils/training_file_validator.rb

@@ -0,0 +1,39 @@
+require "json"
+
+module Asimov
+  module Utils
+    ##
+    # Validates that a file is in the "fine-tune" format
+    # used by OpenAI.  The file is a JSONL file, with
+    # "prompt" and "completion" keys for each line that have string
+    # values.  No other keys are permitted.
+    ##
+    class TrainingFileValidator < JsonlValidator
+      def validate_line(line, idx)
+        parsed = JSON.parse(line)
+        validate_training_example(parsed, idx)
+      end
+
+      def validate_training_example(parsed, idx)
+        return if training_example?(parsed)
+
+        raise InvalidTrainingExampleError,
+              "Expected file to have JSONL format with prompt/completion keys. " \
+              "Invalid format on line #{idx + 1}."
+      end
+
+      def training_example?(parsed)
+        return false unless parsed.is_a?(Hash)
+
+        keys = parsed.keys
+        return false unless keys.size == 2
+        return false unless keys.include?("prompt")
+        return false unless keys.include?("completion")
+        return false unless parsed["prompt"].is_a?(String)
+        return false unless parsed["completion"].is_a?(String)
+
+        true
+      end
+    end
+  end
+end

data/lib/asimov/version.rb

@@ -0,0 +1,3 @@
+module Asimov
+  VERSION = "0.1.0".freeze
+end

data/lib/asimov.rb

@@ -0,0 +1,35 @@
+require_relative "asimov/version"
+require_relative "asimov/configuration"
+require_relative "asimov/error"
+require_relative "asimov/client"
+
+##
+# Client library for using the OpenAI API.
+##
+module Asimov
+  ##
+  # Method uses to initialize the application-wide configuration.  Should be called with
+  # a block like so:
+  #
+  # Asimov.configure do |config|
+  #   config.api_key = 'abcd'
+  #   config.organization = 'def'
+  # end
+  #
+  # Attributes that can be set on the configuration include:
+  #
+  # api_key - The OpenAI API key that Asimov::Client instances should use by default.
+  # organization_id - The OpenAI organization identifier that Asimov::Client instances should
+  #                   use by default.
+  ##
+  def self.configure
+    yield(configuration)
+  end
+
+  ##
+  # Getter for the application-wide Asimove::Configuration singleton.
+  ##
+  def self.configuration
+    @configuration ||= Asimov::Configuration.new
+  end
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: asimov
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Peter M. Goldstein
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.18.1
+    - - "<"
+      - !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
+email:
+- peter.m.goldstein@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- lib/asimov.rb
+- lib/asimov/api_v1/api_error_translator.rb
+- lib/asimov/api_v1/base.rb
+- lib/asimov/api_v1/completions.rb
+- lib/asimov/api_v1/edits.rb
+- lib/asimov/api_v1/embeddings.rb
+- lib/asimov/api_v1/files.rb
+- lib/asimov/api_v1/finetunes.rb
+- lib/asimov/api_v1/images.rb
+- lib/asimov/api_v1/models.rb
+- lib/asimov/api_v1/moderations.rb
+- lib/asimov/api_v1/network_error_translator.rb
+- lib/asimov/client.rb
+- lib/asimov/configuration.rb
+- lib/asimov/error.rb
+- lib/asimov/headers_factory.rb
+- lib/asimov/utils/classifications_file_validator.rb
+- lib/asimov/utils/file_manager.rb
+- lib/asimov/utils/jsonl_validator.rb
+- lib/asimov/utils/request_options_validator.rb
+- lib/asimov/utils/text_entry_file_validator.rb
+- lib/asimov/utils/training_file_validator.rb
+- lib/asimov/version.rb
+homepage: https://github.com/petergoldstein/asimov
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/petergoldstein/asimov
+  source_code_uri: https://github.com/petergoldstein/asimov
+  changelog_uri: https://github.com/petergoldstein/asimov/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.3
+signing_key:
+specification_version: 4
+summary: A Ruby client for the OpenAI API
+test_files: []