Aura Gateway API

• 1: Architecture and components
• 1.1: Plugins
• 1.1.1: aura-generative-api plugin
• 1.1.2: aura-generative-process-service plugin
• 1.1.3: aura-nlp-resolution-api plugin
• 1.1.4: aura-nlp-resolution-process-service plugin
• 1.1.5: aura-development-api plugin
• 1.1.6: aura-feedback-api plugin
• 1.1.7: aura-agents-api plugin
• 1.1.8: aura-operations-api plugin
• 2: Operational overview
• 3: Environment variables
• 4: API definition
• 4.1: Aura Gateway API
• 4.2: Aura Gateway Core API
• 4.3: Aura Agents API
• 4.4: Aura Generative API
• 4.5: Aura NLP resolution API
• 4.6: Aura Feedback API
• 4.7: Aura Gateway Development API
• 4.8: Aura Operations API

1 - Architecture and components

Aura Gateway API architecture and components

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.

1.1 - Plugins

Aura gateway API plugins

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.

1.1.1 - aura-generative-api plugin

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

1.1.2 - aura-generative-process-service plugin

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

1.1.3 - aura-nlp-resolution-api plugin

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

1.1.4 - aura-nlp-resolution-process-service plugin

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

1.1.5 - aura-development-api plugin

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

1.1.6 - aura-feedback-api plugin

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

1.1.7 - aura-agents-api plugin

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

1.1.8 - aura-operations-api plugin

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

2 - Operational overview

Aura Gateway API operational overview

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.

3 - Environment variables

Aura Gateway API environment variables

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

| Property | Type | Description | Modifiable by OB? | |:—————-|:—————————————————————————| | AURA_COGNITIVE_ENDPOINT | string | URL of Aura NLP API. | NO. In any case, it must be the internal k8s URL pointing to the api-gw. |

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.

4 - API definition

API definition for Aura Gateway API

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.

4.1 - Aura Gateway API

Aura Gateway API

4.2 - Aura Gateway Core API

Aura Gateway Core API

4.3 - Aura Agents API

Aura Agents API

4.4 - Aura Generative API

Aura Generative API

4.5 - Aura NLP resolution API

Aura NLP resolution API

4.6 - Aura Feedback API

Aura Feedback API

4.7 - Aura Gateway Development API

Aura Gateway Development API

4.8 - Aura Operations API

Aura Operations API