Run apps by SDK — Instabase Documentation

With the AI Hub software development kit (SDK), you can write a Python script to create an end-to-end solution and integrate it with existing upstream and downstream workflows. From uploading files to running an app, you can use the SDK to create a complete AI Hub document-processing solution.

This guide includes a complete script to use as a model for creating your own workflow.

The script in this guide uses the AI Hub SDK, but you can use the AI Hub API instead. For guidance, see the batches and runs endpoints, or try out the API runner tool in the AI Hub interface.

About the API runner tool...

Before you begin

Review the developer quickstart and 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 os
2 import time
3 
4 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>)

Upload files to a batch

You can create a batch of files to use as input for your app run. You can add and remove files from the batch, but the batch ID remains constant so you can repeatedly use all files in the batch as app input. For more information, see the batches endpoint.

Below the code you wrote to initialize the client, create a batch with client.batches.create() and upload files to it with client.batches.add_file().

1 # create a batch
2 batch = client.batches.create(name=<BATCH-NAME>)
3 
4 # add files to the batch
5 file_paths = [<PATH/TO/FILE1>, <PATH/TO/FILE2>]
6 for path in file_paths:
7     with open(file_path, 'rb') as file:
8         client.batches.add_file(batch_id=batch.id,
9                                 file_name=os.path.basename(path),
10                                 file=file)

User-defined values

Value	Type	Required	Description
`batch`	str	Yes	User-generated name of the batch. Maximum length is 255 characters.
`file_paths`	list[str]	Yes	Paths to one or more local files to upload to the batch. Each path is a separate string. All paths are collected in a list, even when there’s only one path.

Process files through an AI Hub app

After uploading your files to a batch, you can process them using an AI Hub app. With the SDK, you can run the app, check the status of your app run, and when the run is complete, get the run results. For more information, see the runs endpoint.

This section of the script runs the app with the batch you created as input, checks the status of the app run, and gets the results.

1 run = client.apps.runs.create(app_name='<APP-NAME>',
2                               owner='<OWNER>',
3                               batch_id=batch.id)
4 
5 # repeatedly check run status until run is complete
6 status = client.apps.runs.status(run.id)
7 while status.status == 'RUNNING':
8     time.sleep(5)  # polling interval in seconds
9     status = client.apps.runs.status(run.id)
10 
11 # get app run results
12 results = client.apps.runs.results(run.id)

User-defined values

Parameter	Type	Required	Description
`app_name`	str	Yes	The name of the AI Hub app to process the files in the batch.
`owner`	str	No	The account that generated the app. - For apps you created: omit setting `owner`. - For apps published by Instabase: specify `instabase`.

You don’t need to define the batch.id or run.id values in this section of the script, because they’re passed through from the results of the previous step.

For more information about customizing an app run, including using webhooks, see the runs endpoint.

Complete script

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 batch object and upload files to the batch.
Run the specified app using the batch as input.
Poll the app run status until the run is complete.
Return app run results as an object that can be converted into a Python dictionary. See the get run results endpoint for an example of app run results.

1 import os
2 import time
3 
4 from aihub import AIHub
5 
6 # initialize the SDK client
7 client = AIHub(api_key=<API-TOKEN>,
8                api_root=<API-ROOT>,
9                ib_context=<IB-CONTEXT>)
10 
11 # create a batch
12 batch = client.batches.create(name=<BATCH-NAME>)
13 
14 # add files to the batch
15 file_paths = [<PATH/TO/FILE1>, <PATH/TO/FILE2>]
16 for path in file_paths:
17     with open(file_path, 'rb') as file:
18         client.batches.add_file(batch_id=batch.id,
19                                 file_name=os.path.basename(path),
20                                 file=file)
21 
22 run = client.apps.runs.create(app_name='<APP-NAME>',
23                               owner='<OWNER>',
24                               batch_id=batch.id)
25 
26 # repeatedly check run status until run is complete
27 status = client.apps.runs.status(run.id)
28 while status.status == 'RUNNING':
29     time.sleep(5)  # polling interval in seconds
30     status = client.apps.runs.status(run.id)
31 
32 # get app run results
33 results = client.apps.runs.results(run.id)

User-defined values

Value	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.
`batch`	str	Yes	User-generated name of the batch. Maximum length is 255 characters.
`file_paths`	list[str]	Yes	Paths to one or more local files to upload to the batch. Each path is a separate string. All paths are collected in a list, even when there’s only one path.
`app_name`	str	Yes	The name of the AI Hub app to process the files in the batch.
`owner`	str	No	The account that generated the app. - For apps you created: omit setting `owner`. - For apps published by Instabase: specify `instabase`.

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

1	# create a batch
2	batch = client.batches.create(name=<BATCH-NAME>)
3
4	# add files to the batch
5	file_paths = [<PATH/TO/FILE1>, <PATH/TO/FILE2>]
6	for path in file_paths:
7	with open(file_path, 'rb') as file:
8	client.batches.add_file(batch_id=batch.id,
9	file_name=os.path.basename(path),
10	file=file)

1	run = client.apps.runs.create(app_name='<APP-NAME>',
2	owner='<OWNER>',
3	batch_id=batch.id)
4
5	# repeatedly check run status until run is complete
6	status = client.apps.runs.status(run.id)
7	while status.status == 'RUNNING':
8	time.sleep(5) # polling interval in seconds
9	status = client.apps.runs.status(run.id)
10
11	# get app run results
12	results = client.apps.runs.results(run.id)

1	import os
2	import time
3
4	from aihub import AIHub
5
6	# initialize the SDK client
7	client = AIHub(api_key=<API-TOKEN>,
8	api_root=<API-ROOT>,
9	ib_context=<IB-CONTEXT>)
10
11	# create a batch
12	batch = client.batches.create(name=<BATCH-NAME>)
13
14	# add files to the batch
15	file_paths = [<PATH/TO/FILE1>, <PATH/TO/FILE2>]
16	for path in file_paths:
17	with open(file_path, 'rb') as file:
18	client.batches.add_file(batch_id=batch.id,
19	file_name=os.path.basename(path),
20	file=file)
21
22	run = client.apps.runs.create(app_name='<APP-NAME>',
23	owner='<OWNER>',
24	batch_id=batch.id)
25
26	# repeatedly check run status until run is complete
27	status = client.apps.runs.status(run.id)
28	while status.status == 'RUNNING':
29	time.sleep(5) # polling interval in seconds
30	status = client.apps.runs.status(run.id)
31
32	# get app run results
33	results = client.apps.runs.results(run.id)