Query API

Note

The query API is available in SLU v4.1 or later.

In some cases, it may be necessary to retrieve a response generated by your AI assistant to use it further in the dialog logic. For example, you may need to get the information the user requests and save it to a file, send it by email and so on.

Alan AI provides the query API to query corpus data programmatically. The query API can be helpful for:

  • Education and training

  • Data analysis

  • Reporting and so on

To query corpus data programmatically, add api.query_v1() to the dialog script. The query API takes two parameters:

  • Data corpus against which the query is run

  • Question to be asked

Dialog script
let text = corpus(`
    My name is Alan
`)

intent('Answer my question', async p => {
    let answer = await api.query_v1({corpus: text, question: "What is your name?"});
    p.play('Here you go')
    console.log(answer.summary);
});

Examples of use

Let’s assume you want to get an answer to a question from the FAQ data you have in plain text. For this, you can add the following code to the dialog script:

Dialog script
let FAQ = corpus(`
    Where can I sell with Shopify? Shopify lets you sell almost anywhere your customers are, including online, in-person, online marketplaces, and social media.
    What happens when I receive an order? Depending on your preferences, you’ll receive an email, mobile app notification, or RSS notification every time your receive an order.
    Do I need to ship items myself? No, you don’t need to ship items yourself. You can use a third-party fulfilment service to prepare and ship your orders for you.
`);

intent("$(QUERY* .+)", async p => {
    let answer = await api.query_v1({corpus: FAQ, question: p.QUERY.value});
    if (answer) {
        p.play(answer);
        let final = await answer.gather();
        console.log(final.summary);
        console.log(final.answer);
    } else {
        p.play(`Sorry, I cannot help you with that`);
    }
});

Here, the corpus data is saved to FAQ. The user question is captured with the QUERY slot and then passed to api.query_v1 together with the corpus data. To get the answer, the gather() method is used that collects the final response. The result is then written to Alan Studio logs.

Let’s assume you want to get an answer to a question from the FAQ data published in a web page. For this, you can add the following code to the dialog script:

Dialog script
let FAQ = corpus({url: "https://www.shopify.com/faq", depth: 1, maxPages: 10});

intent(`$(QUERY* .+)`, async p => {
    let query = p.QUERY.value;
    let answer = await api.query_v1({corpus: FAQ, question: query});
    if (answer) {
        p.play(answer);
        let final = await answer.gather();
        console.log(final.summary);
        console.log(final.answer);
    } else {
        p.play(`Sorry, I cannot help you with that`);
    }
});

Here, the corpus data is saved to FAQ. The user question is captured with the QUERY slot and then passed to api.query_v1 together with the corpus data. To get the answer, the gather() method is used that collects the final response. The result is then written to Alan Studio logs.

You can ask questions covered by the FAQ page, for example:

  • What is a merchant account?

  • How can I dropship with Shopify?

In some cases, you may need to present answers from the Q&A services transformed and formatted in a specific way. To do this, you can utilize the transforms() function in Alan AI. The transforms() function allows you to pre-process and transform input data using the templates and rules that you define. For details, see Data transformation.

Note

The transforms functionality is available in SLU 4.2 and later.

Let’s assume you want to display all answers using the following format:

Question

User query

Answer

Answer from FAQ

Steps to take

For that, do the following:

  1. Add a transform named format with the following rules:

    Example 1

    • Common prompt: The input contains the initial response provided by the AI assistant, the query contains a sample question, the result shows how the text must be formatted

    • Input: A merchant account is an account where your money is deposited after your customers’ payments have been authorized and processed. It is used to accept payments from customers and is typically provided by a third-party payment processor (also known as a payment provider or payment gateway). The payment processor will authorize and process the payments and then deposit the funds into the merchant account., input format: text

    • Query: What is a merchant account?

    • Result: example of output data, output format: markdown:

      Result field
      **Question**:
      
      What is a merchant account?
      
      **Answer**:
      
      A merchant account is an account where your money is deposited after your customers’ payments have been authorized and processed. It is used to accept payments from customers and is typically provided by a third-party payment processor (also known as a payment provider or payment gateway). The payment processor will authorize and process the payments and then deposit the funds into the merchant account.
      
      **Steps to take**
      
      - [Start a free trial](https://accounts.shopify.com/)
      - [Log in](https://accounts.shopify.com/)
      

    Example 2

    • Common prompt: The input contains the initial response provided by the AI assistant, the query contains a sample question, the result shows how the text must be formatted

    • Input: No, you don’t need to ship items yourself. You can use a third-party fulfilment service to prepare and ship your orders for you., input format: text

    • Query: Do I need to ship items myself?

    • Result: example of output data, output format: markdown:

      Result field
      **Question**:
      
      Do I need to ship items myself?
      
      **Answer**:
      
      No, you don’t need to ship items yourself. You can use a third-party fulfilment service to prepare and ship your orders for you.
      
      **Steps to take**
      
      - [Start a free trial](https://accounts.shopify.com/)
      - [Log in](https://accounts.shopify.com/)
      
    ../../../_images/query-api-transforms.png
  2. Add the following code to your dialog script:

    Dialog script
    let FAQ = corpus({url: "https://www.shopify.com/faq", depth: 1, maxPages:10});
    
    intent(`$(QUERY* .+)`, async p => {
        let query = p.QUERY.value;
        let answer = await api.query_v1({corpus: FAQ, question: query});
        if (answer) {
            let final = await answer.gather();
            let formattedAnswer = await transforms.format({
                input: final,
                query: query
            });
            p.play(formattedAnswer);
        } else {
            p.play(`Sorry, I cannot help you with that`);
        }
    });
    

Here, the corpus data is saved to FAQ. The user question is captured with the QUERY slot and then passed to api.query_v1 together with the corpus data. The answer obtained from the Query API is then formatted using the rules defined in the format transform and displayed in the Alan AI Chat:

../../../_images/query-api-transforms-example.png