Aura – functionality

Docs:

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

ATRIA components default configuration

Description of the default configuration (internal configuration) for ATRIA components

Introduction

The default configuration of ATRIA corresponds to the server configuration, that is, the internal configuration for ATRIA components.

Within a specific configuration type, parameters are organized by component:

Fields for atria-model-gateway configuration
Fields for atria-rag-server
Common fields for both components

1. Server configuration

Fields related to the internal configuration of ATRIA components

Target users: ATRIA development and installation teams

The default server configuration fields are non-modifiable by ATRIA constructors (excepting prompts)

1.1. Logging configuration

Configuration field shared between atria-model-gateway and atria-rag-server that enables the configuration of logs in a customizable and independent way

The logging configuration is done through a json configuration file that is set by default, as shown below.

{
  "version": 1,
  "disable_existing_loggers": false,
  "logging": {
    "handlers": {
      "hdl2": {
        "class": "logging.StreamHandler",
        "formatter": "json",
        "level": <AUTOCOMPLETED>
      }
    },
    "loggers": {
      "atria_model_gw": {
         "level": <AUTOCOMPLETED>,
         "handlers":[
            "hdl2"
         ],
         "filters":[],
         "propagate": false
      }
    },
    "root": {
      "level": <AUTOCOMPLETED>,
      "handlers": []
    }
  }
}

Fields

The main fields are explained below. However, for more details, developers are kindly requested to read the General Python logging documentation

Parameter	Subparameters	Definition	Type/Default values
`version`		Version of the logging configuration	number
`disable_existing_loggers`		Boolean value to indicate whether or not the already existing loggers when this call is made are disabled or not	boolean
`handlers`		Dictionary with different logging handlers. Each key is the name of a handler
	`class`	It is configured with Python logging handlers (See Python documentation)
	`formatter`	It configures the format of logs.	`json`, `string`, `console`, `simple`
	`level`	Level of the logging event. It must be filled with the labels	`INFO`, `ERROR`, `WARN` or `DEBUG`
`loggers`		Python dictionary in which each key is a logger name and each value is a dictionary describing how to configure the corresponding logger instance
	`level`	(Optional) Level of the logger.
	`handlers`	(Optional) List with the IDs of the handlers for this logger
	`filters`	(Optional) List with the IDs of the filters for this logger
`root`		Configuration for the root logger.
	`level`	(Optional) Level of the logger.
	`handlers`	(Optional) List with the IDs of the handlers for this logger

1.2. atria-model-gateway default configuration

This section includes the parameters configured by default in atria-model-gateway:

Defaults

General-purpose field with parameters to define the behavior of atria-model-gateway

Defaults fields

Parameter	Subparameters	Definition	Type/Default values
`session_params`		(Optional) Default values for a session	object
	`window`	(Optional) Session window	number
	`timeout`	(Optional) Session expiration time	number
`service_params`		(Optional) Default values for the server	object
	`preflight_max_age`	(Optional) Preflight max age	number
`messages`		(Optional) Message options	object
	`types`	(Optional) Types of messages.	list[string]
`openai_proxy`		Activate OpenAI proxy	boolean
`trimmer`		(Optional) Expression to trim the response	string

If the timeout is 0, the last conversation in the session will not be saved, but the session history will be used.

Defaults by default

The default configuration is described as follows:

defaults:
  # Default values for a session
  session_params:
    window: 2
    timeout: 3600

  # Default values for the server
  service_params:
    preflight_max_age: 86400

  # Message options
  messages:
    types:
      - feedback

  # Activate openai proxy
  openai_proxy: false

Redis

This section includes the Redis connection configuration for atria-model-gateway.

Redis fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number

Redis by default

The default configuration for Redis is described as follows:

redis:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>

Redis Subscriber

This section includes the Redis event subscriber connection configuration for atria-model-gateway.

Redis subscriber fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number
`channels`	List of channels to subscribe to	list[string]

Redis subscriber by default

The default configuration for Redis is described as follows:

redis_subscriber:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>
  channels:
    - "ApplicationConfiguration"
    - "PresetConfiguration"

Config API

Field with parameters for the API configuration for atria-model-gateway

Config API fields

Parameter	Definition	Type/Default values
`base_url`	(Mandatory) API config URL	string
`api_key`	(Mandatory) APIKey	string

Config API by default

The default configuration is described as follows:

aura_config_api:
  base_url: <AUTOCOMPLETED>
  api_key:  <AUTOCOMPLETED>

Allow logging prompts with INFO level

Field to allow logging prompt with INFO level for atria-model-gateway. It should only be used for debugging errors in environments where there are no debug logs. Due to the size of the prompts, this variable should be set to false once it is not needed.

Allow logging prompts

Parameter	Definition	Type/Default values
`allow_log_prompts`	Allow logging prompts	boolean

Allow logging prompts by default

The default configuration is described as follows:

allow_log_prompts: false

Models

Predefined AI models included in atria-model-gateway by default.

The model(s) to be used must be selected when configuring an application.

Model fields

Parameter	Subparameters	Definition	Type/Default values
`type`		(Mandatory) Identifier type of model	`rag`, `openai`, `mock`, `perplexity`
`name`		(Optional) Model name. If this value does not exist, `id` is used	string
`class_params`		(Mandatory) Preset description	object
	`endpoint`	(Mandatory) Endpoint of the model	string
	`type`	(Mandatory for RAG) Type of the model	`langchain`
	`path`	(Mandatory for RAG) Path of endpoint model	string
	`azure_name`	(Mandatory for OpenAI) Azure name of the model	string
	`model_name`	(Mandatory for OpenAI) Model name	string
	`api_key`	(Mandatory for OpenAI) APIkey to be used in the model call	string
	`api_version`	(Mandatory for OpenAI) API version to be used in the model call	string
	`output`	(Mandatory for mocks) Response to be used in the model call	string
`description_params`		(Optional) Description of the model params	object
	`context_window`	(Optional) Context window of model	number
`tokenizer`		(Optional) Tokenizer of model	string

Models by default

atria-rag model

Model for using the atria-rag-server.

The default configuration is described as follows:

  atria-rag:
    type: rag
    name: Rag server model
    class_params:
      type: langchain
      endpoint: <AUTOCOMPLETED>
      path: <AUTOCOMPLETED>

gpt-4

Model for using Azure OpenAI GPT-4 model.

The default configuration is described as follows:

      gpt-4:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4
          model_name: gpt-4
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
             timeout: 60
             read: 60
        description_params:
          context_window: 300

gpt-4o

Model for using Azure OpenAI GPT-4o model.

The default configuration is described as follows:

      gpt-4o:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4o
          model_name: gpt-4o
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

gpt-4o-mini

Model for using Azure OpenAI GPT-4o-mini model.

The default configuration is described as follows:

      gpt-4o-mini:
        type: openai
        local: false
        class_params:
          azure_name: deployment_gpt-4o-mini
          model_name: gpt-4o-mini
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

o3-mini

Model for using Azure OpenAI o3-mini model.

The default configuration is described as follows:

      o3-mini:
        type: openai
        local: false
        class_params:
          azure_name: deployment_o3-mini
          model_name: o3-mini
          api_key: <AUTOCOMPLETED>
          endpoint: <AUTOCOMPLETED>
          api_version: <AUTOCOMPLETED>
          timeout:
            timeout: 60
            read: 60
          description_params:
            context_window: 128000

gpt-4.1-nano

Model for using Azure OpenAI gpt-4.1-nano model.

gpt-4.1-nano:
  type: openai
  local: false
  class_params:
    azure_name: deployment_gpt-4.1-nano
    model_name: gpt-4.1-nano
    api_key: <AUTOCOMPLETED>
    endpoint: <AUTOCOMPLETED>
    api_version: <AUTOCOMPLETED>
    timeout:
      timeout: 60
      read: 60
    description_params:
      context_window: 128000

perplexity-sonar

This model will be available in ATRIA in upcoming releases. Model for using Perplexity sonar model.

The default configuration is described as follows:

perplexity-sonar:
 type: perplexity
 local: false
 class_params:
   model_name: sonar
   api_key: <AUTOCOMPLETED>
   endpoint: <AUTOCOMPLETED>
   timeout:
     timeout: 20
     read: 45
   http_raise_when_retry_limit_exceeded_recognizer: false
 description_params:
   context_window: 300

Important: This model does not support the same parameters as the previous ones. Check Microsoft document API & feature support.
The following parameters are not supported by the model: temperature, top_p, presence_penalty, frequency_penalty, logprobs, top_logprobs, logit_bias, max_tokens.

1.3. atria-rag-server default configuration

This section includes the parameters configured by default in atria-rag-server:

LLMs

Predefined parameter to define the Large Language Models (LLMs) that call from atria-model-gateway to atria-rag-server.

Currently, only one LLM with the necessary configuration to connect atria-model-gateway to atria-rag-server is defined. It cannot be modified.

LLMs fields

Parameter	Definition	Type/Default values
`name`	(Optional) LLM name. If this value does not exist, `id` is used	string
`model_type`	(Mandatory) Model type	string
`endpoint`	(Mandatory) Endpoint of the model	string

LLm by default

atria-model-gateway:

  atria_model_gateway:
    name: Local Model Gateway
    model_type: llm_manager
    endpoint: http://atria-model-gw:6391/aura-services/v1/atria-model-gw

Embeddings

Parameters to define the embeddings, vector representations to find text blocks that contain the information to resolve the input request.

Two types of Embeddings are available for use:

Local Embeddings: Generated by the atria-rag-server in local mode.
Embeddings OpenAI: Generated by OpenAI.

Embeddings fields

Parameter	Definition	Type/Default values
`name`	(Mandatory) Embedding name	string
`type`	(Mandatory) LLM name. Type of the model	`sentence_transformer`, `azure_openai`
`model`	(Mandatory) Used model	string
`openai_api_version`	(Mandatory to call Azure OpenAI) OpenAI API version	string
`openai_api_type`	(Mandatory to call Azure OpenAI) OpenAI API type	string
`openai_api_key`	(Mandatory to call Azure OpenAI) OpenAI APIKey	string
`azure_endpoint`	(Mandatory to call Azure OpenAI) Azure endpoint	string

Embeddings by default

The predefined embeddings in atria-rag-server are shown below:

Local Sentence Transformer from HuggingFace:

This is an open-source model that appears in sentence-transformers library.

It maps sentences & paragraphs to a 384 dimensional dense vector space and can be used for several tasks like:

Clustering
Multilingual similarity searches
Retrieval-based tasks
Classification

A brief characterization of this embedding regarding different parameters is included below:

Cost: Free to use once downloaded (local execution). No API call costs.
Latency: Low, since it runs locally without external API calls.
Performance: Satisfactory for general-purpose sentence embeddings, supporting multiple languages.
Vector Length: 384 dimensions (smaller than OpenAI’s ADA model).
Hardware Requirements: Needs a GPU for faster inference; otherwise, it can be slow on a CPU.
Model Size: Requires local storage (~120MB).
Quality: Slightly lower accuracy than larger models, especially for complex NLP tasks.

This embedding can be configured with a yaml file:

local_st:
    name: Local Sentence Transformer from HuggingFace
    type: sentence_transformer
    model: paraphrase-multilingual-MiniLM-L12-v2

Distilbert-based Local Sentence Transformer from HuggingFace

This is an open-source model that appears in sentence-transformers library.

It has been trained on 215M (question, answer) pairs from diverse sources.

It maps sentences & paragraphs to a 768 dimensional dense vector space and was designed for several tasks like:

Semantic search
Question answering
Passage retrieval

A brief characterization of this embedding regarding different parameters is included below:

Cost: Free (local execution). No API call costs.
Latency: Fast, optimized for question-answer retrieval tasks.
Performance: Outperforms MiniLM in retrieval-based tasks due to DistilBERT’s training on QA data.
Vector Length: 768 dimensions (higher than MiniLM, better at capturing semantics).
Hardware Requirements: Similar to MiniLM, requires a GPU for optimal performance.
Model Size: Larger than MiniLM (~250MB).
Quality: Primarily trained for English, not as strong for multilingual applications.

This embedding can be configured with a yaml file:

test_distilbert:
    name: Distilbert-based Local Sentence Transformer from HF
    type: sentence_transformer
    model: multi-qa-distilbert-cos-v1

OpenAI Embeddings ADA

This is one of OpenAI’s latest models for generating embeddings and has quickly become a top choice for tasks:

Recommendation systems
Chatbots
Semantic search
Large-scale applications

A brief characterization of this embedding regarding different parameters is included below:

Cost: Paid API model (depends on token usage, $0.0001/1k Tokens). It can be expensive for high-volume applications.
Latency: API calls introduce certain delay, specially in large-scale real-time applications.
Performance: State-of-the-art embeddings with high accuracy for a wide range of NLP tasks.
Hardware Requirements: No local hardware requirements, it works via API.
Vector Length: 1536 dimensions (rich semantic representation).
Quality: Strong performance across multiple languages.

This embedding can be configured with a yaml file:

text-embedding-ada-002:
  name: text-embedding-ada-002 model from Azure OpenAI API
  type: azure_openai
  model: deployment_text-embedding-ada-002
  openai_api_version: <AUTOCOMPLETED>
  openai_api_type: azure
  openai_api_key: <AUTOCOMPLETED>
  azure_endpoint: <AUTOCOMPLETED>

Redis Subscriber

This section includes the Redis event subscriber connection configuration for the atria-rag-server.

Redis subscriber fields

Parameter	Definition	Type/Default values
`connection_mode`	(Mandatory) Connection mode	`single`, `sentinel`, `cluster`
`pool_size`	(Mandatory) Pool size	number
`database`	(Mandatory) Database	number
`password`	(Mandatory) Password	string
`uri`	(Mandatory) URI name	string
`prefix`	(Mandatory) Prefix	string
`sleep_time`	(Optional) Sleep time	number
`max_retries`	(Optional) Maximum number of retries	number
`channels`	List of channels to subscribe to	list[string]

Redis subscriber by default

The default configuration for Redis is described as follows:

redis_subscriber:
  connection_mode: <AUTOCOMPLETED>
  pool_size: 100
  database: <AUTOCOMPLETED>
  password: <AUTOCOMPLETED>
  uri: <AUTOCOMPLETED>
  prefix: <AUTOCOMPLETED>
  channels:
    - "PresetConfiguration"

Prompts

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.

A prompt by default is defined in ATRIA for different RAG stages. This can be used when a specific prompt is not defined in the preset.

Prompts structure for RAG

The hierarchy of default prompts in RAG stages is shown below:

prompts  
 |___ <stage>
        |___ default
        |       |___ text
        |       |___ args
        |___ <language>
                |___ text
                |___ args

The first level in the prompts configuration are the stages of the RAG process. Each stage has its own configuration and purpose.
Prompts configuration works at language level, so it is possible to have different prompts for different languages, indicated by the language code:
- <language>: Any language prompt configuration (ISO 639-1 Code)
- default: Default prompt configuration (in a specific language)
For each language, the prompts structure must include the fields text and args:
- text: This field contains the text of the prompt that will be sent to the language model. It includes placeholders (e.g., {query}, {target_language}) that are mandatory for the prompt to work. These placeholders will be dynamically replaced with the specific values when the prompt is executed.
- args: Optional field that contains a dictionary of arguments that will be used to replace the placeholders in the text field.

Default prompts in RAG stages

The following stages are currently defined in RAG:

cleanStg

This stage is responsible for cleaning the user query. It ensures that the query is in a proper format before further processing.

See how to include this stage in the default prompt code here

translationStg

This stage handles the translation of the user query into the target language, if necessary.

See how to include this stage in the default prompt code here

contextStg

This stage determines the context of the user query, ensuring it is aligned with the previous conversation or context.

Default prompts in this stage:

sameContext: Configuration to check if the query is in the same context.
recreatedQuestion: Configuration to rewrite the original question. It is composed of following prompts:
- default: Configuration for rewriting the original question.
- system: System prompt configuration.
- human: Human prompt configuration.
system: System prompt configuration.
human: Human prompt configuration.
order: Array of strings with prompts names sorted.

See how to include this stage in the default prompt code here

postFilteringStg

This stage filters the retrieved documents or data to ensure relevance to the user query.

Default prompts in this stage:

relevantDocument: Configuration to check if the document is relevant.
relevantSql: Configuration to check if the SQL data is relevant.

See how to include this stage in the default prompt code here

generativeStg

This stage generates the final response using the retrieved and filtered data.

Default prompts in this stage:

stuff: Configuration for the “stuff” strategy. It is composed of the following sub-stages:
- default: Configuration for the “stuff” strategy.
- system: System prompt configuration.
- human: Human prompt configuration.
notAnswerResponse: Configuration for responses when the question cannot be answered.
informationExtraction: Configuration for extracting information. It is composed of following prompts:
- human1: Human prompt configuration.
- ia: IA prompt configuration.
- human: Human prompt configuration.
responseConsolidation: Configuration for consolidating the response.
sqlPrompt: Configuration for generating SQL query statements.

See how to include this stage in the default prompt code here

RAG default prompt

The current section includes the prompt defined by default for ATRIA RAG capability.

You can also access the yaml file in the Github repository.

In case of any discrepancy between the content of this document and that on GitHub, the GitHub version shall always be considered the most up-to-date

RAG default prompt

prompts:
  cleanStg:
    es:
      text: |
        A continuación hay una consulta del usuario.
        Por favor, limpie la consulta y responda solo con la pregunta del usuario o alguna charla informal.
        -------
        {query}        
    default:
      text:
        A user query follows.
        Please clean the query and respond with just the user question or small talk. The query must be written in English.
        -------
        {query}
  translationStg:
    default:
      text: |
        Translate the following question to {target_language}: {question}

        Instructions:
        1. Maintain the formal tone of the original text.
        2. Do not translate proper names and specific terms (e.g., company names, product names, countries).
        3. Provide the translation in the same format and structure as the original text.

        Translated Text:
        Finally, return the result as a unique JSON object, with the following structure:

        ```
        {{
            "source_languge": The original question language,
            "target_language": The target language,
            "translation": The translation of the question to the target_language. ,
            "possible": true|false,
            "reason": The reason why it is possible or not possible to translate the question.
        }}
        ```        
  contextStg:
    sameContext:
      default:
        text: |
          Below is a conversation followed by a question. You must determine if the question corresponds to the same context as the conversation or if it is from a different context.
          Respond only with: [SAME CONTEXT] o [DIFFERENT CONTEXT]

          Conversation:
          {memory}

          Question:
          {query}          
      es:
        text: |
          A continuación hay una conversación y seguidamente una pregunta. Debes responder si la pregunta corresponde al mismo contexto de la conversación o es una pregunta de un contexto diferente.
          Responde únicamente con: [MISMO CONTEXTO] o [DIFERENTE CONTEXTO]

          Conversación:
          {memory}

          Pregunta:
          {query}          
    recreatedQuestion:
      default:
        default:
          text: |
            Answer with just a new question or the original question.
            Rewrite the original question only if it follows the conversation. Always rewritten question in the same language as the user's question.

            Conversation:
            {memory}

            Original question:
            {query}

            Rewritten question:            
        es:
          text: |
            Responde sólamente con una nueva pregunta.
            Reescribe la pregunta original si es una continuación de la conversación. Utiliza el idioma de la peticion del usuario para rescribir la pregunta.

            Conversación:
            {memory}

            Pregunta original:
            {query}

            Pregunta reescrita:            
      system:
        default:
          text: |
            The user text contains a query, plus the previous conversation turn.
            - If the previous conversation is relevant for the current query, incorporate it into the query and produce a rewritten query
            - else just repeat the current query.

            Always rewrite the question in the same language as the user's question.            
        es:
          text: |
            El texto del usuario contiene una consulta, además del turno anterior de la conversación.

            - Si la conversación anterior es relevante para la consulta actual, incorpórala en la consulta y produce una consulta reescrita.
            - Si no es relevante, simplemente repite la consulta actual.

            Reescribe siempre la consulta en el mismo idioma en que está formulada la consulta del  usuario.            
      human:
        default:
          text: |
            Previous conversation:
            {memory}

            Current query:
            {query}

            Rewritten query:            
        es:
          text: |
            Conversación anterior:
            {memory}

            Consulta actual:
            {query}

            Consulta reescrita:            
      order: ["system", "human"]
  postFilteringStg:
    relevantDocument:
      default:
        text: |
          Below is an excerpt of text followed by a question. You must determine if the excerpt is relevant or irrelevant for answering the question.
          Respond only with: [RELEVANT] o [IGNORABLE]

          Excerpt:
          {extract}

          Question:
          {query}          
      es:
        text: |
          A continuación hay un extracto de texto y seguidamente una pregunta. Debes responder si el extracto es relevante o ignorable para responder la pregunta.
          Responde únicamente con: [RELEVANTE] o [IGNORABLE]

          Extracto:
          {extract}

          Pregunta:
          {query}          
    relevantSql:
      default:
        text: |
          Given the following question:
          `{question}`

          Is it possible to answer, using the data contain in the following table?:
          ```sql
          {sql_table_definition}
          ```


          **Explain briefly, all your decisions**.
          First, identify which tables are necessary to answer the question. Justify why you selected each of these tables.
          Use the following format:
          ```
          I need the following tables to answer the question:
            - <table_name>: <reasoning>
            - <table_name>: <reasoning>
            ...
          ```

          Then, identify which columns are necessary to answer the question. Justify why you selected each of these columns.
          Write the list of columns you identified, and the reasoning after each column, using the following format:
          ```
          I need the following columns to answer the question:
            - <table name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            - <table_name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            ...
          ```

          Then, tell if the tables and columns you identified are enough to answer the question.
          Write the answer using the following format:
          ```
          Possible to answer the question using the former columns:
            - <reasoning>
            - Result: <Yes|No>
          ```

          Then, explain, step by step, how you would write the SQL query to answer the question, using the columns you identified.
           **Use the full qualified names of the columns**. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.

          Finally, tell if the question can be answered using this format:

          ```
          {{
              "possible": true|false,
              "reason": The reason why it is possible or not possible to answer the question.
          }}
          ```          
  generativeStg:
    stuff:
      default:
        default:
          text: |
            Use the following context extractions to answer the question at the end.

            Contexto:
            {context}

            If the extracted context do not contain the answer avoid coming up with an answer, and response you do not have information for answering and kindly invite the user to make a new question.

            Question:
            {question}

            Never include information by your own using your own knowledge.
            {extra_prompt}            
        es:
          text: |
            Utilice el siguiente contexto que ha sido extraido  para responder la pregunta del final.

            Contexto:
            {context}

            Usando esta información, responde a la pregunta del usuario.
            Si la información no contiene la respuesta evita firmemente responder, di que desconoces la respuesta e invita educadamente al usuario a que formule una nueva pregunta.

            Pregunta:
            {question}

            Nunca incluyas información utilizando tus propios conocimientos.
            {extra_prompt}            
      system:
        default:
          text: |
            Respond in language {user_query_language}.

            Question:
            {question}            
          args:
            user_query_language: "#.auto.language.user_query"
        es:
          text: |
            Responde en el idioma {user_query_language}.

            Pregunta:
            {question}            
          args:
            user_query_language: "#.auto.language.user_query"
      human:
        default:
          text: |
            You are going to generate an answer for a user question or query.
            To generate the answer, take always into account all the information available in the context provided.

            Context:
            {context}

            Question:
            {question}

            Never include information by your own using your own knowledge.
            {extra_prompt}            
        es:
          text: |
            Vas a generar una respuesta para una pregunta o consulta del usuario.
            Para generar la respuesta, ten siempre en cuenta toda la información disponible en el contexto proporcionado.

            Pregunta:
            {question}

            Contexto:
            {context}

            Nunca incluyas información utilizando tus propios conocimientos.
            {extra_prompt}            
      order: ["system", "human"]
    notAnswerResponse:
      default:
        text: |
          You are a question answering agent. You have tried to answer this question: {query}
          However you do not have information to answer this.
          Please, tell the user that you are not able to answer, apologize and invite the user to make other question.
          Avoid any harmful answer, such as sexual, rude, sexist or racist.
          Respond in language {user_query_language}.

          User question:
          {query}          
        args:
          user_query_language: "#.auto.language.user_query"
      es:
        text: |
          Eres un agente de respuesta a preguntas. Has intentado responder a esta pregunta: {query}
          Sin embargo, no tienes información para responder a esto.
          Por favor, dile al usuario que no puedes responder, discúlpate e invita al usuario a hacer otra pregunta.
          Evita cualquier respuesta dañina, como sexual, grosera, sexista o racista.
          Responde en el idioma {user_query_language}.

          Pregunta del usuario:
          {query}          
        args:
          user_query_language: "#.auto.language.user_query"
    informationExtraction:
      default:
        default:
          text: |
            The original question is this: {question}
            We have provided a previous answer: {existing_answer}
            Only if necessary, refine the answer exclusively with the context below.
            ------------
            {context_str}
            ------------
            Given the new context, refine the original answer to improve the quality of the response.
            If the context is useless, respond with the exact words of the original answer.
            {extra_prompt}            
        es:
          text: |
            La pregunta original es esta: {question}
            Hemos proporcionado una respuesta previa: {existing_answer}
            Sólo si es necesario refina la respuesta exclusivamente con el contexto a continuación.
            ------------
            {context_str}
            ------------
            Dado el nuevo contexto, refina la respuesta original para mejorar la calidad de la respuesta.
            Si el contexto es inútil responde con las mismas palabras de la respuesta original.
            {extra_prompt}            
      human1:
        default:
          text: "{question}"
        es:
          text: "{question}"
      ia:
        default:
          text: "{existing_answer}"
        es:
          text: "{existing_answer}"
      human:
        default:
          text: |
            Refine the existing answer only if necessary, exclusively with the context below.
            ------------
            {context_str}
            ------------
            Given the new context, refine the original answer to improve the quality of the response.
            If the context is useless, respond with the exact words of the original answer.
            {extra_prompt}            
        es:
          text: |
            Refina la respuesta existente, sólo si es necesario, exclusivamente con el contexto a continuación.
            ------------
            {context_str}
            ------------
            Dado el nuevo contexto, refina la respuesta original para mejorar la calidad de la respuesta.
            Si el contexto es inútil responde con las mismas palabras de la respuesta original.
            {extra_prompt}            
      order: ["human1", "ia", "human"]
    responseConsolidation:
      default:
        default:
          text: |
            Below I provide you a context.
            ---------------------
            {context_str}
            ---------------------

            Given exclusively the context, and without using any prior knowledge, respond with a single sentence to the question:
            {question}

            {extra_prompt}            
        es:
          text: |
            A continuación te doy un contexto.
            ---------------------
            {context_str}
            ---------------------

            Dado exclusivamente el contexto, y sin usar ningún conocimiento previo responde con una única frase a la pregunta:
            {question}

            {extra_prompt}            
      system:
        default:
          text: |
            Below I provide you a context.
            ---------------------
            {context_str}
            ---------------------

            Given exclusively the context, and without using any prior knowledge, respond with a single sentence to the question:
            {question}

            {extra_prompt}            
        es:
          text: |
            A continuación te doy un contexto.
            ---------------------
            { context_str }
            ---------------------

            Dado exclusivamente el contexto y sin usar ningún conocimiento previo responde con una única frase a cualquier pregunta.

            { extra_prompt }            
      human:
        default:
          text: "{question}"
        es:
          text: "{question}"
      order: ["system", "human"]
    sqlPrompt:
      default:
        text: |
          Generate a SQL query statement to answer the following question:
          `{question}`

          Use the data contained in the following table, as defined in SQL:
          ```sql
          {sql_table_definition}
          ```

          The following tables, containing auxiliary information, are also available:
          ```sql
          CREATE TABLE D_CBD_Static_Geo_Area_v6 (GEO_AREA_ID VARCHAR, CBD_GEO_AREA_LEVEL1_ID VARCHAR, CBD_GEO_AREA_LEVEL2_ID VARCHAR, CBD_GEO_AREA_LEVEL3_ID VARCHAR, CBD_GEO_AREA_LEVEL4_ID VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area IS 'Geographical areas. This table contains foreign keys to the different levels of geographical areas. In particular, it contains the foreign keys to these tables: CBD_Static_Geo_Area_Level1, CBD_Static_Geo_Area_Level2, CBD_Static_Geo_Area_Level3, CBD_Static_Geo_Area_Level4. Therefore, this tables is used, via JOIN, to query the geographical information contained in the different levels of geographical areas. For instance, if you have a table T with a field GEO_AREA_ID and you need to check whether this location corresponds to the region of Asturias you will need to look for GEO_AREA_ID in this table, then extract the CBD_GEO_AREA_LEVEL4_ID and query the table CBD_Static_Geo_Area_Level4 to get the name of the region.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL1_ID IS 'Identifier of the geographical area Level 1 (max level of detail: CP or similar). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL2_ID IS 'Identifier of the geographical area Level 2 (City/Town). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code. This field does not contain location names.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level2_v6 (CBD_GEO_AREA_LEVEL2_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, CBD_GEO_AREA_LEVEL3_ID VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level2 IS 'Geographical area level 2 (State)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.CBD_GEO_AREA_LEVEL2_ID IS 'Identifier of the geographical area Level 2 (City/Town). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 2. FORMAT: alphanumeric string containing the name of the city/town.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 2';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 2';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level2.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level3_v6 (CBD_GEO_AREA_LEVEL3_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, CBD_GEO_AREA_LEVEL4_ID VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, ISO_3166_2_CD VARCHAR, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level3 IS 'Geographical area level 3 (Region)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.CBD_GEO_AREA_LEVEL3_ID IS 'Identifier of the geographical area Level 3 (Province). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 3. FORMAT: alphanumeric string containing the name of the province.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 3';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 3';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.ISO_3166_2_CD IS 'ISO 3166-2 associated';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level3.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Geo_Area_Level4_v6 (CBD_GEO_AREA_LEVEL4_ID VARCHAR, GEO_AREA_LEVEL_DES VARCHAR, LONGITUDE_LON_CO DOUBLE, LATITUDE_LAT_CO DOUBLE, HASC_1_CD VARCHAR, GEO_AREA_ID VARCHAR, GEO_STD_AREA_CD VARCHAR, OB_ALPHA_ID VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Geo_Area_Level4 IS 'Geographical area level 4 (min. Detail)';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.CBD_GEO_AREA_LEVEL4_ID IS 'Identifier of the geographical area Level 4 (State/Region). FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_AREA_LEVEL_DES IS 'Description associated to the identifier level 4. FORMAT: alphanumerical string containing the name of the state/region. EXAMPLE VALUES: ''Asturias'', ''Andaluc\u00eda'', etc.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.LONGITUDE_LON_CO IS 'Longitude coordinates (in WGS84) associated with level 4';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.LATITUDE_LAT_CO IS 'Latitude coordinates (in WGS84) associated with level 4';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.HASC_1_CD IS 'Hierarchical administrative subdivision codes ';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_AREA_ID IS 'Identifier of the geographical area considered. FORMAT: string containing a numerical code.';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.GEO_STD_AREA_CD IS 'Standard code of the geo area';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.OB_ALPHA_ID IS 'Alphanumeric Organizational Business ID';
              COMMENT ON COLUMN D_CBD_Static_Geo_Area_Level4.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_CBD_Static_Station_Type_v6 (STATION_TYPE_CD VARCHAR, TECH_LEVEL_WEIGHT_QT FLOAT, STATION_TYPE_L2_DES VARCHAR, STATION_TYPE_L1_DES VARCHAR, STATION_TYPE_L2_ORDER_NUM INT, STATION_TYPE_L1_ORDER_NUM INT, STATION_TYPE_ORDER_NUM INT, CONSCIOUS_IND BOOLEAN, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_CBD_Static_Station_Type IS 'Station types';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_CD IS 'Device type';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.TECH_LEVEL_WEIGHT_QT IS 'Associated weight for the technologic level of the home';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L2_DES IS 'Station type level 2';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L1_DES IS 'Station type level 1';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L2_ORDER_NUM IS 'Station type order level 2';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_L1_ORDER_NUM IS 'Station type order level 1';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.STATION_TYPE_ORDER_NUM IS 'Station type order';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.CONSCIOUS_IND IS 'Indicates if the related device type has energy efficiency';
              COMMENT ON COLUMN D_CBD_Static_Station_Type.EXTRACTION_TM IS 'Date-time of the record';

          CREATE TABLE D_Segment_v8 (OPERATOR_ID VARCHAR, SEGMENT_ID VARCHAR, SEGMENT_DES VARCHAR, GBL_SEGMENT_ID VARCHAR, SEGMENT_GROUP_ID VARCHAR, SEGMENT_GROUP_DES VARCHAR, EXTRACTION_TM VARCHAR);
              COMMENT ON TABLE D_Segment IS 'Classifications of the customers, attending to different segmentation criteria, for marketing and management issues, according to OB criteria and its correspondence with the global segment classification';
              COMMENT ON COLUMN D_Segment.OPERATOR_ID IS 'Global Operator Identifier (Operator acting as owner of the information present in the current entity)';
              COMMENT ON COLUMN D_Segment.SEGMENT_ID IS 'Organisational segment of the client, in the OB. FORMAT: Numerical code.';
              COMMENT ON COLUMN D_Segment.SEGMENT_DES IS 'Segment description. This is the actual name of the segment. POSSIBLE VALUES: ''NTT'', ''Residencial'', ''Pymes'', ''Residencial/SC'', ''Autonomos'', ''Operadores'', ''Grandes Clientes'', ''Residencial Prepago'', ''Telefonica'', ''Sin Clasificar'', ''Empresas''';
              COMMENT ON COLUMN D_Segment.GBL_SEGMENT_ID IS 'ID of the global segment classification';
              COMMENT ON COLUMN D_Segment.SEGMENT_GROUP_ID IS 'ID code of the segmentation group';
              COMMENT ON COLUMN D_Segment.SEGMENT_GROUP_DES IS 'Description of the segmentation group. POSSIBLE VALUES: ''0.- OPERADORES'', ''1.- U.N. Empresas'', ''2.-U.N. Gran Público'', ''3.- TELEFONICA'', ''4.- SIN CLASIFICAR''';
              COMMENT ON COLUMN D_Segment.EXTRACTION_TM IS 'Date-time of the record';
          ```

          Some of the former tables contains columns in full-qualified format. For instance, these are some examples of full-qualified columns:
          ```
          record_name.field_name
          TEC_PLAT_REC.DEVICE_ID
          record_name.subrecord_name.field_name
          TEC_PLAT_REC.TEC_PLAT_SUBCOMP_REC.DEVICE_ID
          ...
          ```
          Always use the full-qualified format when referring to columns in the tables. For instance, if you need to use the column 'TEC_PLAT_REC.DEVICE_ID', you should not refer to it as 'DEVICE_ID', but as 'TEC_PLAT_REC.DEVICE_ID'.
          **Explain in detail, step by step, all your decisions**.
          If you need to filter by a higher level geographical such as a region (Comunidad Autónoma) you will need to:
          - join the `GEO_AREA_ID` field of the data table (such as `CBD_HGU_Detail_Daily`) with the `GEO_AREA_ID` field in `D_CBD_Static_Geo_Area` table
          - then join the `CBD_GEO_AREA_LEVEL4_ID` field in the `D_CBD_Static_Geo_Area` with the `CBD_GEO_AREA_LEVEL4_ID` field in the `D_CBD_Static_Geo_Area_Level4` table
          - then compare the `GEO_AREA_LEVEL_DES` field in the `D_CBD_Static_Geo_Area_Level4` table with the name of the region (e.g., 'Cantabria'), since the DESCRIPTION field does contain the actual name of the geographical area.
          **Only perform these joins if explicit filtering or grouping by geographical location is necessary**.

          First, identify which tables are necessary to answer the question. Justify why you selected each of these tables.
          Use the following format:
          ```
          I need the following tables to answer the question:
            - <table_name>: <reasoning>
            - <table_name>: <reasoning>
            ...
          ```
          Then, identify which columns are necessary to answer the question. Justify why you selected each of these columns.
          Write the list of columns you identified, and the reasoning after each column, using the following format:
          ```
          I need the following columns to answer the question:
            - <table name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            - <table_name>:
              - <column_name>: <reasoning>
              - <column_name>: <reasoning>
              ...
            ...
          ```
          Then, tell if the tables and columns you identified are enough to answer the question.
          Write the answer using the following format:
          ```
          Possible to answer the question using the former columns:
            - <reasoning>
            - Result: <Yes|No>
          ```
          Then, explain, step by step, how you would write the SQL query to answer the question, using the columns you identified. **Use the full qualified names of the columns**. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.
          Finally, write the SQL query to answer the question, using the columns you identified. **DO NOT USE THE `JSON_OBJECT` FUNCTION IN THE QUERY**.
          Return the result as a unique JSON object, with the following structure:
          {{
              "result": <Write the SQL query here. **MAKE SURE THAT THE STATEMENT `SELECT JSON_OBJECT` is not used in the query and Use the full qualified names of the columns. Generate a valid SQL sentence in a single line without new line characters.**>,
              "status": "OK",
              "reason": <a reasoning explaining the query>
          }}
          If the former table does not contain the necessary data to answer the question, return the following JSON object:
          {{
              "result": null,
              "status": "ERROR",
              "reason": <a reasoning explaining the query>
          }}
          Make sure that the JSON object is correctly formatted, and can be parsed by a JSON parser.

Injection

Default injection configuration for atria-rag-server. It is used to avoid prompt injection.

Injection fields

Parameter	Definition	Type/Default values
`heuristics`	Heuristic sentences. Object, where the key is the language and the value is a list of phrases. Now, by default, the heuristics sentences are defined in the config, the file path is no indicated. It is important to note that the phrases added here will be also added to those defined in the security stage securityStg of the preset configuration.	object

| max_length | (Mandatory) Maximum length |number |

Injection by default

The default configuration is described as follows:

injection:
  heuristics:
    es: 
      - responde como
      - responda como
      - respondeme como
      - respondame como
    en: 
      - answer like
      - forget everything
      - forget your
  max_length: 200

Service

Defaults service configuration for atria-rag-server.

Service fields

Parameter	Definition	Type/Default values
`host`	(Mandatory) Host name	string
`port`	(Mandatory) Port id	number

Service by default

The default configuration is described as follows:

service:
  host: 0.0.0.0
  port: <AUTOCOMPLETED>
  log_level: <AUTOCOMPLETED>

Local Storage

Defaults fields related to the configuration of the local storage for documents

Local Storage fields

Parameter	Definition	Type/Default values
`atria_resources_data_folder`	(Mandatory) Folder name for data resources	string
`atria_shared_data_folder`	(Mandatory) Shared data folder name	string

Local Storage by default

The default configuration is described as follows:

local_storage_manager:
  atria_resources_data_folder: "/opt/atria-rag/data"
  atria_shared_data_folder: "/var/atria-rag-data"

Config API

Field with parameters for atria-rag-server API configuration

Config API fields

Parameter	Definition	Type/Default values
`base_url`	(Mandatory) API Config URL	string
`api_key`	(Mandatory) APIKey	string

Config API by default

The default configuration is described as follows:

aura_config_api:
  base_url: <AUTOCOMPLETED>
  api_key:  <AUTOCOMPLETED>

Retrievers

Retriever are responsible for storing the information that have been generated in the documents. Each retriever is associated with a database in order to feed or retrieve information from it.

Currently, there are three different retrievers defined in ATRIA:
-qdrant
-tfidf
-elasticsearch

Retriever fields

Each retriever type has defined specific fields, as shown below:

Parameter	Subparameters	Definition	Type/Default values
`qdrant`	`host`	(Mandatory) Host service Qdrant	string
	`port`	(Mandatory) Port service Qdrant	number
	`prefix`	(Mandatory) Prefix to collection	string
`tfidf`	`dump_name`	(Mandatory) Dump name of service Tfidf	string
`elasticsearch`	`host`	(Mandatory) Host service Elasticsearch	string
	`ca_crt`	(Mandatory) Path certificate Elasticsearch	string
	`username`	(Mandatory) Username service Elasticsearch	string
	`password`	(Mandatory) Password service Elasticsearch	string
	`index_name`	(Mandatory) Index service Elasticsearch	string

Retrievers by default

The default configuration is described as follows:

retrievers:
  qdrant:
    host: <AUTOCOMPLETED>
    port: 6333
    prefix: <AUTOCOMPLETED>
  tfidf:
    dump_name: /var/atria-rag-data/tfidf/dump/

Metadata

Parameter related to the configuration of metadata in atria-rag-server

It is used to setup how metadata is used when providing responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata. The metadata is used to filter the candidates and provide additional information in the response.

Metadata fields

Parameter	Subparameters	Definition	Type/Default values
`map`	`filetype`	(Optional) Type of file, typically used to specify the format	string
	`page_number`	(Optional) Page number. It could be used to identify particular pages	string
`group-by`		(Optional) Group by field names.	string
`aggregate`		(Optional) Determines how the values of duplicated fields are consolidated during grouping	string
`output_filter`		(Optional) List of fields to be displayed in the metadata	List of string
`root`		(Optional) Primary fields that will structure the final output of the metadata processing	List of string

Metadata by default

The default configuration for metadata is described as follows:

metadata:
  map:
    filetype: content-type
    page_number: page-number
  group-by: url
  aggregate: page-number
  output_filter:
    - title
    - url
    - content-type
    - page-number
    - _zxcv
  root:
    - title
    - url
    - content-type

Language identification

Parameter related to the configuration of Language Identification in atria-rag-server

It is used to identify the language of the user’s question. The result is a dictionary containing the detected language in ISO 639-3 format and its corresponding conversion.
In addition to language identification, the user’s question is preprocessed at this stage, and special characters that may cause recognition errors are removed. For example, line breaks. In case of error, the default language is returned.

This language identification is calculated through fasttext library.

Language identification fields

Parameter	Definition	Type/Default values
`language_default`	(Optional) Language in ISO 639-3 format (two letters). For example: `es`	string
`score_threshold`	(Optional) Score threshold used to respond in the identified language or in the default language. For example: `0.85`	float
`model_path`	(Mandatory) Model path. For example: `/opt/atria-fasttext/fasttext_model.bin`	string
`chars_to_clean`	(Optional) Characters to be cleaned. By default is `['/n']`	list of string

Language Identification by default

The default configuration for language identification is described as follows:

language_identification:
  score_threshold: <AUTOCOMPLETED>
  language_default: <AUTOCOMPLETED>
  model_path: "/opt/atria-fasttext/fasttext_model.bin"

Docs:

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

Aura authentication flow

Description of the authentication flow for Aura users

The authentication validation process

Before starting a conversation with aura-bot, the channel needs to set a valid auraId and a fresh DirectLine token, if accessing via Direct Line, that should be sent as authorization header of bearer type in the request to the bot.

Find further information about Direct Line request in MS DirectLine API description.

Authentication validation in aura-bot consists of two phases:

Validate that the Direct Line token is a valid one, generated by the bot instance running behind aura-bot.
Validate the Aura credentials of the user, currently only based on Kernel authentication. If request authentication fails, the message is no longer processed, and an unauthenticated error response is returned to the channel.

An Aura channel should send its auraId in the from.id field of the request to the bot. Once the Direct Line token has been validated, aura-bot reads the from.id field to validate it:

Firstly, aura-bot checks if the auraId exists in the AuraUsers database and, if exists, then goes on with the authentication in Kernel.
- If the channel allows anonymous users: In the happening that the received auraId does not exist in the AuraUsers database, then the user is marked as anonymous and the Kernel authentication validation is not launched.
- If the channel does not allow anonymous users, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
Kernel authentication validation:
- A new fresh Kernel accessToken is requested for the userId and authorizationId related to the auraId.
- If the authorizationId is invalid or no longer exists in Kernel, then an UNAUTHENTICATED error is sent to the channel, informing that the Kernel authentication process must be relaunched before going on.
- Then a fresh Kernel introspect token is requested, so deeper information about the user identities and permissions for aura-bot is obtained.
- Finally, the Kernel UserProfile info is obtained and processed to obtain further information about the user’s contract, for instance, its subscription type.
- After that, all this information is stored in a cache during the time when Kernel accessToken is valid. During this period, the authentication validation process is avoided.
- Besides, all this information is set in the AuraUser model and stored in the conversation context of the bot to be available during the rest of the conversation messages processing.

The authentication process is managed by the fourth-platform-authorization-middleware.

Users data storage

Authenticated users

Users database

When a user authenticates with the basic authentication mechanism of a channel, the user’s information is created/updated in MongoDB and aura-bot accesses it through the aura-authentication-api API Aura Services API published in Kernel.

For instance, in WhatsApp, when the user authenticates with SMS-OTP, her information is stored in AuraUsers database.

Local cache

It is the node cache that each pod has with information from the users.

The information is saved on each request and expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Remote cache

Mongo cache with aura-bot users’ information. It is shared by all pods.

The information is saved on each request and expires in 1 hour, configurable via AURA_MONGODB_BOT_COLLECTION_CACHES_INDEX_TTL environment variable.

Anonymous users

Local cache

Node cache to store anonymous users’ information, who are accessing each pod.

The information expires in 5 minutes, configurable via AURA_USER_LOCAL_CACHE_TTL environment variable.

Both types of users

BotFramework conversational cache

This is the conversational cache of BotFramework, which is called internally in aura-bot persistentData.

It is a MongoDB cache with three parts: ConversationData, UserData and AuthData. Therefore, as this section is related to users’ information, it is stored in the last two sections.

Find more information about cache module.

How does the authenticated user’s cache expire?

The expiration of the cache depends on different factors:

The TTL of each cache element.
Kernel accessToken is no longer valid.
If the accountRemovalTimestamp of the conversational cache is greater than the timestamp of the cache

Authentication process flowchart

The following flowchart shows the authentication process:

Authentication steps

getUserData()

This function gets the user’s data from AuraUsers database, accessing through the Aura Services API published in Kernel.

If the endpoint returns a 404 error, null is returned by the function because in this case the user is anonymous, but it depends on the channel configuration to mark it as an error, if the channel does not support anonymous users ( for example, novum-mytelco channel), or as a valid anonymous users, for channels that allowed them (such as WhatsApp or Aura Webclient).

If other error is returned, the function throws an error and the authentication flow ends.

In the normal flow, the endpoint returns a user and the function returns a AuraUserModel object:

{
   "userAuraId":"c2aa81f0-abd9-444f-b7cb-47c179f10556",
   "userAuraIdGlobal":"d065dba31c79090a9e3c5afa94558d0c39ffa90c8e136931a5a12069418efad5",
   "userChannel":{
      "id":"45494a5b-835a-4fff-a813-b3d2be529dbe",
      "dialogs":[

      ],
      "outputMessageFormat":null,
      "allowAnonymous":null,
      "name":null,
      "shortName":null,
      "fpaAuthIntegrated":null
   },
   "authorizationId":"",
   "userPhoneNumber":"+34600000003",
   "userClientId":"up24456789",
   "timestamp":1575366984,
   "userPhoneType":null,
   "userSubscriptionType":null,
   "userAccessToken":null,
   "introspectScopes":null,
   "userProfile":null,
   "userType":null,
   "userAccountNumber":null
}

getChannelConfiguration()

This method returns an ChannelConfiguration object. This function tries to obtain the channel configuration by the channelId or channelName passed as parameters.

{
  "dialogLibraries": [
    {
      "name": "common",
      "dialogs": [
        {
          "id": "greetings",
          "allowAnonymous": true,
          "triggerConditions": [
            {
              "intent": "intent.common.greetings"
            }
          ]
        }
      ]
    }
  ],
  "id": "45494a5b-835a-4fff-a813-b3d2be529dbe",
  "name": "novum-mytelco",
  "nlp": {
    "enabled": true,
      "enabled": true
    }
  },
  "prefix": "nov",
  "requestOptions": {
    "requestOptionsVersion": {
      "1": {
        "channel": "directline"
      }
    }
  },
  "responseOptions": {
    "dialogContext": {
      "cardActions": {
        "generate": "always",
        "generateList": true
      },
      "defaultListType": "ordinalCardinal",
      "disabled": false,
      "normalizeTerms": true,
      "processFromClient": true,
      "promptChoice": {
        "generate": "always",
        "generateList": true
      },
      "returnToClient": false
    }
  },
  "security": {
    "authPurposes": "customer-self-service identify-customer aura-technical-problems-purpose",
    "channelId": "novum-mytelco"
  }
}

getInitialUserType()

This method returns an initial approach of the userType, because at this point some user types cannot be inferred.

Depending on the channel configuration and the user returned by getUserData(), there are four possible scenarios:

getUserData() returns a valid user
- The user has userType
  - User.userType is returned
- The user does not have userType
  - Undefined is returned
getUserData() returns null
- The channel allows anonymous
  - Anonymous is returned
- The channel does not allow anonymous
  - Unauthenticated is returned

At this point, we can have three different flows:

If the user is anonymous, it is returned with the minimal data available.
If the user is unauthenticated and the channel have integrated auth, getIntegratedAuthIntent() is called but if the channel does not have integrated auth, an error is returned and the authentication ends.
If the user is undefined or other type, it starts the flow to obtain the data from Kernel.

getIntegratedAuthIntent() (Only unauthenticated users)

This method returns the intent to redirect to the integrated authentication.

This intent is returned in user.redirectIntent provided by the authentication function.

getUserAccessToken()

This method constructs the options object with scopes, purposes, authorizationId, deviceId, security.channelId and userId. Afterwards, it makes the request and obtain the token.

If an error occurs, the function will throw an error and the authentication ends with error.

security.channelId is added when requesting the jwt-bearer.

getUserProfile()

This method returns the user profile from Kernel. If there is any error, it will be thrown and the authentication will end with error.

{
    "id": "up24456789",
    "name": "ESP - Usuario de Prueba 2 - prepago",
    "id_document": {
      "country": "ESP",
      "type": "NIF",
      "value": "712724440A"
    },
    "identities": [
      {
        "type": "phone_number",
        "id": "+34600000003",
        "services": ["mobile_prepaid"],
        "roles": ["owner", "admin"]
      }
    ]
}

getAnonymousUserProfile()

This method returns the user profile from Kernel, for anonymous users. If there is any error, it will be thrown and the authentication will end with error.

[
  {
    "identities": [
      {
        "roles": [
          "owner"
        ],
        "id": "12SIME16",
        "services": [
          "authentication"
        ],
        "type": "uid"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34680395460",
        "services": [
          "mobile_postpaid"
        ],
        "type": "phone_number"
      },
      {
        "roles": [
          "owner",
          "basic",
          "admin"
        ],
        "id": "+34911725467",
        "services": [
          "landline",
          "internet"
        ],
        "type": "phone_number"
      },
      {
        "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613",
        "type": "uid",
        "roles": [
          "owner"
        ],
        "services": [
          "authentication"
        ]
      }
    ],
    "id": "CD53D6C5285CB60DD8E50052C1DBFADDDA033613"
  }
]

encodeAnonymousData()

This method sets the userId and auraIdGlobal for anonymous users. These values are needed to be stored in KPIs.

{
  "userId": "76661cf96c2bda27c4fb016627f2d74af1c3cee496b76cf5d7bc2b2ad8a38cb2",
  "auraIdGlobal": "8eeb101175bfe9c247e9d10669c0d1696e8034f8e1a12b25b54780e00de0e1c1!616e6f6e796d6f7573"
}

getAuraUserType()

This method returns the final userType and the userIdentity.

First of all, identities are filtered and only the type phone_number with services prepaid, postpaid, control, hybrid or internet are returned.
After that, we need to select the phone number of the user among the numbers filtered.
- If we have more than 1 number and userData do not have userPhoneNumber (the user has not been logged with phone number), the userType returned is multimsisdn and userIdentity is undefined.
- If there is only 1 phone number, userType is monomsisdn.
- If there are many phones but we also have userPhoneNumber in userData, this phone is searched in phones array and if found, the user is considered monomsisdn although it is multimsisdn.

Monomsisdn users return userType (prepaid, postpaid or control) and userIdentity filled:

{
   "type":"phone_number",
   "id":"+34600000003",
   "services":[
      "mobile_prepaid"
   ],
   "roles":[
      "owner",
      "admin"
   ],
   "phone_type":"mobile",
   "subscription_type":"prepaid",
   "identifier":"+34600000003"
}

getIntrospect()

This method returns the scopes, purposes and boundScopes for this user from Kernel.

{
   "scopes":[
      "event-low-data-read",
      "insights-data-usage-result-read",
      "mobile-balance-transfer-write",
      "auraid-read",
      "webviews-phone-number-read",
      ...
   ],
   "purposes":[
      "sim-upgrade-suggestion",
      "identify-customer",
      "customer-self-service",
      "aura-read-insight-events",
      "device-recommendations",
      "detect-abnormal-usage"
   ],
   "identifierBoundScopes":[

   ]
}

Docs:

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

General RAG capability

Overview of the General RAG capability, encompassing the underlying technology, its application in ATRIA and the benefits derived from its use

Application in ATRIA: General RAG

ATRIA enables the generation of generic questions experiences (use cases) to resolve users' requests expressed in natural language and based on FAQs by supporting complex calls to AI models.
This is done through the integration of a predefined RAG (Retrieval Augmented Generation) chain while guaranteeing security and privacy in interactions.

Figure 13. General RAG in ATRIA

The predefined RAG chain defined in ATRIA is called General RAG. It includes additional steps that overcome the potential of Retrieval Augmented Generation technologies by optimizing the input prompt and generating more accurate responses. See details in section Functional overview.

In upcoming versions, constructors will be able to design their own LLMs chains based on RAG.

Interaction with ATRIA General RAG capability

This service is accessible via API, enabling its consumption both from Aura Platform and any external application.

Current available models

The AI-driven models currently integrated into ATRIA are included here.

Functional overview of General RAG

The use of the General RAG capability encompasses three different stages:

Data ingestion, that includes uploading the knowledge bases used for lexical (keywords) and semantic search (embeddings) search.
Discover the underlying processes for that in the document Import documents into *ATRIA, as well as tips for data curation, a process recommended before the documents uploading.
RAG chain: If a request enters ATRIA, the General RAG capability executes the predefined steps in its chain, which are described in the following figure.
Aura answer: The generated response is sent to the user.

Figure 14. General RAG stages

Making a zoom in the stages of the General RAG pipeline, the following steps are included:

Figure 18. General RAG chain

Security: the request is analyzed to improve security and prevent prompt injection.
Multi-language: The multi-language feature allows users to receive responses in their own language. The system automatically detects the language in the user’s request in the multi-language step of the RAG pipeline, and this language is afterwards used in the response generation stage to provide the response back to the user.
Conversation history: If there is information from previous interactions, they are now analyzed to check if they are relevant for the current query. In this case, the query is rewritten using this context information.
Retrieval: Lexical and semantic retrieval from databases that return text blocks with key information to compose the response.
Post-filtering: The retrieved text blocks are compared with the user query to determine if they are relevant or not to answer the question.
Response generation: If so, the fragments are reordered and used to compose an augmented prompt which is resolved through LLMs technology.

Benefits from the use of ATRIA General RAG

The General RAG predefined chain enables all the advantages of RAG technologies to the resolution of use cases. Specifically for generic questions use cases based on FAQs.
Moreover, General RAG capability integrates other extra features that lead to more accurate responses:
- Features to avoid prompt injection
- Conversation history
- Filtering steps
The use of Retrieval Augmented Generation techniques enables the use of continually updated information, every time an up-to-date knowledge base is uploaded into the system.

Generative feedback functionality

When testing how Generative AI/RAG capabilities work with the ATRIA web interface aura-manager, it is possible to use the feedback functionality to estimate the user’s satisfaction regarding the quality and appropriateness of the generated answer to her request. This can be done easily by clicking the thumbs-up or thumbs-down icons.

