Aura – aura-gateway-api

Docs:

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

Aura Gateway API

Definition of the complete API in aura-gateway-api

Download swagger file

Docs:

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

aura-generative-api plugin

Description of the aura-generative-api plugin

Introduction

The aura-generative-api plugin manages the endpoints for the communication with atria-model-gateway.

Consumes components (IOC)

Name	Type	Description
generativeProcessService	PluginType.Service	Send data to model-gw and process the response
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
generativeApi	PluginType.API	Endpoints for the communication with generative APIs

Docs:

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

Aura gateway API plugins

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

Introduction

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

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

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

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

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

Plugins management

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

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

The PluginManager performs the following tasks:

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

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

Plugin basic structure

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

A basic plugin must define at least:

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

The structure of this basic plugin is as follows:

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

Plugins modules

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

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

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

Docs:

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

Aura Gateway API architecture and components

Development architecture and technical components of Aura Gateway API

Technical foundations

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

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

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

Architecture overview

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

ConfigurationManager

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

RedisConnector

RedisConnector is a handler connection to redis.

Kpis-handler

KpisHandler is the module responsible for writing the KPIs entities.

HTTP server

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

Middlewares

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

Plugins

Different plugins provide functionality to aura-gateway-api.

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

Docs:

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

Aura Gateway API

Descriptive technical documentation regarding aura-gateway-api, an ATRIA component that provides an interface to expose different capabilities

Introduction

aura-gateway-api is a server in charge of the access to the different AI cognitive capabilities provided by ATRIA.

A channel, service or skill can send a request through an application (entity that enables the communication with aura-gateway-api). After passing through Kernel for authentication and security purposes, aura-gateway-api sends this request to the corresponding AI-driven technology for providing the most accurate response.

Currently, aura-gateway-api enables the access to ATRIA capabilities.

Associated documentation

Descriptive technical documentation regarding aura-gateway-api includes:

Guidelines for working with aura-gateway-api for the development of experiences, depending on the specific ATRIA capability:

Technical guidelines

Docs:

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

Aura Gateway API Postman collection

Postman collection for simulations in aura-gateway-api

Postman collection

Collection

Docs:

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

Aura Gateway Core API

Definition of the core API in aura-gateway-api

Download swagger file

Docs:

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

aura-generative-process-service plugin

Description of the aura-generative-process-service plugin

Introduction

The aura-generative-process-service plugin manages the communication with atria-model-gateway to allow applications to communicate with LLMs.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
generativeProcessService	PluginType.Service	Send data to model-gw and process the response

Docs:

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

Aura Agents API

Description of Aura Agents API

Download swagger file

Docs:

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

Gateway API metrics

List of metrics available in Aura Gateway API

http_request_duration_seconds

This metric is intended to store the information related to all the incoming HTTP requests received by aura-gateway-api.

It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

This metric allows measuring the behavior of the requests from any given endpoint. Specifically, the duration since the request lands in aura-gateway-api until its HTTP response is returned:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status_code: HTTP status code returned in the response
application: Application name of the request.
channel: Channel name of the request. Only for NLPaaS endpoint.
preset: Preset name of the request. Only for Generative endpoint.

outgoing_request_duration_seconds

This metric is intended to store the information related to all the outgoing HTTP requests made by aura-gateway-api. It is stored as a Summary in Prometheus, so every sample, besides the defined labels, also includes its duration.

The metric allows measuring the behavior of the requests to any given endpoint:

The number of requests during a time
The average/min/max duration of these requests

Labels:

method: HTTP method used by the request being stored (GET, POST, PUT, DELETE, etc.)
host: host and domain where the request is being sent
path: specific endpoint of the request
status: HTTP status code returned in the response

aura_component_version

This metric is intended to store the number of aura-gateway-api instances (pods) running each version of the code.

It is stored as a Gauge in Prometheus.

Labels:

version: version field in the package.json file included in the running docker container.
component: name of the component that is writing the metric.

This metric was stored since Beatles (8.9.0) release.

aura_server_unhandled_error

This metric is intended to store the number of unhandled errors happening in aura-gateway. It is stored as a Counter in Prometheus.

Labels:

error: exception message that forced the unhandled error.

services_status

This metric is intended to store the number of success or errored checks of modules of the server. It is stored as a Counter in Prometheus.

Labels:

moduleId: Id of the module.
status: OK or ERROR

Docs:

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

Aura Gateway API operational overview

Description of Aura Gateway API operation and communication protocol

Communication protocol

aura-gateway-api communication protocol is synchronous, depending on the endpoint.

A new component comes here into play: application, defined as an entity used by a channel, service or skill to connect with aura-gateway-api.

