Chatbot queries by SDK

Import modules and initialize the client

The first step of using the SDK is to import key Python modules.

1
import sys
2
import time
3
4
from aihub import AIHub

Next, initialize a client that lets you interact with the AI Hub API. For information on what values to use for the parameters, see the Developer quickstart.

1
# initialize the SDK client
2
client = AIHub(api_key=<API-TOKEN>,
3
               api_root=<API-ROOT>,
4
               ib_context=<IB-CONTEXT>)

Provide the chatbot ID

Identify the chatbot to query by providing its unique ID in a Python dictionary.

1
# provide the chatbot ID
2
source_app = {'type': 'CHATBOT',
3
              'id':   <CHATBOT-ID>}

For chatbot queries, the type key must have the string CHATBOT as its value.

The value for <CHATBOT-ID> is in the chatbot URL. The chatbot ID is the 36-character string at the end of the URL, excluding the slash at the beginning of the string.

To find the chatbot’s URL, navigate to Hub and run the chatbot you want to send queries to.

Send a query to the chatbot

You’re ready to send a query to the chatbot. It can handle any query that you might use with the graphical user interface, except for requests for graphs.

As part of the query, you can tell the chatbot which model to use when coming up with a reply.

You also need to specify whether to include information on which of the chatbot’s knowledge base documents contributed to its reply.

1
# send a query to the chatbot
2
response = client.queries.run(query=<QUERY>,
3
                              source_app=source_app,
4
                              model_name=<MODEL-NAME>,
5
                              include_source_info=<INCLUDE_SOURCE-INFO>)
6
7
# need query_id to check the query's status and get an answer
8
query_id = response.query_id

User-defined values

Check the query processing status

After you submit the query, repeatedly check the query’s status with client.queries.status(<QUERY-ID>).status so you can tell when a response is ready. Three statuses are possible:

• RUNNING - the chatbot is still processing the query.

• COMPLETE - the chatbot has finished processing the query and has a reply.

• FAILED - something went wrong. Try resubmitting the query.

1
# check query status until an answer is ready
2
TIMEOUT_SECS = 60  # how long to wait for query processing before failing
3
POLLING_INTERVAL_SECS = 5  # how often to check the query processing status
4
total_wait_time_secs = 0
5
6
status_response = client.queries.status(query_id)
7
while status_response.status == 'RUNNING':
8
    if total_wait_time_secs < TIMEOUT_SECS:
9
        time.sleep(POLLING_INTERVAL_SECS)
10
        total_wait_time_secs += POLLING_INTERVAL_SECS
11
        status_response = client.queries.status(query_id)
12
    else:
13
        sys.exit(f"Error: query still processing after {TIMEOUT_SECS} seconds")

Parse the reply

When a response’s status is COMPLETE you can extract the chatbot’s reply from the response.

If you asked for source information when submitting your query, you can also extract details about which documents contributed to the reply.

1
# parse chatbot answer
2
if status_response.status == 'COMPLETE':
3
    for result in status_response.results:
4
        print(f"Answer: {result.response}")
5
        for source_document in result.source_documents:
6
            print(f"Source: {source_document.name}, "
7
                  f"Pages: {source_document.pages}")
8
elif status_response.status == 'FAILED':
9
    sys.exit(f"Error: {status_response.error}")
10
else:
11
    sys.exit(f"Unknown status: {status_response.status}")