Aura – components

Docs:

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

account-linking dialog

Description of the account-linking dialog, one of the dialogs that handles users’ account linking

Introduction

The account-linking dialog is included in the global linking library.

It is in charge of handling user’s account linking for channels using integrated authentication, that is, channels that already have a proper user’s identifier that should be linked with the corresponding auraId and that cannot handle Kernel authentication directly:

WebClient
Facebook
WhatsApp

This dialog launches authentication in Kernel based on browser navigation. It includes several steps to validate the Terms and Conditions of the services and to launch the user’s autentication in the OB authenticator and in Kernel that, in the end, would register the auraId in Aura users’ database.

Environment variables

Property	Type	Scope	Description
LINKING_FP_ACCESS_SESSIONS_ENDPOINT	string	Local	URL to Kernel Access Sessions API
LINKING_FP_CALLBACK_LOGIN_URL	string	Local	URL to redirect to authentification login
LINKING_FP_CALLBACK_LOGOUT_URL	string	Local	URL to redirect to authentification logout
LINKING_TERMS_AND_CONDITIONS_URL	string	Local	URL to terms and conditions HTML file. By default: `/documents/termsandconditions.html`
SAFETY_CHECK_ENDPOINT	string	Local	URL API client endpoint

Docs:

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

Aura configuration API admin module

Admin module description for aura-configuration-api

Introduction

The administration module defines services associated with general administration tasks in aura-configuration-api server.

All these services are defined in the admin namespace (/admin).

Servers definition

By default, the servers defined in the swagger include the base path (for v2): /aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/admin/export
aura-services/v2/configuration/admin/import

Endpoints

Path	Method	Description
/admin/export	GET	Export configuration
/admin/import	POST	Import configuration

You can read the complete documentation of each service in the aura-configuration-api swagger file.

Export modules

Export all

To export all configuration, a GET call to /admin/export path must be made.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/export' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

The service will respond with an ExportModel type object:

export interface ExportModel {
    /** Export metadata */
    metadata?: ExportMetadata;
    /** Export data */
    data?: ExportModelData;
}

metadata: It contains information related to the export itself: export date (data), current API version (apiVersion), bot configuration version (version).
data: Module data information indexed by module name.

Further information about ExportModel interface.

Export one or several specific modules

It is possible to export one or several modules using the module parameter in the call to /admin/export endpoint.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/export?modules=channels' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

The result will have the same format as for complete export, but in the data field only includes the indicated modules.

Import modules

To import, data from a previous export must be used. The import can be from a complete or partial export of certain modules.

To import all configuration, a POST call to /admin/import path must be made.

curl --location --request POST 'http://aura-configuration-api:8999/aura-services/v2/configuration/admin/import' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX' \
--header 'Content-Type: application/json' \
--data-raw 'PREVIOUS_EXPORT_DATA'

How is an import processed?

During the import process, the following tasks are performed:

For each module to export, the import method of each of those modules is called.
The necessary mappers are executed to adapt the export version to the current server version (if applicable).
The objects of each module are validated with json schema.
The objects are inserted in the appropriate collection.

flowchart TD
    A[Import] --> B{Are there modules?}
    B --> |Yes| Mappers[Apply mappers]
    Mappers --> Validate[Validate using json schema]
    Validate --> Add[Add to collection]
    Add --> B
    B ---->|No| E[End]

Result of the import process

The import service will respond with an ImportResult type object:

export interface ImportResult {
    version: string;
    fromVersion: string;
    modules: ImportModuleResult[];
    status: ProcessStatus;
}

export interface ImportModuleResult {
    name: string;
    patches?: ImportPatches;
    result: ProcessResult;
}

export enum ProcessStatus {
    Ok = 'Ok',
    Error = 'Error'
}

version: Version to which the import has been made.
fromVersion: Original import version.
modules: array of ImportModuleResult with the result of the import of each module.
status: Status with the overall result of the import process. If any module fails the result will be Error.

Database

The database to store the aura-configuration-api information must be named with the following format:

aura-configuration-<ENVIRONMENT_NAME>-<BOT_VERSION>

Example for the ap-next environment and 7.4.0 version:

aura-configuration-ap-next-7-4-0

As a general rule, all those modules that define a DAO will have a collection associated with that module.The currently existing collections are described in the following sections.

Channels collection

This collection stores channel information using channels collection.

Fields

Field name	Type	Required
name	string	true
prefix	string	true
nlp	{}	true
nlp.enabled	boolean	true
auraBotCacheTTL	number	false
id	string	true
dialogLibraries	Array<{}>	false
actions	{}	false
actions.afterLogin	{}	false
actions.afterLogin.action	string	false
actions.afterLogin.type	string	false
actions.afterLogin.data	{}	false
actions.thirdPartyApp	{}	false
actions.thirdPartyApp.action	string	false
actions.thirdPartyApp.type	string	false
actions.thirdPartyApp.data	{}	false
actions.thirdPartyApp.contentType	string	false
rcs	{}	false
rcs.agentId	string	true
rcs.clientToken	string	true
rcs.email	string	true
rcs.privateKey	string	true
requestOptions	{}	false
requestOptions.fileAttachments	{}	false
requestOptions.fileAttachments.enabled	boolean	true
requestOptions.fileAttachments.enabledExtensions	Array<string[]>	false
requestOptions.fileAttachments.customProactiveDialogId	string	false
requestOptions.fileAttachments.validations	{}	false
requestOptions.requestOptionsVersion	{}	false
responseOptions	{}	false
responseOptions.dialogContext	{}	false
responseOptions.dialogContext.disabled	boolean	false
responseOptions.dialogContext.disabledMerge	boolean	false
responseOptions.dialogContext.normalizeTerms	boolean	false
responseOptions.dialogContext.defaultListType	’none’,‘ordinalCardinal’,‘ordinal’,‘cardinal’	false
responseOptions.dialogContext.promptChoice	{}	false
responseOptions.dialogContext.promptChoice.generateList	boolean	false
responseOptions.dialogContext.promptChoice.generate	’never’,‘always’,‘custom’	false
responseOptions.dialogContext.cardActions	{}	false
responseOptions.dialogContext.cardActions.generateList	boolean	false
responseOptions.dialogContext.cardActions.generate	’never’,‘always’,‘custom’	false
responseOptions.dialogContext.returnToClient	boolean	false
responseOptions.dialogContext.processFromClient	boolean	false
responseOptions.versions	{}	false
responseOptions.needsEmptyResponseEvent	boolean	false
responseOptions.outputMessageFormat	‘custom’,’enrich’,‘html5’,‘simple’,‘voice’	false
responseOptions.sendSpeak	boolean	false
responseOptions.disambiguationFormat	‘disabled’,‘prompts’,‘suggestions’	false
responseOptions.textConvert	boolean	false
responseOptions.suggestionType	‘actions’,‘attachment’	false
responseOptions.suggestionsNumber	number	false
responseOptions.tv.actions	Array<Action[]>	false
security	{}	false
security.anonymous	‘anonymous’,‘identifiable’	false
security.allowUserProfile	boolean	false
security.channelId	string	false
security.authScopes	string	true
security.authPurposes	string	true
security.federatedAuthentication	{}	false
security.federatedAuthentication.loginUrl	string	false
security.federatedAuthentication.auraIdSeparator	string	false
security.federatedAuthentication.loginCallback	{}	false
security.federatedAuthentication.loginCallback.method	string	false
security.federatedAuthentication.loginCallback.integrated	boolean	false
security.federatedAuthentication.loginCallback.endpoint	string	false
security.federatedAuthentication.loginCallback.queryParams	string	false
security.federatedAuthentication.loginCallback.headers	Array<string[]>	false
security.federatedAuthentication.loginCallback.body	string	false
security.federatedAuthentication.logoutCallback	{}	false
security.federatedAuthentication.logoutCallback.method	string	false
security.federatedAuthentication.logoutCallback.integrated	boolean	false
security.federatedAuthentication.logoutCallback.endpoint	string	false
security.federatedAuthentication.logoutCallback.queryParams	string	false
security.federatedAuthentication.logoutCallback.headers	Array<string[]>	false
security.federatedAuthentication.logoutCallback.body	string	false
security.termsAndConditions	{}	false
security.termsAndConditions.authenticated	{}	false
security.termsAndConditions.authenticated.version	string	true
security.termsAndConditions.authenticated.service	string	true
security.termsAndConditions.anonymous	{}	false
security.termsAndConditions.anonymous.version	string	true
security.termsAndConditions.anonymous.service	string	true
whatsapp	{}	false
whatsapp.client	{}	false
whatsapp.client.id	string	true
whatsapp.client.secret	string	true
whatsapp.client.purposes	string	false
whatsapp.client.scopes	string	false
whatsapp.phoneNumber	string	false
whatsapp.listOptions	{}	false
whatsapp.listOptions.type	‘button’,’enumeratedList’,’list’	false
whatsapp.listOptions.rules	Array<{}>	false
whatsapp.type	‘whatsapp’	false
metadata	{}	false
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1,
        "name": "idx_channel_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 1,
        "name": "idx_channel_library",
        "keys": {
            "id": 1,
            "dialogLibraries.name": 1
        }
    }
]

skills collection

This collection stores skills information using skills collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
appId	string	true
skillEndpoint	string	true
channels	Array<string[]>	true
disabled	boolean	false
external	boolean	false
metadata	{}	false
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1.1,
        "name": "idx_skill_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    }
]

applications collection

This collection stores applications information using applications collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
brand	string	true
disabled	boolean	false
agents	string[]	false
nlp.channelId	string	false
models.level	Level	false
models.presets	string[]	true
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Types

Type name	Type	Options
Level	string	Set the different levels of access for the application. It can only be changed by Aura Global Team

Indexes

[
    {
        "version": 1.5,
        "name": "idx_app_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.5,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    }
]

presets collection

This collection stores presets information using presets collection.

Fields

Root

Field name	Type	Required
id	string	true
name	string	true
description	string	false
group	string	false
session	Session	false
generative	Generative	false
rag	Rag	false
metadata	Metadata	false

Types

Action

Field name	Type	Required
name	string	true
target	string	false
params	object	false
postBack	object	false

Session

Field name	Type	Required
session.window	number	false
session.timeout	number	false

Generative

Field name	Type	Required
generative.model.id	string	false
generative.model.parameters.max_tokens	number	false
generative.model.parameters.temperature	number	false
generative.model.parameters.top_p	number	false
generative.injectionMaxLength	number	false
generative.prompts.template	string	false
generative.prompts.preamble.text	string	false
generative.prompts.preamble.args.name	string	false
generative.prompts.examples	string[]	false
generative.prompts.promptRegexClean	string	false
generative.prompts.promptMaxLength	number	false

RAG

Field name	Type	Required
rag.type	string	false
rag.references.maximum	number	false
rag.references.baseUrl	string	false
rag.model.id	string	false
rag.model.parameters.max_tokens	number	false
rag.model.parameters.temperature	number	false
rag.model.parameters.top_p	number	false
rag.stages.language	string	false
rag.stages.security.heuristics.example	string	false
rag.stages.security.maxLength	number	false
rag.stages.translation.prompt	string	false
rag.stages.translation.language	string	false
rag.stages.clean.prompt.default	string	false
rag.stages.clean.prompt.es	string	false
rag.stages.context.prompts.recreatedQuestion.default	string	false
rag.stages.context.prompts.recreatedQuestion.es	string	false
rag.stages.context.prompts.sameContext.default	string	false
rag.stages.context.prompts.sameContext.es	string	false
rag.stages.context.stickyContext	string	false
rag.stages.retrieval.sourceDataId	string	false
rag.stages.postFiltering.candidatesPostFiltering	string	false
rag.stages.postFiltering.prompt.default	string	false
rag.stages.postFiltering.prompt.es	string	false
rag.stages.generative.ragStrategy	string	false
rag.stages.generative.prompts.stuff.default	string	false
rag.stages.generative.prompts.stuff.es	string	false
rag.stages.generative.prompts.refine.default	string	false
rag.stages.generative.prompts.refine.es	string	false
rag.outputRefine.candidates	boolean	false
rag.outputRefine.filterOutputMetadata.map.fileType	string	false
rag.outputRefine.filterOutputMetadata.map.pageNumber	string	false
rag.outputRefine.filterOutputMetadata.groupBy	string	false
rag.outputRefine.filterOutputMetadata.aggregate	string	false
rag.outputRefine.filterOutputMetadata.outputFilter	string[]	false
rag.outputRefine.filterOutputMetadata.root	string[]	false

Metadata

Field name	Type	Required
metadata.version	string	false
metadata.createdAt	string	false
metadata.updatedAt	string	false

Indexes

[
    {
        "version": 1.10,
        "name": "idx_preset_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 1.10,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 1.10,
        "name": "idx_preset_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

suggestions collection

This collection stores suggestion information using suggestions collection.

Fields

Field name	Type	Required
id	string	true
name	string	true
intent	string	true
entities	Array<{}>	true
resources	Array<{}>	true

Indexes

[ 
    {
        "version": 2.1,
        "name": "idx_suggestion_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 2.1,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 2.1,
        "name": "idx_suggestion_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

tv-section collection

This collection stores TV Section information using the tv-sections collection.

Fields

Field name	Type	Required	Description
id	string	true	Unique identifier for the TV Section (UUID)
pid	string	false	External or process identifier
name	string	false	Name of the TV Section
canon	string	false	Canonical name of the TV Section
type	string	false	Section type (`app` or `section`)
metadata	object	false	Document metadata (version, creation and update dates)

Example of `metadata`:

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

  {
    "version": 2.0,
    "name": "idx_tvsections_id",
    "keys": { "id": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_tvsections_pid",
    "keys": { "pid": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_updated_at",
    "keys": { "metadata.updatedAt": -1 }
  },
  {
    "version": 2.0,
    "name": "idx_tvsections_name",
    "keys": { "name": 1 },
    "unique": true
  }
]

agents collection

This collection stores agent information using the agents collection.

Fields

Field name	Type	Required	Description
id	string	true	UUID that identifies the agent univocally in Aura.
name	string	true	Name that identifies the agent univocally in Aura.
description	string	false	Agent description description.
communication	object	true	Communication configuration of the agent. See `communication` object.
flowConfig	object	false	Configuration of the agent flow.
deploymentName	string	false	Name of the deployment where the agent is running.
metadata	object	false	Document metadata (version, creation and update dates). See metadata object.

communication object (HTTP)

Field	Type	Description
endpoint	string	HTTP endpoint where the agent is listening to.
headers	object	HTTP headers associated with the agent.
communicationType	string	Communication type (`http`).
timeout	number	Timeout for the agent.
retries	number	Number of retries for the agent.

metadata object

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

[
  {
    "version": 2.0,
    "name": "idx_agent_id",
    "keys": { "id": 1 },
    "unique": true
  },
  {
    "version": 2.0,
    "name": "idx_updated_at",
    "keys": { "metadata.updatedAt": -1 }
  },
  {
    "version": 2.0,
    "name": "idx_agent_name",
    "keys": { "name": 1 },
    "unique": true
  }
]

routing filters collection

This collection stores routing filters information using the routing-filters collection.

Fields

Field name	Type	Required	Description
id	string	true	UUID that uniquely identifies a routing filter in Aura.
name	string	true	Name that uniquely identifies a routing filter in Aura.
description	string	false	Routing Filter description.
type	string	true	Contains the type of filter. Currently, there is only one type ‘userId’.
entities	string[]	true	Contains at least one entity necessary to generate the data for the filter.
dataBase	object	true	Contains an object with the collections necessary to store and process data. See database object.
vars	object	true	Contains an object with the custom variables necessary for any phase of the filter. Encrypted field.
fields	object	true	Contains the field mapping for grouping and its relationship with the previously defined entities. Encrypted field.
sourceFilters	object	false	Contains an object to filter source data when loading from entity data. Encrypted field.
match	object	true	Contains an object with the MongoDB aggregation format that must return grouped data. Encrypted field.
summary	object	true	Contains an object with MongoDB command format to insert these obtained aggregates into a summary collection. Encrypted field.
actions	object[]	true	Contains an array of objects with the actions to be performed on the filtered data.
summaryFilter	object	true	Contains an object with MongoDB command format to select the records that meet the filter. Encrypted field.
metadata	object	false	Document metadata (version, creation and update dates). See metadata object.

database object

Field	Type	Description
dataFilterCollection	object	Contains an object with the name of the collection for raw data and its expiration in seconds. See filterCollection object.
dataSummaryCollection	object	Contains an object with the name of the collection for summary data and its expiration in seconds. See filterCollection object.

filterCollection object

Field	Type	Description
collectionName	string	Contains the name of the collection.
expiration	object	Contains the value in seconds of the expiration of the collection data.
indexes	object[]	A optional array with indexes in mongodb format. Example: `[{"seq1": 1}]`

metadata object

Field	Type	Description
version	string	Configuration version when the document was created
createdAt	string	Creation date (ISO 8601)
updatedAt	string	Update date (ISO 8601)

Indexes

[
    {
        "version": 2.2,
        "name": "idx_routing_filter_id",
        "keys": {
            "id": 1
        },
        "unique": true
    },
    {
        "version": 2.2,
        "name": "idx_updated_at",
        "keys": {
            "metadata.updatedAt": -1
        }
    },
    {
        "version": 2.2,
        "name": "idx_routing_filter_name",
        "keys": {
            "name": 1
        },
        "unique": true
    }
]

A example with a complete filter definition

 {
        "name": "preset-filter-stb-conversational-search",
        "id": "4a879583-5f76-4e6b-87c1-6250e8743dda",
        "description": "Limit the number of messages per user in a month for stb conversational search preset",
        "type": "userId",
        "entities": [
            "GATEWAYMESSAGE"
        ],
        "vars": {
            "llm_execution_limit": 10
        },
        "dataBase": {
            "dataFilterCollection": {
                "collectionName": "dataFilterPreset",
                "expiration": 5356800,
                "indexes": [
                    {
                        "seqId": 1
                    }
                ]
            },
            "dataSummaryCollection": {
                "collectionName": "dataSummaryStbConvSearch",
                "expiration": 5356800,
                "indexes": [
                    {
                        "month": 1,
                        "total": 1,
                        "year": 1
                    },
                    {
                        "itemId": 1,
                        "month": 1,
                        "year": 1
                    }
                ]
            }
        },
        "fields": {
            "MatchingValue": "^ef3d0603-3fef-4109-a577-0ab92f9060df$",
            "forId": "USER_ID",
            "forMatchingField": "AURA_PRESET_NAME",
            "forTime": "MESSAGE_TM"
        },
        "sourceFilters": [
            {
                "field": "USER_ID",
                "op": "notEqual",
                "val": ""
            }
        ],
        "match": [
            {
                "$match": {
                    "fieldForMatch": "{{fields.forMatchingField}}",
                    "seqId": {
                        "$gt": "{{ctx.lastSeqId|number}}"
                    },
                    "valueForMatch": {
                        "$options": "i",
                        "$regex": "{{fields.MatchingValue}}"
                    }
                }
            },
            {
                "$group": {
                    "_id": {
                        "itemId": "$itemId",
                        "month": "$month",
                        "year": "$year"
                    },
                    "seqId": {
                        "$max": "$seqId"
                    },
                    "total": {
                        "$sum": 1
                    }
                }
            },
            {
                "$project": {
                    "_id": 0,
                    "itemId": "$_id.itemId",
                    "month": "$_id.month",
                    "seqId": 1,
                    "total": 1,
                    "year": "$_id.year"
                }
            }
        ],
        "summary": {
            "filter": {
                "itemId": "{{doc.itemId}}",
                "month": "{{doc.month|number}}",
                "year": "{{doc.year|number}}"
            },
            "options": {
                "upsert": true
            },
            "update": {
                "$inc": {
                    "total": "{{doc.total|number}}"
                },
                "$set": {
                    "expiresAt": "{{ctx.expiration|expires}}",
                    "month": "{{doc.month|number}}",
                    "updatedAt": "{{__DATE_NOW__}}",
                    "year": "{{doc.year|number}}"
                }
            }
        },
        "summaryFilter": {
            "filter": {
                "month": "{{ctx.month|number}}",
                "total": {
                    "$gt": "{{vars.llm_execution_limit|number}}"
                },
                "year": "{{ctx.year|number}}"
            },
            "options": {
                "projection": {
                    "_id": 0,
                    "itemId": 1,
                    "month": 1,
                    "total": 1,
                    "year": 1
                }
            }
        },
        "metadata": {
            "updatedAt": "2025-10-03T06:06:49.609Z",
            "version": "10.5.0"
        }
    }

Docs:

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

agent-dispatcher-api plugin

Technical description of the agent-dispatcher-api plugin

Introduction

agent-dispatcher-api plugin manages and dispatches the requests to the agent API.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector
sessionService	PluginType.Service	Session service
agentsConfiguration	PluginType.Service	Agents Configuration

Provides components (IOC)

Name	Type	Description
agentDispatcherApi	PluginType.API	Agent dispatcher API

Docs:

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

ATRIA Model Gateway architecture and components

Development architecture and technical components of the atria-model-gateway

Technical foundations

atria-model-gateway is responsible for managing the communication with different AI models. This component receives a request from aura-gateway-api, together with other input data, and makes a call the corresponding AI models.

If the selected AI model is RAG, then atria-model-gateway calls the atria-rag-server, which is in charge of executing the RAG chain and making the corresponding calls to the LLM models and databases.

Functional components

The functional components of atria-model-gateway are described in the document LLM/LMM Experiences Builder

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-model-gateway.

A brief description of these components is included below:

Access module

Module for the management of different profiles to access atria-model-gateway.

Context module

Module in charge of the storage of a conversation history in a cache (currently, Redis is used) over a period of time, grouped by session ID. These conversations are taken into account when calling the generative LLM models.

Model manager

Module that includes the available models and presets. It is in charge of receiving the info from aura-gateway-api and calling the corresponding model.

Models

Available AI models integrated into the atria-model-gateway.

Presets

Presets are configurable entities to define the specific model to work with and certain parameters associated to it: model Id, name, description, model parameters, etc.

Constructors can use the default presets or build new ones: Go to document ATRIA configuration.

When configuring an application, all the presets that can be used for this application must be previously defined.

Docs:

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

ATRIA RAG Generate DB architecture and components

Development architecture and technical components of the atria-rag-generate-db

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-rag-generate-db.

A brief description of the technical components is included below:

Data sources

A project contains information required for the execution of the generation of the databases: specific path of documents to feed the databases, allowed file extensions, etc. It can read from different sources, this source type is defined in the extensions field.

Before the information from the documents is stored in the corresponding database, the documents are processed, e.g., they are cut up and cleaned.

Retrievers

The retrievers are in charge of reading the information from the documents and feeding the databases.

The retrievers are defined in the retrievers field of the project. Each retriever is associated with a database in order to feed or retrieve information from it.

Docs:

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

ATRIA RAG Server architecture and components

Development architecture and technical components of the atria-rag-server

Architecture overview

The following diagram schematically shows the main technical components integrated into atria-rag-server.

A brief description of the technical components is included below:

Project

A project contains information required for the execution of the RAG pipeline: specific models for semantic search and lexical search; path where the documents to feed the LLMs are located; allowed file extensions, etc.

Semantic search (embeddings)

Qdrant database that stores the embeddings generated through semantic search (OpenAI embeddings) technology.

Lexical search (LLMs)

Database that stores the required documentation for making lexical searching, based on keywords.

Configuration

atria-rag-server includes a default configuration. Constructors can use it as is or they can modify it to be adapted to their requirements or business models: Go to document ATRIA configuration.

Docs:

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

Aura Complex Logic Framework architecture and components

Architecture and main components that you should handle when working over Aura Complex Logic Framework

CLF architecture

Aura Complex Logic Framework is a docker container, meaning that it is configured as a lightweight, stand-alone, executable package of software that includes all the required elements to run an application.

The Complex Logic Framework architecture is schematically shown in the following figure, containing different elements described in the succeeding sections.

CLF main components

Sandbox

A sandbox is an isolated testing environment that enables users to run programs or execute files without affecting the application, system or platform on which they run and to test new programming code.

Plugins

Plugins in Aura Complex Logic Framework are components that add a specific feature to an existing computer program, enabling its customization.

The role of plugins within the Complex Logic Framework is to receive data, make the required computations and return an adequate response to the handler.

CLF manages different types of plugins, which are encapsulated in the sandbox. Moreover, it contains several global plugins, but it is possible for developers to add custom ones.

Some key features of CLF plugins are defined below:

Architecture allows each package of plugins to be deployed in its own environment: it is possible to have an isolated container deployed in an independent way containing all the plugins of a specific package (for instance, global plugins).
Each package is isolated by being run as a different process by a unique user with randomized name. The rationale behind this is to provide an isolated sandbox to make sure no package of plugins is a security risk. Thereby, each user has limited privileges and computational resources (memory, file descriptors and CPU time) and only runs one process for package.
The running packages can only receive data from a socket, and the appropriate plugin is then executed depending on both the plugin type and the intent contained in the data. The API handler is in charge of forwarding the data to the package, acting as a proxy, but it also checks the requests and transforms the responses back.

To ease working with this architecture, packages, users and sockets have the same random name. This name also appears in the information and error log files.

OBs can develop their own custom plugins in the Aura Complex Logic Global repository, with each plugin implemented as a class that inherits from PluginBase and overwrites run method. This method receives the request data and contains the logic of the plugin. It must also generate a response that will be returned to the API handler. When a request is performed, depending on the intent, the request data will be forwarded to the corresponding plugin automatically. Note that two intents can trigger the same plugin but it is not possible to trigger two plugins with the same intent.
Each package of plugins is watched by a supervisor. If the package process crashes, it will be restarted automatically by supervisor. The causes of abrupt exit could be excessive consumption of resources (CPU time, memory or file descriptors) or plugin internal malfunction.

Stub

A stub, in the context of distributed computing, is a piece of code that is used to convert parameters during a remote procedure call (RPC). An RPC allows a client computer to remotely call procedures on a server computer.

The parameters used in a function call have to be converted because the client and server computers use different address spaces. Stubs perform this conversion so that the remote server computer perceives the RPC as a local function call.

API server

API server is the process that listens for requests. This API server is based on the cognitive API package and, in this case, is configured to run the Complex Logic module.

HTTP requests will be passed to the package API handlers according to the CLF configuration.

It is also important to mention that API server process is watched by supervisor (meaning that it is fault-tolerant).

API handler

In Aura Complex Logic Framework, API handlers are classes that inherit from BaseComplexLogicAPIHandler. They are responsible for dealing with HTTP requests through the following methods:

Checking the request is valid.
Checking that the response is in the correct format.
Making a new request to the corresponding package process, which contains a group of plugins.

The first two items are implemented by the declaration of schemas that define the query request and the response. Plugin API handlers are only responsible for defining which request schema is accepted and which response is valid (also by using a schema).

The request to a specific package is made automatically by the system as long as the specific intent that summons the trigger is recognized. The configuration is described in plugins configuration.

API plugin

API plugin is an internal component based on the cognitive API package. It exposes the plugins contained in a package.

Kernel Platform connectors

Kernel is the database where Telefónica stores all the data of its customers in a safe and reliable way, allowing users to control their data at the same time.

These data can be consulted through a Kernel API with the necessary permissions. From the Complex Logic Framework, the only way to access Kernel is through our connectors. The connectors are used, for example, to obtain customer invoices or offer the catalog of devices and services.

These connectors provide total security in order to avoid problems of wrong, malicious or not careful use by third party developers. For this purpose, prior to any request to Kernel, a check of the required permits is made.

CLF Sequence diagram

The following sequence diagram shows the functional flow of the Complex Logic Framework, starting with the request from aura-bot to the Complex Logic module.

Docs:

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

ATRIA application

Definition and role of applications in ATRIA

Introduction

Within ATRIA’s framework, an application is defined as an entity that allows the connection of a channel, service or skill with aura-gateway-api, the component in charge of managing the access to the different ATRIA capabilities.

ATRIA application

As a preliminary step for leveraging any ATRIA AI-driven capability, the use case constructor must configure an application, including different parameters:

To indicate which specific ATRIA capabilities are utilized in the use case.
In this framework, applications supported by ATRIA can be classified as follows:
- Applications that make use only of the NLP as a Service capabilities
- Applications that use Generative capabilities
- Applications that use RAG capabilities
The difference between Generative and RAG capabilities relies solely on the definition of the preset that is associated. But the same application can make use of one, several or all of these capabilities, combining their configuration.
Once the capabilities are selected, to set the required fields for its operation

For example, if we want to use Generative AI for the use case resolution, firstly, certain parameters must be set corresponding to:
- Establishing admin accesses.
- Setting the presets that the application can use, that is, the instructions to work with the AI model, that will be defined in the application configuration.

How to configure an application

An ATRIA application must be configured with specific parameters. For this purpose, follow the guidelines Configure an application in ATRIA, using the specific parameters for the ATRIA AI-driven technology to be used.

Example of application

This is a example of an application that makes use of NLPaaS, Generative and RAG capabilities:

    {
        "id": "8832550f-f03c-4e18-bdbe-7c6fc7adf5ff",
        "name": "app",
        "disabled": false,
        "brand": "0401",
        "nlp": {
            "channelId": "1234"
        },
        "models": {
            "level": "user",
            "presets": ["atria-rag-gpt-4", "generative-preset"]
        }
    }

Applications model

Common fields

Field name	Type	Description
id	string	Unique application identifier. UUID
name	string	Unique application name
brand	string	Identifier of the Telefónica Brand associated to the application. Available values in the document Telefónica brands management
disabled	boolean	Boolean value to enable or disable the application.

NLPaaS fields

Field name	Type	Description
nlp.channelId	string	Channel identifier used to call NLP

Generative/RAG fields

Field name	Type	Description
models.level	string	It indicates the level application in atria-model-gateway, meaning that it has specific access and control privileges. Default value `user`
models.presets	string[]	It indicates all the available ATRIA presets that the application can use. - Check the list of available presets by default - Learn here how to add a new preset or modify one

Docs:

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

Aura Bot main dialog

Description of the main dialog, one Aura Bot core dialog that maps the recognized intent with a specific dialog

Introduction

The main dialog is one of the aura-bot core dialogs in charge of routing from the recognized intention of the user to the specific dialog that provides the functionality required in an intended channel.

main dialog extends ComponentDialog, as all the rest of the dialogs. It is an internal dialog that contains all the intents-to-dialog routing map. It is loaded during the AuraBotserver start-up to be injected as a property in aura-bot and used after each intent recognition to execute the selected dialog.

At this stage, it is both instantiated and initialized, through these steps:

First, the whole list of plugins to be loaded in the system are passed to the dialog.
It also counts on the instance of the Aura BotFramework adapter, used during this start-up phase.
Then the WaterfallDialog with all the steps managed by the main dialog is added to the dialog.
After that, it is initialized:
- A RoutingMap is created.
- All the configured plugins are registered:
  - First of all, internal dialogs are included as dialogs: context-filter dialog and suggestions dialog.
  - Then, all the plugins configured in plugins-config are looped to add the routes of all their dialogs in the RoutingMap property of the main dialog, used during the activities processing to map the recognized intent to the corresponding dialog.

During the activity processing, the ActivityHandler calls MainDialog.run method to handle the incoming activity (in the form of a TurnContext), that passes it through the dialog system. If no dialog is active, it starts the default dialog. If there is any error in the TurnContext, the processing stops here and is sent to the channel.

At this stage, the main dialog is in charge of:

Routing the recognized intent to the dialog that handles it for the current channel.
Update Aura Context information of the current activity to include the dialog information.
If the dialog includes a contextFilter that fits the user’s context, then the dialog executed is the internal context-filter dialog.
If the user’s context does not match with the contextFilter of the dialog or the dialog does not have any contextFilter, then the next step of the main dialog is executed to validate if the Kernel accessToken of the user includes the scopes and purposes needed to execute the dialog.
- If the accessToken has no permissions to access it, then an error is returned, notifying the channel that the user has not consented aura-bot to access the specific API.
- If authorization is correct, then the specific dialog is executed.
When it ends, the next step of the main dialog is executed to check whether or not the dialog needs suggestions. If the dialog is configured to send suggestions and the user’s settings support them, then the internal SuggestionsDialog is executed.
When it ends, the main dialog also ends and an outgoing message flow is started.

Find here detailed information regarding the Routing Manager.

Docs:

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

Aura utils

Aura utils is an utility found in Aura Bot common library to manage dialogs and prompts

Introduction

Aura utils utility allows managing Aura dialogs and prompts.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-bot-utilities/src/aura-bot-common/utils

It contains different methods, described in the following sections.

DialogUtils

Generic tools for any dialog.

setDataActiveDialog

It saves data between steps of a waterfall. Only valid in the same dialog.

param	type	description	mandatory
context	WaterfallStepContext	Context in a step of a Waterfall	yes
keyData	string	Key to recover data saved	yes
data	any	Data to be saved	yes

DialogUtils.setDataActiveDialog(stepContext, KEY_DESCRIPTION, description);

getDataActiveDialog

It gets data between the steps of a Waterfall through an identifier.

param	type	description	mandatory
context	WaterfallStepContext	Context in a step of a Waterfall	yes
keyData	string	Key to recover data saved	yes

const description = DialogUtils.getDataActiveDialog(stepContext, KEY_DESCRIPTION);

getResourcePath

It gets the whole resource path uploaded to blob-storage to be included in cards.

param	type	description	mandatory
libraryName	string	Original file name, that was uploaded to the blob-storage.	yes
baseFilePath	string	Path in Azure Storage from library name (static-resources/libraries/library_name) to resource name.	yes
configuration	Configuration	Set of of configuration variables.	yes

const uriGenericRaw= DialogUtils.getResourcePath('generic', `${this.configuration.GENERIC_RESOURCES_BASE_PATH}/config/${this.configuration.GENERIC_RAW_NAME}`, this.configuration)

If we need a full URL image path including device resolution, getImageUrl method from @telefonica/aura-bot-library-util should be used instead.

isDeeplink

It returns true if the passed URL is a deeplink, and false otherwise.

param	type	description	mandatory
url	string	URL to check.	yes

const isDeepLink = DialogUtils.isDeeplink('http://movistar.es/campain/ahora.html')

PromptUtils

getRetriesValidator

It gets a validator function that will be called each time the user responds to the prompt. In this function, it controls the number of retries to show the prompt.

If attempt is allowed, it is the recognizer that will let an attempt (when there are not results) or the dialog the will manage the result found.

If the retries exceed to maxRetries parameter, the control will be returned to dialog, managing results or not.

If an attempt is shown, the configured retryPrompt (or the same prompt as default) will be shown.

param	type	description	mandatory
maxRetries	number	Number of retries to show the prompt	yes

// Create a ChoicePrompt without retries
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesControl(0));

getRetriesValidatorAndOverwriteRecognizerResult

This validator function is similar to getRetriesValidator but also overwrites the recognizer result obtained by the prompt recognizer with a previous stored value.

This recognizer result value can be set with the function ContextUtils.setPromptRecognizedResult. By default, the result is: prompt-check-recognizer-middleware.

param	type	description	mandatory
maxRetries	number	Number of retries to show the prompt	yes

// Create a ChoicePrompt with 3 retries and use of ordinals control overwriting promptRecognizedResult with the value of aura-bot.
const myPrompt = new ChoicePrompt(ID_PROMPT,PromptUtils.getRetriesValidatorAndOverwriteRecognizerResult(3));

getAbsolutePath

It returns an absolute normalized file path.

param	type	description	mandatory
filePath	string	File path to convert	yes

const path: string = getAbsolutePath('/test/demo_path.txt');

Docs:

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

Global authentication dialogs

Global authentication dialogs support different types of authentication in Aura

Global authentication dialogs include:

Docs:

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

Base recognizer

Description of base-recognizer

Introduction

Recognizers are middlewares that inherit from the abstract class called BaseRecognizerMiddleware.

export abstract class BaseRecognizerMiddleware implements Middleware, Recognizer {
    protected name: string;
    protected id: string;
    protected type: RecognizerType;
    constructor(name: string, id: string, type?: RecognizerType) {
        this.type = type || RecognizerType.Asynchronous;
        this.name = name;
        this.id = id;
    }

The source code of this recognizer is included in Aura Bot Platform recognizers - Github repository.

base-recognizer parameters

Parameters	Type	Description
name	property	Name of the middleware.
id	property	Unique identifier for middleware.
type	property	Type of execution (async or sync) to execute the recognizer method.
recognize	method	Abstract method that must be implemented in the recognizer. If the recognizer detects an intent, it must save the intent result in the turn context.
onTurn	method	Private method executed when the activity is processed by the adapter.
processIntent	method	Protected method to process the intent and entities and store the intentResult and the intent in `AuraCommand` format.

IntentResult model

Name	Type	Description
text	string	Utterance sent to the recognizer.
alteredText	string	If the original text is changed due to mistakes such as spelling typos, the altered version is included here.
intents	Object	Map of intent names to an object with score is returned. Format: `[name: string]: {score: number;};`
entities	Entity	Entities recognized.
promptCheck	boolean	If `true`, the finalize-recognizers-middleware evaluates if exits a prompt in the stack and decides whether it needs to pop from the stack or continues.

Docs:

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

Channeldata validator middleware

Description of channeldata-validator-middleware, in charge of the validation of the request channelData for normalized versions

Introduction

The source code of this middleware is included in this Github repository.

This middleware will check if the channelData of the incoming request is valid or not. This validation is made:

If the environment variable AURA_CHANNELDATA_VALIDATION is set to true.
If the incoming channelData version is greater or equal than AURA_CHANNELDATA_VALIDATION_MIN_VERSION.
If a validator for this version exists. Validators are loaded using schemas stored in aura-models package.

If the validation is ok or is not executed because one or more of the previous conditions are not satisfied, aura-groot continues the normal flow, executing the rest of middlewares.

If the validation fails, the error message core:core.model-validation.request.error will be returned to the user and no more middlewares will be executed.

Docs:

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

Domain recognizer

Description of domain-recognizer in charge of recognizing the user’s domain

Introduction

domain-recognizer is the aura-groot recognizer in charge of identifying the domain in the user’s input request.

This is possible thanks to the mapping of the list of channels and skills that is done at server start-up. A skill can have several associated channels, but a channel can only have one associated skill.

Example:

GOOD
channel1 => skill1
channel2 => skill1
channel3 => skill2

BAD
channel1 => skill1
channel2 => skill2
channel2 => skill1 -> This is not possible

When a user writes through a channel:

The domain to which the channel belongs is identified
The skill associated with that domain is executed
The domain is registered in KPIs

If the recognition of the domain fails, the user will be returned the error message root:skill.not.found.

Docs:

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

Aura Bot generic-ai-dialog-v1

Description of Aura bot generic-ai-dialog-v1, that allows managing several experiences for TV channels using AI services and complex logic resolution.

Introduction

The generic-ai-dialog-v1 allows OBs to implement search and recommendation use cases for TV channels based on AI services and complex logic resolution for channelData v1 channels.

You can check its source code in Github: generic-ai-dialog-v1.ts.

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
GENERIC_MP_RESOLUTION_NO_RESULT_CODE	string[]	List of resolution codes that indicate no results found. By default `['211', '462']`.	no

How it works

The dialog works in a similar way to the generic-ai-dialog-v3 but adapted to the structure of channelData v1.

Complex Logic proxy is used to interact with Complex Logic resolution API, which returns a response similar to Movistar Plus Resolution API. This adaptation is only valid for TVSearch responses for STB channel, because only a subset of fields has been mapped from normalized TV API to legacy TV API.

Docs:

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

Aura Bot generic-ai-dialog-v3

Description of Aura bot generic-ai-dialog-v3, that allows managing several experiences for TV channels using AI services and complex logic resolution.

Introduction

The generic-ai-dialog-v3 allows OBs to implement search and recommendation use cases for TV channels based on AI services and complex logic resolution for channelData v3 channels.

You can check its source code in Github: generic-ai-dialog-v3.ts.

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

Adding configurations for the AI Service

To use the AI Service, you need to add the intent configurations to the channel settings. The configurations should be added in the following format:

{
    "atria": {
        "dialogs": {
            "intent.tv.retrieve": {
                "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
                "presetId": "5d06f26c-a8d8-4f45-a999-102aaa8b191b"
            }
        }
    }
}

With this configuration, when the generic-ia-dialog-v3 is called with the intent intent.tv.retrieve, it will use the specified applicationId and presetId to call the generative API.

How it works

Steps

The dialog starts by retrieving the intent information from the context and logging the start of the dialog.
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, it calls the complex logic service to get a resolution based on the intent and entities from the generative response.
If the resolution indicates no content found, it redirects to the conversational-search dialog.
Otherwise, it builds an activity to be sent to the user using the intent result, intent settings, and resolution.
If any error occurs during these steps, it logs the error, sets the error in the context, and builds an activity from the error.
Finally, it sends the activity to the user and ends the dialog.

Sequence diagram

sequenceDiagram
    autonumber
    participant User
    participant Dialog
    participant AI Services
    participant Complex Logic
    participant Conversational Search
    Dialog->>Dialog: Retrieve intent information from context
    Dialog->>AI Services: Call AI service with intent and session ID
    AI Services->>Dialog: Return generative response and session ID
    Dialog->>Complex Logic: Call complex logic service with intent and entities
    Complex Logic->>Dialog: Return resolution
    alt No content found in resolution
        Dialog->>Conversational Search: Redirect to conversational-search dialog
    else Content found
        Dialog->>Dialog: Build activity with intent result, intent settings, and resolution
        Dialog->>User: Send activity to user
    end
    Dialog->>Dialog: End dialog

Docs:

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

Aura Bot generic-dialog v1

Dialog based on a simple configuration that allows managing several experiences for TV channels. This version is compatible with channelData v1.

Introduction

The generic-dialog allows OBs to implement certain local use cases for Movistar Home, Movistar Plus and Set-top Box (STB) channels in an autonomous, agile and simple way with no code development, only by means of configuration.

Use this generic-dialog if your channelData version is v1.

You can check its source code in Github: generic-dialog.ts.

Included intents

The next table shows current intents available on generic-dialog and the previous library where the intent was set.

Intent	Previous library
intent.common.goodbyes	common
intent.common.greetings	common
intent.common.help	common
intent.common.swearwords	common
intent.common.thankyous	common
intent.communications.silent_mode_on	communications
intent.communications.silent_mode_off	communications
intent.communications.call_voicemail	communications
intent.communications.add_contact	communications
intent.communications.phone_pick_up	communications
intent.communications.call	communications
intent.communications.call_by_number	communications
intent.communications.call_by_name	communications
intent.communications.check_calls	communications
intent.communications.redial	communications
intent.communications.ignore_calls	communications
intent.domotics.light_on	domotics
intent.domotics.light_off	domotics
intent.ecommerce.add_to_wish_list	ecommerce
intent.miscellaneous.radio_turn_off	miscellaneous
intent.miscellaneous.time_check	miscellaneous
intent.miscellaneous.weather_forecast	miscellaneous
intent.miscellaneous.news_listen	miscellaneous
intent.navigation.section_show	navigation
intent.navigation.back	navigation
intent.navigation.next	navigation
intent.navigation.previous	navigation
intent.carousel.info	tv
intent.tv.details	tv
intent.tv.help	tv
intent.tv.init	tv
intent.tv.from_beginning	tv
intent.tv.record	tv
intent.tv.channel_down	tv
intent.tv.channel_up	tv
intent.tv.move_backwards	tv
intent.tv.move_forwards	tv
intent.tv.mute	tv
intent.tv.unmute	tv
intent.tv.stop	tv
intent.tv.off	tv
intent.tv.on	tv
intent.tv.pause	tv
intent.tv.resume	tv
intent.tv.volume_down	tv
intent.tv.volume_up	tv
intent.tv.c2c	tv
intent.tv.content_get_info	tv
intent.tv.none	tv
intent.tv.question_time_loc	tv
intent.tv.search	tv
intent.tv.search_similar	tv
intent.tv.vod_epq_information	tv
intent.tv.watching_now	tv
intent.tv.suggestions	tv
intent.wifi.get_access	wifi

Generic indexed text

Generic dialog implements an algorithm, which based on a dialog configuration, can customize its response. The getIndexedText function returns a POEditor resource based on the dialog configuration’s setting indexedResourceBase and the value entity.entity obtained from the first entity. This functionality relies in those two values and will return an error if they are not present.

{
    "intent": "intent.exact-match.faq",
    "settings": {
        "indexedResourceBase": "generic:faq-answer.",
        "functions": {
            "params": [
                "context",
                "currentIntent",
                "persistentData"
            ],
            "algorithm": "getIndexedText"
        }
    }
}

In this example, the reference that will be searched in POEditor will be generic:faq-answer.X, where X is the identifier gathered from the first entity.

Keep in mind that in function.params there has to be an array of parameters that will be used in getIndexedText.

Enabling AI resolution

To enable the AI-based fallback mechanism, add the flag enableAIResolution to true inside the dialog configuration for the intent. This setting allows the dialog to use the ai recognizer when the NLP resolution returns no entities or when the Movistar Plus resolution returns no results.

Example configuration:

{
    "intent": "intent.tv.search",
    "settings": {
        "locales": {
            "error": [
                "core:flc.answer.error"
            ]
        },
        "enableAIResolution": true,
        "needTvResolution": true
    }
}

AI fallback resolution

When using generic-dialog v1 and needTvResolution is set to true, a fallback mechanism using AI services is available if enableAIResolution is set to true in the dialog configuration.

If NLP resolution returns no entities or when the Movistar Plus resolution returns no results, the system applies an AI-based fallback strategy (“triage”). This ensures robustness and continuity of the dialog flow.

The fallback is triggered in two scenarios:

No entities detected If the intent requires TV resolution and no entities are returned by the NLP (intentResult.entities?.length === 0), the dialog calls the recognizeUsingAI function. If a new intent is successfully recognized, the current dialog is replaced by the new one.
Movistar Plus resolution returns no results When the intent and entities are passed to Movistar Plus Resolution but no valid result is obtained (GENERIC_MP_RESOLUTION_NO_RESULT_CODE), the system again invokes recognizeUsingAI. A new intent will be attempted and, if available, the dialog is redirected accordingly.

In both cases, the interaction origin is marked as InteractionOriginType.NoResults.

Docs:

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

Aura Bot generic-dialog-v3

Dialog based on a simple configuration that allows managing several experiences for TV channels. This version is compatible with channelData v3.

Introduction

The generic-dialog-v3 allows OBs to implement certain local use cases for channelData v3 channels in an autonomous, agile and simple way with no code development, only by means of configuration.

You can check its source code in Github: generic-v3-dialog.ts.

Differences between generic dialog v1 and v3

These are the main differences in comparison with the generic-dialog v1:

Deprecated fields in dialog’s settings (dialogLibraries.dialogs.triggerConditions.settings):
- type, action, payload, addEntitiesToPayload, sound, payloadType and isFullScreen are no longer used.
- action, payload and sound configurations will be transformed to the new actions format and added to the new field actions.
New field actions: This field contains the configuration of all the actions returned inside the channelData.

Generic dialog environment variables

Generic

Property	Type	Scope	Description
TV_VOLUME_LEVELS_UP_DOWN	number	Local	Number of points at which the volume can be raised and lowered. By default `5`.
TV_MOVE_SECONDS_BACKWARD_FORWARD	number	Local	Number of seconds in which user can forward or rewind a video. By default `60`.
WIFI_FP_SMART_WIFI_ENDPOINT	string	Local	URL Kernel endpoint endpoint to interact with smart wifi API.
TV_TIMER_RECOGNIZER_FIRST_ENTITY_CONFIG	string	Local	Configuration of the recognition of entities with timer content in first position to calculate number of seconds. By default: `1 4:0.25,3 4s:0.75,4 de hora:0.25,hora:1.0,media:0.5,medio:0.5,minuto:1.0,un:1.0,un 4:0.25,una:1.0`.

| TV_TIMER_RECOGNIZER_SECOND_ENTITY_CONFIG | string | Local | Configuration of recognition of entities with timer content in second position to calculate number of seconds. By default: 1 4:0.25,3 4s:0.75,4 de hora:0.25,hora:1.0,media:0.5,medio:0.5,minuto:1.0,un:1.0,un 4:0.25,una:1.0,4:0.25. |

Generic dialog utilities

There are several functions that implement different requirements for the generic-dialog such as:

calculateSecondLevels: Calculate the value in seconds in case the entity type is not expressed in this format: ent.time_length_sec. Right now it only converts minutes into seconds.
getIndexedText: Get the text’s reference with information about the entity value.
getInfoWifiPlus: Retrieve Wi-Fi info.
getSecondsLevelsWithTimerRecognizer: Calculates the total number of seconds, based on the provided timer entities, making a recognition and conversion of them depending on the configuration of each country. The configuration is added in the environment variables: TV_TIMER_RECOGNIZER_FIRST_ENTITY_CONFIG and TV_TIMER_RECOGNIZER_SECOND_ENTITY_CONFIG.
getWifiInfo: Manage Wi-Fi data by setting the persistentData and the value of movistarPlusResolution.

AI fallback resolution

The configuration and fallback mechanism for AI resolution in generic-dialog-v3 are the same as in generic-dialog v1.

The only difference is in the second fallback condition:

In generic-dialog v1, the fallback is triggered when Movistar Plus resolution returns no results.
In generic-dialog v3, the fallback is triggered when the complex logic resolution process returns no results.

All other aspects (configuration with enableAIResolution, marking the interaction origin as InteractionOriginType.NoResults, and redirecting to the new dialog) remain exactly the same.

Docs:

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

Aura bridge global plugins catalog

Current global plugins developed in Aura bridge by the Aura Platform Team

Global plugins repository

Check the Github global plugins repository to see the currently available plugins in aura-bridge.

Aura Platform Team is progressively documenting each plugin within this section. The already documented ones include the corresponding link below.

admin-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/admin-api
async-callback-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/async-callback-directline-processor
auraline-conversation-api plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-conversation-api
- auraline-conversation-api plugin description
auraline-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-incoming-processor
- auraline-incoming-processor plugin description
auraline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/auraline-service
aurapush-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-incoming-processor
aurapush-sendfeedback-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/aurapush-sendfeedback-service
- aurapush-sendfeedback-service plugin description
directline-auraline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-auraline-processor
- directline-auraline-processor plugin description
directline-rcs-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-rcs-processor
- directline-rcs-processor plugin description
directline-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-service
- directline-service plugin description
directline-whatsapp-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-processor
directline-whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/directline-whatsapp-service
- directline-whatsapp-service plugin description
genesys-directline-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/genesys-directline-processor
- genesys-directline-processor plugin description
rcs-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-incoming-processor
rcs-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/rcs-service
whatsapp-incoming-processor plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-incoming-processor
whatsapp-service plugin
- https://github.com/Telefonica/aura-bridge/tree/master/src/plugins/whatsapp-service
- whatsapp-service plugin description

Docs:

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

Incoming Event middleware

Description of incoming-event-middleware, executed in event activity types.

Introduction

The incoming-event-middleware is in charge of managing events, that is, activities for the end-to-end communication between aura-bot and channels.

Channels can send events to aura-bot to inform about any relevant event happening on their side.
In particular, aura-bridge sends an event to aura-bot, when the transformation from bot activity to WhatsApp message fails, that is handled by this middleware.

When aura-bot receives an event, this middleware prevents the execution of the rest of the middlewares by completing the request flow.

There are two types of events:

Log type: the channel asks aura-bot to log certain information

emptyResponse type: Event sent by the bot when no response activity is sent. Currently, it is internally used for aura-bot towards aura-bridge.

export enum TypeEvent {
    /**
     * Log event
     */
    Log = 'log',
    /**
     * Directline empty response event (Event sent by the bot when no response activity is sent)
     */
    EmptyResponse = 'emptyResponse'
}

This middleware is executed once the HTTP request arrives at the server to the POST /api/messages endpoint and the Direct Line authentication executed by the Adapter is successful.

It is a Turn middleware, so it is executed during turn initialization. It is only executed if the type of the activity is event. In this case, the middleware records the KPIs and updates the context.

The source code of this middleware is included in Aura Bot Platform middlewares - Github repository.

Incoming Event flow diagram

The incoming-event-middleware flowchart is included below:

Docs:

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

Input validation video plugin

Docs:

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

Intent result recognizer

Description of intent-result-recognizer in charge of registering the intent result

Introduction

intent-result-recognizer is the recognizer in charge of the registration of the intent result.

This recognizer is executed after the execution of the middlewares and before sending a message to user. It is also in charge of registering the result of the intent in KPIs.

It receives information from the skill in the following way:

activity: {
    channelData: {
        payload: {
            skill: {
                intentResult: {
                    name: string,
                    entities: [
                        entity: string,
                        type: string
                    ]
                }
            }
        }
    }
}

Docs:

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

Internal API clients

Description of internal API clients implemented and used by aura-bot

Introduction

Internal API clients in Aura are associated with Aura servers. They are automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

The self-generated clients are clients automatically generated and published with changes in the API definition of its server during the CI execution, the developer does nothing to update it.

Almost all servers developed by the aura-bot team belong to this set, but not all. For instance, aura-bridge client, as its complete swagger is built out of the different partial swaggers of aura-bridge core and all its plugins, is generated and stored in aura-clients repository instead of in aura-bridge repository, as would happen with the self-generated clients.

Aura cognitive client

This client provides a set of classes to interact with the Telefónica Cognitive Service. It implements version 3.4.0.

These classes are:

DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service. This service is no longer used by aura-bot, because the updated version is the one available in aura-nlp-client.
InsightsResolutionApi: interaction with Telefónica’s Insights Resolution Classifier Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
SuggestionsApi: interaction with Telefónica’s Suggestions Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
NotificationsFilterApi: interaction with the Telefónica’s NotificationFilter Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-cognitive-client/

📄 Access this API client in the Github repository: aura-cognitive-client

Movistar+ cognitive client

This client provides a set of classes to interact with the Movistar+ cognitive Service.

These classes are:

MovistarPlusCognitiveClient: Interaction with Movistar+ Resolution Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.
MovistarPlusCognitiveStatusClient: Interaction with Movistar+ Resolution Status Cognitive Service passing the base path where the service is hosted and the user OAuth access token to use when interacting with the remote service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/movistar-plus-cognitive-client/

Aura NLP client

This client implements the internal NLP API that provides access to the aura-bot nlp-recognizer-middleware. It implements the client for the 3.0.0. version of the API.

It provides access to DomainClassifierApi: interaction with Telefónica’s Domain Classifier Cognitive Service.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-nlp-client/

📄 Access the aura-nlp API definition

Aura authentication client (autogenerated)

This client implements the internal authentication API that provides access to the Aura user’s service. It implements the client for the 2.2.0. version of the API and provides access to UsersApi.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/authentication-api-client/

📄 Access the aura-authentication-api API definition

Find more information in the Github repository:

Aura File Manager client

This client implements the internal API that provides access to the aura-file-manager component. It implements the client for the 2.2.0. version of the API and provides access to the File Manager API, microservice responsible of handling attached files storage and validations at channel level.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-file-manager-client/

📄 Access the aura-file-manager API definition

Aura Configuration Client

This client implements the API that provides access to the aura-configuration-api component. It implements the client for the 2.3.0. version of the API.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-configuration-api-client/

📄 Access the aura-configuration-api API definition

Aura Bridge client

The aura-bridge client contains a set of endpoints that support aura-bridge, that is, Aura component in charge of adapting the communication protocol between aura-groot and certain external channels, such as Whatsapp, that cannot implement the Direct Line protocol.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-bridge-client/

📄 Access the aura-bridge API definition

Aura Complex Logic client

This client implements the API that provides access to the aura-complex-logic component in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/complex-logic-client/

📄 Access the aura-complex-logic API definition

Aura Gateway API client

This client implements the API that provides access to the aura-gateway-api service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-gateway-api-client/

📄 Access the aura-gateway-api API definition

Agents Manager API client

This client implements the API that provides access to the agents-manager service in Aura.

Find more information in the Github repository: https://github.com/Telefonica/aura-common-utilities/tree/master/packages/aura-clients/src/aura-agents-manager-client/

Docs:

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

Introduction to ATRIA

Discover in this document the fundamentals and advantages of ATRIA (Artificial Trusted Intelligence by Aura)

What is ATRIA?

The world of Artificial Intelligence (AI) is revolutionizing virtual assistants by integrating advanced AI-based algorithms to understand, anticipate and respond to the users’ needs.

In this framework, ATRIA is a platform that integrates multiple AI technologies, both proprietary and third-party ones, enabling products and services to build experiences flexibly, leveraging the advanced functionalities of AI in a secure and controlled manner.

Figure 1. What is ATRIA?

The innovative solution of ATRIA as a platform that integrates different AI technologies empowers our users to effortlessly incorporate advanced capabilities based on Artificial Intelligence into their products or services.

This can be done in an efficient and secure way through AI-driven capabilities included in ATRIA that are accessible via APIs exposed in Kernel, the Telefónica digital ecosystem, which is founded on the principle of maintaining privacy and security.

Key ATRIA features

The design of ATRIA provides the following main features:

ATRIA features

AI services aggregator, as our platform allows a seamless integration of AI-powered technologies for language detection

Natural language interactions, as ATRIA supports an easy and intuitive communication with its users

Multi-brand, as within an OB, it can be accessible through diverse brands, each of them with different channels and use cases

Multi-language RAG pipeline, enabling the automated detection of the language of each request and delivering the most relevant response in the same language if the RAG capability is used

ATRIA enables data persistence in knowledge bases across releases, ensuring that all existing data remains fully available and accessible for every ATRIA experience independently of the deployed version.

Privacy and security, as ATRIA is accessible through APIs exposed in Kernel, providing robust protection for data and user information

ATRIA functional overview

The following diagram shows how ATRIA operates and its communication flow at a high level:

Figure 2. ATRIA overview

The user accesses ATRIA through one of the brands that the OB uses to commercialize its services and sends a request.
First, the request passes through Kernel (Telefónica Digital Ecosystem) for authentication and security purposes.
ATRIA derives the input information to the corresponding AI-driven capability to be used, previously set in configuration.
The capability uses the specific AI technology to generate the most relevant response, which is provided back to the user.

ATRIA benefits

ATRIA platform provides key advantages from the use of its AI-powered capabilities, both for constructors and end users, which are summarized below:

Innovation and integration
ATRIA facilitates an easy and straightforward integration of AI technologies, powered by our in-house team of experts dedicated to continuous research and implementation of innovations in AI and prompt engineering.
Accuracy
Leveraging advanced AI capabilities, ATRIA delivers precise and coherent responses that align closely with user’s requests, enhancing satisfaction and fostering greater interaction.
Security in interactions
ATRIA guarantees security against malicious attacks aiming to change the purpose of AI and, additionally, provides mechanisms that ensure privacy and prevent access to, or leakage of, sensitive data from the system.
Compatibility with Kernel
ATRIA is compatible with Telefónica Kernel, the technological service that integrates data and APIs from Telefónica services, assuring efficiency, as well as data privacy and control.
Ethical and responsible AI
ATRIA preserves the ethical uses of AI by not allowing misuse by individuals or systems, implementing control mechanisms in requests and verifying AI responses.
Efficiency and time saving
ATRIA automates tasks, enabling users to complete actions more efficiently. This leads to significant time savings as routine and time-consuming activities can be handled seamlessly.

Docs:

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

Introduction to Aura Virtual Assistant

Discover in this document the fundamentals and advantages of Aura Virtual Assistant

What is Aura Virtual Assistant?

Aura Virtual Assistant is the new relationship with our clients. A cutting-edge digital assistant accessible through different channels, brands and devices, that understands our customers’ needs expressed in natural language and offers personalized responses in real time.

Figure 1. Aura Virtual Assistant

Aura Virtual Assistant is able to:

Talk and establish conversations with the users, as it is based on a conversational design to provide a natural experience through several channels and using different brands
Understand and recognize the user’s requests: Leveraging Cognitive Services, Aura Virtual Assistant offers natural language processing capabilities for an accurate communication with the customers, depending on channel capabilities and usability criteria.
Resolve: Aura Virtual Assistant builds the logic of different types of experiences and provides precise answers to our customers in real time.

Key Aura Virtual Assistant features

Aura Virtual Assistant is designed as a distributed ecosystem, within an architecture evolution at the forefront of the latest advances in software architecture.

In this framework, it is conceived as a multi-bot system based on Microsoft skills architecture, that offers the following capabilities:

Aura Virtual Assistant is:

Multichannel, as it can be integrated into different channels, both third-party and Telefónica ones.

Multibrand, as within an OB, it can be accessible through diverse brands, each of them with different channels and use cases

Multi-communication mode, allowing text, voice or tap-based interaction through different devices.

It enables and accelerates the creation and integration of skills-bots across channels, for Telefónica users to manage their digital services and deliver rich experiences, while ensuring data privacy and security.

It has a specific personality and tone, consistent through channels.

It includes a set of use cases and prebuilt bots (as the video one).

It offers a series of capabilities and tools to create locally relevant experiences for the user.

It enables the connection with ATRIA for leveraging cutting-edge AI capabilities.

It broadens the spectrum of technologies that can be connected to Aura.

Aura Virtual Assistant functional overview

The following diagram shows how Aura Virtual Assistant operates and its communication flow at a high level:

Figure 2. Aura Virtual Assistant functional overview

The user accesses Aura through one of the brands through which the OB commercializes its services.
The user sends a request to Aura through a specific channel available for the selected brand, which is the communication mean a Telefónica client must use to interact with Aura.
Then, Aura Root component, which is the core block of Aura Virtual Assistant functionalities, receives the request and redirects it to the best skill to answer it.
This skill, which is a bot with specific expertise and features, understands the request and resolves it. If required, it retrieves data from Kernel.
Aura Root provides the response back to the user through the intended channel.

Discover more details of Aura Virtual Assistant functional operation and its functional components in the document Aura Virtual Assistant functional description.

Are you a highly-skilled technician? Access here technical documents related to Aura Virtual Assistant:

Benefits from using Aura Virtual Assistant

Benefits for Aura end-users

Key advantages	Enhancements for Aura
Easier relationship	Aura Virtual Assistant enhances customer relationships and improves business automation, efficiency, and transversal intelligence within the digital ecosystem.
Improved user’s experience	Aura can easily integrate cutting-edge AI technologies to improve Aura capabilities, thus offering a wider range of experiences together with more accurate and enriched responses to the users, while ensuring data privacy and security.
Consistency	The user will always have the same experience regardless of the channel she is using, as there will not be different use cases depending on the channel
Ready for future challenges	The quick and easy integration of technologies broadens the capabilities of Aura, that can take advantage of state-of-the-art solutions from different partners to be connected to Aura

Benefits for Aura IT Teams

Key advantages	Enhancements for Aura
Efficiency	Multibot architecture can perform tasks more efficiently due to the skills isolation. Each skill can be deployed and work independently, leading to better overall performance and resources utilization.
Scalability and flexibility	The separation of Aura functionalities (logic, training, routing, deployment, etc.) allows a cost and time-effective strategy for extending Aura capabilities without affecting other components
Autonomy	The new architecture allows an easy integration of multivendor development tools (such as Microsoft Composer, Teneo), third-party bots or innovative cognitive components (for example, KSolr, MSFT Language Studio, Azure OpenAI models).
Deployment simplification	The separation of Aura into different functional blocks and the skills isolation facilitate the installation, as only the specific component/feature to be deployed is affected, without the need for global re-deployments
Resilience	Multibot architecture improves fault-tolerance. If a single component fails, the whole system can continue functioning
Enrichment mechanisms	Aura can incorporate tools able to add additional information both to the user’s request (better resolution) and to the response (relevant information for the user) through the integration of Advanced Analytics Models (AAMs) and contextual information

Docs:

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

Key ATRIA concepts

Explore the ATRIA the essential components constructors need to understand in order to build experiences with ATRIA AI-driven capabilities

ATRIA use cases constructors

Preset

The preset is the key entity for the configuration of ATRIA. It is like a recipe for your experience, that defines which ingredients to use and in what amounts.

Technically, the preset is a JSON file that defines a hierarchy of both required and optional configuration parameters for the use case configuration.

ATRIA preset

Once the constructors have defined a preset, it must be included in an application to be used by ATRIA.

Prompt

Within an ATRIA preset, a prompt is defined as an input instruction given to an AI model to generate a response. It guides the AI in the required kind of output we want as constructors.

Application

From the constructor’s point of view, an application can be defined as a container for ATRIA presets.

When developing a use case, constructors should use an existing application or create a new one in order to:

Define the specific ATRIA capabilities that can be used, currently Generative AI, RAG, NLP as a Service and Semantic Search.
Declare the presets that this application can use.

Highlights

Every preset and application is identified by both a name and an ID.
To be used and tested, a preset must be placed inside an application (folder).
Nested applications are not allowed. The hierarchy is: application → preset.
An application can contain one or more presets.
A single preset can belong to multiple applications. When you update the preset, it will be updated in all applications it is associated with.

Definition of presets in an application
Each environment can be considered as an independent container of applications and presets. Consequently, if you update a preset in one environment, another preset with the same ID will not be updated in a different environment.

Access technical documentation

Do you need more technical information regarding ATRIA components? Access here:

ATRIA technical components

Docs:

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

Aura Groot middlewares

Description of middlewares included in aura-groot

Introduction

The current document describes the different middlewares that are part of aura-groot

init-middleware

This middleware is in charge of setting the initial context values (userData accessor, conversationData accessor, correlator) for the rest of the middlewares/handlers.

user-middleware

In this middleware, the user is checked and stored in context for the following middlewares/handlers.

Find detailed information in user-middleware documentation.

channeldata-validator-middleware

This middleware validates input channelData activities and throws an error if something is wrong.

Find more information in channeldata-validator-middleware documentation.

Docs:

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

Agents Manager API plugins

agents-manager plugins are components that provide different functionalities to agents-manager

Introduction

agents-manager is composed of plugins, which provide functionality to this component. Plugins work independently, the same way as a service in microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

From the different types of plugins, only Api plugins are available in agents-manager.

The following plugins are currently available in agents-manager. Certain plugins are used by all or some of the other plugins and others are specific for one capability.

agent-dispatcher-api plugin
This plugin manages request to Agent Dispatcher API.
development-api plugin
This plugin manages configuration in development environments. Only available in development environments.
configuration-service plugin
This plugin manages requests to Agent Configuration.
redis-connector-service plugin
This plugin manages requests to Redis.
session-service plugin
This plugin manages the sessions.
agent-deployment plugin, that provides deployment functionalities for agents within the agents-manager. Plugin currently deactivated.

Discover detailed information regarding the available plugins in the left index.

Plugins management

agents-manager uses the @architect/architect library for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, agents-manager uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the agents-manager start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the agents-manager component.
It adds the core modules to the IOC context. See the section plugins modules.
It stores the information of each module defined in the plugins.

Apart from the agents-manager core environment variables, each plugin can define its own specific variables. Access the document agents-manager environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, agents-manager uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

session-api
├── index.ts
└── package.json

Plugins modules

agents-manager currently adds one module that can be used by the different plugins. To use it, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the agents-manager configuration information.
redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to agents-manager.

Docs:

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

Aura gateway API plugins

aura-gateway-api plugins are components that provide different functionalities to aura-gateway-api

Introduction

aura-gateway-api is composed of plugins, which provide functionality to this component. Plugins work independently, the same way as a service in microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

From the different types of plugins, only Api plugins are available in aura-gateway-api.

The following plugins are currently available in aura-gateway-api. From the different ATRIA capabilities that this component can manage, certain plugins are used by all or some of them and others are specific of one capability.

aura-generative-api plugin
This module manages request to external OpenAI APIs.
aura-generative-process-service plugin
This module manages the communication and data processing with external OpenAI APIs.
aura-nlp-resolution plugin
This module manages the request to NLP services.
aura-nlp-resolution-process-services plugin
This module manages the communication and data processing with external NLP services.
aura-development-api plugin
This module manages configuration in development environments. Only available in development environments.
aura-feedback-api plugin
This module manages requests to provide feedback about the generative and RAG services behavior.
aura-agents-api plugin
This module manages the communication with agents.
dapr-pubsub-service plugin This plugin allows the interaction with the Dapr PubSub Service.
aura-operations-api plugin
This module allows you to perform operations on now, currently launching the generateDB

Discover detailed information regarding the available plugins in the left index.

Plugins management

aura-gateway-api uses the @architect/architect library for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-gateway-api uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-gateway-api start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-gateway-api component.
It adds the core modules to the IOC context. See the section plugins modules.
It stores the information of each module defined in the plugins.

Apart from the aura-gateway-api core environment variables, each plugin can define its own specific variables. Access the document aura-gateway-api environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, aura-gateway-api uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

session-api
├── index.ts
└── package.json

Plugins modules

aura-gateway-api currently adds one module that can be used by the different plugins. To use it, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-gateway-api configuration information.
redisConnector: Module with the aura-gateway-api Redis connection.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-gateway-api.

Docs:

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

Aura bridge plugins

Aura bridge plugins are components that provide different functionalities to the bridge

Introduction

aura-bridge is composed of plugins, which provide functionality to the bridge. Plugins work independently, the same way as a service in a microservices oriented architecture: isolated, self-contained and without affecting other existing functionalities in the system.

The aura-bridge plugins system also allows an OB to generate new plugins and create an “ad hoc” aura-bridge, with the functionalities required and removing those which are not needed for the OB.

ℹ️ The practical process for the generation of plugins is included in develop a plugin and activate in aura-bridge.

Discover in the current documents detailed information regarding aura-bridge plugins:

Types of plugins

There are different types of plugins:

Api. REST services that perform specific tasks not associated with the communication with a channel.
Client. These plugins define clients that can be used to communicate with a channel. These clients are normally used by processor plugins.
Processor. Plugins in charge of communicating with a channel, transforming the message received from a source channel to a destination channel.
Service. Utility plugins to be used by the rest of plugins.

Plugins management

As indicated in the previous section, aura-bridge uses the library@architect/architect for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-bridge uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-bridge start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-bridge component.
It adds the core modules to the IOC context. See the section modules added by aura-bridge.
It stores the information of each module defined in the plugins.

An example to define aura-bridge-example-service plugin of the previous section is shown below:

/* file: plugin-config.json */
[
    "./lib/plugins/aura-bridge-example-service",
]

Currently, the plugins are in the src/plugins folder of aura-bridge, but in the future these plugins should be independent libraries and could be charged by library name (for example: @telefonica/aura-bridge-example-service).

Apart from the aura-bridge core environment variables, each plugin can define its own specific variables. Access the document Aura bridge environment variables and find them in the section corresponding to your plugin.

Plugin basic structure

Currently, aura-bridge uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

aura-bridge-example-service
├── index.ts
└── package.json

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { v4 as uuidv4 } from 'uuid';
import { Services } from './example-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin service type
        name: 'exampleService',         // Name of the plugin service
        instance: {                     // [provides] Instance that provides the module
            getUniqueId() {
                return uuidv4();
            }
        },
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "exampleService"
        ]
    }
}

The modules specified in the plugin.consumes field define the services that are needed by this plugin. The modules specified in the plugin.provides field define the modules that this plugin offered.

Plugins modules

aura-bridge currently adds three modules that can be used by the different plugins. To use them, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-bridge configuration information.
auraBridgeCache: Module to manage the aura-bridge cache.
prometheus: Service for metrics management.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-bridge.

The existing types are defined in PluginType, which are described in the following sections.

export enum PluginType {
    Api = 'Api',
    Client = 'Client',
    Processor = 'Processor',
    Service = 'Service'
}

All plugins modules must follow the base Plugin interface:

export interface Plugin {
    /**
     * Plugin module name.
     */
    name: string;
    /**
     * Object where the services that plugin module consume will be injected (IOC).
     */
    services?: unknown;
    /**
     * Plugin module type.
     */
    type?: PluginType;
    /**
     * @hapi/joi schema definition with the variables used by the plugin module.
     */
    configuration?: { [key: string]: any; };
}

API plugin module

Use the aucli tool to generate the scaffolding of an API plugin: aucli bridge generate api

An API plugin module type mainly contains:

At least one source code file that defines the API plugin module and controllers for each of the operations specified in the swagger definition.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.
A swagger.yaml file that contains a detailed description of the entire API defined by the plugin.

The basic structure for a API plugin module type is as follows:

aura-bridge-example-api
├── index.ts
├── package.json
└── swagger.yaml

A type API module must implement the PluginApi interface:

export interface PluginApi extends Plugin {
    /**
     * List of controllers (Express) defined by the plugin module.
     */
    controller: { [operationId: string]: PluginApiController | ((req: Request, res: Response) => Promise<void>) };
}

export interface PluginApiController {
    /**
     * Is directline processor?
     */
    isDirectlineProcessor?: boolean;
    /**
     * Channel type.
     */
    channelType?: BridgeType;
    /**
     * Express controller function.
     */
    controller: (req: Request, res: Response) => Promise<void>;
    /**
     * Custom error handler.
     */
    errorHandler?: (err: any, request: express.Request, response: express.Response, next: express.NextFunction) => void;
}

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { Services } from './example-api-consume-services';

const controller = {
    hello: (req: Request, res: Response) => {
        res.send({ message: 'Hello from example api!' });
    }
}

export = registerPlugin([
    {
        type: PluginType.Api,           // Plugin module type
        name: 'exampleApi',             // Plugin module name
        controller,                     // Controllers definitions (linked to swagger operationId),
                                        // or it is possible to also use the PluginApiController interface
        services: Services,             // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-api",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ],
        "provides": [
            "exampleApi"
        ]
    }
}

# file: swagger.yaml
openapi: 3.0.0
info:
  title: aura bridge example api
...
paths:
  /example/hello:
   get:
     operationId: hello             # Function name defined in "controller".
     x-router-controller: plugins   # It should always be "plugins".
     responses:
       '200':
         description: OK
         headers: { }

An API module can also define its own error handling and not use the default error handling defined in the bridge core.

Example:

public errorHandler(err: any, request: express.Request, response: express.Response, next: express.NextFunction) {
    const corr = (request as any).correlator;

    let status: number = 200;
    let message: string = 'Accepted request';

    if (err.statusCode === 401) {
        status = err.statusCode;
        message = 'Unauthorized request';
    }

    // An error in swagger validation is simply logged as a warning
    if (err.failedValidation) {
        logger.warning({
            msg: `Bad request on swagger validation. The first error message was: ${err?.validationResult[0]?.message}`,
            stck: err.validationResult, corr,
            step: AuraBridgeStep.Controller
        });
    }

    response.status(status).send({ code: status, message });
}

Client module

Use the aucli tool to generate the scaffolding of a client module: aucli bridge generate client

A client module type mainly contains:

At least one source code file that defines the client module and the client itself.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.

The basic structure for a client module type is as follows:

aura-bridge-example-client
├── index.ts
├── package.json

A type client module must implement the PluginClient interface:

export interface PluginClient extends Plugin {
    /**
     * Client instance.
     */
    instance?: any;
    /**
     * Returns a client instance if it must be initiated asynchronously.
     */
    getInstance?: () => any;
}

The instance field or the getInstance method should be used to obtain the client, but not both. If the client does not need to be initiated asynchronously, the client definition in the instance field is the preferred option. If it is necessary to asynchronously start the client, the getInstance method must be used.

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
import { Services } from './example-consume-services';
import { ExampleClient } from './example-client';

export = registerPlugin([
    {
        type: PluginType.Client,
        name: 'ExampleClient',
        instance: new ExampleClient(),
        services: Services
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-client",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "ExampleClient"
        ]
    }
}

/* file: example-client.ts */
import { AuraBridgeClient, AuraBridgeRequestInfo, SendMessageOptions } from '@telefonica/aura-bridge-common';
import { AuraLogger } from '@telefonica/aura-logging';
import { Services } from './example-consume-services';

const logger: AuraLogger.AuraBusEmitter = new AuraLogger.AuraBusEmitter('ExampleClient');

export class ExampleClient extends AuraBridgeClient {
    public constructor() {
        super('ExampleClient', Services.configurationManager.environmentConfiguration);
    }

    public async sendMessage(message: any, options: SendMessageOptions): Promise<void> {
        const { corr }: Partial<AuraBridgeRequestInfo> = options.requestInfo;
        // TODO: Implement the message sending logic here.
    }
}

A basic client should only extend the AuraBridgeClient class and implement the sendMessage method. The client can define any other method, but the sendMessage method will be used by the processors to send a message to a destination.

If the client uses the OAuth protocol, it is possible to add the OpenID authorization information to the client and automatically update the access token for the communication. To make use of this functionality, it is necessary that the new client extends from AuraBridgeClientOAuthTokens class instead of AuraBridgeClient class:

/* file: example-client.ts */
import { AuraBridgeClientOAuthTokens, AuraBridgeRequestInfo, SendMessageOptions } from '@telefonica/aura-bridge-common';
import { AuraLogger } from '@telefonica/aura-logging';
import { Services } from './example-consume-services';

const logger: AuraLogger.AuraBusEmitter = new AuraLogger.AuraBusEmitter('ExampleClient');

export class ExampleClient extends AuraBridgeClientOAuthTokens {
    public constructor() {
        super(
            'ExampleClient',
            Services.configurationManager.environmentConfiguration,
            [] // TODO: Add list ClientOAuthInformation here
        );
    }

    public async init(): Promise<void> {
        await this.refreshTokens();    // <-- It is responsible for updating the tokens before it expire.
    }

    public async sendMessage(message: any, options: SendMessageOptions): Promise<void> {
        const { corr }: Partial<AuraBridgeRequestInfo> = options.requestInfo;
        // TODO: Implement the message sending logic here.
    }
}

In addition to the refreshTokens method, the AuraBridgeClientOAuthTokens class defines the following methods:

addOpenIdClients: Add new clients to the list to update your tokens.
getTokenByClientId: Get token by client id.
stopRefreshTokens: Stop refresh client tokens.

Processor module

Use the aucli tool to generate the scaffolding of a processor module: aucli bridge generate processor.

As a general rule, a processor is responsible for converting an input message (from a “source” channel) to an output message (that will be sent to a “destination” channel).

Processor flow

To help with the task of generating a processor (in addition to the aucli tool) , the aura-bridge-common library provides the AuraBridgeFlow class that allows to define the converter and the client that will be used to convert and send the incoming message to the destination in a simple and declarative way.

const flow: BridgeFlow = {
    source: {                               // Source from where the request is initiated
        type: BridgeNodeType.Directline
    },
    destination: {                          // Destination where the request will be redirected
        type: BridgeNodeType.TestModel,
        converter: DirectlineToTestModelConverter,
        client: services.testModelClient,
        clientOptions: { queue: { bridgeFlowName: directlineToTestModelFlow.name } }
    },
    onError: {
        // ...
    }
};

In the same way, in case an exception occurs, it is possible to define the list of channels that should be informed.

const flow: BridgeFlow = {
    source: {
        // ...
    },
    destination: {
        // ...
    },
    onError: {                          // How and which channels should be informed on exception
        destinations: [
            {
                type: BridgeNodeType.TestModel,
                converter: ErrorToTestModelApiConverter,
                client: services.testModelClient,
                decode: TestModelDestinationResponseError
            },
            {
                type: BridgeNodeType.Directline,
                converter: ErrorToDirectlineEventConverter,
                client: services.directlineClient,
                decode: directlineDestinationResponseError
            }
        ]
    }
};

Declaring a destination

The destination field must follow the interface BridgeDestination.

export interface BridgeDestination extends BridgeNode {
    /**
     * Client instance that will be used to send the message to the destination
     */
    client: AuraBridgeClient;
    /**
     * Client options. System to send the message used: queue, retries, etc
     */
    clientOptions?: SendMessageClientOptions;
    /**
     * Converter to use
     */
    converter?: AuraBridgeMessageConverter;
    /**
     * Relationship between exception and response error
     */
    decode?: ExceptionResponseError[];
    /**
     * Optional condition for a destination to be executed
     */
    condition?: (error?: Error, lastError?: Error, requestInfo?: AuraBridgeRequestInfo, message?: any) => boolean;
}

The process to send a message using the previous definition is shown below:

If the indicated condition is true, the message will be converted (using converter) and sent (using client with options defined in clientOptions field). If during the process there is an error that throws an exception, all the destinations defined in onError.destinations field will be executed in order in the same way.

The following diagram shows the execution sequence:

flowchart LR
    subgraph source
        A[Message]
    end
    subgraph destination
    direction LR
        A[Message] --> Check{check condition}
        Check -->|True| Converter[Converter]
        Check -->|False| End[end]
        Converter --> |Converted message| Client[Client]
        help[Send message using clientOptions]
    end

When an exception is thrown, all the destinations defined in onError.Destinations are processed, passing both the original message and the exception occurred:

flowchart LR
    subgraph onError information
        Message[Message]
        Exception[Exception message]
    end
    subgraph onError destinations
    direction LR
        Message[Message] --> CheckOnError{check condition}
        Exception --> CheckOnError{check condition}
        CheckOnError -->|True| ConverterOnError[Converter]
        CheckOnError -->|False| EndOnError[Next destination]
        ConverterOnError --> |Converted message| ClientOnError[Client]
        helpOnError[Send message using clientOptions]
    end

Sending a specific message on exception

When an exception occurred during the execution of a flow (BridgeFlow), it is possible to decode the exception in a specific error message for each destination defined in onError.destinations field.

The list that relates the exception with each message is added in the field decode of BridgeDestination. Each of these elements must implement the following interface:

/**
 * @interface ExceptionResponseError
 */
export interface ExceptionResponseError {
    /**
     * Name error from exception
     */
    name?: string;
    /**
     * Message to user key
     */
    messageToUserKey?: string;
    /**
     * Error status from exception
     */
    status?: number;
    /**
     * Error response code
     */
    responseCode?: string;
    /**
     * Response error information
     */
    response: ResponseError;
}

In the following code, the example shows how to send a message with status 500 and message key bridge:error.transform when an error in the converter has occurred:

const exampleResponseError: ExceptionResponseError[] = [
    {
        name: AuraBridgeConverterError.name,
        response: {
            status: StatusCodes.INTERNAL_SERVER_ERROR,
            description: 'Internal bridge error converting input message to output format',
            messageToUserKey: 'bridge:error.transform'
        }
    }
];

Basic structure of the processor module

The processor module type mainly contains:

At least one source code file that defines the processor plugin module and controllers for each of the operations specified in the swagger definition.
A package.json file defining the library, with a plugin section defining which modules it consumes and supplies.
A swagger.yaml file that contains a detailed description of the entire API defined by the plugin.
A source code file that defines the BridgeFlow.
A source code file that defines the AuraBridgeMessageConverter.

The basic structure for a processor plugin module type is as follows:

aura-bridge-example-processor
├── index.ts            # Processor plugin module and controller
├── converter.ts        # Converter (AuraBridgeMessageConverter)
├── flow.ts             # Flow (BridgeFlow)
├── package.json
└── swagger.yaml        # Api definition

A type processor module must implement the PluginProcessor interface:

export interface PluginProcessor extends PluginApi {
    /**
     * List of defined flows.
     */
    flows: BridgeFlow[];
}

In addition to the definition of flows, the same requirements as for an API plugin type are applied.

If the processor plugin must manage the aura-groot response (using DirectLine) for a channel type, it is possible to use the PluginApiController interface to define the controller.

For example:

/* Manage aura-groot response messages for whatsapp channels */
postDirectlineConversationsActivities: {
    isDirectlineProcessor: true,                            // Indicates if it is a directline processor
    channelType: BridgeType.Whatsapp,                      // Channel type
    controller: directlineWhatsappController.controller     // Controller definition
}

In this way, all the messages sent for the WhatsApp type channel to /aura-services/{channelName}/v3/conversations/{conversationId}/activities and /aura-services/{channelName}/v3/conversations/{conversationId}/activities/{messageId} endpoints will be managed by the defined controller.

⚠️ These endpoints do not need to be defined in the plugin swagger, since they are supplied by the aura-bridge core.

A couple of examples with the content of each file are shown below:

/* file: index.ts */
/* description: Using controller function */

import ...

const controller = {
    exampleNotification: async (req: Request, res: Response) => {
        const env = Services.configurationManager.environmentConfiguration;
        res.status(200).send();
        await AuraBridgeFlow.process(exampleToDirectlineFlow(Services), getRequestInformation(req, env), req.body);
    }
};

export = registerPlugin([
    {
        type: PluginType.Processor,         // Plugin module type
        name: 'exampleProcessor',           // Plugin module name
        controller,                         // Controllers definitions (linked to swagger operationId)
        flows: [exampleToDirectlineFlow],   // Flows
        services: Services                  // [consumes] Needed modules are added here
    }
]);

/* file: index.ts */
/* description: Using PluginApiController interface */

import ...

const controller = {
    // This plugin manages all the requests from aura-groot for the testModel channel type destination
    postDirectlineConversationsActivities: {
        isDirectlineProcessor: true,
        channelType: BridgeType.TestModel,
        controller:  async (req: Request, res: Response) => {
            ...
        }
    }
};

export = registerPlugin([
    {
        type: PluginType.Processor,         // Plugin module type
        name: 'directlineTestModelProcessor',    // Plugin module name
        controller,                         // Controllers definitions (linked to swagger operationId)
        flows: [exampleToDirectlineFlow],   // Flows
        services: Services                  // [consumes] Needed modules are added here
    }
]);

/* file: converter.ts */
import ...

export class ExampleConverter extends AuraBridgeMessageConverter {
    public static async message(incomingMessage: ExampleMessage) {
        // Logic of the converter here
    }
}

/* file: flow.ts */
/**
 * Flow: example to directline.
 *
 *
 * [Example] ─────> (bridge) ───(ok)──────> [Directline]
 *
 * @returns {BridgeFlow} flow
 */
export function asyncCallbackToDirectlineFlow(services: any): BridgeFlow {
    const flow: BridgeFlow = {
        source: {
            type: BridgeNodeType.Example
        },
        destination: {
            type: BridgeNodeType.Directline,
            converter: ExampleConverter,
            client: services.directlineClient,
            clientOptions: { retries: {} }
        },
        onError: {
            destinations: [
                ...
            ]
        }
    };

    return flow;
}

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-processor",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ... ],
        "provides": [
            "exampleProcessor"
        ]
    }
}

# file: swagger.yaml
openapi: 3.0.0
info:
  title: aura bridge example processor
...
paths:
  /example/notification:
   get:
     operationId: exampleNotification       # Function name defined in "controller".
     x-router-controller: plugins           # It should always be "plugins".
     responses:
       '200':
         description: OK
         headers: { }

Service module

Use the aucli tool to generate the scaffolding of a service plugin: aucli bridge generate service

A service plugin module is a set of utilities that can be reused by the rest of plugins and mainly contains:

At least one source code file that defines the service plugin module and the service itself.
A package.json file defining the library, with a plugin section defining that modules consume and supplies.

The basic structure for a service plugin module type is as follows:

aura-bridge-example-service
├── index.ts
└── package.json

A type service module must implement the PluginService interface:

export interface PluginService extends Plugin {
    /**
     * Service instance.
     */
    instance?: any;
    /**
     * Returns a service instance if it must be initiated asynchronously.
     */
    getInstance?: () => any;
}

The instance field or the getInstance method should be used to obtain the service, but not both. If the service does not need to be initiated asynchronously, the service definition in the instance field is the preferred option. If it is necessary to asynchronously start the service, the getInstance method must be used.

A couple of examples with the content of each file are shown below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/aura-bridge-common';
...

const exampleService = {
    isActionMessage: (message: ExampleMesageModel) => {
        return !!message?.channelData?.customData?.action;
    }
}

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin module type
        name: 'exampleService',         // Plugin module name
        instance: exampleService,       // Service instance
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-bridge-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [ ],
        "provides": [
            "exampleService"
        ]
    }
}

Plugins in specific channels

There is a relationship between a channel and the different plugins that give full support to the channel in aura-bridge. This is because plugins can supply: services, incoming messages management, output messages management, etc.

Therefore, to support a channel like WhatsApp, several plugins may be necessary and knowing that relationship allows to enable/disable the support to the complete channel in aura-bridge correctly.

Plugins for WhatsApp channel

Plugin	Dependencies	Core dependencies
whatsapp-incoming-processor	whatsapp-service, directline-service	configurationManager, prometheus
directline-whatsapp-processor	whatsapp-service, directline-service	configurationManager
directline-whatsapp-service	whatsapp-service, directline-service	configurationManager
whatsapp-service		configurationManager, prometheus
directline-service		configurationManager, auraBridgeCache

How to disable the WhatsApp channel

To disable the WhatsApp channel, it is necessary to take into account the following:

The whatsapp-incoming-processor and directline-whatsapp-processor plugins are not dependent on any other plugin, so they can be removed from the plugin-config.json file.
The directline-whatsapp-service, whatsapp-service and directline-service plugins can be used by other plugins and can only be removed if they are not needed.

Plugins for async-callback

Plugin	Dependencies	Core dependencies
async-callback-directline-processor	directline-service	configurationManager, prometheus

How to disable the async-callback functionality

The async-callback-directline-processor plugin is not dependent on any other plugin, so it can be removed from the plugin-config.json file to completely disable the async-callback functionality.

Plugins for Genesys

Plugin	Dependencies	Core dependencies
genesys-directline-processor	directline-service	configurationManager

How to disable the Genesys functionality

The genesys-directline-processor plugin is not dependent on any other plugin, so it can be removed from the plugin-config.json file to completely disable the Genesys functionality.

Docs:

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

Aura mocks server plugins

aura-mocks-server plugins are components that provide different functionalities to this component

Introduction

aura-mocks-server is composed of plugins, which provide functionality to the tool. Plugins work independently, the same way as a service in a microservices oriented architecture: isolated, self-contained and without affecting other existing functionality in the system.

Discover in the current documents detailed information regarding aura-mocks-server plugins:

Descriptive information regarding plugins: types of plugins, plugins management, plugin basic structure, plugins modules
Available plugins in the aura-mocks-server global plugins catalog

Global plugins catalog

The available global plugins of aura-mocks-server are included in the Github global plugins repository.

Aura Platform Team is progressively documenting each plugin within the current documents. Check the already documented ones in the left sidebar index.

Types of plugins

There are different types of plugins:

Api. REST services that perform specific tasks not associated with the communication with a channel.
Client. These plugins define clients that can be used to communicate with a channel. These clients are normally used by processor plugins.
Processor. Plugins in charge of communicating with a channel, transforming the message received from a source channel to a destination channel.
Service. Utility plugins to be used by the rest of plugins.

Plugins management

As indicated in the previous section, aura-mocks-server uses the library@architect/architect for the management of plugins, so it is the architect library that is responsible for managing the dependencies injection in each module.

To create the architect application, aura-mocks-server uses the PluginManager module (located in the modules/plugin-manager folder). This module starts as the rest of modules at the aura-mocks-server start-up.

The PluginManager performs the following tasks:

It starts the architect application with the plugins defined in plugin-config.json file, located at the root of the aura-mocks-server component.
It adds the core modules to the IOC context. See the section modules added by aura-mocks-server.
It stores the information of each module defined in the plugins.

An example to define aura-mocks-server-example-service plugin of the previous section is shown below:

/* file: plugin-config.json */
[
    "./lib/plugins/aura-mocks-server-example-service",
]

Currently, the plugins are in the src/plugins folder of aura-mocks-server, but in the future these plugins should be independent libraries and could be charged by library name (for example: @telefonica/aura-mocks-server-example-service).

Apart from the aura-mocks-server core environment variables, each plugin can define its own specific variables.

Plugin basic structure

Currently, aura-mocks-server uses @architect/architect library for plugins management.

A basic plugin must define at least:

A package.json file defining the library, like any other JavaScript library, with a plugin section defining which modules it consumes and supplies.
A source code file that defines the modules that it supplies (index.ts for example).

The structure of this basic plugin is as follows:

aura-mocks-server-example-service
├── index.ts
└── package.json

A couple of examples with the content of each file are included below:

/* file: index.ts */
import { PluginType, registerPlugin } from '@telefonica/xxxx-server-common';
import { v4 as uuidv4 } from 'uuid';
import { Services } from './example-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,       // Plugin service type
        name: 'exampleService',         // Name of the plugin service
        instance: {                     // [provides] Instance that provides the module
            getUniqueId() {
                return uuidv4();
            }
        },
        services: Services              // [consumes] Needed modules are added here
    }
]);

/* file: package.json */
{
    "name": "@telefonica/aura-mocks-server-example-service",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "exampleService"
        ]
    }
}

Plugins modules

aura-mocks-server currently adds three modules that can be used by the different plugins. To use them, it is only necessary to add the package.json dependencies on plugin.consumes (like any other module/component).

configurationManager: Module with the aura-mocks-server configuration information.
auramocks-serverCache: Module to manage the aura-mocks-server cache.
prometheus: Service for metrics management.

A plugin can provide one or more plugin modules and each plugin module can be of a different type. Each type of module is intended to add a specific functionality to aura-mocks-server.

The existing types are defined in PluginType, which are described in the following sections.

export enum PluginType {
    Api = 'Api',
    Client = 'Client',
    Processor = 'Processor',
    Service = 'Service'
}

Docs:

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

Preset plugin

Preset plugin description for aura-configuration-api

Introduction

The preset plugin defines services associated with the management of presets in aura-configuration-api server.

All these services are defined in the presets namespace (/presets).

Servers definition

By default, the servers defined in the swagger include the base path (for v1): /aura-services/v2/configuration.

Therefore, in order to access the services, the base path and service path must be used.

Examples:

aura-services/v2/configuration/presets
aura-services/v2/configuration/presets/{presetId}

Endpoints

Path	Method	Description
/presets/	GET	Get all presets information
/presets/	POST	Add a new preset
/presets/{presetId}	GET	Get preset information using preset id
/presets/{presetId}	PUT	Replace preset information associated to preset id
/presets/{presetId}	PATCH	Update some fields of preset information using preset id
/presets/{presetId}	DELETE	Delete preset information using preset id

You can read the complete documentation of each service in the aura-configuration-api swagger file.

Retrieving information from presets

Retrieving specific fields from preset information

It is possible to get only a specific list of fields for preset information, reducing the amount of data transmitted when necessary, using the includeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/presets?includeFields=id,name,generative' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: XXX'

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "preset_2",
        "generative": {
            "model": {
                "id": "gpt-4o-mini",
                "parameters": {
                    "top_p": 1,
                    "max_tokens": 250,
                    "temperature": 1
                }
            },
            "prompts": {
                "template": "string",
                "preamble": {
                    "text": "Hola.",
                    "args": {
                        "brand": "Movistar",
                        "country": "Spain",
                        "year": "2024"
                    }
                },
                "promptMaxLength": 1500
            }
        }
    }
]

Excluding fields in presets information

It is also possible to exclude presets information fields using the excludeFields query parameter.

curl --location --request GET 'http://aura-configuration-api:8999/aura-services/v2/configuration/presets?excludeFields=generative,metadata' \
--header 'correlator: urn:uuid:c8a604ee-29f8-7cda-2979-d2ae6189c360' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY XXX'

Response example:

[
    {
        "id": "ab744582-c5a6-48e1-95bb-f509bdb55512",
        "name": "preset_2",
        "session": {
            "window": 8
        }
    }
]

Database

The complete definition of the data model can be found in presets collection section within the administration module.

Docs:

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

Python repositories migration

Migration of Python repositories from Python 3.9 to Python 3.13 version for PyUtils, Aura NLP, Aura Complex Logic Framework plugin packages and ATRIA repositories

Introduction

This document describes the migration process of Python repositories from Python 3.9 to Python 3.13 ¹ for PyUtils, Aura NLP, Aura Complex Logic Framework plugin packages, ATRIA and other productive Python repositories that has taken place in Prince 10.0.0 release.

This migration is required due to the end of life of Python 3.9, set in October 2025.

PyUtils migration

PyUtils contains multiple repositories that have been migrated to Python 3.13 version by Aura Global NLP Team.

The use of these libraries is the same as before the migration, but OBs constructors must test the use cases to ensure that everything is working correctly.

NLP packages migration

The Aura Global NLP team has migrated the Python repositories to Python 3.13 version and has generated the different NLP packages for the OBs.

Two branches will live together:

release/7.0: Compatible branch with Python 3.9 version. If the deployed OB release is previous to Prince 10.0.0.
release/8.0: Compatible branch with Python 3.13 version. After Prince 10.0.0 release delivery.

The release/8.0 branch will be launched together with Prince 10.0.0 delivery. However, release/7.0 will remain active until the OB deploys Prince in production environment and even after that, for any issue or hotfix required.

The repositories of NLP training has a JenkinsFile ² that defines the pipeline in Jenkins for the continuous integration of the repositories. For release/7.0 branch, the JenkinsFile of Aura NLP repositories will be configured for working with Python 3.9 version in the pipelines defines in Jenkins, to allow OBs to continue creating NLP packages, until they deploy this new release.

When deploying Prince release and changing from release/7.0 to release/8.0, both branches must be synchronized to preserve all modifications made in the older one.

Constructors should not do any change, as no trainings with the QnA and LUIS stages should exist (these stages are deprecated and must have already been replaced by the OpenAIEmbeddings and CLU stages respectively).

With the NLP packages provided by Aura Global NLP team, the OB constructors must test and validate that all the use cases are working correctly.

QnA and LUIS recognizers deprecation

The QnA and LUIS recognizers are deprecated and have been replaced by the OpenAIEmbeddings and CLU recognizers respectively in all trainings.

NLP Resources

The repositories resources listed below, which are the ones in production environment, have been migrated:

AP
- resources_pizza
- resources_ap-demo
- resources_cr
ES
- resources_tiempo
- resources_real-academia-historia
- resources_core-dialogs
- resources_bingo
- resources_movistar-shop
- resources_movistar-gaming
- resources_es-nov
- resources_memory
- resources_leia
- resources_eset
- resources_chester
- resources_mis-tokens
- resources_movistar-cloud
- resources_estadio-infinito
- resources_es
BR
- resources_br-b2c
- resources_br-b2b
- resources_br
- resources_br-rh
- resources_br-rcs
- resources_br-stb
- resources_br-easy
- resources_br-app
- resources_br-wa
- resources_br-nov

Migration process for CLF plugins

The Aura Global NLP team and constructors have carried out the following steps for the migration of CLF plugins:

Aura Global NLP team:
- Updated in requirements.txt the packages to the versions generated for Prince release.
- Updated tools and scripts to work with the Prince release.
- These repositories work the same way as the NLP training repositories: a release/7.0 branch has been launched before the Prince release to make changes in previous versions. For Prince release, a release/8.0 branch is available.
- Updated JenkinsFile:
  - The JenkinsFile is set for versions previous to Prince release (release/7.0).
  - In Prince release, there is no need to update JenkinsFile as it is already configured in master.
Constructors:
- Reviewed the Python changelog for Python 3.13 version.
- Executed tests with the new version of Python and its libraries.
- Executed plugins and tested the locally.
- Adapted code.
- Generated a new version of the plugin package of the constructors and propagated to the corresponding environment.
- Tested plugins in the environments.

Currently, there are no constructors outside the global team. For this reason, the Aura Global NLP team will be responsible for the migration of the CLF Plugins.

CLF plugins repository list

Below, the list of migrated CLF plugins repositories is included:

aura_clf_video

Migration process for ATRIA

The ATRIA repositories have been migrated to Python 3.13 by Aura Global Team.

The configuration inside ATRIA repositories must be the same as before migration, but constructors must test the use cases to ensure that everything is working correctly.

Information about the migration process for any productive repositories of Python language

Get sure that any productive repository that is not currently being used has been migrated from Python 3.9 to 3.13 version before being put into production.

Python 3.13 is the latest version of Python Programming Language at this moment. Cognitive components are being migrated to this version. ↩︎
JenkinsFile defines the pipeline in Jenkins for the continuous integration of the repositories. ↩︎

Docs:

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

Aura Bot recognizers

Description of the different Aura Bot recognizers, components in charge of the identification of the user’s intention

What are Aura Bot recognizers?

Recognizers in aura-bot are a specific type of middlewares that are executed in a certain stage of the message flow. They are in charge of the recognition of the user’s intention based on the data sent in the request.

Recognizers inherit from the abstract class called BaseRecognizerMiddleware.

There are two types of recognizers, internal and external:

Internal recognizers

aura-bot own components that are able to recognize the intention of the user directly from the incoming message. Currently, they are:

External recognizers

Responsible for calling an external API to obtain an intention.
Currently, the only external recognizer is nlp-recognizer-middleware, in charge of detecting the intention of the user from all the training of the environment.

Apart from the ones mentioned above, the finalize-recognizers-middleware is in charge of finalizing the recognition process.

Recognizers are executed sequentially in the order previously defined during the bot start-up.

Recognizers flow

The following figure shows the execution flowchart for aura-bot recognizers, including the recognizers included in aura-bot by default. They are executed sequentially.

