Aura Complex Logic Framework

• 1: Architecture and components
• 2: Configuration
• 3: Files and libraries
• 4: Global plugins
• 4.1: Input validation video plugin
• 5: API definition

1 - Architecture and components

Aura Complex Logic Framework architecture and components

CLF architecture

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

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

CLF main components

Sandbox

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

Plugins

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

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

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

Some key features of CLF plugins are defined below:

• Architecture allows each package of plugins to be deployed in its own environment: it is possible to have an isolated container deployed in an independent way containing all the plugins of a specific package (for instance, global plugins).

• Each package is isolated by being run as a different process by a unique user with randomized name. The rationale behind this is to provide an isolated sandbox to make sure no package of plugins is a security risk. Thereby, each user has limited privileges and computational resources (memory, file descriptors and CPU time) and only runs one process for package.

• The running packages can only receive data from a socket, and the appropriate plugin is then executed depending on both the plugin type and the intent contained in the data. The API handler is in charge of forwarding the data to the package, acting as a proxy, but it also checks the requests and transforms the responses back.

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

• OBs can develop their own custom plugins in the Aura Complex Logic Global repository, with each plugin implemented as a class that inherits from PluginBase and overwrites run method. This method receives the request data and contains the logic of the plugin. It must also generate a response that will be returned to the API handler. When a request is performed, depending on the intent, the request data will be forwarded to the corresponding plugin automatically. Note that two intents can trigger the same plugin but it is not possible to trigger two plugins with the same intent.

• Each package of plugins is watched by a supervisor. If the package process crashes, it will be restarted automatically by supervisor. The causes of abrupt exit could be excessive consumption of resources (CPU time, memory or file descriptors) or plugin internal malfunction.

Stub

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

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

API server

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

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

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

API handler

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

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

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

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

API plugin

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

Kernel Platform connectors

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

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

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

CLF Sequence diagram

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

2 - Configuration

Aura Complex Logic Framework configuration

Introduction

The configuration of the Complex Logic Framework has two different purposes, each of them supported by a configuration file:

• General operational configuration
  General configuration for the Complex Logic Framework performance.

• Plugins configuration
  Specific configuration for each plugin developed over the CLF.

General operational configuration

The file bootstrap.cfg contains the Complex Logic Framework operational config sections. This file is included in the CLF repository, within the folder:
~/aura-complex-logic-[country_code]/config/etc/bootstrap.cfg

⚠️ OBs must not modify these fields. If any modification is required, it must be adjusted after approval by the Aura Platform Team

The file follows the general structure shown hereunder:

[logging]
handlers = { . . . }
loggers = { . . . }
root = { . . . }

Logging

[logging]
handlers = {
      'hdl1':{
         'class':'logging.StreamHandler',
         'formatter':'console',
         'level': 'DEBUG'
      },
      'hdl2':{
         'class':'logging.StreamHandler',
         'formatter': 'simple',
         'level': 'DEBUG'
      }
   }
loggers = {
      'plugins': {
         'level': 'DEBUG',
         'handlers':[
            'hdl1'
         ],
         'filters': [],
         'propagate': False
      }
    }
root = {
      'level': 'DEBUG',
      'handlers':[
         'hdl2'
      ]
    }

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

• handlers: This field configures a dictionary with different logging handlers. Each key is the name of a handler, and is composed of the following parameters:

  • class: It is configured with Python logging handlers (See Python documentation).
  • formatter: It configures the format of logs. It must be filled with the labels json, string, console or simple.
  • level: It is referred to the level of the logging event. It must be filled with the labels INFO, ERROR, WARN or DEBUG.

• loggers: The corresponding value is a Python dictionary in which each key is a logger name and each value is a dictionary that describes how to configure the corresponding Logger instance:

  • level (optional parameter): Level of the logger.
  • handlers (optional parameter): List of IDs of the handlers for this logger.
  • filters (optional parameter): List of IDs of the filters for this logger.

• root: This field includes the configuration for the root logger.

  • level (optional parameter): Level of the logger.
  • handlers (optional parameter): List of IDs of the handlers for this logger.

Plugins Configuration

The file complex_logic.json includes the specific configuration for each plugin. It is included in the following path of the CLF repository:
~/aura-complex-logic-[country_code]/config/plugins/complex_logic.json

⚠️ OBs must not modify these files. If any modification is required, it must be adjusted after approval by the Aura Platform Team

{
     "aura_clf_XX.plugins.plugin_1_name.plugin_1_class_name": {
         "config": {
             "sound_disabled_channels": ["channel_1", "channel_2"],
         }
     },
     ...
     "aura_clf_XX.plugins.plugin_N_name.plugin_N_class_name": {}
}

