This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

TV search use case

1: Dialog configuration
2: TV search plugin
3: TV search resources
4: NLP configuration by OB

TV search use case

Global use case developed by Aura Platform Team that allows users to search specific TV content in Aura

Introduction

The TV search use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura for TV content using a vocal interface.

Find additional information in following the documents:

Discover the TV search specifications and the particularities of the use case development.
Learn how to configure the generic-dialog for TV search use case.
Access to the TV search plugin.
Discover which are the resources used by the TV search use case.
Find out the NLP configuration for each OB for the TV search use case.

Specifications

Kernel API

In order to resolve the user’s search request, Aura uses Video Contents normalized Kernel API.

Request-response model

TV search use case is adapted to the new request-response normalized model v3.

Available channels

Once TV search v3 use case is fully normalized, it will be available for any channel that implements normalized v3 request-response model including TV related data.

Search features

Currently, the normalized TV search use case includes basic search features and smart answers for entertainment content:

Search by title
Search by genre (movie, series, documentaries, programs, short films and games)
Search by subgenre (action, scare, love, etc)
Search by actor or director

In addition to these search features, the use case includes a contingency or fallback search mode used in case the Video Contents API does not provide any answer to Aura request. The contingency or fallback search mode could be deactivated by configuration.

🆕 As a novelty in the current release, the use case is able to provide the users with smart answers features, meaning that the entities included in the user’s requests can be included in the answer.

Therefore, the answer could be of this type: “That’s what I’ve found about [$title, $participant, $genre, $subgenre]

For example:

The user asks for a specific title: “Play a film starring Brad Pitt”
In previous versions, Aura sends the content provided by the API as “That’s what I’ve found for you”
Now, the entity can be included in the answer, giving the user a most personalized answer: “That’s what I’ve found about Brad Pitt”

Current limitations

Currently, the TV search use case does not include these features:

Request for a specific season o episode of a TV Series.
Search content from third-parties (content must belong to Aura’s catalog).
Search including temporary entities or time intervals.
Search sport content based on entities.

Use case development

The TV search use case development includes these components:

Understanding features

TV search use case intent: intent.tv.search
TV search use case entities:

Entity	Example
`ent.audiovisual_film_title`	“Busca La princesa prometida”
`ent.audiovisual_documental_title`	“Busca ABBA Forever”
`ent.audiovisual_tvshow_title`	“Busca Late Motiv”
`ent.audiovisual_tvseries_title`	“Busca Hierro”
`ent.audiovisual_subgenre`	“Busca una comedia”
`ent.audiovisual_genre`	“Busca una película”
`ent.audiovisual_actor`	“Busca algo de Brad Pitt”
`ent.audiovisual_director`	“Busca algo de Almodóvar”

⚠️ Other entities in the user’s request are not taken into account in the searching process.

In order to understand users’ requests (utterances), Aura is trained with:

NLP expression to recognize the user’s utterance and detect her intention.
TV catalog in order to understand TV content (titles, actors, director) in the user’s utterance and detect them as Aura entities.
Other content like genre or subgenre.

Use case logic

Once Aura has recognized the user’s utterance based on NLP components, the use case should be resolved based on:

Aura Bot dialog:

TV search is built over the generic-dialog-v3.
- Check the section Configuration of the generic-dialog for TV search use case in order to know the required configuration for the TV search experience.
CLF Plugin:

Complex Logic Framework is used for the recognition of the user’s request.
- Check here the TV search plugin.

1 - Dialog configuration

Configuration of the generic-dialog for TV search use case

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

Specific configuration

The TV search 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.search",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Specific values

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

2 - TV search plugin

TV search plugin

Complex Logic Framework plugin for the TV search use case

Introduction

The TV search plugin resolves the request from a user searching a video 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.

Filter invalid entities

The TV search plugin executes the step for entities validation listed below and prepares data before resolving the request:

Check that season/episode entity contains a number. In other case, it removes this entity.

Entertainment Search

The search of video content is based in the received entities.

The search stage follows the following steps:

Build the `search_query` param

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

Entities used to search are grouped by:

Title entities: ent.audiovisual_documental_title, ent.audiovisual_film_title, ent.audiovisual_tvseries_title and ent.audiovisual_tvshows_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 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: ("TE" OR "AC")
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.

API video query

After preparing the search_query parameter, we will make a query to the Telefonica Kernel video 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: List of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
search_query: String with a custom search query based in the received entities.
show_series: series.
profile: Input data[app_context][user][video_profile_name]. This field 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 this field only when input data has this value.
commercialization_types: List made by SVOD.
max_quality: Input data[app_context][device][max_quality]

Search response

When performing a search, the following possible scenarios can occur 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. Then, it executes the contingency search if it isn’t disabled by configuration. If it is disabled by configuration, the returned resource is tv:video.search.no-results.

c. Receive a single result by searching for one title entity. The returned resource is tv:video.search.by-title.simple-result and params with the value of the title searched for.

d. Receive several results by searching for one title entity. The returned resource is tv:video.search.by-title.multiple-results and params with the value of the title searched for.

e. Receive a single result by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.simple-result and params with the value of the participant searched for.

f. Receive several results by searching for one actor/director entity. The returned resource is tv:video.search.by-participant.multiple-results and params with the value of the participant searched for.

g. Receive a single result by searching for one genre entity. The returned resource is tv:video.search.by-genre.simple-result and params with the value of the genre searched for.

h. Receive several results by searching for one genre entity. The returned resource is tv:video.search.by-genre.multiple-results and params with the value of the genre searched for.

i. Receive a single result by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.simple-result and params with the value of the genre and subgenre searched for.

