Aura –

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Configuration of the generic-dialog for TV display use case

How the generic-dialog must be configured for this use case

Specific configuration

The TV display use case is triggered by the generic-dialog-v3. For this use case, the required specific configuration is set below:

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "triggerConditions": [
        {
            "intent": "intent.tv.display",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.needTvResolution	true	Get resolution from resolution API

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

TV display plugin

Complex Logic Framework plugin for the TV display use case

Introduction

The TV display plugin resolves the request from a user displaying a channel or content.

It includes some key steps described in the following sections.

Validate input request

This step validates that the input request fulfills all the requirements from the input schema.

If the input data has an error, the resource returned is:
tv:video.model-validation.request.error.

Display channel or content

The display channel or content is based in the received entities.

The display stage follows the steps set below:

Build the `search_query` param

The display plugin builds a search_query param using label values of entities to prioritize the searched channel content or video content. If the label value is null for an entity, then the canon value is used.

Entities used to search are grouped by:

Channel entities: ent.audiovisual_channel
Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshow_title
Participant entities: ent.audiovisual_actor and ent.audiovisual_director
Genre entities: ent.audiovisual_genre and ent.audiovisual_subgenre

The priority to search using these entities is described as follows:

If there are channel entities and other entities, then the search_query parameter is built only using the first channel entity.
- For instance: channel_name: "La 1"
If there are title entities and other entities, then the search_query parameter is built only using title entities.
- For instance: title: ("Matrix" OR "La princesa prometida")
If there are participant entities and other entities, then the search_query parameter is built only using participant entities.
- All entities (ent.audiovisual_actor and ent.audiovisual_director) are used for fields actor and director.
- For instance: actor: ("Tom Cruise" OR "Martin Scorsese") OR director: ("Tom Cruise" OR "Martin Scorsese")
If there are genre entities and other entities, then the search_query parameter is built only using genre entities.
- The ent.audiovisual_genre is used with the field content_category and the ent.audiovisual_subgenre with field genre.
- For instance: content_category: ("MOV" OR "SER" OR "DOC") AND genre: ("Terror" OR "Acción")
If there are not any entities allowed, then a query param to search is not built.

With this prioritization, the system builds a search_query param that will be used to call the API video query for searching purposes.

Video query API

After preparing the search_query parameter, we will make a query to Video Contents normalized Kernel API by searching through all the possible fields with the remaining words.

To make this API call, several parameters are needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: use LIVE value if there are channel entities, else use VOD,LIVE,L7D value for title entities, participant entities or genre entities.
search_query: String with a custom search query based in the received entities.
show_series: series.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
commercial_offer: Input data[app_context][user][profile] if exists. Otherwise, do not use this param.
live_at: if there are channel entities use UTC current time at which the request is made. Otherwise, do not use this param.
profile: Input data[app_context][user][video_profile_name] if exists. Otherwise, do not use this param.
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

The fields current_region and profile may not be implemented in certain cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send these fields only when input data has this value.

Display response

When a user requests for displaying a channel, the following possible scenarios can occur for the response:

a. Receive no results at all. Then, it executes the contingency search.

b. Receive content with channel info. The returned resource is tv:video.display.by-channel.single-result

c. Receive content with channel info has already been broadcast or recieve a video content. The returned resource is video.display.by-default.single-result

d. Receive content with channel info that has not been broadcast yet or the content does not have enough information to be played. The returned resource is video.display.by-default.detail-result

e. Receive more than one type of content with channel info or video content. The returned resource is tv:video.display.by-default.multiple-results

f. Receive an API error. The returned resource is tv:video.api.answer.error

Contingency search

The contingency search is a more in-depth search to get, at least, one response. This search uses the entire utterance in every search field.

Contingency search is based on the following steps:

Normalization section

When a request is made by the user, it is possible to find certain words with no real value for Aura, so the system is not able to redirect them to obtain a response. For this reason, a list of forbidden words known as “ignore-words” will be declared, which will be eliminated.

The first step is to transform the entire utterance received as input to lowercase, removing all non-alphanumeric characters and separators. Once the utterance has been normalized, the words that belong to the list of “ignore-words” are eliminated.

This list is declared in a resource file called normalizer_rules.json. This file can be found in the following path: src.aura_clf_video.resources.[language].normalizer_rules.json Where [language] must be replaced by each language, for example: es-es.

If the language does not have the normalizer rule defined, it will be redirected to a default folder: src.aura_clf_video.resources.default.normalizer_rules.json

If, for example, the language is Spanish, the path to the resource where the normalization rules are defined will be: src.aura_clf_video.resources.es-es.normalizer_rules.json

Normalizer rules structure It is a dictionary where all the items are declared in a list as shown below:
```
{
  "ignore_items": [
    "ignore item 1",
    "ignore item 2"
  ]
}
```
Validation of resource content
The normalization is done sequentially, a previous rule cannot affect a succeeding one.

For example:
- The utterance is “ok aura some”.
- We define “aura” and also “ok aura” in the “ignore-words” list.
- If we remove “aura” firstly from the original utterance, we obtain the following normalized utterance: “ok some”. In this case, “ok aura” does not have any effect.
- In short, the correct order should be: first, remove “ok aura” and, after that, remove “aura”. In this case, we will obtain the final utterance as “some”.

“Ignore-words” will be automatically validated in order to prevent this behavior in every Pull Request.

If after normalization the normalized phrase is empty, the resource returned is: tv:video.display.contingency.no-results

API video query

After normalizing, we will query the Telefonica Kernel video API by searching through all possible fields with the remaining words.

To make this API call, a series of parameters are going to be needed, which are described below:

user_id: Input data[aura_user][user_id]
administrative_number: Input data[app_context][user][account_number]
access_token: Input data[aura_user][access_token]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]
catalog_types: List that is made by VOD, LIVE and L7D.
search_query: Is a joint of the normalized phrase by OR operator. Use this format to search by any fields. Example: “La resistencia Shameless” the search_query is “(La OR resistencia OR Shameless)”.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field may not be implemented in some cases and this could give the error 501 Not Implemented in the video API according to the documentation. To prevent this problem, we should send this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]
order: personal
current_region: Input data[app_context][location][currentRegion] if exists. Otherwise, do not use this param.