An application has a specific configuration and will be the entry point to the aura-gateway-api flow, previous pass through Kernel, meaning that the input parameters for aura-gateway-api come from the application, and no specific information regarding the channel, service or skill is required.

Docs:

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

Aura Generative API

Description of Aura Generative API

Download swagger file

Docs:

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

aura-nlp-resolution-api plugin

Technical description of the aura-nlp-resolution-api plugin

Introduction

The aura-nlp-resolution-api plugin manages the communication with NLP APIs to return a recognizer response.

Consumes components (IOC)

Name	Type	Description
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
nlpResolutionApi	PluginType.API	Endpoints for the communication with NLP APIs

Docs:

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

Aura Gateway API environment variables

List of environment variables handled by Aura Gateway API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Introduction

aura-gateway-api environment variables can be common for all plugins or specific for each of them.

Common properties

Property	Type	Description	Modifiable by OB?
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Configuration API URL where the bot should get the configuration of all the channels available in the environment.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey. By default: `16`.	NO
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the server is deployed. Used during server make-up to handle the indexes of the database properly.	NO
AURA_HTTP_KEEP_ALIVE	boolean	Use of keep-alive in HTTP connections. Used in monkey-patcher. By default: `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in monkey-patcher. By default: `100000`.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Maximum number of sockets. Used in monkey-patcher. By default: `200`.	NO
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of body request. Allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20mb`.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas whose request would not be logged. By default `aura-kpis,static-resources` Used in monkey-patcher.	NO
AURA_INTERNAL_RETRIES	number	Number of retries to be made by the server in case of error in an internal request. By default: `1`.	NO
AURA_KPI_ENABLED	Boolean	Boolean value, indicating whether aura-gateway-api writes entity files or not. By default: `true`	NO, excepting if requested by Product or Operations teams
AURA_KPI_FILE_PREFIX	string	String with the prefix used in the KPIs entities files of this service. By default, `gwapi/GWAPI`	NO
AURA_KPI_REMOVE_SPECIAL_CHARACTERS	string	Regular expression for removing special characters Default:`\n\r`	NO
AURA_KPI_STORE_MODE	string	It indicates which is the destination of the KPIs entities files. Default: `blob`. If `file`, they will be stored locally to the instance, in the folder shown in `KPI_TO_DSV_LOCAL_FILES_DIRECTORY`. For development purposes. If `blob`, they will be stored remotely in the Azure blob container shown in `KPIS_STORE_CONTAINER`. Mandatory in environments running on k8s.	NO, only configurable when running aura-gateway-api locally.
AURA_KPI_TO_DSV_CACHE_TTL	number	Number with the amount of milliseconds to cache existing requests to calculate their duration. Default: 1800.	NO
AURA_KPI_TO_DSV_DELIMITER	string	Field delimiter to be used in KPIs entities files. Default: \|	NO. It will break all the analysis and processes running on top of these files.
AURA_KPI_TO_DSV_EXTENSION	string	Extension to be used in KPIs entities files. Default: `txt`	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_KPIS_BLOB_STORE_INTERVAL	number	Time interval in milliseconds to upload asynchronously logs to the `KPIS_STORE_CONTAINER`. Default: `60000`. Only needed if `KPI_STORE_MODE==blob`.	NO. In pre/production, it must be `blob` so the files will be uploaded to Kernel instance afterwards. Setting file for development is recommended.
AURA_KPIS_LOG_API_REQUEST_BODY	boolean	Flag to log or not the request body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_LOG_API_RESPONSE_BODY	boolean	Flag to log or not the response body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_STORE_CONTAINER	string	The name of the Azure Blob container to store KPIs entities files. By default, `aura-kpis`. It MUST be the same than the one configured in `KPIS_UPLOADER` module. Only needed if `KPI_STORE_MODE==blob`.	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	NO
AURA_MAKEUP_MODE	string	It allows `dev` mode for the make-up process with the value `local`. By default: `full`.	NO
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. By default: `aura-configuration`.	NO
AURA_MICROSOFT_AZURE_STORAGE_STATIC_CONTAINER_NAME	string	Aura static container name.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service or not.	NO
AURA_REQUEST_TIMEOUT	number	Number of seconds to wait for a request. By default: `30 * 1000`.	NO
AURA_REQUEST_DEADLINE_TIMEOUT	number	Deadline timeout for the request.	NO
AURA_RETRIES_CODES	string[]	List of codes that will be used to retry the request. By default: `['ECONNRESET']`.	NO
AURA_SERVER_PORT	number	Port to where server is listening. By default: `8989`.	NO
AURA_SERVER_REMOTE_CONTAINER_PREFIX	number	Remote container prefix. By default: `aura-gateway-api`.	NO
AURA_SERVER_RETRIES	number	Number of retries made by aura-gateway-api in case of error in an HTTP request. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVER_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVER_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SERVICES_PATH	string	Path where the services are located. By default: `/aura-services/`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Time in milliseconds to complete the SHUTDOWN signal and process all the messages in queue before SIGTERM. By default: `25 1000`.	NO
AURA_SWAGGER_LOCAL_PATH	string	Location of the swagger file generated from all loaded plugins. By default: `swagger.yaml`. Used during makeup to upload the file to remote.	NO
AURA_SWAGGER_PLUGIN_PATH	string	Location of the swagger file of every plugin. Default: swagger.yaml.	NO
AURA_SWAGGER_LOCAL_CORE_PATH	string	Location of aura-generative-service swagger base file. By default: `swagger-core.yaml`.	NO
AURA_SWAGGER_REMOTE_CONTAINER_PREFIX	string	Remote container prefix to store the swagger information. By default: `swagger`	NO
AURA_SOURCE_PATH_AVRO_ADAPTERS	string	Relative path to file with the dimensions and entities to transform to Avro.	NO
AURA_TRUSTED_HOSTNAMES	string	Comma-separated list of the trusted domains URL of the current environment.	YES, all the trusted domains must be added.
AURA_VERSION	string	Mandatory, release of Aura.	NO

