ibm_watson 1.3.0 → 2.0.0.rc1

data/lib/ibm_watson/language_translator_v3.rb

@@ -13,9 +13,11 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+#
+# IBM OpenAPI SDK Code Generator Version: 3.17.0-8d569e8f-20201030-142059
+#
 # IBM Watson™ Language Translator translates text from one language to another.
-# The service offers multiple IBM provided translation models that you can customize based
+# The service offers multiple IBM-provided translation models that you can customize based
 # on your unique terminology and language. Use Language Translator to take news from
 # across the globe and present it in your language, communicate with your customers in
 # their own language, and more.
@@ -32,39 +34,75 @@ module IBMWatson
   # The Language Translator V3 service.
   class LanguageTranslatorV3 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "language_translator"
+    DEFAULT_SERVICE_URL = "https://api.us-south.language-translator.watson.cloud.ibm.com"
+    attr_accessor :version
     ##
     # @!method initialize(args)
     # Construct a new client for the Language Translator service.
     #
     # @param args [Hash] The args to initialize with
-    # @option args version [String] The API version date to use with the service, in
-    #   "YYYY-MM-DD" format. Whenever the API is changed in a backwards
-    #   incompatible way, a new minor version of the API is released.
-    #   The service uses the API version for the date you specify, or
-    #   the most recent version before that date. Note that you should
-    #   not programmatically specify the current date at runtime, in
-    #   case the API has been updated since your application's release.
-    #   Instead, specify a version date that is compatible with your
-    #   application, and don't change it until your application is
-    #   ready for a later version.
+    # @option args version [String] Release date of the version of the API you want to use. Specify dates in
+    #   YYYY-MM-DD format. The current version is `2018-05-01`.
     # @option args service_url [String] The base service URL to use when contacting the service.
     #   The base service_url may differ between IBM Cloud regions.
     # @option args authenticator [Object] The Authenticator instance to be configured for this service.
+    # @option args service_name [String] The name of the service to configure. Will be used as the key to load
+    #   any external configuration, if applicable.
     def initialize(args = {})
       @__async_initialized__ = false
       defaults = {}
-      defaults[:version] = nil
-      defaults[:service_url] = "https://gateway.watsonplatform.net/language-translator/api"
+      defaults[:service_url] = DEFAULT_SERVICE_URL
+      defaults[:service_name] = DEFAULT_SERVICE_NAME
       defaults[:authenticator] = nil
+      defaults[:version] = nil
+      user_service_url = args[:service_url] unless args[:service_url].nil?
       args = defaults.merge(args)
       @version = args[:version]
       raise ArgumentError.new("version must be provided") if @version.nil?
 
-      args[:service_name] = "language_translator"
       args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
       super
+      @service_url = user_service_url unless user_service_url.nil?
     end
 
+    #########################
+    # Languages
+    #########################
+
+    ##
+    # @!method list_languages
+    # List supported languages.
+    # Lists all supported languages for translation. The method returns an array of
+    #   supported languages with information about each language. Languages are listed in
+    #   alphabetical order by language code (for example, `af`, `ar`). In addition to
+    #   basic information about each language, the response indicates whether the language
+    #   is `supported_as_source` for translation and `supported_as_target` for
+    #   translation. It also lists whether the language is `identifiable`.
+    # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
+    def list_languages
+      raise ArgumentError.new("version must be provided") if version.nil?
+
+      headers = {
+      }
+      sdk_headers = Common.new.get_sdk_headers("language_translator", "V3", "list_languages")
+      headers.merge!(sdk_headers)
+
+      params = {
+        "version" => @version
+      }
+
+      method_url = "/v3/languages"
+
+      response = request(
+        method: "GET",
+        url: method_url,
+        headers: headers,
+        params: params,
+        accept_json: true
+      )
+      response
+    end
     #########################
     # Translation
     #########################
@@ -72,15 +110,31 @@ module IBMWatson
     ##
     # @!method translate(text:, model_id: nil, source: nil, target: nil)
     # Translate.