Contingency search response

When performing a contingency search, there are four possible scenarios for the response received by the search:

a. Receive an API error. The returned resource is tv:video.api.answer.error

b. Receive no results at all. The returned resource is tv:video.display.contingency.no-results

c. Receive a single result. The returned resource is tv:video.display.contingency.single-result

d. Receive several results. The returned resource is tv:video.display.contingency.multiple-results

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH except when the resource is:
- video.display.by-channel.single-result, then the field value is CHANNEL.PLAY
- video.display.by-default.single-result, then the field value is CONTENT.PLAY
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:video.display.by-channel.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the display request. If we receive a response, this field includes the following parameters:
- type: The value of this field depends on the type of data included in the field data (info returned by the API):
  - If it is a value: details
  - If it is a list: content_list
- data: It returns the information provided by the Kernel API.
status: Final status request. This field includes the following parameters:
- code: Status code.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.
actions: Actions to follow with the result of request. This plugin could include the following actions:
- REMOTEON.ZAPTO: The target for this action is stb and its parameters are:
  - channelId, channelNumber and deviceId when we have the resource tv:video.display.by-channel.single-result
- REMOTEON.PLAYTO: The target for this action is stb and its parameters are:
  - contentId, deviceId, liveProgramId and catalogType when we have the resource video.display.by-default.single-result and content has already been broadcast.
  - contentId, deviceId and catalogType when we have the resource video.display.by-default.single-result and content is a video content.
- MAKE_SOUND: The target for this action is channel and its unique parameter is sound with the value:
  - positive when we have the resource tv:video.display.by-channel.single-result, video.display.by-default.single-result, video.display.by-default.detail-result, tv:video.display.by-default.multiple-results, tv:video.display.contingency.single-result, tv:video.display.contingency.multiple-results
  - negative when we have the resource tv:video.display.contingency.no-results and tv:video.api.answer.error.
conditions: Condition for the actions to be applied.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

TV display use case resources

Resources used by the TV display use case

Introduction

The TV display use case will use three different types of resources:

Specific resources for the use case: tv.display

The resources associated to the TV display plugin are defined below:

Specific resources for tv.display use case	Definition	Example	Managed by	Scope
`video.display.by-channel.single-result`	Resource returned when the search finds one channel and is broadcasting	Esto es lo que están emitiendo ahora en ese canal	tv.display plugin	Use case-specific
`video.display.by-default.single-result`	Resource returned when the search finds one channel content has already been broadcast or finds a video content	Voy a ello, dame un segundo	tv.display plugin	Use case-specific
`video.display.by-default.detail-result`	Resource returned when the search finds one channel content or video content that has not been broadcast yet, or the content does not have enough information to be played	Mira, he encontrado este contenido	tv.display plugin	Use case-specific
`tv:video.display.by-default.multiple-results`	Resource returned when the search finds more than one channel content or content on demand	He encontrado estos contenidos relacionados con tu petición	tv.display plugin	Use case-specific
`tv:video.display.contingency.single-result`	Resource returned when the contingency search finds one result	He encontrado este contenido relacionado	tv.display plugin	Use case-specific
`tv:video.display.contingency.multiple-results`	Resource returned when the contingency search finds more than one result	He encontrado estos contenidos relacionados	tv.display plugin	Use case-specific
`tv:video.display.contingency.no-results`	Resource returned when the contingency search does not find any result	Lo siento, no encuentro lo que dices	tv.display plugin	Use case-specific

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

NLP configuration by OB

NLP configuration by OB for the TV display use case

Introduction

The current document includes the configuration of the NLP model for the normalized TV display use case in the OBs where it is available.

Brazil

The aura-nlpdata repository structure in Brazil is organized by channel: aura-nlpdata-br-[channel]. Each repository will contain the files for the available use cases in this channel.

The following configuration corresponds to the STB channel, which is included in the repository: https://github.com/Telefonica/aura-nlpdata-br-stb

Intent

intent.tv.display

Entities

| ent.audiovisual_channel | “Quiero ver La 1” |

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

CluRecognizerWrapper
PygrapeGrammarWrapper
EntityTaggerAdapterWrapper

The whole pipeline.jsonfile is available at: https://github.com/Telefonica/aura-nlpdata-br-stb/blob/master/data/pt-br/stb/pipeline.json

Spain

The TV display use case is available for three channels: Movistar Plus, Movistar Home and STB.

Intent

intent.tv.display

Entities

Pipeline stages

The following stages of STB’s pipeline have been used to develop this UC:

CluRecognizerWrapper
PygrapeGrammarWrapper
EntityTaggerAdapterWrapper

The whole pipeline.json files can be checked here for each channel:

Aura –

Docs:

Configuration of the generic-dialog for TV display use case

Specific configuration

Specific values

Docs:

TV display plugin

Introduction

Validate input request

Display channel or content

Build the search_query param

Video query API

Display response

Contingency search

Normalization section

API video query

Contingency search response

Response

Docs:

TV display use case resources

Introduction

Specific resources for the use case: tv.display

Docs:

NLP configuration by OB

Introduction

Brazil

Intent

Entities

Pipeline stages

Spain

Intent

Entities

Pipeline stages

Build the `search_query` param