vania-janet/multiturn-rag-retrieval-data huggingface dataset:
Rules for creating custom prompts and speaker models 

The Tune by Example feature is beta functionality that is supported only for US English custom models and voices.

The service enforces the following rules for custom prompts and speakers models. Among the rules are guidelines for making the most effective use of the feature.



 Rules for creating custom prompts 

The following rules apply to the identifier, text, and audio that you provide when adding a custom prompt to a custom model.



 Rules for prompt identifiers 

For the identifier of a prompt:



* Include a maximum of 49 characters.
* Include only alphanumeric characters and _ (underscores).
* Do not include XML sensitive characters (double quotes, single quotes, ampersands, angle brackets, and slashes).
* To add a new prompt, the ID must be unique for the specified custom model. Otherwise, the information for the prompt overwrites the existing prompt that has that ID.







 Rules for prompt text 

For the written text of a prompt:



* Write the text of a prompt as you would normally, with commas and sentence-ending punctuation. However, Tune by Example bases the prosody and intonation of the prompt on the prompt audio, not on the punctuation of the prompt text as it does for regular speech synthesis. Only the spoken audio impacts the prosody of the synthesized prompt.
* A prompt cannot contain more than 1000 characters of text. Speaking one or two sentences of text is the recommended limit.
* A prompt can include only fixed, static text. It cannot include variable data, which is data that changes for different uses of the prompt. For example, "Your account balance is $500" contains variable data: namely, "$500," which is a variable value that changes depending on a user's account balance. In this case, the prompt needs to speak "Your account balance is," and a second synthesis request needs to say the balance.
* Escape XML sensitive characters (double quotes, single quotes, ampersands, angle brackets, and slashes) that appear in the text of a prompt by applying the same rules that you use to provide text for a synthesis request.
Service prompts the user to choose from a list of dialog options, including Cancel an account, Cancel a product order, and None of the above.Service prompts the user to choose from a list of dialog options_ including Cancel an account_ Cancel a product order_ and None of the above_.] Service prompts the user to choose from a list of dialog options, including Capture date information.Service prompts the user to choose from a list of dialog options_ including Capture date information_.] ! ! ! ! !
{"intent":"Customer_Care_Cancel_Account","confidence":0.5602024316787719},
{"intent":"eCommerce_Cancel_Product_Order","confidence":0.46903514862060547},
{"intent":"Customer_Care_Appointments","confidence":0.29033891558647157},
{"intent":"General_Greetings","confidence":0.2894785046577454},
In fact, if you test from the Try it out pane, you can hover over the eye icon to see the top three intents that were recognized in the test input.!]Your assistant is 0.5618281841278076 (56%) confident that the user goal matches the Customer_Care_Cancel_Account intent. If another intent has a confidence score that is close to the score of this top intent, then disambiguation is triggered. In this example, the eCommerce_Cancel_Product_Order intent has a close confidence score of 46%.As a result, when the user input is i must cancel it today, both dialog nodes are likely to be considered viable candidates to respond. To determine which dialog node to process, the assistant asks the user to pick one. And to help the user choose between them, the assistant provides a short summary of what each node does. The summary text is extracted directly from the external node name information that is specified for each node.!
They are NOT unique per environment or collection.
* A customer_id cannot be more than 256 characters in length.
* If a customer_id contains only whitespace or is empty, it is treated as though the customer_id was not provided at all, and no error messages are returned.





 Labeling data with the Discovery tooling 

Data can be labeled with the customer_id field, when you use the Discovery tooling. Click the ![Environment details](https://cloud.ibm.com/docs-content/v1/content/ded4adc3ea0bd2a81b113c579f2b1183926da211/discovery/images/env_icon.png) and enter the customer_id in the GDPR Data Label field. After this field is set, all data uploaded using this browser session is labeled with the specified customer_id. If the associated customer ID changes, change this field.

Adding a customer_id with the GDPR Data Label field labels the documents, notices, and training data within that URL domain from that point forward, including each instance under that domain. Any actions, including document uploads, that occurred in the Discovery tooling before adding the GDPR Data Label field are not labeled.

If you switch domains or browsers, empty the browser cache, or start an incognito session after you specify your customer_id using the GDPR Data Label field of the Discovery tooling, the customer_id is not retained, and your data is not labeled. If you must switch domains or browsers, re-enter the customer_id in the GDPR Data Label field.







 Deleting labeled data 

To delete it later, data must be labeled with a customer_id.



1. Use the DELETE /v1/user_data operation and provide the customer_id of the data you wish to delete. DELETE /v1/user_data deletes all data associated with a particular customer_id within that service instance, as specified in [Methods that support labeling data](https://cloud.ibm.com/docs/discovery?topic=discovery-information-securitypi_methods).
For more information, see [Special conditions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-overviewdialog-overview-special-conditions).



 Setting initial context 

If you need to set initial context variables at the beginning of each conversation, make sure you do so in a way that works with all of the integrations you plan to use. Do not use the Welcome node to set initial context variables unless you are certain your dialog will only be accessed in situations where the welcome special condition is triggered.

A safer and more consistent approach is to always set any initial context in a node defined using the conversation_start special condition, which is always triggered. You can use this node in addition to a Welcome node that displays a greeting.

To manage the start of any conversation regardless of integration, follow these steps:



1. Add a dialog node above the Welcome node that is automatically added to the top of the dialog tree when you create the dialog.
2. Set the node condition for this newly added node to conversation_start. This node will be reliably triggered at the beginning of any conversation.
3. In the conversation_start node, define any default values for context variables, and call any webhooks you need to call at the beginning of every conversation.
4. Do not define a text response for this node. Instead, configure this node to jump to the Welcome node directly below it in the dialog tree (or whichever other node you want to process first), and choose If assistant recognizes (condition).



![Screenshot of the dialog tree with a conversation_start node jumping to a welcome node below it.](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/dialog-start.png)

This design results in a dialog that works like this:



* Whatever the integration type, the conversation_start node is processed, which means any context variables that you define in it are initialized.
* The service might fail to detect a mismatch between the prompt’s text and audio. This problem is more likely to occur with longer prompts. Multiple shorter prompts are preferable to a single long prompt.
* The text of a prompt might include a word that the service does not recognize. In this case, you can add a custom word/translation pair to the prompt's custom model to tell the service how to pronounce the word. For more information, see [Adding a single word to a custom model](https://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-customWordscuWordAdd).
* The quality of the input audio might be insufficient or the service’s processing of the audio might fail to detect or reflect the intended prosody. Submitting new audio for the prompt can correct these issues.



If a prompt that is created without a speaker ID does not adequately reflect the intended prosody, enrolling the speaker and providing a speaker ID for the prompt is one recommended means of potentially improving the quality of the prompt. This is especially important for shorter prompts such as "good-bye" or "thank you," where less audio data makes it more difficult for the service to match the prosody of the speaker.
For example, for entity ContactInfo, the patterns for phone, email, and website values can be defined as follows:



* Phone



* localPhone: (d{3})-(d{4}), e.g. 426-4968
* fullUSphone: (d{3})-(d{3})-(d{4}), e.g. 800-426-4968
* internationalPhone: ^((?+?[0-9])?)?[0-9_- ()]$, e.g., +44 1962 815000



* email: b[A-Za-z0-9._%+-]+@([A-Za-z0-9-]+.)+[A-Za-z]{2,}b, e.g. [name@ibm.com](mailto:name@ibm.com)
* website: (https?://)?([da-z.-]+).([a-z.]{2,6})([/w .-])/?$, e.g. [https://www.ibm.com](https://www.ibm.com)



3. Click Add value and repeat the process to add more entity values.



When you use pattern entities to find patterns in user input, you often need a way to store the part of the user input text that matches the pattern. To do so, you can use a context variable. For more information, see [Defining a context variable](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-dialog-runtime-contextdialog-runtime-context-var-define).

For example, your dialog might ask users for their email addresses. The dialog node condition will contain a condition similar to @contactInfo:email. You can use the following syntax in the dialog node's response section to define a context variable that captures and stores the user's email address text:



Saving a pattern

 Variable Value 

 email <?
For more information about the pricing updates, see



* The Speech to Text service in the [IBM Cloud Catalog](https://cloud.ibm.com/catalog/services/speech-to-text)
* The [Pricing FAQs](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-faq-pricing)



Empty body no longer required for HTTP POST requests
: You no longer need to pass an empty data object as the body for the following POST requests:



* POST /v1/sessions
* POST /v1/register_callback
* POST /v1/customizations/{customization_id}/train
* POST /v1/customizations/{customization_id}/reset
* POST /v1/customizations/{customization_id}/upgrade_model



For example, you now call the POST /v1/sessions method with curl as follows:

curl -X POST -u "{username}:{password}" --cookie-jar cookies.txt "{url}/v1/sessions"

You no longer need to pass the following curl option with the request: --data "{}". If you experience any problems with one of these POST requests, try passing an empty data object with the body of the request. Passing an empty object does not change the nature or meaning of the request in any way.





 22 May 2017 

The continuous parameter removed from all methods
: The continuous parameter is removed from all methods that initiate recognition requests. The service now transcribes an entire audio stream until it ends or times out, whichever occurs first. This behavior is equivalent to setting the former continuous parameter to true. By default, the service previously stopped transcription at the first half-second of non-speech (typically silence) if the parameter was omitted or set to false.

Existing applications that set the parameter to true will see no change in behavior. Applications that set the parameter to false or that relied on the default behavior will likely see a change. If a request specifies the parameter, the service now responds by returning a warning message for the unknown parameter:

"warnings": [
"prompt": "Hello and welcome",
"prompt_id": "greeting",
"status": "available",
"speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
},
{
"prompt": "How can I help you today?",
"prompt_id": "help",
"status": "processing",
"speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
},
{
"prompt": "I am sorry to hear that.",
"prompt_id": "sorry",
"status": "available",
"speaker_id": "323e4476-63de-9825-7cd7-8120e45f8331"
}
]
}
Show more





 List a specific custom prompt example 

The following example returns information about just the first custom prompt from the previous listing:

IBM Cloud

curl -X GET -u "apikey:{apikey}" "{url}/v1/customizations/{customization_id}/prompts/greeting"

IBM Cloud Pak for Data

curl -X GET --header "Authorization: Bearer {token}" "{url}/v1/customizations/{customization_id}/prompts/greeting"

The response duplicates the information from the previous example:

{
"prompt": "Hello and welcome!",
"prompt_id": "greeting",
"status": "available",
"speaker_id": "56367f89-546d-4b37-891e-4eb0c13cc833"
}







 Deleting a custom prompt 

To delete a custom prompt from a custom model, use the DELETE /v1/customizations/{customization_id}/prompts/{prompt_id} method.
Building a conversational flow 

The dialog defines what your assistant says in response to customers.



 Creating a dialog 

To create a dialog, complete the following steps:



1. Click the Dialog tab, and then click Create dialog.

When you open the dialog editor for the first time, the following nodes are created for you:



* Welcome: The first node. It contains a greeting that is displayed to your users when they first engage with your assistant. You can edit the greeting.



This node is not triggered in dialog flows that are initiated by users. For example, dialogs that are deployed in environments such as messaging channels where customers start the conversation do not process nodes with the welcome special condition.



* Anything else: The final node. It contains phrases that are used to reply to users when their input is not recognized. You can replace the responses that are provided or add more responses with a similar meaning to add variety to the conversation. You can also choose whether you want your assistant to return each response that is defined in turn or return them in random order.



2. To add more nodes to the dialog tree, click the More![More icon](https://cloud.ibm.com/docs-content/v1/content/a2b18c153837bce00a5b4de496e4b4ca64bbf56e/assistant-data/images/kabob.png) icon on the Welcome node, and then select Add node below.
3. In the If assistant recognizes field, enter a condition that, when met, triggers your assistant to process the node.

To start off, you typically want to add an intent as the condition. For example, if you add open_account here, it means that you want the response that you will specify in this node to be returned to the user if the user input indicates that the user wants to open an account.

As you begin to define a condition, a box is displayed that shows you your options. You can enter one of the following characters, and then pick a value from the list of options that is displayed.



Condition builder syntax

 Character Lists defined values for these artifact types 

 `#` intents
This documentation is for the classic Watson Assistant experience. To see the documentation for the new Watson Assistant, please go [here](https://cloud.ibm.com/docs/watson-assistant).



 Controlling the conversational flow 

Understand how your dialog is processed when a person interacts with your assistant at run time. Learn to use the conversation flow to your advantage and alter the flow if necessary.

You can impact the flow of a conversation with the following features:



* [Disambiguation](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-runtimedialog-runtime-disambiguation)
* [Digressions](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-runtimedialog-runtime-digressions)





 Disambiguation 

Disambiguation instructs your assistant to ask the customer for help when more than one dialog node can respond to a customer's input. Instead of guessing which node to process, your assistant shares a list of the top node options with the user, and asks the user to pick the right one.

![Shows a sample conversation between a user and the assistant, where the assistant asks for clarification from the user.](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/disambig-demo.png)

Disambiguation is triggered when the following conditions are met:



* The confidence scores of the runner-up intents that are detected in the user input are close in value to the confidence score of the top intent.
* The confidence score of the top intent is above 0.2.



Even when these conditions are met, disambiguation does not occur unless two or more independent nodes in your dialog meet the following criteria:



* The node condition includes one of the intents that triggered disambiguation.
* A description of the node's purpose is provided for the node in the node name field.
After you identify the list of steps, you can then focus on writing engaging content to turn each interaction into a positive experience for your customer.

![Diagram of a simple exchange between a customer and an actions skill step.](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/action-skill-explained.png)





 Dialog skill 

A dialog skill contains the training data and logic that enables an assistant to help your customers. It contains the following types of artifacts:



* [Intents](https://cloud.ibm.com/docs/assistant?topic=assistant-intents): An intent represents the purpose of a user's input, such as a question about business locations or a bill payment. You define an intent for each type of user request you want your application to support. The name of an intent is always prefixed with the character. To train the dialog skill to recognize your intents, you supply lots of examples of user input and indicate which intents they map to.

A content catalog is provided that contains prebuilt common intents you can add to your application rather than building your own. For example, most applications require a greeting intent that starts a dialog with the user. You can add the General content catalog to add an intent that greets the user and does other useful things, like end the conversation.
* [Dialog](https://cloud.ibm.com/docs/assistant?topic=assistant-dialog-build): A dialog is a branching conversation flow that defines how your application responds when it recognizes the defined intents and entities. You use the dialog editor to create conversations with users, providing responses based on the intents and entities that you recognize in their input.

![Diagram of a basic implementation that uses intent and dialog only.]
Message A single turn within a conversation that includes a single call to the /message API endpoint and its corresponding response. 
 Monthly active user (MAU) A single unique user who interacts with an assistant one or many times in a given month. 
 Preview link An integration that builds embeds your assistant in a chat window that is displayed on an IBM-branded web page. From the preview link integration, you can test how a conversation flows through any and all skills that are attached to your assistant, from end to end. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-deploy-web-link). 
 Response Logic that is defined in the Assistant responds section of a dialog node that determines how the assistant responds to the user. When the node's condition evaluates to true, the response is processed. The response can consist of an answer, a follow-up question, a webhook that sends a programmatic request to an external service, or slots which represent pieces of information that you need the user to provide before the assistant can help. The dialog node response is equivalent to a Then statement in If-Then-Else programming logic. 
 Skill Does the work of the assistant. A dialog skill has the training data and dialog that your assistant uses to chat with customers. An actions skill is a new way to build a conversation. Actions offers step-by-step flows for a range of simple or complex conversations and is made so that anybody can build. A search skill is configured to search the appropriate external data sources for answers to customer inquiries. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-skill-add). 
 Skill version Versions are snapshots of a skill that you can create at key points during the development lifecycle. You can deploy one version to production, while you continue to make and test improvements that you make to another version of the skill. [Learn more](https://cloud.ibm.com/docs/assistant-data?topic=assistant-data-versions).
[Diagram of a more complex implementation that uses intent, entity, and dialog.](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/complex-impl.png)

As you add information, the skill uses this unique data to build a machine learning model that can recognize these and similar user inputs. Each time you add or change the training data, the training process is triggered to ensure that the underlying model stays up-to-date as your customer needs and the topics they want to discuss change.





 Search skill ![Plus or higher plans only](https://cloud.ibm.com/docs-content/v1/content/417db917d18067d9dcc4cf2612564a9a87c3ddc8/assistant/images/plus.png) 

When Watson Assistant doesn't have an explicit solution to a problem, it routes the user question to a search skill to find an answer from across your disparate sources of self-service content. The search skill interacts with the IBM Watson® Discovery service to extract this information from a configured data collection.

If you already use the Discovery service, you can mine your existing data collections for source material that you can share with customers to address their questions.

However, you do not need to have a Discovery service instance. If you choose to create a search skill, a free instance of Discovery is provisioned for you. You can then create a collection from a data source and configure your search skill to search this collection for answers to customer queries.

The following diagram illustrates how user input is processed when both a dialog skill and a search skill are added to an assistant. Any questions that the dialog is not designed to answer are sent to the search skill, which finds a relevant response from a Discovery data collection.

![Diagram of how a question gets routed to the search skill.]