Purpose and Vision:

This project's goal is to allow any person to talk to any relational database. For example if connected to a meal planning application, a user could say 'Create a meal plan for next week with at least two meals meatless' and our engine would create the database mutations necessary to get that done for the user. Our engine has access to the user's specific schema at runtime so it knows whether it needs to ask follow-up questions or if it can execute the command from the user.

To accomplish this we are using Devii's schema generation, api, and security engine so every database has consistent structure. This means you will need to set up a Devii account to use this api.

Quick Start

Please visit the link to NLAPI Playground

1. Authenticate to your database via https://api.devii.io/auth

2. Use your Access token to send a POST request to [nlapi_url]/nlapi

fetch('[nlapi_url]/nlapi', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify({
    "user_input": "create new ingredient called pinto beans",
    "context" : ["user id is 1"] // optional
    // "thread_id" : 34232 // use this to followup on a conversation
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch((error) => console.error('Error:', error));

Documentation

Key Concepts:

Messages

Messages are the foundation of the information that is passed to and from the NLAPI server. To send a message to the server a developer can simply send a POST request to the /nlapi endpoint with user_input apart of the json object in the body. user_input is the only required input for this endpoint. You can continue a conversation by including the thread_id key in the request. (see Threads section for more info) You can also include the key context in the request. (see Context for more info)

The api will return the latest message in the thread object returned in the messages array. The latest message will always be at messages[0] and the array will be ordered by create time in descending order (latest -> oldest ).

Each message object returned will have the following keys: content : The natural language input from the user (human) or natural language output from our models (bot) speaker : Identifies who said the message. Currently will always be bot or human created_at : Timestamp of when the message with created

Threads

Threads are simply a conversation of messages. Sometimes a user will try to interact with a model, but not provide required information for a valid db mutation. When this happens, the nlapi will respond in natural language with a message indicating what information it needs to complete the users' request. When this happens, the developer will need to pass the thread_id key in the next request to follow up on the conversation. The nlapi will use the whole context of the whole thread to complete the request so the user does not have to repeat previous information already mentioned in the thread.

If no thread_id is provided in the request, a new thread is created and the nlapi has no access to previous messages.

Thread Expiration: After a thread expires, a user cannot add additional messages to a thead. Expiring threads is a security feature. If we didn't expire threads, and a user had access to something early on in the thread, but not later, the nlapi may assume access still and hallucinate bad database interactions. With the proper Role Based Access Control policies, your user will still not be able to perform any action they are not allowed, but it could lead to a poor user expirience and more hallucinations with longer threads. We may change this in the future.

The thread object is what is returned from every nlapi request. Each thread object returned will have the following keys: thread_id : This is used to keep track of threads so a user can followup with a conversation created_at : The timestamp the thread was created. expires_at : The timestamp when the thread expires. After this, no more messages will be accepted and the nlapi will return ____ cod messages : The array of message objects (see message object for more details)

Context

The context is information the developer knows about the user or current location of the request that the user and the nlapi would not have access. For example on a project management software if a user is on a project dashboard page and sends the {'user_input' : 'add a task called make documentation for feature x i'}. The nlapi would not know what project the user is referencing. But because the user is on the project page, the user could add the context: ["user is on project_id 71"] to the payload and the nlapi would understand that the user is likely wanting to add a task with project_id of 71.

How context is being implemented is currently being shaped and is subject to change.

Feedback Loop

To continue to improve our models we optionally allow users to rank and give feedback on threads. We use this data internally to continually improve our models. Coming In Some Amount of Time: with enterprise installations of this software, the enterprises exclusive model will continue to learn from the data in this feedback loop

Developers can send POST requests to /nlapi_feedback with the feedback object to help provide feedback and improve our models. Users can only provide feedback on threads they are logged into

Feedback Object

Keys: rating : The user feedback on a scale of 1-10? 10 being the most satisfied feedback : The user could write anything about the thread here. thread_id : The thread id the feedback is associated with.

Architecture

-> Request -> Natural Language Resolver -> Code generated to interact with the db -> db request sent to RBAC policies -> code manipulates the database -> Natural Language Resolver Explains results or asks for a follow up