Nlp Gauntlet

The Nlp Gauntlet was designed to hold any number of external Natural Language Processing services, better known as NLP services. When used in combination, their already impressive powers make the wearer able to do anything they want.

The goal of this project is to make integration and testing of external NLP services in Apex as easy as snapping your fingers. We achieve this by providing a common interface to invoke and consume results for different NLP service implementations. Having a common output across providers allows swapping NLP services without having to re-write any of the applications that consume the prediction results.

Installation instructions

Method 1 : Un-managed package installation

To install using a pre-built package, use the installation links provided here

Method 2 : Non-Scratch Org quick deploy

Method 3 : Scratch Org sfdx CLI deploy

Install Salesforce DX. Enable the Dev Hub in your org or sign up for a Dev Hub trial org and install the Salesforce DX CLI. Follow the instructions in the Salesforce DX Setup Guide or in the App Development with Salesforce DX Trailhead module.

Clone the nlp-gauntlet repository:

git clone https://github.com/forcedotcom/nlp-gauntlet
cd nlp-gauntlet

Create a scratch org and provide it with an alias (nlp-gauntlet):

sfdx force:org:create -s -f config/project-scratch-def.json -a nlp-gauntlet

Push the app to your scratch org:
```
sfdx force:source:push
```
Assign the External Nlp Admin permission set to the default user:
```
sfdx force:user:permset:assign -n External_Nlp_Admin
```
Open the scratch org:
```
sfdx force:org:open
```

Setup instructions

Once you have deployed the source code to your org, you can begin the authorization setup for your corresponding NLP service provider.

The provided service implementations rely on Named Credentials to generate the authorization tokens.

This project will create some Sample Named Credentials in your org but you will need to edit/clone these with the right credentials/certificates.

Go to Setup > Security > Named Credentials and edit the corresponding Named Credential.

Below you'll find instructions on how to setup and test each specific Nlp Service:
Next, go to /apex/ExternalNlpWorkbench in your browser to verify connectivity and run some tests.

The Nlp Gauntlet Workbench tool allows you to test out different model configurations. You can also load saved configurations from Custom Metadata Types in your org.

Once you've verified the connection and confirmed your models are working correctly. You can consume these predictions from your apex code :

    // Instantiate external nlp service
    // Replace with your provider type (e.g. WitAi, Watson, DialogFlow, Luis)
    ExternalNlpService extNlpService = ExternalNlpServiceFactory.makeNlpService(EinsteinAiService.class);

    // Un-comment line below if instantiating from a Custom Metadata Definition
    //ExternalNlpService extNlpService = ExternalNlpServiceFactory.makeNlpService('Einstein_ai');

    // Set model parameters
    List<ExternalNlpModelParameters> modelParams = new List<ExternalNlpModelParameters>{
        new ExternalNlpModelParameters.Builder()
            .setModelId('Your Model/App/Skill/etc Id')
            .setNamedCredentialKey('Your Named Credential Key') // Case-sensitive name
            .build()
    };

    // Set thresholds and additional parameters (if needed)
    ExternalNlpServiceParameters serviceParams = new ExternalNlpServiceParameters.Builder()
        .setModelParams(modelParams)
        .setIntentThreshold((Double)0.7)
        .setNerThreshold((Double)0.7)
        .setSentimentThreshold((Double)0.7)
        .setAdditionalParams(new Map<String, String>())
        .build();

    // Get predictions
    ExternalNlpPredictionResult results = extNlpService.predict(serviceParams, 'Your text to be analyzed', 'en_US');

    // Consume predictions
    System.debug(results.getIntentResults().getPredictedIntents());
    System.debug(results.getIntentResults().getHighestConfidenceIntentName());
    System.debug(results.getEntityResults().getPredictedEntities());
    System.debug(results.getSentimentResults().getDocumentSentiment());

Profit!

You can now retire on a quiet farm and stare at the universe you just created.

Adding a new service

To add a new service to the nlp gauntlet follow the steps provided in this guide