monkeylearn-ruby

Official Ruby client for the MonkeyLearn API. Build and consume machine learning models for language processing from your Ruby apps.

Installation

Install with rubygems:

$ gem install monkeylearn

Or add this line to your Gemfile

$ gem "monkeylearn", "~> 3"

Usage

First, require and configure the lib:

Before making requests to the API, you need to set your account API Key:

require 'monkeylearn'

# Basic configuration
Monkeylearn.configure do |c|
  c.token = 'INSERT_YOUR_API_TOKEN_HERE'
end

Requests

From the Monkeylearn module, you can call any endpoint (check the available endpoints below). For example, you can classify a list of texts using the public Sentiment analysis classifier:

classifier_model_id='cl_Jx8qzYJh'
data = [
  'Great hotel with excellent location',
  'This is the worst hotel ever.'
]

response = Monkeylearn.classifiers.classify(classifier_model_id, data)

Responses

The response object returned by every endpoint call is a MonkeylearnResponse object. The body attribute has the parsed response from the API:

puts response.body
# =>  [
# =>      {
# =>          "text" => "Great hotel with excellent location",
# =>          "external_id" => nil,
# =>          "error" => false,
# =>          "classifications" => [
# =>              {
# =>                  "tag_name" => "Positive",
# =>                  "tag_id" => 1994,
# =>                  "confidence" => 0.922,
# =>              }
# =>          ]
# =>      },
# =>      {
# =>          "text" => "This is the worst hotel ever.",
# =>          "external_id" => nil,
# =>          "error" => false,
# =>          "classifications" => [
# =>              {
# =>                  "tag_name" => "Negative",
# =>                  "tag_id" => 1941,
# =>                  "confidence" => 0.911,
# =>              }
# =>          ]
# =>      }
# =>  ]

You can also access other attributes in the response object to get information about the queries used or available:

puts response.plan_queries_allowed
# =>  300

puts response.plan_queries_remaining
# =>  240

puts response.request_queries_used
# =>  2

Errors

Endpoint calls may raise exceptions. Here is an example on how to handle them:

begin
  response = Monkeylearn.classifiers.classify("[MODEL_ID]", ["My text"])
rescue PlanQueryLimitError => d
  puts "#{d.error_code}: #{d.detail}"
end

Available exceptions:

Handling batching and throttled responses manually

Classify and Extract endpoints may require more than one request to the MonkeyLearn API in order to process every text in the data parameter. If the auto_batch config is true (which is the default value) you don't have to keep the data length below the max allowed value (200), you can just pass the full list and the library will handle the bactching making multiple requests if necessary.

If you want to handle this yourself you can set auto_batch to false and slice the data yourself:

require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = 'INSERT_YOUR_API_TOKEN_HERE'
  c.auto_batch = false
end

data = ['Text to classify'] * 300
batch_size = 200
model_id = '[MODULE_ID]'

responses = (0...data.length).step(batch_size).collect do |start_idx|
  sliced_data = data[start_idx, batch_size]
  Monkeylearn.classifiers.classify(model_id, sliced_data, batch_size: batch_size)
end

multi_response = Monkeylearn::MultiResponse.new(responses)

puts multi_response.body

Also, any API calls might be throttled (see Rate limiting). If the retry_if_throttled config is true (which is the default value) any throttled request will be retried after waiting (sleep) the required time.

You can control this manually if you need to:

require 'monkeylearn'

Monkeylearn.configure do |c|
  c.token = 'INSERT_YOUR_API_TOKEN_HERE'
  c.auto_batch = false
  c.retry_if_throttled = false
end

data = ['Text to classify'] * 300
batch_size = 200
model_id = '[MODULE_ID]'

responses = (0...data.length).step(batch_size).collect do |start_idx|
  sliced_data = data[start_idx, batch_size]
  throttled = true
  while throttled
    begin
      response = Monkeylearn.classifiers.classify(model_id, sliced_data, batch_size: batch_size)
      throttled = false
    rescue ConcurrencyRateLimitError
      sleep 2
    rescue PlanRateLimitError => e
      sleep e.seconds_to_wait
    end
  end
  response
end

multi_response = Monkeylearn::MultiResponse.new(responses)

puts multi_response.body

This way you'll be able to control every request that is sent to the MonkeyLearn API.

Available endpoints

The following are all the endpoints of the API. For more information about each endpoint, check out the API documentation.

Classifiers

Classify

Monkeylearn.classifiers.classify(model_id, data, options = {})

Parameters:

Optional parameters:

Example:

data = ["First text", {text: "Second text", external_id: "2"}]
response = Monkeylearn.classifiers.classify("[MODEL_ID]", data)

Classifier detail

Monkeylearn.classifiers.detail(model_id)

Parameters:

Example:

response = Monkeylearn.classifiers.detail("[MODEL_ID]")

Create Classifier

Monkeylearn.classifiers.create(name, options = {})

Parameters:

Optional parameters:

Example:

response = Monkeylearn.classifiers.create("New classifier name", algorithm: "svm", ngram_range: [1, 2])

Edit Classifier

Monkeylearn.classifiers.edit(model_id, options = {})

Parameters:

Optional parameters:

Example:

response = Monkeylearn.classifiers.edit("[MODEL_ID]", name: "New classifier name", algorithm: "nb")

Delete classifier

Monkeylearn.classifiers.delete(model_id)

Parameters:

Example:

Monkeylearn.classifiers.delete('[MODEL_ID]')

List Classifiers

Monkeylearn.classifiers.list(page: 1, per_page: 20, order_by: '-created')

Optional parameters:

Example:

response = Monkeylearn.classifiers.list(page: 2, per_page: 5, order_by: ['-is_public', 'name'])

Train

Monkeylearn.classifiers.train(model_id)

Parameters:

Example:

Monkeylearn.classifiers.train('[MODEL_ID]')

Deploy

Monkeylearn.classifiers.deploy(model_id)

Parameters:

Example:

Monkeylearn.classifiers.deploy('[MODEL_ID]')

Tag detail

Monkeylearn.classifiers.tags.detail(model_id, tag_id)

Parameters:

Example:

response = Monkeylearn.classifiers.tags.detail("[MODEL_ID]", TAG_ID)

Create tag

Monkeylearn.classifiers.tags.create(model_id, name, options = {})

Parameters:

Example:

response = Monkeylearn.classifiers.tags.create("[MODEL_ID]", "Positive")

Edit tag

Monkeylearn.classifiers.tags.edit(model_id, tag_id, options = {})

Parameters:

Optional parameters:

Example:

response = Monkeylearn.classifiers.tags.edit("[MODEL_ID]", TAG_ID, name: "New name")

Delete tag

Monkeylearn.classifiers.tags.delete(model_id, tag_id, options = {})

Parameters:

Optional parameters:

Example:

Monkeylearn.classifiers.tags.delete("[MODEL_ID]", TAG_ID)

Upload data

Monkeylearn.classifiers.upload_data(model_id, data)

Parameters:

data hash keys:

Example:

response = Monkeylearn.classifiers.upload_data(
  "[MODEL_ID]",
  [{text: "text 1", tags: [TAG_ID_1, "[tag_name]"]},
   {text: "text 2", tags: [TAG_ID_1, TAG_ID_2]}]
)

Extractors

Extract

Monkeylearn.extractors.extract(model_id, data, options = {})

Parameters:

Optional parameters:

Example:

data = ["First text", {"text": "Second text", "external_id": "2"}]
response = Monkeylearn.extractors.extract("[MODEL_ID]", data)

Extractor detail

Monkeylearn.extractors.detail(model_id)

Parameters:

Example:

response = Monkeylearn.extractors.detail("[MODEL_ID]")

List extractors

Monkeylearn.extractors.list(page: 1, per_page: 20, order_by: '-created')

Parameters:

Example:

response = Monkeylearn.extractors.list(page: 2, per_page: 5, order_by: ['-is_public', 'name'])