TV LLM Conversational Search UC

• 1: tv-conversational-search-dialog
• 2: TV Conversational Search plugin
• 3: TV Conversational Search UC resources
• 4: AI configuration by OB

1 - tv-conversational-search-dialog

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

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

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

2 - TV Conversational Search plugin

TV Conversational Search plugin

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:

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:

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

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

3 - TV Conversational Search UC resources

TV LLM Conversational Search UC resources

Introduction

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

• Aura Platform global resources
• Common resources for video use cases
• Specific resources for the use case: tv-conversational-search

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:

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

4 - AI configuration by OB

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:

1. 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”)
2. 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:

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

2. By breaking command: EXIT (“Salir”, “Abandonar”, “Quiero irme ya”, “Eu quero sair daqui”, “Terminei”)

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

1. Returning 0 when it is identified that the user wants to leave the conversation (breaking command)
2. Returning 1 when the category mentioned by the user matches one from the available list
3. 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: