ibm_watson 0.9.2 → 0.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -96,31 +96,30 @@ module IBMWatson
96
96
  # Translates the input text from the source language to the target language.
97
97
  # @param text [Array[String]] Input text in UTF-8 encoding. Multiple entries will result in multiple
98
98
  # translations in the response.
99
- # @param model_id [String] Model ID of the translation model to use. If this is specified, the **source** and
100
- # **target** parameters will be ignored. The method requires either a model ID or
101
- # both the **source** and **target** parameters.
102
- # @param source [String] Language code of the source text language. Use with `target` as an alternative way
103
- # to select a translation model. When `source` and `target` are set, and a model ID
104
- # is not set, the system chooses a default model for the language pair (usually the
105
- # model based on the news domain).
106
- # @param target [String] Language code of the translation target language. Use with source as an
107
- # alternative way to select a translation model.
99
+ # @param model_id [String] A globally unique string that identifies the underlying model that is used for
100
+ # translation.
101
+ # @param source [String] Translation source language code.
102
+ # @param target [String] Translation target language code.
108
103
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
109
104
  def translate(text:, model_id: nil, source: nil, target: nil)
110
- raise ArgumentError("text must be provided") if text.nil?
105
+ raise ArgumentError.new("text must be provided") if text.nil?
111
106
 
112
107
  headers = {
113
108
  }
109
+
114
110
  params = {
115
111
  "version" => @version
116
112
  }
113
+
117
114
  data = {
118
115
  "text" => text,
119
116
  "model_id" => model_id,
120
117
  "source" => source,
121
118
  "target" => target
122
119
  }
120
+
123
121
  method_url = "/v3/translate"
122
+
124
123
  response = request(
125
124
  method: "POST",
126
125
  url: method_url,
@@ -144,10 +143,13 @@ module IBMWatson
144
143
  def list_identifiable_languages
145
144
  headers = {
146
145
  }
146
+
147
147
  params = {
148
148
  "version" => @version
149
149
  }
150
+
150
151
  method_url = "/v3/identifiable_languages"
152
+
151
153
  response = request(
152
154
  method: "GET",
153
155
  url: method_url,
@@ -165,16 +167,20 @@ module IBMWatson
165
167
  # @param text [String] Input text in UTF-8 format.
166
168
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
167
169
  def identify(text:)
168
- raise ArgumentError("text must be provided") if text.nil?
170
+ raise ArgumentError.new("text must be provided") if text.nil?
169
171
 
170
172
  headers = {
171
173
  }
174
+
172
175
  params = {
173
176
  "version" => @version
174
177
  }
178
+
175
179
  data = text
176
180
  headers["Content-Type"] = "text/plain"
181
+
177
182
  method_url = "/v3/identify"
183
+
178
184
  response = request(
179
185
  method: "POST",
180
186
  url: method_url,
@@ -203,13 +209,16 @@ module IBMWatson
203
209
  def list_models(source: nil, target: nil, default_models: nil)
204
210
  headers = {
205
211
  }
212
+
206
213
  params = {
207
214
  "version" => @version,
208
215
  "source" => source,
209
216
  "target" => target,
210
217
  "default" => default_models
211
218
  }
219
+
212
220
  method_url = "/v3/models"
221
+
213
222
  response = request(
214
223
  method: "GET",
215
224
  url: method_url,
@@ -257,47 +266,43 @@ module IBMWatson
257
266
  # @param parallel_corpus_filename [String] The filename for parallel_corpus.
258
267
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
259
268
  def create_model(base_model_id:, name: nil, forced_glossary: nil, parallel_corpus: nil, forced_glossary_filename: nil, parallel_corpus_filename: nil)
260
- raise ArgumentError("base_model_id must be provided") if base_model_id.nil?
269
+ raise ArgumentError.new("base_model_id must be provided") if base_model_id.nil?
261
270
 
262
271
  headers = {
263
272
  }
273
+
264
274
  params = {
265
275
  "version" => @version,
266
276
  "base_model_id" => base_model_id,
267
277
  "name" => name
268
278
  }
279
+
280
+ form_data = {}
281
+
269
282
  unless forced_glossary.nil?
270
- mime_type = "application/octet-stream"
271
283
  unless forced_glossary.instance_of?(StringIO) || forced_glossary.instance_of?(File)
272
284
  forced_glossary = forced_glossary.respond_to?(:to_json) ? StringIO.new(forced_glossary.to_json) : StringIO.new(forced_glossary)
273
285
  end
274
- if forced_glossary_filename
275
- forced_glossary = forced_glossary.instance_of?(StringIO) ? HTTP::FormData::File.new(forced_glossary, content_type: mime_type, filename: forced_glossary_filename) : HTTP::FormData::File.new(forced_glossary.path, content_type: mime_type, filename: forced_glossary_filename)
276
- else
277
- forced_glossary = forced_glossary.instance_of?(StringIO) ? HTTP::FormData::File.new(forced_glossary, content_type: mime_type) : HTTP::FormData::File.new(forced_glossary.path, content_type: mime_type)
278
- end
286
+ forced_glossary_filename = forced_glossary.path if forced_glossary_filename.nil? && forced_glossary.respond_to?(:path)
287
+ form_data[:forced_glossary] = HTTP::FormData::File.new(forced_glossary, content_type: "application/octet-stream", filename: forced_glossary_filename)
279
288
  end
289
+
280
290
  unless parallel_corpus.nil?
281
- mime_type = "application/octet-stream"
282
291
  unless parallel_corpus.instance_of?(StringIO) || parallel_corpus.instance_of?(File)
283
292
  parallel_corpus = parallel_corpus.respond_to?(:to_json) ? StringIO.new(parallel_corpus.to_json) : StringIO.new(parallel_corpus)
284
293
  end
285
- if parallel_corpus_filename
286
- parallel_corpus = parallel_corpus.instance_of?(StringIO) ? HTTP::FormData::File.new(parallel_corpus, content_type: mime_type, filename: parallel_corpus_filename) : HTTP::FormData::File.new(parallel_corpus.path, content_type: mime_type, filename: parallel_corpus_filename)
287
- else
288
- parallel_corpus = parallel_corpus.instance_of?(StringIO) ? HTTP::FormData::File.new(parallel_corpus, content_type: mime_type) : HTTP::FormData::File.new(parallel_corpus.path, content_type: mime_type)
289
- end
294
+ parallel_corpus_filename = parallel_corpus.path if parallel_corpus_filename.nil? && parallel_corpus.respond_to?(:path)
295
+ form_data[:parallel_corpus] = HTTP::FormData::File.new(parallel_corpus, content_type: "application/octet-stream", filename: parallel_corpus_filename)
290
296
  end
297
+
291
298
  method_url = "/v3/models"
299
+
292
300
  response = request(
293
301
  method: "POST",
294
302
  url: method_url,
295
303
  headers: headers,
296
304
  params: params,
297
- form: {
298
- forced_glossary: forced_glossary,
299
- parallel_corpus: parallel_corpus
300
- },
305
+ form: form_data,
301
306
  accept_json: true
302
307
  )
303
308
  response
@@ -310,14 +315,17 @@ module IBMWatson
310
315
  # @param model_id [String] Model ID of the model to delete.
311
316
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
312
317
  def delete_model(model_id:)
313
- raise ArgumentError("model_id must be provided") if model_id.nil?
318
+ raise ArgumentError.new("model_id must be provided") if model_id.nil?
314
319
 
315
320
  headers = {
316
321
  }
322
+
317
323
  params = {
318
324
  "version" => @version
319
325
  }
326
+
320
327
  method_url = "/v3/models/%s" % [ERB::Util.url_encode(model_id)]
328
+
321
329
  response = request(
322
330
  method: "DELETE",
323
331
  url: method_url,
@@ -337,14 +345,17 @@ module IBMWatson
337
345
  # @param model_id [String] Model ID of the model to get.
338
346
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
339
347
  def get_model(model_id:)
340
- raise ArgumentError("model_id must be provided") if model_id.nil?
348
+ raise ArgumentError.new("model_id must be provided") if model_id.nil?
341
349
 
342
350
  headers = {
343
351
  }
352
+
344
353
  params = {
345
354
  "version" => @version
346
355
  }
356
+
347
357
  method_url = "/v3/models/%s" % [ERB::Util.url_encode(model_id)]
358
+
348
359
  response = request(
349
360
  method: "GET",
350
361
  url: method_url,
@@ -86,16 +86,19 @@ module IBMWatson
86
86
  # @param text [String] The submitted phrase. The maximum length is 2048 characters.
87
87
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
88
88
  def classify(classifier_id:, text:)
89
- raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
89
+ raise ArgumentError.new("classifier_id must be provided") if classifier_id.nil?
90
90
 
91
- raise ArgumentError("text must be provided") if text.nil?
91
+ raise ArgumentError.new("text must be provided") if text.nil?
92
92
 
93
93
  headers = {
94
94
  }
95
+
95
96
  data = {
96
97
  "text" => text
97
98
  }
99
+
98
100
  method_url = "/v1/classifiers/%s/classify" % [ERB::Util.url_encode(classifier_id)]
101
+
99
102
  response = request(
100
103
  method: "POST",
101
104
  url: method_url,
@@ -117,16 +120,19 @@ module IBMWatson
117
120
  # @param collection [Array[ClassifyInput]] The submitted phrases.
118
121
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
119
122
  def classify_collection(classifier_id:, collection:)
120
- raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
123
+ raise ArgumentError.new("classifier_id must be provided") if classifier_id.nil?
121
124
 
122
- raise ArgumentError("collection must be provided") if collection.nil?
125
+ raise ArgumentError.new("collection must be provided") if collection.nil?
123
126
 
124
127
  headers = {
125
128
  }
129
+
126
130
  data = {
127
131
  "collection" => collection
128
132
  }
133
+
129
134
  method_url = "/v1/classifiers/%s/classify_collection" % [ERB::Util.url_encode(classifier_id)]
135
+
130
136
  response = request(
131
137
  method: "POST",
132
138
  url: method_url,
@@ -153,45 +159,40 @@ module IBMWatson
153
159
  # (`de`), Italian (`it`), Japanese (`ja`), Korean (`ko`), Brazilian Portuguese
154
160
  # (`pt`), and Spanish (`es`).
155
161
  # @param training_data [File] Training data in CSV format. Each text value must have at least one class. The
156
- # data can include up to 20,000 records. For details, see [Data
162
+ # data can include up to 3,000 classes and 20,000 records. For details, see [Data
157
163
  # preparation](https://console.bluemix.net/docs/services/natural-language-classifier/using-your-data.html).
158
164
  # @param metadata_filename [String] The filename for training_metadata.
159
165
  # @param training_data_filename [String] The filename for training_data.
160
166
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
161
167
  def create_classifier(metadata:, training_data:, metadata_filename: nil, training_data_filename: nil)
162
- raise ArgumentError("metadata must be provided") if metadata.nil?
168
+ raise ArgumentError.new("metadata must be provided") if metadata.nil?
163
169
 
164
- raise ArgumentError("training_data must be provided") if training_data.nil?
170
+ raise ArgumentError.new("training_data must be provided") if training_data.nil?
165
171
 
166
172
  headers = {
167
173
  }
168
- mime_type = "application/json"
174
+
175
+ form_data = {}
176
+
169
177
  unless metadata.instance_of?(StringIO) || metadata.instance_of?(File)
170
178
  metadata = metadata.respond_to?(:to_json) ? StringIO.new(metadata.to_json) : StringIO.new(metadata)
171
179
  end
172
- if metadata_filename
173
- metadata = metadata.instance_of?(StringIO) ? HTTP::FormData::File.new(metadata, content_type: mime_type, filename: metadata_filename) : HTTP::FormData::File.new(metadata.path, content_type: mime_type, filename: metadata_filename)
174
- else
175
- metadata = metadata.instance_of?(StringIO) ? HTTP::FormData::File.new(metadata, content_type: mime_type) : HTTP::FormData::File.new(metadata.path, content_type: mime_type)
176
- end
177
- mime_type = "text/csv"
180
+ metadata_filename = metadata.path if metadata_filename.nil? && metadata.respond_to?(:path)
181
+ form_data[:training_metadata] = HTTP::FormData::File.new(metadata, content_type: "application/json", filename: metadata_filename)
182
+
178
183
  unless training_data.instance_of?(StringIO) || training_data.instance_of?(File)
179
184
  training_data = training_data.respond_to?(:to_json) ? StringIO.new(training_data.to_json) : StringIO.new(training_data)
180
185
  end
181
- if training_data_filename
182
- training_data = training_data.instance_of?(StringIO) ? HTTP::FormData::File.new(training_data, content_type: mime_type, filename: training_data_filename) : HTTP::FormData::File.new(training_data.path, content_type: mime_type, filename: training_data_filename)
183
- else
184
- training_data = training_data.instance_of?(StringIO) ? HTTP::FormData::File.new(training_data, content_type: mime_type) : HTTP::FormData::File.new(training_data.path, content_type: mime_type)
185
- end
186
+ training_data_filename = training_data.path if training_data_filename.nil? && training_data.respond_to?(:path)
187
+ form_data[:training_data] = HTTP::FormData::File.new(training_data, content_type: "text/csv", filename: training_data_filename)
188
+
186
189
  method_url = "/v1/classifiers"
190
+
187
191
  response = request(
188
192
  method: "POST",
189
193
  url: method_url,
190
194
  headers: headers,
191
- form: {
192
- training_metadata: metadata,
193
- training_data: training_data
194
- },
195
+ form: form_data,
195
196
  accept_json: true
196
197
  )
197
198
  response
@@ -205,7 +206,9 @@ module IBMWatson
205
206
  def list_classifiers
206
207
  headers = {
207
208
  }
209
+
208
210
  method_url = "/v1/classifiers"
211
+
209
212
  response = request(
210
213
  method: "GET",
211
214
  url: method_url,
@@ -222,11 +225,13 @@ module IBMWatson
222
225
  # @param classifier_id [String] Classifier ID to query.
223
226
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
224
227
  def get_classifier(classifier_id:)
225
- raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
228
+ raise ArgumentError.new("classifier_id must be provided") if classifier_id.nil?
226
229
 
227
230
  headers = {
228
231
  }
232
+
229
233
  method_url = "/v1/classifiers/%s" % [ERB::Util.url_encode(classifier_id)]
234
+
230
235
  response = request(
231
236
  method: "GET",
232
237
  url: method_url,
@@ -242,11 +247,13 @@ module IBMWatson
242
247
  # @param classifier_id [String] Classifier ID to delete.
243
248
  # @return [nil]
244
249
  def delete_classifier(classifier_id:)
245
- raise ArgumentError("classifier_id must be provided") if classifier_id.nil?
250
+ raise ArgumentError.new("classifier_id must be provided") if classifier_id.nil?
246
251
 
247
252
  headers = {
248
253
  }
254
+
249
255
  method_url = "/v1/classifiers/%s" % [ERB::Util.url_encode(classifier_id)]
256
+
250
257
  request(
251
258
  method: "DELETE",
252
259
  url: method_url,
@@ -20,7 +20,7 @@
20
20
  # can ignore most advertisements and other unwanted content.
21
21
  #
22
22
  # You can create [custom
23
- # models](/docs/services/natural-language-understanding/customizing.html) with Watson
23
+ # models](https://console.bluemix.net/docs/services/natural-language-understanding/customizing.html) with Watson
24
24
  # Knowledge Studio to detect custom entities and relations in Natural Language
25
25
  # Understanding.
26
26
 
@@ -96,22 +96,33 @@ module IBMWatson
96
96
 
97
97
  ##
98
98
  # @!method analyze(features:, text: nil, html: nil, url: nil, clean: nil, xpath: nil, fallback_to_raw: nil, return_analyzed_text: nil, language: nil, limit_text_characters: nil)
99
- # Analyze text, HTML, or a public webpage.
100
- # Analyzes text, HTML, or a public webpage with one or more text analysis features,
101
- # including categories, concepts, emotion, entities, keywords, metadata, relations,
102
- # semantic roles, and sentiment.
103
- # @param features [Features] Specific features to analyze the document for.
99
+ # Analyze text.
100
+ # Analyzes text, HTML, or a public webpage for the following features:
101
+ # - Categories
102
+ # - Concepts
103
+ # - Emotion
104
+ # - Entities
105
+ # - Keywords
106
+ # - Metadata
107
+ # - Relations
108
+ # - Semantic roles
109
+ # - Sentiment.
110
+ # @param features [Features] Analysis features and options.
104
111
  # @param text [String] The plain text to analyze. One of the `text`, `html`, or `url` parameters is
105
112
  # required.
106
113
  # @param html [String] The HTML file to analyze. One of the `text`, `html`, or `url` parameters is
107
114
  # required.
108
- # @param url [String] The web page to analyze. One of the `text`, `html`, or `url` parameters is
115
+ # @param url [String] The webpage to analyze. One of the `text`, `html`, or `url` parameters is
109
116
  # required.
110
- # @param clean [Boolean] Remove website elements, such as links, ads, etc.
111
- # @param xpath [String] An [XPath query](https://www.w3.org/TR/xpath/) to perform on `html` or `url`
112
- # input. Results of the query will be appended to the cleaned webpage text before it
113
- # is analyzed. To analyze only the results of the XPath query, set the `clean`
114
- # parameter to `false`.
117
+ # @param clean [Boolean] Set this to `false` to disable webpage cleaning. To learn more about webpage
118
+ # cleaning, see the [Analyzing
119
+ # webpages](https://console.bluemix.net/docs/services/natural-language-understanding/analyzing-webpages.html)
120
+ # documentation.
121
+ # @param xpath [String] An [XPath
122
+ # query](https://console.bluemix.net/docs/services/natural-language-understanding/analyzing-webpages.html#xpath)
123
+ # to perform on `html` or `url` input. Results of the query will be appended to the
124
+ # cleaned webpage text before it is analyzed. To analyze only the results of the
125
+ # XPath query, set the `clean` parameter to `false`.
115
126
  # @param fallback_to_raw [Boolean] Whether to use raw HTML content if text cleaning fails.
116
127
  # @param return_analyzed_text [Boolean] Whether or not to return the analyzed text.
117
128
  # @param language [String] ISO 639-1 code that specifies the language of your text. This overrides automatic
@@ -122,13 +133,15 @@ module IBMWatson
122
133
  # @param limit_text_characters [Fixnum] Sets the maximum number of characters that are processed by the service.
123
134
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
124
135
  def analyze(features:, text: nil, html: nil, url: nil, clean: nil, xpath: nil, fallback_to_raw: nil, return_analyzed_text: nil, language: nil, limit_text_characters: nil)
125
- raise ArgumentError("features must be provided") if features.nil?
136
+ raise ArgumentError.new("features must be provided") if features.nil?
126
137
 
127
138
  headers = {
128
139
  }
140
+
129
141
  params = {
130
142
  "version" => @version
131
143
  }
144
+
132
145
  data = {
133
146
  "features" => features,
134
147
  "text" => text,
@@ -141,7 +154,9 @@ module IBMWatson
141
154
  "language" => language,
142
155
  "limit_text_characters" => limit_text_characters
143
156
  }
157
+
144
158
  method_url = "/v1/analyze"
159
+
145
160
  response = request(
146
161
  method: "POST",
147
162
  url: method_url,
@@ -159,17 +174,20 @@ module IBMWatson
159
174
  ##
160
175
  # @!method list_models
161
176
  # List models.
162
- # Lists available models for Relations and Entities features, including Watson
163
- # Knowledge Studio custom models that you have created and linked to your Natural
164
- # Language Understanding service.
177
+ # Lists Watson Knowledge Studio [custom
178
+ # models](https://console.bluemix.net/docs/services/natural-language-understanding/customizing.html) that are
179
+ # deployed to your Natural Language Understanding service.
165
180
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
166
181
  def list_models
167
182
  headers = {
168
183
  }
184
+
169
185
  params = {
170
186
  "version" => @version
171
187
  }
188
+
172
189
  method_url = "/v1/models"
190
+
173
191
  response = request(
174
192
  method: "GET",
175
193
  url: method_url,
@@ -187,14 +205,17 @@ module IBMWatson
187
205
  # @param model_id [String] model_id of the model to delete.
188
206
  # @return [DetailedResponse] A `DetailedResponse` object representing the response.
189
207
  def delete_model(model_id:)
190
- raise ArgumentError("model_id must be provided") if model_id.nil?
208
+ raise ArgumentError.new("model_id must be provided") if model_id.nil?
191
209
 
192
210
  headers = {
193
211
  }
212
+
194
213
  params = {
195
214
  "version" => @version
196
215
  }
216
+
197
217
  method_url = "/v1/models/%s" % [ERB::Util.url_encode(model_id)]
218
+
198
219
  response = request(
199
220
  method: "DELETE",
200
221
  url: method_url,