Converse by SDK — Instabase Documentation

With the AI Hub software development kit (SDK), you can write a Python script to chat with documents programmatically instead of using the graphical interface or sending API calls. You can create a new Converse conversation, upload files to the conversation, and converse with your uploaded files.

This guide includes a complete script to use as a model when writing Python scripts for having conversations.

While the scripts in this guide use the AI Hub Python SDK, you can use the AI Hub API conversations endpoint to do the same in any programming language.

Before you begin

Review the developer quickstart and then install the AI Hub SDK.

Import modules and initialize the client

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

1 import time
2 
3 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>)

Create a conversation with your files

Create a conversation and upload files to it using the client.conversations.create() method.

1 # create conversation and upload files to it
2 conversation = client.conversations.create(
3     name=<NAME>,
4     description=<DESCRIPTION>,
5     org=<ORGANIZATION-ID>,  # optional for community accounts
6     workspace=<WORKSPACE>,  # optional for community accounts
7     files=[<PATH/TO/FILE1>, <PATH/TO/FILE2>])

User-defined values

Placeholder	Type	Required	Description	Example
`name`	str	Yes	Name of the conversation.	`Passport analysis`
`description`	str	Yes	Description of the conversation.	`ask questions about passport contents`
`org`	str	No	Default value uses consumption units from the community account associated with your username. Setting this to the ID of an organization associated with your username uses consumption units from that organization.	`Dept of Border Control`
`workspace`	str	Required for organization accounts, otherwise optional	Name of the workspace to create the conversation in. For organization members, your personal workspace name is your user ID.	`Production`
`files`	list[str]	Yes	Paths to local files to upload to the conversation. To add multiple documents to the conversation, use a separate path for each document. All paths are collected in a list, even when there’s only one path.	`['docs/passport1.pdf']`

See the conversations endpoint for more supported parameters and information, including instructions for enabling object detection.

When uploading files to a conversation, note these limitations:

Each document can be up to 50 MB and up to 800 pages.
Each request can upload up to 100 MB worth of documents.
A conversation can have up to 100 uploaded documents.
Certain file types are supported.

The client.conversations.create() method in the snippet above performs these tasks:

Create the conversation in your personal workspace.
Upload files to the conversation.
Digitize and index the files.

Return the conversation ID, conversation name, and upload status as a JSON object, 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 }

Response schema

When the JSON object is converted into a Python dictionary, it has this schema.

Field	Python type	Description
`id`	str	unique identifier for the conversation
`name`	str	name of the conversation
`upload_status`	object	information about file upload statuses
`upload_status.failure`	list[object]	information about files that failed to upload
`upload_status.success`	list[object]	information about uploaded files
`upload_status.failure[i]`	object	information about a single failed file upload
`upload_status.success[i]`	object	information about a single uploaded file
`upload_status.failure[i].name`	str	name of a failed file upload
`upload_status.success[i].name`	str	name of an uploaded file

Notes about the schema

i in [i] represents any valid array index, such as 0, 1, or 2.
Array indices are zero-based, so upload_status.success[2].name gives the name of the third file uploaded.
.id, .name, and .upload_status.success[i].name are the most commonly used fields.

Check conversation status

Use the client.conversations.status() method to check if document processing is complete. After it has finished, you can converse with your documents.

1 # wait for the conversation to finish processing the documents
2 status = client.conversations.status(conversation.id)
3 while status.state == 'RUNNING':
4     time.sleep(5)  # polling interval in seconds
5     status = client.conversations.status(conversation.id)

client.conversations.status() returns a JSON object with information about the conversation and its document upload and processing status. 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 }

Response schema

When the JSON object is converted into a Python dictionary, it has this schema.

Field	Type	Description
`description`	str	description of the conversation you provided when creating it
`documents`	list[object]	list of the conversation’s documents that have been both uploaded and processed
`documents[i].id`	int	ID of a single uploaded document. Use this value when conversing with a document to specify which documents to query.
`documents[i].name`	str	name of a single uploaded document
`id`	str	ID of the conversation
`name`	str	name of the conversation you provided when creating it
`state`	str	state of the conversation’s document processing stage: - `COMPLETE`: ready to converse with the documents - `FAILED`: unable to process some uploaded files - `RUNNING`: still processing uploaded files

