TV LLM Search UC

• 1: Dialog configuration
• 2: TV Retrieve plugin for LLM Search UC
• 3: TV LLM Search UC resources
• 4: AI configuration by OB

1 - Dialog configuration

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

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"
                }
            }
        ]
    }

2 - TV Retrieve plugin for LLM Search UC

TV Retrieve plugin for 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:

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

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)

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.

3 - TV LLM Search UC resources

TV LLM Search UC resources

Introduction

The TV LLM 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 LLM Search

Specific resources for the use case: TV LLM Search

The resources associated to the TV LLM 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 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 currently return a ‘None’ intent or zero results, offering a second chance for classification and response generation.

Intents

Once the triage has classified the user’s petition under the intent intent.tv.retrieve, the user’s petition can be further classified into the following intents or UCs:

• intent.tv.recommend: This intent will be returned when the user seeks TV content recommendations and explicitly refers to entities such as genres, subgenres, titles, sports-related content, directors, or actors. Example: “¿Qué documentales me recomiendas?”.
• intent.tv.retrieve: This intent will be returned when the user is searching for either generic or specific TV content. Example: “Muestra películas dirigidas por Quentin Tarantino”.
• intent.tv.none: This intent will be returned for any request that is not covered by the two use cases outlined above. Examples: “Cambia a Telecinco”, “Avanza 5 minutos”, “Pon una alarma”.

Entities

Three different entities can be returned if mentioned by the user:

• entities.channel: This entity will be returned whenever there is a mention of a TV channel or a third-party TV platform in the user’s request.
• entities.person: This entity will be returned whenever a proper name belonging to an actor, actress, director, driver, boxer, or other public figure is mentioned in the user’s request.
• entities.query: This entity will be returned when any relevant information for performing a search on the platform is mentioned in the user’s request. (e.g., TV titles, genres, subgenres)

LLM output format

In the output format, the only mandatory field is that of the intent. Entities are optional, as they may or may not be mentioned in the user’s request. If multiple values are present for an entity type, values must be separated by a double pipe “||”.

Examples: