Using Converse with the AI Hub SDK

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.

While the scripts in this guide use the AI Hub Python SDK, you can use the Conversations endpoint in the AI Hub API 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.

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

When uploading files to a conversation, note these limitations:

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.
Certain file types are supported.

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:

1 {
2     "id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3     "name": "Conversation 2023-08-23 11:40:30.669832",
4     "upload_status": {
5         "success": [
6             {
7                 "name": "img.pdf"
8             },
9             {
10                 "name": "file.pdf"
11             }
12         ],
13         "failure": []
14     }
15 }

Checking conversation status

After creating a conversation, use the client.conversations.status method to fet`ch 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.

1 # Pulls in the conversation ID from the previous step.
2 conversation_id = conversation.id
3 
4 # Gets status.
5 status = client.conversations.status(conversation_id)
6 
7 # Waits for the conversation to finish processing.
8 while status.state == 'RUNNING':
9   time.sleep(5)
10   status = client.conversations.status(conversation_id)
11 
12 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:

1 {
2     "id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3     "name": "Conversation 2023-08-23 11:40:30.669832",
4     "description": "",
5     "documents": [
6         {
7             "id": 15,
8             "name": "file.pdf"
9         },
10         {
11             "id": 16,
12             "name": "img.pdf"
13         }
14     ],
15     "state": "COMPLETE",
16     "status": "Documents Processed"
17 }

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.

1 # Pulls in the conversation ID from the previous step.
2 conversation_id = conversation.id
3 # Pulls in the document ID of the file at index 0 in the status object returned in the previous step.
4 document_id = status.documents[0].id
5 
6 # Query one document at a time.
7 document_ids = [document_id]
8 
9 question = "What is the main topic of the document?"
10 answer = client.conversations.converse(conversation_id=conversation_id,
11                                        question=question,
12                                        document_ids=document_ids,
13                                        mode='default') # Optional
14 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.
`mode`	string	No	The model to use to answer the question. Supports the standard (`default`) and advanced (`advanced`) models. If unspecified, the standard model is used. See Choosing a model for details about each model. The multistep model isn’t supported for queries made by API.

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 Conversations 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:

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

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.

1 from aihub import AIHub
2 import os
3 import time
4 
5 # Initializes the client. Define your API token, API root URL, and IB-Context header value.
6 client = AIHub(api_key="<API-TOKEN>",
7                api_root="<API-ROOT>",
8                ib_context="<IB-CONTEXT>")
9 
10 # Creates conversation, uploads and processes files
11 file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>'] # A list of file paths
12 conversation = client.conversations.create(name='Sample Conversation',
13                                            description='Sample Description',
14                                            org='<ORGANIZATION-ID>', # Optional for community accounts
15                                            workspace='<WORKSPACE-NAME>', # Optional for community accounts
16                                            files=file_paths)
17 
18 # Pulls in the conversation ID from the previous step.
19 conversation_id = conversation.id
20 
21 # Gets status.
22 status = client.conversations.status(conversation_id)
23 
24 # Waits for the conversation to finish processing.
25 while status.state == 'RUNNING':
26   time.sleep(5)
27   status = client.conversations.status(conversation_id)
28 
29 # Pulls in the document ID of the file at index 0 in the status object returned in the previous step.
30 document_id = status.documents[0].id
31 
32 # Query one document at a time.
33 document_ids = [document_id]
34 
35 question = "What is the main topic of the document?"
36 answer = client.conversations.converse(conversation_id=conversation_id,
37                                        question=question,
38                                        document_ids=document_ids,
39                                        mode='default') # Optional
40 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 organization accounts, otherwise optional.	Your organization. For organization members, use your organization ID.
`workspace`	string	Required for organization accounts, otherwise optional.	The name of your personal workspace, where the conversation is created. For organization members, 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.
`mode`	string	No	The model to use to answer the question. Supports the standard (`default`) and advanced (`advanced`) models. If unspecified, the standard model is used. See Choosing a model for details about each model. The multistep model isn’t supported for queries made by API.

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

1	{
2	"id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3	"name": "Conversation 2023-08-23 11:40:30.669832",
4	"upload_status": {
5	"success": [
6	{
7	"name": "img.pdf"
8	},
9	{
10	"name": "file.pdf"
11	}
12	],
13	"failure": []
14	}
15	}

1	# Pulls in the conversation ID from the previous step.
2	conversation_id = conversation.id
3
4	# Gets status.
5	status = client.conversations.status(conversation_id)
6
7	# Waits for the conversation to finish processing.
8	while status.state == 'RUNNING':
9	time.sleep(5)
10	status = client.conversations.status(conversation_id)
11
12	print(f"Conversation status: {status}")

1	{
2	"id": "f2ef9702-b018-4a45-9b2e-d1fb575b42ed",
3	"name": "Conversation 2023-08-23 11:40:30.669832",
4	"description": "",
5	"documents": [
6	{
7	"id": 15,
8	"name": "file.pdf"
9	},
10	{
11	"id": 16,
12	"name": "img.pdf"
13	}
14	],
15	"state": "COMPLETE",
16	"status": "Documents Processed"
17	}

1	# Pulls in the conversation ID from the previous step.
2	conversation_id = conversation.id
3	# Pulls in the document ID of the file at index 0 in the status object returned in the previous step.
4	document_id = status.documents[0].id
5
6	# Query one document at a time.
7	document_ids = [document_id]
8
9	question = "What is the main topic of the document?"
10	answer = client.conversations.converse(conversation_id=conversation_id,
11	question=question,
12	document_ids=document_ids,
13	mode='default') # Optional
14	print(f"Answer: {answer.answer}")

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

1	from aihub import AIHub
2	import os
3	import time
4
5	# Initializes the client. Define your API token, API root URL, and IB-Context header value.
6	client = AIHub(api_key="<API-TOKEN>",
7	api_root="<API-ROOT>",
8	ib_context="<IB-CONTEXT>")
9
10	# Creates conversation, uploads and processes files
11	file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>'] # A list of file paths
12	conversation = client.conversations.create(name='Sample Conversation',
13	description='Sample Description',
14	org='<ORGANIZATION-ID>', # Optional for community accounts
15	workspace='<WORKSPACE-NAME>', # Optional for community accounts
16	files=file_paths)
17
18	# Pulls in the conversation ID from the previous step.
19	conversation_id = conversation.id
20
21	# Gets status.
22	status = client.conversations.status(conversation_id)
23
24	# Waits for the conversation to finish processing.
25	while status.state == 'RUNNING':
26	time.sleep(5)
27	status = client.conversations.status(conversation_id)
28
29	# Pulls in the document ID of the file at index 0 in the status object returned in the previous step.
30	document_id = status.documents[0].id
31
32	# Query one document at a time.
33	document_ids = [document_id]
34
35	question = "What is the main topic of the document?"
36	answer = client.conversations.converse(conversation_id=conversation_id,
37	question=question,
38	document_ids=document_ids,
39	mode='default') # Optional
40	print(f"Answer: {answer.answer}")