aura-development-api plugin

Property	Type	Description	Modifiable by OB?
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_PREFIX	string	Redis prefix.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Used in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	String with a list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_REDIS_USE_CONNECTION_POOL	boolean	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
DEV_AURA_BEHAVIOR_CACHE_TTL	number	Maximum lifetime of behavior cache in seconds. After this time, the system will delete the message. By default: `60 * 60` (60 min).	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_COMMAND_PATTERN	string	Pattern to recognize a behavior command. By default: `gateway(:\| +)(get\|set\|unset)(:\| +)(\w+)(:\| +)?.+`	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments. By default: `false`	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_PREFIX	string	Used in cache key prefix and in command name. By default: `gateway`.	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_SETTINGS_FILE_CRON_PATTERN	string	CRON expression associated with the reload time of the configuration file. Configuration file is defined in: `DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE`. By default: `\/5 * * *`.	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE	string	Profile configuration file location for the aura-behavior-manager. By default: `aura-gateway/aura-gateway-behavior-manager.json`	NO in production environments. This feature could only be activated in development environments.

aura-generative-api plugin

Property	Type	Description	Modifiable by OB?
AURA_MODEL_GW_ENDPOINT	string	URL of Atria Model GW API.	NO. In any case, it must be the internal k8s URL pointing to the `atria-model-gateway`.

aura-update-me-api plugin

Property	Type	Description	Modifiable by OB?
AURA_CONFIGURATION_RETRIES	number	Number of retries to get the configuration. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.

aura-nlp-resolution-process-services plugin

aura-feedback-api plugin

Property	Type	Description	Modifiable by OB?
AURA_MODEL_GW_ENDPOINT	string	URL of Atria Model GW API.	NO. In any case, it must be the internal k8s URL pointing to the `atria-model-gateway`.

aura-agents-api plugin

Property	Type	Description	Modifiable by OB?
AURA_AGENTS_MANAGER_ENDPOINT	string	URL of agents-manager API.	NO. In any case, it must be the internal k8s URL pointing to the `agents-manager`.
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO

aura-operations-api plugin

Property	Type	Description	Modifiable by OB?
AURA_CONFIG_WATCHER_ENDPOINT	string	URL of config-watcher API.	NO. In any case, it must be the internal k8s URL pointing to the `config-watcher`.

Docs:

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

Aura NLP resolution API

Description of Aura NLP Resolution API

Download swagger file

Docs:

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

aura-nlp-resolution-process-service plugin

Technical description of the aura-nlp-resolution-process-service plugin

Introduction

The aura-nlp-resolution-process-service plugin manages the communication with NLP APIs to return a recognizer response.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications
channelsConfiguration	PluginType.Service	Configuration of channels

Provides components (IOC)

Name	Type	Description

Docs:

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

Get Kernel access token for Aura Gateway API

Guidelines to get a Kernel access token for working with aura-gateway-api

Steps in the process

