asimov 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c50684e3e690496248b87a912334da4b3ace87c83dec1c05e2d8b33349c5d16d
-  data.tar.gz: 6ab91367f32fa02d4582018fd6cad490ba4e78db92c86e231b64323a3389d88f
+  metadata.gz: 7d49b0bc867c3e318501548e7fcf45a3dd48bc469b05f959b5839144e3f9d472
+  data.tar.gz: 1193a9a5eea75c3d3b57d09ca10ccd5e50ee01d44ecce648c985ac2bcfd5cded
 SHA512:
-  metadata.gz: 859bbbfccff90fdddac6708846bc03b2a6f175bf83fd7ad9329a3de86d8830444e34d822eeeb65d4ba054678b1cda15312b85ca52b4dea2e43dc83cc2554e908
-  data.tar.gz: 169621c5fe064acc1ba293a01da9473c75aae65f7a650139c377319990140f2295fdae39d5b231fae7f3df7a506224d99e9f7d64acfb46af6967841ec46072c5
+  metadata.gz: 349259c93c833021ebfc46f7912f8c36109dc51693c3828972d263282f514adee94b5416d9e89c2dc1cc1d868d01cabce20ef1df01e83279eac80d156b1ded61
+  data.tar.gz: 67deac4b3306ffdc5ab36aa49b7ab66093dc4938131b3264ce2ef2cd6a628840cd04d3474f39fe7bc1f70dc5c0d9dba7bd136c28c46c58b776ff2494ae825030

data/CHANGELOG.md

@@ -5,9 +5,42 @@ 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.1.0] - 2023-03-01
+
+### Added
+
+- Made API base URI configurable to support services that proxy API calls (like Helicone)
+- Added support for the chat and audio endpoints
+
+## [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,15 @@ source "https://rubygems.org"
 
 gemspec
 
-gem "simplecov", require: false, group: :test
+group :development, :test do
+  gem "faker"
+  gem "rake", "~> 13.0"
+  gem "rspec", "~> 3.12"
+  gem "rubocop", "~> 1.44"
+  gem "rubocop-performance"
+  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/audio.rb

@@ -0,0 +1,52 @@
+require_relative "../utils/chat_messages_validator"
+
+module Asimov
+  module ApiV1
+    ##
+    # Class interface for API methods in the "/audio" URI subspace.
+    ##
+    class Audio < Base
+      RESOURCE = "audio".freeze
+
+      ##
+      # Creates a transcription request 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_transcription(file:, model:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+
+        rest_create_w_multipart_params(resource: [RESOURCE, "transcriptions"],
+                                       parameters:
+                                       open_file(parameters.merge({
+                                                                    file: file, model: model
+                                                                  })))
+      end
+
+      ##
+      # Creates a transcription request 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_translation(file:, model:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+
+        rest_create_w_multipart_params(resource: [RESOURCE, "translations"],
+                                       parameters:
+                                       open_file(parameters.merge({
+                                                                    file: file, model: model
+                                                                  })))
+      end
+
+      private
+
+      def open_file(parameters)
+        raise MissingRequiredParameterError.new(:file) unless parameters[:file]
+
+        parameters.merge(file: Utils::FileManager.open(parameters[:file]))
+      end
+    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
@@ -11,65 +15,115 @@ module Asimov
       extend Forwardable
       include HTTParty
 
-      base_uri "https://api.openai.com/v1"
-
       def initialize(client: nil)
         @client = client
       end
-      def_delegators :@client, :headers, :request_options
+      def_delegators :@client, :headers, :request_options, :openai_api_base
 
-      def http_delete(path:)
+      ##
+      # Executes a REST index for the specified resource
+      #
+      # @param [String] resource the pluralized resource name
+      ##
+      def rest_index(resource:)
+        wrap_response_with_error_handling do
+          self.class.get(
+            absolute_path("/#{Array(resource).join('/')}"),
+            { headers: headers }.merge!(request_options)
+          )
+        end
+      end
+
+      ##
+      # Executes a REST delete on the specified resource.
+      #
+      # @param [String] resource the pluralized resource name
+      # @param [String] id the id of the resource to delete
+      ##
+      def rest_delete(resource:, id:)
         wrap_response_with_error_handling do
           self.class.delete(
-            path,
+            absolute_path("/#{resource}/#{CGI.escape(id)}"),
             { headers: headers }.merge!(request_options)
           )
         end
       end
 
-      def http_get(path:)
+      ##
+      # Executes a REST get on the specified resource.
+      #
+      # @param [String] resource the pluralized resource name
+      # @param [String] id the id of the resource get
+      ##
+      def rest_get(resource:, id:)
         wrap_response_with_error_handling do
           self.class.get(
-            path,
+            absolute_path("/#{resource}/#{CGI.escape(id)}"),
             { headers: headers }.merge!(request_options)
           )
         end
       end
 