Each plugin requires a specific configuration. This will be defined in a JSON file with the following structure:

• Class path: Path and identifier for the plugin.
• Open dictionary including the specific configuration of the plugin.

Enabling/disabling sound responses

Within the configuration dictionary of each plugin, you can include the sound_disabled_channels field to specify in which channels sound responses (both positive and negative) should be disabled for that plugin. This field must be a list of channel prefixes.

For example, if a channel prefix is included in this list, the plugin will not play any sound in its responses when the interaction occurs through that channel.

Currently, the configuration added in this file is not included in the production phase, therefore this file should only list the Plugins class path and keep an empty dictionary as configuration.

Disabling contingency or fallback modes for tv search use case

For the tv search use case, in the configuration dictionary of the plugin aura_clf_video.plugins.tv_search_plugin.TvSearchPlugin, you can include the contingency_disabled_channels field to specify if the contingency or fallback search mode is disabled for a specific channel. This field must be a list of channel prefixes.

{
    "aura_clf_video.plugins.tv_search_plugin.TvSearchPlugin": {
        "config": {
            "contingency_disabled_channels": ["channel_1", "channel_2"],
        }
    },
    ...
}

3 - Files and libraries

Aura Complex Logic Framework files and libraries

requirements.txt file

This file contains Python module dependencies. By default, it includes two own libraries:

• Library auracog-lib
• Library auracog-plugins-lib

And other external ones used in the testing and verification stages:

• flake8-htmlPylint
• pytest-pylint
• pytest-html

It is possible to include new dependencies in this file if required for the development of new plugins.

auracog-lib

auracog-lib library is a Python package containing a few basic classes & modules intended as helpers for Aura Cognitive applications, specifically:

• Configuration: it contains AuConfig, wrapper for the standard Python ConfigParser with certain added functionality.
• Logging: it contains LoggerWrapper, wrapper for the standard Python logging with certain added functionality.
• Testing: it contains functionality used in test development.

auracog-plugins-lib

auracog-plugins-lib contains the necessary utilities for all the plugins, such as validators and metrics used in verification and performance scripts or plugin_base, the base class of all the plugins.

plugin_base.py file

This is an essential internal file in Aura Complex Logic Framework for its proper performance. This file contains the base class PluginBase, from which all the plugins that are developed will inherit.

All the plugins developed will be initialized with a configuration and a logger that will be passed to them as a parameter and they will have to necessarily develop an asynchronous run method. The run method is the main method of the plugin and will develop the activity for which the plugin has been designed. This method receives data, a dict with the JSON request as a parameter and it will return the JSON response as a dict.

It is also possible to use other auxiliary methods if developers consider it.

from typing import Dict

from auracog_lib.aura_logging import logger_wrapper
from auracog_lib.code_utilities.type_hints_utilities import TypeHintsUtilitie
from auracog_lib.utils.exception import AuraAbstractException


class PluginBase:

    def __init__(self, cfg: Dict, log: logger_wrapper.LoggerWrapper):
        """
        Init method. No overload is required.
        
        :param cfg: a dict with the configuration for plugins.
        :param log: a logger object that implements the usual info, debug and error methods.
        """
        self.cfg = cfg
        self.log = log
        
    async def run(self, data: TypeHintsUtilities.Json) -> TypeHintsUtilities.Json:
        """
        Overload this methods in your custom plugins.
        
        :param data: A dict with the JSON request.
        :return: The JSON response that will be returned as a dict.
        """
        raise AuraAbstractException

4 - Global plugins

Aura Complex Logic Framework global plugins

Introduction

Plugins in Aura Complex Logic framework are components that add a specific feature, thus enabling its customization. They receive data, make the required computations and return an adequate response to the handler

Aura CLF contains several global plugins, but it is possible for developers to add custom ones in the Aura Complex Logic global repository.

This section describes the current catalog of Aura CLF global plugins developed by Aura Global Team. Currently, CLF only contains video plugins, suitable for TV use cases.

Aura CLF video plugins

Input validation video plugin

This is a swagger whose role is the validation of the input for video plugins. It includes a sub-section for each plugin, corresponding to a specific TV use case.

The purpose of this swagger is to show the description models and examples for possible video plugin requests and responses.

ℹ️ Check the multiple example response of plugins: Success, Error invalid request, etc.

Access here to Input validation video plugin

TV search plugin

Plugin for the TV search use case:

• TV search plugin

TV display plugin

Plugin for the TV display use case:

• TV display plugin

TV content get info plugin

Plugin for the TV content get info use case:

• TV content get info plugin

TV vod epg information plugin

Plugin for the TV vod epg information use case:

• TV vod epg information plugin

4.1 - Input validation video plugin

Input validation video plugin

5 - API definition

Aura Complex Logic API