To use the Kernel aura-aiservice API, first authenticate with the client credentials specifying the required scopes, that depend on the specific ATRIA capability to be used:
- NLP as a Service: aura-ai-services:nlp-messaging:write
- Generative AI and RAG: aura-ai-services:messaging:write
Afterwards, refresh the token following Kernel instructions.
To obtain the real secret of your app, just run the following command, as an example of using the app “aura-bot” in Kernel “global-int-current” with a fake password.
```
$ kubectl -n $AURA_ENVIRONMENT get secret aura-bot -o json | jq -r ".data.AURA_FP_CLIENT_SECRET|@base64d"
```

Now you can request the access_token:

# generate a valid UUID as correlator
# substitute {{correlator}} with the generated UUID
export CORRELATOR={{correlator}}
# substitute aura-bot:secret with the specific information for your Kernel client.

$ curl -i -X POST -u aura-bot:secret -H 'Content-Type: application/x-www-form-urlencoded' -H 'Cache-Control: no-cache' -H 'x-correlator: $CORRELATOR' 'https://auth.global-int-current.baikalplatform.com/token' -d 'scope=aura-ai-services:messaging:write&grant_type=client_credentials'

HTTP/2 200
{"access_token":"<token>","token_type":"Bearer","expires_in":3599,"scope":"aura-ai-services:messaging:write","purpose":""}

This token expires after a certain time, so it is required to repeat the steps above to obtain a new one.

Access here to more information about Kernel authentication.

Docs:

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

API definition for Aura Gateway API

Description of API swaggers for aura-gateway-api component

APIs index

Aura Gateway API
Definition of the complete API in aura-gateway-api
Aura Gateway Core API
Definition of the core API in aura-gateway-api that handle its operations
Aura Gateway Agents API
This API is exposed in Kernel to handle agents services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Generative API
This API is exposed in Kernel to handle Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura NLP Resolution API
This API is exposed in Kernel to handle NLP as a Service: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Feedback API
This API is exposed in Kernel to provide feedback about the behavior of Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Gateway Update-Me API
Aura Gateway Development API
Only available in development environments.
Dapr PubSub API
Aura Operations API
API that include a set of endpoints related to operations over Aura.

Docs:

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

Aura Feedback API

Description of Aura Feedback API

Download swagger file

Docs:

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

aura-development-api plugin

Technical description of the aura-development-api plugin

Introduction

aura-development-api plugin manages the configuration in development environments. Only available in development environments.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
redisConnector	PluginType.Service	Redis connector

Provides components (IOC)

Name	Type	Description
developmentApi	PluginType.API	Endpoints to change development configuration
behaviorCache	PluginType.Service	Cache to store the configuration changes
behaviorManager	PluginType.Service	Management of changes

Docs:

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

Aura Gateway Development API

Description of Aura Gateway Development API. Only available in development environments.

Download swagger file

Docs:

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

aura-feedback-api plugin

Description of the aura-feedback-api plugin

Introduction

The aura-feedback-api plugin manages the communication with atria-model-gateway to provide feedback about the Generative and RAG services behavior.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications

Provides components (IOC)

Name	Type	Description
feedbackApi	PluginType.API	Endpoints for the communication with feedback endpoint

Docs:

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

Triage recognizer middleware

Description of triage-recognizer-middleware, responsible for calling an external API in an attempt to obtain the user’s intent.

Enabling the triage recognizer

The triage-recognizer-middleware is an optional recognizer that can be added to the environment variable AURA_ACTIVE_MIDDLEWARES to enable it.

AURA_ACTIVE_MIDDLEWARES=TriageRecognizerMiddleware

Once enabled, the middleware will only run if the following conditions are met:

There is no intent already recognized in the context.
The intent is included in the list of intents defined in the environment variable AURA_INTENTS_NONE. By default, this variable contains the value ['None', 'intent.none', 'intent.tv.none'].

Adding the necessary configuration for the channel

To use this recognizer, it is necessary to add the configuration for the channel in the channel collection in the aura-configuration-api.

The configuration must include the applicationId and presetId for the TriageRecognizer in the atria.recognizers object.

For example, if the channel is movistar-plus, the configuration should look like this:

{
    "name": "movistar-plus",
    "prefix": "mp",
    "atria": {
        "recognizers": {
            "TriageRecognizer": {
                "applicationId": "816bdab6-3ea3-4a77-bdea-12945d6d7053",
                "presetId": "67cb30a2-aec7-448c-a2a6-18faaa9d1820"
            }
        }
    }
}

How the triage recognizer works

The triage-recognizer-middleware is responsible for calling an external API, ATRIA, to obtain the user’s intent using a Large Language Model (LLM) system.

The triage-recognizer-middleware uses the AiService to call the Atria generative API with the message received in the request and the configuration defined for the channel in the channel collection in the aura-configuration-api (see the section Adding the necessary configuration for the channel).

