datarobot-ai_api 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7763e2dae82034b312b2daf53061aafa7a1db5f091964a118c5eca2ecc3f8b33
+  data.tar.gz: 1b0ad22bf75f5ef9742c5baedbbb9784ff56a3d533f7034f91b838e3d91c7b1c
+SHA512:
+  metadata.gz: 742b703100a6ca1d24fd5c37c7e39a1f8ee94cc23d756136b78910c66ec182105cf5f5921e4bb6d6d48557098d310d05aebce6871073b93ad3eec18ebdf74578
+  data.tar.gz: 2fafe6e650f301e35c5ccc3207ee09e86c117b822e36bce90ebd47cde56a7f05d66221f4a6d80a7f8f6ae72111bbb96fcdb4b1cdfe028f7c7098452122f8fa71

data/.gitignore

@@ -0,0 +1,3 @@
+Gemfile.lock
+doc
+.rake_tasks~

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,12 @@
+## Objects
+
+* AI
+* Datasets
+* Learning Sessions
+* Outputs
+
+## Extra endpoints
+
+* Ping me
+* Ping
+* Status

data/Rakefile

@@ -0,0 +1,54 @@
+# coding:utf-8
+
+require 'rubygems'
+require 'rubygems/specification'
+require 'rake'
+
+def gemspec
+  @gemspec ||= begin
+    gem_name =  "datarobot-ai_api"
+    file = File.expand_path("../#{gem_name}.gemspec", __FILE__)
+    eval(File.read(file), binding, file)
+  end
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rake/gempackagetask'
+rescue LoadError
+  task(:gem) { $stderr.puts '`gem install rake` to package gems' }
+else
+  Rake::GemPackageTask.new(gemspec) do |pkg|
+    pkg.gem_spec = gemspec
+  end
+  task :gem => :gemspec
+end
+
+desc "Validates the gemspec"
+task :gemspec do
+  gemspec.validate
+end
+
+desc "Displays the current version"
+task :version do
+  puts "Current version: #{gemspec.version}"
+end
+
+desc "Installs the gem locally"
+task :install => :package do
+  sh "gem install pkg/#{gemspec.name}-#{gemspec.version}"
+end
+
+desc "Release the gem"
+task :release => :package do
+  sh "gem push pkg/#{gemspec.name}-#{gemspec.version}.gem"
+end
+
+task :package => :gemspec
+task :default => :test

data/datarobot-ai_api.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name        = 'datarobot-ai_api'
+  s.version     = '0.0.3'
+  s.date        = '2019-04-16'
+  s.summary     = "A Ruby wrapper for the DataRobot AI API"
+  s.description = "Provides an interface to the AI API"
+  s.authors     = ["AI API team"]
+  s.email       = 'ai-api-team@datarobot.com'
+  s.files       = %w(.gitignore README.md Rakefile datarobot-ai_api.gemspec lib/datarobot.rb Gemfile) + Dir.glob("{lib,test}/**/*")
+  s.homepage    =
+    'https://developers.datarobot.com/api'
+  s.license       = 'Nonstandard'
+  s.add_development_dependency "minitest", "~> 5.8"
+  s.add_development_dependency "minitest-reporters", "~> 1.1"
+  s.add_development_dependency "minitest-vcr", "~> 1.4"
+  s.add_development_dependency "webmock", "~> 3.6"
+  s.add_development_dependency 'pry', '~> 0.12.2'
+  s.add_runtime_dependency 'multipart-post', '~> 2.1'
+end

data/lib/datarobot.rb

@@ -0,0 +1 @@
+require_relative 'datarobot/ai_api'

data/lib/datarobot/ai_api.rb

