Aura – nlpaas

Docs:

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

NLP Apps capability

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

Introduction to NLP Apps technology

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

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

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

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

Application of NLP Apps in ATRIA

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

Figure 6. NLP Apps in ATRIA

Interaction with NLP Apps in ATRIA

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

Functional overview

A simple overview of the process is provided below:

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

Docs:

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

NLP as a Service operational workflow

ATRIA technical operational flow corresponding to the operation of the NLP as a Service capability

Operational flowchart

The sequence diagram of the process executed by the NLP Apps capability is shown below:

@startuml
title NLP resolution API diagram
participant Application
participant Kernel #1add4d
participant AuraGatewayApi #76bbe7
Application -> Kernel: Create two-legged token with scope aura-ai-services:nlp-messaging:write
Note right of Kernel: this token needs refreshing
Kernel -> Application: Response two-legged token
Application -> Kernel: Request to aura-aiservices/nlp/query with token
Kernel -> AuraGatewayApi: Request to aiservices/nlp/query with token-info header
AuraGatewayApi -> AuraGatewayApi: Validate request
AuraGatewayApi -> AuraNLPApp: Request recognition
AuraGatewayApi -> AuraGatewayApi: generate response
AuraGatewayApi -> Kernel: response 200 and message
Kernel -> Application: response 200 and message
@enduml

NLP Apps operational sequence diagram

Docs:

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

Build experiences that call NLP apps

Workflow with the main stages to build an end-to-end experience that calls NLP as a Service to use an NLP app

Introduction

Within NLP as a Service, the NLP Apps capability enables channels, services or skills to connect with Aura cognitive capabilities for sending a request expressed in natural language and receiving back an accurate response via API, without the need for a conversational bot.

Steps in the process

a. Prerequisites: Install and enable

1. Enable ATRIA components in Aura installer

GES team

Is Aura NLP deployed in your Aura system? If not:
Deploy Aura NLP
Enable NLP as a Service components

2. Publish aura-gateway-api in Kernel

GES team / Kernel DevOps Team

Is aura-gateway-api published in Kernel? If not:
Publish the aura-gateway-api API in Kernel as a prerequisite to call this API

3. Get a Kernel token

GES team

Check if your Kernel token has already expired. If so:
Get a valid Kernel two-legged token

b. Configure

4. Configure an application

Use case constructor

Configure an application to connect with aura-gateway-api

c. Build & test

5. Build the understanding model

Use case constructor

Generate and deploy the NLP recognition package for your use case

6. Make request to API

Use case constructor

Make a request to Aura NLP resolution API

Docs:

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

Semantic Search capability

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

Introduction to Semantic Search technology

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

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

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

Figure 7. Semantic Search technology

Application of Semantic Search in ATRIA

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

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

Figure 8. Semantic Search in ATRIA

Interaction with Semantic Search in ATRIA

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

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

Current available models

Semantic Search currently uses Azure OpenAI embeddings technology.

Check the version of the model here.

Functional overview

The use of this capability encompasses three different stages:

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

Docs:

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

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

Build experiences that call Semantic Search

How to build an end-to-end experience that uses the Semantic Search stage (OpenAI embeddings recognizer), within NLP as a service

Introduction

Within [NLP as a Service], the Semantic Search capability enables the use of Azure OpenAI embeddings for the development of generic questions experiences (grounded in FAQs).

Steps in the process

a. Prequisites: Install and enable

1. Enable ATRIA components in Aura installer

GES team

Deploy Aura NLP
Enable NLP as a Service components

2. Publish aura-gateway-api in Kernel

GES team / Kernel DevOps Team

Is aura-gateway-api published in Kernel? If not:
Publish the aura-gateway-api API in Kernel as a prerequisite to call this API

3. Get a Kernel token

GES team

Check if your Kernel token has already expired. If so:
Get a valid Kernel two-legged token

b. Configure

4. Configure an application

Use case constructor

Configure an application to connect with aura-gateway-api

c. Build & test

5. Prepare the FAQ knowledge base

Content manager

Prepare the FAQ contents and answers used by the Semantic Search stage

6. Build the understanding model

Use case constructor

Generate and deploy the NLP recognition package for your use case
For the Semantic Search capability, the stage OpenAI embeddings is used

7. Make request to API

Use case constructor

Make a request to Aura NLP resolution API

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

Guidelines for making a request to Aura NLP Resolution API

Steps to be followed to make a request to the aura-gateway-api NLP Resolution API, for using ATRIA NLP as a Service capabilities

Introduction

The use of the ATRIA AI-driven NLP as a Service capability requires making a request to the aura-gateway-api aura-nlp-resolution-api.

For this purpose, constructors must follow the steps below.

Steps in the process

The request from the application must include different fields to be properly processed by this API:

application.id or application.name: Id or name of the application that has configured the specific pipeline to be used for the resolution of the request. If this field is empty or the channel configured in the application does not exist in the Aura NLP service, an error is sent.
message: text of the message with the request to be resolved.
Authorization header: Two-legged token.

