Class: IBMWatson::AssistantV2

Inherits:
IBMCloudSdkCore::BaseService
  • Object
show all
Includes:
Concurrent::Async
Defined in:
lib/ibm_watson/assistant_v2.rb

Overview

The Assistant V2 service.

Constant Summary collapse

DEFAULT_SERVICE_NAME = 
"assistant"
DEFAULT_SERVICE_URL = 
"https://api.us-south.assistant.watson.cloud.ibm.com"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(args) ⇒ AssistantV2

Construct a new client for the Assistant service.

Parameters:

  • args (Hash) —

    The args to initialize with

Options Hash (args):

  • version (String) —

    Release date of the API version you want to use. Specify dates in YYYY-MM-DD format. The current version is ‘2021-06-14`.

  • service_url (String) —

    The base service URL to use when contacting the service. The base service_url may differ between IBM Cloud regions.

  • authenticator (Object) —

    The Authenticator instance to be configured for this service.

  • service_name (String) —

    The name of the service to configure. Will be used as the key to load any external configuration, if applicable.

Raises:

  • (ArgumentError) 


52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/ibm_watson/assistant_v2.rb', line 52

def initialize(args = {})
  @__async_initialized__ = false
  defaults = {}
  defaults[:service_url] = DEFAULT_SERVICE_URL
  defaults[:service_name] = DEFAULT_SERVICE_NAME
  defaults[:authenticator] = nil
  defaults[:version] = nil
  user_service_url = args[:service_url] unless args[:service_url].nil?
  args = defaults.merge(args)
  @version = args[:version]
  raise ArgumentError.new("version must be provided") if @version.nil?

  args[:authenticator] = IBMCloudSdkCore::ConfigBasedAuthenticatorFactory.new.get_authenticator(service_name: args[:service_name]) if args[:authenticator].nil?
  super
  @service_url = user_service_url unless user_service_url.nil?
end

Instance Attribute Details

#version ⇒ Object

Returns the value of attribute version.



39
40
41
 
# File 'lib/ibm_watson/assistant_v2.rb', line 39

def version
  @version
end

Instance Method Details

#bulk_classify(skill_id: , input: nil) ⇒ IBMCloudSdkCore::DetailedResponse

Identify intents and entities in multiple user utterances. Send multiple user inputs to a dialog skill in a single request and receive

information about the intents and entities recognized in each input. This method
is useful for testing and comparing the performance of different skills or skill
versions.

This method is available only with Enterprise with Data Isolation plans.

Parameters:

  • skill_id (String) (defaults to: ) —

    Unique identifier of the skill. To find the skill ID in the Watson Assistant user interface, open the skill settings and click **API Details**.

  • input (Array[BulkClassifyUtterance]) (defaults to: nil) —

    An array of input utterances to classify.

Returns:

  • (IBMCloudSdkCore::DetailedResponse) —

    A ‘IBMCloudSdkCore::DetailedResponse` object representing the response.

Raises:

  • (ArgumentError) 


304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
 
# File 'lib/ibm_watson/assistant_v2.rb', line 304

