Converse by SDK — Instabase Documentation

The conversations endpoint lets you chat with documents programmatically instead of using the graphical interface. You can create a new Converse conversation, upload files to the conversation, and converse with your uploaded files.

This guide explains how to access the conversations endpoint with the Python SDK. All code snippets are also presented at the end of this guide as a complete script. Use that as a model when writing your own scripts to have conversations with documents.

Before you begin

Learn about the API and SDK and install the SDK.

Import modules and initialize the API client

Import key Python modules.

1 import time
2 
3 from aihub import AIHub

Initialize a client that lets you interact with the AI Hub API through Python objects and methods.

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

Parameter reference

Parameter	Type	Value	Description
`api_root`	str	No	The root URL of your AI Hub API. For community accounts • Omit setting `api_root`. For 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`.
`api_key`	str	Yes	Your API token.
`ib_context`	str	No, but recommended	The value for the `IB-Context` header that the SDK includes with all API requests. For community accounts • Omit setting `ib_context`. For commercial accounts • To use your personal account, set to your user ID. • To use your organization account, set to your organization ID. If `ib_context` isn’t explicitly set, requests use consumption units from your community account.

Create a conversation and upload files

Create a conversation and upload files to it with one method call.

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>])

Parameter reference

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 `org` 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 if there’s only one path.	`['docs/passport1.pdf']`

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

Files uploaded to a conversation have 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 performs several tasks.

Create the conversation in the specified 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.

Key	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 document processing state

Repeatedly check the state of document processing until it’s COMPLETE.

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.

Key	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 the ID 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.

Converse with a document

When the document processing state is COMPLETE, all documents are processed and the conversation is ready to accept prompts to one or more uploaded documents.

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}')

Parameter reference

Parameter	Type	Required	Description	Example
`question`	str	Yes	An input prompt. The prompt 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`

After the script sends the prompt to your conversation, AI Hub 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.

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

Complete script

This script combines all the snippets from above and contains all the code needed to converse with documents using the SDK.

The script performs these tasks:

Import modules and Initialize the API client.
Create a conversation and upload documents to the conversation.
Check the processing status of the uploaded files.
When processing is complete, 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_root=<API-ROOT>,
7                api_key=<API-TOKEN>,
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 # send prompt and get answer
25 answer = client.conversations.converse(conversation_id=conversation.id,
26                                        question=<QUESTION>,
27                                        document_ids=<DOCUMENT-IDS>,
28                                        mode=<MODE>)  # optional
29 print(f'Answer: {answer.answer}')

Parameter reference

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

Parameter	Type	Required	Description
`api_root`	str	No	The root URL of your AI Hub API. For community accounts • Omit setting `api_root`. For 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`.
`api_key`	str	Yes	Your API token.
`ib_context`	str	No, but recommended	The value for the `IB-Context` header that the SDK includes with all API requests. For community accounts • Omit setting `ib_context`. For commercial accounts • To use your personal account, set to your user ID. • To use your organization account, set to your organization ID. 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 `org` 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 if 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. The prompt 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_root=<API-ROOT>,
3	api_key=<API-TOKEN>,
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	# 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_root=<API-ROOT>,
7	api_key=<API-TOKEN>,
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	# send prompt and get answer
25	answer = client.conversations.converse(conversation_id=conversation.id,
26	question=<QUESTION>,
27	document_ids=<DOCUMENT-IDS>,
28	mode=<MODE>) # optional
29	print(f'Answer: {answer.answer}')