Aura – application

Docs:

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

ATRIA application

Definition and role of applications in ATRIA

Introduction

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

ATRIA application

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

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

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

How to configure an application

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

Example of application

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

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

Applications model

Common fields

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

NLPaaS fields

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

Generative/RAG fields

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

Docs:

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

Guidelines for the configuration of an application

Comprehensive instructions for the configuration of an application to communicate with aura-gateway-api

Introduction

Prior to the development of a use case that needs aura-gateway-api to connect with an external service, the configuration of an application is required to set the specific parameters of the ATRIA AI-driven capability to be used.

Additionally, if certain changes must be made on an existing application through a hot swapping process, follow the guidelines Hot swapping of Aura applications configuration

Guidelines to create and configure an application

The creation of an application requires the following steps:

Create a task for the configuration of an application in JIRA.
Copy the tables below and paste them into the JIRA task.
Fill in all the fields corresponding to your specific ATRIA capability in the table’s column “Value in app”.
Do not modify the content of the remaining columns aside from “Value in app”.
The application must be available in the applications list of the environment, which is available through the aura-configuration-api server.
The edited sheet will serve as the basis for the subsequent validation of the application by Aura Global Team and its uploading to the system.

Mandatory parameters: parameter_name
Optional parameters: parameter_name

Application basic data

Parameter	Definition	Type	Value in app
disabled	Boolean value to enable or disable the application. By default: `false`	Boolean	complete
id	Unique application identifier	UUID	complete
name	Unique application name	String	complete
brand	Identifier of the Telefónica Brand associated to the application. Available values in the document Telefónica brands management	String	complete
nlp	Parameters to use the NLP as a Service capability Mandatory for using this capability	N/A	Go to NLP as a Service section
models	Parameters to use the Generative AI capability or RAG capability Mandatory for using these capabilities	N/A	Go to Using Generative AI / RAG section
agents	Identifiers of the agents associated with the application. Mandatory if the application requires integration with agents.	String[]	complete

Using NLP as a Service: nlp parameter

The use of the NLP as a Service capability by a channel requires the previous registration of the channel in Aura using the channels registration template.

Parameter	Definition	Type	Value in app
channelId	Identifier of the channel willing to use NLP as a Service	String	complete

Using Generative AI / RAG: models parameter

The use of Generative AI or RAG capabilities by applications requires the definition of the following parameters:

Parameter	Definition	Type
level	. It indicates if level application in atria-model-gateway, meaning that it has specific access and control privileges. . Default value `user`	String
presets	. Include here all the presets (configurable entities that define the instructions to work with the AI model for the resolution of a use case) that will be assigned to this application. . For this purpose, follow the guidelines to include a preset in the application . Take into account that a preset must be previously created in ATRIA	String[]

Docs:

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

Hot swapping of Aura applications configuration

Guidelines to execute modifications in Aura applications configuration through a hot swapping process

Prerequisites

The URL of aura-configuration-api must have the following format: https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration where:
- {{aura-services-domain}} should be svc-[country]-[environment], for instance svc-es-pre
Recommended:
- kubectl installed in your local host.
- curl installed in your local host.
- jq installed in your local host.

Access Aura Configuration API

Get the APIKey

First, we must get the APIKey, AURA_AUTHORIZATION_HEADER, of aura-configuration-api. For this purpose, follow these steps:

Execute the following command:

# substitute {{aura-environment}} with the environment you're configuring
export AURA_ENVIRONMENT={{aura-environment}}

$ kubectl -n $AURA_ENVIRONMENT get secret aura-configuration-api -o json | jq -r ".data.AURA_AUTHORIZATION_HEADER|@base64d

Copy the value of APIKey.

Update the application configuration

To update the configuration of an application, we must make a patch to the aura-configuration-api indicating the application that we want to modify and the new value:

Execute the next curl to update configuration:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment, svc-[country]-[environment].
# substitute {{applicationId}} with the value of application to change
# substitute {{apikey}} with the value of APIKey get in the previous step
$ curl --location --request PATCH 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/applications/{{applicationId}}' \
--header 'correlator: {{correlator}}' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}' \
--data-raw '{
    "id": "{{applicationId}}",
     // Send the object to update
    }
}'

Check the change through the following request:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
# substitute aura-services-domain with the specific information for environment svc-[country]-[environment].
# substitute {{applicationId}} with the value of application to change
# substitute {{apikey}} with the value of APIKey get in the previous step
# The response will be the application configuration.
$ curl --location --request GET 'https://{{aura-services-domain}}.auracognitive.com/aura-services/v2/configuration/applications/{{applicationId}}' \
--header 'correlator: {{correlator}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{apikey}}'

ℹ️ NOTE: The config-watcher runs periodically (every 5 minutes) and when it detects that the application configuration has been modified, it will restart the pods.

Docs:

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

Update Germany configuration for Imagine Dragons 9.5.0

Guidelines to update Germany default configuration for Imagine Dragons:

To apply the correct brand in all the channels and applications
To point to the correct Kernel deployment
To avoid issues of Databricks deployment compatibility with Confidential Computing

Prerequisites

