Abacus 1.0.0.

• 1: Set-up Abacus
• 2: Use Abacus

1 - Set-up Abacus

Abacus 1.0.0. initial set-up

Prerequisites for using Abacus

Check that you fulfil these requisites before Abacus set-up.

1. You have the NLP Virtual Machine installed and working, with your aura-nlpdata working branch generated.

2. The understanding model is already defined and configured.

3. You have generated the specific training files and E2E test files required for each stage of your NLP pipeline.

4. You have already filled the variables required for training in the configuration file build_local_variables.sh.

Steps for Abacus set-up

1. Access the NLP Virtual Machine.

2. Enter your local working project, henceforth {Root_project}, whose name should be:
   aura-nlpdata-[country-code]

3. Copy the local variables configuration template: "${Root_project}/tools/build_local_variables.sh.tpl"
   and rename as:
   "${Root_project}/tools/build_local_variables.sh"

   cd ${Root_project}/tools
   cp build_local_variables.sh.tpl build_local_variables.sh 
   

4. Access the file build_local_variables.sh in the tools/ folder.

5. Fill in the variables inside the “run_web_trainings” section:

   • TRAINING_WEB_AZURE_BASE_URL and TRAINING_WEB_AZURE_SAS_TOKEN variables:
     Ask the APE Team for them.

   • GITHUB_TOKEN variable:

     • Generate a GitHub token:

       • Enter GitHub with your profile
       • Verify your email address if you haven’t done it yet
       • Go to GitHub token settings and generate a new token
       • Fill in the name and expiration date of the token
       • Select the scopes (Recommended: activate repo)
       • Click Generate token

     • Copy the token in the variable GITHUB_TOKEN.
       ⚠️ Make sure you copy it, as it will only shown once.

     

6. Run the script file:

   ${Root_project}/tools/run_web_trainings.sh
   

7. When the script is finished, Abacus is opened automatically.

2 - Use Abacus

Guidelines for the use of Abacus 1.0.0.

Open Abacus

1. Open the NLP Virtual Machine.

   

2. Execute the following commands in the console:

   cd ${Root_project}/tools
   ./run_web_trainings.sh 
   

   

3. Abacus is now opened.

   

Discover Abacus main screen

Create a new Pull Request

1. Enter Abacus and select “New Pull Request” as your working mode.

   

2. In the main interface, select the channel where your understanding model is.

   

4. Train your understanding model.

   

5. When the training is finished, select “Results” in the drop-down menu and access to the results of the accuracy tests.

   • End-to-end tests (accuracy of the overall NLP model)

   

6. Evaluate the accuracy of your model:

• Check in “last test” the overall accuracy related to the last test performed in the tool.

• Click on each specific error in “last test report” to access to detailed information.

• Use the filters to visualize errors per type, intent obtained or intent expected.

  

7. Test your NLP model locally (Abacus simulator).
   Once your model is trained, you can use the Simulator to launch and test your pipeline locally and make a real-time evaluation of accuracy in the recognition of a specific statement.

   • Open the simulator.
   • Type a phrase.
   • Check how your model recognizes it.

   

8. When the accuracy is satisfactory, publish your model:

• Press the “PUBLISH” button.

• Create your Pull Request inserting the type, related JIRA issue, title and description and publish it.

• If everything goes right, your PR is published. You can also see the details in Github.
  

Edit an existing Pull Request

1. Enter Abacus and select “Edit existing Pull Request” as your working mode.

2. Select your intended Pull Request. You can open it from Abacus or from GitHub to see its details.
   

3. Now, you can work over it as explained in Create a new Pull Request section, from step 2 onwards.

Abacus additional information

When Abacus is started, the API is available in: http://127.0.0.1:4000 (*)

(*) The port is variable, with values in the range: 4000 - 4100

The API documentation is included in Aura NLP API definition.

Abacus troubleshooting

Logs files

All the operations carried out with Abacus are recorded in the logs file:  ${Root_project}/server.log 

1. If an error occurs, Abacus will show this message:

2. Clicking on “Download”, you can access to the log report and check the error for fixing it.

3. If, the problem persists, contact the Global Support Team and provide them with the report.

4. When it is solved, press “Reload”, to continue using Abacus.

Git conflicts

If the remote branch has changes that have not been updated in the local working branch, Github detects this situation as a conflict when publishing, and is not able to recognize which are the correct changes.

The following pop up will appear after clicking on “publish”.

Clicking on “Download”, you will get the file ${Root_project}/server.log, where you can check the errors that have occurred and try to solve them.

!  [rejected]    <<working-branch>>  ->  <<working-branch>> (fetch first)
error: failed to push some refs to 'git@github.com:Telefonica/aura-nlpdata-global.git'

Conflicts in server.log must be resolved locally using the editor:

1. Open a terminal in code editor. Make sure the branch in terminal is the correct working branch.

2. Move changes from the remote branch to local:
   git pull origin <<working-branch>>

   

3. A message with a list of files with conflicts is shown.

4. Open each file and right-click to access the conflicts resolver.

5. Resolve the conflict. You can include texts from the local branch (left) or from the remote one (right) or discard both and copy what is needed.

6. Once conflicts are resolved, launch the following command to review the status of the local branch and check that all the conflicts are fixed in the response message:
   git status

7. When all the conflicts are resolved, commit changes:
   git commit –m "[[feat]] resolve conflicts: <<description of changes>>"

8. Push to update changes to the remote branch:
   git push origin <<working-branch>>

9. A message with all the details will appear.

10. If everything is solved, now restart the web server and continue with the existing Pull Request.