@@ -0,0 +1,190 @@
+require 'net/https'
+require 'json'
+require 'cgi'
+require "net/http/post/multipart"
+
+module Datarobot
+  module AiApi
+    class UnauthorizedError < StandardError; end;
+    class NotFoundError < StandardError; end;
+    class ApiError < StandardError; end;
+
+    @@api_key = ''
+    @@base_url = 'https://developers.datarobot.com'
+
+    def self.api_key; @@api_key end
+    def self.api_key= v; @@api_key = v end
+
+    # Sets global API key
+    # @param [String] api_key The api key to use for authentication
+    # @return [Datarobot::AiApi]
+    def self.configure!(api_key: '', base_url: nil)
+      @@api_key = api_key
+      @@base_url = base_url if base_url
+      self
+    end
+
+    # Checks the `ping` endpoint. Useful for debugging
+    # @return [Hash]
+    def self.ping
+      request_endpoint('/aiapi/ping')
+    end
+
+    # Checks the `ping/me` endpoint. Useful for debugging authentication
+    # @return [Hash]
+    def self.ping_me
+      request_endpoint('/aiapi/ping/me')
+    end
+
+    # Adds default headers to a net http request
+    # @param [Net::HTTP::*] request The net/http request to add the headers to
+    # @param [Hash] additional_headers Will overwrite defaults 
+    # @return [Net::Http::*] returns an aribitrary request type (GET/POST/etc.)
+    def self.add_headers(request, additional_headers={})
+      request["User-Agent"] = "datarobot-ai/ruby"
+      request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@@api_key}"
+      additional_headers.each do |k, v|
+        request[k] = v
+      end
+      request
+    end
+
+    # Make a request with https. This is a helper method to avoid having to
+    # write net/http boilerplate
+    # @param [String] uri The uri to make the request to
+    # @param [Hash] params Additoinal params to add to the request. Will
+    # overwrite params in the query string of the given uri
+    #
+    # @yield [uri, http] Yields the https request with the parsed uri and http object
+    def self.with_https(uri, params={})
+      uri = URI.parse(uri)
+      existing_params = CGI::parse(uri.query.to_s)
+      uri.query = URI.encode_www_form(existing_params.merge params)
+      Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
+        yield uri, http
+      end
+    end
+
+    # Gets a bare uri. Useful for requests with `result` objects
+    # @param [String] bare_uri
+    # @param [Block] block passed to `handle_response`
+    def self.get(bare_uri, &block)
+      with_https(bare_uri) do |uri, http|
+        request = Net::HTTP::Get.new(uri)
+        request = add_headers(request)
+
+        response = http.request(request)
+        handle_response(response, &block)
+      end
+    end
+
+    # Converts a file into an octet stream, and uploads it to given endpoint
+    # @param [String] endpoint The endpoint to upload the file to
+    # @param [String] file_path Path to local file for upload
+    # @return Delegates return values to `handle_response`
+    def self.upload_to_endpoint(endpoint, file_path, &block)
+      uri = "#{@@base_url}#{endpoint}"
+      with_https(uri) do |uri, http|
+        request = Net::HTTP::Post::Multipart.new uri.request_uri, "file" => UploadIO.new(file_path, "application/octet-stream")
+        request["User-Agent"] = "datarobot-ai/ruby"
+        request["Authorization"] = "Bearer #{@@api_key}"
+        response = http.request(request)
+        handle_response(response, &block)
+      end
+    end
+
+    # Common error handling and response parsing
+    # @yield [data] Yields the parsed json response if there is one
+    # @return nil if body is empty
+    # @return [Hash] data Parsed json response if no block is provided
+    def self.handle_response(response, &block)
+      if response.code.to_i < 300
+        return nil if response.body.to_s.empty?
+        data = JSON.parse(response.body)
+        if block_given?
+          yield data
+        else
+          data
+        end
+      else
+        determine_error(response)
+      end
+    end
+
+    # Makes a request to the given endpoint
+    # @param [String] endpoint The url path to the endpoint
+    # @param [String] method The HTTP method to make the request with
+    # @param [Hash] body JSON body. Only used in put and post requests
+    # @param [Hash] headers Additional headers to add to request
+    # @param [Hash] params Additoinal url parameters to add
+    # @return Delegates return values to `handle_response`
+    def self.request_endpoint(endpoint, method: 'get', body: {}, headers: {}, params: {}, &block)
+      uri_str = "#{@@base_url}#{endpoint}"
+      with_https(uri_str, params) do |uri, http|
+        case method.downcase
+        when 'put'
+          request = Net::HTTP::Put.new(uri.request_uri)
+          request.body = JSON.dump(body)
+        when 'delete'
+          request = Net::HTTP::Delete.new(uri.request_uri)
+        when 'post'
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request.body = JSON.dump(body)
+        else
+          request = Net::HTTP::Get.new(uri)
+        end
+        request = add_headers(request, headers)
+
+        response = http.request(request)
+        handle_response(response, &block)
+      end
+    end
+
+    # Uses request data to determin error classes
+    # Only raises values. Will never return
+    def self.determine_error(response_obj)
+      parsed = JSON.parse(response_obj.body)
+      msg = parsed["error"] || parsed["message"]
+      case response_obj.code
+      when "403"
+        raise Datarobot::AiApi::UnauthorizedError, msg
+      when "404"
+        raise Datarobot::AiApi::NotFoundError, msg
+      else
+        raise Datarobot::AiApi::ApiError, msg
+      end
+    end
+
+    # Given an arbitrary url, return the correct AiApi object
+    # @param [String] url
+    # @return [Datarobot::AiApi::*]
+    def self.determine_object(url)
+      case url
+      when /\/ais/
+        Datarobot::AiApi::AI
+      when /\/datasets/
+        Datarobot::AiApi::Dataset
+      when /\/learningSessions/
+        Datarobot::AiApi::LearningSession
+      when /\/outputs/
+        Datarobot::AiApi::Output
+      when /\/status/
+        Datarobot::AiApi::Task
+      when /\/deployment/
+        Datarobot::AiApi::Deployment
+      end
+    end
+  end
+end
+
+require 'datarobot/ai_api/page'
+require 'datarobot/ai_api/refreshable'
+require 'datarobot/ai_api/evaluation'
+require 'datarobot/ai_api/deployment'
+require 'datarobot/ai_api/ai'
+require 'datarobot/ai_api/dataset'
+require 'datarobot/ai_api/task'
+require 'datarobot/ai_api/learning_session'
+require 'datarobot/ai_api/output'
+require 'datarobot/ai_api/prediction'