-      def json_post(path:, parameters:)
+      ##
+      # Executes a REST create with JSON-encoded parameters for the specified
+      # resource.
+      #
+      # @param [String] the resource to be created.
+      # @param [Hash] parameters the parameters to include with the request
+      # to create the resource
+      ##
+      def rest_create_w_json_params(resource:, parameters:)
         wrap_response_with_error_handling do
           self.class.post(
-            path,
+            absolute_path("/#{Array(resource).join('/')}"),
             { headers: headers,
               body: parameters&.to_json }.merge!(request_options)
           )
         end
       end
 
-      def multipart_post(path:, parameters: nil)
+      ##
+      # Executes a REST create with multipart-encoded parameters for the specified
+      # resource.
+      #
+      # @param [String] the resource to be created.
+      # @param [Hash] parameters the optional parameters to include with the request
+      # to create the resource
+      ##
+      def rest_create_w_multipart_params(resource:, parameters: nil)
         wrap_response_with_error_handling do
           self.class.post(
-            path,
+            absolute_path("/#{Array(resource).join('/')}"),
             { headers: headers("multipart/form-data"),
               body: parameters }.merge!(request_options)
           )
         end
       end
 
-      def http_streamed_download(path:, writer:)
-        self.class.get(path,
+      ##
+      # Executes an REST get on the specified path, streaming the resulting body
+      # to the writer in case of success.
+      #
+      # @param [Array] resource the resource path elements as an array
+      # @param [Writer] writer an object, typically a File, that responds to a `write` method
+      ##
+      def rest_get_streamed_download(resource:, writer:)
+        self.class.get(absolute_path("/#{Array(resource).join('/')}"),
                        { 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 absolute_path(path)
+        "#{openai_api_base}#{path}"
+      end
+
       def wrap_response_with_error_handling
         resp = begin
           yield
@@ -84,7 +138,6 @@ module Asimov
         return if resp.code == 200
 
         ApiErrorTranslator.translate(resp)
-        resp
       end
     end
   end

data/lib/asimov/api_v1/chat.rb

@@ -0,0 +1,29 @@
+require_relative "../utils/chat_messages_validator"
+
+module Asimov
+  module ApiV1
+    ##
+    # Class interface for API methods in the "/chat" URI subspace.
+    ##
+    class Chat < Base
+      RESOURCE = "chat".freeze
+
+      ##
+      # Creates a completion request 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_completions(model:, messages:, parameters: {})
+        raise MissingRequiredParameterError.new(:model) unless model
+        raise MissingRequiredParameterError.new(:messages) unless messages
+        raise StreamingResponseNotSupportedError if parameters[:stream]
+
+        messages = Utils::ChatMessagesValidator.validate_and_normalize(messages)
+        rest_create_w_json_params(resource: [RESOURCE, "completions"],
+                                  parameters: parameters.merge({ model: model,
+                                                                 messages: messages }))
+      end
+    end
+  end
+end

data/lib/asimov/api_v1/completions.rb

@@ -4,10 +4,18 @@ 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]
+      ##
+      # Creates a completion request 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)
+        rest_create_w_json_params(resource: "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]
+      ##
+      # Creates an edit resource 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)
+        rest_create_w_json_params(resource: "edits",
+                                  parameters: parameters.merge({ model: model,
+                                                                 instruction: instruction }))
       end
     end
   end

data/lib/asimov/api_v1/embeddings.rb

@@ -4,11 +4,22 @@ 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]
+      ##
+      # Creates an embedding resource with the specified parameters.
+      #
+      # @param [String] model the id for the model used to create the embedding
+      # @param [String] parameters the (optional) additional parameters being
+      # provided to inform embedding creation.
+      # @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)
+        rest_create_w_json_params(resource: "embeddings",
+                                  parameters: parameters.merge({
+                                                                 model: model, input: input
+                                                               }))
       end
     end
   end

data/lib/asimov/api_v1/files.rb

@@ -10,37 +10,62 @@ module Asimov
     # Class interface for API methods in the "/files" URI subspace.
     ##
     class Files < Base
-      URI_PREFIX = "/files".freeze
+      RESOURCE = "files".freeze
+      private_constant :RESOURCE
 
       ##
       # Lists files that have been uploaded to OpenAI
       ##
       def list
-        http_get(path: URI_PREFIX)
+        rest_index(resource: RESOURCE)
       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]))
+        rest_create_w_multipart_params(
+          resource: RESOURCE,
+          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}")
+        rest_get(resource: RESOURCE, id: 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}")
+        rest_delete(resource: RESOURCE, id: 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)
+        rest_get_streamed_download(resource: [RESOURCE, file_id, "content"], writer: writer)
       end
 
       private