Analyze use case

Import and authorize the SDK

Just like for the automate use case, start your program by making the SDK available and configuring authorization details.

1
from aihub import AIHub
2
3
client = AIHub(api_root="PASTE YOUR API ROOT HERE",
4
               api_key="PASTE YOUR API KEY HERE",
5
               ib_context="PASTE YOUR IB-CONTEXT HERE")

Download files to analyze

Download two PDF files so you can upload them to the conversation later.

Create a conversation with one file

When you created a batch in the previous use case, you made the batch with one SDK operation, and you uploaded files to it with a separate SDK operation. Creating a conversation is different: you use a single SDK operation to create the conversation and upload files to it (although you can add more files later).

This example creates a conversation with a single file called A330_specs.pdf, which you downloaded earlier.

1
create_conversation_resp = client.conversations.create(
2
    name="Airbus conversation",
3
    description="Analyze Airbus technical specs",
4
    org="PASTE YOUR IB-CONTEXT HERE",
5
    workspace="SDK-Tutorial",
6
    files=["PATH/TO/A330_specs.pdf"])

Wait for the document to be processed

When you create a conversation, AI Hub processes any documents you included in the conversation so that it’s prepared to answer questions about them. The information-rich, three-page PDF you included in the conversation could take up to 30 seconds to process.

This code snippet repeatedly polls the status of the conversation until it’s finished processing any documents the conversation contains.

1
import time
2
while True:
3
    time.sleep(3)
4
    status_resp = client.conversations.status(
5
        create_conversation_resp.id)
6
    print(f"document #1 processing status: {status_resp.state}")
7
    if status_resp.state == "COMPLETE":
8
        break

Line 1 makes Python’s time library available so you can pause the program between status checks.

Line 2 starts a loop for checking document processing status. The loop stops when processing is done.

Line 3 pauses for a few seconds to give AI Hub a chance to make progress on processing the document.

Lines 4 and 5 call an SDK method to check on the document processing status, passing in the conversation’s ID.

Lines 6 prints the status.

Lines 7 and 8 break out of the loop if AI Hub has finished processing the document.

Get the document ID

When you send a question to an AI Hub conversation, you have to tell AI Hub two things.

• Which conversation is the question directed at?

• Which documents within the conversation does AI Hub consider when coming up with an answer?

The second task uses document IDs. This code looks in the response to the last processing status query and extracts the ID of the one document you uploaded along with the conversation.

1
first_document_id = status_resp.documents[0].id

Submit a question to one document

Now you’re ready to analyze the document by asking AI Hub questions about it—or as AI Hub sometimes calls it, conversing with the document.

1
converse_resp = client.conversations.converse(
2
    conversation_id=create_conversation_resp.id,
3
    question="What airplane family are these specs for?",
4
    document_ids=[first_document_id])

Print the answer

The client.conversations.converse() method is synchronous, which means an answer is provided in the method’s response. There’s no need to check the conversation’s processing status or make another call to retrieve the answer.

1
print(f"answer: {converse_resp.answer}")

Upload another document to the conversation

As you learned earlier, a conversation can have more than one document associated with it. Upload a second document containing technical specs for a different family of Airbus airplanes.

1
add_documents_resp = client.conversations.add_documents(
2
    conversation_id=create_conversation_resp.id,
3
    files=["PATH/TO/A350_specs.pdf"])

Wait for the second document to be processed

You need to wait for the new document to be processed before you can send a question to the conversation. This code uses the same technique you used while waiting for the first document to be processed.

1
while True:
2
    time.sleep(3)
3
    status_resp = client.conversations.status(
4
        create_conversation_resp.id)
5
    print(f"document #2 processing status: {status_resp.state}")
6
    if status_resp.state == "COMPLETE":
7
        break

Send a question to both documents asynchronously

Both documents are processed, so now you can send a question that requires AI Hub to consider the contents of both documents when answering.

1
query = "List all Airbus planes by ascending wingspan."
2
source_app = {"type": "CONVERSE",
3
              "id": create_conversation_resp.id}
4
run_query_resp = client.queries.run(query=query,
5
                                    source_app=source_app)

Line 1 defines the question you want AI Hub to answer.

Lines 2 and 3 tell AI Hub whether to direct the question to a conversation or a chatbot, and specify the conversation or chatbot ID.

Lines 5 and 6 submit the question.

Wait for the conversation to have an answer

Because multi-document queries are asynchronous, you need to check the status of your question until AI Hub comes up with an answer.

1
while True:
2
    time.sleep(3)
3
    query_status_resp = client.queries.status(
4
        query_id=run_query_resp.query_id)
5
    print(f"query status: {query_status_resp.status}")
6
    if query_status_resp.status == "COMPLETE":
7
        break

Line 1 starts a loop that stops when AI Hub has an answer ready.

Line 2 pauses for a few seconds to give AI Hub time to process your question.

Lines 3 and 4 ask AI Hub for the status of the query, using its ID.

Line 5 prints the most recent query status.

Lines 6 and 7 break out of the loop when the status is COMPLETE.

Retrieve and print the answer

When AI Hub responds to your client.queries.status() call with a status of COMPLETE, that response includes a field called results that contains the answer to your question. Now you just have to extract and print it.

The results field holds a list of results. Depending on what questions you ask and how many documents are in the conversation, the list might contain one result or it might contain more. In this example there’s only one result, but it’s always safest to iterate through the list and print each result.

1
for result in query_status_resp.results:
2
    print(f"answer: {result.response}")

Run the SDK-enabled program

You’ve now seen all the code for this use case. It’s time to run it.

1. If you haven’t been entering the code into a file on your computer called analyze_with_sdk.py, do so now.

2. Run it the same way you ran automate_with_sdk.py, following the instructions for your operating system.

   Linux

   macOS

   Windows

   1. Open a terminal.

   2. Type cd PATH/TO/DIRECTORY/WITH/analyze_with_sdk.py, replacing the placeholders with the path to wherever you stored analyze_with_sdk.py.

   3. Type python3 analyze_with_sdk.py.

Your output looks similar to this. Results might vary due to randomness inherent in AI.

answer: Based on the information from the documents,
here are the Airbus planes listed by ascending wingspan:
1. A330-200, A330-300, A330-200F, A330-200P2F, A330-300P2F: 60.30 meters
2. A330-800, A330-900: 64.00 meters
3. A350-900, A350-1000: 64.75 meters
This list includes the wingspan details for the A330 and A350
families as provided in the documents.

Add exception handling

Just as with the automate use case you looked at earlier, there are many possible problems you could address in this program. Here’s just one.

In step 11 you called the client.queries.status() method to check if AI Hub was finished generating an answer to your question. You stop checking when the status is COMPLETE, but you can also stop checking if something goes wrong and the status is FAILED.

In this snippet, lines 1 through 7 are already in your program, near the end.

Add lines 8 through 10 to handle FAILED processing status.

1
while True:
2
    time.sleep(3)
3
    query_status_resp = client.queries.status(
4
        query_id=run_query_resp.query_id)
5
    print(f"query status: {query_status_resp.status}")
6
    if query_status_resp.status == "COMPLETE":
7
        break
8
    if query_status_resp.status == "FAILED":
9
        import sys
10
        sys.exit("ERROR: AI Hub couldn't process this query")