data/lib/datarobot/ai_api/ai.rb

@@ -0,0 +1,191 @@
+module Datarobot
+  module AiApi
+
+    # This is the primary model in the AI API. This is the thing that learns
+    # about the data that you give it
+    class AI
+      include Datarobot::AiApi::Refreshable
+      attr_reader :output_count, :dataset_count, :learning_session_count, :id
+      attr_accessor :name,
+
+      # Retrieves all AIs as a paginated resource.
+      #
+      # @param [Integer] limit Number of AIs per page
+      # @param [Integer] offset How many AIs to skip before this page
+      #
+      # @return [Datarobot::AiApi::Page(Datarobot::AiApi::AI)]
+      def self.all(limit: 50, offset: 0)
+        Datarobot::AiApi.request_endpoint('/aiapi/ais/', params: {limit: limit, offset: offset}) do |data|
+          Datarobot::AiApi::Page.new(self, data)
+        end
+      end
+
+      # Retrieves an AI given an ID.
+      #
+      # @param [String] id The ID of the AI to retrieve
+      #
+      # @return [Datarobot::AiApi::AI]
+      def self.find(id, &block)
+        raise Datarobot::AiApi::NotFoundError, "Cannot find AI with id: nil" if id.nil?
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{id}") do |data|
+          if block_given?
+            yield data
+          else
+            self.new(data)
+          end
+        end
+      end
+
+      # Creates an AI
+      #
+      # @param [String] name The ID of the AI to retrieve
+      #
+      # @return [Datarobot::AiApi::AI]
+      def self.create(name: 'New AI')
+        Datarobot::AiApi.request_endpoint('/aiapi/ais/', method: 'post', body: { name: name }) do |data|
+          ai_data = Datarobot::AiApi.get(data["links"]["result"])
+          new(ai_data)
+        end
+      end
+
+      # Deletes an AI. Returns `nil` if the action was successful. Will raise
+      # an error if the action was unsuccessful
+      #
+      # @param [String] id The ID of the AI to delete
+      #
+      # @return [nil]
+      def self.delete(id)
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{id}", method: "delete")
+      end
+
+      # Given a parsed response body from the API, will create a new AI object
+      def initialize(options = {})
+        # Suppresses warnings about uninitialized variables
+        @id = nil
+        @name = nil
+        @dataset_count = nil
+        @output_count = nil
+        @learning_session_count = nil
+
+        set_from_options(options)
+        @outputs = nil
+      end
+
+      # Takes a response body from the API. Will set all AI attributes from the
+      # response body
+      #
+      # @param [Hash] options A parsed response body
+      # @return [void]
+      def set_from_options(options = {})
+        # one-liner replacement for `stringify_keys`
+        options = options.collect{|k,v| [k.to_s, v]}.to_h
+
+        @output_count = options.dig("outputCount") || @output_count
+        @dataset_count = options.dig("datasetCount") || @dataset_count
+        @learning_session_count = options.dig("learningSessionCount") || @learning_session_count
+        @name = options.dig("name") || @name
+        @id = options.dig("id") || @id
+      end
+
+      # Lists all the outputs associated with the AI as a paginated resource
+      #
+      # @return [Datarobot::AiApi::Page(Datarobot::AiApi::Output)]
+      def outputs
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{@id}/outputs") do |data|
+          data["aiId"] = @id
+          Datarobot::AiApi::Page.new(Datarobot::AiApi::Output, data)
+        end
+      end
+
+      # Lists all the datasets associated with the AI as a paginated resource
+      #
+      # @return [Datarobot::AiApi::Page(Datarobot::AiApi::Dataset)]
+      def datasets
+        Datarobot::AiApi.request_endpoint("/aiapi/datasets?aiId=#{@id}") do |data|
+          data["aiId"] = @id
+          Datarobot::AiApi::Page.new(Datarobot::AiApi::Dataset, data)
+        end
+      end
+
+      # Finds an output by name
+      #
+      # @param [String] name The name of the output associated with this AI
+      # that you want to find
+      # @return [Datarobot::AiApi::Output]
+      def find_output(name)
+        # TODO: Update this when AI API supports CGI escaped URIs
+        #
+        # This code was lifted from source of erb method:
+        # https://apidock.com/ruby/v2_6_3/ERB/Util/url_encode
+        #
+        # URI.escape is deprecated because it does not encode url control
+        # characters, thus making it a potential security issue and CGI.escape
+        # substitutes whitespace with a + which is correct, but unsupported by
+        # the AI API
+        encoded_name = name.gsub(/[^a-zA-Z0-9_\-.~]/) { |m|
+          sprintf("%%%02X", m.unpack1("C"))
+        }
+
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{@id}/outputs/#{encoded_name}") do |data|
+          data["aiId"] = @id
+          Datarobot::AiApi::Output.new(data)
+        end
+      end
+
+      # Adds a dataset to the AI. Raises an error on failure. Returns true on
+      # success
+      #
+      # @param [String] dataset_id The ID of the dataset to add
+      # @return [Bool] true
+      def add_dataset(dataset_id)
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{@id}/datasets", method: 'post', body: { datasetId: dataset_id })
+        true
+      end
+
+      # Adds a learning session to the AI. Raises an error on failure. Returns
+      # true on success
+      #
+      # @param [String] session_id The ID of the learning session to add
+      # @return [Bool] true
+      def add_learning_session(session_id)
+        Datarobot::AiApi.request_endpoint("/aiapi/ais/#{@id}/learningSessions", method: 'post', body: { learningSessionId: session_id })
+        true
+      end
+
+      # Trains an AI on the given target with the data in the file at the given
+      # path. Returns true if successful. Raises an error otherwise
+      #
+      # @param [String] target The target to train the AI on
+      # @return [Bool] true
+      def train(target, file_path)
+        dataset = Datarobot::AiApi::Dataset.create_from_file(file_path)
+        add_dataset(dataset.id)
+        learning_session = Datarobot::AiApi::LearningSession.create(dataset_id: dataset.id, target: target)
+        add_learning_session(learning_session.id)
+        Datarobot::AiApi::Output.create(ai_id: @id, learning_session_id: learning_session.id, output_name: "#{@name} output")
+        true
+      end
+
+      # Predicts a target feature given a data hash
+      #
+      # @param target The target feature to predict
+      # @param data The remaining features used to predict target feature
+      def predict(target, data={})
+        output = outputs.find { |o| o.target == target }
+
+        raise NotFoundError, "No output with target #{target.inspect} found AI with ID #{@id.inspect}" if output.nil?
+
+        deployment_id = output.source["deploymentId"]
+        key = output.source["datarobot-key"]
+        Datarobot::AiApi.request_endpoint(
+          "/predApi/v1.0/deployments/#{deployment_id}/predictions/",
+          method: 'post',
+          body: [ data ],
+          headers: {"datarobot-key" => key}
+        ) do |data|
+          Datarobot::AiApi::Page.new(Datarobot::AiApi::Prediction, data)
+        end
+      end
+    end
+  end
+end