Aura – video

Docs:

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

TV LLM Conversational None UC

Global Use Case developed by Aura Platform Team that informs users of the platform’s available actions, ensuring correct invocation for proper system understanding.

Introduction

The video LLM Conversational None use case is a global experience designed and developed by Aura Global Team that provides Telefónica customers guidance on gaining knowledge of available platform actions and how to perform them correctly.

Find additional information in the following documents:

Discover the Conversational None specifications and the particularities of the use case development.
Learn how to configure the conversational-none-dialog for Conversational None use case.
Access the TV Retrieve plugin for LLM None UC.
Discover the resources used by the Conversational None use case.
Find the AI configuration for each OB for the TV LLM Conversational None UC.

Specifications

Request-response model

The TV LLM Conversational None UC is adapted to both request-response V1 and to its normalized model V3.

Available channels

The TV LLM Conversational None UC can be enabled in any channel in both v1 and v3 and TV-related payloads.

Use case development

The TV LLM Conversational None UC includes the following components:

Understanding features

Intent: intent.conversational.none

Use case logic

Once Aura recognizes the user’s utterance, the UC is resolved via:

Aura Bot dialog

TV LLM Conversational None UC is built over conversational-none-dialog.
See the Dialog configuration for the required settings and bypass configuration.

Docs:

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

TV LLM Conversational Search UC

Global use case developed by Aura Platform Team that allows users searching for recommendations by holding a conversation with Aura

Introduction

The video LLM Conversational Search use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to hold a conversation with Aura for having TV content recommendations using a voice interface.

Find additional information in the following documents:

Discover the Conversational search specifications and the particularities of the use case development.
Learn how to configure the conversational-search-dialog for Conversational Search use case.
Access the TV Retrieve plugin for LLM Search UC.
Discover the resources used by the Conversational search use case.
Find the AI configuration for each OB for the TV LLM Conversational Search UC.

Specifications

Kernel API

To resolve the user’s request, Aura uses the normalized Video Contents Kernel API.

Request-response model

The Conversational search use case is adapted to both request-response normalized model v3 and v1.

Available channels

The Conversational search use case can be enabled in any channel in both v1 and v3 and TV-related payloads.

Use case development

The Conversational search use case includes the following components:

Understanding features

Intent: intent.conversational.search

Use case logic

Once Aura recognizes the user’s utterance, the UC is resolved via:

Aura Bot dialog

The Conversational search use case is built over conversational-search-dialog.
See the Dialog configuration for the required settings and bypass configuration.

Docs:

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

Global use case developed by Aura Platform Team that allows users to get personalized TV/video recommendations in Aura

Introduction

The video LLM Recommend use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura for content recommendations (live channels and catalog items) using a voice interface.

Find additional information in the following documents:

Discover the TV LLM Recommend specifications and the particularities of the use case development.
Learn how to configure the generic-dialog for TV LLM Recommend use case.
Access the TV LLM Recommend plugin.
Discover the resources used by the TV LLM Recommend use case.
Find the AI configuration for each OB for the TV Recommend use case.

Specifications

Kernel API

To resolve the user’s request, Aura uses the normalized Video Contents Kernel API.

Request-response model

The TV LLM Recommend UC is available only when using the normalized request-response model v3.

Available channels

The TV LLM Recommend UC can be enabled in any channel implementing the normalized v3 request-response model and TV-related payloads.

The normalized TV LLM Recommend UC includes personalized recommendations:

Suggest a single live channel (with a zap action).
Suggest a single catalog item (e.g., VOD).
Suggest a list of items when multiple results are available.
Return no content when the API returns no results.

Current limitations

Currently, the TV LLM Recommend UC does not include:

Fallback/contingency search (as in TV search).
Filters customized (as persons, genres, participants, …).
Third-party catalogs outside Aura/Kernel scope.

Use case development

The TV LLM Recommend UC includes these components:

Understanding features

Intent: intent.tv.recommend

Use case logic

Once Aura recognizes the user’s utterance, the UC is resolved via:

Aura Bot dialog

TV LLM Recommend UC is built over generic-dialog-v3.
See the Dialog configuration for the required settings.

Response

The response follows the standard video plugin response schema.

Where:

intent: input intent.
entities: input entities as received.
result_intent: usually MEDIA.SEARCH; CHANNEL.PLAY is used when returning a single live channel.
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.recommend.multiple-results, tv:video.recommend.by-default.simple-result, tv:video.recommend.display.single-result, tv:video.recommend.no-results.
- params: This field returns any required parameter in the resource. Example: channelId or deviceId for tv:video.recommend.display.single-result.
payload: Information provided by the Kernel API, when we make the content get info 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: Used to tune a live channel on STB.
conditions: conditions for actions to be applied.

Docs:

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

TV LLM Search UC

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

Introduction

The video LLM 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 (live content and catalog items) using a voice interface.

Find additional information in the following documents:

Discover the TV LLM Search specifications and the particularities of the use case development.
Learn how to configure the generic-dialog for TV LLM Search use case.
Access the TV Retrieve plugin for LLM Search UC.
Discover the resources used by the TV LLM Search use case.
Find the AI configuration for each OB for the TV LLM Search use case.

Specifications

Kernel API

To resolve the user’s request, Aura uses the normalized Video Contents Kernel API.

Request-response model

The TV LLM Search UC is adapted to the normalized request-response model v3.

Available channels

The TV LLM Search UC can be enabled in any channel implementing the normalized v3 request-response model and TV-related payloads.

TV LLM Search features

The normalized TV LLM Search UC includes basic retrieval features for entertainment content:

Search by channel (including live channels and third-party streaming platforms).
Search by person (e.g., presenters/actors).
Search by free-form query strings. (e.g., TV content titles, genres, subgenres, …).
Support for multiple values per entity.

When a single live content is unambiguously found, the plugin can trigger a channel tune action (REMOTEON.ZAPTO) to start playback on the STB.

Current limitations

Currently, the TV LLM Search UC does not include:

Contingency/fallback search mode (no secondary search if zero results).
Temporal filters (time intervals).
Third-party catalogs outside Aura/Kernel scope.

Use case development

The TV LLM Search UC includes the following components:

Understanding features

Intent: intent.tv.retrieve
Entities consumed by the plugin:

Entity	Example (utterance)	Notes
`ent.audiovisual_channel`	“Pon #0” / “Abrir Movistar LaLiga”	Multiple channels allowed via `canon` with `
`ent.audiovisual_person`	“Lo de Broncano”	Multiple persons allowed via `canon` with `
`ent.audiovisual_query`	“noticias Oviedo”	Multiple tokens allowed via `canon` with `

⚠️ NLP should provide the canon field concatenated with || (double pipe) when multiple values are recognized (see NLP configuration) ⚠️ Other entities (e.g., time, devices, etc.) are not used by this plugin and should be omitted for this UC.

Use case logic

Once Aura recognizes the user’s utterance, the UC is resolved via:

Aura Bot dialog

TV LLM Search UC is built over generic-dialog-v3.
See the Dialog configuration for the required settings.

Response

The response follows the standard video plugin response schema.

Where:

intent: input intent.
entities: input entities as received.
result_intent: usually MEDIA.SEARCH; CHANNEL.PLAY is used when returning a single live channel.
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.retrieve.multiple-results, tv:video.retrieve.by-default.simple-result, tv:video.retrieve.display.single-result, tv:video.retrieve.no-results.
- params: This field returns any required parameter in the resource. Example: queryDisplayed.
payload: Information provided by the Kernel API, when we make the content get info 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: Used to tune a live channel on STB.
conditions: conditions for actions to be applied.

Docs:

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

TV LLM Triage UC

Global use case developed by Aura Platform Team that routes unanswered or unclassified requests to different LLMs

Introduction

The video LLM Triage use case is a global experience designed and developed by Aura Global Team that routes unanswered or unclassified requests to different LLMs to improve the chances of returning relevant results to the user.

Find additional information in the following documents:

Find the AI configuration for each OB for the TV LLM Triage use case.

Docs:

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

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.

Docs:

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

Description of Aura bot conversational-search-dialog, that is specifically designed to resolve the advanced TV recommendation using LLMs in ATRIA and complex logic resolution.

Introduction

The conversational-search-dialog is specifically designed to resolve the advanced recommendation, using LLMs in ATRIA. Specifically the LLM configured for TV Conversational Search UC.

You can check its source code in Github:

conversational-search-dialog.ts.
conversational-search-v3-dialog.ts. Currently, this dialog is available for Aura channelData V1 and V3 versions.

For this use case, the required specific configuration is set below:

{
            "channelDataVersion": "v3", // Only in Aura channelData V3 version
            "id": "conversational-search-dialog-v3",
            "allowAnonymous": true,
            "triggerConditions": [
                {
                    "intent": "intent.conversational.search",
                    "settings": {
                        "locales": {
                            "error": [
                                "core:flc.answer.error"
                            ]
                        },
                        "needTvResolution": true
                    }
                }
            ],
            "bypass": {
                "duration": 60,
                "payloadName": "openai",
                "initialData": {},
                "recognizersEnabled": true,
                "recognizersBreakIntents": {
                    "intent.tv.display": [],
                    "intent.navigation.section_show": []
                }
            }
        }

Specific values

Key	Value	Description
bypass.duration	60 (minutes)	This value overwrites the default aura-bot value for bypass lasting 10 minutes.
bypass.payloadName	openai	Name of the interface that will be used as bypass payload for this dialog.
bypass.initialData	empty	It should contain any data needed by the dialog to be initialized.
bypass.recognizersEnabled	true	This value overwrites the default aura-bot way of working with recognizers when it is in bypass mode. If it is set to `true`, recognizers are executed, and their result is stored in the bypass payload to be used, if needed, afterwards.
bypass.recognizersBreakIntents	Array of intents	Used to handle when the user requested any other use case during the execution of the TV Conversational Search UC.

Configuration by channel

For this dialog it is necessary to add the configuration of applicationId and presetId per channel and intent in the channel model.

For this use case, the required specific configuration per channel is set below:

{   
    "atria": {
        "dialogs": {
            "intent.conversational.search": {
                "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
                "presetId": "acdef02f-f810-4474-8143-6b2a04a042f8"
            }
        }
    }
}

Environment variables

Property	Type	Description	Mandatory
AURA_AUTHORIZATION_HEADER	string	Authorization header to be sent to `AURA_GATEWAY_API_ENDPOINT`	yes
AURA_COMPLEX_LOGIC_ENDPOINT	string	URL of Complex Logic endpoint to interact with resolution API.	yes
AURA_GATEWAY_API_ENDPOINT	string	URL of Aura Gateway API endpoint	yes
AURA_GATEWAY_API_ISSUER_URL	string	Issuer URL for token info	yes
AURA_CHANNELDATA_DEFAULT_VERSION	string	Default version of channelData. By default `1.0.0`.	no
AURA_CHANNELDATA_LA_DEFAULT_VERSION	string	Default version of channelData for Latin America. By default `2.0.0`.	no
CONVERSATIONAL_SEARCH_MAX_TAGS	number	Default number of max tags to manage in the dialog. By default `4`.	no
CONVERSATIONAL_SEARCH_TAGS_SCORE_THRESHOLD	number	Default number with minimum score threshold required for a tag to be considered relevant in a TV Conversational Search. Value of this variable oscillates between 0 and 1. By default `0`.	no

How it works

Steps

The dialog starts by init bypass mode.
Then, it checks if the iteration comes from the Triage recognizer, by setting the user’s text to the fixed phase of resource: tv-conversational-search:command.recommend and then calling the AI service.
If the iteration originated because there were no results, it will return the text obtained from the resource: tv-conversational-search:command.no-results to the user.
Then, it calls the AI service to get a generative response based on the intent and the current session ID. The session ID is updated in the context for future requests.
Next, with the response obtained from the LLM, the user will be composed of the following:
- If the generative response returns command info, It will be checked if the command is EXIT so the bypass will be closed and the resource: tv-conversational-search:command.exit will be returned to the user.
- If the generative response returns tags info, it calls the complex logic service to get a resolution based on the intent and tags from the generative response. If the tags are not valid or not meet a threshold or there are no results, the resource will be returned: tv-conversational-search:command.no-results. Instead, ff content exists, it will be returned in the channel data, but the text of the result shown to the user will always be the one obtained from generative response.
- If the generative response returns text info, this text is included in response of user, unless there are no results, as we indicated in the previous paragraph, a specific resource will be returned.
Finally, it sends the activity to the user and ends the dialog.
The bypass will only be closed if these two conditions are met:
- The ‘EXIT’ command is detected.
- A new user intent configured that match those configured in the dialog in field: recognizersBreakIntents.

Sequence diagram

sequenceDiagram
    autonumber
    participant User
    participant Dialog
    participant AI Services
    participant Complex Logic

    Dialog->>Dialog: Open dialog 
    Dialog->>Dialog: Init bypass mode and check interaction origin
    alt interaction origin is no-results
        Dialog->>User: Send activity to user with command no-results text
        Dialog->>Dialog: End dialog
    else interaction origin is triage
        Dialog->>Dialog: set text to send LLM with command recommend.
    end
    Dialog->>Dialog: continue bypass
    alt user intent recognized match with break intent configured
        Dialog->>Dialog: Close bypass
        Dialog->>User: Send activity to user with command exit text
    else user intent is not break intent configured
        Dialog->>Dialog: continue bypass
        Dialog->>AI Services: Call AI service with intent and session ID
        AI Services->>Dialog: Return generative response and session ID
        alt generative response contains a 'EXIT' command
            Dialog->>Dialog: Close bypass
            Dialog->>User: Send activity to user with command exit text
            Dialog->>Dialog: End dialog
        else generative response contains tags
            alt tags are valid
                Dialog->>Complex Logic: Call complex logic service with intent and tags
                Complex Logic->>Dialog: Return resolution
                alt No content found in resolution
                    Dialog->>User: Send activity to user with command no-results text
                else Content found
                    Dialog->>User: Send activity to user with text of generative response and resolution
                end
            else tags are invalid
                Dialog->>User: Send activity to user with command no-results text
            end
        else generative response contains text
                Dialog->>User: Send activity to user with text of generative response
        end
    end
    Dialog->>Dialog: End dialog

Docs: TV LLM Conversational None: Dialog Configuration

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

Configuration of the generic-ai-dialog for TV LLM Conversational None UC

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

Specific configuration

The TV LLM Conversational None UC is triggered by the generic-ai-dialog-v1 for channelData v1 or generic-ai-dialog-v3 for channelData v3. For this use case, the required specific configuration is set below:

Example v1:

    {
    "name": "generic-ai",
    "dialogs": [
        {
            "id": "generic-ai-dialog-v1",
            "onlyIn": [
                "set-top-box"
            ],
            "triggerConditions": [
                {
                    "intent": "intent.conversational.none",
                    "settings": {
                        "locales": {
                            "error": [
                                "tv.error.fpaOrCognitive"
                            ]
                        }
                    }
                }
            ]
        }
    ]
    }

Example v3:

    {
        "channelDataVersion": "v3",
        "id": "generic-ai-dialog-v3",
        "onlyIn": [
            "set-top-box",
            "global-video-platform"
        ],
        "triggerConditions": [
            {
                "intent": "intent.conversational.none",
                "settings": {
                    "locales": {
                        "error": [
                            "core:flc.answer.error"
                        ]
                    }
                }
            }
        ]
    }

Docs:

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

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

Specific configuration

The TV Recommend use case is triggered by the generic-dialog-v3.
For this use case, the required configuration is:

{
  "id": "generic-dialog-v3",
  "channelDataVersion": "v3",
  "triggerConditions": [
    {
      "intent": "intent.tv.recommend",
      "settings": {
        "locales": {
          "error": [
            "core:flc.answer.error"
          ]
        },
        "needTvResolution": true,
        "payloadType": "tv"
      }
    }
  ]
}

Docs:

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

Configuration of the generic-ai-dialog for TV LLM Search UC

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

Specific configuration

The TV LLM Search UC is triggered by the generic-ai-dialog-v1 for channelData v1 or generic-ai-dialog-v3 for channelData v3. For this use case, the required specific configuration is set below:

Example v1:

    {
        "id": "generic-ai-dialog-v3",
        "onlyIn": [
            "movistar-plus"
        ],
        "triggerConditions": [
            {
                "intent": "intent.tv.retrieve",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "payloadType": "tv"
                }
            }
        ]
    }

Example v3:

    {
        "id": "generic-ai-dialog-v1",
        "onlyIn": [
            "movistar-plus"
        ],
        "triggerConditions": [
            {
                "intent": "intent.tv.retrieve",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "payloadType": "tv"
                }
            }
        ]
    }

Docs:

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

Configuration of the generic-dialog for Section Show use case

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

Specific configuration

The Section Show 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.navigation.section_show",
                "settings": {
                    "locales": {
                        "error": [
                            "tv:tv.error.fpaOrCognitive"
                        ]
                    },
                    "actions": [
                        {
                            "name": "NAVIGATION_SECTION_SHOW"
                        },
                        {
                            "name": "MAKE_SOUND"
                        }
                    ],
                    "sound": "positive",
                    "needPlayingContent": false,
                    "payloadType": "tv"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic-dialog for the Audiovisual App Opening use case

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

Specific configuration

The Audiovisual App Opening 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.app_open",
            "settings": {
                "locales": {
                    "error": [
                        "tv:video.section.not_available"
                    ]
                },
                "actions": [
                    {
                        "name": "GOTOAPP"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "sound": "positive",
                "needPlayingContent": false,
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV content get info use case

How the generic dialog must be configured for this use case

Specific configuration

The TV content get info 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.content_get_info",
            "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

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

Configuration of the generic-dialog for Change language use case

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

Specific configuration

The Change language 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.language_change",
            "settings": {
                "locales": {
                    "error": [
                        "tv:tv.error.fpaOrCognitive"
                    ]
                },
                "actions": [
                    {
                        "name": "REMOTEON_AUDIO_SUBTITLES"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV move backwards use case

How the generic dialog must be configured for this use case

Specific configuration

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

Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_backwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveBackwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV move forwards use case

How the generic dialog must be configured for this use case

Specific configuration

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

Configuration for Spain OB in MP, MH and STB channels. In this configuration, there is still a default value of 60 seconds if no time entity is identified. Only the minutes and seconds entities are handled.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY",
                        "params": {
                            "keyCode": "MOVE_FORWARD",
                            "levels": "60"
                        }
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm": "currentIntent.entities.map((ent) => { if (!isNaN(ent.entity)) { persistentData.dialogData.actionParams.SEND_KEY = { levels: ent.type === 'ent.time_length_sec' ? Number(ent.entity) : Number(ent.entity) * 60}}})"
                }
            }
        }
    ],
    "onlyIn": [
        "movistar-plus",
        "set-top-box"
    ]
}

Configuration for Brazil OB in STB channel. In this configuration, no default value is defined, as the STB device will resolve it when receiving an empty value in the parameter levels. A new entity is now recognized: ent.time_length_hour. Additional recognition was required by the aura-bot in order to obtain the total number of seconds to be returned in the parameter levels. To obtain that convertion into seconds, a new function has been created in utiles called: getSecondsLevelsWithTimerRecognizer.

{
    "id": "generic-dialog-v3",
    "channelDataVersion": "v3",
    "suggestions": false,
    "triggerConditions": [
        {
            "intent": "intent.tv.move_forwards",
            "settings": {
                "locales": {
                    "success": [
                        "tv:tv.moveForwards"
                    ],
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "actions": [
                    {
                        "name": "SEND_KEY"
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv",
                "functions": {
                    "params": [
                        "currentIntent",
                        "persistentData",
                        "genericUtils",
                        "configuration"
                    ],
                    "algorithm": "return new Promise(async (resolve, reject) => { try { const params = { levels: await genericUtils.getSecondsLevelsWithTimerRecognizer(currentIntent, configuration) }; persistentData.dialogData.actionParams['SEND_KEY'] = params; resolve(); } catch (error) { reject(error); } });"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV none use case

How the generic dialog must be configured for this use case

Specific configuration

The TV none 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.none",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "needTvResolution": true
            }
        }
    ],
    "onlyIn": [
        "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

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

Docs:

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

Configuration of the generic-dialog for Subtitles remove use case

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

Specific configuration

The Subtitles remove 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.subtitles_remove",
            "settings": {
                "locales": {
                    "error": [
                        "tv:tv.error.fpaOrCognitive"
                    ]
                },
                "actions": [
                    {
                        "name": "REMOTEON_AUDIO_SUBTITLES",
                        "params": {
                            "subtitles": "None"
                        }
                    },
                    {
                        "name": "MAKE_SOUND"
                    }
                ],
                "payloadType": "tv"
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Docs:

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

Configuration of the generic dialog for TV VOD EPG information use case

How the generic dialog must be configured for this use case

Specific configuration

The TV VOD EPG information 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.vod_epg_information",
            "settings": {
                "locales": {
                    "error": [
                        "core:flc.answer.error"
                    ]
                },
                "payloadType" : "tv",
                "functions" : {
                    "params" : [
                        "currentIntent",
                        "persistentData"
                    ],
                    "algorithm" : "const entityType = currentIntent?.entities?.[0]?.type; switch (entityType) { case 'ent.device_tv': case 'ent.device_mobile': case 'ent.device_phone': persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_TV', entities: [ { type: entityType, entity: currentIntent.entities?.[0]?.entity } ] }; break; default: persistentData.dialogData.dialogSetting.forcedIntentResult = { name: 'MEDIA.SHEET_SECOND_SCREEN', entities: [] }; break; }"
                }
            }
        }
    ],
    "onlyIn": [
        "set-top-box"
    ]
}

Specific values

Key	Value	Description
triggerConditions[?].settings.functions.params	String[]	Params for algorithm
triggerConditions[?].settings.functions.algorithm	String	Logic to get intentResult by entities

Docs:

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

TV display use case

Global use case developed by Aura Platform Team that allows users to display specific TV channels in Aura

Introduction

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

Find additional information in following the documents:

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

Specifications

Kernel API

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

Request-response model

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

Available channels

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

Display features

Currently, the normalized TV display use case includes the following display features:

Display by channel (both for Brazil and Spain OBs)
Display by content: title, genre, subgenre, actor or director (for Spain OB)

Therefore, the answer could be of this type: “This is what they are broadcasting now on that channel”

Use case development

The TV display use case development includes these components:

Understanding features

TV display use case intent: intent.tv.display
TV display use case entities: Entities vary across the OBs where this experience is available: Check NLP configuration by OB.

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 (channels, titles, genres, subgenres, actors, directors) in the user’s utterance and detect them as Aura entities.

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 display is built over the generic-dialog-v3.
- Check the section Configuration of the generic-dialog for TV display use case in order to know the required configuration for the TV display experience.
CLF Plugin:

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

Docs:

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

TV content get info plugin

Complex Logic Framework plugin for the TV content get info use case

Introduction

The TV content get info 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.

Get content info about a channel

The content get info about a channel is based in the received entities.

The content get info stage follows the steps set below:

Build the `search_query` param

The content get info builds a search_query param using label values of first entity ent.audiovisual_channel to prioritize channels searching. If the label value is null for an entity, then the canon value is used.

Entity used to search is: ent.audiovisual_channel

The entity will be used 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 not entities allowed, then a query param to content get info is not built.

With this prioritization, the system builds a search_query param that will be used to call the video query API 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: LIVE.
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: UTC current time at which the request is made.
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.

Content get info response

When a user requests for getting content information about a channel, the following possible scenarios can occur for the response:

a. No content with channel info is received. The returned resource is tv:video.content-get-info.by-channel.no-results

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

c. More than one type of content is received. The returned resource is tv:video.content-get-info.by-channel.multiple-results

d. The request does not contain any ent.audiovisual_channel entity. The returned resource is tv:video.content-get-info.by-channel.no-results

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

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SEARCH.
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.content-get-info.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 content get info 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:
- MAKE_SOUND: The target for this action is channel and its unique parameter is sound (with negative value assigned). This action is returned when we have the resource tv:video.content-get-info.by-channel.no-results
conditions: Condition for the actions to be applied.

Docs:

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

TV content get info use case

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

Introduction

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

Find additional information in following the documents:

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

Specifications

Kernel API

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

Request-response model

TV content get info use case is adapted to the new request-response normalized model v3.

Available channels

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

Currently, STB channels in ES are already available.

Display features

Currently, the normalized TV content get info use case includes basic get content information features for channels:

Content get info by channel

Therefore, the answer could be of this type: “This is what they are broadcasting now on that channel”

Use case development

The TV content get info use case development includes these components:

Understanding features

TV content get info use case intent: intent.tv.content_get_info
TV content get info use case entities:

Entity	Example
`ent.audiovisual_channel`	“What’s on in channel 1?”

⚠️ Other entities in the user’s request are not taken into account in the get content info 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 (channels) in the user’s utterance and detect them as Aura entities.

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 content get info is built over the generic dialog v3.
- Check the section Configuration of the generic dialog for TV content get info use case in order to know the required configuration for the TV content get info experience.
CLF Plugin:

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

Docs:

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

TV Conversational Search plugin

Complex Logic Framework plugin for the TV Conversational Search use case

Introduction

The TV Conversational Search plugin resolves requests from a user to obtain personalized recommendations for audiovisual content from Telefónica catalogs.

Intent: intent.conversational.search
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

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

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Example:
```
(mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)
order: personal

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.conversational.search.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound
- result_intent: CHANNEL.PLAY
- Resource: tv:video.conversational.search.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: MEDIA.SEARCH
- Resource: tv:video.conversational.search.by-default.simple-result

3. Multiple results

Payload: list of items
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.conversational.search.multiple-results (with param query_displayed)

Resources returned

The TV Recommend plugin may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.conversational.search.no-results → no content found
tv:video.conversational.search.by-default.simple-result → one non-live result
tv:video.conversational.search.multiple-results → multiple results
tv:video.conversational.search.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Recommend me something”
- for a single live channel result → CHANNEL.PLAY tune channel with live channel.
- for a multiple results → MEDIA.SEARCH with tv:video.conversational.search.multiple-results.
- for any results → tv:video.conversational.search.no-results.

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.

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 move backwards use case

Global use case developed by Aura Platform Team that allows users to move the content backwards on the TV by using Aura

Introduction

The TV move backwards use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to move the content backwards on the TV using a vocal interface.

Find additional information in following the documents:

Learn how to configure the generic dialog for TV move backwards use case.
Discover which are the resources used by the TV move backwards use case.
Find out the NLP configuration for each OB for the TV move backwards use case.

Specifications

Request-response model

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

Available channels

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

Currently, STB channel in ES is available for channelData V1. And channelData V3 is suitable for STB in Brazil with time entity recognition: ent.time_length_hour.

Display features

Currently, the normalized TV move backwards use case includes basic move backwards features for some entities:

Move the TV content backwards
Move backwards by specifying the desired time

This UC also includes specific verbs without entities. For AP repository the key verbs are: “retroceder”, “retornar” and “rebobinar”. For Brazil, they are “recuar” and “retroceder”.

Therefore, the answer could be of this type: “Okay, I’ll rewind the TV content.”

Use case development

The TV move backwards use case development includes these components:

Understanding features

TV move backwards use case intent: intent.tv.move_backwards
TV move backwards use case entities:

Entity	Example
`ent.audiovisual_genre`	“Move the movie backwards”
`ent.time_length_hour`	“Move the movie backwards 2 hours”
`ent.time_length_min`	“Move the movie backwards 2 minutes”
`ent.time_length_sec`	“Move the movie backwards 2 seconds”
`ent.time_instant`	“Move it backwards now”

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

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

NLP expression to recognize the user’s utterance and detect the user’s intention.

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 move backwards is built over the generic dialog v3.
- Check the section Configuration of the generic dialog for TV move backwards use case in order to know the required configuration for the TV move backwards experience.

Docs:

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

TV move forwards use case

Global use case developed by Aura Platform Team that allows users to move the content forwards on the TV by using Aura

Introduction

The TV move forwards use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to move the content forwards on the TV using a vocal interface.

Find additional information in following the documents:

Learn how to configure the generic dialog for TV move forwards use case.
Discover which are the resources used by the TV move forwards use case.
Find out the NLP configuration for each OB for the TV move forwards use case.

Specifications

Request-response model

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

Available channels

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

Currently, MH and STB channels in ES are already available for channelData V3 version and MP is available for channelData V1. But for these channels, time entity recognition: ent.time_length_hour is not yet available. It would be available for STB in Brazil.

Display features

Currently, the normalized TV move forwards use case includes basic move forwards features for some entities:

Move the TV content forwards
Move forwards by specifying the desired time

This UC also includes specific verbs without entities. For AP repository the key verbs are: “avanzar” and “adelantar”. For Brazil, they are “adiantar” and “avançar”.

Therefore, the answer could be of this type: “Ok, I’ll fast forward the content a little”

Use case development

The TV move forwards use case development includes these components:

Understanding features

TV move forwards use case intent: intent.tv.move_forwards
TV move forwards use case entities:

Entity	Example
`ent.audiovisual_genre`	“Move the movie forwards”
`ent.time_length_hour`	“Move the movie forwards 2 hours”
`ent.time_length_min`	“Move the movie forwards 2 minutes”
`ent.time_length_sec`	“Move the movie forwards 2 seconds”
`ent.time_instant`	“Move it forwards now”

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

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

NLP expression to recognize the user’s utterance and detect the user’s intention.

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 move forwards is built over the generic dialog v3.
- Check the section Configuration of the generic dialog for TV move forwards use case in order to know the required configuration for the TV move forwards experience.

Docs:

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

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

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.

Docs:

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

Complex Logic Framework plugin for the TV Recommend use case

Introduction

The TV Recommend plugin resolves requests from a user to obtain personalized recommendations for audiovisual content from Telefónica catalogs.

Intent: intent.tv.recommend
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

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

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_channel`	Yes	Multiple values accepted, separated by `\|\|`.
`ent.audiovisual_person`	Yes	For participants (actors, directors, presenters, etc.), multiple values accepted with `\|\|`.
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Channel: trim each value, wrap each value in quotes, and join with OR inside the parentheses.
- Person: trim each value, wrap each value in quotes, and join with AND (no group parentheses).
- Example:
```
("La 1" OR "La 2") AND "Brad Pitt" AND (mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)
order: personal

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.recommend.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: CHANNEL.PLAY
- Resource: tv:video.recommend.display.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound
- result_intent: MEDIA.SEARCH
- Resource: tv:video.recommend.by-default.simple-result

3. Multiple results

Payload: content list and search_query (search query response string)
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.recommend.multiple-results (with param query_displayed)

Resources returned

The TV Recommend plugin may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.recommend.no-results → no content found
tv:video.recommend.by-default.simple-result → one non-live result
tv:video.recommend.multiple-results → multiple results
tv:video.recommend.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Recommend me something”
- for a single live channel result → CHANNEL.PLAY tune channel with live channel.
- for a multiple results → MEDIA.SEARCH with tv:video.recommend.multiple-results.
- for any results → tv:video.recommend.no-results.

Docs:

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

TV Retrieve plugin for LLM Search UC

Complex Logic Framework TV Retrieve plugin for the TV LLM Search UC

Introduction

The TV Retrieve plugin for LLM Search UC resolves requests from a user to search and retrieve audiovisual content from Telefónica catalogs.

Intent: intent.tv.retrieve
Main result intents: MEDIA.SEARCH (default), CHANNEL.PLAY (when zapping to a live channel).

Validate input request

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

If the input data is invalid, the resource returned is:

tv:video.model-validation.request.error.

Entities used for search

The plugin works with the following entity types:

Entity type	Usage in search	Notes
`ent.audiovisual_channel`	Yes	Multiple values accepted, separated by `\|\|`.
`ent.audiovisual_person`	Yes	For participants (actors, directors, presenters, etc.), multiple values accepted with `\|\|`.
`ent.audiovisual_query`	Yes	Free text query, multiple values accepted with `\|\|`.

Multiple entities & values:
You can repeat the same entity type multiple times and/or provide several values in a single entity using the \|\| separator.

Building the search query

The plugin constructs two query strings:

search_query → technical query sent to Kernel API:
- Group query and channel entities in parentheses.
- Joins different entity types with AND.
- Query: split on ||, trim each value, and join with OR inside the parentheses (no quotes).
- Channel: trim each value, wrap each value in quotes, and join with OR inside the parentheses.
- Person: trim each value, wrap each value in quotes, and join with AND (no group parentheses).
- Example:
```
("La 1" OR "La 2") AND "Brad Pitt" AND (mystery OR series)
```
search_query_response → a simplified, user-readable query string included in the payload and telemetry.

If no entities are present, the plugin returns a no results response.

API video query (Handler 4P)

Plugin calls Handler4P.tv_4p_handler.get_user_content_search(...) with the following parameters:

user_id: data[aura_user][user_id]
administrative_number: data[app_context][user][account_number]
access_token: data[aura_user][access_token]
scopes: data[aura_user][scopes]
purposes: data[aura_user][purposes]
device_type: data[app_context][device][type]
catalog_types:
- Default: VOD, LIVE, L7D
- Allowed: VOD, LIVE, L7D, LCH, LSR
- Filtered according to allowed_catalog_types of the device
search_query: built as explained above
show_series: series
profile: data[app_context][user][video_profile_name] (optional; only if present to avoid API 501 errors)
commercialization_types: [SVOD]
max_quality: data[app_context][device][max_quality] (optional)
current_region: data[app_context][location][currentRegion] (optional)

Response logic

Depending on the number and type of results, the plugin builds different responses:

1. No results

Plays negative sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.retrieve.no-results
Status: SUCCESS.NO_CONTENT

2. One result

Live channel:
- Payload: { type: details, data: <channel info> }
- Action: REMOTEON.ZAPTO (with params channelId and deviceId)
- Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
- result_intent: CHANNEL.PLAY
- Resource: tv:video.retrieve.display.single-result
Non-live content (VOD, L7D, etc.):
- Payload: details of the single item
- Plays positive sound
- result_intent: MEDIA.SEARCH
- Resource: tv:video.retrieve.by-default.simple-result

3. Multiple results

Payload: content list and search_query (search query response string)
Plays positive sound unless the channel is disabled in the sound_disabled_channels configuration
result_intent: MEDIA.SEARCH
Resource: tv:video.retrieve.multiple-results (with param query_displayed)

Resources returned

The TV Retrieve plugin for LLM Search UC may return the following resources:

tv:video.model-validation.request.error → input validation error
tv:video.api.answer.error → API Video error
tv:video.retrieve.no-results → no content found
tv:video.retrieve.by-default.simple-result → one non-live result
tv:video.retrieve.multiple-results → multiple results
tv:video.retrieve.display.single-result → one live channel (tune channel)

Payload and actions

Payload:
- type: details (single item) or content_list (multiple items)
- data: item(s) from Kernel API
- For multiple results: includes search_query (human-readable string)
Actions:
- Sound feedback (positive/negative)
- For a single live channel: {"name": "REMOTEON.ZAPTO", "params": {"channelId": "$channelId", "deviceId": "$deviceId"}, "target": "stb"}

Status codes

status: Final status request. This field includes the following parameters:
- code: Status code with value: SUCCESS, SUCCESS.NO_CONTENT or ERROR.INTERNAL.
- message: Status message, which describes the status code.
- params: Parameter that sends details of status. This field does not appear if it is empty.

Example behavior

“Put La 1” → detects ent.audiovisual_channel with value "La 1" → single live channel result → CHANNEL.PLAY tune channel with live channel.
“I want something with Brad Pitt” → detects ent.audiovisual_person with value "Brad Pitt" → multiple results → MEDIA.SEARCH with tv:video.retrieve.multiple-results.
“Mystery series” → detects audiovisual_query with value "Mystery series" → if no results → tv:video.retrieve.no-results.

Docs:

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

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

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.

Docs:

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

TV VOD EPG information plugin

Complex Logic Framework plugin for the TV VOD EPG information use case

Introduction

The TV VOD EPG information plugin resolves the request from a user getting information about the TV content broadcasted in this specific moment

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.

Get VOD EPG information about a playing content

The VOD EPG information about a playing content is based in the catalog type and content id.

To retrieve content information stage follows the steps set below:

Video query API

We will make a query to Video Contents normalized Kernel API to retrieve content.

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

user_id: Input data[aura_user][user_id]
access_token: Input data[aura_user][access_token]
catalog_type: Input data[app_context][playing][catalog_type] where “vod” is “VOD”, “l7d” and “record” is “L7D”, and “live” is “LIVE”.
administrative_number: Input data[app_context][user][account_number]
content_id: Input data[app_context][playing][content_id]
scopes: Input data[aura_user][scopes]
purposes: Input data[aura_user][purposes]
device_type: Input data[app_context][device][type]

VOD EPG information response

When a user requests for getting playing EPG information about a specific content, the following possible scenarios can occur for the response:

a. Receive a content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvDetail

b. Receive a content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:carousel.info.contentDetail

c. Not received or not found in API any content with the EPG information and the request does not contain any devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.moreInfoTvNotAllowed

d. Not received or not found in API any content with the EPG information and the request contain devices entities (ent.device_tv, ent.device_mobile, ent.device_phone). The returned resource is tv:tv.more_info.notAllowed

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

Response

The response follows this response schema.

Where:

intent: input intent.
entities: input entities.
result_intent: This field is always MEDIA.SHEET_TV except when the resource is tv:carousel.info.contentDetail or tv:tv.more_info.notAllowed. In this case this field is MEDIA.SHEET_SECOND_SCREEN.
resources: List of response resources that includes three main parameters:
- type: Type of the response resource.
- name: Name of the response resource. Example: tv:tv.moreInfoTvDetail
- params: This field returns any required parameter in the resource.
payload: Information provided by the Kernel API, when we make the VOD EPG information request. For this case, If we receive a response, it is a value and then this field includes the following parameters:
- type: details
- 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.
conditions: Condition for the actions to be applied.

Docs:

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

TV VOD EPG information use case

Global use case developed by Aura Platform Team that allows users to get VOD EPG information about the playing content.

Introduction

The TV VOD EPG information use case is a global experience designed and developed by Aura Global Team that allows Telefónica customers to ask Aura about what they are watching on TV at that specific moment using a vocal interface. The use case answers with the name of the TV content being broadcasted.

A user interacts with Aura through a normalized video channel
She asks about the content currently playing: “What am I watching?”, “What’s on?”
Aura recognizes the request and provides back to the channel the information required to answer the request

Find additional information in following the documents:

Discover the TV VOD EPG information specifications and the particularities of the use case development.
Learn how to configure the generic dialog for TV VOD EPG information use case.
Find out the NLP configuration for each OB for the TV VOD EPG information use case.

Specifications

Kernel API

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

Request-response model

TV VOD EPG information use case is adapted to the new request-response normalized model v3.

Available channels

TV VOD EPG information use case could be available for any channel that implements normalized v3 request-response model including TV related data.

Currently, STB channels in BR are already available.

Display features

Currently, the normalized TV VOD EPG information use case includes basic VOD EPG information features for content:

VOD EPG information by content

Therefore, the questions could be of this type: “What am I watching?” “Which actors are involved?”

Use case development

The TV VOD EPG information use case development includes these components:

Understanding features

TV VOD EPG information use case intent: intent.tv-vod_epg_information
TV VOD EPG information use case entities:

Entity	Example
`ent.device_tv`	“¿Qué estoy viendo en la tele?”
`ent.device_mobile`	“¿Qué estoy viendo en el móvil?”
`ent.device_phone`	“¿Qué estoy viendo en el teléfono?”

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

NLP expression to recognize the user’s utterance and detect the user’s intention.

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 VOD EPG information is built over the generic dialog v3.
- Check the section Configuration of the generic dialog for TV VOD EPG information use case in order to know the required configuration for the TV VOD EPG information experience.

Docs:

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

Audiovisual App Opening use case resources

Resources used by the Audiovisual App Opening use case

Introduction

The Audiovisual App Opening use case will use three different types of resources:

Specific resources for the use case

The resources associated to the Audiovisual App Opening plugin are defined below:

Specific resources for intent.tv.app_open use case	Definition	Example	Managed by	Scope

`tv:video.section.not_available`	Resource returned when the section is not available		tv.app_open plugin	Use case-specific

Docs:

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

Change language use case resources

Resources used by the Change language use case

Introduction

The Change language use case will use three different types of resources:

Docs:

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

Section Show use case resources

Resources used by the Section Show use case

Introduction

The Section Show use case will use three different types of resources:

Specific resources for the use case: tv.display

There are no specific resources for TV section show in V3. For v1, the resources associated are defined below:

Specific resources for tv.display use case	Definition	Example	Managed by	Scope
`navigation:navigation.section_show`	Resource returned when the navigation section show is successfully		navigation.section_show plugin	Use case-specific

Docs:

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

Subtitles remove use case resources

Resources used by the Subtitles remove use case

Introduction

The Subtitles remove use case will use three different types of resources:

Docs:

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

TV content get info use case resources

Resources used by the TV content get info use case

The TV content get info use case will use three different types of resources:

Specific resources for the use case: tv.content_get_info

The resources associated to the TV content get info plugin are defined below:

Specific resources for tv.content_get_info use case	Definition	Example	Managed by	Scope
`tv:video.content-get-info.by-channel.no-results`	Resource returned when the search does not find any result with channel info	Lo siento, no encuentro lo que dices	tv.content_get_info plugin	Use case-specific
`tv:video.content-get-info.by-channel.single-result`	Resource returned when the search finds one channel	Esto es lo que están emitiendo ahora en ese canal	tv.content_get_info plugin	Use case-specific
`tv:video.content-get-info.by-channel.multiple-results`	Resource returned when the search finds more than one channel	He encontrado estos contenidos que se estan emitiendo	tv.content_get_info plugin	Use case-specific

Docs:

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

TV LLM Conversational Search UC resources

Resources used by the TV LLM Conversational Search UC

Introduction

The TV LLM Conversational Search UC will use three different types of resources:

Specific resources for the use case: TV LLM Conversational Search

In case the LLM Conversational Search does not return the text to be shown to the user, the resources from TV Conversational Search plugin would be used

The resources associated to aura-bot are defined below:

Specific resources for TV LLM Conversational Search use case	Definition	Example	Managed by	Scope
`tv-conversational-search:command.exit`	Resource returned when the user sends a message to stop the dialog and launch a different UC	Entendido. Recuerda que puedes volver a probarlo diciendo “Recomendador avanzado"	conversational-search dialog	Use case-specific
`tv-conversational-search:command.close.words`	Resource returned when the user sends a message to stop the dialog. By default, it is not configured.	Salir, cerrar, goodbye, exit, quit	conversational-search dialog dialog	Use case-specific
`tv-conversational-search:command.no-results`	Resource returned in case there is no results	Ahora mismo no encuentro resultados, pero si me dices un género o tu estado de ánimo te sugiero algo.	conversational-search dialog	Use case-specific
`tv-conversational-search:command.recommend`	Resource used to call the LLM with a fixed phrase when the request comes from triage	Recomendación avanzada	conversational-search dialog	Use case-specific

The resources associated to the TV LLM Conversational Search plugin are defined below:

Specific resources for TV LLM Conversational Search use case	Definition	Example	Managed by	Scope
`tv:video.conversational.by-default.simple-result`	Resource returned when finds one result as recommendation	Here is a suggestion	tv.recommend plugin	Use case-specific
`tv:video.conversational.multiple-results`	Resource returned when finds more than one result as recommendation	Here are some suggestions	tv.recommend plugin	Use case-specific
`tv:video.conversational.display.single-result`	Resource returned when one live channel is recommended and starts playback	Tuning to channel	tv.recommend plugin	Use case-specific
`tv:video.conversational.no-results`	Resource returned when does not find any result as recommendation	Nothing found	tv.recommend plugin	Use case-specific

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

Resources used by the TV LLM Recommend UC

Introduction

The TV LLM Recommend UC will use three different types of resources:

The resources associated to the TV LLM Recommend plugin are defined below:

Specific resources for TV LLM Search use case	Definition	Example	Managed by	Scope
`tv:video.recommend.by-default.simple-result`	Resource returned when finds one result as recommendation	Here is a suggestion	tv.recommend plugin	Use case-specific
`tv:video.recommend.multiple-results`	Resource returned when finds more than one result as recommendation	Here are some suggestions	tv.recommend plugin	Use case-specific
`tv:video.recommend.display.single-result`	Resource returned when one live channel is recommended and starts playback	Tuning to channel	tv.recommend plugin	Use case-specific
`tv:video.recommend.no-results`	Resource returned when does not find any result as recommendation	Nothing found	tv.recommend plugin	Use case-specific

Docs:

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

TV LLM Search UC resources

Resources used by the TV LLM Search UC

Introduction

The TV LLM Search UC will use three different types of resources:

Specific resources for the use case: TV LLM Search

The resources associated to the TV LLM Search plugin are defined below:

Specific resources for TV LLM Search use case	Definition	Example	Managed by	Scope
`tv:video.retrieve.by-default.simple-result`	Resource returned when the search finds one result	Here is the content I found	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.multiple-results`	Resource returned when the search finds more than one result	Here are the contents I found	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.display.single-result`	Resource returned when the search finds a single live channel and starts playback	Tuning to channel with live channel	tv.retrieve plugin	Use case-specific
`tv:video.retrieve.no-results`	Resource returned when the search does not find any result	I haven’t found anything	tv.retrieve plugin	Use case-specific

Docs:

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

TV move backwards use case resources

Resources used by the TV move backwards use case

The TV move backwards use case will use two different types of resources:

Docs:

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

TV move forwards use case resources

Resources used by the TV move forwards use case

The TV move forwards use case will use two different types of resources:

Docs:

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

TV none use case resources

Resources used by the TV none use case

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

Specific resources for the use case: tv.none

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

Specific resources for tv.none use case	Definition	Example	Managed by	Scope
`tv:video.search.contingency.no-results`	Resource returned when the contingency search does not find any result	No he encontrado nada	tv.none 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.none 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.none plugin	Use case-specific

Docs:

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

TV none use case

Global use case developed by Aura Platform Team that allows searching content related with the user’s utterance when the intent is intent.tv.none

Introduction

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

Find additional information in following the documents:

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

Specifications

Kernel API

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

Request-response model

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

Available channels

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

Currently, STB channels in BR are already available.

Display features

Currently, the normalized TV none use case includes basic search features for content/channels:

none search content/channels with user normalized utterance

Therefore, the answer could be any provided by the recognized intent: intent.tv.none

Use case development

The TV none use case development includes these components:

Understanding features

TV none use case intent: intent.tv.none
TV none use case entities: Ignore the entities for search content/channels, use normalized utterance for contigency search.

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 (channels) in the user’s utterance and detect them as Aura entities.

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 none is built over the generic dialog v3.
- Check the section Configuration of the generic dialog for TV none use case in order to know the required configuration for the TV none experience.
CLF Plugin:

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

Docs:

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

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

Docs:

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

TV VOD EPG information use case resources

Resources used by the TV VOD EPG information use case

The TV VOD EPG information use case will use three different types of resources:

Specific resources for the use case: tv.vod_epg_information

The resources associated to the TV VOD EPG information plugin are defined below:

Specific resources for tv.vod_epg_information use case	Definition	Example	Managed by	Scope
`tv:tv.moreInfoTvDetail`	Resource returned when content is retrieved with some device entities (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Esto es lo que se está reproduciendo en la televisión	tv.vod_epg_information plugin	Use case-specific
`tv:carousel.info.contentDetail`	Resource returned when content is retrieved without any device entity (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Aquí tienes más detalles	tv.vod_epg_information plugin	Use case-specific
`tv:tv.moreInfoTvNotAllowed`	No resource returned when content is retrieved with some device entities (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Vaya, parece que no puedo darte más información de lo que estás viendo en la televisión	tv.vod_epg_information plugin	Use case-specific
`tv:tv.more_info.notAllowed`	No resource returned when content is retrieced without any device entity (`ent.device_tv`, `ent.device_mobile`, `ent.device_phone`)	Vaya, parece que no puedo hacer eso	tv.vod_epg_information plugin	Use case-specific

Docs:

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

AI configuration by OB

The following information applies to both Spain and Brazil; there will not be separate blocks for each OB.

Introduction

LLMs UCs are configured and located within the aura-config-provision repository. See the TV LLM Conversational None Preset (notice that in the url, the field [ob] needs to be replaced by [es] or [br]) LLM use cases have been designed to provide a fallback mechanism for user requests that are not currently understood, i.e. return a ‘None’ intent, or when no content is found in the video platform related to it, offering a second chance for classification and response generation.

Intent

The Conversational None Use Case has different invocation points:

From triage: when the LLM fails to map the user’s input to any known intent often due to ambiguous, incomplete or broad queries (“Uno hacia abajo”, “Sintoniza el canal”, “Cambia cómo suena”).
From failures or KOs occurring in other supported use cases.

Once the user’s input is classified as intent.conversational.none, the request is routed to the Conversational None Agent, an LLM-based conversational module designed to handle unclassified or unsupported queries with the goal of guiding the user toward valid flows or supported actions within the platform by suggesting possible next steps or rephrasing options.

The conversation is considered complete once the LLM returns a response to the user. Subsequent user inputs will be reprocessed through the full recognition pipeline, including both deterministic and LLM-based intent classifiers.

LLM output format

In the output format, the LLM returns a structured JSON response based on predefined Use Cases configured within the field use_cases in the preset (in args). These Use Cases follow a structured format that includes three fields separated by a pipe (|):

NAME (mandatory): The name of the Use Case.
DESCRIPTION (optional): A short explanation or instruction. This field may be empty.
EXAMPLE (mandatory): A representative user utterance for that Use Case.

Sample extract from use case information:

NAME	DESCRIPTION	EXAMPLE
abrir una sección	Para abrir una sección es necesario mencionar el nombre de la sección que deseas consultar. Algunas son: Deportes, Cine o Series.	Abrir la sección Deportes
Desativar o som		Silencie a TV

Based on this information and according to matching criteria with the user’s request, the LLM constructs its output response by returning two fields:

“speak”: intended for voice output to be spoken by the system.
“text”: displayed on screen as visual feedback within the Video Platform interface.

The content of these fields varies depending on the type of match between user’s input and the predefined Use Cases:

Single Use Case Match:
- If the Use Case has a description:
  - “speak”: this field references the name of the Use Case related to the request, describes its invocation process and includes a relevant example.
  - “text”: this field mirrors the example used in “speak”.
- If the Use Case has no description:
  - “speak”: this field mentions the name of the Use Case linked to the request and the corresponding example.
  - “text”: this field mirrors the example used in “speak”.
Multiple Use Cases Match:
- “speak”: this field mentions the ambiguity and shows two likely Use Cases with examples.
- “text”: this field includes the same two examples.
No match:
- “speak”: this field explains the uncertainty and suggests two random valid Use Cases with examples.
- “text”: this field repeats only the examples pertaining to the Use Cases shown in “speak”.

This conditional behavior ensures that the assistant gives relevant, helpful responses tailored to the context of the user’s request.

Examples in Castilian Spanish:

Type of match	Input	Output
“Single Use Case no description”	“Pon la peli desde el principio”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Parece que quieres poner un contenido desde el principio. Por ejemplo, prueba a decir Pon Titanic desde el principio.", "text": "Pon Titanic desde el principio"}}}}`
“Single Use Case with description”	“Pon cualquier canal”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Parece que quieres cambiar de canal. Para cambiar de canal es necesario mencionar el nombre del canal que quieres sintonizar o indicar el número de dial asociado a ese canal. Por ejemplo, prueba a decir Pon el canal Antena 3.", "text": "Pon el canal Antena 3"}}}}`
“Multiple Use Cases”	“Volumen”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Creo que quieres ejecutar alguna acción relacionada con el volumen. Podría ser bajar el volumen o subir el volumen. Por ejemplo, prueba a decir Baja un poco el volumen o Sube un poco el volumen", "text": "Baja un poco el volumen, Sube un poco el volumen"}}}}`
“No match”	“Cántame una canción”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "No tengo claro a qué te refieres pero sí que puedo cambiar de canal o abrir una sección. Por ejemplo, prueba a decir Pon el canal Antena 3 o Abrir la sección Deportes", "text": "Pon el canal Antena 3, Abrir la sección Deportes"}}}}`

Examples in Brazilian Portuguese:

Type of match	Input	Output
“Single Use Case no description”	“Coloque o filme desde o começo”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Parece que você quer colocar um conteúdo desde o começo. Por exemplo, tente dizer Começar desde o início.", "text": "Começar desde o início"}}}}`
“Single Use Case with description”	“Coloque qualquer canal	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Parece que você quer mudar de canal. Para mudar de canal é necessário mencionar o nome do canal que deseja sintonizar. Por exemplo, tente dizer Mudar para o SBT.", "text": "Mudar para o SBT"}}}}`
“Multiple Use Cases”	“Volume”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Creo que você quer executar alguma ação relacionada ao volume. Pode ser abaixar o volume ou subir o volume. Por exemplo, tente dizer Abaixe o volume ou Suba o volume", "text": "Abaixe o volume, Suba o volume"}}}}`
“No match”	“Canta-me uma canção”	`{{"name": "llm_conversational_none", "arguments": {{ "speak": "Não tenho certeza do que você está se referindo mas eu posso mudar de canal ou abrir uma seção. Por exemplo, tente dizer Mudar para o SBT ou Abra Filmes", "text": "Mudar para o SBT, Abra Filmes"}}}}`

Aura – video

Docs:

TV LLM Conversational None UC

Introduction

Specifications

Request-response model

Available channels

Use case development

Understanding features

Use case logic

Docs:

TV LLM Conversational Search UC

Introduction

Specifications

Kernel API

Request-response model

Available channels

Use case development

Understanding features

Use case logic

Docs:

TV LLM Recommend UC

Introduction

Specifications

Kernel API

Request-response model

Available channels

TV LLM Recommend features

Current limitations

Use case development

Understanding features

Use case logic

Response

Docs:

TV LLM Search UC

Introduction

Specifications

Kernel API

Request-response model

Available channels

TV LLM Search features

Current limitations

Use case development

Understanding features

Use case logic

Response

Docs:

TV LLM Triage UC

Introduction

Docs:

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

Docs:

Introduction

Specific values

Configuration by channel

Environment variables

How it works

Steps

Sequence diagram

Docs: TV LLM Conversational None: Dialog Configuration

Configuration of the generic-ai-dialog for TV LLM Conversational None UC

Specific configuration

Docs:

Configuration of the generic-dialog for TV Recommend use case

Specific configuration

Docs:

Configuration of the generic-ai-dialog for TV LLM Search UC

Specific configuration

Docs:

Configuration of the generic-dialog for Section Show use case

Build the `search_query` param