Do you need a more detailed explanation on how Generative feedback capability works?

Access the document Generative feedback functional description
Access the document Use ATRIA web interface (aura-manager) to discover how to utilize this functionality.

Docs:

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

Generative AI capability

Overview of the Generative AI capability, encompassing the underlying technology, its application in ATRIA and the benefits derived from its use

Introduction to Generative AI

What is Generative AI?

Generative Artificial Intelligence is a subset of Machine Learning that focuses on the creation of new content, such as text, images, or music, based on patterns learned from large volumes of data.

This technology has advanced significantly in recent years, fueled by the development of Deep Learning models that can understand and replicate complex data structures.

Figure 10. Generative AI technology

Below are the main steps in how Generative AI works:

Training: The model is fed with extensive datasets containing examples of the target content, allowing the system to identify patterns, structures and relationships among different elements.
Instruction input: The user provides an instruction or “prompt,” which can be a question, a topic, or any indication of what is expected from the model output.
Content generation: Based on the information obtained during training, the model applies complex algorithms to generate a relevant and coherent response or new content aligned with the user’s request.
Response delivery: The model presents the generated output to the user quickly and efficiently. It can be a text, an image, or any other type of content.

Within Generative AI, the Large Language Models (LLMs) are advanced AI models designed to understand and generate human-like text, typically trained on vast amounts of text data, enabling them to predict and produce coherent and appropriate text. They are the ones integrated into ATRIA.

Benefits and limitations

The main benefits from the use of Generative AI are summarized below:

Creativity and Originality: Generative AI generates new and original content that can inspire creators.
Efficiency: Generative AI automates content generation tasks, allowing humans to focus on more complex activities.
Personalization: Generative AI generated content is tailored to the specific needs of users.
Access to information: Generative AI provides quick answers to complex questions thanks to its extensive access to data.

Despite these advantages, Generative AI has certain limitations that led ATRIA to integrate other complementary technologies:

Hallucinations: Generative AI can generate inaccurate responses that seem plausible, leading to misinformation.
Temporal Limitations: Generative AI models are limited to the information available at the time of their last training, meaning they cannot access real-time or recent data updates.

Application of Generative AI in ATRIA

Generative AI is a key ATRIA capability provided by a predefined chain designed with the LLM/LMM Experiences Builder.

ATRIA enables the generation of experiences (use cases) to resolve users' requests expressed in natural language by supporting simple calls to AI models.
This is done through an easy integration of advanced Generative AI technologies while guaranteeing security and privacy in interactions.

Figure 11. Generative AI in ATRIA

Example case

Imagine that our platform, ATRIA, operates like a restaurant with different chefs, each specialized in a unique approach to meeting customers' needs.

A traditional generative model can be compared to Chef Manuel, a chef who spent several years mastering in traditional Spanish cuisine.

Manuel’s expertise encompasses a wide range of recipes and cooking techniques, but some of his knowledge may be outdated since he hasn’t pursued further training in recent years.

When a customer requests for a nutritious and hearty meal, Manuel relies solely on his internal knowledge to prepare a classic dish: lentils with vegetables. He does not need to search for additional information because his prior expertise is sufficient to offer a consistent and reliable answer.

A traditional generative model operates like Manuel, generating responses based solely on the implicit knowledge learned during the model's training, without consulting external sources.

Interaction with ATRIA Generative AI

This service is accessible via API, enabling its consumption both from Aura Platform and any external application.

Current available models

The AI-driven models currently integrated into ATRIA are included here.

Functional overview

The use of this capability encompasses different stages:

When a user sends a request to ATRIA, it is sent to an auto-generative content generator, the one that best aligns with the use case considering different factors such as latencies, costs, etc.
Additionally, specific instructions upon which the model must base its response are also included. These instructions can be configured to meet specific channel-level business and experience requirements but, at the same time, to ensure that the provided responses retain the nuances of tone and personality that characterize Aura.
In addition, ATRIA provides a layer of security to avoid prompt injection, that is, to prevent misuse by third-party services that can create malicious prompts as inputs and cause the model to act in unintended ways.
For example, it can prevent a user from modifying the instructions on how the system should behave or the invalidation of instructions from a predefined block of the prompt (Aura personality), if contradictory instructions are given.
The Generative AI model recognizes the request and generates the most appropriate response for it. This response is sent back to the user.

Benefits from the use of Generative AI in ATRIA

There are clear benefits derived from the integration of Generative AI in ATRIA:

Benefits for constructors

It streamlines the use cases development process, since there is no need to generate specific responses or undergo specific trainings.
Other types of experiences, not directly related to Aura, can be generated. For example: data analysis tasks, development of new products, etc.

Benefits for end-users

Our customers’ satisfaction will increase, as Aura can offer enhanced understanding capabilities.
Aura can incorporate new areas of interest for users in a more agile manner and explore new types of users for whom to develop services based on natural language recognition technologies.
ATRIA interactions guarantee security and privacy for our users.

Generative feedback functionality

Docs:

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

Handling channelData versions

Description of components that make Aura Bot capable of working with different channelData versions.

UML diagram

@startuml
title ChannelData handling diagram
actor User
participant AuraGroot
participant ChannelDataValidatorMiddleware #76bbe7
participant AuraBot #ebdff7
participant Routing #ebdff7
participant MainDialog #1add4d
participant Dialog #1c733b
participant OutgoingChannelDataNormalizerMiddleware #73c1c3
participant Adapter #1bcad5
participant AuraChannelDataHandler #ebba65
User -> AuraGroot: User request
AuraGroot -> ChannelDataValidatorMiddleware: request reaches validation middleware
alt AURA_CHANNELDATA_VALIDATION === true
    ChannelDataValidatorMiddleware -> AuraChannelDataHandler: isValidatableVersion checks if channelData request version is validatable
    AuraChannelDataHandler -> ChannelDataValidatorMiddleware: isValidatableVersion returns if version is valid
    alt isValidatableVersion === true
        ChannelDataValidatorMiddleware -> AuraChannelDataHandler: getRequestValidator validates channelData request
        AuraChannelDataHandler -> ChannelDataValidatorMiddleware: getRequestValidator returns validation
    end
end
ChannelDataValidatorMiddleware -> AuraBot
AuraBot -> MainDialog: Route to main dialog
MainDialog -> Routing: MainDialog routing step
alt channelDataRequest <= v3
    Routing -> Routing: Add information to triggerCondition
end
alt channelDataRequest >= v3
    Routing -> Routing: Add information to triggerCondition (intent.vX)
end
Routing -> MainDialog: checkLegacyDialogStep check if a conversion to legacy channel data is needed
alt channelDataRequest <= v3
    MainDialog -> AuraChannelDataHandler: getNormalized normalizes request to supported aura-bot channelData
end
MainDialog -> Dialog: Reach dialog by intent if exists
alt channelDataRequest === v3 && channelDataVersion === v3
    Dialog -> AuraChannelDataHandler: formatChannelDataV3 formats response to be compatible with v3 version
    AuraChannelDataHandler -> Dialog: formatChannelDataV3 returns formatted v3 channelData
end
Dialog -> OutgoingChannelDataNormalizerMiddleware: Pass activity formed in dialog to outgoingMiddlewares
alt channelDataRequest <= v3
    OutgoingChannelDataNormalizerMiddleware -> AuraChannelDataHandler: getNormalized Normalizes activity (output) and request (input) to be compatible with supported aura-bot version
    AuraChannelDataHandler -> OutgoingChannelDataNormalizerMiddleware: getResponseChannelData Gets original response channel data
end
OutgoingChannelDataNormalizerMiddleware -> Adapter: Middleware's pipeline is finished and result is received by the adapter
alt AURA_CHANNELDATA_RESPONSE_VALIDATION === true
    Adapter -> AuraChannelDataHandler: isValidatableVersion checks if channelData response version is validatable
    AuraChannelDataHandler -> Adapter: isValidatableVersion returns if version is valid
    alt isValidatableVersion === true
        Adapter -> AuraChannelDataHandler: getResponseValidator gets validation for the response version
    end
end
alt channelDataRequest >= v3
    Adapter -> Adapter: Add version parameter to response.
end
alt channelDataRequest < v3
    Adapter -> Adapter: getResponseChannelData gets transformed channel data from correct version (removes version field)
end
Adapter -> AuraBot: Activity is processed and ready to be sent
AuraBot -> User: Bot response
@enduml

Version Format

The version format will be a semantic versioning, (MAJOR.MINOR.PATCH). However, aura-bot will work exclusively with the MAJOR version: If a customer sends the version 3.1.0, for Aura the version is 3.

Aura will keep the original version from the request in the response. That is, if the client sends version 3.0.0, but Aura is currently working with version 3.5.1 as Aura works with the older one, there is no problem and Aura will keep the version that the client sent, 3.0.0, in the response.

For versions greater or equal to 3.0.0, aura-bot accepts either SemVer versioning (3.0.0) or major versioning (3) in channelData.version property.

Request channelData validation

The channeldata-validator-middleware executes request channelData validations. aura-bot receives the request which contains information about the channelData version. With that information, different validations are made.

More information regarding validations being made and utilities that used for this flow can be found in channelData validation.

Aura Bot channelData versions behavior

aura-bot is able to work with channelData versions v1, v2 and v3.
If a channel does not specify the version, it is assumed to be working with version v1.
Version v2 was specific for living-apps, and version v3 is the first version of the normalized channelDatamodel.
Use cases created for channelData version v1 will not be able to execute dialogs created with the v3 model and vice versa.

Intent format for v3

The format for intents in channelData version v3 only changes internally.

Therefore, when defining an intent, it is not necessary to specify its version, the dialog loading system will do it internally.

Dialog configuration

From channelData v3 onwards, it is necessary to specify the version to be used in the channelData dialogs.

If no version is specified, it is understood that they work in v1 mode for classic use cases.

If you want to work with the channelData normalized version (v3), specify it in the use case dialog configuration file.

Example:


{
  "name": "packageLibTest",
  "dialogs": [
    {
      "id": "channel-data-V3-dialog-example",
      "channelDataVersion": "v3",   <-  It's mandatory specific version for ChannelData v3
      "triggerConditions": [
        {
          "intent": "intent.factotum-test.channel-data-model"
        }
      ]
    }
  ]
}

When a dialog has specified its channelData version through the channelDataVersion property, it can only be executed if the client has specified that version in the request. Otherwise, the system will return an “I don’t understand you”.

A client can have two dialogs for the same use case with different versions, but it is mandatory that the names of the dialogs are different. The intents must be called exactly the same for v3 and for others, as the format of the intents is set internally and it is not necessary to specify anything.


{
  "name": "packageLibTest",
  "dialogs": [
    {
      "id": "channel-data-V1-dialog-example",
      "triggerConditions": [
        {
          "intent": "intent.factotum-test.channel-data-model"
        }
      ]
    }
  ]
}

This configuration contains the same intent as the previous one, but the dialog is for channelData version v1, as its version has not been set. It should be noted that if you set a version channelDataVersion: v1 it will also work in v1 mode.

Routing to version v3

Loading Dialogs configuration

The first step to set the intents to their proper version must be done during the dialogs loading. This is done inside the aura-configuration package in the document channels-configuration-current.ts.


    private buildAuraChannel(channelConfiguration: ChannelConfiguration): ChannelConfiguration {
        ........

        // NORMALIZATION. Assign the intent to the channel Data Version
        channelConfiguration.dialogLibraries?.forEach((library) => {
            library.dialogs.forEach((dialog) => {
                const channelDataVersion = this.getChannelDataVersionMajor(dialog.channelDataVersion);
                if (channelDataVersion > 2) {
                    dialog.triggerConditions.forEach((triggerCondition) => {
                        triggerCondition.intent = this.getIntentByChannelDataVersion(triggerCondition.intent, dialog.channelDataVersion);
                    });
                }
            });
        });

        .......

Routing configuration

Intents whose dialogs have the property channelDataVersion with a value greater than or equal to v3 will name their intents with the corresponding version.

Example:

“channelDataVersion”: “v3” -> intent.[intent_name].v3
“channelDataVersion”: “v2” -> intent.[intent_name]
“channelDataVersion”: “v1” -> intent.[intent_name]
“No channelDataVersion” -> intent.[intent_name]

For the previous example, the dialog routing would be as follows:

“intent.factotum-test.channel-data-model.v3” -> Routing -> “channel-data-V3-dialog-example”
“intent.factotum-test.channel-data-model” -> Routing -> “channel-data-V1-dialog-example”

Establishment of intent versioning in recognizers

When a channel sets a version of the channelData greater or equal to v3, the routing step will set intent format in getIntentByChannelDataVersion(), which can be found in aura-configuration.

  public static setIntentResult(context: TurnContext, intentResult: any, utterance: string, promptCheck: boolean,
        ......
        intentResult.intent = AuraChannelsConfiguration.instance.getIntentByChannelDataVersion(intentResult.intent, ChannelDataUtils.getChannelDataVersion(context));
        ......
    }

Routing to v3 dialog

Once the routing and the recognizers steps are executed, based of the result obtained, it will be routed to a v3 dialog if channelDataVersion: "v3" and there is match in the recognized intent.

Dialogs in v3

Currently, only certain dialogs have been migrated to channelData v3 version,as specified in the following sections.

Greetings v3 dialog

Greetings dialog, which is included in common library, has been migrated to v3.

For more information about this implementation, check Create/migrate a dialog to channelData v3.

didntUnderstand special case

There is a particular case: a request needs a V3 dialog and this is not implemented. In this case, None dialog should be triggered.

At the moment, None has not being migrated to v3 so this type of requests are redirected to bot’s fallback case didntUnderstand.

This occurs due to routing appending v3 to None intent and not finding a match. This case returns an activity with the resource core:core.cancel

Prompt case

In this particular case, the last message processed by the dialog must have the channelData correct version.

Firstly, the prompt is displayed to the user going through the mainDialog, but user’s response to that prompt does not follow the same path.

During this stage, channelData is converted into v3 for compatibility with aura-bot core.

If the dialog is in version v1, channelData will not need to be modified, so the channeldata-validator-middleware will check if the dialog is legacy and will convert its response channelData to v1.

Outgoing middlewares

Once aura-bot responds, this response is being processed by certain middlewares that work in v3 version. Hence, there are two possible flows:

User is requesting a v1 dialog In this case, the response from the v1 dialog is converted into v3 immediately after the activity is created.

Once the activity is being processed by the middleware’s pipeline, it is converted from v3 to v1 by the outgoingchannelDataNormalizer middleware, that performs the same actions in reverse order than incomingchannelDataNormalizer middleware.

Once the activity is being processed by the middleware’s pipeline, it is converted from v3 to v1 in the Aura BotFramework adapter.
User is requesting a v3 dialog In this case, the response from the v3 dialog is already in the current supported version, so there is no need to merge to other version.

Adapter

Before sending the response to the user, there are a number of extra steps which are performed inside the Aura BotFramework adapter.

channelData validation

As done in the request stage, there is another validation in the response, before sending the resulting activity to the user, checking if the sent schema is valid for the activity version.

Find more information about which validations are made and utilities used for this flow in channelData validations.

Activity merging

For more information about how channelData merges are processed, check channelData mapping.

Docs:

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

Introduction to Aura channels

Overview of Aura Virtual Assistant channels, foundations and available ones

The current document includes content with low technical complexity.

For in-depth, low-level technical content related to channels, access the section channels technical documentation.

Introduction

An Aura channel is a communication means a Telefonica client may use to interact with Aura Assistant, to request for products or services.

Aura Virtual Assistant is multi-channel, as it is designed to communicate through different types channels to make requests and receive responses.

In any case, it is able to adapt to the channel’s specific requirements, providing a consistent and engaging experience across different environments while maintaining its personality and tone.

What languages do Aura Assistant talk?

To be able for a channel to communicate with Aura Virtual Assistant, it has to “speak” a language Aura can understand. As Aura platform is based on Microsoft Azure Bot Service and Bot Framework, it uses the general-purpose communication mechanism called Direct Line API, provided by Microsoft.

In this framework, Aura Virtual Assistant is able to communicate:

Directly with channels that “talk” Microsoft Direct Line
Directly through communication protocols based on Direct Line, such as Auraline
Through the use of adapters for channels that do not support Direct Line.

Direct Line

As Aura platform is based on Microsoft Azure Bot Service and Bot Framework, it uses a general-purpose communication mechanism called Direct Line, provided by Microsoft.

However, having a connection means is not enough, and Aura Virtual Assistant has designed a normalized semantic model built on top of the Direct Line protocol, to optimize the communication of Aura with channels or services: Aura Request - Response Semantic Model.

Do you need more technical details regarding Microsoft Direct Line? Access the document Direct Line communication protocol

Discover the Aura Request - Response Semantic Model.

Auraline

Aura Platform Team has developed a proprietary communication protocol: Auraline, based on Direct Line but eliminating the dependency on Microsoft Azure Bot Service.

Auraline provides significant advantages, including cost saving, higher flexibility, easy integration for channels and the ability to plan future developments according to specific needs. Additionally, it enables addressing new backend-to-backend scenarios, such as managing a channels aggregator system or responding across multiple channels or applications instead of a single one.

As the Direct Line protocol, Auraline uses the Aura Request - Response Semantic Model, within the version v3 of the channelData property.

Find detailed information regarding Auraline communication protocol

Use of adapters

For channels that do not support Direct Line, it is required to use an adapter that “translates” the information coming from the channel to a language Aura can understand. This is the case of WhatsApp channels.

The adapters are provided by aura-bridge and are based on the last version of the standard Aura request/response model.

Which channels are currently supported by Aura?

The following table shows the channels currently supported by Aura Assistant for each of the three communication protocols explained in the previous section and organized by its origin: Telefónica channels or third-party channels.

Communication protocols	Telefónica channels	Third-party channels
Channels supporting Direct Line protocols	Mobile apps (Meu Vivo) Movistar Plus IPTV (STB+desco)
Channels that require an adapter to communicate with Aura	N/A	WhatsApp Google RCS Business Messaging

Mobile apps (Meu Vivo)

Meu Vivo is a key Vivo channel that currently supports Direct Line protocol.

This app offers complete Telco experiences in Vivo, with an intuitive interface and easy interaction and with all the potential of this channel for showing both text and visual elements. The current application is built as a set of WebViews embedded in a native container. And the communication with Aura is done through Direct Line protocol based on a JSON model attached in the activity of the Bot.

Aura in Meu Vivo channel

Movistar Plus

Movistar Plus is a Telefónica proprietary channel that supports Direct Line and Auraline protocols.

Aura is integrated in Movistar Plus mobile app, providing a fast and easy interaction with the customers focused on TV experiences, mainly for searching for TV content and launching them on TV.

Although text messaging is available, the use of voice control boosts the agility of TV searching.

Aura in Movistar Plus channel

IPTV (STB+desco)

IPTV (STB+desco) is a Telefónica proprietary channel that supports Direct Line and Auraline protocols.

Aura is integrated in Movistar+ vocal remote control, offering TV experiences such as searching for TV content, navigating through menu sections, asking for recommendations, changing language, subtitles activation or open Movistar Apps.

It allows users to interact with the M+ service using only their voice, helping them to look for content faster and controlling the reproduction while keeping their privacy safe (it only listens when users keep pressing the mic button).

Aura IPTV

Aura is available on a widespread and close at hand channel such as WhatsApp. It offers an easy and agile interaction, with key benefits:

Direct and concise text responses to the users
High speed interaction with the user
Better engagement Aura-user, as WhatsApp channel is widely used by most of our users and always available in the mobile phone

Presently, Aura contains the functionalities listed below in WhatsApp. Moreover, OBs can build their own use cases in this channel.

Global use cases: onboarding, authentication, handover use case (the user asks for an agent to solve her request).
Small Talk (greetings, goodbyes, thank yous, swearwords)
Use of files and templates in experiences
Use of interactive messages in experiences
Use of emoticons in experiences
Use of footer in experiences

Aura in WhatsApp

Do you need technical details regarding WhatsApp experiences in Aura?

Descriptive documentation related to WhatsApp channel in Aura

Guidelines for the activation of WhatsApp channel

Guidelines for use cases development in WhatsApp

Aura WhatsApp design toolkit

Google RCS Business Messaging

Rich Communication Services (RCS) is a communication protocol designed to enhance traditional SMS and MMS messaging. The channel Google RCS Business Messaging allows sending different types of messages to the user, such as texts, suggested replies, suggested actions, etc. Additionally, RCS enables its users to incorporate richer content through features like video, images, cards, carousels and other interactive elements.

Aura allows Google RCS Business Messaging channel to communicate with the users through an application installed by default in their phones, with lower costs than WhatsApp.

Do you need technical details regarding Google RCS Business Messaging channel?

Google RCS Business Messaging channel descriptive documentation

Guidelines for the activation of Google RCS Business Messaging channel

Guidelines for use cases development in Google RCS Business Messaging channel

Channels technical documentation

Are you a highly-skilled technician?
Do you need low-level technical documentation regarding channels?

Access these documents:

Descriptive channels documentation

Guidelines for managing channels in Aura

Docs:

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

NLP as a Service

Discover NLP as a Service, the AI-driven functionality for seamless language recognition and integration based on Natural Language Processing technologies

Introduction to NLP technologies

Natural language processing (NLP) refers to the branch of AI concerned with giving computers the ability to process, understand and generate human language. NLP combines computational linguistics (rule-based modelling of human language) with statistical, machine learning and deep learning models to bridge the communication gap between humans and machines.

Figure 4. NLP technologies

NLP encompasses a wide spectrum of technologies designed to be integrated into diverse user experiences. It includes deterministic and probabilistic techniques, syntax and semantics methods, named entity recognition (NER), etc.

Nowadays, the use of NLP in virtual assistants is not limited to understand and respond to simple utterances but also to derive meaning and use data behind user queries, allowing them to provide relevant and precise responses resulting in more accurate and natural interactions through different NLP technologies.

Application of NLP as a Service in ATRIA

NLP as a Service enables the use of different technologies through NLP Apps (Natural Language Processing recognition stages) for understanding users’ requests and providing back accurate responses.

Currently, these technologies, both proprietary and third-party ones, are included in the Aura NLP component but, in future releases, external NLP methods will be used.

In this framework, constructors have two approaches depending on the utilized stages:

Using NLP Apps (NLP recognition stages) different from Semantic Search
Find here detailed information regarding NLP Apps capability
Using Semantic Search technology, a specific NLP App that overcomes traditional keyword-based searches through the use of embeddings.
Find here detailed information regarding Semantic search functionality

Figure 5. NLP as a Service in ATRIA

Benefits from the use of NLP as a Service

NLP as a Service offers several benefits both for constructors and end-users:

Benefits for use cases constructors

Less time and complexity of use cases development
It is possible to create and configure tailored NLP pipelines, choosing from a variety of available stages and connectors that cover different aspects of Natural Language Processing.
No need for the manual generation of training phrases (aliases) for generic questions knowledge bases.
Knowledge bases can be updated continuously in an easy and quick way.
Accessibility: any application, both internal and external to Aura Platform, can consume this service.

Benefits for Aura end users

End-users can interact with Aura in a natural and conversational way, using their own words and expressions and even informal language, slang, abbreviations, misspellings, etc.
Improved Aura’s understanding capabilities, leading to fast and reliable responses and results.
Easy update of the knowledge bases, so the users can receive reliable responses based on up-to-date data.
The NLP service can be leveraged as capabilities offered to end-users or as internal features used by other Telefonica teams in order to streamline specific internal processes.

Docs:

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

Aura file manager processes flowchart

Sequential flowchart for Aura file manager processes and API functionalities

Initialization sequence

sequenceDiagram
    participant A as Orchestrator
    participant B as HttpMonkeyPatcher
    participant C as AuraChannelsConfiguration
    participant D as AuraMongoDb.Connector
    participant E as FileQueueDao
    participant F as FileService
    participant G as FileManagerServer
    participant H as ClientOAuthToken4P
    participant I as StorageFileManager
    participant J as 4P Whatsapp API
    participant K as Aura Global Azure storage
    participant L as QueueManager
    participant M as QueueAgent
    A ->>+ B: init
    B -->>- A: instance
    A ->>+ C: init
    C ->>+ K: loadChannelsConfiguration
    K -->>- C: Channels configuration
    C -->>- A: instance
    A ->>+ D: init
    D -->>- A: instance
    A ->>+ E: init
    E -->>- A: instance
    A ->>+ F: init
    F ->>+ H: init
    loop 4P oauth tokens
        H ->>+ J: grantClient
        J -->>- H: TokenSet
    end
    H -->>- F :initialized
    F ->>+ I: new
    I -->>- F: instance
    F -->>- A: instance
    A ->>+ G: init
    G -->>- A: instance
    A ->>+ L: init
    L -->>- A: instance
    A ->>+ M: init
    M -->>- A: instance

Sequence explanation

HttpMonkeyPatcher utility is loaded, mostly to monitor HTTP traffic through Prometheus.
AuraChannelsConfiguration is loaded, which retrieves channels configuration from Aura Global Azure storage. Aura file manager needs it in order to retrieve validation configuration for the selected channel.
AuraMongoDb.Connector and FileQueueDao are loaded to access MongoDB.
FileService initializes other different services.

ClientOauthToken4P: It connects to Kernel WhatsApp API and retrieves tokens for different channels (WhatsApp).
StorageFileManager: It initializes and configures the connection against Aura Global Azure storage.

Queue components are started: QueueManager and QueueAgent, in charge of message management.
FileManagerServer is started, which exposes aura-file-manager API.

API functionalities

In this section, aura-file-manager functionalities are documented using sequence diagrams.

Detailed information about these endpoints can be found in the aura-file-manager API definition.

Upload and validate files

GET /aura-services/v1/files

Upload and validate operation. It allows to upload and validate a file based on previously defined validations.

sequenceDiagram
    actor User as Channel user
    participant K as Groot
    participant A as Bot (FileManagerRecognizer)
    participant B as Bridge (AsyncCallback plugin)
    participant C as FileManagerServer
    participant D as FileController
    participant E as FileService
    participant I as FileQueueDao
    participant J as QueueManager
    participant F as ClientOauthToken4P
    participant G as Aura Global Azure storage
    participant H as FileValidator

    User->>+K: Unprocessed attachment
    K->>-User: 204
    K->>+A: Unprocessed attachment
    A-->>-K: 204
    A->>+C: POST /files
    C-->>-A: 204
    C->>+D: uploadAndValidateFiles
    D->>+E: storeFiles
    E->>+I: insertIncomingFileRequest
    I-->>-E: Ok
    E->>+J: addTask
    J-->>-E: Ok
    D-->>-C: 204    
        alt Have queue space?
        J->>+E: processFile
        loop multiple attachments
            E->>+F: getTokenByClientId
            F-->>-E: Token
            E->>+G: uploadFile
            G-->>-E: Upload result
            E->>+G: getFileContents
            G-->>-E: File contents
            E->>+H: validateFile
            H-->>-E: Validation
            E->>+G: getSasUrl
            G-->>-E: Url
            E-->>-E: Attachment data
        end
        D-->>C: Attachments data
        C-->>B: Attachments data
        B-->>K: Attachments data
        K-->>A: Attachments data
        A-->>K: Attachments data
        K-->>User: Attachments data
    end

Actors

Channel user: User that is interacting with the dialog.
Groot: aura-groot main bot over distributed architecture .
Bot: aura-bot responsible of handling the attachments processing. It is done through the aura-file-manager recognizer.
Bridge: aura-bridge responsible of handling attachments once processed and sending data back to aura-bot.
FileManager microservice: Microservice responsible of processing attachments.
- FileManagerServer: Server responsible of handling request to the microservice.
- File: Controller that handles requests of attachments processing.
- FileService: Service where the attachments files are validated and uploaded to Aura Global Azure storage.
- ClientOauthToken4P: Small utility to retrieve and maintain authorization Kernel tokens.
- FileQueueDao: Decentralized autonomous organization (DAO) to manage BD operations.
- QueueManager: Component in charge of managing queue messages.
Aura Global Azure storage: Repository where the files are going to be stored temporarily. By default, they are accessible for one hour.
aura-file-validator utility: Utility responsible for validating files content.

Sequence explanation

A channel user has uploaded a file/s as requested by a dialog that supports attachments.
When the attachments are detected by aura-bot (through the aura-file-manager recognizer), the attachments are sent to aura-file-manager microservice to be processed.
Once the attachments are received by Aura file manager, basic checks are done synchronously (all parameters needed are present and have correct format), the request added in queue is stored and a ACK is sent to the aura-file-manager recognizer.
After sending the ACK, the real attachments processing starts asynchronously.
If queue is not full, the attachments begin to process.
The direct link is sent directly to Aura Global Azure storage, delegating on it the responsibility of its uploading.
If the repository uploads the file correctly, then aura-file-manager downloads it and, through the use of the aura-file-validator utility, validates its content.
Once the file is validated, a direct download link is retrieved from the repository, and the data is sent to aura_bridge asyncCallback endpoint.
aura-bridge translates the message and sends it to aura-groot.
aura-groot translates the message and sends it to aura-bot, where aura-file-manager recognizer will forward it to the originating dialog.
If queue is full, when one aura-file-manager pod has space enough, the attachments will be processed by QueueAgent.

Docs:

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

Actions managed by redirect command

Description of the redirect command, in charge of sending a message to Aura Groot when this command is received by Aura Bridge

Introduction

Certain actions can be performed by aura-bridge when a specific command is received. Currently, only the redirect command is implemented in the plugins that manage messages from aura-groot:

directline-whatsapp-processor plugin
directline-rcs-processor plugin

Redirect command

The redirect command allows sending a message to aura-groot when a message with this command is received by aura-bridge from aura-groot. For example, if you want to launch an intent after login in aura-groot. In this case, aura-bot needs to receive the new requested intent from outside to relaunch and complete the authentication flow.

The format of an action message is the following:

In channelData V3:

{
  "type":"message",
  "channelData":{
    "actions":[
      {
        "target":"bridge",
        "name":"REDIRECT.COMMAND",
        "params":{
          "auraCommand":{
            "type":"suggestion",
            "value":{
              "intent":"intent.common.greetings"
            }
          }
        }
      }
    ]
  },
  "inputHint":"ignoringInput"
}

In channelData V1:

{
    "type": "message",
    "channelData": {
        "customData": {
            "type": "redirect",
            "action": "REDIRECT.COMMAND",
            "data": {
                "auraCommand": {
                    "type": "suggestion",
                    "value": {
                        "intent": "intent.common.greetings"
                    }
                }
            }
        },
    },
    "inputHint": "ignoringInput"
}

In this example, if aura-bridge receives this message, it will send an auraCommand with the intent intent.common.greetings to aura-groot.

Redirect command in directline-whatsapp-processor plugin

The directline-whatsapp-processor plugin can behave in different ways depending on the message containing the REDIRECT.COMMAND action:

aura-groot message contains text in the text field: In this scenario, in addition to sending the message to the bot with the REDIRECT.COMMAND information, a message will be sent to WhatsApp with that text.

graph LR
    A(aura-groot) -->|Redirect message| B(Bridge)
    B -->|Whatsapp user message| W[Whatsapp]
    B -->|Redirect message| A

aura-groot message does not contains text (empty) in the text field:
In this scenario, only one message will be sent to the bot with the REDIRECT.COMMAND information. No message will be sent to the WhatsApp user.

graph LR
    A(aura-groot) -->|Redirect message with empty text| B(Bridge)
    B -->|Redirect message| A

The same process is followed in the directline-rcs-processor plugin.

Docs:

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

Users authentication

Description of users’ authentication process in Aura Bot. Discover the different types of users and how they can authenticate in Aura

Introduction

aura-bot supports different types of users, each of them with access to specific services and use cases:

Authenticated users
Anonymous users

In the authentication process, aura-bot carries out the following summarized steps:

Obtains information from the users
Validates it
If the validation is successful, and depending on the type of user, aura-bot allows accessing to different services
Stores the user’s data

The detailed process is described in users’ authentication flow.

The authentication of a user implies the acceptance of Terms and Conditions, which are handled by aura-bot.

In certain scenarios (use cases) where the user is unauthenticated, it is required to redirect specific intents that need authentication. Find here the complete information regarding login redirections.

Docs:

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

Aura users types

Description of the different users types existing in Aura

Introduction

Aura supports different types of users: authenticated and anonymous, each of them with access to specific services and use cases. The following sections include detailed information about each type.

Authenticated users

Aura securely knows the identity of the users, as they must have successfully completed the authentication flow.

They can be classified into different groups regarding their type of subscription. This classification depends on the different countries, but in general terms, there are three main types of authenticated users: postpaid, prepaid, hybrid / control.

Authenticated users can access any use case in Aura, providing that the use case supports authenticated users or the specific subscription type of the user, defined through context filters.

In case the authorization process of an Aura user fails:

If the channel does not allow anonymous users, then the request is marked as failed and a status with the unauthenticated error is returned to the channel. This indicates that the channel should relaunch the authentication of the user to get a valid auraId.

Anonymous users

Anonymous users are unauthenticated users but with authorized access to certain Aura’s use cases: to those which support the anonymous user’s type. In every case, Aura’s experience is different for each type of users.

Within anonymous users, there is a specific type named identifiable users in which the channel auraId univocally identifies a user in the channel.

It also depends on the channel, as different Aura channels can support both types of users (anonymous-identifiable and authenticated) or only authenticated ones.

Due to some restrictions in Kernel, from Kiss release onwards, anonymous users also have userId and auraGlobalId. These fields, in contrast to authenticated users, are not obtained from Kernel but auto-generated by aura-bot and aura-authentication-api in some cases, to be stored in KPIs. The values are generated to maintain the same value between channels to allow the user identification if possible.

Docs:

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

ATRIA capabilities

Discover the AI-driven functionalities that the ATRIA platform put at your disposal for the generation of experiences. They are primarily focused on improving the understanding of human language and, consequently, providing highly reliable responses to the user in a secure and controlled manner.

Additionally, access documentation regarding available key ATRIA features.

ATRIA AI-driven functionalities

ATRIA is conceived as an AI technologies aggregator and currently includes key capabilities, based both on proprietary and third-party technologies.

The current capabilities and AI technologies in this first ATRIA are shown in the following figure and introduced below.

Figure 3. ATRIA capabilities

NLP as a Service

NLP as a Service enables the connection with Aura cognitive services to leverage different NLP technologies via API for understanding users’ requests and providing accurate responses.

Find detailed information regarding NLP as a Service or access directly to its associated capabilities:

NLP Apps
- Semantic Search

LLM/LMM Experiences Builder

The LLM/LMM Experiences Builder allows ATRIA to integrate third-party AI technologies via API to create interactive, personalized, and dynamic user interactions while establishing control mechanisms to ensure security and data privacy.

Find detailed information regarding the LLM/LMM Experiences Builder or access directly to its associated capabilities:

ATRIA features

Additionally, ATRIA contains key features focused on improving the generation of experiences, that allow advanced customization options and adaptability to user preferences.

Multibrand feature: Users can access ATRIA through the different Telefónica brands available in their country.
Multi-language feature: ATRIA RAG includes a multi-language feature, to deliver service to a global audience in multiple languages, as it automatically detects the input language and provides the response accordingly.

Docs:

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

Aura SQL RAG pipeline

Description of the SQL RAG pipeline

Introduction

ATRIA currently integrates one RAG pipeline for the conversion of a request from natural language to an SQL query.

Steps in the SQL RAG chain

The use of the SQL RAG chain encompasses different stages, which are explained and schematically represented below.

Figure 15. SQL RAG chain

1. Injection checking

Detects the presence of anomalies in the user’s query that may affect the resolution process.
Currently, a set of checks, based on heuristics, are made:
- Detects overly long questions.
- Detects suspicious substrings in the query.

2. Question translation (currently deactivated)

Optional step for the translation of the user’s query into English.
Currently, it is not activated.

3. Candidate table retrieval

The system searches the candidate tables for relevant documents. This is currently done using a hybrid search, through the combination of lexical and semantic search (embeddings).
The table retrieval is currently based on the similarity between the user’s query and the tables high level description.

4. SQL query generation

The top-2 results (tables) are selected.
In them, the user’s request is converted from natural language to an SQL query.

Docs:

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

auraCommand model

Description of the auraCommand model suitable for sending intents directly to Aura with no recognition stage

Introduction

An auraCommand is an structure to send intents directly to Aura. It includes specific messages consisting on pre-defined options that the user can select from Aura’s interface as part of the response to her request. These messages come from channels using Direct Line format. Currently, they correspond to notifications and suggestions.

The aura-bot recognizer in charge of auraCommand is aura-command-recognizer-middleware. This recognizer detects if the message matches auraCommand format and then processes the message and extract the intent and entities from it.

An auraCommand should be sent within the channelData of the request to aura-bot in an optional property called auraCommand.

AuraCommand property in channelData

It is the channelData property called AuraCommand, which value should fit an AuraCommand Model.

Property	Type	Description
auraCommand	AuraCommand	This property contains an `auraCommand` object.

AuraCommand Model

Property	Type	Description
type	string	`AuraCommand` type: suggestion: used to send a common intent. The prefix of the intent must be `intent.`. Its the type by default. operation: It represents an intent that needs a context in Aura. The prefix of the intent must be `operation`. notification: It represents an intent generated by notification. The prefix must be `intent`. text: The value of the `auraCommand` contains directly a `string` with the text to be recognized by NLP. event: The value of the AuraCommand contains and event that aura-bot recognizes to carry out an action.
value	Intent model or string	Object intent or text.
utm	Utm model	Source that contains the AuraCommand.
actions	Action model	Array of actions.

Intent model

Property	Type	Description
intent	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add the it.
entities	Entity model	Array with the entities. This array can be empty.

Entity model

Property	Type	Description
type	string	Name of the intent. If this name does not contain the prefix `intent.`, Aura will add it.
entity	string	Name of the entity. If this name does not contain the prefix `ent.` Aura will add it.
canon	string
score	float	Array with the entities. This array can be empty.

Utm model

Property	Type	Description
source	string	It identifies which site sent the traffic. In Aura, use the channel name.
medium	string	It identifies what type of link was used, such as cost per click or email. In Aura, use banner, button, etc.
campaign	string	It identifies a specific product, promotion or strategic campaign.
term	string	It identifies search terms.
content	string	It identifies what was specifically clicked to bring the user to the site, such as a banner ad or a text link.

Docs:

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

channelData mapping

channelData mapping in Aura response

Introduction

Currently, Aura supports dialogs able to provide responses in v1, v2 and v3 channelData versions. These responses are mapped to be handled by the bot output middlewares as v3, but after that, dialogs are mapped again to the original response version to be returned to the client.

However, incoming middlewares are able to work with different request channelData versions v1, v2 and v3, indistinctly.

Request

The request is currently not transformed and is accessed using channelData utils from the aura-bot-common library.

These utils make transparent the access to all channelData properties needed in v1 or v3.

Response

The response returned by the dialog is normalized in the outgoingchannelDataNormalizer middleware, the first outgoing middleware executed after the dialog.

This normalization is done if the channelData version returned is lower than the current version.

The middleware calls ChannelDataResponseMapper.getResponseChannelData with:

The normalized version (currently, v3) as first parameter.
The channelData in the old version as second parameter.

This mapper function will return a normalized version of the channelData.

After all the middlewares are executed, in the adapter, the response should be transformed to the version returned by dialog again.

To do this, ChannelDataResponseMapper.getResponseChannelData is called again with:

The version originally returned by the dialog as first parameter.
The channelData as second parameter.
The original channelData returned by the dialog as third parameter. This third parameter is needed because in the conversion from old versions to the normalized version certain fields may disappear, so we need to merge the normalized channelData (maybe modified by the outgoing middlewares) with the original returned by the dialog.

Channels using a BotService adapter

Channels such as Facebook that use a BotService Adapter will always use a channelData without version, which internally is translated to v1.

This means that the request will have to be mapped for good. The major implication is that channelData version v3 must take into account the fields needed by these adapters, so the communication and the user’s experience are kept the same.

Currently, aura-bot is only validated to be accessed through the Facebook Messenger adapter. In this case, the protocol allows the exchange of HeroCards, but the way they are sent to the channel is a bit different than in Direct Line channels: they are sent as attachments of the channelData instead of attachments of the activity.

So, in order to allow Aura use cases to send buttons or a complete HeroCard to a user, the attachments field of the channelData must be kept during the version mapping.

Docs:

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

Aura Bot conversational flow

Description of users’ authentication process in Aura Bot. Discover the different types of users and how they can authenticate in Aura.

Aura conversational process

Once the user’s authentication is validated, aura-bot starts the message processing.

Firstly, all incoming message middlewares are executed, in the order established in the bot set-up.
Then, recognizers come into play in order to recognize the user’s intention.
Depending on the type of input message, the process is different. For instance, aura-bot is able to recognize the user’s intent itself if the message is an auraCommand or requires summoning Aura Cognitive Services for this purpose.
Recognizers are executed sequentially and, after one of them recognizes an intention, the rest are not executed.
Once the intent and entities are identified, the next step is to route the message to the dialog in charge of that intent for the current channel. This step is done by the main dialog. This special and core dialog is responsible for:
- Getting the dialog that handles the recognized intent for the current channel. If it does not exist, an error is returned to the channel.
- Validating if the user’s context matches with the context filters configured in the selected dialog. If that is the case, then the context filter dialog is executed.
- Validating the authorization settings of the dialog to be executed with the AuraUser authentication model. In the case of Kernel authentication, it checks that the scopes and purposes of the user contain the mandatory ones to execute the dialog.
  This validation improves aura-bot performance, avoiding external requests to Kernel that will return a permissions error. If the user is anonymous, this step is not executed.
The specific dialog selected is started during one of the steps of the main dialog, and thus the execution is now managed directly by that specific dialog.
The dialog must get the information needed to provide a proper response to the user through Aura NLP, Complex Logic API or Kernel Telco APIs in order to generate the expected answer.
The response is now ready to be provided to the user and will start its way through the outgoing middlewares.
After that, the execution flow continues to the next step of the MainDialog, that is checking whether or not the dialog must include suggestions. To do so, it will check that the proper dialog settings are stored in the context. If suggestions are needed, the suggestions API will be called, the resulting activity will be prepared following the UX Guidelines.
In the end, a complete response consisting of several ordered activities will be provided to the channel, that will read them from Direct Line and the result will be rendered to the user.

Conversational process flowchart

The following flowchart schematically shows the components involved in the process.

Check here the complete Aura Bot conversational process flowchart.

Docs:

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

Create and configure a preset

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of a preset

This guidelines correspond to a specific stage in the processes for building experiences using Generative AI or RAG, which are fully explained in:

Introduction

A preset is a configurable entity that defines the instructions to work with the AI model for the resolution of a use case.

These instructions include, apart from other parameters, the prompt with text to guide the AI model with the generation of the response. For example:

“Maintain the formal tone of the original text”
“If the previous conversation is relevant for the current query, incorporate it into the query and produce a rewritten query”

When developing an experience in ATRIA, use cases constructors must configure a preset for the specific ATRIA application to be used.

ATRIA use cases constructors can use the currently available default presets or they can modify them or create new ones via API.

In both scenarios, a further step is required to include the preset in the application.

Guidelines to configure a preset

1. Create a new preset

Build the preset for your use case (json file), using the available preset fields.
Do you get lost with all the preset configuration parameters? In best practices for ATRIA configuration, you can find the most commonly used parameters by experiences constructors grouped by their purpose (“I want to increase security”, “I want to activate the multi-language feature”, etc.)

When the preset json file is generated, execute this command to include it:

  curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data-raw '<NEW PRESET JSON>'

1.1. Modify/update a preset

If once created, certain modifications are required, follow these instructions:

Make the required changes in the preset json file using the available preset fields.

When the preset is modified, execute this command to include it:

  curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<PRESET JSON WITH MODIFICATIONS>'

1.2. Delete a preset

Execute the following command:

  curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/presets/<presetId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the preset in the application

An application is defined as an entity that allows the connection of a channel, service or skill with with ATRIA.

If the application for your use case does not exist, firstly it is required to create it following the guidelines for the configuration of an application.

Once the application is created, assign the created preset. Two scenarios arise here:

2.1. If an existing preset is modified

Get the list of presets assigned to the application to be used from aura-configuration-api:

  curl --location 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/applications/<applicationID>' \
  --header 'Authorization: APIKEY '

Check if your preset is already included in the list and, consequently, associated to your application.
If not, declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

2.2. If a new preset is created

Update aura-configuration-api to indicate to the application the complete list of presets to be used.

It is necessary to include the entire list of presets associated to the application (the existing presets and the created/modified ones)

    curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/:applicationId' \
    --header 'Accept: application/json' \
    --header 'Authorization: APIKEY XXX' \
    --data '{
        "id": "<applicationId>",
        "models": {
            "level": <levelType>, 
            "presets": [
                <complete-new-list-of-presets>
            ]
        }
    }'

The level field, that indicates the different levels of access to the application, can only be changed By the Global Team. This command is a specific scenario in the process of modifying API configuration, described in the document Hot swapping of Aura applications configuration.

Declare the created preset in the application following the guidelines for the configuration of an application: Use Generative AI/RAG, within the field presets.

Preset fields

The fields for the characterization of a preset are summarized below, which are defined in the API swagger Aura Configuration API Preset.

If there is any discrepancy between the parameters definitions included in this document and those in the API swagger, definitions established in the API shall prevail.

id: Mandatory. Preset identifier. The type is string.
name: Mandatory. Preset name. If this value does not exist, id is used. The type is string.
description: Optional. Preset description. If this value does not exist, id is used. The type is string.
group: Mandatory. This parameter is used to group requests regarding the AI technologies used to generate KPIs. The type is string. Feasible values: simple_ai (Generative AI preset) and enriched_ai (RAG preset).
session: Optional. Parameters for session configuration.
- window: Optional. The size of the session window, in queries. The type is number.
- timeout: Optional. The time in seconds after which the session will be closed if no queries are received. If it is 0, the session history will be used, but the current interaction will not be saved. The type is number.
generative: Mandatory if Generative AI is used. It indicates the use of Generative AI in the use case. If this field exists, the rag field must not exist.
- model: Mandatory. Model configuration.
  - id: Mandatory. Unique identifier of the model
  - parameters. Optional. Dictionary with all possible parameters for the model. For generative, check them here.
- injectionMaxLength. Optional. Maximum length of the input user. The type is number.
- prompts: Optional. Parameters to define the prompts with instructions used as input by the AI model to automatically generate responses.
  . The object may include properties such as text, additional parameters, and specific configurations to control the behavior of the generative model.
  . If no prompt is defined, the resolution of the use case is entirely delegated to the LLM model.
  - template: Optional. Template that includes the user’s input. It must include {MSG} for the user’s utterance. This will override (or add, if not defined) the template for the user message, as defined in the preset (Note: templates allow framing the user message to mitigate prompt injection attacks). The type is string.
  - preamble: Optional. List of phrases to be included in the model prompt.
  - examples: Optional. Examples to enrich the prompt. The type is string.
  - promptMaxLength: Optional. Maximum length of the completed prompt. Used to avoid calling LLMS with wrong prompts.
  - promptRegexClean: Optional. Regex pattern to clean the query before sending it to the model. This is useful to remove unwanted characters or patterns from the query. The type is number.
rag: Mandatory if RAG technology is used. It indicates the RAG configuration. If this field exists, the generative field must not exist.
- ragType: Optional. RAG type. Values: questions-answers (by default) or sql
- model: Mandatory. Parameters for the configuration of the RAG model.
  - id: Mandatory. Unique identifier of the model to be used. The type is string.
  - parameters: Optional. Dictionary with all the possible parameters for the model.
- references: Optional. Configuration for managing references in the system. It control de number of references the system relies on to generate a response.
  - maximum: Optional. Maximum number of returned references. The type is number.
  - baseUrl: Optional. Base URL of references that will be shown to the user as part of the response. For the types of data unstructured, csvand text (defined in the field loaderType), it is required to add here the path to the public URL to be shown in the response as a clickable reference.
- stages: Mandatory. Stages of the RAG model.
  - promptSystemLanguage: Optional. Parameter to select a specific language from the ones defined in the prompt. Type: string in ISO 639-3 format. For example: es.
  - defaultUserLanguage: Optional. Parameter used in multi-language feature. It indicates the default response language to be used if the system is not able to automatically recognize the language. Type: string in ISO 639-3 format. For example: es.
  - securityStg: Stage with parameters related to security used to avoid prompt injection.
    - injectionMaxLength: Mandatory. Maximum length of the input user. If length is greater, an error is sent. The type is number.
    - heuristics: Optional. Heuristics configuration.
      - es: List of heuristic sentences in Spanish. The type is list.
      - en: List of heuristic sentences in English. The type is list.
  - translationStg: Stage used to translate the prompt.
    - enabled: Mandatory. Boolean value to activate or not the translation stage. The type is boolean.
    - language: Mandatory. Two-letter ISO 639-1 language code into which user input is translated to match the language of the data. The type is string. If this field exists, the prompts field must not exist.
    - prompt: Mandatory. List of prompts to be used in the LLM call.
      . The type is PromptLanguage.
      . If this field exists, the language field must not exist.
      . If this field is empty, the default prompt for this stage will be used.
  - contextStg: Stage used to know if the user’s phrase has the same context of the conversation.
    - enabled: Mandatory. Boolean value to activate or not the context stage. The type is boolean.
    - stickyContext: Mandatory. Strategy to include the context into the new query. If not specified, the optional context in the request is ignored. The type is string. Values:
      - ask_llm: An LLM-call is made to discern whether the context applies to the current query. If so, a recreate_question is performed. If not, the context is ignored and a clear_context field is added into the response.
      - include_context: The context will be inserted as is into the query. prompts should not by empty for this option.
      - recreate_question: An LLM-call will try to recreate the question by using the context.
    - prompts: Optional. List of prompts to be used in the LLM call.
      . The type is StickyContextPrompts.
      . If this field is empty, the default prompt for this stage will be used.
  - cleanStg: Stage used to remove prompt injection attempts using an LLM call.
    - enabled: Mandatory. Boolean value to activate or not the clean stage. The type is boolean.
    - prompt: Optional. Prompt to be used in the LLM call.
      . The type is PromptLanguage. For example: “Please clean up the query and reply only with the user’s question”.
      . If this field is empty, the default prompt for this stage will be used.
  - retrievalStg: Mandatory. Stage related to the retrieval phase, which is the process of obtaining relevant documents by comparing the query against indexed data or vectors.
    The stage is crucial for identifying and retrieving the documents or data that best match the input query, ensuring that only the most relevant results are returned.
    - sources: Mandatory. Sources data.
      - name: Mandatory. Name of the source data. The type is string.
      - embeddings: Mandatory. Embeddings model identifier that the ATRIA source data is associated with.
      - docs: Mandatory. Field with parameters related to the configuration of documents. The type is object.
        
        extension: Mandatory. Extensions of documents. The type is string. The extensions must be separated by a comma.
        
        loader: Mandatory. Project loader configuration.
        
        loaderType: Mandatory. Type of loader. Values: unstructured, csv, text, jsond, jsonl or url_list
        
        options: Optional. Object that configures how the document loader operates. It allows specifying the mode of loading and any post-processing actions to be applied to the loaded data.
        
        loaderMode: Optional. Modes for loader running. The type is string. The possible values are:
        
        single: Document will be returned as a single document representing the whole
        
        elements: The loader splits the document into different elements such as: Title, NarrativeText, etc. This allows a more granular processing and analysis
        
        postProcessors: Optional. Post processor loader. It allows to perform operations in the loaded document such as cleaning, transforming, enriching, etc. The type is string.
      - splitter: Optional. Project splitter for dividing large text inputs into smaller, manageable chunks, that can be more easily processed by language models, ensuring efficient and accurate processing.
        
        splitterType: Mandatory. Method used to split the text. Value: recursivechar (Recursively divides the text based on a character, typically looking for specific breakpoints such as punctuation or whitespace)
        
        options: Optional. Project splitter options.
        
        chunkSize: Optional. Maximum size of chunks to be returned. The type is number.
        
        chunkOverlap: Optional. Overlap in characters between chunks. The type is number.
      - retrievers: Mandatory. List of retrievers used to query and retrieve relevant data or documents from a collection based on a given query.
        
        retrieverType: Mandatory. Type of the retriever. Possible values: qdrant, tfidf, or elasticsearch.
        
        config: Optional. Configuration parameters for retrievers. The type is dictionary.
        
        numDocs: Optional. Number of documents to retrieve. The type is number.
        
        loadChunkSize: Optional. Chuck size used to load the documents in qdrant. The type is number. By default, 1000.
  - postFilteringStg: Stage in charge of processing candidates before they enter the RAG chain.
    . It prompts the project LLM for each candidate, using the query and the candidate text. The LLM determines whether the candidate text is related to the query, and if not, the candidate will be filtered out.
    . If this option is not enabled, no post-processing or filtering will take place.
    - enabled: Mandatory. Boolean value to activate or not the post-filtering stage. The type is boolean.
    - candidatesPostFiltering: Mandatory. Post-retrieval filtering applied to the candidates. It must be llm_filter (for each candidate, a very short request is made to the LLM to identify whether the candidate is relevant to answer the query. If ’no’ is decided, the candidate is filtered out)
    - prompt: Optional. Prompt to be used in the LLM call.
      . The type is PromptLanguage.
      . If this field is empty, the default prompt for this stage will be used.
  - generativeStg: Stage for handling the question and answer process.
    . It defines the strategy to solve the question, the prompts used in different stages of the process and the templates for generating responses
    - ragStrategy: Optional. Strategy to combine documents to generate a response. By default, stuff:
      - stuff: Mandatory. If stuff prompt is used, ragStrategy must be set to stuff.
      - refine: Mandatory. If informationExtraction or responseConsolidation prompts are used, ragStrategy must be set to refine.
    - prompts Optional. List of prompts to be used in the LLM call.
      . The type is GenerationPrompts.
      . If this field is empty, the default prompt for this stage will be used.
      - #.auto.language.user_query: Parameter that activates the automatic detection of language in the user’s query (multi-language feature).
        . This parameter is included in the args field of the prompt.
        . If you use the prompt by default, the multi-language feature is already activated.
        . Example:
        ... default: text: | Respond in language {user_query_language}. Question: {question} args: user_query_language: "#.auto.language.user_query" ...
- outputRefine: Optional. It is used to set up how to provide responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.
  - candidates: Optional. It indicates whether to return the candidates in raw (useful for evaluation purposes) or not. The type is boolean, by default, false.
  - filterOutputMetadata: Optional. It is used to set up how metadata is used when providing responses. The retrieving operation produces a list of candidates, each of which may provide a dictionary of metadata.
    - map: Optional. Maps attribute names in the original data to standard or more user-friendly names for later use.
      - fileType: Optional. String representing the type of file, typically used to specify the format or content type of the file being referenced. By default, content-type
      - pageNumber: Optional. String representing a page number. It could be used to identify particular pages within a document or resource. By default, page-number
    - groupBy: Optional. groupBy and aggregate are expressed in post-map field names. By default, url
    - aggregate: Optional. It determines how the values of duplicated fields are consolidated during grouping, specifying the handling of aggregated field information. By default, page-number
    - outputFilter: Optional. List of fields to be displayed in the metadata. Type is list.
    - root: Optional. Defines the primary fields that will structure the final output of the metadata processing. Fields listed under root will remain at the top level of the response entries, while all other metadata fields will be nested under a metadata. Type is list.

Example of preset for Generative AI capability

      {
        "id": "e27ca464-488a-435d-a508-da8a262d905f",
        "name": "openai",
        "description": "openai model",
        "brand": "",
        "contact": "",
        "group": "simple_ai",
        "session": {
          "window": 0
        },
        "generative": {
          "model": {
            "id": "openai",
            "parameters": {
              "top_p": 0.9
            }
          },
          "prompts": {
              "preamble": {
                "text": "Habla como si fueras {name}",
                "args": {
                  "name": "Napoleon"
                }
              },
              "examples":[
                "Naciste en galicia",
                "Di que tu padre era gallego"
              ],
              "promptRegexClean": "[#\\n\"]+"
          }
        }
      }

Example of preset for RAG capability

    {
        "id": "1cafcb5c-7951-4645-86d4-055d3b46fe79",
        "name": "atria-rag-gpt-35-turbo",
        "group": "enriched_ai",
        "description": "Atria rag GPT 3.5",
        "session": {
            "window": 3
        },
        "rag": {
            "ragType": "questions-answers",
            "model": {
                "id": "gpt-35-turbo",
                "parameters": {
                    "max_tokens": 4000,
                    "temperature": 1,
                    "top_p": 1
                }
            },
            "references": {
                "maximum": 3,
                "baseUrl": "project-gpt-35-turbo/pdfs"
            },
            "stages": {
                "language": "en",
                "translationStg": {
                    "enabled": true,
                    "language": "en"
                },
                "contextStg": {
                    "enabled": true,
                    "stickyContext": "ask_llm"
                },
                "cleanStg": {
                    "enabled": true
                },
                "retrievalStg": {
                    "sources": {
                        "name": "project-gpt-35-turbo",
                        "embeddings": "text-embedding-ada-002",
                        "docs": [
                            {
                                "extension": "pdf",
                                "loader": {
                                    "loaderType": "unstructured",
                                    "options": {
                                        "loaderMode": "single"
                                    }
                                }
                            },
                            {
                                "extension": "txt",
                                "loader": {
                                    "loaderType": "url_list"
                                }
                            }
                        ],
                        "splitter": {
                            "splitterType": "recursivechar",
                            "options": {
                                "chunkSize": 60,
                                "chunkOverlap": 20
                            }
                        },
                        "retrievers": [
                            {
                                "retrieverType": "qdrant",
                                "config": {
                                    "loadChunkSize": 10000
                                }
                            },
                            {
                                "retrieverType": "tfidf"
                            }
                        ]
                    }
                },
                "postFilteringStg": {
                    "enabled": true
                },
                "generativeStg": {
                    "ragStrategy": "stuff"
                }
            },
            "outputRefine": {
                "candidates": false
            }
        }
    }

Docs:

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

Aura Virtual Assistant functional description

Discover in this document the fundamentals of Aura Virtual Assistant architecture from a functional point of view and a high-level overview of its main components

Foundation: Microsoft skills architecture

Aura architecture is conceived as a multi-bot system based on Microsoft Bot Framework skills architecture.

In this framework, the architecture is composed of a root bot, that can call one or more skill bots, which are specific to a knowledge area or topic.

The user interacts directly with the root bot, and it delegates the conversational logic to a skill to provide the user with the intended service or response.

Figure 3. Microsoft skills

Access Microsoft Skills documentation.

Aura Assistant functional overview

Starting from the functional overview flowchart (Figure 2), the current section zooms in and shows a deeper detail of the functional operation of Aura Virtual Assistant.

Figure 4. Aura Virtual Assistant functional operation

The user accesses a specific Telefónica brand and sends a request to Aura through a channel.
The channel connects to Aura Root.
Two scenarios arise here:
- If the channel “speaks” a language Aura understands, that is, it supports Direct Line protocol: direct connection.
- If the channel “does not speak” a language Aura understands: the incoming request must be converted into a standard Aura message through an adapter.
Aura Root makes the decision about what is the best skill (bot) to answer the user’s request in a routing component.
Optionally, it is possible to add additional information to the request through an enrichment module, with data coming from Aura context, algorithms, analytical models, insights, etc.
Aura Root sends the request to a specific skill, depending on the selected domain.
The specific skill (domain-bot) routed by Aura Root receives the request and handles it. At this stage, two scenarios can arise:
- 6.a. The skill receives the request in Direct Line format.
- 6.b. If the routed bot is not part of the Microsoft ecosystem (third-party bots), the request must be transformed through a third-party adapter to be understood by the bot (and the other way around with answers).
  Strictly speaking these adapters are not part of Aura Root and could be integrated through different strategies by the OBs. For instance, the conversion could be performed in a specific skill connected to the third-party bot.
The skill calls NLP as a Service capability in ATRIA for the recognition of the user’s intention and entities.
- Currently, aura-bot as a skill works as in the previous architecture, calling Aura NLP for recognition purposes.
The response to the user’s request is built and sent back to Aura Root.
Aura Root provides the answer back to the channel. If required, the channel adapter converts again the Aura message to the format compatible with the channel.

Take into account that the current document only shows a functional representation in order to make the new architecture more understandable for readers. The underlying technical components and processes are explained in the documents:

Docs:

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

Introduction to Aura Root

The current document includes an overview of Aura Root and general information regarding this Aura Virtual Assistant functional component.

Moreover, it includes links to low-level technical documentation for highly-skilled technicians.

Introduction

Aura Root constitutes the core functional block of Aura Virtual Assistant and is responsible for connecting channels with skills (bots).

It carries out the following key tasks:

Receives requests from the channels.
If required, it adapts the incoming request from a channel that Aura is able to understand through an adapter.
Makes the decision about what is the best skill (bot) to answer the user’s request and routes this petition to the corresponding domain bot in a routing component. Currently, routing is only done by channels or channels groups.
Is able to enrich both the request and the answer with additional information coming from Aura context and different models in a enrichment module. (In the current version, no enrichment is available).
Can have multiple skills connected, and one of them could be the current aura-bot functioning as a skill.
Generates entities files with relevant information regarding each interaction, that will be afterwards uploaded to Kernel.

Aura Root functional components

From a functional point of view, Aura Root includes the following features:

Routing

The user’s request is routed to a specific skill (domain bot) able to best respond to this query.

Currently, routing is done only by channels or group of channels (no configuration options are available).

Channel adapter

If the channel does not support a language that Aura understands (Microsoft Direct Line protocol), an adapter is required to establish the communication.

Enrichment

Enrichment adds additional data to enrich both request and response through context information, algorithms, analytical models, insights, etc.

This feature will be available in further releases.

Aura Root technical components

As explained before, Aura Root is a functional representation in order to make the new architecture more understandable for readers.

The technical component that manages the functionalities above defined is aura-groot.

Docs:

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

LLM/LMM Experiences Builder

Discover ATRIA LLM/LMM Experiences Builder, that includes LLM chains for the generation of different types of content through Generative AI or RAG technologies

Introduction

ATRIA can integrate third-party AI technologies via API through the LLM/LMM Experiences Builder to create interactive, personalized, and dynamic user interactions, while establishing control mechanisms to ensure security and data privacy.

To do that, the LLM/LMM Experiences Builder allows the creation of LLM chains, which are defined as structured workflows that involve several interconnected steps, each of them using diverse LLM technologies to process, generate, or transform text data. Each step feeds into each other, with the ultimate goal of understanding a request expressed in natural language and providing an accurate response to it.

In the current release, two predefined LLM chains are included in ATRIA, offering two key capabilities:

Simple flows that call to an LLM: Generative AI capability for understanding and generating human-like texts through LLMs.
Complex flows: General RAG capability through RAG (retrieval-augmented-generation) processing techniques that combine different AI models.

Currently, only these two predefined chains can be used. In further ATRIA versions, constructors will have the flexibility of creating customized LLM chains.

ATRIA also includes a testing UI interface to test the behavior of the LLM/LMM Experiences Builder when using both Generative and RAG capabilities, before publishing into production. In further versions, the solution will include an interface to configure different parameters easily and a mechanism to load data.

Functional components

The following diagram schematically shows the functional components into play in the LLM/LMM Experiences Builder.

Figure 9. LLM/LMM Experiences Builder

Chain builder and orchestration layer

Currently, this layer allows:

Using a predefined LLM chain for specific use cases, that corresponds to a RAG (Retrieval Augmented Generation) pipeline integrated using LangChain.
Manual configuration of parameters.
Integration of new components (vector databases, document loaders, text splitters, etc.) by Aura Global Team.
Simple fallback mechanism: flag set in configuration.
Conversation history, taking into account past interactions for the enrichment of responses.

Control layer

The components of this layer have the following roles:

Providing mechanisms for ensuring security and data protection.
- Heuristics blacklists.
- Prompt injection.
- Templates.
Including the control of tokens consumption.

Model layer

The model layer can include both internally and externally hosted models.

Models currently integrated into ATRIA

The AI models currently integrated in ATRIA are:

Azure OpenAI embeddings model: text-embedding-ada-002
Hugging face models: paraphrase-multilingual-MiniLM-L12-v2, Multi-qa-distilbert-cos-v1
Azure OpenAI GPT models: gpt-4-turbo, gpt-4o, gpt-4o-mini, o3-mini

In further releases, the model manager will integrate other state-of-the-art models from different providers, avoiding lock-in and making easy for constructors to choose, try and select the one that fits better with their needs.

Analytics layer

The analytics layer currently includes two features:

Feedback functionality, for the estimation of the accuracy in the response, in which the user can provide feedback by clicking on a thumbs-up icon if the quality and appropriateness of the answer is correct or selecting the thumbs-down icon if the response misses the point, contains hallucinations, or is unclear.
Simple RAG monitoring to check how the RAG chain performs.

Docs:

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

NLP Apps capability

Overview of the NLP Apps capability, encompassing the underlying technology and its application in ATRIA

Introduction to NLP Apps technology

Within Natural language processing (NLP) technologies, NLP Apps refers to NLP pipelines (chains) that combine different technologies for language processing with several tools for combining them.

Currently, these technologies, both proprietary and third-party ones, are included in the Aura NLP component and can be categorized in the following groups:

Deterministic recognizers, such as Exact Match or Grammars.
Probabilistic recognizers, such as OpenAI embeddings: Semantic Search, that uses Azure OpenAI capabilities based on embeddings and Microsoft CLU.
Classifiers, from the traditional Domain Classifier to the embeddings-based Domain Classifier.
Entities recognition stages, Standard NER or Gazetteer NER, based on deterministic entity detection.
Other tools for executing different normalization tasks, connectors, adapters, etc.

The technical description of all the available NLP technologies in included in the document Components for NLP pipelines

Application of NLP Apps in ATRIA

ATRIA enables the generation of experiences (use cases) through the use of Aura cognitive capabilities as stand-alone NLP Apps for sending a request expressed in natural language and receiving back an accurate response without the need for a conversational bot.

Figure 6. NLP Apps in ATRIA

Interaction with NLP Apps in ATRIA

This service is accessible via API, enabling its consumption both from Aura Platform or any external application.

Functional overview

A simple overview of the process is provided below:

A user sends a request to ATRIA, indicating which specific NLP App she wants to use for the recognition of the request. These Apps are available in Aura NLP, a module of Aura Cognitive Services in charge of processing and understanding human natural language.
The NLP technologies in the pre-selected specific App resolves the use case and generates a response.
The response is sent back to the user.

Docs:

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

RAG capability

Overview of the RAG capability, the benefits derived from its use and the current predefined RAG chain in ATRIA

Introduction to RAG technology

RAG (Retrieval Augmented Generation) is a technique for augmenting LLM knowledge with additional data. It provides a way to optimize the output of an LLM with targeted and updated information without retraining it; thus, providing more appropriate answers based on specific and latest data.

The process includes three differentiated parts:

Retrieval: it searches and extracts relevant information from a KB database using information retrieval techniques, such vector representations (embeddings) to find text blocks that contain the appropriate information to resolve the input request.
Augmented: the RAG model augments the user input (or prompts) by adding the relevant retrieved data. This step uses prompt engineering techniques to communicate effectively with the LLM.
Generation: the enriched prompt is sent to an LLM, that generates the most accurate response for the user.

Figure 12. RAG technology

Application of RAG in ATRIA

As explained before, the LLM/LMM Experiences Builder enables the generation of LLM chains that integrate different AI technologies.

Within this capability, complex flows based on the RAG technology can be integrated.

Example case

Imagine that our platform, ATRIA, operates like a restaurant with different chefs, each specialized in a unique approach to meeting customers' needs.

A RAG model can be compared to Chef Sara, a chef who combines her traditional culinary experience with the real-time consultation of resources to enhance her recipes with the latest culinary trends worldwide, as she likes to be continuously up-to-date.

When a customer requests a nutritious and hearty meal, Sara goes beyond her own knowledge, based on already learnt techniques and recipes. Instead, she consults innovative cuisine resources: Indian cookbooks and her recent notes on advanced molecular cooking techniques. These external sources allow her to innovate and propose a unique dish: a curry foam, light and airy, with an intense spice flavor and a touch of coconut milk.

In technical terms, the RAG approach combines:
a. Generation based on prior knowledge (the internal model): equivalent to Sara's knowledge of cooking.
b. Real-time retrieval of external information: consulting cookbooks and notes represents how a RAG system looks up information in databases or dynamic sources during the response process.

This integration allows the model to provide more contextualized responses, tailored to specific needs, especially when the stored knowledge is limited or insufficient.

Currently, ATRIA incorporates the following RAG chains:

General RAG: Complex AI-driven flow for resolving generic questions experiences based on FAQs
SQL RAG: RAG-based pipeline for resolving SQL queries

In upcoming versions, constructors will be able to design their own LLMs chains based on RAG.

Benefits from the use of RAG technologies

Updated and targeted information: RAG allows developers to provide the latest data to the generative models, targeted to the specific use case.
Cost-effective implementation: Data in the knowledge repository can be continually updated without incurring significant costs.
Enhanced user trust: The data sources contributing to the RAG’s vector database are identifiable. This transparency allows for the correction or removal of any inaccuracies present in RAG and clearly improves users’ confidence.
Improved developers control: With RAG, developers can test and improve their applications more efficiently, control and change the LLM’s information sources to adapt to changing requirements, restrict sensitive information retrieval to different authorization levels and ensure the LLM generates appropriate responses.

Docs:

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

Aura bridge response messages synchronization

Description of the process for the synchronization of the user’s messages executed by Aura Bridge using Redis as the database for storing Aura bridge cache

Introduction

aura-bridge manages the synchronization of the user’s messages.

Requirements

Messages in aura-bridge are divided into two parts:

The entry of the message in the bridge (Request Message)
The message replies (Response Message)

Message order

The messages must be sorted in order:

If there is a previous message that has not yet received a reply, it must wait.
If there is a previous response to the current one, wait for it.

Error returning messages to the client

If a response returns a non-recoverable error, all messages belonging to the same group, i.e., to the same request, must be cancelled.
If a response returns a recoverable error, the message must be included in messages to be resent, together with those of the same group.

Flow of messages in the queue

Incoming message (request)

This is the input message, containing a unique identifier requestId and the conversation identifier.

If the message does not have a direct response, but is made through an external service, the async callback must carry the identifier requestId, so that the bridge does not block the queue. Note that the requirement that a message cannot go out if it has a previous request would cause the queue to block because it has no response. By assigning this identifier to the callback, the bridge reuses the previous request and thus the callback response would unblock the queue.

Before sending an async Callback to aura-groot, you must assign the messageId with the id of the activity:

messageId = context.activity.id

Output message (response)

Output messages can be one or several for each input message. They all contain a unique identifier responseId, the identifier to the input message to which they belong (requestId) and the conversation identifier.

Awaited messages

The outgoing messages can be in two states:

PENDING, which means that messages are already included in the queue and it is currently trying to send them.
AWAITED, which are messages that have been tried to be sent, but for whatever reason it has not been possible.

These messages must be reattempted to be sent.

All these processes are managed by the message syncer.

The related aura-bridge environment variables are shown in the following table:

Property	Type	Description	Default Value
AURA_QUEUE_MANAGER_AWAITED_MESSAGE_TTL	number	In milliseconds, maximum lifetime of a message in aura-bridge. After this time, the system will delete the message.	900.000 (15 m)
AURA_QUEUE_MANAGER_AWAITED_MESSAGES_BY_TURN	number	Number of messages to be imported by the Awaited Message Agent in each turn.	15
AURA_QUEUE_MANAGER_AWAITED_MESSAGES_INTERVAL	number	In milliseconds, time interval of a shift for the Awaited Message Agent.	20.000
AURA_QUEUE_MANAGER_AWAITED_RETRIES_FACTOR	number	Factor to manage the backoff of the Awaited Message Agent. The time to consider an `AWAITED` message is: currentRetry * `MAX_PENDING_TIME` * `AWAITED_RETRIES_FACTOR`	1
AURA_QUEUE_MANAGER_AWAITED_TIME_WHEN_RETRIES_END	number	In milliseconds, when a message has consumed all the retries from the queue, it goes to the `AWAITED` state. This variable assigns the waiting time assigned to retry the message.	5000
AURA_QUEUE_MANAGER_CHECK_QUEUE_INTERVAL	number	In milliseconds, time interval used by the queue manager to check if the queue system has pending messages. If not, it deactivates the service and it will be reactivated when a new message comes in.	1000
AURA_QUEUE_MANAGER_CONCURRENT	number	Number of messages processed by the memory queue simultaneously.	25
AURA_QUEUE_MANAGER_CONCURRENT_FACTOR	number	It sets together with `AURA_QUEUE_QUEUE_MANAGER_CONCURRENT` the maximum number of messages the message execution queue can have. The number is assigned with the operation: `AURA_QUEUE_QUEUE_MANAGER_CONCURRENT` * `AURA_QUEUE_QUEUE_MANAGER_CONCURRENT_FACTOR`	2
AURA_QUEUE_MANAGER_INTERVAL	number	In milliseconds, time interval for processing messages in the queue.	200
AURA_QUEUE_MANAGER_MAX_PENDING_TTL	number	In milliseconds, time that a message is in `PENDING` status before it is considered as `AWAITED`.	30.000
AURA_QUEUE_MANAGER_MAX_PENDING_TTL_MARGIN	number	In milliseconds, time margin used by the memory queue to manage the time that a `PENDING` message has before being discarded and returned to the AWAITEDs system.	5.000
AURA_QUEUE_MANAGER_MAX_RETRIES	number	Number of validation attempts. Do not confuse with message sending retries. These retries are for the validations that a message makes to check if it can be sent or if it has to continue waiting.	100
AURA_QUEUE_MANAGER_MESSAGE_TTL	number	In milliseconds, lifetime of an incoming message.	10.000
AURA_QUEUE_MANAGER_SENT_MESSAGE_TTL	number	In milliseconds, lifetime of a message with status `SENT`. If the ACK does not arrive from the client, then the message is considered as sent and is deleted from the system, making way for the next messages that the user has pending.	5.000
AURA_QUEUE_MANAGER_DATABASE	string	Set the default database engine to store the queue information. Values: `REDIS`, `MONGODB`	MONGODB
AURA_QUEUE_MANAGER_METRICS_PARTIAL_INTERVAL	number	In milliseconds, it is used to obtain partial values of the queue metrics. These metrics are internal and used for performance testing to see the behavior of the message queue. To enable these metrics, it is necessary to set the environment variable `AURA_LOGGING_EXTRA_TIME_METRICS` to `true`.	30.000

Message Model

{
    _id?;                       // Mongo Id. Not used in Redis
    conversationId: string;     // Conversation Identifier
    origin: string;             // Name of Client
    requestId: string;          // Request Identifier
    taskItem?: TaskItem;        // Task Item Model
    requestTimestamp?: number;  // Date of request
    responseId?: string;        // Response Identifier
    responseTimestamp?: number; // Date of response
    asyncResponseId?: string;   // Identifier of Async response
    status?: MessageSyncStatus; // Status of Message
    lastAccess?: Date;          // Date of last Access
    sentAttempt?: number;       // Number of sent attempts
    awaitedRetries: number;     // Number of retries by Awaited Agent module
    awaitedToDate: Date;        // Next Date to retry to send the Message
    expiresAt?: Date;           // Message expiration Date
    requestIdCounter?: number;  // Number of response messages
    expiresAtTS?: number;       // Expiration Date in Unix Timestamp format (seconds)
    awaitedToDateTS?: number;   // Same that awaited to Date but in  Unix Timestamp format (seconds)
}

Redis Message Models

Several data structures designed to prioritize performance are required to manage messages in the queue with Redis.

These data structures will be responsible for storing the key data of a conversation: ConversationId, Request Message, Response Message, ACK management, Awaited Messages.

MinMessageInfo String

Structure containing the minimum information of an message, that is: requestId, responseId, conversationId.

It is used as a member of a list and must be passed as a string in a certain order to serve as an internal key and not generate duplicates.

Example:

{ rqId: [requestId], rsId: [responseId], cnId: [ConversationId] }

Redis KEYS

 Request Message:            bridge:queue:req:[ requestId ]  EXPIRES => AURA_QUEUE_MANAGER_MESSAGE_TTL**  
 Response Message:           bridge:queue:res:[ responseId ]  EXPIRES => AURA_QUEUE_MANAGER_AWAITED_MESSAGE_TTL**  
 Conversation Request List:  bridge:queue:[ conversationId ]:req   EXPIRES => AURA_QUEUE_MANAGER_MESSAGE_TTL**  
 Conversation Response List: bridge:queue:[ conversationId ]   EXPIRES => AURA_QUEUE_MANAGER_MESSAGE_TTL**  
 Pending Message List:       bridge:queue:pendingMessages    EXPIRES => AURA_QUEUE_MANAGER_MESSAGE_TTL**  
 ACK Identifier:             bridge:queue:asyncRequest:[ asyncRequestId ]   EXPIRES => AURA_QUEUE_MANAGER_SENT_MESSAGE_TTL**

Request Message

Request messages are stored in a HASH structure:

KEY: bridge:queue:req:[ requestId ] EXPIRES: AURA_QUEUE_MANAGER_MESSAGE_TTL
FIELDS:

Field	Description
conversationId	Conversation identifier
origin	Sender client of the message
requestId	Request identifier
requestTimestamp	Timestamp with the date of request
status	Status of message. Valuer: `WAITING`, `PENDING`
responseIdCounter	Number of replies that have arrived with for this request message
expiresAtTS	Timestamp with the expiration date of the message

Response Message

Response messages are stored in a HASH structure:

KEY: bridge:queue:res:[ responseId ] EXPIRES: AURA_QUEUE_MANAGER_AWAITED_MESSAGE_TTL
FIELDS:

Field	Description
conversationId	Conversation identifier
origin	Sender client of the message
requestId	Request identifier
responseId	Response identifier
requestTimestamp	Timestamp with the date of request
responseTimestamp	Timestamp with the date of response
status	Status of message. Values: `WAITING`, `PENDING`, `SENT`, `AWAITED`, `CANCEL`
expiresAtTS	Timestamp with the expiration date of the message
awaitedToDateTS	Timestamp with the next date to retry sending the message
awaitedRetries	Number of awaited retries
taskItem	TaskItem Model

Conversation Structures

Request List

Queue-structured list of incoming messages in a conversation. It is necessary to maintain the order of the messages. If a reply is going to be sent, make sure that there are no pending incoming messages.

KEY: bridge:queue:[ conversationId ]:req EXPIRES: AURA_QUEUE_MANAGER_MESSAGE_TTL
VALUES: Strings with the key of the requests.

bridge:queue:cnId-1:req

    bridge:queue:req:rqId-A (older)
    bridge:queue:req:rqId-B

Response List

Sorted list with the [ requestTimestamp ].([ responseTimestamp ] % 10000) as score. One for each conversation. It will be the one that indicates the order in which the messages will be sent. It contains a MinMessageInfo It must be taken into account that it must be used together with the previous one because a previous input message may not have received a response yet, so it will not be in this list yet.

Sorted list with the [ requestTimestamp ].([ responseTimestamp ] % 10000) as score. One for each conversation.

It will be the one that indicates the order in which the messages will be sent and contains a MinMessageInfo.

Take into account that it must be used together with the previous one because a previous input message may not have received a response yet, so it will not be in this list yet.

KEY: bridge:queue:[ conversationId ] EXPIRES: AURA_QUEUE_MANAGER_MESSAGE_TTL
VALUES: MinMessageInfo [requestTimestamp].([responseTimestamp] % 10000)

bridge:queue:cnId-1

    10000000.00001  { rqId: rqId-A, rsId: rsId-A1, cnId: cnId-1 } 
    10000000.00009  { rqId: rqId-A, rsId: rsId-A2, cnId: cnId-1 } 
    10000001.00007  { rqId: rqId-B, rsId: rsId-B1, cnId: cnId-1 }

Manage of awaited messages

When a message has consumed all its retries, it goes to an AWAITED state, so that it can be reattempted again. The information regarding when messages can be reattempted is stored in a sorted list, the date from which it can be reattempted and the message data is stored as MinMessageInfo.

KEY: bridge:queue:pendingMessages EXPIRES: AURA_QUEUE_MANAGER_MESSAGE_TTL
VALUES: MinMessageInfo [Timestamp]

bridge:queue:pendingMessages

    10000000  { rqId: rqId-A, rsId: rsId-A1, cnId: cnId-1 } 
    10000002  { rqId: rqId-A, rsId: rsId-A2, cnId: cnId-1 } 
    10000003  { rqId: rqId-B, rsId: rsId-B1, cnId: cnId-1 }

ACK Management

When a message is returned to the client, an identifier (asyncResponseId) is received, which is used to later identify to which message an ACK belongs. This identifier is stored in a key-value structure (asyncRequestId, MinMessageInfo).

KEY: bridge:queue:asyncRequest:[ asyncRequestId ] EXPIRES: AURA_QUEUE_MANAGER_SENT_MESSAGE_TTL
VALUE: MinMessageInfo

  bridge:queue:asyncRequest:rA1  -> { rqId: rqId-A, rsId: rsId-A1, cnId: cnId-1 } 
  bridge:queue:asyncRequest:rA2  -> { rqId: rqId-A, rsId: rsId-A2, cnId: cnId-1 } 
  bridge:queue:asyncRequest:rB1  -> { rqId: rqId-B, rsId: rsId-B1, cnId: cnId-1 }

Message flow and operations

Request Message

The message information is stored in the request message structure.
AURA_QUEUE_MANAGER_MESSAGE_TTL is set to expire.
It is added to the request list of the conversation.
The expiration of the list is set to AURA_QUEUE_QUEUE_MANAGER_MESSAGE_TTL.

Example:

conversationId: conv-01
requestId:      rq-message-1


[Request Message]
Key
 bridge:queue:req:rq-message-1
Properties
 conversationId: "conv-01"
 origin: "whatsapp"  
 requestId: "rq-message-1"
 requestTimestamp: 0000000001
 status: "WAITING"
 responseIdCounter: 0
 expiresAtTS: 000060001

[Conversation conv-01 List]
Key
 bridge:queue:conv-01:req
Value
 0: bridge:queue:req:rq-message-1

If another message from the same user comes in, its request message record is created and added to the end of the list.

In this way, the conversation list has the items sorted in order of arrival, with the oldest being the first. This is useful to know if a message has any unanswered incoming messages.

Example:

conversationId: conv-01
requestId:      rq-message-2

[Request Messages]
.....
Key
 bridge:queue:req:rq-message-1
Properties
 .....
Key
 bridge:queue:req:rq-message-2
Properties
 .....
....

[Conversation conv-01 List]
Key
 bridge:queue:conv-01:req
Value
 0: bridge:queue:req:rq-message-1
 1: bridge:queue:req:rq-message-2

If a message from another user arrives, we will have:

conversationId: conv-02
requestId:      rq-message-3

[Request Messages]
.....
Key
 bridge:queue:req:rq-message-1
Properties
 .....
Key
 bridge:queue:req:rq-message-2
Properties
 .....
Key
 bridge:queue:req:rq-message-3
Properties
 .....
....

[Conversations Lists]

Key
 bridge:queue:conv-01:req
Value
 0: bridge:queue:req:rq-message-1
 1: bridge:queue:req:rq-message-2


Key
 bridge:queue:conv-02:req
Value
 0: bridge:queue:req:rq-message-3

Response Message

Response messages have the identifier associated with the request message. With this identifier, the properties of the input message are obtained and a new HASH record is created for the response data.
The expiration time of AURA_QUEUE_MANAGER_AWAITED_MESSAGE_TTL is added.
Added 1 to the message counter of the request property requestIdCounter.
Add to the list of response Messages of the conversation.
The expiration of the conversation response list is set to AURA_QUEUE_QUEUE_MANAGER_AWAITED_MESSAGE_TTL.
It is added to the list of Pending Messages (awaited).

The expiration of the list of Pending Messages is set to AURA_QUEUE_QUEUE_MANAGER_AWAITED_MESSAGE_TTL.

Example:

conversationId: conv-01
responseId:      res-message-1-1


[Response Message]
Key
 bridge:queue:res:rq-message-1-1
Properties
 conversationId: "conv-01"
 origin: "whatsapp"  
 requestId: "rq-message-1"
 responseId: "res-message-1-1"
 requestTimestamp: 0000000001
 responseTimestamp: 0000000012
 status: "PENDING"
 expiresAtTS: 000080001
 awaitedToDateTS: 000080001
 awaitedRetries: 0
 taskItem: [TaskItem data]

[Conversation responses conv-01 Sorted List]
Key
 bridge:queue:conv-01
Value
 0:  10000000.00001  "{ rqId: 'rq-message-1', rsId: 'res-message-1-1', cnId: 'conv-01' }"

[Pending messages Sorted List]
Key
 bridge:queue:pendingMessages
Value
 0:  000080001  "{ rqId: 'rq-message-1', rsId: 'res-message-1-1', cnId: 'conv-01' }"

If another response to the same request arrives, we will have:

 conversationId: conv-01
 responseId:      res-message-1-2


[Response Message]
Key
  bridge:queue:res:rq-message-1-2
Properties
 ....

[Conversation responses conv-01 Sorted List]
Key
  bridge:queue:conv-01
Value
  0:  10000000.00001  "{ rqId: 'rq-message-1', rsId: 'res-message-1-1', cnId: 'conv-01' }"
  0:  10000000.00002  "{ rqId: 'rq-message-1', rsId: 'res-message-1-2', cnId: 'conv-01' }"

[Pending messages Sorted List]
Key
  bridge:queue:pendingMessages
Value
  0:  000080001  "{ rqId: 'rq-message-1', rsId: 'res-message-1-1', cnId: 'conv-01' }"
  1:  000080002  "{ rqId: 'rq-message-1', rsId: 'res-message-1-2', cnId: 'conv-01' }"

If a message arrives from another request, we will have:

 conversationId: conv-02
 responseId:      res-message-2-1

[Response Message]
Key
  bridge:queue:res:rq-message-2-1
Properties
 ....

[Conversation responses conv-02 Sorted List]
Key
  bridge:queue:conv-02
Value
  0:  10000005.00003  "{ rqId: 'rq-message-2', rsId: 'res-message-2-1', cnId: 'conv-02' }"

[Pending messages Sorted List]
Key
  bridge:queue:pendingMessages
Value
  0:  000080001  "{ rqId: 'rq-message-1', rsId: 'res-message-1-1', cnId: 'conv-01' }"
  1:  000080002  "{ rqId: 'rq-message-1', rsId: 'res-message-1-2', cnId: 'conv-01' }"
  2:  000080003  "{ rqId: 'rq-message-2', rsId: 'res-message-2-1', cnId: 'conv-02' }"

Validate if the response can be sent to the client

It is the operation that each message must perform before being sent to ensure the order of the messages.

Steps:

The response message has an associated a request message. The first thing to be validated is whether the request message is the first in the list of request messages of the conversation list or not.
This is important because a previous request message may have operations as attachments, which means that response messages have not been received yet.
If the request message matches with the request message of the current Response message, then what is checked is whether this response message is the first in the list of Response messages in the conversation or not.
In this case three things can happen:
1. If the current response message is the first in the list, the message can go out.
2. If the first message in the list is not the current response message and it exists, then the current request message will wait.
3. If the first message in the list is not the current response message and it does not exist, it is removed from the list and checked again.

Awaited Management

This is the management of messages that could not be sent because you still have previous messages to send and your sending attempts have been completed.

A message can also go to AWAITED status when a recoverable error occurs.

Steps:

As they are in an ordered list (bridge:queue:pendingMessages), simply collect the messages from that list.
Once the messages to be processed have been collected, they must be blocked so that other services do not process the same messages.
These collected messages are passed to the priority queue to be processed.

Logical States

These are logical states since any message that passes to these states is removed from the queuing system.

Message synchronization modules

Message synchronization is managed at two levels:

The first level is the micro-service memory. A queue within the micro-service’s own memory is used to manage message synchronization locally. For the management of this level, a module called Memory Queue Manager is used, which is composed of two components:
- Memory Queue Core that implements an in-memory queue manager.
- Awaited Message Manager, which is responsible for collecting pending messages from Redis.
The second level is through Redis. It is used to synchronize messages between the different micro-services. For queue management at this level, the Message Sync Module is used, which is responsible, among other things, for managing the CRUD operations of the messages in the queue in Redis.

Memory Queue Manager

Memory Queue Core

Message Task Model

{
  executionTask: QueueTask;                     // Task to execute when validation is OK
  validationTask?: QueueTask;                   // Task to validate if the Main task can be executed
  errorTask?: QueueTask;                        // Task to execute when Main Task fails
  taskId: string;                               // Task identify
  taskGroup: string;                            // Task Group
  tsInput: number;                              // Time when the input message was received
  tsOutput: number;                             // Time when the response message was received
  internalId?: number;                          // Use by the Queue internally
  timeInQueue?: number;                         // Maximum time that one Task can stay in Queue
  messageOptions: SendMessageOptions<any>;      // Message Options
  corr: string;                                 // Task correlator
}

Architecture

Life Cycle

Enqueue Phase

Messages can be queued in the memory queue for two reasons:

Because a response arrives to aura-bridge and it wants to be synchronized or
Because the agent that takes care of the pending messages has obtained messages from Redis, bridge:queue:pendingMessages list.

The aura-bridge environment variables that are associated with this agent are:

Select Priority Tasks

At this point, those that are not expired are selected from the main queue, and secondly, if they belong to a group, only the first one to be sent to the priority queue will be sent to the priority queue.

The aura-bridge environment variables that are associated with this process are:

Execution Phase

In this phase, each task is validated to see if it can be executed. This validation is done, firstly, by validating if it has not expired or has not exceeded the maximum number of validations, and secondly if there is no pending task for the user to whom the message is addressed.

The flow within the execution phase is as follows:

The aura-bridge environment variables that are associated with this process are:

Awaited Messages Agent

This module is in charge of collecting messages with AWAITED status.

The collection of these messages is done periodically:

The variable AURA_QUEUE_QUEUE_MANAGER_AWAITED_MESSAGES_INTERVAL is the one that establishes the interval time.
The number of messages to collect at each interval is determined by the environment variable AURA_QUEUE_QUEUE_MANAGER_AWAITED_MESSAGES_BY_TURN.

When the module is started for the first time, a second within a minute is set, i.e., a value between 0 and 59 in which the first request for messages with AWAITED status will be launched, and from then on, the time interval is followed. This is to try to avoid that two instances of aura-bridge make the request at the same time.

Memory Sync Manager

This module is in charge of managing the synchronization between the different aura-bridge instances and their messages. This is performed through the MessageSyncManager class.

Methods

createConversationRegister

Method used for message input in aura-bridge. It sets the message to WAITING status.
This method has all steps to manage Request Message Flow.

Input:
- origin: Name of the client sending the message. Example: “whatsapp”.
- conversationId: Conversation identifier.
- requestId: Identifier of the incoming message.
- corr: Correlator of the request.
- requestTimestamp: Date on which the request is made.
Output:
- MessageSyncInfo: Message Model.

getInitDefaultValues

This is an auxiliary method used to initialize the values to their default value.

Input:
- origin: Name of the client sending the message.
- conversationId: Conversation identifier.
- requestId: Identifier of the incoming message.
- requestTimestamp: Date on which the request is made.
Output
- MessageSyncInfo: Message Model.

markPendingConversationRegister

This method is called when a response message has arrived and has all steps to manage Response Message Flow.

Input:
- origin: Name of the client sending the message.
- conversationId: Conversation identifier.
- requestId: Identifier of the incoming message.
- taskItem : Message Task Model.
- corr: Current correlator.
- responseId: Unique identifier for the response message.

markSentConversationRegister

This method is used when a message is sent to the destination client. It sets the status of the message to SENT.

Input:
- conversationId: Conversation identifier.
- requestId: Identifier of the incoming message.
- corr: Current correlator.
- responseId: Unique identifier for the response message.
- asyncResponseId: Identifier received when sending the message. This is used when sending messages against asynchronous clients. This identifier is necessary to manage the ACKs.

canSendConversationMessage

This is the method used by the default validator of a message to know whether or not the current message can be sent to the destination client.

The model used to the return value is:

CanSendResponse {
    canSendStatus: CanSendStatus;
    firstResponseId: string;
}

Input:
- conversationId: Conversation identifier.
- requestId: Identifier of the incoming message.
- corr: Current correlator.
Output:
- CanSendResponse: it returns a boolean value indicating whether or not the message can be sent.

getFirstConversationMessage

This method returns true if the current message is the first one, indicating that it can be sent immediately.

Input:
- conversationId: Conversation identifier.
Output:
- MessageSyncInfo: Message Model.

deleteConversationMessage

This method deletes all references in Redis of a message. To select the message to be deleted, it uses the model SyncMessageOptions.

SyncMessageOptions {
    responseId?: string;
    asyncResponseId?: string;
    corr: string;
}

Input:
- options: SyncMessageOptions

deleteConversationRegister

This method deletes all messages from the same RequestId.

Input:
- allOriginExcept: Indicates that messages should not be deleted.
- status: The status that the message must have to be deleted.
- requestInfo: Object generated in all requests that contains the relevant information of a request.

getConversationMessage

This method returns a message based on its responseId or asyncResponseId.

Input:
- options: SyncMessageOptions.
- projection: A filter in JSON format to return only specific fields. Example: { name:1}.
Output:
- MessageSyncInfo: Message Model.

setAwaitedByRequestId

This method sets the message to AWAITED status based on its requestId.

Input:
messageInfo: Message Model.
corr: Current correlator.

setAwaitedByResponseId

This method sets the message to AWAITED status based on its responseId.

Input:
- options: SyncMessageOptions.

getAwaitedMessages

It returns a specified number of messages with AWAITED status.

Input:
- nMessages: Number of messages to return.
- corr: Current correlator.
Output:
- MessageSyncInfo: Message Model.

setErrorById

Used when needs remove current message and their siblings.

Input:
options: SyncMessageOptions.

updateAwaitedExpires

Set a new date for awaited.

Input:
- responseId: Response id of message to update.
- corr: Current correlator.

removeRequestMessage

Remove all references of a message in redis.

Input:
- syncOptions: SyncMessageOptions.
- removeOwner: True if the current message must be deleted
- corr: Current correlator.

getAllSiblings

Get all siblings of a message

Input:
- responseIdKey: Response message Key in Redis
- corr: Current correlator.
Output:
- ResponsesIdByRequestId: model with info and siblings.

removeAllSiblings

Remove all siblings from a RequestIdByRequestId model.

Input:
- ResponsesIdByRequestId: Model with info and siblings.
- corr: Current correlator.

generateUniqueMinInfoKey

Get all siblings of a message.

Input:
- minInfo: Minimal information of a message MinMessageInfo.
Output:
- string: String with the data in JSON model: { rqId: minInfo.rqId, rsId: minInfo.rsId, cnId: minInfo.cnId }.

removeAllReferencesAtTime

Used to remove all references of a message in Redis setting a timer.

Input:
- syncOptions: SyncMessageOptions.
- delay: Delay in seconds to wait until remove the references.
- corr: Current correlator.

Docs:

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

Introduction to ATRIA multibrand feature

Description of ATRIA multibrand feature, based on a multitenant architecture

Introduction

ATRIA, just like Aura Virtual Assistant, is designed as a multibrand platform, meaning that users can access ATRIA through the different Telefónica brands available in their country.

This multibrand feature is based on a multitenant architecture, with a tenant defined as the deployment associated to a specific brand.

Functional multitenant architecture in ATRIA

An overview of the functional operation of the multibrand feature in ATRIA is shown and explained below:

Overview of multitenant architecture in ATRIA

ATRIA supports different brands
Each brand is associated to several channels
Each channel allows accessing to use cases in a specific domain
When a user send a request, it passes through Kernel and is managed by a specific Kernel tenant
This Kernel tenant sends the query to a particular ATRIA tenant
ATRIA calls the required AI-driven models for its resolution

Technical documents

Multitenant configuration in Aura installer

Aura installer: Multitenant configuration: Guidelines for the configuration of different tenants when several brands are available in the OB.

Descriptive documents and guidelines

Once the user accesses through a specific Telefónica brand, the technical behavior of the corresponding Aura tenant is similar to the one before the implementation of the multitenant architecture. Therefore, there are no specific descriptive documents or guidelines for the multitenant architecture.

Docs:

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

Aura bridge channelData.payload model

Description of the data model used by Aura Bridge in channelData.payload

Description

aura-bridge adds relevant information in communication with aura-groot through a field called payLoad. This field is at the root of the channelData field of the activity:

{
    from: {
        ...
    },
    conversation: {
        ...
    },
    channelData: {
        payload: { ... } // Bridge extra information
    }
}

Read detailed information regarding the management of the channelData payload property.

aura-models library, available in aura-utilities repository, contains the basic typescript interfaces and models definitions used across aura-groot components.

Docs:

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

Aura KPIs dimensions

Processing of Aura KPIs dimensions generated in aura-kpis-uploader

All of them will be generated in Avro format.

Introduction

aura-kpis-uploader-cli component generates the following types of KPIs dimensions:
. Channel type dimensions
. Recognizers type dimensions
. Skill type dimensions
. Components type dimensions
. Presets type dimensions
. Applications type dimensions

All of them are stored into the correspondent container in Aura Common Azure Storage (environment variable: AURA_KPIS_STORE_COMMON_CONTAINER).

Once the files are copied, the local copy is moved to a folder inside the container (environment variables: AURA_KPIS_STORE_COMMON_CONTAINER/ AURA_KPI_UPLOADER_PROCESSED_FOLDER) and kept there during a time, for recovering issues.

Types of KPIDimensionType:

export enum KPIDimensionTypes {
    KPIS_DIMENSIONS_CHANNEL = 'CHANNEL',
    KPIS_DIMENSIONS_RECOGNIZER = 'RECOGNIZER',
    KPIS_DIMENSIONS_SKILL = 'SKILL',
    KPIS_DIMENSIONS_APP = 'APP',
    KPIS_DIMENSIONS_PRESETS = 'PRESETS',
    KPIS_DIMENSIONS_COMPONENT = 'COMPONENT'
}

The path and filename should follow these patterns:

Path: AURA_KPIS_ENTITIES_CONTAINER/avro/dimensional/<avro_schema: name>/<avro_schema: x-fp-version>
Filename: <OB>_DIM_<DIM_NAME>_YYYYMMDDTHH0000Z.<AURA_KPI_FILES_EXTENSION>

The filename of the file is obtained as follows:

export function getDimensionFileName(KPIDimensionType: string) {
    return \`${getCountry().toUpperCase()}_\` +
        'DIM_' + \`${KPIDimensionType}_\` +
        \`${moment()
            .toISOString()
            .substring(0, 13)
            .replace(/-/g, '')
            .replace(/:/g, '') + '0000Z'}\` +
        \`${ConfigurationManager.instance.environmentConfiguration.AURA_KPI_FILES_EXTENSION}\`;
}

Channel type dimensions

aura-kpis-uploader-cli gets the list of channels configured in the environment through the aura-configuration-api channels endpoint.

It generates a file with the following schema:

Channel Schema

The Adapter format:

 {
        "name": "D_Aura_Channel",
        "schema": "dimensional",
        "avroSchema": "aura-channel-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "CHANNEL"
        },
        "targetType": "avro",
        "fields": {
            "AURA_CHANNEL_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_CHANNEL_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "AURA_CHANNEL_SHORT_NAME": {
                "sourceName": "prefix",
                "targetType": "string"
            },
            "AURA_SKILL_ID": {
                "sourceName": "skillId",
                "targetType": "string",
                "defaultValue": "NO_SKILL"
            },
            "AURA_NLP_STAGES_ARRAY": {
                "sourceName": "nlp.stages",
                "targetType": "array",
                "nullable": "true"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "GBL_CONTACT_CHANNEL_ID": {
                "sourceName": "contact",
                "targetType": "string"
            },
            "BRAND_ID": {
                "sourceName": "brand",
                "targetType": "string"
            }
        }
    }

Recognizers type dimensions

aura-kpis-uploader-cli gets the recognizers configuration through the file configured in the project: aura-kpis-uploader/src/dimensions/resource/recognizers.json

It generates a file with the following schema:

Recognizer Schema

The Adapter format:

  {
        "version": "1.0.0",
        "name": "D_Aura_Recognizer",
        "schema": "dimensional",
        "avroSchema": "aura-recognizer-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "RECOGNIZER"
        },
        "targetType": "avro",
        "fields": {
            "AURA_RECOGNIZER_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_RECOGNIZER_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            }
        }
    }

Skill type dimensions

aura-kpis-uploader-cli gets the skill configuration through the aura-configuration-api Skills endpoint.

It generates a file with the following schema:

Skill Schema

The Adapter format:

{
        "version": "1.0.0",
        "name": "D_Aura_Skill",
        "schema": "dimensional",
        "avroSchema": "aura-skill-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "SKILL"
        },
        "targetType": "avro",
        "fields": {
            "AURA_SKILL_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_SKILL_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "EXTERNAL_SKILL_IND": {
                "sourceName": "external",
                "targetType": "boolean"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            }
        }
    }

Components type dimensions

aura-kpis-uploader-cli gets the components configuration through the aura-configuration-api Components endpoint.

It generates a file with the following schema:

Component Schema

The Adapter format:

{
        "version": "1.0.0",
        "name": "D_Aura_Component",
        "schema": "dimensional",
        "avroSchema": "aura-component-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "COMPONENT"
        },
        "targetType": "avro",
        "fields": {
            "AURA_COMPONENT_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_COMPONENT_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            }
        }
    }

Presets type dimensions

aura-kpis-uploader-cli gets the presets configuration through the atria-model-gateway presets endpoint.

It generates a file with the following schema:

Preset Schema

The Adapter format:

    {
        "version": "1.0.0",
        "name": "D_Aura_Preset",
        "schema": "dimensional",
        "avroSchema": "aura-preset-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "PRESETS"
        },
        "targetType": "avro",
        "fields": {
            "AURA_PRESET_ID": {
                "sourceName": "preset.id",
                "targetType": "string"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "preset.name",
                "targetType": "string"
            },
            "AURA_MODEL_ID": {
                "sourceName": "model.id",
                "targetType": "string"
            },
            "AURA_PRESET_GROUP_NAME_CD": {
                "sourceName": "preset.group",
                "targetType": "enum",
                "symbols": [
                    "enriched_ai",
                    "simple_ai"
                ]
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            }
        }
    }

Applications type dimensions

aura-kpis-uploader-cli gets the applications configuration through the aura-configuration-api Applications endpoint.

It generates a file with the following schema:

Application Schema

The Adapter format:

    {
        "version": "1.0.0",
        "name": "D_Aura_App",
        "schema": "dimensional",
        "avroSchema": "aura-app-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "APP"
        },
        "targetType": "avro",
        "fields": {
            "AURA_APP_ID": {
                "sourceName": "id",
                "targetType": "string"
            },
            "AURA_APP_NAME": {
                "sourceName": "name",
                "targetType": "string"
            },
            "AURA_NLP_CHANNEL_ID": {
                "sourceName": "nlp.channeId",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_PRESET_NAMES_ARRAY": {
                "sourceName": "models.presets",
                "targetType": "array",
                "nullable": "true"
            },
            "EXTRACTION_TM": {
                "sourceName": "EXTRACTION_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "BRAND_ID": {
                "sourceName": "brand",
                "targetType": "string"
            }
        }
    }

Docs:

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

Introduction to Aura multibrand feature

Description of Aura multibrand feature, based on a multitenant architecture

Introduction

The OBs commercialize their Telefónica services through different brands (Movistar, O2, Vivo, Blau, Whatsapp SIM, etc.).

To align with this scenario, Aura (both Aura Virtual Assistant and ATRIA) is now designed as a multibrand virtual assistant, capable of providing services to multiple brands through a shared infrastructure.

The communication flow is similar to the one previous to the implementation of the multibrand feature (see Figure 2).

A user can access Aura through the different Telefónica brands available in her country.
Within a specific brand, the connection to Aura is done through a particular channel.
The user can now submit a request (use case) and have it resolved, as long as the use case is available in this specific channel.

Overview of the multitenant architecture

Aura multibrand feature is based on a multitenant architecture.

In the multitenant architecture, we introduce the concept of tenant, defined as the deployment associated to a specific brand.

Aura multibrand feature operates in different scenarios:
- In Aura Virtual Assistant (use cases resolved by a bot or skill)
- In ATRIA (use cases resolved by AI-powered LLM models)

In both scenarios, Aura Virtual Assistant and ATRIA are structured in different tenants, each of them associated to a specific brand and with isolated deployment and operation.

Relationship between brand and tenant

There is not physical separation between Aura components in each brand, but logical separation.

As well as Aura, Kernel also supports a multitenant architecture. A tenant in Kernel is defined as a logical way of isolating resources within a Kernel instance.

A use case submitted from a specific brand will be resolved using the Kernel tenant associated to this brand.

See more details of the specific behavior of the multitenant architecture in:

Functional multitenant architecture in Aura Virtual Assistant

An overview of the functional operation of the multibrand feature based on multitenant architecture in Aura Virtual Assistant is shown and explained below:

Overview of multitenant architecture in Aura Virtual Assistant

Aura Virtual Assistant supports different brands
Each brand is associated to several channels
Each channel allows accessing to use cases in a specific domain
Use cases in a specific brand are operated by a particular Aura tenant
These use cases will be resolved using the Kernel tenant associated to this brand

An exception to this Aura Virtual Assistant behavior is for authentication. In this task, the authentication request enters firstly through a Kernel tenant, and once the user is authorized, it passes to the corresponding Aura tenant.

Comprehensive technical documents

Multitenant configuration in Aura installer

Aura installer: Multitenant configuration: Guidelines for the configuration of different tenants when several brands are available in the OB.

Descriptive documents and guidelines

Docs:

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

Aura Bot channelData

How Aura Bot manages the channelData property used by Aura to define the Aura request-response semantic model

The current section details the management by aura-bot skill of the channelData property used by Aura to define the Aura Request – Response Semantic Model.

The Aura semantic application model defines a set of properties that can be used as secondary elements of the Microsoft Azure Bot Service and Bot Framework Activities property included in the application activities.

channelData is an open field in the activity, i.e., the message exchanged during a communication between a channel and a bot built on top of Microsoft Bot Framework, that is devoted to define the specific format of the request needed by the specific bot to provide a proper response to the channel and, thus, to the user.

The current section will describe the specific channelData aspects related to aura-bot, such as:

How to handle the different channelData versions.
channelData mapping in Aura response.
channelData validations in requests and responses.

Docs:

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

channelData validations

channelData validations done both in the request and the response, according to a certain configuration

Validations in request channelData

Request channelData will be validated if its version is greater than or equal to AURA_CHANNELDATA_VALIDATION_MIN_VERSION, that is always v3 (prior versions will never validate and will get all the channelData “as they are”).

That means, that any version from v3 onwards will be validated (even non existing versions, such as 99, will try to be validated).

Versions from v3 onwards will only use the major as a string (e.g., 3), but also semver is understood (e.g., 3.0.0), but note that minor and patch will be ignored (e.g., 3.2.1 === 3.0.0) when looking for a validator.

Logic location

The validation is done in the channeldata-validator-middleware, that must be one of the first middlewares, to ensure that no other logic is fetching data from channelData before validating it.

Errors

There are two types of errors on request validation:

Validation error: the request channelData does not comply the schema for that version. The error is stored in requestValidationErrors property within the thrown error.
Missing validator error: the specified version does not have a matching validator, so channelData is invalid.

Validations in response channelData

Response channelData will be validated if AURA_CHANNELDATA_RESPONSE_VALIDATION environment variable is set to true.

In that case, all outgoing activities will have their channelData validated, even the error messages, before sending to the user.

The validation must be done after the channelData is transformed into the final version (that could be or not the “internal” version).

Logic location

The response validation is done in Aura Groot, in AuraCloudAdapter class.

Errors

There are two types of errors on response validation:

Validation error: the response channelData does not comply the schema for that version and the error is stored in responseValidationErrors property within the thrown error.
Missing validator error: the specified version does not have a matching validator, so the channelData is invalid.

Docs:

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

dialogContext model

Description of the dialogContext model, for the management of different existing options in the response

Introduction

A dialogContext is a structure that facilitates the recognition of CardActions and prompts without the need of training.

It has the following characteristics:

It can be autogenerated when a prompt is active.
It can be autogenerated when there is a CardAction.
It can be created manually in a dialog but with certain restrictions.
It is stored in the conversation cache.
It is processed by the dialog-context-recognizer-middleware.
It is auto-generated and stored by the aura-bot adapter.
It can be configured at channel level, prompt level and CardAction level.
It facilitates the recognition of CardActions if a user, instead of pressing the button, types the button text.
It facilitates the recognition of numbered lists either by ordinals or cardinals.
It uses a proximity search algorithm.
It solves the problems of the recognition of numbers and ordinals that the current Bot Framework prompt has.

Existing models

dialogContext model

Property	Type	Description
text	String	Text or texts (separated by ‘\|’) with the options to be matched.
value	Object	Object of `IntentResult` or other with the action to carry out if the option is validated.

Example:

"dialogContext": [
                    {
                        "text": "Hello",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "greetings",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    },
                    {
                        "text": "Bye bye mi picolissima dama",
                        "value": {
                            "intent": "intent.factotum-test.dialog-context",
                            "entities": [
                                {
                                    "entity": "goodbyes",
                                    "type": "ent.dialog-context",
                                    "score": 1
                                }
                            ]
                        }
                    }
                ]

Channel model

The dialogContext model at the channel level applies to all dialog components.

This model has the highest priority, i.e., in case of conflict between models, the channel model has the highest weight.

This model is inside the responseOptions.dialogContext property. Check it in Aura channel model: ResponseOptions model.

An example is shown below:


channel: {
...
        responseOptions: {
            dialogContext: {
                normalizeTerms: true,
                disabled: false,
                disabledMerge: false,
                processFromClient: false,
                returnToClient: false,
                defaultListType: 'none',
                promptChoice: {
                    generate: 'never',
                    generateList: false
                },
                cardActions: {
                    generate: 'never',
                    generateList: false
                }
            }
        }
    },
...

Prompt model

The options of dialogContext for a prompt can be included inside the property validations of Prompt Options within its sub-property dialogContext.

When generating the list of options, the system takes into account two properties of the prompt: recognizeNumbers and recognizeOrdinals.

In these cases:

If the prompt has recognizeNumbers=false and we have activated the list of options, only the ordinal values of each option will be generated.
If the option recognizeOrdinals=false, then only the cardinal options will be generated.
If both are set to false, no list items will be generated.

By default, the prompt has both properties set to true.

Property	Type	Description
originalFindChoicesOptions	Object	Original prompt findChoiceOptions. Used if the dialogContext recognizer needs to change it, the prompt would be restored to the original state.
originalStored	Boolean	It indicates whether the dialogContext recognizer had to overwrite the original prompt values. Default: `false`.
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for prompt options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of list to enumerate the prompt options. Default: `OrdinalCardinal`.

Example of prompt options:


{
  "Choices": [
    {
      "value": "Lunes",
      "synonyms": [
        "El lunes"
      ]
    },
    {
      "value": "martes"
    }
  ],
  "validations": {
    "dialogContext": {
      "enabled": true,
      "listType": "ordinal "
    }
  }
}

CardAction model

The options of dialogContext for a CardAction can be included inside the property channelData of button options, within the sub-property dialogContext.

Property	Type	Description
enabled	Boolean	It indicates whether the generation of ordinal and cardinal lists for CardAction options is active. Default: `Inherited from the channel configuration`.
listType	DefaultListType	Type of the list to enumerate the CardAction buttons. Default: `OrdinalCardinal`.
synonyms	String[]	Array of strings with synonyms of the title.

{
  "buttons": [
    {
      "type": "postBack",
      "title": "Monday",
      "value": {
        "intent": "monday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal"
        }
      }
    },
    {
      "type": "postBack",
      "title": "Wednesday",
      "value": {
        "intent": "wednesday"
      },
      "channelData": {
        "dialogContext": {
          "enabled": true,
          "listType": "ordinalCardinal",
          "synonyms": [
            "X"
          ]
        }
      }
    }
  ]
}

Custom dialogContext

It is possible to add in the channelData a dialogContext manually. If the channel configuration allows it, this will be merged with the _dialogContext that is generated automatically.

The following rules must be taken into account when including our own dialogContext:

Do not generate the list values, that is, do not add ordinals and/or cardinals, as this will be done by the system.
The options of a custom dialogContext are included right at the top of the list.

How does dialogContext work?

The dialogContext flowchart includes two differentiate phases: recognition phase and build phase, described below.

Recognition phase

When validating if the user has entered a phrase that matches the dialogContext that we have generated from the previous answer, take into account that the comparison is done by proximity.

The match value will be reported in a score field that goes from 0 to 1. Valid values will be those that are greater or equal to a given threshold. For a dialogContext we have two thresholds.

AURA_DIALOG_CONTEXT_THRESHOLD: Default threshold when comparing two strings. Default value: 0.80.
AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD: Threshold used in case dialogContext elements are in list form and also if the input phrase includes a number. By default, 0.95.
This value is so high because if the user writes ‘11’ or ’the 11’, and there are only 5 elements in the list, the comparison could give us a very high value, since comparing 11 with 1 has a threshold higher than 0.80, which means that writing 11 would select the first option. To avoid this kind of cases when there are numbers in the user input and the list is enumerated, then the threshold should be stricter.

Another thing to take into account is that if the dialogContext does not get a valid match, if we have an active prompt choice, the system will override its recognizeNumbers and recognizeOrdinals properties, as long as we are working with enumerated elements.

This is done because when MS Bot Framework detects an ordinal number in a sentence, it ignores the rest of the sentence, which can lead to many errors. These values are restored every time the prompt is regenerated if it has not been resolved.

In the recognition phase, the dialogContext recognizer compares value to value, and in the case that one of them meets the conditions, the intention associated with the value is established. It also assigns to the input text the value expected by the prompt, in case there is one.

Example:

DialogContext

[
  {
    "text": "1|the 1|one|the one|first|the first|Monday",
    "value": {
      "intent": "monday"
    }
  },
  {
    "text": "2|the 2|two|the two|second|the second|Tuesday",
    "value": {
      "intent": "tuesday"
    }
  },
  {
    "text": "3|the 3|three|the three|third|the third|X|Wednesday",
    "value": {
      "intent": "wednesday"
    }
  },
  {
    "text": "4|the 4|four|the four|fourth|the fourth|Thursday",
    "value": "The Thursday"
  },
  {
    "text": "5|the 5|five|the five|fifth|the fifth|Friday",
    "value": "Friday"
  }
]

User Input: the 4

In this case, as the list is numbered and the user has entered a number in his sentence, the selected threshold will be AURA_DIALOG_CONTEXT_ORDINAL_CARDINAL_THRESHOLD.
The elements of each option will be compared with the user’s value:

   1 ≅ the 4  -> Score 0 
   the 1 ≅ the 4  -> Score 0.80
   ......
   the 4 ≅ the 4  -> Score 1.0   -> Option Selected

If the selected option has value, the value is assigned to the activity text. In other case, the assigned value is the last value of the text, in this case ‘Thursday’.
If there is a prompt choice, the validations recognizeNumbers and recognizeOrdinals are set to false.

Build phase

The build phase is responsible for collecting the customized dialogContext (if any) and, in turn, for generating the dialogContext of the CardActions and Prompt in the different activities that make up the output message.

The enumeration of the elements depends on the configuration of the channel and the respective components. Once generated, it is stored in the user’s conversation cache.

The module in charge of this procedure is the Aura Bot Adapter.

Docs:

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

Import documents into ATRIA

Guidelines for importing documents and new data into ATRIA environment

Introduction

As described in General RAG: functional overview, when using RAG capability, different databases are used for lexical and semantic search.

The documents that feed these knowledge bases must be uploaded into the environment to be used in the RAG chain and updated when required. In this framework, two processes must be considered:

a. Curate data (recommended): Firstly, it is important to curate the data to be uploaded afterwards, to optimize the recognition process.
b. Import documents: Once the data is curated, the documents must be uploaded into the system. For that purpose, apart from the general method, a hot swapping process can be executed.

a. Data curation

Data curation is the process of organizing, managing, cleaning up and maintaining data to ensure it stays relevant and valuable. Good practices in this task leads to an efficient recognition by the AI model.

For this purpose, we recommend following these tips, based on research and internal analysis:

1. Data selection and cleaning

Include only data relevant to the purpose of the RAG. Redundant, irrelevant or outdated information should be removed to clean up noise that does not add value.

2. Clarity and consistency in content

Be concrete and specific: Keep the information to the point. Avoid unnecessary words or complex explanations.
Avoid ambiguous messages: Avoid vague or unclear terms that could lead to confusion. Make sure the meaning is easy to interpret.
Reinforce the message: Make the message clearer by using specific terms related to the category being discussed. Use keywords strategically to reinforce the message.
Make sure procedures are clear and include all the necessary steps: Make sure each step in tutorials is fully described, logically structured and easy to follow. Avoid fragmented or disjointed instructions.
Remove unnecessary reference information: Minimize excessive details between steps that could distract or confuse the LLM. Keep the flow simple and clear.

3. Improvements in information

Add missing content: If the product includes features similar to others but with slight variations, add a sentence explaining what is and is not supported to make the LLM more accurate.
Add similar terminology: Although you cannot control what terminology people use, mentioning common alternative terms in your content can help the LLM provide more informative answers.

4. Structure and formatting

Maintain consistent formatting: Ensure all steps follow a parallel structure (similar sentence formats and style) to improve coherence.
Simplify complex tables: Avoid blank cells and ensure every cell has a complete value. Replace symbols (e.g., checkmarks) with clear text (“Yes”, “Supported”) to improve interpretation. Rewrite footnote text to add context. Move complex information in table cells out of the table.
Avoid nested content: LLMs can have difficulty with multiple levels of nesting (e.g., steps within steps). Keep content linear and simple for better understanding.
Add summaries to tutorials or long procedures: LLMs can get “lost” with long tutorials or procedures due to context window limitations. Including a summary is a simple way to enhance results.

5. Clarification and Explanation of Concepts

Easy writing: Resolve writing issues such as wordiness, passive voice, and unclear pronouns (with ambiguous references) to make text more understandable.
Explain graphics/images in text: Clearly explain conceptual graphics through text to resolve ambiguities and avoid relying on an image-to-text model

b. Import documents

Once the data is curated, the documents must be uploaded into the system. For that purpose, the following guidelines must be followed.

Note: The RAG does not support files with whitespaces.

1. Upload documents in the Azure container `atria-resources`

Insert these documents in the <preset_name>/<retrievalStg.sources.name>/<retrievalStg.sources.docs[i].extension>/ folder.
Keep in mind the allowed formats for documents, set in the preset’s variable loader.loaderType.

2. Configure `docs` parameter in preset

For these documents to be used in your use case, they must be included in the preset, following these instructions.

Fill in the parameters in the docs key of your preset, which is related to the configuration of documents.

Here is an example of documents configuration. In this example, documents in the preset are separated into two folders, as we are going to load two different types of data (jsonl and pdf) into this preset.

```json
{
"retrievalStg":{
    "sources":{
        "name":"project-de-faqs",
        "embeddings":"text-embedding-ada-002",
        "docs":[
            {
            "extension":"jsonl",
            "loader":{
                "loaderType":"jsonl"
            }
            },
            {
            "extension":"pdf",
            "loader":{
                "loaderType":"unstructured",
                "options":{
                    "loaderMode":"single"
                }
            }
            }
        ],
        "splitter":{
            "splitterType":"recursivechar",
            "options":{
            "chunkSize":512,
            "chunkOverlap":160
            }
        },
        "retrievers":[
            {
            "retrieverType":"qdrant"
            },
            {
            "retrieverType":"tfidf"
            }
        ]
    }
}
}
```

3. Upload list of URLs

If you use URLs as documents ("loaderType": "url_list"), you also need to upload a file with the list of URLs in the preset folder.
Separate each URL with a line break. The file must have the extension .txt.
```
http://www.url1.com
http://www.url2.com
```

4. Upload jsonl or jsond files

If you use jsonl or jsond files as documents ("loaderType": "jsonl" or "loaderType": "jsond"), you also need to upload the file content in the same folder with the extension .jsonl or .jsond.

To do so, each desired document content must be provided in the page_content key.

{"page_content": "test1", "metadata": {"source": "https://www.dummy1.es/"}, "type": "Document"}
{"page_content": "test2", "metadata": {"source": "https://www.dummy2.es/"}, "type": "Document"}

5. Add project.metadata file (optional)

Scenario 1: Unstructured, csv or text data

If the loaderType is url_list, unstructured or csv, you can optionally add a file called project.metadata with relevant information about each file. This metadata will be stored in the database and is very helpful when we want to modify the source URL.

It is important that the file is correctly tabulated and does not contain any invalid characters.

The file is composed of:

Key __global__, which contains global data that affects all the files.
Names of the specific files to which we want to include this extra data.

It is not necessary to define metadata for all the files in the folder.

Example:

__global__:
   url: https://www.google.com
   field1: test
   field2: test
file1.txt:
   url: https://www.dummy-url.com
   title: file1 title
file2.txt:
   url: https://www.dummy-url.com
   title: file1 title
   source: test

NOTE: From all the information added to the project.metadata when creating your use case, you can select the specific sources that will be shown to the user as part of the response, adding them to the field baseURL of the preset configuration.

Scenario 2: URL or json documents

In this case, there is no need to add the project.metadata file:

"loaderType": "url_list" —> Metadata information is included in the URLs themselves, uploaded in step 3
"loaderType": "jsonl", "loaderType": "jsond" —> Metadata information is already included in the files uploaded in step 4

6. Update data into the environment

Finally, execute the atria-rag-generate-db job to update the data into the environment.

Docs:

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

Description of the process for redirecting intents that need authentication in cases where the user is unauthenticated.

Global authentication dialogs

There are 2 different dialogs to authenticate the user according to the channel:

account-linking dialog for channels using integrated authentication, for example, Aura Webclient.
whatsapp-otp-login dialog for SMS-OTP authentication in WhatsApp channel.

To redirect to login dialogs, we need a contextFilter with the redirectToIntent field set with the intent of the authentication dialog that we want to redirect.

This is done in the channel model:
triggerCondition model > conditionValidation model

For example, if we want to redirect to authentication in a channel, we need to add a configuration in the dialog as shown below:

{
  "name": "bill",
  "dialogs": [
    {
      "id": "balance-check",
      "triggerConditions": [
        {
          "intent": "intent.balance.check",
          "contextFilters": [
            {
              "name": "Anonymous redirect to linking",
              "type": "type",
              "conditions": "/type eq 'anonymous'",
              "true": {
                "name": "Anonymous redirect to linking",
                "breakDialogExecution": true,
                "breakFilterEval": true,
                "redirectToIntent": "intent.account.linking",
                "suggestions": false
              }
            }
          ]
        }
      ]
    }
  ]
}

In WhatsApp channel, the contextFilter will be the same but changing the redirectToIntent to the intent for WhatsApp authentication (intent.authentication.login):

{
  "triggerConditions": [
    {
      "intent": "intent.factotum-test.whatsapp-auth",
      "contextFilters": [
        {
          "name": "Anonymous redirect to linking",
          "type": "type",
          "conditions": "/type eq 'anonymous'",
          "true": {
            "name": "Anonymous redirect to linking",
            "breakDialogExecution": true,
            "breakFilterEval": true,
            "redirectToIntent": "intent.authentication.login",
            "suggestions": false
          }
        }
      ]
    }
  ]
}

Docs:

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

Semantic Search capability

Overview of the Semantic Search capability, encompassing the underlying technology and its application in ATRIA

Introduction to Semantic Search technology

Within Natural Language Processing technologies, Semantic Search goes beyond the traditional keyword-based search methods, as it delves into the intent and the meaning behind a query, interpreting the meaning of words and phrases.

This leads to the generation of more accurate and relevant search results that align closely with the user’s intent.

For this purpose, semantic search uses neural network embeddings: a representation of words or phrases in a continuous vector space that captures the semantic relationships between them. This information is crucial for semantic search to interpret the user’s intent accurately.

Figure 7. Semantic Search technology

Application of Semantic Search in ATRIA

Semantic Search is a specific NLP App, included in the NLP as a Service capability.

ATRIA benefits from the Semantic Search capability based on embeddings for the development of generic questions experiences (grounded in FAQs).
It allows achieving an accurate understanding of requests and the generation of highly reliable answers, fully aligned with the user's expectations.

Figure 8. Semantic Search in ATRIA

Interaction with Semantic Search in ATRIA

This service is accessible via API, enabling its consumption both from Aura Platform and any external application.

Semantic search technology is available in Aura through a specific Aura NLP stage: OpenAI embeddings.

Current available models

Semantic Search currently uses Azure OpenAI embeddings technology.

Check the version of the model here.

Functional overview

The use of this capability encompasses three different stages:

Preparation, for the creation of the use case knowledge bases with the required FAQs and associated answers, and the subsequent generation of embeddings with this information.
Identification, in which a user sends a request to ATRIA, selecting as the specific NLP App the one that includes the semantic search technology (OpenAI embeddings). This app recognizes the user’s request.
Answer generation: the best response to the user request is identified and sent back to the user.

Docs:

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

Introduction to ATRIA multi-language feature

Description of ATRIA multi-language feature, offering its AI-driven capabilities in different languages

This feature is only available for ATRIA RAG stages

Introduction

ATRIA RAG now includes a multi-language feature, to deliver service to a global audience in multiple languages.

This multi-language capability allows users to make a request to ATRIA and receive back the response in their own language through a technology that automatically detects and adapts to the input language.

The multi-language feature provides multiple benefits:

The information provided by ATRIA is easier to understand, as it is generated in the user’s language.
A wide range of languages is supported, allowing ATRIA to reach a global audience.
The user experience is also optimized by reducing the need for external translation tools, making communication more seamless and natural.

From a technical point of view, the model for text identification and classification fastText is used, that supports more than 176 languages.

Functional overview

This feature is only available for RAG stages

A high-level overview on how the ATRIA multi-language feature works is included below.

A users sends a request to ATRIA in a specific language. ATRIA automatically detects the input language and sends the response back to the user in the same language.
In case the user’s request includes a mixture of languages (for example, “por favor, dame feedback”), ATRIA detects the predominant language of the query and uses it in the response.
In case ATRIA is not capable of identifying the request language, then the system generates the response in a language previously configured by default (that should be the region/country primary one).
The multi-language feature can be activated or deactivated by ATRIA constructors, as well as configured to meet their requirements and needs.

Technical guidelines

How constructors can configure ATRIA multi-language feature?

Constructors can configure this feature through different parameters of the prompt:

Best practices for ATRIA configuration: Use the multi-language feature

ATRIA server internal configuration

The ATRIA server configuration responsible for managing the multi-language feature includes these fields:

ATRIA default configuration: language identification fields

Docs:

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

Aura bridge blacklist numbers in WhatsApp

Description of the process for stoping call loops in numbers with autoreply activated in WhatsApp channel

Introduction

A call loop between two phone numbers occurs when both numbers have automated systems (such as voicemail, auto-reply or call-forwarding) that continuously trigger each other in response to calls. In this situation, each number responds to the other’s automatic actions, creating an endless cycle of calls back and forth.

aura-bridge manages a mechanism to stop call loops for numbers that have autoreply activated.

Configuration

The mechanism for stopping call loops is configured as follows:

The numbers with autoreply response must be identified and included in the aura-bridge environment variable AURA_BRIDGE_WA_BLACKLISTED_NUMBERS.
Afterwards, it is necessary to restart the pod for this configuration to be refreshed.
The Operations Team must remove the number from the list and reboot again, since it is a mechanism to stop the loop at a certain time. Otherwise, the list would grow exponentially and would not be programmatically viable.

Additionally to using this aura-bridge mechanism, a recommendation is to manage externally numbers with autoreply activated to limit them and consequently prevent call loops from ocurring.

When this configuration is set, if the from field of a message matches a number included in the blacklist, then aura-bridge avoids processing the message, thus preventing call loops.

Docs:

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

Aura entities processing

How Aura entities files are processed by aura-kpis-uploader and uploaded to Telefónica Kernel storage

Introduction

Currently, Aura entities processing is done both for CSV and Avro entities, that coexist in Aura.

These two processes are described in the following sections:

Aura entities processing

Aura entities processing for CSV files

Check Aura entities definition in CSV format here

aura-kpis-uploader-cli component aims to copy Aura’s entities files into Telefónica Kernel data storage.

It iterates all the folders where Aura servers store the entities files ( the aura-kpis container in the source Azure Storage account), copying them into the destination Azure Storage account (usually a Telefónica Kernel container).

Afterwards, the processed files are moved to the processed folder within the source container and, finally, the original files are removed.

sequenceDiagram
Title: Normal flow for a source component of Aura entities
    actor Cronjob
    participant uploadEntities
    participant processKPIS
    participant processBlobs
    participant processRemoteKPI
    participant StorageFileManager
    participant Azure Storage
    Cronjob ->> uploadEntities: Start process
    uploadEntities ->> processKPIS: Launch upload KPIS
    loop
      processKPIS ->> StorageFileManager: Get container client and blobs
      StorageFileManager ->> Azure Storage: 
      Azure Storage ->> StorageFileManager: OK
      StorageFileManager ->> processKPIS: OK
      processKPIS ->> processBlobs: Send all blobs to process
      processBlobs ->> processRemoteKPI: Filter and format blobs
      loop
        processRemoteKPI ->> StorageFileManager: Copy source blobs to destination container
        StorageFileManager ->> Azure Storage: 
        Azure Storage ->> StorageFileManager: OK
        StorageFileManager ->> processRemoteKPI: OK
        processRemoteKPI ->> StorageFileManager: Copy source blobs to source processed folder
        StorageFileManager ->> Azure Storage: 
        Azure Storage ->> StorageFileManager: OK
        StorageFileManager ->> processRemoteKPI: OK
        processRemoteKPI ->> StorageFileManager: Delete source blobs
        StorageFileManager ->> Azure Storage: 
        Azure Storage ->> StorageFileManager: OK
        StorageFileManager ->> processRemoteKPI: OK
      end
    end

The Adapter CSV entities definitions:

{
        "version": "1.0.0",
        "name": "E_Aura_BOT",
        "schema": "entity",
        "avroSchema": "",
        "source": {
            "data": "csv",
            "id": "BOT"
        },
        "targetType": "csv",
        "fields": {}
    },
    {
        "version": "1.0.0",
        "name": "E_Aura_CLF",
        "schema": "entity",
        "avroSchema": "",
        "source": {
            "data": "csv",
            "id": "CLF"
        },
        "targetType": "csv",
        "fields": {}
    },
    {
        "version": "1.0.0",
        "name": "E_Aura_GROOT",
        "schema": "entity",
        "avroSchema": "",
        "source": {
            "data": "csv",
            "id": "GROOT"
        },
        "targetType": "csv",
        "fields": {}
    },
    {
        "version": "1.0.0",
        "name": "E_Aura_NLP",
        "schema": "entity",
        "avroSchema": "",
        "source": {
            "data": "csv",
            "id": "NLP"
        },
        "targetType": "csv",
        "fields": {}
    }

Aura entities processing for AVRO files

Check Aura entities definition in Avro format here

There are two ways in which KPIs entities are created:

One is through a component, for example, aura-gateway-api generates its KPIs while it is running.
The other way is with the aura-kpis-uploader itself through the transformations of other KPIS already stored, for example AUDIT, which is generated through the aura-gateway-api count in AVRO format and through the aura-groot KPI, which is in CSV format.

When generating KPIS in AVRO for entities, it is not done in the default folder for each entity AURA_KPIS_ENTITIES_CONTAINER/avro/entity/<avro_schema: name>/<avro_schema: x-fp-version>, but a temporary folder named current is used: AURA_KPIS_ENTITIES_CONTAINER/avro/current/entity/<avro_schema: name>/<avro_schema: x-fp-version>. This is done to separate the files already generated from those currently being generated. When the KPIS Uploader is run, it moves the files that have already been generated to the default folder and converts them to BlockBlob.

aura-gateway-api Message Entity KPI

It generates a file with the following schema:

Aura Gateway API Schema Definition

First the CSV data must be transformed into avro format:

{
        "version":"1.0.1",
        "name": "Aura_Gateway_Message_converter",
        "stopWithErrors": true,
        "order": 1,
        "schema": "entity",
        "avroSchema": "aura-gateway-message-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "partialCsv",
            "id": "GATEWAY",
            "csvFolder": "gwapi",
            "entityName": "GATEWAYMESSAGE",
            "removeAfterProcessing": true
        },
        "targetType": "avro",
        "fields": {
                "MESSAGE_ID": {
                "sourceName": "MESSAGE_ID",
                "targetType": "string",
                "defaultValue": "NO_MESSAGE_ID"
            },
            "MESSAGE_TM": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_3_ALPHA_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "DAY_DT": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            },
            "AURA_NLP_IND": {
                "sourceName": "AURA_NLP_IND",
                "targetType": "boolean"
            },
            "CORR_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string",
                "defaultValue": "NO_CORR_ID"
            }
        }
    }

The next adapter process the Gateway from current folder to entity destination folder.

{
        "version": "1.0.0",
        "name": "Aura_Gateway_Message",
        "schema": "entity",
        "avroSchema": "aura-gateway-message-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "GATEWAY"
        },
        "targetType": "avro",
        "fields": {}
    }

AUDIT Entity KPI

It generates a file with the following schema: Audit Schema Definition

The Adapters format is shown below:

From current folder to entity destination folder:

    {
        "version": "1.0.0",
        "name": "Aura_Audit",
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "object",
            "id": "AUDIT",
            "useDefaultTimeFilter": true
        },
        "targetType": "avro",
        "fields": {}
    }

From aura-gateway-api Message Entity KPI:

 {
        "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "avro",
            "id": "AUDIT",
            "avroSchema": "aura-gateway-message-asvc.json",
            "avroSchemaVersion": "6.0.0"
        },
        "targetType": "avro",
        "fields": {
            "INTERACTION_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string"
            },
            "AURA_TM": {
                "sourceName": "MESSAGE_TM",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_CHANNEL_ID": {
                "sourceName": "AURA_CHANNEL_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_3_ALPHA_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_SERVICE_NAME_CD": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "defaultValue": "nlpaas",
                "valueIfExist" : "ai"
            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_COMPONENT_ID": {
                "sourceName": "AURA_COMPONENT_ID",
                "targetType": "string"
            },
            "AURA_COMPONENT_HOST_ID": {
                "sourceName": "AURA_COMPONENT_HOST_ID",
                "targetType": "string"
            },
            "AURA_VERSION_ID": {
                "sourceName": "AURA_VERSION_ID",
                "targetType": "string"
            },
            "DAY_DT": {
                "sourceName": "DAY_DT",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            }
        }
    }

From aura-groot Message Entity KPI:

{
        "version": "1.0.0",
        "name": "Aura_Audit",
        "stopWithErrors": true,
        "schema": "entity",
        "avroSchema": "aura-audit-asvc.json",
        "versionSchema": "6.0.0",
        "source": {
            "data": "partialCsv",
            "id": "AUDIT",
            "csvFolder": "groot",
            "entityName":"GROOTMESSAGE"
        },
        "targetType": "avro",
        "fields": {
            "INTERACTION_ID": {
                "sourceName": "CORR_ID",
                "targetType": "string"
            },
            "AURA_TM": {
                "sourceName": "MSG_DT",
                "targetType": "string",
                "preCalculated": "DATE_ISO_8691"
            },
            "AURA_CHANNEL_ID": {
                "sourceName": "CHANNEL_ID",
                "targetType": "string",
                  "nullable": "true"
            },
            "AURA_APP_ID": {
                "sourceName": "AURA_APP_ID",
                "targetType": "string",
                "nullable": "true"
            },
            "COUNTRY_3_ALPHA_CD": {
                "sourceName": "COUNTRY_CD",
                "targetType": "string",
                "preCalculated": "COUNTRY_ISO_3166_ALPHA_3"
            },
            "AURA_SERVICE_NAME_CD": {
                "sourceName": "AURA_SERVICE_NAME_CD",
                "targetType": "string",
                "defaultValue": "message"

            },
            "AURA_PRESET_NAME": {
                "sourceName": "AURA_PRESET_NAME",
                "targetType": "string",
                "nullable": "true"
            },
            "AURA_COMPONENT_ID": {
                "sourceName": "AURA_COMPONENT_ID",
                "targetType": "string"
            },
            "AURA_COMPONENT_HOST_ID": {
                "sourceName": "AURA_COMPONENT_HOST_ID",
                "targetType": "string"
            },
            "AURA_VERSION_ID": {
                "sourceName": "VERSION_ID",
                "targetType": "string"
            },
            "DAY_DT": {
                "sourceName": "MSG_DT",
                "targetType": "string",
                "preCalculated": "CUSTOM_DATE_FORMAT",
                "format": "YYYY-MM-DD"
            },
            "BRAND_ID": {
                "sourceName": "BRAND_ID",
                "targetType": "string"
            }
        }
    }

Docs:

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

Aura bridge functionalities

Description of the main functionalities carried by Aura bridge and the different processes that can be executed for its management

The current documents describe the main functionalities of aura-bridge and processes that can be carried out over it:

Actions managed by redirect command: Certain actions can be performed by aura-bridge through the redirect command, that manages messages from aura-groot.
Response messages synchronization: Description of the process for the synchronization of the user’s messages executed by aura-bridge.
Managing payload information: aura-bridge adds relevant information in communication with aura-groot through a field called payLoad, within the root channelData field of the activity.
Aura Bridge supports several WhatsApp numbers: functionality that allows Aura bridge to support several numbers in WhatsApp channel.
Errors management by Aura bridge: aura-bridge has to manage errors for different sources such as aura-groot, Kernel, WhatsApp, etc.
Aura bridge events management: aura-bridge can emit and listen to events through a centralized service.
Aura bridge channelData v3 configuration: aura-bridge configuration to communicate with aura-bot using channelData v3 for WhatsApp channels.
Aura bridge make-up process: the make-up process, that includes a set of operations to prepare an environment once a module has been deployed, must always be executed to correctly start aura-bridge component.
Management of list options for WA channel: Aura is able to use list messages in WhatsApp graphical interface. This interactive component is managed by aura-bridge.

Docs:

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

Aura Groot operational flows

Description of aura-groot main operational flows

Introduction

The current document includes the main operational flows in the aura-groot component.

Blocked skill

This flow describes the control of the messages received by aura-groot from the skill and the sending of the error message to the user in case the skill does not respond.

sequenceDiagram
title: BLOCKED-SKILL

    actor Channel
    participant AuraGroot #ebdff7
    participant AuraBot #ebdff7

    Channel ->> AuraGroot: request message1
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraBot: request message1
    AuraBot -->> AuraGroot: response message1
    AuraGroot ->> AuraGroot: delete timeout, update targetSkill
    AuraGroot -->> Channel: response message1
    AuraBot -->> AuraGroot: response endOfConversation
    AuraGroot ->> AuraGroot: delete targetSkill

    Channel ->> AuraGroot: request message2
    AuraGroot ->> AuraGroot: create skillConversation2, begin timeout in targetSkill
    AuraGroot ->> AuraBot: request message2
    Channel -->> AuraGroot: request message3
    AuraGroot ->> AuraGroot: control timeout (active targetSkill)

    alt timeout targetSkill < TIMEOUT
        AuraGroot ->> AuraBot: request message3
        AuraBot -->> AuraGroot: response message2
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message2

        AuraBot -->> AuraGroot: response message3
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message3
        AuraBot -->> AuraGroot: response endOfConversation message2
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraBot -->> AuraGroot: response endOfConversation message3
        AuraGroot ->> AuraGroot: discard endOfConversation in conversation2
    end

    alt timeout targetSkill > TIMEOUT
        AuraGroot -->> Channel: Error
        AuraGroot ->> AuraGroot: begin timeout, in targetSkill
        AuraGroot ->> AuraBot: request message3
        AuraBot -->> AuraGroot: response message2
        AuraGroot ->> AuraGroot: delete timeout, update targetSkill
        AuraGroot -->> Channel: response message2
        AuraBot -->> AuraGroot: response endOfConversation message2
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraBot -->> AuraGroot: response message3
        AuraGroot ->> AuraGroot: discard delete timeout in targetSkill
        AuraGroot -->> Channel: response message3
        AuraBot -->> AuraGroot: response endOfConversation message3
        AuraGroot ->> AuraGroot: discard endOfConversation in targetSkill
    end

Use case with asynchronous calls

This diagram describes the flow of a user’s request that is resolved through a dialog with asynchronous calls.

Further information regarding how asynchronous APIs are handled by Aura can be found in the Guidelines for building a dialog that uses async APIs.

sequenceDiagram
title: MESSAGE_ASYNC_USECASE
    actor User
    User ->> WA: User request
    WA ->> 4P: User request
    4P ->> AuraBridge: User request
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: User request
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraSkill: User request
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> AuraSkill: basic whatsapp flow
    AuraSkill ->> LocalDialog: message
    LocalDialog ->> 4P: request async + callback bridge
    4P ->> LocalDialog: 200 OK
    Note right of 4P: when 4p finishes the request sends the response to the indicated callback (AuraBridge)
    4P ->> AuraBridge: response request async
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: response request async
    AuraGroot ->> AuraBridge: 200 OK
    Note right of AuraBridge: the response is sent as payload
    AuraGroot ->> AuraGroot: control timeout
    alt targetSkill.timeout < TIMEOUT
        AuraGroot ->> AuraSkill: response request async
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> LocalDialog: response request async
        LocalDialog ->> LocalDialog: process response
        LocalDialog ->> AuraSkill: response processing
        AuraSkill ->> AuraGroot: async response processed
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation1
        AuraGroot ->> AuraBridge: async response processed
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async response processed
        4P ->> AuraBridge: 200 OK
        4P ->> WA: async response processed
        WA ->> User: async response processed
    else
        AuraGroot ->> AuraBridge: error
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async error
        4P ->> AuraBridge: 200 OK
        4P ->> WA: error
        WA ->> User: error
        AuraGroot -> AuraSkill: request async endOfConversation
        AuraGroot -> AuraGroot: delete skillConversation1
        AuraGroot -> AuraGroot: create skillConversation2, begin timeout in targetSkill
        AuraGroot ->> AuraSkill: response request async
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> AuraSkill: Not recognize
        AuraSkill ->> AuraGroot: none
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation2
        AuraGroot ->> AuraBridge: none
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: none
        4P ->> AuraBridge: 200 OK
        4P ->> WA: none
        WA ->> User: none
    end

Use case with files sending by the user

This diagram describes the flow of a use case that includes sending a file by the user (WhatsApp channel).

Further information regarding how to receive a file from the user can be found in:

sequenceDiagram
title: MESSAGE_FILE_USECASE
    User ->> WA: Phrase to init UC file dialog
    WA ->> 4P: Phrase to init UC file dialog
    4P ->> AuraBridge:Phrase to init UC file dialog
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: Phrase to init UC file dialog
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
    AuraGroot ->> AuraSkill: Phrase to init UC file dialog
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> AuraSkill: Basic whatsapp flow for authenticated user
    AuraSkill ->> FileDialog: Start UC file dialog
    FileDialog ->> AuraSkill: Send me a file
    AuraSkill ->> AuraGroot:  Send me a file
    AuraGroot ->> AuraSkill: 200 OK
    AuraGroot ->> AuraGroot: delete timeout in targetSkill
    AuraGroot ->> AuraBridge: Send me a file
    AuraBridge ->> AuraGroot: 200 OK
    AuraBridge ->> 4P: Send me a file
    4P ->> AuraBridge: 200 OK
    4P ->> WA: Send a file
    WA ->> User: Send a file
    User ->> WA: Send the attachment
    WA ->> 4P: Send the attachment
    4P ->> AuraBridge: Send the attachment
    AuraBridge ->> 4P: 200 OK
    AuraBridge ->> AuraGroot: Send the attachment
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraSkill: Send the attachment
    AuraSkill ->> AuraGroot: 200 OK
    AuraSkill ->> FileApi: Validate / process the attachment
    FileApi ->> AuraBot: 200 OK
    FileApi ->> AuraBridge: Attachment processed, validated and ready (async-callback)
    AuraBridge ->> FileApi: 200 OK
    AuraBridge ->> AuraGroot: Send attachment processed
    AuraGroot ->> AuraBridge: 200 OK
    AuraGroot ->> AuraGroot: control timeout
    Note right of AuraSkill: we could control that it is a system message, but the case would be the same if a message from the user arrives before the asynchronous response
    alt targetSkill.timeout < TIMEOUT
        AuraGroot ->> AuraSkill: Send attachment processed
        AuraSkill ->> AuraGroot: 200 OK
        AuraGroot ->> FileDialog: Send attachment processed
        FileDialog ->> FileDialog: process attachment
        FileDialog ->> AuraSkill: response processed attachment
        AuraSkill ->> AuraGroot: response processed attachment
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation1
        AuraGroot ->> AuraBridge: response processed attachment
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: response processed attachment
        4P ->> AuraBridge: 200 OK
        4P ->> WA: response processed attachment
        WA ->> User: response processed attachment
    else
        AuraGroot ->> AuraBridge: error
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: async error
        4P ->> AuraBridge: 200 OK
        4P ->> WA: error
        WA ->> User: error
        AuraGroot -> AuraSkill: request endOfConversation
        AuraGroot -> AuraGroot: delete skillConversation1
        AuraGroot -> AuraGroot: create skillConversation2, begin timeout in targetSkill
        AuraGroot ->> AuraSkill: response processed attachment
        AuraSkill ->> AuraGroot: 200 OK
        AuraSkill ->> AuraSkill: UnexpectedFile
        AuraSkill ->> AuraGroot: UnexpectedFile
        AuraSkill ->> AuraGroot: response endOfConversation
        AuraGroot ->> AuraSkill: 200 OK
        AuraGroot ->> AuraGroot: delete targetSkill
        AuraGroot ->> AuraGroot: delete skillConversation2
        AuraGroot ->> AuraBridge: UnexpectedFile
        AuraBridge ->> AuraGroot: 200 OK
        AuraBridge ->> 4P: UnexpectedFile
        4P ->> AuraBridge: 200 OK
        4P ->> WA: UnexpectedFile
        WA ->> User: UnexpectedFile
    end

Handover use case

This diagram describes the flow of the handover use case.

Further information regarding about handover use case handover-genesys dialog.

sequenceDiagram

title: handover
actor Channel
participant Bridge #ebdff7
participant AuraGroot #ebdff7
participant AuraBot #ebdff7
participant Genesys #ebdff7

Channel ->> AuraGroot: request message1
AuraGroot ->> AuraGroot: create skillConversation1, begin timeout in targetSkill
AuraGroot ->> AuraBot: request message1
AuraBot -->> AuraGroot: response message1
AuraGroot ->> AuraGroot: delete timeout in targetSkill
AuraGroot -->> Channel: response message1
AuraBot -->> AuraGroot: response endOfConversation
AuraGroot ->> AuraGroot: delete targetSkill
AuraBot ->> Genesys: request chat "init"
Genesys ->> AuraBot: response chat "init"
AuraBot ->> Genesys: message history
Genesys ->> AuraBot: response message history
Genesys -->> Bridge: pushNotification: starter messages with genesys

Bridge ->> AuraGroot: request message2
AuraGroot ->> AuraGroot: create skillConversation2, begin timeout in targetSkill
AuraGroot ->> AuraBot: request message2
AuraBot -->> AuraGroot: response message2
AuraGroot ->> AuraGroot: delete timeout in targetSkill
AuraGroot -->> Bridge: response message2
Bridge -->> Channel: response message2
AuraBot -->> AuraGroot: response endOfConversation
AuraGroot ->> AuraGroot: delete targetSkill

Docs:

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

Aura Bot processes

Description of the main functionalities carried by Aura Bot and the different processes that can be executed for its management

The main functionalities in charge of aura-bot as Aura’s neuronal network are listed below:

Aura users’ sign up:
Different ways of registering users in Aura, depending on the channel. Find detailed information in channel authentication.
Aura authentication validation process Aura supports different types of users, each of them with access to specific services and use cases: authenticated users and anonymous users. The authentication process carried out by aura-bot is fully explained in Users authentication.
Aura conversational process aura-bot is in charge of managing the conversational flow with the user, from receiving her request and understand it to fetch the required data to compose the most appropriate response and provide it back to the user. Find detailed information in Aura conversational flow.

Apart from these core tasks in Aura’s performance, there are other processes that can be executed over aura-bot in order to customize it or access to different components.

channelData management

Docs:

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

Aura bridge supports several WhatsApp numbers

Description of the process for the configuration of Aura, so Aura bridge can support several WhatsApp channels

Introduction

aura-bridge is able to support different WhatsApp numbers, treating each of them as a different Aura channel. For example, it will be possible to have several numbers at the same time and with the support of the same bridge.

From Aura’s point of view, we would consider these numbers as different channels: they can be configured to all intents and purposes as different channels.

Communication flow

Request flow of a message to aura-groot from a web container or native app:

sequenceDiagram

whatsapp ->> Kernel: 1002 request
whatsapp ->> Kernel: 1004 request
Kernel ->> bridge: request + apiKey + channelId
Note right of bridge: get openId data for this channelId
bridge ->> aura: request + channelId
aura ->> bridge: response + channelId
bridge ->> Kernel: response + accessToken
Kernel ->> whatsapp: response to 1002
Kernel ->> whatsapp: response to 1004

Properties of the channel

The WhatsApp channel must have the following fields in its configuration, defined in the WhatsApp client model, within Aura channel model:

"channel_id": "<channel_id>",     // Contains the UUID that identifies the channel univocally in Aura.
...,
"whatsapp": {
    "client": {
        "id": "<id>",             // authorization ID with Kernel whatsapp client.
        "secret": "<secret>",     // authorization secret with Kernel whatsapp client
        "purposes": "<purposes>", // authorization purposes with Kernel whatsapp client
        "scopes": "<scopes>"      // authorization scopes with Kernel whatsapp client
    }
},
....

Set the webhook

The last step is to tell Kernel which is the callback of the service where Aura will process the WhatsApp requests. So, in this case, we must set as webhook the WhatsApp messages endpoint of aura-bridge.

An example request is shown below:

# substitute <aura-services-domain> with the domain of your environment, usually something like svc-es-pro
# substitute <api-key> with an APIKey generated
# substitute <channelId> with an whatsapp channel identifier

$ curl -i -X PATCH -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' -H 'x-correlator: $CORRELATOR' 'https://api.global-int-current.baikalplatform.com/whatsapp/v1/settings/webhook' -d '{"webhooks": {"url": "https://<aura-services-domain>.auracognitive.com/aura-services/v1/whatsapp/messages?apikey=<api_key>&channelId=<channel_id>"}}'

HTTP/2 201
{"webhooks": {"url": "https://<aura-services-domain>.auracognitive.com/aura-services/v1/whatsapp/messages?apikey=<api_key>&channelId=<channel_id>"}}

It is not needed that the endpoint is up and running to set it as webhook.

Further information of Kernel APIs for WhatsApp: https://developers.baikalplatform.com/apis/whatsapp/1.0.0/#operation/Update-Webhooks

Detailed information for WhatsApp activation.

Docs:

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

Terms and Conditions

Description of Terms and Conditions handled in Aura Bot Platform

Terms and conditions flow

When a user message arrives, the first step in authentication is to check if it is in cache. In case that it is not found, Terms & Conditions API is checked and if the user does not exist or has a pending status, it is redirected to T&C dialog.

Obviously, all the users with accepted status continue with the normal flow. In the Terms and Conditions dialog a record with status pending is stored in the T&C API if does not exist yet and the terms and conditions prompt is shown. If the user accepts, the status accepted is set in T&C API.

Anonymous and authenticated users have different T&C, so if both are configured, users should accept T&C twice: after the first message as anonymous and after the authentication.

Terms and conditions settings

Terms and Conditions settings

In Aura channel model, T&C are set in the termsAndConditionsconfiguration model. It is added to channels who need to enable this feature.

There are two fields with different configurations inside: authenticated and anonymous. Each of these settings will be used according to the type of user. It defines the version and service used in T&C API.

{
  "channel_id": "f7fd1021-41cd-588a-a461-387cc24be223",
  "name": "whatsapp",
  "termsAndConditions": {
    "authenticated": {
      "version": "1",
      "service": "whatsappAuth"
    },
    "anonymous": {
      "version": "1",
      "service": "whatsappAnonymous"
    }
  }
}

Docs:

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

Aura Bot object, data types and models

Description of the different types of data and models supported by Aura Bot

aura-bot supports several data models, compatible with different languages or structures in order to execute the conversational flow.

The current document includes the description of the different models supported by Aura Bot platform, currently:

auraCommand model
The use of auraCommands, that is, pre-defined options that the user can select from Aura’s interface, is managed by the auraCommand model.

dialogContext model
Aura supports the dialogContext model, a structure that facilitates the recognition of CardActions and prompts without the need of training.

Aura API Key
Aura counts on API Keys to connect to available API endpoints. They are based on an encrypted APIKey data model, which is included in aura-validate-apikey utility.

Docs:

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

Create and configure an agent

Guidelines for the configuration of ATRIA by use cases constructors when developing an experience by means of an agent

Introduction

An agent is a configuration entity in ATRIA that represents an integration point for external channels, services, or platforms.

Each agent defines how ATRIA communicates with and manages sessions for a specific external system, specifying connection details, session parameters, and operational metadata.

Agents are referenced by applications to enable channel or service connectivity within the platform.

Guidelines to configure an agent

1. Create a new agent

Build the agent for your use case (json file), using the available agent fields.

When the agent json file is generated, execute this command to include it:

curl --location --request POST 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data-raw '<NEW AGENT JSON>'

1.1. Modify/update an agent

If once created, certain modifications are required, follow these instructions:

Make the required changes in the agent json file using the available agent fields.

When the agent is modified, execute this command to update it:

curl --location --request PUT 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentID>' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '<AGENT JSON WITH MODIFICATIONS>'

1.2. Delete an agent

Execute the following command:

curl --location --request DELETE 'https://svc-<env>.auracognitive.com/aura-services/v2/configuration/agents/<agentId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX'

2. Include the agent in the application

If the application for your use case does not exist, first create it following the guidelines for the configuration of an application.

Once the application is created, assign the created agent in the field agents.

If you update or delete an agent, ensure that any application referencing it is also updated accordingly.
Remember that agents must exist to be inserted in an application.

Example to update the list of agents in an application:

curl --location --request PATCH 'https://svc-<env>.auracognitive.com/aura-services/v1/applications/<applicationId>' \
  --header 'Accept: application/json' \
  --header 'Authorization: APIKEY XXX' \
  --data '{
    "id": "<applicationId>",
    "agents": [
      "<agentId1>",
      "<agentId2>"
    ]
  }'

Agent fields

The fields for the characterization of an agent are summarized below, as defined in the API swagger Aura Configuration ATRIA Agents:

Field	Type	Mandatory	Description
`id`	string	Yes	Unique identifier (UUID) for the agent.
`name`	string	Yes	Name that uniquely identifies the agent in Aura.
`description`	string	No	Description of the agent.
`communication`	object	Yes	Parameters for the configuration of the communication flow. See communication configuration.
`flowConfig`	object	No	Configuration of the agent flow.
`deploymentName`	string	No	Name of the deployment where the agent is running. If the `endpoint` field is not present in `communication`, this field will be used to route requests to the agent.
`metadata`	object	No	Document metadata (version, createdAt, updatedAt, etc). See metadata.

Communication configuration (`communication`)

Field	Type	Mandatory	Description
`communicationType`	string	Yes	Type of communication. Only `http` is currently supported.
`endpoint`	string	No	HTTP endpoint where the agent listens.
`headers`	object	No	HTTP headers associated with the agent.
`timeout`	number	No	Timeout for agent communication.
`retries`	number	No	Number of retries for communication.

Metadata (`metadata`)

Field	Type	Mandatory	Description
`version`	string	No	Configuration version when the document was created.
`createdAt`	string	No	Creation date (ISO 8601).
`updatedAt`	string	No	Last update date (ISO 8601).

Example: Minimal agent configuration

{
  "id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "name": "example-agent",
  "communication": {
    "communicationType": "http",
    "endpoint": "https://agent.example.com/webhook"
  }
}

Example: Full agent configuration

{
  "id": "b1e2c3d4-5678-1234-9abc-def012345678",
  "name": "example-agent",
  "description": "Agent for integration with Example Service",
  "communication": {
    "communicationType": "http",
    "endpoint": "https://agent.example.com/webhook",
    "headers": {
      "Authorization": "Bearer <token>"
    },
    "timeout": 30,
    "retries": 3
  },
  "flowConfig": {},
  "deploymentName": "example-deployment",
  "metadata": {
    "version": "1.0.0",
    "createdAt": "2024-05-30T10:00:00Z",
    "updatedAt": "2024-05-30T12:00:00Z"
  }
}

Note:

The id, name, and communication fields are mandatory.

The communicationType must be http.

If an agent is deleted, applications referencing it will be updated.

Docs:

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

Errors handled by Aura bridge

Description of how Aura bridge manages errors coming from different sources

Introduction

aura-bridge has to manage errors for different sources such as aura-groot, Kernel, WhatsApp, etc.

Management of Kernel errors

If a request to Kernel fails, aura-bridge receives a direct response error.

There are two error types:

Recoverable: aura-bridge enqueues the message and tries to resend the message later.
Unrecoverable: aura-bridge removes the message.

In both cases, aura-bridge cannot inform about the error to the user and must send an event to aura-groot, in order to record the KPIs.

@startuml
title Kernel error

Actor User
participant AuraBridge
participant AuraGroot
participant Kernel_Whatsapp


User -> AuraBridge: user message
AuraBridge -> AuraGroot: send user message
AuraGroot -> AuraBridge: replay with activity
AuraBridge -> Kernel_Whatsapp: send message from activity
Kernel_Whatsapp -> AuraBridge: response error
AuraBridge -> AuraGroot: send event for kpis
    alt error is unrecoverable
        AuraBridge -> AuraBridge: remove message from activity
    end
    alt error is recoverable
       loop For numRetries
            AuraBridge -> Kernel_Whatsapp: send message from activity
        end
    end
@enduml

Management of WhatsApp errors

If WhatsApp reports an error to Kernel, then Kernel sends the bridge a message with the errors.

There are two error types:

Recoverable: aura-bridge enqueues the message and tries to resend the message later.
Unrecoverable: aura-bridge removes the message and informs about it to the user.

In both cases, aura-bridge sends an event to aura-groot, in order to record the KPIs.

@startuml
title Error Whatsapp

Actor User
participant AuraBridge
participant AuraGroot
participant Kernel
participant Whatsapp


User -> AuraBridge: user message
AuraBridge -> AuraGroot: send user message
AuraGroot -> AuraBridge: replay with activity
AuraBridge -> Kernel  : send message from activity
Kernel -> Whatsapp: send message from activity
Whatsapp -> Kernel: response error
Kernel -> AuraBridge: response error
AuraBridge -> AuraGroot: send event for kpis
    alt error is unrecoverable
        AuraBridge -> User: send error message for user
        AuraBridge -> AuraBridge: remove message from activity
    end
    alt error is recoverable
       loop For numRetries
            AuraBridge -> Kernel: send message from activity
        end
    end
@enduml

Management of rendering errors

It occurs when the transformation from aura-groot activity to WhatsApp message fails.

aura-bridge sends an event to aura-groot, in order to record the KPIs and informs about error to the user.

@startuml
title Rendering error

Actor User
participant AuraBridge
participant AuraGroot
participant Kernel_Whatsapp


User -> AuraBridge: user message
AuraBridge -> AuraGroot: send user message
AuraGroot -> AuraBridge: replay with activity
alt rendering fails
    AuraBridge -> AuraBridge: render bot activity to whatsapp message
end
AuraBridge -> AuraGroot: send event for kpis
AuraBridge -> User: send error message for user
@enduml

Docs:

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

Generative feedback functional description

Discover the feedback functionality that can be used for Generative AI and RAG capabilities

If you are interested in the detailed technical operational flow of this capability, that includes the sequence diagram of interactions between components, access here

Introduction

Within the use of the ATRIA AI-driven Generative AI or RAG capabilities, we have developed a feedback functionality.

This feedback functionality allows the estimation of the user’s satisfaction regarding the obtained response.

The user can provide feedback by clicking on a thumbs-up icon if the quality and appropriateness of the answer is correct or selecting the thumbs-down icon if the response misses the point, contains hallucinations, or is unclear.

Functional operation

The underlying process is summarized in the following lines and schematically shown in the figure below:

An application sends a request to aura-gateway-api generative with a correlator.
Firstly, it passes through Kernel (Telefónica Digital Ecosystem) for authentication and security purposes.
aura-gateway-api processes the received request and sends the request to the auto-generative content generator atria-model-gateway to obtain an appropriate response.
atria-model-gateway generates the most appropriate response and sends it back to aura-gateway-api.
aura-gateway-api sends the response back to the service that initiated the request with the same correlator and a session identifier.
An application sends a request to aura-gateway-api feedback with:
- A new header correlator
- The sessionId received in the path
- The field msg_corrid, in the body, that indicates the correlator of the message the feedback is about.
aura-gateway-api processes the received request and communicates with atria-model-gateway to send this request.
atria-model-gateway stores the feedback.
aura-gateway-api communicates a 204 to the application.

Docs:

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

Introduction to skills

The current document includes an overview of Aura skills and general information regarding these components.

Moreover, it includes links to low-level technical documentation for highly-skilled technicians.

Introduction

Skills are bots able to perform a specific function or capability in a coordinated and efficient manner designed to handle particular tasks or provide information on a focused topic.

In Aura Virtual Assistant, skills can communicate with Aura Root.

In Aura Virtual Assistant, skills are bots based on Microsoft skills protocol or can be external bots built with any technology available on the market.

In any case, currently they are domain bots, each of them able to manage a different type of request from the user. Therefore, each skill will contain the use cases corresponding to its domain.

Skills can communicate with Aura Root to receive a user’s request and resolve it, to provide the user with the most accurate answer or service and can be trained (each skill will invoke Aura Cognitive Services) and deployed independently.

Types of skills

Within Aura, there are three different types of skills:

Skills developed over Aura cluster

They are proprietary skills that follow Microsoft Bot Framework Direct Line protocol.

Currently, aura-bot is a skill itself.

Skills developed outside Aura cluster with Microsoft-compatible technologies

These skills are developed outside Aura with a technology compatible with Microsoft Bot Framework (Composer, etc.).

Third-party bots, developed with other technologies

They are bots developed with other technologies different from Microsoft ones (Google Assistant, Teneo, etc.).

They require an adapter for its communication with Aura Root.

These third-party adapters are skills that must be developed by the OBs willing to connect their external bots with Aura Root.

Aura Bot as a skill

In the current phase of development of Aura Virtual Assistant, aura-bot is a skill itself but, in general terms, it behaves the same way as in the previous architecture.

Currently, all the existing use cases are placed in aura-bot skill in order to assure backward compatibility, excepting Germany, that has migrated its use cases to an external bot.

Due to the migration of aura-bot component to a skill, certain components have suffered from modifications to be adapted to it and other ones have moved to aura-groot. For example: aura-bot-adapter now extends the Microsoft Bot Framework class cloudAdapter.

Find comprehensive documentation here: Aura Bot as a skill

Skills technical documentation

Are you a highly-skilled technician?
Do you need low-level technical documentation regarding skills?

Access these documents:

Manage skills

Docs:

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

Event management by Aura bridge

Description of how the aura-bridge can emit and listen to events through a centralized service.

Introduction

aura-bridge can emit and listen to events using the AuraBridgeEventService class. This service extends directly from EventEmitter, so any method of this class is available.

How to activate the event service?

The BRIDGE_EVENT_SERVICE_ACTIVE environment variable sets whether or not the event service will be active.

It is possible to continue using the event service even if it is not active. The code will compile and will not produce any errors on execution, but no events will be emitted or received.

Using the event service in a plugin

As for any other service that is necessary in an aura-bridge plugin, it must be added in the plugin configuration:

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

Emitting events

To emit an event when an important action must be notified, you can use the emit method:

Services.eventService.emit(WhatsappEvent.AckMessageReceived, eventData);

The events that a plugin emits must be defined in the events field of the service provided by the plugin.

export = registerPlugin([
    {
        type: PluginType.Processor,
        name: 'whatsappIncommingProcessor',
        events: [
            // Event emitted when a new ack message is received.
            WhatsappEvent.AckMessageReceived
        ]
        // ...
    }
]);

Listening for events

Once the event service is injected into the plugin, we can listen for events of a specific type using the on method:

Services.eventService.on(WhatsappEvent.AckMessageReceived, async () => {
    // process event here
});

⚠️ Check the BRIDGE_EVENT_SERVICE_ACTIVE variable if you are not receiving events

Docs:

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

Bridge channelData v3 configuration

Description of how the aura-bridge can be configured to communicate with aura-bot using channelData v3 for WhatsApp channels

Introduction

aura-bridge can handle WhatsApp messages and send them to aura-groot using channelData v2 and channelData v3. The version to be used will depend on the configuration of the channel.

How to configure a specific channel to use channelData V3

To configure a channel to use channelData v3, you should set the variable defaultDirectlineVersion to true in the channel:

{
    "id": "888888-8888-8888-8888-8888888888",
    "name": "whatsapp",
    "prefix": "wa",
    "responseOptions": {
        .
        .
        .
        "versions": {
            "v2": {
                "singleMessage": true
            },
            "v3": {
                "singleMessage": true,
                "defaultDirectlineVersion": true
            }
        },
        "needsEmptyResponseEvent": true
    },
    "type": "whatsapp",
    .
    .
    .
}

How to configure all channels to use channelData V3

On the contrary, if you want to configure at once all the WhatsApp channels to use channelData v3, you should set the following aura-bridge environment variable AURA_WHATSAPP_DIRECTLINE_DEFAULT_VERSION to 3.

Also with this configuration, you can configure any of the channels to use channelData v2 using the defaultDirectlineVersion flag, as seen previously.