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:

class	Description
MonkeylearnError	Base class for each exception below.
RequestParamsError	An invalid parameter was sent. Check the exception message or response object for more information.
AuthenticationError	Authentication failed, usually because an invalid token was provided. Check the exception message. More about Authentication.
ForbiddenError	You don't have permissions to perform the action on the given resource.
ModelLimitError	You have reached the custom model limit for your plan.
ModelNotFound	The model does not exist. Check the model_id.
TagNotFound	The tag does not exist. Check the tag_id parameter.
PlanQueryLimitError	You have reached the monthly query limit for your plan. Consider upgrading your plan. More about Plan query limits.
PlanRateLimitError	You have sent too many requests in the last minute. Check the exception details. More about Plan rate limit.
ConcurrencyRateLimitError	You have sent too many requests in the last second. Check the exception details. More about Concurrency rate limit.
ModuleStateError	The state of the module is invalid. Check the exception details.

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:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example 'cl_oJNMkt2V'.
data	Array[String or Hash]	A list of up to 200 data elements to classify. Each element must be a String with the text or a Hash with the required text key and the text as the value. You can provide an optional external_id key with a string that will be included in the response.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Default	Description
production_model	Boolean	False	Indicates if the classifications are performed by the production model. Only use this parameter with custom models (not with the public ones). Note that you first need to deploy your model to production either from the UI model settings or by using the Classifier deploy endpoint.
batch_size	Integer	200	Max amount of texts each request will send to Monkeylearn. A number from 1 to 200.

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:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.

Example:

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

Create Classifier

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

Parameters:

Parameter	Type	Description
name	String	The name of the model.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Default	Description
description	String	''	The description of the model.
algorithm	String	'nb'	The algorithm used when training the model. It can either be "nb" or "svm".
language	String	'en'	The language of the model. Full list of supported languages.
max_features	Integer	10000	The maximum number of features used when training the model. Between 10 and 100000.
ngram_range	Array	[1,1]	Indicates which n-gram range is used when training the model. It's a list of two numbers between 1 and 3. They indicate the minimum and the maximum n for the n-grams used, respectively.
use_stemming	Boolean	true	Indicates whether stemming is used when training the model.
preprocess_numbers	Boolean	true	Indicates whether number preprocessing is done when training the model.
preprocess_social_media	Boolean	false	Indicates whether preprocessing of social media is done when training the model.
normalize_weights	Boolean	true	Indicates whether weights will be normalized when training the model.
stopwords	Boolean or Array	true	The list of stopwords used when training the model. Use false for no stopwords, true for the default stopwords, or an array of strings for custom stopwords.
whitelist	Array	[]	The whitelist of words used when training the model.

Example:

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

Edit Classifier

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

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Description
name	String	The name of the model.
description	String	The description of the model.
algorithm	String	The algorithm used when training the model. It can either be "nb" or "svm".
language	String	The language of the model. Full list of supported languages.
max_features	Integer	The maximum number of features used when training the model. Between 10 and 100000.
ngram_range	Array	Indicates which n-gram range used when training the model. A list of two numbers between 1 and 3. They indicate the minimum and the maximum n for the n-grams used, respectively.
use_stemming	Boolean	Indicates whether stemming is used when training the model.
preprocess_numbers	Boolean	Indicates whether number preprocessing is done when training the model.
preprocess_social_media	Boolean	Indicates whether preprocessing of social media is done when training the model.
normalize_weights	Boolean	Indicates whether weights will be normalized when training the model.
stopwords	Boolean or Array	The list of stopwords used when training the model. Use false for no stopwords, true for the default stopwords, or an array of strings for custom stopwords.
whitelist	Array	The whitelist of words used when training the model.

Example:

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

Delete classifier

Monkeylearn.classifiers.delete(model_id)

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.

Example:

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

List Classifiers

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

Optional parameters:

Parameter	Type	Default	Description
page	Integer	1	Specifies which page to get.
per_page	Integer	20	Specifies how many items per page will be returned.
order_by	String or Array	'-created'	Specifies the ordering criteria. It can either be a String for single criteria ordering or an array of Strings for more than one. Each String must be a valid field name; if you want inverse/descending order of the field prepend a - (dash) character. Some valid examples are: 'is_public', '-name' or ['-is_public', 'name'].

Example:

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

Train

Monkeylearn.classifiers.train(model_id)

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.

Example:

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

Deploy

Monkeylearn.classifiers.deploy(model_id)

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.

Example:

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

Tag detail

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

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
tag_id	Integer	Tag ID.

Example:

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

Create tag

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

Parameters:

Parameter	Type	Description
model_id	`String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
name	String	The name of the new tag.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Example:

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

Edit tag

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

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
tag_id	Integer	Tag ID.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Description
name	String	The new name of the tag.

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:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
tag_id	Integer	Tag ID.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Default	Description
move_data_to	int	nil	An optional tag ID. If provided, data associated with the tag to be deleted will be moved to the specified tag before deletion.

Example:

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

Upload data

Monkeylearn.classifiers.upload_data(model_id, data)

Parameters:

Parameter	Type	Description
model_id	String	Classifier ID. It always starts with 'cl', for example, 'cl_oJNMkt2V'.
data	Array[Hash]	A list of hashes with the keys described below.

data hash keys:

Key	Description
text	A String of the text to upload.
tags	An optional Array of tags that can be refered to by their numeric ID or their name. The text will be tagged with each tag in the list when created (in case it doesn't already exist on the model). Otherwise, its tags will be updated to the new ones. New tags will be created if they don't already exist.
markers	An optional Array of String. Each one represents a marker that will be associated with the text. New markers will be created if they don't already exist.

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:

Parameter	Type	Description
model_id	String	Extractor ID. It always starts with 'ex', for example, 'ex_oJNMkt2V'.
data	Array[String or Hash]	A list of up to 200 data elements to extract from. Each element must be a string with the text or a dict with the required text key and the text as the value. You can also provide an optional external_id key with a string that will be included in the response.
options	Hash	Optional parameters, see below. The hash always expects symbols as keys.

Optional parameters:

Parameter	Type	Default	Description
production_model	Boolean	False	Indicates if the extractions are performed by the production model. Only use this parameter with custom models (not with the public ones). Note that you first need to deploy the model to production either from the UI model settings or by using the Classifier deploy endpoint.
batch_size	Integer	200	Max number of texts each request will send to MonkeyLearn. A number from 1 to 200.

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:

Parameter	Type	Description
model_id	String	Extractor ID. It always starts with 'ex', for example, 'ex_oJNMkt2V'.

Example:

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

List extractors

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

Parameters:

Parameter	Type	Default	Description
page	Integer	1	Specifies which page to get.
per_page	Integer	20	Specifies how many items per page will be returned.
order_by	String or Array	'-created'	Specifies the ordering criteria. It can either be a String for single criteria ordering or an array of Strings for more than one. Each String must be a valid field name; if you want inverse/descending order of the field prepend a - (dash) character. Some valid examples are: 'is_public', '-name' or ['-is_public', 'name'].

Example:

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