-    # Translates the input text from the source language to the target language.
-    # @param text [Array[String]] Input text in UTF-8 encoding. Multiple entries will result in multiple
-    #   translations in the response.
-    # @param model_id [String] A globally unique string that identifies the underlying model that is used for
-    #   translation.
-    # @param source [String] Translation source language code.
-    # @param target [String] Translation target language code.
+    # Translates the input text from the source language to the target language. Specify
+    #   a model ID that indicates the source and target languages, or specify the source
+    #   and target languages individually. You can omit the source language to have the
+    #   service attempt to detect the language from the input text. If you omit the source
+    #   language, the request must contain sufficient input text for the service to
+    #   identify the source language.
+    #
+    #   You can translate a maximum of 50 KB (51,200 bytes) of text with a single request.
+    #   All input text must be encoded in UTF-8 format.
+    # @param text [Array[String]] Input text in UTF-8 encoding. Submit a maximum of 50 KB (51,200 bytes) of text
+    #   with a single request. Multiple elements result in multiple translations in the
+    #   response.
+    # @param model_id [String] The model to use for translation. For example, `en-de` selects the IBM-provided
+    #   base model for English-to-German translation. A model ID overrides the `source`
+    #   and `target` parameters and is required if you use a custom model. If no model ID
+    #   is specified, you must specify at least a target language.
+    # @param source [String] Language code that specifies the language of the input text. If omitted, the
+    #   service derives the source language from the input text. The input must contain
+    #   sufficient text for the service to identify the language reliably.
+    # @param target [String] Language code that specifies the target language for translation. Required if
+    #   model ID is not specified.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def translate(text:, model_id: nil, source: nil, target: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("text must be provided") if text.nil?
 
       headers = {
@@ -122,6 +176,8 @@ module IBMWatson
     #   example, `en` for English or `es` for Spanish) and name of each language.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_identifiable_languages
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       headers = {
       }
       sdk_headers = Common.new.get_sdk_headers("language_translator", "V3", "list_identifiable_languages")
@@ -150,6 +206,8 @@ module IBMWatson
     # @param text [String] Input text in UTF-8 format.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def identify(text:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("text must be provided") if text.nil?
 
       headers = {
@@ -186,12 +244,15 @@ module IBMWatson
     # Lists available translation models.
     # @param source [String] Specify a language code to filter results by source language.
     # @param target [String] Specify a language code to filter results by target language.
-    # @param default [Boolean] If the default parameter isn't specified, the service will return all models
+    # @param default [Boolean] If the `default` parameter isn't specified, the service returns all models
     #   (default and non-default) for each language pair. To return only default models,
-    #   set this to `true`. To return only non-default models, set this to `false`. There
-    #   is exactly one default model per language pair, the IBM provided base model.
+    #   set this parameter to `true`. To return only non-default models, set this
+    #   parameter to `false`. There is exactly one default model, the IBM-provided base
+    #   model, per language pair.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_models(source: nil, target: nil, default: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       headers = {
       }
       sdk_headers = Common.new.get_sdk_headers("language_translator", "V3", "list_models")
@@ -219,38 +280,109 @@ module IBMWatson
     ##
     # @!method create_model(base_model_id:, forced_glossary: nil, parallel_corpus: nil, name: nil)
     # Create model.
-    # Uploads Translation Memory eXchange (TMX) files to customize a translation model.
+    # Uploads training files to customize a translation model. You can customize a model
+    #   with a forced glossary or with a parallel corpus:
+    #   * Use a *forced glossary* to force certain terms and phrases to be translated in a
+    #   specific way. You can upload only a single forced glossary file for a model. The
+    #   size of a forced glossary file for a custom model is limited to 10 MB.
+    #   * Use a *parallel corpus* when you want your custom model to learn from general
+    #   translation patterns in parallel sentences in your samples. What your model learns
+    #   from a parallel corpus can improve translation results for input text that the
+    #   model has not been trained on. You can upload multiple parallel corpora files with
+    #   a request. To successfully train with parallel corpora, the corpora files must
+    #   contain a cumulative total of at least 5000 parallel sentences. The cumulative
+    #   size of all uploaded corpus files for a custom model is limited to 250 MB.
+    #
+    #   Depending on the type of customization and the size of the uploaded files,
+    #   training time can range from minutes for a glossary to several hours for a large
+    #   parallel corpus. To create a model that is customized with a parallel corpus and a
+    #   forced glossary, customize the model with a parallel corpus first and then
+    #   customize the resulting model with a forced glossary.
+    #
+    #   You can create a maximum of 10 custom models per language pair. For more
+    #   information about customizing a translation model, including the formatting and
+    #   character restrictions for data files, see [Customizing your
+    #   model](https://cloud.ibm.com/docs/language-translator?topic=language-translator-customizing).
+    #
+    #
+    #   #### Supported file formats
+    #
+    #    You can provide your training data for customization in the following document
+    #   formats:
+    #   * **TMX** (`.tmx`) - Translation Memory eXchange (TMX) is an XML specification for
+    #   the exchange of translation memories.
+    #   * **XLIFF** (`.xliff`) - XML Localization Interchange File Format (XLIFF) is an
+    #   XML specification for the exchange of translation memories.
+    #   * **CSV** (`.csv`) - Comma-separated values (CSV) file with two columns for
+    #   aligned sentences and phrases. The first row must have two language codes. The
+    #   first column is for the source language code, and the second column is for the
+    #   target language code.
+    #   * **TSV** (`.tsv` or `.tab`) - Tab-separated values (TSV) file with two columns
+    #   for aligned sentences and phrases. The first row must have two language codes. The
+    #   first column is for the source language code, and the second column is for the
+    #   target language code.
+    #   * **JSON** (`.json`) - Custom JSON format for specifying aligned sentences and
+    #   phrases.
+    #   * **Microsoft Excel** (`.xls` or `.xlsx`) - Excel file with the first two columns
+    #   for aligned sentences and phrases. The first row contains the language code.
+    #
+    #   You must encode all text data in UTF-8 format. For more information, see
+    #   [Supported document formats for training
+    #   data](https://cloud.ibm.com/docs/language-translator?topic=language-translator-customizing#supported-document-formats-for-training-data).
+    #
+    #
+    #   #### Specifying file formats
+    #
+    #    You can indicate the format of a file by including the file extension with the
+    #   file name. Use the file extensions shown in **Supported file formats**.
+    #
+    #   Alternatively, you can omit the file extension and specify one of the following
+    #   `content-type` specifications for the file:
+    #   * **TMX** - `application/x-tmx+xml`
+    #   * **XLIFF** - `application/xliff+xml`
+    #   * **CSV** - `text/csv`
+    #   * **TSV** - `text/tab-separated-values`
+    #   * **JSON** - `application/json`
+    #   * **Microsoft Excel** -
+    #   `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
     #
-    #   You can either customize a model with a forced glossary or with a corpus that
-    #   contains parallel sentences. To create a model that is customized with a parallel
-    #   corpus <b>and</b> a forced glossary, proceed in two steps: customize with a
-    #   parallel corpus first and then customize the resulting model with a glossary.
-    #   Depending on the type of customization and the size of the uploaded corpora,
-    #   training can range from minutes for a glossary to several hours for a large
-    #   parallel corpus. You can upload a single forced glossary file and this file must
-    #   be less than <b>10 MB</b>. You can upload multiple parallel corpora tmx files. The
-    #   cumulative file size of all uploaded files is limited to <b>250 MB</b>. To
-    #   successfully train with a parallel corpus you must have at least <b>5,000 parallel
-    #   sentences</b> in your corpus.
+    #   For example, with `curl`, use the following `content-type` specification to
+    #   indicate the format of a CSV file named **glossary**:
     #
-    #   You can have a <b>maximum of 10 custom models per language pair</b>.
-    # @param base_model_id [String] The model ID of the model to use as the base for customization. To see available
-    #   models, use the `List models` method. Usually all IBM provided models are
-    #   customizable. In addition, all your models that have been created via parallel
-    #   corpus customization, can be further customized with a forced glossary.
-    # @param forced_glossary [File] A TMX file with your customizations. The customizations in the file completely
-    #   overwrite the domain translaton data, including high frequency or high confidence
-    #   phrase translations. You can upload only one glossary with a file size less than
-    #   10 MB per call. A forced glossary should contain single words or short phrases.
-    # @param parallel_corpus [File] A TMX file with parallel sentences for source and target language. You can upload
-    #   multiple parallel_corpus files in one request. All uploaded parallel_corpus files
-    #   combined, your parallel corpus must contain at least 5,000 parallel sentences to
-    #   train successfully.
+    #   `--form "forced_glossary=@glossary;type=text/csv"`.
+    # @param base_model_id [String] The ID of the translation model to use as the base for customization. To see
+    #   available models and IDs, use the `List models` method. Most models that are
+    #   provided with the service are customizable. In addition, all models that you
+    #   create with parallel corpora customization can be further customized with a forced
+    #   glossary.
+    # @param forced_glossary [File] A file with forced glossary terms for the source and target languages. The
+    #   customizations in the file completely overwrite the domain translation data,
+    #   including high frequency or high confidence phrase translations.
+    #
+    #   You can upload only one glossary file for a custom model, and the glossary can
+    #   have a maximum size of 10 MB. A forced glossary must contain single words or short
+    #   phrases. For more information, see **Supported file formats** in the method
+    #   description.
+    #
+    #   *With `curl`, use `--form forced_glossary=@{filename}`.*.
+    # @param parallel_corpus [File] A file with parallel sentences for the source and target languages. You can upload
+    #   multiple parallel corpus files in one request by repeating the parameter. All
+    #   uploaded parallel corpus files combined must contain at least 5000 parallel
+    #   sentences to train successfully. You can provide a maximum of 500,000 parallel
+    #   sentences across all corpora.
+    #
+    #   A single entry in a corpus file can contain a maximum of 80 words. All corpora
+    #   files for a custom model can have a cumulative maximum size of 250 MB. For more
+    #   information, see **Supported file formats** in the method description.
+    #
+    #   *With `curl`, use `--form parallel_corpus=@{filename}`.*.
     # @param name [String] An optional model name that you can use to identify the model. Valid characters
-    #   are letters, numbers, dashes, underscores, spaces and apostrophes. The maximum
-    #   length is 32 characters.
+    #   are letters, numbers, dashes, underscores, spaces, and apostrophes. The maximum
+    #   length of the name is 32 characters.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def create_model(base_model_id:, forced_glossary: nil, parallel_corpus: nil, name: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("base_model_id must be provided") if base_model_id.nil?
 
       headers = {
@@ -300,6 +432,8 @@ module IBMWatson
     # @param model_id [String] Model ID of the model to delete.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def delete_model(model_id:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("model_id must be provided") if model_id.nil?
 
       headers = {
@@ -328,10 +462,12 @@ module IBMWatson
     # Get model details.
     # Gets information about a translation model, including training status for custom
     #   models. Use this API call to poll the status of your customization request. A
-    #   successfully completed training will have a status of `available`.
+    #   successfully completed training has a status of `available`.
     # @param model_id [String] Model ID of the model to get.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def get_model(model_id:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("model_id must be provided") if model_id.nil?
 
       headers = {
@@ -364,6 +500,8 @@ module IBMWatson
     # Lists documents that have been submitted for translation.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def list_documents
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       headers = {
       }
       sdk_headers = Common.new.get_sdk_headers("language_translator", "V3", "list_documents")
@@ -390,23 +528,31 @@ module IBMWatson
     # Translate document.
     # Submit a document for translation. You can submit the document contents in the
     #   `file` parameter, or you can reference a previously submitted document by document
-    #   ID.
-    # @param file [File] The contents of the source file to translate.
-    #
-    #   [Supported file
-    #   types](https://cloud.ibm.com/docs/services/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats)
-    #
-    #   Maximum file size: **20 MB**.
+    #   ID. The maximum file size for document translation is
+    #   * 20 MB for service instances on the Standard, Advanced, and Premium plans
+    #   * 2 MB for service instances on the Lite plan.
+    # @param file [File] The contents of the source file to translate. The maximum file size for document
+    #   translation is 20 MB for service instances on the Standard, Advanced, and Premium
+    #   plans, and 2 MB for service instances on the Lite plan. For more information, see
+    #   [Supported file formats
+    #   (Beta)](https://cloud.ibm.com/docs/language-translator?topic=language-translator-document-translator-tutorial#supported-file-formats).
     # @param filename [String] The filename for file.
     # @param file_content_type [String] The content type of file.
-    # @param model_id [String] The model to use for translation. `model_id` or both `source` and `target` are
-    #   required.
-    # @param source [String] Language code that specifies the language of the source document.
-    # @param target [String] Language code that specifies the target language for translation.
+    # @param model_id [String] The model to use for translation. For example, `en-de` selects the IBM-provided
+    #   base model for English-to-German translation. A model ID overrides the `source`
+    #   and `target` parameters and is required if you use a custom model. If no model ID
+    #   is specified, you must specify at least a target language.
+    # @param source [String] Language code that specifies the language of the source document. If omitted, the
+    #   service derives the source language from the input text. The input must contain
+    #   sufficient text for the service to identify the language reliably.
+    # @param target [String] Language code that specifies the target language for translation. Required if
+    #   model ID is not specified.
     # @param document_id [String] To use a previously submitted document as the source for a new translation, enter
     #   the `document_id` of the document.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def translate_document(file:, filename: nil, file_content_type: nil, model_id: nil, source: nil, target: nil, document_id: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("file must be provided") if file.nil?
 
       headers = {
@@ -454,6 +600,8 @@ module IBMWatson
     # @param document_id [String] The document ID of the document.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def get_document_status(document_id:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("document_id must be provided") if document_id.nil?
 
       headers = {
@@ -484,6 +632,8 @@ module IBMWatson
     # @param document_id [String] Document ID of the document to delete.
     # @return [nil]
     def delete_document(document_id:)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("document_id must be provided") if document_id.nil?
 
       headers = {
@@ -527,6 +677,8 @@ module IBMWatson
     #   example, 'text/html;charset=utf-8'.
     # @return [IBMCloudSdkCore::DetailedResponse] A `IBMCloudSdkCore::DetailedResponse` object representing the response.
     def get_translated_document(document_id:, accept: nil)
+      raise ArgumentError.new("version must be provided") if version.nil?
+
       raise ArgumentError.new("document_id must be provided") if document_id.nil?
 
       headers = {

data/lib/ibm_watson/natural_language_classifier_v1.rb

@@ -13,7 +13,9 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-
+#
+# IBM OpenAPI SDK Code Generator Version: 3.17.0-8d569e8f-20201030-142059
+#
 # IBM Watson™ Natural Language Classifier uses machine learning algorithms to
 # return the top matching predefined classes for short text input. You create and train a
 # classifier to connect predefined classes to example texts so that the service can apply
@@ -31,6 +33,8 @@ module IBMWatson
   # The Natural Language Classifier V1 service.
   class NaturalLanguageClassifierV1 < IBMCloudSdkCore::BaseService
     include Concurrent::Async
+    DEFAULT_SERVICE_NAME = "natural_language_classifier"
+    DEFAULT_SERVICE_URL = "https://api.us-south.natural-language-classifier.watson.cloud.ibm.com"
     ##
     # @!method initialize(args)
     # Construct a new client for the Natural Language Classifier service.
@@ -39,15 +43,19 @@ module IBMWatson
     # @option args service_url [String] The base service URL to use when contacting the service.
     #   The base service_url may differ between IBM Cloud regions.
     # @option args authenticator [Object] The Authenticator instance to be configured for this service.
+    # @option args service_name [String] The name of the service to configure. Will be used as the key to load
+    #   any external configuration, if applicable.
     def initialize(args = {})
       @__async_initialized__ = false
       defaults = {}
-      defaults[:service_url] = "https://gateway.watsonplatform.net/natural-language-classifier/api"
+      defaults[:service_url] = DEFAULT_SERVICE_URL
+      defaults[:service_name] = DEFAULT_SERVICE_NAME
       defaults[:authenticator] = nil
+      user_service_url = args[:service_url] unless args[:service_url].nil?
       args = defaults.merge(args)
-      args[:service_name] = "natural_language_classifier"
       args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
       super
+      @service_url = user_service_url unless user_service_url.nil?
     end
 
     #########################