Using Converse with the AI Hub SDK

Table of Contents

With the AI Hub software development kit (SDK), you can integrate the ability to chat with documents into your workflow. You can create a new Converse conversation, upload files to the conversation, and converse with your uploaded files. This guide includes a complete script you can reference to create your own complete workflow.

Note

While the scripts in this guide use the AI Hub Python SDK, you can use the AI Hub API’s Conversations endpoint to do the same in any scripting language.

Before you begin

Review the developer quickstart and install the AI Hub SDK.

Creating a conversation with your files

To start, create a Converse conversation and upload files using the client.conversations.create method.

# Creates conversation, uploads and processes files
file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>'] # A list of file paths
conversation = client.conversations.create(name='Sample Conversation',
                                           description='Sample Description',
                                           org='<ORGANIZATION-ID>', # Optional for community accounts
                                           workspace='<WORKSPACE-NAME>', # Optional for community accounts
                                           files=file_paths)

Define the following values in the script:

Parameter	Type	Required	Description
`name`	string	Yes	Name of the conversation.
`description`	string	Yes	Description of the conversation.
`file_paths`	list	Yes	A list of local file paths of files to upload to the conversation.

See the Conversations endpoint for more supported parameters and information, including how to enable object detection.

Note

There are some limitations when uploading files to a conversation:

Files can be up to 50 MB or 800 pages.
You can upload up to 100 MB per request.
You can have up to 100 documents per conversation.
There are specific supported file types.

When run, the method performs the following tasks:

Creates the conversation in your personal workspace.
Uploads the listed files to the conversation.
Processes the files, digitizing and indexing them for the conversation.
Returns the conversation ID, conversation name, and upload status in JSON format. For example:

{
    "id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
    "name": "Conversation 2023-08-23 11:40:30.669832",
    "upload_status": {
        "success": [
            {
                "name": "img.pdf"
            },
            {
                "name": "file.pdf"
            }
        ],
        "failure": []
    }
}

Checking conversation status

After creating a conversation, use the client.conversations.status method to fetch the status of the conversation. This step lets you check if the document processing stage is complete; when complete, you can start conversing with your documents.

# Pulls in the conversation ID from the previous step.
conversation_id = conversation.id

# Gets status.
status = client.conversations.status(conversation_id)

# Waits for the conversation to finish processing.
while status.state == 'RUNNING':
  time.sleep(5)
  status = client.conversations.status(conversation_id)

print(f"Conversation status: {status}")

The response is a status object, which contains information about the conversation and its processing status, according to the following schema:

Key	Type	Description
`id`	string	A unique identifier for the conversation.
`name`	string	The name of the conversation.
`description`	string	A description of the conversation.
`state`	string	The state of the conversation: - `COMPLETE`: Ready to start a conversation. - `FAILED`: Not able process any of the uploaded files. - `RUNNING`: Still processing the uploaded files.
`documents`	list	A list of all uploaded and processed documents in the conversation.
`documents/id`	integer	The uploaded document’s ID. Use this value when conversing with a document to specify the document to query.
`documents/name`	string	The name of the document.

For example:

{
    "id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
    "name": "Conversation 2023-08-23 11:40:30.669832",
    "description": "",
    "documents": [
        {
            "id": 15,
            "name": "file.pdf"
        },
        {
            "id": 16,
            "name": "img.pdf"
        }
    ],
    "state": "COMPLETE",
    "status": "Documents Processed"
}

Conversing with a document

When all documents are finished processing and the conversation state is COMPLETE, you can start conversing with an uploaded document using the client.conversations.converse method. You can converse with one document at a time by API.

# Pulls in the conversation ID from the previous step.
conversation_id = conversation.id 
# Pulls in the document ID of the file at index 0 in the status object returned in the previous step. 
document_id = status.documents[0].id 

# Query one document at a time.
document_ids = [document_id]

question = "What is the main topic of the document?"
answer = client.conversations.converse(conversation_id=conversation_id,
                                       question=question,
                                       document_ids=document_ids)
print(f"Answer: {answer.answer}")

User-defined parameters in this request include:

Parameter	Type	Required	Description
`question`	string	Yes	An input prompt. This can include any question or request supported by Converse, except for plot graphs.

Note

The example script pulls in a document ID from the conversation status object returned in the previous step. If you want to query a specific document, define the document_id value. See the Converse with a document endpoint for details.

When run, the example script queries the document with your question and returns the answer, along with a prompt ID. For example:

{
   "prompt_id": "5b7057f8e3a04cc3a68e092bef78927e",
   "answer": "The document is a receipt for an Uber trip on March 25, 2024."
}

Complete workflow

This example Python script shows a complete, end-to-end workflow based on calls to AI Hub API using the AI Hub SDK. When run, this script performs the following tasks:

Initializes the API client.
Creates a conversation and uploads files to the conversation.
Checks the processing status of the uploaded files.
When processing is complete, queries a document with the provided question.
Returns the answer to the question in JSON format.

from aihub import AIHub
import os
import time

# Initializes the client. Define your API token, API root URL, and IB-Context header value.
client = AIHub(api_key="<API-TOKEN>", api_root="<API-ROOT>", ib_context="<IB-CONTEXT>")

# Creates conversation, uploads and processes files
file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>'] # A list of file paths
conversation = client.conversations.create(name='Sample Conversation',
                                           description='Sample Description',
                                           org='<ORGANIZATION-ID>', # Optional for community accounts
                                           workspace='<WORKSPACE-NAME>', # Optional for community accounts
                                           files=file_paths)

# Pulls in the conversation ID from the previous step.
conversation_id = conversation.id

# Gets status.
status = client.conversations.status(conversation_id)

# Waits for the conversation to finish processing.
while status.state == 'RUNNING':
  time.sleep(5)
  status = client.conversations.status(conversation_id)

# Pulls in the document ID of the file at index 0 in the status object returned in the previous step. 
document_id = status.documents[0].id 

# Query one document at a time.
document_ids = [document_id]

question = "What is the main topic of the document?"
answer = client.conversations.converse(conversation_id=conversation_id,
                                       question=question,
                                       document_ids=document_ids)
print(f"Answer: {answer.answer}")

User-defined values

To recap, this tables outlines all values in the complete script that can or must be defined.

Parameter or variable	Type	Required	Description
`<API-TOKEN>`	string	Yes	Your API token. Used when initializing the API client.
`<API-ROOT>`	string	No	Defaults to `https://aihub.instabase.com/api`. Used when initializing the API client.
`<IB-CONTEXT>`	string	No, but recommended.	Defaults to your user ID. If undefined, requests are made with your community account. Used when initializing the API client.
`name`	string	Yes	Name of the conversation.
`description`	string	Yes	Description of the conversation.
`org`	string	Required for commercial accounts, otherwise optional.	Your organization. For commercial users, your organization is `<ORGANIZATION-ID>`.
`workspace`	string	Required for commercial accounts, otherwise optional.	The name of your personal workspace, where the conversation is created. For commercial users, your personal workspace name is your user ID.
`file_paths`	list	Yes	A list of local file paths of files to upload to the conversation.
`question`	string	Yes	An input prompt. This can include any question or request supported by Converse, except for plot graphs.