If triage middleware is enabled but the channel does not contain the config for the TriageRecognizer, the middleware will not be executed.

For each call, the previous session information associated with the user is sent, if it exists. The session information is stored in the context for future requests.

Finally, the intent is extracted from the response received from ATRIA and fills the IntentResult with the recognized intent.

Docs:

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

Aura Operations API

Description of Aura Operations API

Download swagger file

Docs:

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

aura-agents-api plugin

Description of the aura-agents-api plugin

Introduction

The aura-agents-api plugin manages the endpoints for the communication with the agents-manager.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager
applicationConfiguration	PluginType.Service	Configuration of applications
agentsConfiguration	PluginType.Service	Configuration of agents

Provides components (IOC)

Name	Type	Description
agentsApi	PluginType.API	Endpoints for the communication with agents APIs
agentsManagerClient	PluginType.Service	Client of agents-manager

Docs:

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

aura-operations-api plugin

Description of the aura-operations-api plugin

Introduction

The aura-operations-api plugin manages the endpoints for operations related to Aura.

Consumes components (IOC)

Name	Type	Description
configurationManager	PluginType.Service	Configuration manager

Provides components (IOC)

Name	Type	Description
operationsApi	PluginType.API	Endpoints for the communication with operations APIs
configWatcherOperationsClient	PluginType.Service	Client to make requests to the config-watcher

Docs:

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

Update Imagine Dragons 9.5.0 base configuration

Guidelines to update Imagine Dragons base configuration:

Update scopes configuration for aura-bot and aura-billing Kernel clients, and use them in Databricks executions
Update aura-gateway-api environment variables to control how KPI entities are written

Prerequisites

In the corresponding Kernel deployment, all Aura datasets are published and the corresponding scopes are configured to aura-bot and aura-billing clients.
A kubeconfig of the Aura environment must be configured.
Substitute <YOUR_ENV> with the corresponding environment: es-pre, es-pro, br-pre, de-pre, de-int, etc.
The installation output file (output_install/<YOUR_ENV>_info.json) to get:
- The KPI blob container name:
  - Substitute <AURA_KPI_CONTAINER> with the obtained value.

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

Update aura-databricks-jobs configuration

Update aura-bot scopes

Add these scopes in the Kernel app of aura-bot:

admin:datasets:read
data:read
data:write

Update aura-billing scopes

Add these scopes in the Kernel app of aura-bot.

admin:datasets:read
data:read
data:write

Update Databricks deployment

It will be necessary to deploy Aura core, indicated in core deployment. This will update the configuration with the following changes:

Update the profile to be multi-node instead of single node, configuring workers autoscaled.
Update the Databricks cluster node type, modifying databricks.cluster.node_type_id configuration:
```
databricks:
  cluster:
    node_type_id: "Standard_DS4_v2"
```

Add autoscale config in cluster:

databricks:
 cluster:  
   config:
      autoscale:
         enabled: true
         min_workers: 2
         max_workers: 4

Update cluster’s config, including a new config element to add spark config as dynamic allocation enabled or executor memory and cores:

databricks:
  cluster:  
    config:
      "spark.debug.maxToStringFields": "100"
      "spark.driver.memory": "4g"
      "spark.executor.memory": "4g"
      "spark.dynamicAllocation.enabled": "true"
      "spark.executor.cores": "4"

Update aura-gateway-api environment variables to control KPI entities writing

Follow these guidelines to update aura-gateway-api environment variables to control the way KPIs entities are written.

This step can be executed at any time, because it is a performance improvement and will be the default configuration in the following release. But it should be applied as a workaround if the aura-gateway-api starts failing and returns responses with 503 or 502 statuses, meaning that the KPI writing processes are consuming all the server resources.

Connect to the environment using your kubeconfig.
Read the name of the container where the KPI entities files are being written.
Edit the config-map of aura-gateway-api to update the variables.
```
kubectl -n <YOUR_ENV> edit cm aura-gateway-api -o 
...
```
Substitute or add the following environment variables.

If an environment variable is not in the config map, it means that the used value is the default one. Please refer to the aura-gateway-api environment variables documentation for further information.

AURA_KPIS_BLOB_STORE_INTERVAL: 3600000
AURA_KPIS_BLOB_STORE_MAX_BLOCK_BYTES: 2500000
AURA_KPIS_LOG_API_REQUEST_BODY: 'false'
AURA_KPIS_LOG_API_RESPONSE_BODY: 'false'
AURA_HTTP_PATHS_LOG_DISABLED: `v1/.well-known, aura-configuration, metrics, healthz, <AURA_KPI_CONTAINER>'

Restart aura-gateway-api pods:

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