Moreover, NLP as a Service can also handle disambiguation. In this scenario, a list of options will be provided back from the Aura NLP service.

A general request and the associated response are included below:

Request

curl --location 'https://api.environment.baikalplatform.com/aura-aiservices/v1/nlp/query' \
--header 'x-correlator: <uuid>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {token}' \
--data '{  
  "message": "¿Cómo puedo contactar con Movistar plus?",
  "contextFilters": [],
  "application": {
      "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}'

Response

{
  "entities": [
    {
      "entity": "7",
      "type": "faq",
      "score": 0.9489,
      "start_index": 1,
      "end_index": 1,
      "canon": "7",
      "label": "openai-embeddings"
    }
  ],
  "questionId": "7",
  "question": "¿Cómo puedo interactuar con Movistar?",
  "text": "Atención Comercial: 900104708 Atención al Cliente: 1004. Desde el extranjero +34 699 991 004 Soporte Técnico: 1002 Clientes con TV por satélite: 900104709  Clientes con sólo satélite: 900110010  Clientes Prepago: 224430  Atención Canal+: 900 220 305  [Bot de Movistar](http://www.movistar.es/#forward) en Twitter",
  "relatedQuestions": [
    {
      "questionId": "8",
      "question": "¿Cómo puedo darme de baja?",
      "text": "Para bajas de líneas móviles de contrato, puedes solicitarlo en la sección [Bajas](https://www.movistar.es/particulares/BajasIframe/?_ga=2.253697609.1756783427.1543820522-1816496064.1527850957).\r\nPara fusión o  prepago, debes llamar al 1004.\r\nPara paquetes de TV, accede a la sección TV."
    },
    {
      "questionId": "9",
      "question": "¿Dónde puedo comprar un móvil?",
      "text": "Encuentra el móvil que necesitas en la [tienda electrónica](http://www.movistar.es/particulares/movil/moviles). Si has solicitado un smartphone a través de la web o del 1004 con la opción de recogida en tienda y no recuerdas el código de bono, [recupéralo](https://www.movistar.es/atcliente/c2c/servicio-online/index.jsp?language=es&service=consulta-bono-canje)."
    }
  ]
}

Types of responses in NLP resolution API

a. Simple response

When the Aura NLP app (pipeline) recognizes an intent, a simple response with the intent and entities recognized is returned:

Request body

{  
  "message": "Hola",
  "contextFilters": [],
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "intent": "intent.common.greetings",
  "entities": []
}

Request body

{  
  "message": "Mi cobertura",
  "contextFilters": [],
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "entities": [
    {
      "entity": "16",
      "type": "faq",
      "score": 0.99,
      "start_index": 1,
      "end_index": 1,
      "canon": "16",
      "label": "openai-embeddings"
    }
  ],
  "questionId": "16",
  "question": "¿Cuál es mi cobertura?",
  "text": "Si quieres, [consulta la cobertura de ADSL y fibra](https://www.movistar.es/coberturas/ ). Para mejorar la cobertura de tu móvil en casa o en el trabajo a través de tu ADSL o fibra puedes contratar el servicio [“Mi cobertura móvil”](http://www.movistar.es/particulares/movil/servicios/ficha/nav-mi-cobertura-movil ).",
  "relatedQuestions": [
    {
      "questionId": "84",
      "question": "¿Cómo puedo reclamar la factura que me ha llegado?",
      "text": "Sentimos que no estés de acuerdo con los conceptos facturados. Por favor, para poder ayudarte, completa el siguiente [formulario](https://www.movistar.es/particulares/atencion-cliente/escribenos/?tipo=telco&tipo_directo=12-21) y el Servicio de Atención te contestará en un plazo aproximado de 48 horas."
    }
  ]
}

c. Disambiguation response

When there is more than one intent recognized, an intent.disambiguation will be returned with a list of options.

Request body

{  
  "message": "Mi factura",
  "contextFilters": [],
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "intent": "intent.disambiguation",
  "entities": [],
  "options": [
    {
      "questionId": "32",
      "question": "¿Cómo puedo ver mi factura?",
      "text": "Para consultar y descargar las facturas del último año accede a la [web](https://www.movistar.es/cliente/areaprivada/#/facturas) o en Facturas en la sección de [cuenta](https://external-account.movistar-es-dev.svc.dev.mad.tuenti.io/redirect.php?target=account-home) de la app.",
      "relatedQuestions": []
    },
    {
      "questionId": "33",
      "question": "¿Cómo puedo pagar mis facturas pendientes?",
      "text": "Si tienes alguna factura pendiente de pago, recibirás un aviso de pago con el que abonar la deuda en cualquier oficina de correos o en las oficinas bancarias indicadas. También puedes abonarla con tarjeta llamando al 1004."
    }
  ]
}

d. Filtered response

In some FAQs of a generic questions use case, you can add multiple answers and select the most accurate one according to some input context-filters:

Request body

{  
  "message": "¿Cómo puedo acceder a Mi Movistar?",
  "contextFilters": ["channelName:novum-mytelco"],
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "entities": [
    {
      "entity": "3",
      "type": "faq",
      "score": 1,
      "start_index": 1,
      "end_index": 1,
      "canon": "3",
      "label": "openai-embeddings"
    }
  ],
  "questionId": "3",
  "question": "¿Cómo puedo acceder a Mi Movistar?",
  "contextFilters": [
    "channelName:novum-mytelco"
  ],
  "text": "Si accedes con tu móvil mediante Mobile Connect verás todos tus productos y el consumo de la línea con la que accedes.\r\nAccediendo con contraseña tendrás acceso a todos tus productos, facturas y consumo de todas tus líneas.",
  "relatedQuestions": [
    {
      "questionId": "7",
      "question": "¿Cómo puedo interactuar con Movistar?",
      "text": "Atención Comercial: 900104708 Atención al Cliente: 1004. Desde el extranjero +34 699 991 004 Soporte Técnico: 1002 Clientes con TV por satélite: 900104709  Clientes con sólo satélite: 900110010  Clientes Prepago: 224430  Atención Canal+: 900 220 305  [Bot de Movistar](http://www.movistar.es/#forward) en Twitter"
    },
    {
      "questionId": "19",
      "question": "¿Qué tengo contratado?",
      "contextFilters": [
        "channelName:novum-mytelco"
      ],
      "text": "Puedes ver los servicios y productos que tienes contratados en la [sección de cuenta](https://external-account.movistar-es-dev.svc.dev.mad.tuenti.io/redirect.php?target=account-home). Si quieres conocer el detalle de lo que incluye tu tarifa, ve a Tu Tarifa dentro de la sección de cuenta."
    }
  ]
}

Here is the example of the same request without context-filters. You can see that the texts are different and the contextFilter field is not returned:

Request body

{  
  "message": "¿Cómo puedo acceder a Mi Movistar?",
  "contextFilters": [],
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "entities": [
    {
      "entity": "3",
      "type": "faq",
      "score": 1,
      "start_index": 1,
      "end_index": 1,
      "canon": "3",
      "label": "openai-embeddings"
    }
  ],
  "questionId": "3",
  "question": "¿Cómo puedo acceder a Mi Movistar?",
  "text": "Puedes entrar:\r\nCon tu móvil: debes tenerlo a mano para validar el acceso.\r\nO con contraseña y con tu NIF, CIF, NIE o pasaporte: si no la recuerdas puedes regenerarla.",
  "relatedQuestions": [
    {
      "questionId": "7",
      "question": "¿Cómo puedo interactuar con Movistar?",
      "text": "Atención Comercial: 900104708 Atención al Cliente: 1004. Desde el extranjero +34 699 991 004 Soporte Técnico: 1002 Clientes con TV por satélite: 900104709  Clientes con sólo satélite: 900110010  Clientes Prepago: 224430  Atención Canal+: 900 220 305  [Bot de Movistar](http://www.movistar.es/#forward) en Twitter"
    },
    {
      "questionId": "9",
      "question": "¿Dónde puedo comprar un móvil?",
      "text": "Encuentra el móvil que necesitas en la [tienda electrónica](http://www.movistar.es/particulares/movil/moviles). Si has solicitado un smartphone a través de la web o del 1004 con la opción de recogida en tienda y no recuerdas el código de bono, [recupéralo](https://www.movistar.es/atcliente/c2c/servicio-online/index.jsp?language=es&service=consulta-bono-canje)."
    }
  ]
}

e. Custom columns response

Request body

{  
  "message": "Información de la jornada 20",
  "application": {
    "id": "12345678-1234-5678-9a0b-abcd73f96111"
  }
}

Response body

{
  "entities":[
    {
      "entity":"10",
      "type":"faq",
      "score":1,
      "start_index":1,
      "end_index":1,
      "canon":"10",
      "label":"openai-embeddings"
    }
  ],
  "questionId":"10",
  "question":"Información de la jornada 20",
  "text":"La información de toda la jornada 20",
  "speak":"La información de toda la jornada veinte",
  "mainContent":"custom",
  "custom":{
    "carrusel":[
      "1",
      "2",
      "3",
      "4"
    ],
    "data_summary":[
      {
        "gol_destacado":{
          "text":"Gol jornada 23",
          "url":"https://www.youtube.com/watch?v=MgP3zDzQ0CE"
        },
        "gol_propia_puerta":{
          "url":"https://www.20minutos.es/deportes/noticia/4146386/0/insolito-golazo-olympique-propia-puerta-psg/"
        }
      },
      {
        "gol_destacado":{
          "text":"Gol jornada 24",
          "url":"https://eldesmarque.com/actualidad/futbol/primera-laliga-santander/video-resumenes-primera/1372827-madrid-atleti-resumen-en-video-del-partido-de-la-jornada-22"
        },
        "gol_propia_puerta":{
          "url":"https://www.mundodeportivo.com/futbol/20200207/473330110580/el-insolito-gol-en-propia-puerta-del-portero-de-uruguay.html"
        }
      }
    ]
  }
}