If one specific recognizer has obtained an intention, then the flow redirects to the finalize-recognizers-middleware, that provides the result to aura-bot in order to trigger the corresponding dialog.
If the recognizer in execution does not get the intention, then the flow continues and the succeeding recognizer is executed.
As can be seen in the flowchart, the last recognizer to be executed is the external one, nlp-recognizer-middleware. This is because aura-bot should only request it if no other recognizer gets the intention of the user.
The finalize-recognizers-middleware is in charge of deciding, in case there is any active prompt, whether to continue with the prompt or to remove the prompt from the dialog stack and process the attempt to start a new dialog otherwise.

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:

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

User middleware

Description of user-middleware in charge of the validation of the user’s data

Introduction

user-middleware is the middleware in charge of validating auraId and channel.

This is needed in aura-groot because routing is currently done by channel, so if the request does not include channelId (mandatory only in channelData v3), the user must be checked in aura-authentication-api to obtain the channel of this user.

This middleware throws an error if there is not activity.from.id or if some error is returned by aura-authentication-api (except 404, because anonymous users should continue the flow).

This middleware also handles a basic user’s cache to avoid unnecessary calls to aura-authentication-api with every user’s request. This cache is implemented using bot UserState.

Docs:

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

aura-mocks-administration-api plugin

Plugin that returns Aura Mocks Server data.

Description

The aura-mocks-administration-api plugin returns data info from Aura Mocks Server, such as app, cache or plugins.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-administration-api

This is part of aura-mocks-server project.

Administration Endpoints API

Enpoint	Method	Group	description
/administration/heapStatistics	GET	App	Get heap statistics
/administration/heapSnapshot	GET	App	Get heap snapshot
/administration/cache	GET	Cache	Get cache
/administration/cache/stats	GET	Cache	Get cache stats
/administration/plugins	GET	Plugins	Get plugins

GET: /administration/heapStatistics

Return Aura Mocks Server data info.

{
    "aura-mocks-server-1.0.0": {...}
}

GET: /administration/heapSnapshot

Generate and upload snapshot to Azure Storage.

{
    "status": 200
}

GET: /administration/cache

Return cache data info.

{
    "info": {
        "Server": {...},
        "Clients": {...},
        "Memory": {...},
        "Persistence": {...},
        "Stats": {...},
        "Replication": {...},
        "CPU": {...},
        "Modules": {...},
        "Errorstats": {...},
        "Cluster": {...},
        "Keyspace": {...}
    }
}

GET: /administration/cache/stats

Return cache stats data.

{
    "stats": {...}
}

GET: /administration/plugins

Return plugins data info.

[
    {
        "name": "redisStorageService",
        "pkg": "@telefonica/aura-redis-service",
        "version": "1.0.0",
        "package": "aura-mocks-redis-service",
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "redisStorageService"
        ]
    }
]

Docs:

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

Agent Deployment Plugin

The agent-deployment plugin is a component that provides deployment functionalities for agents within the agents-manager.

Introduction

The agent-deployment plugin is designed to manage the deployment of agents in a flexible and scalable manner. It allows multiple agents to be deployed within a single microservice, and the same agent can be deployed with different configurations across different microservices or within the same microservice.

Plugin Management

The agent-deployment plugin uses the @architect/architect library for managing dependencies and plugin lifecycle. The PluginManager module, located in the modules/plugin-manager folder, is responsible for initializing the plugin at the start-up of the agents-manager.

The PluginManager performs the following tasks:

Initializes the architect application with the plugins defined in the plugin-config.json file, located at the root of the agents-manager component.
Adds core modules to the IOC context. See the section plugin modules.
Stores information about each module defined in the plugins.

Plugin Basic Structure

A basic plugin must define at least:

A package.json file defining the library, with a plugin section specifying which modules it consumes and supplies.
A source code file that defines the modules it supplies (index.ts for example).

The structure of this basic plugin is as follows:

agent-deployment-plugin
├── index.ts
└── package.json

Example `index.ts`

import { PluginType, registerPlugin } from '@telefonica/agents-manager-common';
import { Services } from './deployment-consume-services';

export = registerPlugin([
    {
        type: PluginType.Service,
        name: 'agentDeploymentService',
        instance: {
            deployAgent(agentConfig) {
                // Implementation for deploying an agent
            }
        },
        services: Services
    }
]);

Example `package.json`

{
    "name": "@telefonica/agent-deployment-plugin",
    "version": "1.0.0",
    "main": "index.js",
    "private": true,
    "plugin": {
        "consumes": [
            "configurationManager"
        ],
        "provides": [
            "agentDeploymentService"
        ]
    }
}

Plugin Modules

The agent-deployment plugin can utilize the following modules provided by the agents-manager:

configurationManager: Module with the agents-manager configuration information.
redisConnector: Module with the agents-manager Redis connection.

A plugin can provide one or more plugin modules, and each plugin module can be of a different type. Each type of module is intended to add specific functionality to the agents-manager.

Docs:

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

Agents Manager architecture and components

Development architecture and technical components of the agents-manager

Technical foundations

agents-manager is mainly a web server built on Typescript using nodejs as engine. It is api-first designed, using OpenAPI v3 to provide the API definition and openapi-backend to handle swagger specification.

agents-manager server is composed by several plugins, which provide different functionalities to this component.

A channel, service, or skill uses an application to connect with agents-manager following this communication protocol.

Architecture overview

The following figure shows the main technical components of the agents-manager, which are described below.

agents-manager components

ConfigurationManager

ConfigurationManager is a handler for configuration, obtained through a configuration file or environment variables.

RedisConnector

RedisConnector is a handler connection to Redis.

HTTP server

Microservice is implemented as an HTTP server (AuraServer) that exposes an API to receive the request to be validated.

Middlewares

The route published in the API definition file is handled by a controller but, before a request lands on its controller, it goes through a series of middlewares that provides some common steps needed by all the controllers of the server such as: request validation, common parameters extraction, logging, metrics initialization, etc.

Controllers and Services

agents-manager is composed of plugins, which provide functionality and uses specific modules from aura-configuration-api.

Check the available plugins together with detailed information in: agents-manager plugins.

Docs:

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

Agents Server architecture and components

Development architecture and technical components of the agents-server

Technical foundations

The agents-server component will start a server that listens for incoming requests and executes the agent’s tasks based on the received input.

The server can be configured to use an agent by specifying the agent package name.

This server creates a REST API that can be used to interact with different agents. The API allows sending requests to the agent and receiving responses.

Within the agents-server, the agents package component enables information processing tasks to be performed and acted upon to achieve specific objectives. This information can come from a database and respond to the user’s request based on that acquired information.

Architecture overview

The following figure shows the main technical components of the agents-server, which are described below.

agents-server components

HTTP server

Microservice is implemented as an HTTP server (fastapi) that exposes an API to receive the request to be validated.

Config Api Handler

The agents-server uses the aura-configuration-api to get the configuration of the agent. This handler is responsible for retrieving the configuration of the agent from the aura-configuration-api and providing it to the server.

ConfigurationManager

ConfigurationManager is a handler for configuration, obtained through a configuration file or environment variables.

Agents Package

The server is configured to use the agent of a specific agent package name. This package contains the agent’s code and its dependencies. The server will load the agent package and use it to execute the agent’s tasks.

Event Subscribers

Event subscribers are implementations for managing event registration and handling in the agents-server. They allow the server to listen for events and trigger actions based on those events.

Redis Async Subscriber

RedisAsyncSubscriber is a handler for subscribing to Redis channels asynchronously. It allows the server to receive messages from Redis and process them in real time.

DAPR Async Subscriber

DaprAsyncSubscriber is a handler for subscribing to DAPR topics asynchronously. It allows the server to receive messages from DAPR and process them in real time.

Docs:

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

Aura Gateway API architecture and components

Development architecture and technical components of Aura Gateway API

Technical foundations

aura-gateway-api is mainly a web server built on Typescript 4.3 using nodejs as engine. It is api-first designed, using OpenAPI v3 to provide the API definition and openapi-backend to handle swagger specification.

aura-gateway-api server is composed by several plugins, which provide different functionalities to this component. From the different capabilities that aura-gateway-api can manage, certain plugins are used by all of them and others are specific of one capability.

A channel, service, or skill uses an application to connect with aura-gateway-api following this communication protocol.

Architecture overview

The following figure shows the main technical components of the aura-gateway-api.

ConfigurationManager

ConfigurationManager is a handler for configuration, obtained through a configuration file or environment variables.

RedisConnector

RedisConnector is a handler connection to redis.

Kpis-handler

KpisHandler is the module responsible for writing the KPIs entities.

HTTP server

Microservice is implemented as an HTTP server (AuraGatewayServer) that exposes an API to receive the request to be validated.

Middlewares

Plugins

Different plugins provide functionality to aura-gateway-api.

Check the available ones together with detailed information in: aura-gateway-api plugins.

Docs:

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

aura-mocks-async-callback-api plugin

Plugin that mocks asynchronous notification message

Description

The aura-mocks-async-callback-api plugin simulates aura-bridge asynchronous notification message for asynchronous API requests, both internal, such as file-manager or external, such as technical-problems-api in Kernel. It also adds several useful endpoints for the QA team and performance testing.

Find more information in the Github repository:
https://github.com/Telefonica/aura-mocks-server/tree/master/src/plugins/aura-mocks-async-callback-api

This is part of aura-mocks-server project.

Endpoints API

Enpoint	Method	Group	description
/async-callback/notifications	GET	Async Callback	Get notifications
/async-callback/notifications	DELETE	Async Callback	Delete notifications
/async-callback/notifications	POST	Async Callback	Send notification

GET: /async-callback/notifications

Get message by messageCorrelator. The query param messageCorrelator is mandatory.

DELETE: /async-callback/notifications

Delete message by messageCorrelator. The query param messageCorrelator is mandatory.

POST: /async-callback/notifications

Add new asynchronous notification message

{
    "payload": {...},
    "creation_date": "2019-08-08T15:19:48.259Z",
    "user_id": "9a47b037-825f-4ae7-bf55-6290efd5d036"
}

Docs:

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

Aura Bot as a skill

aura-bot is Aura’s neuronal network in charge of core features in Aura Virtual Assistant. Find in the current documents the description of this component, its architecture, components and processes.

Aura Virtual Assistant component

Introduction

aura-bot is an HTTP server, based on Microsoft Bot Framework. It is built in Typescript using the node.js SDK of Bot Framework. As an HTTP server, it uses Express.js.

aura-bot is Aura’s neuronal network, where it can be considered as a Bot Development Platform itself. In the recent distributed architecture, aura-bot is the only skill on the system that handles all requests, although the new entry point to the system is now the root bot called aura-groot, that redirects all requests to the only skill in order to access Aura through diverse communication channels and interacts with every Aura system or component in order to provide Aura users with the intended answer or requested service.

The following flowchart shows the complete conversational process executed by aura-bot.

Aura Bot functionalities

The main functionalities in charge of aura-bot are users’ sign up, authentication validation process and conversational process.

Apart from them, there are other processes managed by aura-bot that can be executed in order to customize the bot, activate other components, etc.

Find here all the information related to Aura Bot processes.

Aura Bot components

aura-bot components can be classified into different categories:

Aura Bot Platform components, which are components aura-bot has as a BotFramework bot: dialogs, middlewares, recognizers, Bot framework adapter, Activity Handler, etc.
Other components that have been developed within aura-bot to provide it with a specific functionality, such as plugin manager or routing manager.
Moreover, the databases used by aura-bot.

Find detailed information of all of them in Aura Bot components.

Aura Bot Platform repository

The repository aura-bot-platform has a folder layout inside the src folder, to organize the code according to functionality groups.

In the src root folder, only main files should be placed, such as index.ts, or main server file server.ts (it was app.ts in aura-bot).

src/bots

At the beginning, only the file aura-bot.ts is hold here, that is the main ActivityHandler (a kind of replace of previous UniversalBot).

In a near future, more Bot Builder adapters could be located here.

src/config

This folder contains files that load configurations and that are required in other places, such as channel configuration, environment variables, etc.

src/db

This folder contains files that manage and connect to databases, such as MongoDB.

src/events

The files handling events (such as ModuleObserver subclasses) should be placed in this folder.

src/dialogs

This folder contains the main dialog (main.ts) and custom prompts, as use case dialogs will be located in libraries, loaded as dependencies.

src/make

This folder contains the code related with joining all the library-specific data with global one during the make-up process.

src/middlewares

This folder contains abstract middleware base classes, and specific middleware implementation (final classes).

src/middlewares/recognizers

This folder contains all the recognizers, such as NLP recognizer, Aura Command recognizer, etc.

src/models

Files located within this folder will have exported types and interfaces required in different parts of the code (types and interfaces required only within a file could be self contained).

src/modules

This folder contains independent code blocks, that could be exported as a reusable packages if required in different components, such as cache manager, locale manager, etc.

src/plugin

This folder contains the modules in charge of loading plugins: charging dialogs, middlewares, delivery configuration for these components, etc.

src/routing

This folder contains the code related with intent-to-dialog routing, as this is not part of Bot Builder anymore.

src/utils

This folder contains utility classes and methods that are not part or any other block. We should maintain this folder organized and tidy, to avoid lots of unspecific files.

Docs:

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

Aura Bot core dialogs

Aura Bot core dialogs are internal global dialogs that are deployed within a specific Aura Platform release

Introduction

The following aura-bot core dialogs are global ones designed and developed by Aura Platform Team that are at the OBs’ disposal to build experiences in Aura. OBs cannot modify their logic but use them as they are.

These dialogs are deployed jointly with the corresponding Aura Platform release.

As intended for Aura global experiences, they are named below but fully described in the section Global use cases together with other global dialogs.

Aura – components

Docs:

account-linking dialog

Introduction

Environment variables

Docs:

Aura configuration API admin module

Introduction

Servers definition

Endpoints

Export modules

Export all

Export one or several specific modules

Import modules

How is an import processed?

Result of the import process

Database

Channels collection

Fields

Indexes

skills collection

Fields

Indexes

applications collection

Fields

Types

Indexes

presets collection

Fields

Root

Types

Action

Session

Generative

RAG

Metadata

Indexes

suggestions collection

Fields

Indexes

tv-section collection

Fields

Example of metadata:

Indexes

agents collection

Fields

communication object (HTTP)

metadata object

Indexes

routing filters collection

Fields

database object

filterCollection object

metadata object

Indexes

Docs:

agent-dispatcher-api plugin

Introduction

Consumes components (IOC)

Provides components (IOC)

Docs:

ATRIA Model Gateway architecture and components

Technical foundations

Functional components

Architecture overview

Access module

Context module

Model manager

Models

Presets

Docs:

ATRIA RAG Generate DB architecture and components

Architecture overview

Data sources

Retrievers

Docs:

ATRIA RAG Server architecture and components

Architecture overview

Project

Semantic search (embeddings)

Example of `metadata`: