ibm_watson.assistant_v1 module

The IBM Watson™ Assistant service combines machine learning, natural language understanding, and integrated dialog tools to create conversation flows between your apps and your users.

class AssistantV1(version, url='https://gateway.watsonplatform.net/assistant/api', username=None, password=None, iam_apikey=None, iam_access_token=None, iam_url=None)

Bases: ibm_cloud_sdk_core.base_service.BaseService

The Assistant V1 service.

default_url = 'https://gateway.watsonplatform.net/assistant/api'

message(workspace_id, input=None, intents=None, entities=None, alternate_intents=None, context=None, output=None, nodes_visited_details=None, **kwargs)

Get response to user input.

Send user input to a workspace and receive a response. There is no rate limit for this operation.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• input (MessageInput) – An input object that includes the input text.

• intents (list[RuntimeIntent]) – Intents to use when evaluating the user input.

Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input. :param list[RuntimeEntity] entities: Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input. :param bool alternate_intents: Whether to return more than one intent. A value of true indicates that all matching intents are returned. :param Context context: State information for the conversation. To maintain state, include the context from the previous response. :param OutputData output: An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log. :param bool nodes_visited_details: Whether to include additional diagnostic information about the dialog nodes that were visited during processing of the message. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_workspace(name=None, description=None, language=None, metadata=None, learning_opt_out=None, system_settings=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, **kwargs)

Create workspace.

Create a workspace based on component objects. You must provide workspace components defining the content of the new workspace. This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Parameters

name (str) – The name of the workspace. This string cannot contain carriage

return, newline, or tab characters, and it must be no longer than 64 characters. :param str description: The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param str language: The language of the workspace. :param dict metadata: Any metadata related to the workspace. :param bool learning_opt_out: Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used. :param WorkspaceSystemSettings system_settings: Global settings for the workspace. :param list[CreateIntent] intents: An array of objects defining the intents for the workspace. :param list[CreateEntity] entities: An array of objects describing the entities for the workspace. :param list[DialogNode] dialog_nodes: An array of objects describing the dialog nodes in the workspace. :param list[Counterexample] counterexamples: An array of objects defining input examples that have been marked as irrelevant input. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_workspace(workspace_id, **kwargs)

Delete workspace.

Delete a workspace from the service instance. This operation is limited to 30 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_workspace(workspace_id, export=None, include_audit=None, sort=None, **kwargs)

Get information about a workspace.