In the corresponding Kernel deployment, all Aura datasets are published and the corresponding scopes are configured to aura-bot client.
There is an AURA_CONVERSATIONS container in Kernel Azure Storage.
A kubeconfig of the Aura environment must be configured.
Substitute <YOUR_ENV> with the corresponding pre-production environment: es-pre, es-cert, br-pre, de-pre, de-int, etc.
The installation output file (output_install/<YOUR_ENV>_info.json) to get:
- The APIKey of Aura to access aura-configuration-api.
  - Substitute <AURA_API_KEY> with the obtained value.

PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE=output_install/<YOUR_ENV>_info.json
AURA_API_KEY=$(cat ${PATH_TO_YOUR_OUTPUT_INSTALL_ENV_FILE}|jq -r .aura_bot_services_api_key)

Include new brand as a valid one

Connect to the environment using your kubeconfig.
Edit the config-map of aura-configuration-api to include the new brand.
- To include WhatsAppSim in Germany as new brand, just substitute <NEW_BRAND_ID> with 0111.
Access the full list of Brands defined in Kernel

kubectl -n <YOUR_ENV> edit cm aura-configuration-api -o 
apiVersion: v1
data:
  AURA_BRANDS: 0101,10000,<NEW_BRAND_ID>
...

Restart aura-configuration-api pods:

kubectl -n <YOUR_ENV> rollout restart aura-configuration-api

Change already existing channels and applications brands to point to the new one

Change channels

Substitute <UUID> with a valid UUID version 4 generated for every request.
Substitute <AURA_API_KEY> with the Aura API key read from the environment installation file.
Substitute <CHANNEL_ID> with the channel to be configured.
Substitute <NEW_BRAND_ID> with the brand to be configured.

curl --location --request PATCH 'https://<YOUR_ENV>.auracongnitve.com/aura-services/v2/configuration/channels/<CHANNEL_ID>'
\
--header 'correlator: <UUID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY <AURA_API_KEY>' \
--data '{
    "id": "<CHANNEL_ID>",    
    "brand": "<NEW_BRAND_ID>"
}'

Changes in Germany, the previous PATCH should be executed twice, at least, once per existing channel:
- Sprinklr web chat channel identifier: 33a4dcdc-0ef7-4bf1-886f-48d4fda2a031
- Testing channel identifier: afec79db-dc0d-4c2e-a098-6c996503a7b4

Change applications

Substitute <UUID> with a valid UUID version 4 generated for every request.
Substitute <AURA_API_KEY> with the Aura APIKey read from the environment installation file.
Substitute <APPLICATION_ID> with the application to be configured.
Substitute <NEW_BRAND_ID> with the brand to be configured.

curl --location --request PATCH 'https://<YOUR_ENV>.auracongnitve.com/aura-services/v2/configuration/applications/<APPLICATION_ID>'
\
--header 'correlator: <UUID>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: APIKEY <AURA_API_KEY>' \
--data '{
    "id": "<APPLICATION_ID>",    
    "brand": "<NEW_BRAND_ID>"
}'

Changes in Germany, the previous PATCH should be executed once, at least, to update ATRIA application:
- ATRIA application: 7586c369-b6a0-4fa5-9416-d8b45920274c

Change Kernel configuration in Aura components

Review the following variables in your environment profile:

fourth_platform:
  client_id: "aura-bot" # Aura 4P app client id
  client_secret: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          <THE_SECRET_FOR_AURA_BOT_IN_KERNEL>
  apigw_url: "https://api.<KERNEL_DEPLOYMENT>.baikalplatform.com" # must be filled with the right value. Usually https://api.{{environment_profile}}-{{environment_type}}.baikalplatform.com

For example, in Germany, for WhatsappSim Kernel, the URL should be:
- de-int: https://api.de-int-whatsappsim.baikalplatform.com
- de-pre: https://api.de-pre-whatsappsim.baikalplatform.com
- de-pro: https://api.de-pro-whatsappsim.baikalplatform.com
For aura-kpis-uploader, assure that AURA_MICROSOFT_AZURE_STORAGE_CONTAINER_DESTINATION and AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY_DESTINATION belong to the corresponding Kernel deployment.
Execute deploy_core to assure that the configuration is applied everywhere.

Configure Databricks deployment to be compatible with Confidential Computing

Follow these guidelines:

Delete existing workspace
- If you have already deployed Databricks using deploy_common phase, the first step is to delete the current workspace before redeploying it with the correct configuration for Confidential Computing.
- Go to the Azure dashboard and navigate to the resource group where your Databricks workspace is located (usually the common resource group used in the initial deployment).
- Select the Databricks workspace resource and delete it.
Set up the environment for Confidential Computing
- Once the workspace is deleted, you need to adjust the configuration variables to make the new deployment compatible with Confidential Computing. Add the following variables to the environment configuration:
```
databricks_enhanced_security_compliance: false
databricks:
  cluster:
    node_type_id: "Standard_DC8as_v5"
```
Explanation of the variables
- databricks_enhanced_security_compliance: Set to false to avoid additional security compliance configurations that are not needed in this context, and to remove the ability to use confidential type machines.
- databricks.cluster.node_type_id: This is configured, for example, as “Standard_DC8as_v5”, which is a Confidential Computing node type in Azure.
Deploying the workspace with the new configuration
- To deploy Databricks, we need to re-run the deploy_common phase with the new configuration.
- Once the deployment is complete, the Databricks workspace will be configured to use Confidential Computing nodes.
- To configure the Databricks job we must run again the deploy_core.