Notes about the object schema

i in [i] represents any valid array index, such as 0, 1, or 2.
Array indices are zero-based, so documents[2].name gives the name of the third file uploaded.

Collect document IDs

When your conversation reaches the COMPLETE state, all documents have been processed and the conversation is ready to accept prompts to one or more uploaded documents via the client.conversations.converse() method.

But before submitting a prompt, you must get the document ID for each document you uploaded to the conversation so you can direct prompts to the right documents.

1 # collect document IDs
2 document_ids = [document.id for document in status.documents]

Converse with a document

Submit your query to one or more of the documents you uploaded.

The SDK officially supports queries directed at a single document only.

However, queries directed at multiple documents (like the example shown here) often work as expected.

If you see errors or timeouts while sending a query to multiple documents, make separate queries to each document instead.

1 # send prompt and get answer
2 answer = client.conversations.converse(conversation_id=conversation.id,
3                                        question=<QUESTION>,
4                                        document_ids=<DOCUMENT-IDS>,
5                                        mode=<MODE>)  # optional
6 print(f'Answer: {answer.answer}')

User-defined values

Parameter	Type	Required	Description	Example
`question`	str	Yes	An input prompt. This can include any question supported by Converse, except for requests for graphs.	`What countries are these passports from?`
`document_ids`	list[str]	Yes	One or more documents to send the prompt to. Must be a list, even if it specifies only one document ID.	`[status.documents[0].id, status.documents[1].id]`
`mode`	str	No	The model to use when answering the question. Valid values: - `default`: the standard model - `advanced`: the slower, more expensive advanced model If omitted, the standard model is used. See Choosing a model for details about each model. The multistep model isn’t supported for API queries.	`advanced`

The script sends the prompt to your documents and returns a JSON object, for example:

1 {
2    "prompt_id": "5b7057f8e3a04cc3a68e092bef78927e",
3    "answer": "Both passports are from Indonesia."
4 }

Response schema

When the JSON object is converted into a Python dictionary, it has this schema.

Field	Type	Description	Example
`answer`	str	response to the question	`Both passports are from Indonesia.`
`prompt_id`	str	ID for the question submitted	`5b7057f8e3a04cc3a68e092bef78927e`

Complete workflow

This script demonstrates a complete, end-to-end workflow using the AI Hub SDK. It combines all the snippets from above.

The script performs these tasks:

Initialize the API client.
Create a conversation and upload two documents to the conversation.
Check the processing status of the uploaded files.
When processing is complete, collect the document IDs of the uploaded files.
Send a prompt that draws on information from both documents.
Print the answer.

1 import time
2 
3 from aihub import AIHub
4 
5 # initialize the SDK client
6 client = AIHub(api_key=<API-TOKEN>,
7                api_root=<API-ROOT>,
8                ib_context=<IB-CONTEXT>)
9 
10 # create conversation and upload files to it
11 conversation = client.conversations.create(
12     name=<NAME>,
13     description=<DESCRIPTION>,
14     org=<ORGANIZATION-ID>,  # optional for community accounts
15     workspace=<WORKSPACE>,  # optional for community accounts
16     files=[<PATH/TO/FILE1>, <PATH/TO/FILE2>])
17 
18 # wait for the conversation to finish processing the documents
19 status = client.conversations.status(conversation.id)
20 while status.state == 'RUNNING':
21     time.sleep(5)  # polling interval in seconds
22     status = client.conversations.status(conversation.id)
23 
24 # collect document IDs
25 document_ids = [document.id for document in status.documents]
26 
27 # send prompt and get answer
28 answer = client.conversations.converse(conversation_id=conversation.id,
29                                        question=<QUESTION>,
30                                        document_ids=<DOCUMENT-IDS>,
31                                        mode=<MODE>)  # optional
32 print(f'Answer: {answer.answer}')