def bulk_classify(skill_id:, input: nil)
  raise ArgumentError.new("skill_id must be provided") if skill_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "bulk_classify")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input
  }

  method_url = "/v2/skills/%s/workspace/bulk_classify" % [ERB::Util.url_encode(skill_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end

#create_session(assistant_id: ) ⇒ IBMCloudSdkCore::DetailedResponse

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. A session persists
until it is deleted, or until it times out because of inactivity. (For more
information, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-settings).

Parameters:

  • assistant_id (String) (defaults to: ) —

    Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click **API Details**. For information about creating assistants, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

    Note: Currently, the v2 API does not support creating assistants.

Returns:

  • (IBMCloudSdkCore::DetailedResponse) —

    A ‘IBMCloudSdkCore::DetailedResponse` object representing the response.

Raises:

  • (ArgumentError) 


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/ibm_watson/assistant_v2.rb', line 88

def create_session(assistant_id:)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "create_session")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  method_url = "/v2/assistants/%s/sessions" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  response
end

#delete_session(assistant_id: , session_id: ) ⇒ nil

Delete session. Deletes a session explicitly before it times out. (For more information about the

session inactivity timeout, see the
[documentation](https://cloud.ibm.com/docs/assistant?topic=assistant-assistant-settings)).

Parameters:

  • assistant_id (String) (defaults to: ) —

    Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click **API Details**. For information about creating assistants, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

    Note: Currently, the v2 API does not support creating assistants.

  • session_id (String) (defaults to: ) —

    Unique identifier of the session.

Returns:

  • (nil)

Raises:

  • (ArgumentError) 


128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/ibm_watson/assistant_v2.rb', line 128

def delete_session(assistant_id:, session_id:)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  raise ArgumentError.new("session_id must be provided") if session_id.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "delete_session")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  method_url = "/v2/assistants/%s/sessions/%s" % [ERB::Util.url_encode(assistant_id), ERB::Util.url_encode(session_id)]

  request(
    method: "DELETE",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  nil
end

#delete_user_data(customer_id: ) ⇒ nil

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/assistant?topic=assistant-information-security#information-security).

**Note:** This operation is intended only for deleting data associated with a
single specific customer, not for deleting data associated with multiple customers
or for any other purpose. For more information, see [Labeling and deleting data in
Watson
Assistant](https://cloud.ibm.com/docs/assistant?topic=assistant-information-security#information-security-gdpr-wa).

Parameters:

  • customer_id (String) (defaults to: ) —

    The customer ID for which all data is to be deleted.

Returns:

  • (nil)

Raises:

  • (ArgumentError) 


409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
 
# File 'lib/ibm_watson/assistant_v2.rb', line 409

def delete_user_data(customer_id:)
  raise ArgumentError.new("version must be provided") if version.nil?

  raise ArgumentError.new("customer_id must be provided") if customer_id.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "delete_user_data")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version,
    "customer_id" => customer_id
  }

  method_url = "/v2/user_data"

  request(
    method: "DELETE",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  nil
end

#list_logs(assistant_id: , sort: nil, filter: nil, page_limit: nil, cursor: nil) ⇒ IBMCloudSdkCore::DetailedResponse

List log events for an assistant. List the events from the log of an assistant.

This method requires Manager access, and is available only with Enterprise plans.

Parameters:

  • assistant_id (String) (defaults to: ) —

    Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click **API Details**. For information about creating assistants, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

    Note: Currently, the v2 API does not support creating assistants.

  • sort (String) (defaults to: nil) —

    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 (‘-`).

  • filter (String) (defaults to: nil) —

    A cacheable parameter that limits the results to those matching the specified filter. For more information, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-filter-reference#filter-reference).

  • page_limit (Fixnum) (defaults to: nil) —

    The number of records to return in each page of results.

  • cursor (String) (defaults to: nil) —

    A token identifying the page of results to retrieve.

Returns:

  • (IBMCloudSdkCore::DetailedResponse) —

    A ‘IBMCloudSdkCore::DetailedResponse` object representing the response.

Raises:

  • (ArgumentError) 


358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/ibm_watson/assistant_v2.rb', line 358

def list_logs(assistant_id:, sort: nil, filter: nil, page_limit: nil, cursor: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "list_logs")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version,
    "sort" => sort,
    "filter" => filter,
    "page_limit" => page_limit,
    "cursor" => cursor
  }

  method_url = "/v2/assistants/%s/logs" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "GET",
    url: method_url,
    headers: headers,
    params: params,
    accept_json: true
  )
  response
end

#message(assistant_id: , session_id: , input: nil, context: nil, user_id: nil) ⇒ IBMCloudSdkCore::DetailedResponse

Send user input to assistant (stateful). Send user input to an assistant and receive a response, with conversation state

(including context data) stored by Watson Assistant for the duration of the
session.

Parameters:

  • assistant_id (String) (defaults to: ) —

    Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click **API Details**. For information about creating assistants, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

    Note: Currently, the v2 API does not support creating assistants.

  • session_id (String) (defaults to: ) —

    Unique identifier of the session.

  • input (MessageInput) (defaults to: nil) —

    An input object that includes the input text.

  • context (MessageContext) (defaults to: nil) —

    Context data for the conversation. You can use this property to set or modify context variables, which can also be accessed by dialog nodes. The context is stored by the assistant on a per-session basis.

    Note: The total size of the context data stored for a stateful session cannot exceed 100KB.

  • user_id (String) (defaults to: nil) —

    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. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.global.session_id.

    Note: This property is the same as the user_id property in the global system context. If user_id is specified in both locations, the value specified at the root is used.

Returns:

  • (IBMCloudSdkCore::DetailedResponse) —

    A ‘IBMCloudSdkCore::DetailedResponse` object representing the response.

Raises:

  • (ArgumentError) 


190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
 
# File 'lib/ibm_watson/assistant_v2.rb', line 190

def message(assistant_id:, session_id:, input: nil, context: nil, user_id: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("session_id must be provided") if session_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "message")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input,
    "context" => context,
    "user_id" => user_id
  }

  method_url = "/v2/assistants/%s/sessions/%s/message" % [ERB::Util.url_encode(assistant_id), ERB::Util.url_encode(session_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end

#message_stateless(assistant_id: , input: nil, context: nil, user_id: nil) ⇒ IBMCloudSdkCore::DetailedResponse

Send user input to assistant (stateless). Send user input to an assistant and receive a response, with conversation state

(including context data) managed by your application.

Parameters:

  • assistant_id (String) (defaults to: ) —

    Unique identifier of the assistant. To find the assistant ID in the Watson Assistant user interface, open the assistant settings and click **API Details**. For information about creating assistants, see the [documentation](cloud.ibm.com/docs/assistant?topic=assistant-assistant-add#assistant-add-task).

    Note: Currently, the v2 API does not support creating assistants.

  • input (MessageInputStateless) (defaults to: nil) —

    An input object that includes the input text.

  • context (MessageContextStateless) (defaults to: nil) —

    Context data for the conversation. You can use this property to set or modify context variables, which can also be accessed by dialog nodes. The context is not stored by the assistant. To maintain session state, include the context from the previous response.

    Note: The total size of the context data for a stateless session cannot exceed 250KB.

  • user_id (String) (defaults to: nil) —

    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. For user-based plans, this user ID is used to identify unique users for billing purposes. This string cannot contain carriage return, newline, or tab characters. If no value is specified in the input, user_id is automatically set to the value of context.global.session_id.

    Note: This property is the same as the user_id property in the global system context. If user_id is specified in both locations in a message request, the value specified at the root is used.

Returns:

  • (IBMCloudSdkCore::DetailedResponse) —

    A ‘IBMCloudSdkCore::DetailedResponse` object representing the response.

Raises:

  • (ArgumentError) 


255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
 
# File 'lib/ibm_watson/assistant_v2.rb', line 255

def message_stateless(assistant_id:, input: nil, context: nil, user_id: nil)
  raise ArgumentError.new("assistant_id must be provided") if assistant_id.nil?

  raise ArgumentError.new("version must be provided") if version.nil?

  headers = {
  }
  sdk_headers = Common.new.get_sdk_headers("conversation", "V2", "message_stateless")
  headers.merge!(sdk_headers)

  params = {
    "version" => @version
  }

  data = {
    "input" => input,
    "context" => context,
    "user_id" => user_id
  }

  method_url = "/v2/assistants/%s/message" % [ERB::Util.url_encode(assistant_id)]

  response = request(
    method: "POST",
    url: method_url,
    headers: headers,
    params: params,
    json: data,
    accept_json: true
  )
  response
end