Get information about a workspace, optionally including all workspace content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 20 requests per 30 minutes. For more information, see **Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param str sort: Indicates how the returned workspace data will be sorted. This parameter is valid only if **export**=`true`. Specify sort=stable to sort all workspace objects by unique identifier, in ascending alphabetical order. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_workspaces(page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List workspaces.

List the workspaces associated with a Watson Assistant service instance. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• page_limit (int) – The number of records to return in each page of results.

• include_count (bool) – Whether to include information about the number of

records returned. :param str sort: The attribute by which returned workspaces will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_workspace(workspace_id, name=None, description=None, language=None, metadata=None, learning_opt_out=None, system_settings=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None, append=None, **kwargs)

Update workspace.

Update an existing workspace with new or modified data. You must provide component objects defining the content of the updated workspace. This operation is limited to 30 request per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• name (str) – The name of the workspace. This string cannot contain carriage

return, newline, or tab characters, and it must be no longer than 64 characters. :param str description: The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param str language: The language of the workspace. :param dict metadata: Any metadata related to the workspace. :param bool learning_opt_out: Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used. :param WorkspaceSystemSettings system_settings: Global settings for the workspace. :param list[CreateIntent] intents: An array of objects defining the intents for the workspace. :param list[CreateEntity] entities: An array of objects describing the entities for the workspace. :param list[DialogNode] dialog_nodes: An array of objects describing the dialog nodes in the workspace. :param list[Counterexample] counterexamples: An array of objects defining input examples that have been marked as irrelevant input. :param bool append: Whether the new data is to be appended to the existing data in the workspace. If append**=`false`, elements included in the new data completely replace the corresponding existing elements, including all subelements. For example, if the new data includes **entities and **append**=`false`, all existing entities in the workspace are discarded and replaced with the new entities. If **append**=`true`, existing elements are preserved, and the new elements are added. If any elements in the new data collide with existing elements, the update request fails. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_intent(workspace_id, intent, description=None, examples=None, **kwargs)

Create intent.

Create a new intent. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The name of the intent. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. :param str description: The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param list[Example] examples: An array of user input examples for the intent. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_intent(workspace_id, intent, **kwargs)

Delete intent.

Delete an intent from a workspace. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_intent(workspace_id, intent, export=None, include_audit=None, **kwargs)

Get intent.

Get information about an intent, optionally including all intent content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 400 requests per 30 minutes. For more information, see **Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_intents(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List intents.

List the intents for a workspace. With export**=`false`, this operation is limited to 2000 requests per 30 minutes. With **export**=`true`, the limit is 400 requests per 30 minutes. For more information, see **Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param int page_limit: The number of records to return in each page of results. :param bool include_count: Whether to include information about the number of records returned. :param str sort: The attribute by which returned intents will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_intent(workspace_id, intent, new_intent=None, new_description=None, new_examples=None, **kwargs)

Update intent.

Update an existing intent with new or modified data. You must provide component objects defining the content of the updated intent. This operation is limited to 2000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• new_intent (str) – The name of the intent. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. :param str new_description: The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param list[Example] new_examples: An array of user input examples for the intent. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_example(workspace_id, intent, text, mentions=None, **kwargs)

Create user input example.

Add a new user input example to an intent. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• text (str) – The text of a user input example. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 1024 characters. :param list[Mention] mentions: An array of contextual entity mentions. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_example(workspace_id, intent, text, **kwargs)

Delete user input example.

Delete a user input example from an intent. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• text (str) – The text of the user input example.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_example(workspace_id, intent, text, include_audit=None, **kwargs)

Get user input example.

Get information about a user input example. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• text (str) – The text of the user input example.

• include_audit (bool) – Whether to include the audit properties (created and

updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_examples(workspace_id, intent, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List user input examples.

List the user input examples for an intent, optionally including contextual entity mentions. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• page_limit (int) – The number of records to return in each page of results.

• include_count (bool) – Whether to include information about the number of

records returned. :param str sort: The attribute by which returned examples will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_example(workspace_id, intent, text, new_text=None, new_mentions=None, **kwargs)

Update user input example.

Update the text of a user input example. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• intent (str) – The intent name.

• text (str) – The text of the user input example.

• new_text (str) – The text of the user input example. This string must conform

to the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 1024 characters. :param list[Mention] new_mentions: An array of contextual entity mentions. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_counterexample(workspace_id, text, **kwargs)

Create counterexample.

Add a new counterexample to a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• text (str) – The text of a user input marked as irrelevant input. This string

must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters - It cannot consist of only whitespace characters - It must be no longer than 1024 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_counterexample(workspace_id, text, **kwargs)

Delete counterexample.

Delete a counterexample from a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• text (str) – The text of a user input counterexample (for example, `What are

you wearing?`). :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

get_counterexample(workspace_id, text, include_audit=None, **kwargs)

Get counterexample.

Get information about a counterexample. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• text (str) – The text of a user input counterexample (for example, `What are

you wearing?`). :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_counterexamples(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List counterexamples.

List the counterexamples for a workspace. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• page_limit (int) – The number of records to return in each page of results.

• include_count (bool) – Whether to include information about the number of

records returned. :param str sort: The attribute by which returned counterexamples will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_counterexample(workspace_id, text, new_text=None, **kwargs)

Update counterexample.

Update the text of a counterexample. Counterexamples are examples that have been marked as irrelevant input. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• text (str) – The text of a user input counterexample (for example, `What are

you wearing?`). :param str new_text: The text of a user input marked as irrelevant input. This string must conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters - It cannot consist of only whitespace characters - It must be no longer than 1024 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_entity(workspace_id, entity, description=None, metadata=None, fuzzy_match=None, values=None, **kwargs)

Create entity.

Create a new entity, or enable a system entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It must be no longer than 64 characters. If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.). :param str description: The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param dict metadata: Any metadata related to the entity. :param bool fuzzy_match: Whether to use fuzzy matching for the entity. :param list[CreateValue] values: An array of objects describing the entity values. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_entity(workspace_id, entity, **kwargs)

Delete entity.

Delete an entity from a workspace, or disable a system entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_entity(workspace_id, entity, export=None, include_audit=None, **kwargs)

Get entity.

Get information about an entity, optionally including all entity content. With export**=`false`, this operation is limited to 6000 requests per 5 minutes. With **export**=`true`, the limit is 200 requests per 30 minutes. For more information, see **Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_entities(workspace_id, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List entities.

List the entities for a workspace. With export**=`false`, this operation is limited to 1000 requests per 30 minutes. With **export**=`true`, the limit is 200 requests per 30 minutes. For more information, see **Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param int page_limit: The number of records to return in each page of results. :param bool include_count: Whether to include information about the number of records returned. :param str sort: The attribute by which returned entities will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_entity(workspace_id, entity, new_entity=None, new_description=None, new_metadata=None, new_fuzzy_match=None, new_values=None, **kwargs)

Update entity.

Update an existing entity with new or modified data. You must provide component objects defining the content of the updated entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• new_entity (str) – The name of the entity. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 64 characters. :param str new_description: The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param dict new_metadata: Any metadata related to the entity. :param bool new_fuzzy_match: Whether to use fuzzy matching for the entity. :param list[CreateValue] new_values: An array of objects describing the entity values. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_mentions(workspace_id, entity, export=None, include_audit=None, **kwargs)

List entity mentions.

List mentions for a contextual entity. An entity mention is an occurrence of a contextual entity in the context of an intent user input example. This operation is limited to 200 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_value(workspace_id, entity, value, metadata=None, value_type=None, synonyms=None, patterns=None, **kwargs)

Create entity value.

Create a new value for an entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param dict metadata: Any metadata related to the entity value. :param str value_type: Specifies the type of entity value. :param list[str] synonyms: An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param list[str] patterns: An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression no longer than 512 characters. For more information about how to specify a pattern, see the [documentation](https://cloud.ibm.com/docs/services/assistant/entities.html#entities-create-dictionary-based). :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_value(workspace_id, entity, value, **kwargs)

Delete entity value.

Delete a value from an entity. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_value(workspace_id, entity, value, export=None, include_audit=None, **kwargs)

Get entity value.

Get information about an entity value. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_values(workspace_id, entity, export=None, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List entity values.

List the values for an entity. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• export (bool) – Whether to include all element content in the returned data.

If **export**=`false`, the returned data includes only information about the element itself. If **export**=`true`, all content, including subelements, is included. :param int page_limit: The number of records to return in each page of results. :param bool include_count: Whether to include information about the number of records returned. :param str sort: The attribute by which returned entity values will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_value(workspace_id, entity, value, new_value=None, new_metadata=None, new_value_type=None, new_synonyms=None, new_patterns=None, **kwargs)

Update entity value.

Update an existing entity value with new or modified data. You must provide component objects defining the content of the updated entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• new_value (str) – The text of the entity value. This string must conform to

the following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param dict new_metadata: Any metadata related to the entity value. :param str new_value_type: Specifies the type of entity value. :param list[str] new_synonyms: An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param list[str] new_patterns: An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression no longer than 512 characters. For more information about how to specify a pattern, see the [documentation](https://cloud.ibm.com/docs/services/assistant/entities.html#entities-create-dictionary-based). :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_synonym(workspace_id, entity, value, synonym, **kwargs)

Create entity value synonym.

Add a new synonym to an entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• synonym (str) – The text of the synonym. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_synonym(workspace_id, entity, value, synonym, **kwargs)

Delete entity value synonym.

Delete a synonym from an entity value. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• synonym (str) – The text of the synonym.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_synonym(workspace_id, entity, value, synonym, include_audit=None, **kwargs)

Get entity value synonym.

Get information about a synonym of an entity value. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• synonym (str) – The text of the synonym.

• include_audit (bool) – Whether to include the audit properties (created and

updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_synonyms(workspace_id, entity, value, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List entity value synonyms.

List the synonyms for an entity value. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• page_limit (int) – The number of records to return in each page of results.

• include_count (bool) – Whether to include information about the number of

records returned. :param str sort: The attribute by which returned entity value synonyms will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_synonym(workspace_id, entity, value, synonym, new_synonym=None, **kwargs)

Update entity value synonym.

Update an existing entity value synonym with new text. This operation is limited to 1000 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• entity (str) – The name of the entity.

• value (str) – The text of the entity value.

• synonym (str) – The text of the synonym.

• new_synonym (str) – The text of the synonym. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

create_dialog_node(workspace_id, dialog_node, description=None, conditions=None, parent=None, previous_sibling=None, output=None, context=None, metadata=None, next_step=None, title=None, node_type=None, event_name=None, variable=None, actions=None, digress_in=None, digress_out=None, digress_out_slots=None, user_label=None, **kwargs)

Create dialog node.

Create a new dialog node. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• dialog_node (str) – The dialog node ID. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters. :param str description: The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param str conditions: The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. :param str parent: The ID of the parent dialog node. This property is omitted if the dialog node has no parent. :param str previous_sibling: The ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling. :param DialogNodeOutput output: The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://cloud.ibm.com/docs/services/assistant/dialog-overview.html#dialog-overview-responses). :param dict context: The context for the dialog node. :param dict metadata: The metadata for the dialog node. :param DialogNodeNextStep next_step: The next step to execute following this dialog node. :param str title: The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters. :param str node_type: How the dialog node is processed. :param str event_name: How an event_handler node is processed. :param str variable: The location in the dialog context where output is stored. :param list[DialogNodeAction] actions: An array of objects describing any actions to be invoked by the dialog node. :param str digress_in: Whether this top-level dialog node can be digressed into. :param str digress_out: Whether this dialog node can be returned to after a digression. :param str digress_out_slots: Whether the user can digress to top-level nodes while filling out slots. :param str user_label: A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_dialog_node(workspace_id, dialog_node, **kwargs)

Delete dialog node.

Delete a dialog node from a workspace. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• dialog_node (str) – The dialog node ID (for example, get_order).

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

get_dialog_node(workspace_id, dialog_node, include_audit=None, **kwargs)

Get dialog node.

Get information about a dialog node. This operation is limited to 6000 requests per 5 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• dialog_node (str) – The dialog node ID (for example, get_order).

• include_audit (bool) – Whether to include the audit properties (created and

updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_dialog_nodes(workspace_id, page_limit=None, include_count=None, sort=None, cursor=None, include_audit=None, **kwargs)

List dialog nodes.

List the dialog nodes for a workspace. This operation is limited to 2500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• page_limit (int) – The number of records to return in each page of results.

• include_count (bool) – Whether to include information about the number of

records returned. :param str sort: The attribute by which returned dialog nodes will be sorted. To reverse the sort order, prefix the value with a minus sign (-). :param str cursor: A token identifying the page of results to retrieve. :param bool include_audit: Whether to include the audit properties (created and updated timestamps) in the response. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

update_dialog_node(workspace_id, dialog_node, new_dialog_node=None, new_description=None, new_conditions=None, new_parent=None, new_previous_sibling=None, new_output=None, new_context=None, new_metadata=None, new_next_step=None, new_title=None, new_node_type=None, new_event_name=None, new_variable=None, new_actions=None, new_digress_in=None, new_digress_out=None, new_digress_out_slots=None, new_user_label=None, **kwargs)

Update dialog node.

Update an existing dialog node with new or modified data. This operation is limited to 500 requests per 30 minutes. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• dialog_node (str) – The dialog node ID (for example, get_order).

• new_dialog_node (str) – The dialog node ID. This string must conform to the

following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters. :param str new_description: The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :param str new_conditions: The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. :param str new_parent: The ID of the parent dialog node. This property is omitted if the dialog node has no parent. :param str new_previous_sibling: The ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling. :param DialogNodeOutput new_output: The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://cloud.ibm.com/docs/services/assistant/dialog-overview.html#dialog-overview-responses). :param dict new_context: The context for the dialog node. :param dict new_metadata: The metadata for the dialog node. :param DialogNodeNextStep new_next_step: The next step to execute following this dialog node. :param str new_title: The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters. :param str new_node_type: How the dialog node is processed. :param str new_event_name: How an event_handler node is processed. :param str new_variable: The location in the dialog context where output is stored. :param list[DialogNodeAction] new_actions: An array of objects describing any actions to be invoked by the dialog node. :param str new_digress_in: Whether this top-level dialog node can be digressed into. :param str new_digress_out: Whether this dialog node can be returned to after a digression. :param str new_digress_out_slots: Whether the user can digress to top-level nodes while filling out slots. :param str new_user_label: A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_all_logs(filter, sort=None, page_limit=None, cursor=None, **kwargs)

List log events in all workspaces.

List the events from the logs of all workspaces in the service instance. If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute. For more information, see Rate limiting.

Parameters

filter (str) – A cacheable parameter that limits the results to those matching

the specified filter. You must specify a filter query that includes a value for language, as well as a value for workspace_id or request.context.metadata.deployment. For more information, see the [documentation](https://cloud.ibm.com/docs/services/assistant/filter-reference.html#filter-reference-syntax). :param str sort: How to sort the returned log events. You can sort by request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-). :param int page_limit: The number of records to return in each page of results. :param str cursor: A token identifying the page of results to retrieve. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

list_logs(workspace_id, sort=None, filter=None, page_limit=None, cursor=None, **kwargs)

List log events in a workspace.

List the events from the log of a specific workspace. If cursor is not specified, this operation is limited to 40 requests per 30 minutes. If cursor is specified, the limit is 120 requests per minute. For more information, see Rate limiting.

Parameters

• workspace_id (str) – Unique identifier of the workspace.

• sort (str) – How to sort the returned log events. You can sort by

request_timestamp. To reverse the sort order, prefix the parameter value with a minus sign (-). :param str filter: A cacheable parameter that limits the results to those matching the specified filter. For more information, see the [documentation](https://cloud.ibm.com/docs/services/assistant/filter-reference.html#filter-reference-syntax). :param int page_limit: The number of records to return in each page of results. :param str cursor: A token identifying the page of results to retrieve. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_user_data(customer_id, **kwargs)

Delete labeled data.

Deletes all data associated with a specified customer ID. The method has no effect if no data is associated with the customer ID. You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes data. For more information about personal data and customer IDs, see [Information security](https://cloud.ibm.com/docs/services/assistant/information-security.html).

Parameters

• customer_id (str) – The customer ID for which all data is to be deleted.

• headers (dict) – A dict containing the request headers

Returns

A DetailedResponse containing the result, headers and HTTP status code.

Return type

DetailedResponse

class CaptureGroup(group, location=None)

Bases: object

A recognized capture group for a pattern-based entity.

Attr str group

A recognized capture group for the entity.

Attr list[int] location

(optional) Zero-based character offsets that indicate where

the entity value begins and ends in the input text.

class Context(conversation_id=None, system=None, metadata=None, **kwargs)

Bases: object

State information for the conversation. To maintain state, include the context from the previous response.

Attr str conversation_id

(optional) The unique identifier of the conversation.

Attr SystemResponse system

(optional) For internal use only.

Attr MessageContextMetadata metadata

(optional) Metadata related to the message.

class Counterexample(text, created=None, updated=None)

Bases: object

Counterexample.

Attr str text

The text of a user input marked as irrelevant input. This string must

conform to the following restrictions: - It cannot contain carriage return, newline, or tab characters - It cannot consist of only whitespace characters - It must be no longer than 1024 characters. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class CounterexampleCollection(counterexamples, pagination)

Bases: object

CounterexampleCollection.

Attr list[Counterexample] counterexamples

An array of objects describing the

examples marked as irrelevant input. :attr Pagination pagination: The pagination data for the returned objects.

class CreateEntity(entity, description=None, metadata=None, fuzzy_match=None, created=None, updated=None, values=None)

Bases: object

CreateEntity.

Attr str entity

The name of the entity. This string must conform to the following

restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It must be no longer than 64 characters. If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.). :attr str description: (optional) The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr dict metadata: (optional) Any metadata related to the entity. :attr bool fuzzy_match: (optional) Whether to use fuzzy matching for the entity. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object. :attr list[CreateValue] values: (optional) An array of objects describing the entity values.

class CreateIntent(intent, description=None, created=None, updated=None, examples=None)

Bases: object

CreateIntent.

Attr str intent

The name of the intent. This string must conform to the following

restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. :attr str description: (optional) The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object. :attr list[Example] examples: (optional) An array of user input examples for the intent.

class CreateValue(value, metadata=None, value_type=None, synonyms=None, patterns=None, created=None, updated=None)

Bases: object

CreateValue.

Attr str value

The text of the entity value. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :attr dict metadata: (optional) Any metadata related to the entity value. :attr str value_type: (optional) Specifies the type of entity value. :attr list[str] synonyms: (optional) An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :attr list[str] patterns: (optional) An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression no longer than 512 characters. For more information about how to specify a pattern, see the [documentation](https://cloud.ibm.com/docs/services/assistant/entities.html#entities-create-dictionary-based). :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class DialogNode(dialog_node, description=None, conditions=None, parent=None, previous_sibling=None, output=None, context=None, metadata=None, next_step=None, title=None, node_type=None, event_name=None, variable=None, actions=None, digress_in=None, digress_out=None, digress_out_slots=None, user_label=None, disabled=None, created=None, updated=None)

Bases: object

DialogNode.

Attr str dialog_node

The dialog node ID. This string must conform to the following

restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 1024 characters. :attr str description: (optional) The description of the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr str conditions: (optional) The condition that will trigger the dialog node. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 2048 characters. :attr str parent: (optional) The ID of the parent dialog node. This property is omitted if the dialog node has no parent. :attr str previous_sibling: (optional) The ID of the previous sibling dialog node. This property is omitted if the dialog node has no previous sibling. :attr DialogNodeOutput output: (optional) The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://cloud.ibm.com/docs/services/assistant/dialog-overview.html#dialog-overview-responses). :attr dict context: (optional) The context for the dialog node. :attr dict metadata: (optional) The metadata for the dialog node. :attr DialogNodeNextStep next_step: (optional) The next step to execute following this dialog node. :attr str title: (optional) The alias used to identify the dialog node. This string must conform to the following restrictions: - It can contain only Unicode alphanumeric, space, underscore, hyphen, and dot characters. - It must be no longer than 64 characters. :attr str node_type: (optional) How the dialog node is processed. :attr str event_name: (optional) How an event_handler node is processed. :attr str variable: (optional) The location in the dialog context where output is stored. :attr list[DialogNodeAction] actions: (optional) An array of objects describing any actions to be invoked by the dialog node. :attr str digress_in: (optional) Whether this top-level dialog node can be digressed into. :attr str digress_out: (optional) Whether this dialog node can be returned to after a digression. :attr str digress_out_slots: (optional) Whether the user can digress to top-level nodes while filling out slots. :attr str user_label: (optional) A label that can be displayed externally to describe the purpose of the node to users. This string must be no longer than 512 characters. :attr bool disabled: (optional) For internal use only. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class DialogNodeAction(name, result_variable, action_type=None, parameters=None, credentials=None)

Bases: object

DialogNodeAction.

Attr str name

The name of the action.

Attr str action_type

(optional) The type of action to invoke.

Attr dict parameters

(optional) A map of key/value pairs to be provided to the

action. :attr str result_variable: The location in the dialog context where the result of the action is stored. :attr str credentials: (optional) The name of the context variable that the client application will use to pass in credentials for the action.

class DialogNodeCollection(dialog_nodes, pagination)

Bases: object

An array of dialog nodes.

Attr list[DialogNode] dialog_nodes

An array of objects describing the dialog nodes

defined for the workspace. :attr Pagination pagination: The pagination data for the returned objects.

class DialogNodeNextStep(behavior, dialog_node=None, selector=None)

Bases: object

The next step to execute following this dialog node.

Attr str behavior

What happens after the dialog node completes. The valid values

depend on the node type: - The following values are valid for any node:

• get_user_input

• skip_user_input

• jump_to

• If the node is of type event_handler and its parent node is of type slot or

frame, additional values are also valid:

• if **event_name**=`filled` and the type of the parent node is slot: - reprompt - skip_all_slots

• if **event_name**=`nomatch` and the type of the parent node is slot:

  • reprompt

  • skip_slot

  • skip_all_slots

• if **event_name**=`generic` and the type of the parent node is frame:

  • reprompt

  • skip_slot

  • skip_all_slots

If you specify jump_to, then you must also specify a value for the dialog_node property. :attr str dialog_node: (optional) The ID of the dialog node to process next. This parameter is required if **behavior**=`jump_to`. :attr str selector: (optional) Which part of the dialog node to process next.

class DialogNodeOutput(generic=None, modifiers=None, **kwargs)

Bases: object

The output of the dialog node. For more information about how to specify dialog node output, see the [documentation](https://cloud.ibm.com/docs/services/assistant/dialog-overview.html#dialog-overview-responses).

Attr list[DialogNodeOutputGeneric] generic

(optional) An array of objects describing

the output defined for the dialog node. :attr DialogNodeOutputModifiers modifiers: (optional) Options that modify how specified output is handled.

class DialogNodeOutputGeneric(response_type, values=None, selection_policy=None, delimiter=None, time=None, typing=None, source=None, title=None, description=None, preference=None, options=None, message_to_human_agent=None)

Bases: object

DialogNodeOutputGeneric.

Attr str response_type

The type of response returned by the dialog node. The

specified response type must be supported by the client application or channel. :attr list[DialogNodeOutputTextValuesElement] values: (optional) A list of one or more objects defining text responses. Required when **response_type**=`text`. :attr str selection_policy: (optional) How a response is selected from the list, if more than one response is specified. Valid only when **response_type**=`text`. :attr str delimiter: (optional) The delimiter to use as a separator between responses when selection_policy`=`multiline. :attr int time: (optional) How long to pause, in milliseconds. The valid values are from 0 to 10000. Valid only when **response_type**=`pause`. :attr bool typing: (optional) Whether to send a “user is typing” event during the pause. Ignored if the channel does not support this event. Valid only when **response_type**=`pause`. :attr str source: (optional) The URL of the image. Required when **response_type**=`image`. :attr str title: (optional) An optional title to show before the response. Valid only when **response_type**=`image` or option. This string must be no longer than 512 characters. :attr str description: (optional) An optional description to show with the response. Valid only when **response_type**=`image` or option. This string must be no longer than 256 characters. :attr str preference: (optional) The preferred type of control to display, if supported by the channel. Valid only when **response_type**=`option`. :attr list[DialogNodeOutputOptionsElement] options: (optional) An array of objects describing the options from which the user can choose. You can include up to 20 options. Required when **response_type**=`option`. :attr str message_to_human_agent: (optional) An optional message to be sent to the human agent who will be taking over the conversation. Valid only when **reponse_type**=`connect_to_agent`. This string must be no longer than 256 characters.

class DialogNodeOutputModifiers(overwrite=None)

Bases: object

Options that modify how specified output is handled.

Attr bool overwrite

(optional) Whether values in the output will overwrite output

values in an array specified by previously executed dialog nodes. If this option is set to false, new values will be appended to previously specified values.

class DialogNodeOutputOptionsElement(label, value)

Bases: object

DialogNodeOutputOptionsElement.

Attr str label

The user-facing label for the option.

Attr DialogNodeOutputOptionsElementValue value

An object defining the message input

to be sent to the Watson Assistant service if the user selects the corresponding option.

class DialogNodeOutputOptionsElementValue(input=None)

Bases: object

An object defining the message input to be sent to the Watson Assistant service if the user selects the corresponding option.

Attr MessageInput input

(optional) An input object that includes the input text.

class DialogNodeOutputTextValuesElement(text=None)

Bases: object

DialogNodeOutputTextValuesElement.

Attr str text

(optional) The text of a response. This string can include newline

characters (n), Markdown tagging, or other special characters, if supported by the channel. It must be no longer than 4096 characters.

class DialogNodeVisitedDetails(dialog_node=None, title=None, conditions=None)

Bases: object

DialogNodeVisitedDetails.

Attr str dialog_node

(optional) A dialog node that was triggered during processing

of the input message. :attr str title: (optional) The title of the dialog node. :attr str conditions: (optional) The conditions that trigger the dialog node.

class DialogRuntimeResponseGeneric(response_type, text=None, time=None, typing=None, source=None, title=None, description=None, preference=None, options=None, message_to_human_agent=None, topic=None, dialog_node=None, suggestions=None)

Bases: object

DialogRuntimeResponseGeneric.

Attr str response_type

The type of response returned by the dialog node. The

specified response type must be supported by the client application or channel. Note: The suggestion response type is part of the disambiguation feature, which is only available for Premium users. :attr str text: (optional) The text of the response. :attr int time: (optional) How long to pause, in milliseconds. :attr bool typing: (optional) Whether to send a “user is typing” event during the pause. :attr str source: (optional) The URL of the image. :attr str title: (optional) The title or introductory text to show before the response. :attr str description: (optional) The description to show with the the response. :attr str preference: (optional) The preferred type of control to display. :attr list[DialogNodeOutputOptionsElement] options: (optional) An array of objects describing the options from which the user can choose. :attr str message_to_human_agent: (optional) A message to be sent to the human agent who will be taking over the conversation. :attr str topic: (optional) A label identifying the topic of the conversation, derived from the user_label property of the relevant node. :attr str dialog_node: (optional) The ID of the dialog node that the topic property is taken from. The topic property is populated using the value of the dialog node’s user_label property. :attr list[DialogSuggestion] suggestions: (optional) An array of objects describing the possible matching dialog nodes from which the user can choose. Note: The suggestions property is part of the disambiguation feature, which is only available for Premium users.

class DialogSuggestion(label, value, output=None, dialog_node=None)

Bases: object

DialogSuggestion.

Attr str label

The user-facing label for the disambiguation option. This label is

taken from the user_label property of the corresponding dialog node. :attr DialogSuggestionValue value: An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option. :attr dict output: (optional) The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option. :attr str dialog_node: (optional) The ID of the dialog node that the label property is taken from. The label property is populated using the value of the dialog node’s user_label property.

class DialogSuggestionValue(input=None, intents=None, entities=None)

Bases: object

An object defining the message input, intents, and entities to be sent to the Watson Assistant service if the user selects the corresponding disambiguation option.

Attr MessageInput input

(optional) An input object that includes the input text.

Attr list[RuntimeIntent] intents

(optional) An array of intents to be sent along

with the user input. :attr list[RuntimeEntity] entities: (optional) An array of entities to be sent along with the user input.

class Entity(entity, description=None, metadata=None, fuzzy_match=None, created=None, updated=None, values=None)

Bases: object

Entity.

Attr str entity

The name of the entity. This string must conform to the following

restrictions: - It can contain only Unicode alphanumeric, underscore, and hyphen characters. - It must be no longer than 64 characters. If you specify an entity name beginning with the reserved prefix sys-, it must be the name of a system entity that you want to enable. (Any entity content specified with the request is ignored.). :attr str description: (optional) The description of the entity. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr dict metadata: (optional) Any metadata related to the entity. :attr bool fuzzy_match: (optional) Whether to use fuzzy matching for the entity. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object. :attr list[Value] values: (optional) An array of objects describing the entity values.

class EntityCollection(entities, pagination)

Bases: object

An array of objects describing the entities for the workspace.

Attr list[Entity] entities

An array of objects describing the entities defined for

the workspace. :attr Pagination pagination: The pagination data for the returned objects.

class EntityMention(text, intent, location)

Bases: object

An object describing a contextual entity mention.

Attr str text

The text of the user input example.

Attr str intent

The name of the intent.

Attr list[int] location

An array of zero-based character offsets that indicate where

the entity mentions begin and end in the input text.

class EntityMentionCollection(examples, pagination)

Bases: object

EntityMentionCollection.

Attr list[EntityMention] examples

An array of objects describing the entity mentions

defined for an entity. :attr Pagination pagination: The pagination data for the returned objects.

class Example(text, mentions=None, created=None, updated=None)

Bases: object

Example.

Attr str text

The text of a user input example. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 1024 characters. :attr list[Mention] mentions: (optional) An array of contextual entity mentions. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class ExampleCollection(examples, pagination)

Bases: object

ExampleCollection.

Attr list[Example] examples

An array of objects describing the examples defined for

the intent. :attr Pagination pagination: The pagination data for the returned objects.

class Intent(intent, description=None, created=None, updated=None, examples=None)

Bases: object

Intent.

Attr str intent

The name of the intent. This string must conform to the following

restrictions: - It can contain only Unicode alphanumeric, underscore, hyphen, and dot characters. - It cannot begin with the reserved prefix sys-. - It must be no longer than 128 characters. :attr str description: (optional) The description of the intent. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object. :attr list[Example] examples: (optional) An array of user input examples for the intent.

class IntentCollection(intents, pagination)

Bases: object

IntentCollection.

Attr list[Intent] intents

An array of objects describing the intents defined for the

workspace. :attr Pagination pagination: The pagination data for the returned objects.

class Log(request, response, log_id, request_timestamp, response_timestamp, workspace_id, language)

Bases: object

Log.

Attr MessageRequest request

A request sent to the workspace, including the user

input and context. :attr MessageResponse response: The response sent by the workspace, including the output text, detected intents and entities, and context. :attr str log_id: A unique identifier for the logged event. :attr str request_timestamp: The timestamp for receipt of the message. :attr str response_timestamp: The timestamp for the system response to the message. :attr str workspace_id: The unique identifier of the workspace where the request was made. :attr str language: The language of the workspace where the message request was made.

class LogCollection(logs, pagination)

Bases: object

LogCollection.

Attr list[Log] logs

An array of objects describing log events.

Attr LogPagination pagination

The pagination data for the returned objects.

class LogMessage(level, msg, **kwargs)

Bases: object

Log message details.

Attr str level

The severity of the log message.

Attr str msg

The text of the log message.

class LogPagination(next_url=None, matched=None, next_cursor=None)

Bases: object

The pagination data for the returned objects.

Attr str next_url

(optional) The URL that will return the next page of results, if

any. :attr int matched: (optional) Reserved for future use. :attr str next_cursor: (optional) A token identifying the next page of results.

class Mention(entity, location)

Bases: object

A mention of a contextual entity.

Attr str entity

The name of the entity.

Attr list[int] location

An array of zero-based character offsets that indicate where

the entity mentions begin and end in the input text.

class MessageContextMetadata(deployment=None, user_id=None)

Bases: object

Metadata related to the message.

Attr str deployment

(optional) A label identifying the deployment environment, used

for filtering log data. This string cannot contain carriage return, newline, or tab characters. :attr str user_id: (optional) A string value that identifies the user who is interacting with the workspace. The client must provide a unique identifier for each individual end user who accesses the application. For Plus and Premium plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters.

class MessageInput(text=None, **kwargs)

Bases: object

An input object that includes the input text.

Attr str text

(optional) The text of the user input. This string cannot contain

carriage return, newline, or tab characters, and it must be no longer than 2048 characters.

class MessageRequest(input=None, intents=None, entities=None, alternate_intents=None, context=None, output=None, actions=None)

Bases: object

A request sent to the workspace, including the user input and context.

Attr MessageInput input

(optional) An input object that includes the input text.

Attr list[RuntimeIntent] intents

(optional) Intents to use when evaluating the user

input. Include intents from the previous response to continue using those intents rather than trying to recognize intents in the new input. :attr list[RuntimeEntity] entities: (optional) Entities to use when evaluating the message. Include entities from the previous response to continue using those entities rather than detecting entities in the new input. :attr bool alternate_intents: (optional) Whether to return more than one intent. A value of true indicates that all matching intents are returned. :attr Context context: (optional) State information for the conversation. To maintain state, include the context from the previous response. :attr OutputData output: (optional) An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log. :attr list[DialogNodeAction] actions: (optional) An array of objects describing any actions requested by the dialog node.

class MessageResponse(input, intents, entities, context, output, alternate_intents=None, actions=None)

Bases: object

The response sent by the workspace, including the output text, detected intents and entities, and context.

Attr MessageInput input

An input object that includes the input text.

Attr list[RuntimeIntent] intents

An array of intents recognized in the user input,

sorted in descending order of confidence. :attr list[RuntimeEntity] entities: An array of entities identified in the user input. :attr bool alternate_intents: (optional) Whether to return more than one intent. A value of true indicates that all matching intents are returned. :attr Context context: State information for the conversation. To maintain state, include the context from the previous response. :attr OutputData output: An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log. :attr list[DialogNodeAction] actions: (optional) An array of objects describing any actions requested by the dialog node.

class OutputData(log_messages, text, generic=None, nodes_visited=None, nodes_visited_details=None, **kwargs)

Bases: object

An output object that includes the response to the user, the dialog nodes that were triggered, and messages from the log.

Attr list[LogMessage] log_messages

An array of up to 50 messages logged with the

request. :attr list[str] text: An array of responses to the user. :attr list[DialogRuntimeResponseGeneric] generic: (optional) Output intended for any channel. It is the responsibility of the client application to implement the supported response types. :attr list[str] nodes_visited: (optional) An array of the nodes that were triggered to create the response, in the order in which they were visited. This information is useful for debugging and for tracing the path taken through the node tree. :attr list[DialogNodeVisitedDetails] nodes_visited_details: (optional) An array of objects containing detailed diagnostic information about the nodes that were triggered during processing of the input message. Included only if nodes_visited_details is set to true in the message request.

class Pagination(refresh_url, next_url=None, total=None, matched=None, refresh_cursor=None, next_cursor=None)

Bases: object

The pagination data for the returned objects.

Attr str refresh_url

The URL that will return the same page of results.

Attr str next_url

(optional) The URL that will return the next page of results.

Attr int total

(optional) Reserved for future use.

Attr int matched

(optional) Reserved for future use.

Attr str refresh_cursor

(optional) A token identifying the current page of results.

Attr str next_cursor

(optional) A token identifying the next page of results.

class RuntimeEntity(entity, location, value, confidence=None, metadata=None, groups=None, **kwargs)

Bases: object

A term from the request that was identified as an entity.

Attr str entity

An entity detected in the input.

Attr list[int] location

An array of zero-based character offsets that indicate where

the detected entity values begin and end in the input text. :attr str value: The term in the input text that was recognized as an entity value. :attr float confidence: (optional) A decimal percentage that represents Watson’s confidence in the entity. :attr dict metadata: (optional) Any metadata for the entity. :attr list[CaptureGroup] groups: (optional) The recognized capture groups for the entity, as defined by the entity pattern.

class RuntimeIntent(intent, confidence, **kwargs)

Bases: object

An intent identified in the user input.

Attr str intent

The name of the recognized intent.

Attr float confidence

A decimal percentage that represents Watson’s confidence in

the intent.

class Synonym(synonym, created=None, updated=None)

Bases: object

Synonym.

Attr str synonym

The text of the synonym. This string must conform to the following

restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class SynonymCollection(synonyms, pagination)

Bases: object

SynonymCollection.

Attr list[Synonym] synonyms

An array of synonyms.

Attr Pagination pagination

The pagination data for the returned objects.

class SystemResponse(**kwargs)

Bases: object

For internal use only.

class Value(value, value_type, metadata=None, synonyms=None, patterns=None, created=None, updated=None)

Bases: object

Value.

Attr str value

The text of the entity value. This string must conform to the

following restrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :attr dict metadata: (optional) Any metadata related to the entity value. :attr str value_type: Specifies the type of entity value. :attr list[str] synonyms: (optional) An array of synonyms for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A synonym must conform to the following resrictions: - It cannot contain carriage return, newline, or tab characters. - It cannot consist of only whitespace characters. - It must be no longer than 64 characters. :attr list[str] patterns: (optional) An array of patterns for the entity value. A value can specify either synonyms or patterns (depending on the value type), but not both. A pattern is a regular expression no longer than 512 characters. For more information about how to specify a pattern, see the [documentation](https://cloud.ibm.com/docs/services/assistant/entities.html#entities-create-dictionary-based). :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object.

class ValueCollection(values, pagination)

Bases: object

ValueCollection.

Attr list[Value] values

An array of entity values.

Attr Pagination pagination

The pagination data for the returned objects.

class Workspace(name, language, learning_opt_out, workspace_id, description=None, metadata=None, system_settings=None, status=None, created=None, updated=None, intents=None, entities=None, dialog_nodes=None, counterexamples=None)

Bases: object

Workspace.

Attr str name

The name of the workspace. This string cannot contain carriage return,

newline, or tab characters, and it must be no longer than 64 characters. :attr str description: (optional) The description of the workspace. This string cannot contain carriage return, newline, or tab characters, and it must be no longer than 128 characters. :attr str language: The language of the workspace. :attr dict metadata: (optional) Any metadata related to the workspace. :attr bool learning_opt_out: Whether training data from the workspace (including artifacts such as intents and entities) can be used by IBM for general service improvements. true indicates that workspace training data is not to be used. :attr WorkspaceSystemSettings system_settings: (optional) Global settings for the workspace. :attr str workspace_id: The workspace ID of the workspace. :attr str status: (optional) The current status of the workspace. :attr datetime created: (optional) The timestamp for creation of the object. :attr datetime updated: (optional) The timestamp for the most recent update to the object. :attr list[Intent] intents: (optional) An array of intents. :attr list[Entity] entities: (optional) An array of objects describing the entities for the workspace. :attr list[DialogNode] dialog_nodes: (optional) An array of objects describing the dialog nodes in the workspace. :attr list[Counterexample] counterexamples: (optional) An array of counterexamples.

class WorkspaceCollection(workspaces, pagination)

Bases: object

WorkspaceCollection.

Attr list[Workspace] workspaces

An array of objects describing the workspaces

associated with the service instance. :attr Pagination pagination: The pagination data for the returned objects.

class WorkspaceSystemSettings(tooling=None, disambiguation=None, human_agent_assist=None)

Bases: object

Global settings for the workspace.

Attr WorkspaceSystemSettingsTooling tooling

(optional) Workspace settings related to

the Watson Assistant tool. :attr WorkspaceSystemSettingsDisambiguation disambiguation: (optional) Workspace settings related to the disambiguation feature. Note: This feature is available only to Premium users. :attr dict human_agent_assist: (optional) For internal use only.

class WorkspaceSystemSettingsDisambiguation(prompt=None, none_of_the_above_prompt=None, enabled=None, sensitivity=None)

Bases: object

Workspace settings related to the disambiguation feature. Note: This feature is available only to Premium users.

Attr str prompt

(optional) The text of the introductory prompt that accompanies

disambiguation options presented to the user. :attr str none_of_the_above_prompt: (optional) The user-facing label for the option users can select if none of the suggested options is correct. If no value is specified for this property, this option does not appear. :attr bool enabled: (optional) Whether the disambiguation feature is enabled for the workspace. :attr str sensitivity: (optional) The sensitivity of the disambiguation feature to intent detection conflicts. Set to high if you want the disambiguation feature to be triggered more often. This can be useful for testing or demonstration purposes.

class WorkspaceSystemSettingsTooling(store_generic_responses=None)

Bases: object

Workspace settings related to the Watson Assistant tool.

Attr bool store_generic_responses

(optional) Whether the dialog JSON editor displays

text responses within the output.generic object.