j. Receive several results by searching for one genre and one subgenre entity. The returned resource is tv:video.search.by-subgenre.multiple-results and params with the value of the genre and subgenre searched for.

k. Receive a single result in all other cases. The returned resource is tv:video.search.by-default.simple-result.

l. Receive several results in all other cases. The returned resource is tv:video.search.by-default.multiple-results.

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.search.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 of allowed catalog types. The value can now be a list of catalog types provided by the device, as long as the values are one of the following predefined identifiers: VOD, LIVE, L7D, LCH, LSR.
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]
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.search.contingency.no-results

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

d. Receive several results. The returned resource is tv:video.search.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 because it is the response associated to this domain.
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.search.contingency.single-result
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the search 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 field 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.
conditions: Condition for the actions to be applied.

3 - TV search resources

TV search use case resources

Resources used by the TV search use case

Introduction

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

Specific resources for the use case: tv.search

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

Specific resources for tv.search use case	Definition	Example	Managed by	Scope
`tv:video.search.by-title.simple-result`	Resource returned when the search finds one result by searching for one title entity	He encontrado esto sobre $title	tv.search plugin	Use case-specific
`tv:video.search.by-title.multiple-results`	Resource returned when the search finds more than one result by searching for one title entity	He encontrado estos contenidos sobre $title	tv.search plugin	Use case-specific
`tv:video.search.by-participant.simple-result`	Resource returned when the search finds one result by searching for one actor/director entity	En este contenido participa $participant	tv.search plugin	Use case-specific
`tv:video.search.by-participant.multiple-results`	Resource returned when the search finds more than one result by searching for one actor/director entity	En estos contenidos participa $participant	tv.search plugin	Use case-specific
`tv:video.search.by-genre.simple-result`	Resource returned when the search finds one result by searching for one genre entity	Mira lo que he encontrado sobre $genre	tv.search plugin	Use case-specific
`tv:video.search.by-genre.multiple-results`	Resource returned when the search finds more than one result by searching for one genre entity	Estos son los contenidos que he encontrado sobre $genre	tv.search plugin	Use case-specific
`tv:video.search.by-subgenre.simple-result`	Resource returned when the search finds one result by searching for one genre and one subgenre entity	Mira lo que he encontrado sobre $genre de $subgenre	tv.search plugin	Use case-specific
`tv:video.search.by-subgenre.multiple-results`	Resource returned when the search finds more than one result by searching for one genre and one subgenre entity	Estos son los contenidos que he encontrado sobre $genre de $subgenre	tv.search plugin	Use case-specific
`tv:video.search.by-default.simple-result`	Resource returned when the search finds one result	Aquí tienes este contenido	tv.search plugin	Use case-specific
`tv:video.search.by-default.multiple-results`	Resource returned when the search finds more than one result	Aquí tienes estos contenidos	tv.search plugin	Use case-specific
`tv:video.search.contingency.no-results`	Resource returned when the contingency search does not find any result	No he encontrado nada	tv.search plugin	Use case-specific
`tv:video.search.contingency.single-result`	Resource returned when the contingency search finds one result	Este es el resultado que he encontrado	tv.search plugin	Use case-specific
`tv:video.search.contingency.multiple-results`	Resource returned when the contingency search finds more than one result	Estos son los resultados que he encontrado	tv.search plugin	Use case-specific
`tv:video.search.no-results`	Resource when the contingency search is disabled and does not find any result	No he encontrado lo que dices	tv.search plugin	Use case-specific

4 - NLP configuration by OB

NLP configuration by OB

NLP configuration by OB for the TV search use case

Introduction

The current document includes the configuration of the NLP model for the TV search 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.search

Entities

ent.audiovisual_actor
ent.audiovisual_director
ent.audiovisual_documental_title
ent.audiovisual_film_title
ent.audiovisual_genre
ent.audiovisual_subgenre
ent.audiovisual_tvseries_title
ent.audiovisual_tvshow_title

Pipeline stages

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

CluRecognizerWrapper
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 search use case is available for three channels: Movistar Plus, Movistar Home and STB.

Intent

intent.tv.search

Entities

ent.audiovisual_actor
ent.audiovisual_best
ent.audiovisual_director
ent.audiovisual_documental_title
ent.audiovisual_film_title
ent.audiovisual_genre
ent.audiovisual_most_watched
ent.audiovisual_releases
ent.audiovisual_sports
ent.audiovisual_sports_circuit
ent.audiovisual_sports_player_driver
ent.audiovisual_sports_player_rider
ent.audiovisual_sports_season
ent.audiovisual_sports_season_motor
ent.audiovisual_sports_team
ent.audiovisual_sports_unit
ent.audiovisual_subgenre
ent.audiovisual_tv_episode_number
ent.audiovisual_tv_season_number
ent.audiovisual_tvseries_title
ent.audiovisual_tvshow_title
ent.device_mobile
ent.device_tv
ent.time_instant
ent.time_interval
ent.time_interval_future
ent.time_interval_past

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:

TV search use case

TV search use case

Introduction

Specifications

Kernel API

Request-response model

Available channels

Search features

Current limitations

Use case development

Understanding features

Use case logic

1 - Dialog configuration

Configuration of the generic-dialog for TV search use case

Specific configuration

Specific values

2 - TV search plugin

TV search plugin

Introduction

Validate input request

Filter invalid entities

Entertainment Search

Build the search_query param

API video query

Search response

Contingency search

Normalization section

API video query

Contingency search response

Response

3 - TV search resources

TV search use case resources

Introduction

Specific resources for the use case: tv.search

4 - NLP configuration by OB

NLP configuration by OB

Introduction

Brazil

Intent

Entities

Pipeline stages

Spain

Intent

Entities

Pipeline stages

Build the `search_query` param