Skip to content

Latest commit

 

History

History
629 lines (435 loc) · 25.9 KB

README.md

File metadata and controls

629 lines (435 loc) · 25.9 KB
Raw

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'])