watson_developer_cloud.assistant_v2 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 AssistantV2(version, url='https://gateway.watsonplatform.net/assistant/api', username=None, password=None, iam_apikey=None, iam_access_token=None, iam_url=None)

Bases: watson_developer_cloud.watson_service.WatsonService

The Assistant V2 service.

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

create_session(assistant_id, **kwargs)

Create a session.

Create a new session. A session is used to send user input to a skill and receive responses. It also maintains the state of the conversation.

Parameters:assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). Note: Currently, the v2 API does not support creating assistants. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

delete_session(assistant_id, session_id, **kwargs)

Delete session.

Deletes a session explicitly before it times out.

Parameters:assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). Note: Currently, the v2 API does not support creating assistants. :param str session_id: Unique identifier of the session. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

message(assistant_id, session_id, input=None, context=None, **kwargs)

Send user input to assistant.

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

Parameters:assistant_id (str) – Unique identifier of the assistant. You can find the

assistant ID of an assistant on the Assistants tab of the Watson Assistant tool. For information about creating assistants, see the [documentation](https://console.bluemix.net/docs/services/assistant/create-assistant.html#creating-assistants). Note: Currently, the v2 API does not support creating assistants. :param str session_id: Unique identifier of the session. :param MessageInput input: An input object that includes the input text. :param MessageContext context: State information for the conversation. :param dict headers: A dict containing the request headers :return: A DetailedResponse containing the result, headers and HTTP status code. :rtype: DetailedResponse

class CaptureGroup(group, location=None)

Bases: object

CaptureGroup.

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 DialogLogMessage(level, message)

Bases: object

Dialog log message details.

Attr str level:The severity of the log message. Attr str message:  The text of the log message.

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 object 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 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 assistant if the user selects the corresponding option.

class DialogNodeOutputOptionsElementValue(input=None)

Bases: object

An object defining the message input to be sent to the assistant if the user selects the corresponding option.

Attr MessageInput input:  (optional) The user input.

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

Bases: object

DialogNodesVisited.

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, 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 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 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)

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 to be sent to the assistant if the user selects the corresponding disambiguation option. :attr object output: (optional) The dialog output that will be returned from the Watson Assistant service if the user selects the corresponding option.

class DialogSuggestionValue(input=None)

Bases: object

An object defining the message input to be sent to the assistant if the user selects the corresponding disambiguation option.

Attr MessageInput input:  (optional) The user input.

class MessageContext(global_=None, skills=None)

Bases: object

State information for the conversation.

Attr MessageContextGlobal globalglobal_:  (optional) Contains information that can be shared

by all skills within the Assistant. :attr MessageContextSkills skills: (optional) Contains information specific to particular skills within the Assistant.

class MessageContextGlobal(system=None)

Bases: object

Contains information that can be shared by all skills within the Assistant.

Attr MessageContextGlobalSystem system:  (optional) Properties interpreted by the

Assistant that are shared across all skills within the Assistant.

class MessageContextGlobalSystem(timezone=None, user_id=None, turn_count=None)

Bases: object

Properties that are shared by all skills used by the assistant.

Attr str timezone:  (optional) The user time zone. The assistant uses the time zone to

correctly resolve relative time references. :attr str user_id: (optional) A string value that identifies the user who is interacting with the assistant. The client must provide a unique identifier for each individual end user who accesses the application. This user ID may be used for billing and other purposes. :attr int turn_count: (optional) A counter that is automatically incremented with each turn of the conversation. A value of 1 indicates that this is the the first turn of a new conversation, which can affect the behavior of some skills.

class MessageContextSkills(**kwargs)

Bases: object

Contains information specific to particular skills within the Assistant.

class MessageInput(message_type=None, text=None, options=None, intents=None, entities=None, suggestion_id=None)

Bases: object

The user input.

Attr str message_type:  (optional) The type of user input. Currently, only text input

is supported. :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. :attr MessageInputOptions options: (optional) Properties that control how the assistant responds. :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 str suggestion_id: (optional) For internal use only.

class MessageInputOptions(debug=None, restart=None, alternate_intents=None, return_context=None)

Bases: object

Optional properties that control how the assistant responds.

Attr bool debug:  (optional) Whether to return additional diagnostic information. Set

to true to return additional information under the output.debug key. :attr bool restart: (optional) Whether to start a new conversation with this user input. Specify true to clear the state information stored by the session. :attr bool alternate_intents: (optional) Whether to return more than one intent. Set to true to return all matching intents. :attr bool return_context: (optional) Whether to return session context with the response. If you specify true, the response will include the context property.

class MessageOutput(generic=None, intents=None, entities=None, actions=None, debug=None)

Bases: object

Assistant output to be rendered or processed by the client.

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[RuntimeIntent] intents: (optional) An array of intents recognized in the user input, sorted in descending order of confidence. :attr list[RuntimeEntity] entities: (optional) An array of entities identified in the user input. :attr list[DialogNodeAction] actions: (optional) An array of objects describing any actions requested by the dialog node. :attr MessageOutputDebug debug: (optional) Additional detailed information about a message response and how it was generated.

class MessageOutputDebug(nodes_visited=None, log_messages=None, branch_exited=None, branch_exited_reason=None)

Bases: object

Additional detailed information about a message response and how it was generated.

Attr list[DialogNodesVisited] nodes_visited:  (optional) An array of objects

containing detailed diagnostic information about the nodes that were triggered during processing of the input message. :attr list[DialogLogMessage] log_messages: (optional) An array of up to 50 messages logged with the request. :attr bool branch_exited: (optional) Assistant sets this to true when this message response concludes or interrupts a dialog. :attr str branch_exited_reason: (optional) When branch_exited is set to true by the Assistant, the branch_exited_reason specifies whether the dialog completed by itself or got interrupted.

class MessageResponse(output, context=None)

Bases: object

A response from the Watson Assistant service.

Attr MessageOutput output:  Assistant output to be rendered or processed by the

client. :attr MessageContext context: (optional) The current session context. Included in the response if the return_context property of the message input was set to true.

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

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 object 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)

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 SessionResponse(session_id)

Bases: object

SessionResponse.

Attr str session_id:  The session ID.