User-defined values

This table describes all placeholders in the complete script that can or must be defined.

Placeholder	Type	Required	Description
`api_token`	str	Yes	Your API token. Used when initializing the API client.
`api_root`	str	No	Your AI Hub root URL. Used when initializing the API client. Community accounts: omit setting `api_root`. Organization accounts: - If your organization has a custom AI Hub domain, use your organization’s root API URL, such as `https://my-org.instabase.com/api`. - If your organization doesn’t have a custom AI Hub domain, omit setting `api_root`.
`ib_context`	str	No, but recommended	Used when initializing the API client. If `ib_context` isn’t explicitly set, requests use consumption units from your community account.
`name`	str	Yes	Name of the conversation.
`description`	str	Yes	Description of the conversation.
`org`	str	No	Default value uses consumption units from the community account associated with your username. Setting this to the ID of an organization associated with your username uses consumption units from that organization.
`workspace`	str	Required for organization accounts, otherwise optional	Name of the workspace to create the conversation in. For organization members, your personal workspace name is your user ID.
`files`	list[str]	Yes	Paths to local files to upload to the conversation. To add multiple documents to the conversation, use a separate path for each document. All paths are collected in a list, even when there’s only one path.
`document_ids`	list[str]	Yes	One or more documents to send the prompt to. Must be a list, even if it specifies only one document ID.
`question`	str	Yes	An input prompt. This can include any question supported by Converse, except for requests for graphs.
`mode`	str	No	The model to use when answering the question. Valid values: - `default`: the standard model - `advanced`: the slower, more expensive advanced model If omitted, the standard model is used. See Choosing a model for details about each model. The multistep model isn’t supported for API queries.

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

1	# create conversation and upload files to it
2	conversation = client.conversations.create(
3	name=<NAME>,
4	description=<DESCRIPTION>,
5	org=<ORGANIZATION-ID>, # optional for community accounts
6	workspace=<WORKSPACE>, # optional for community accounts
7	files=[<PATH/TO/FILE1>, <PATH/TO/FILE2>])

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	# wait for the conversation to finish processing the documents
2	status = client.conversations.status(conversation.id)
3	while status.state == 'RUNNING':
4	time.sleep(5) # polling interval in seconds
5	status = client.conversations.status(conversation.id)

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	# collect document IDs
2	document_ids = [document.id for document in status.documents]

1	# send prompt and get answer
2	answer = client.conversations.converse(conversation_id=conversation.id,
3	question=<QUESTION>,
4	document_ids=<DOCUMENT-IDS>,
5	mode=<MODE>) # optional
6	print(f'Answer: {answer.answer}')

1	{
2	"prompt_id": "5b7057f8e3a04cc3a68e092bef78927e",
3	"answer": "Both passports are from Indonesia."
4	}

1	import time
2
3	from aihub import AIHub
4
5	# initialize the SDK client
6	client = AIHub(api_key=<API-TOKEN>,
7	api_root=<API-ROOT>,
8	ib_context=<IB-CONTEXT>)
9
10	# create conversation and upload files to it
11	conversation = client.conversations.create(
12	name=<NAME>,
13	description=<DESCRIPTION>,
14	org=<ORGANIZATION-ID>, # optional for community accounts
15	workspace=<WORKSPACE>, # optional for community accounts
16	files=[<PATH/TO/FILE1>, <PATH/TO/FILE2>])
17
18	# wait for the conversation to finish processing the documents
19	status = client.conversations.status(conversation.id)
20	while status.state == 'RUNNING':
21	time.sleep(5) # polling interval in seconds
22	status = client.conversations.status(conversation.id)
23
24	# collect document IDs
25	document_ids = [document.id for document in status.documents]
26
27	# send prompt and get answer
28	answer = client.conversations.converse(conversation_id=conversation.id,
29	question=<QUESTION>,
30	document_ids=<DOCUMENT-IDS>,
31	mode=<MODE>) # optional
32	print(f'Answer: {answer.answer}')