TV none plugin

Complex Logic Framework plugin for the TV none use case

Introduction

The TV none plugin resolves the request from a user getting information about channel.

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.

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 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.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.

Last modified April 10, 2025: feat: Documentation improvement for Ozzy release #AURA-28512 [RTM] (d141f026)

Tags:

Categories: