Aura –

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:

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

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 Search 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 Search use case has different invocation points:

From triage: when the LLM identifies that the user’s intention is to perform an open search or to get an advanced recommendation (“Recomiéndame algo para ver”, “Quiero ver algo divertido”, “Ponme con el recomendador”)
Fallback for the TV Search deterministic use case and for the TV LLM Search UC for user’s requests with 0 results or KO.

Once the user’s request is classified under intent.conversational.search, the user will enter into a conversation with the LLM Conversational Search agent. During this conversation, the agent will attempt to refine the user’s search criteria to try to lead the user to content that is available on the platform according to the available thematic categories also called tags (e.g., “Amor imposible”, “Persecuciones”, “Psicópatas”).

The conversation can be ended through various means:

By breaking intents:

ES: intent.tv.display (contents & channels) and intent.navigation.section_show (sections, apps…)
BR: intent.tv.display (channels), intent.tv.app_open (apps/third party platforms) and intent.navigation.section_show (sections)

By breaking command: EXIT (“Salir”, “Abandonar”, “Quiero irme ya”, “Eu quero sair daqui”, “Terminei”)
When the user clicks on one of the contents that appears on the screen in response to their request

LLM output format

In the output format, the identified categories, their score, and the text for the user will be included without exceeding the 115-character limit. The number of tags will vary depending on different cases:

Returning 0 when it is identified that the user wants to leave the conversation (breaking command)
Returning 1 when the category mentioned by the user matches one from the available list
Returning 3 for cases such as:

No categories are identified in the user’s request
The user wants to see the full list of categories or any recommendation in general

The list of thematic categories is configured within the field tags in the preset (in args) with a format of comma-separated items enclosed in square brackets ([tag1, tag2, tag3, tag4…]).

Examples:

Input	Output
“Suficiente, quiero salir”	`{"name": "llm_conversational_search", "arguments": {"command": "EXIT"}`
“Me apetece ver algo de amor”	`{"name": "llm_conversational_search", "arguments": {"text": "Aquí tienes algo sobre la temática: Amor", "command": "", "tags":[{ "tag": "Amor", "score": 0.98 }]}}`
“Me gustaría ver contenido de aviones”	`{"name": "llm_conversational_search", "arguments": {"text": "No he encontrado nada relacionado pero puedes explorar categorías como: Épico, Bélico o Crimen fallido", "command": "", "tags":[{ "tag": "Épico", "score": 0.98 }, { "tag": "Bélico", "score": 0.92 }, { "tag": "Crimen fallido", "score": 0.89}]}}`
“¿Qué categorías tienes disponibles?”	`{"name": "llm_conversational_search", "arguments": {"text": "Estas son algunas de las categorías que puedes explorar: Amor, Crisis de pareja o Reencuentros amorosos","command": "", "tags":[{ "tag": "Amor", "score": 0.93 }, { "tag": "Crisis de pareja", "score": 0.87 }, { "tag": "Reencuentros amorosos", "score": 0.77 }]}}`