Running apps with the AI Hub SDK

With the AI Hub software development kit (SDK), you can 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 full script you can reference to create your own workflow.

While the script in this guide uses the AI Hub Python SDK, you can use the AI Hub API to do the same. 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.

Uploading files to a batch

You can create a batch of files to use as input for your app run. In AI Hub, a batch is a user-defined group of files. You can add and remove files from the batch, but its ID remains constant so you can repeatedly use all files in the batch as app input.

For more information, see the Batches endpoint.

Script excerpt

This section of the script creates a batch and uploads the listed files to it.

1 # create a batch
2 batch = client.batches.create(name='<BATCH-NAME>')
3 
4 # add files to the batch
5 import os  # optionally move this up to the program's `imports` section
6 file_paths = ['<path/to/sample1.pdf>', '<path/to/sample2.docx>']
7 for file_path in file_paths:
8     with open(file_path, 'rb') as file:
9         client.batches.add_file(batch_id=batch.id, 
10                                 file_name=os.path.basename(file_path), 
11                                 file=file)

Define the following values in the script:

Parameter or variable	Type	Required	Description
`<BATCH-NAME>`	string	Yes	Name of the batch. Maximum length is 255 characters.
`file_paths`	list	Yes	A list of local file paths of files to upload to the batch.

Processing 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.

Script excerpt

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=None, 
3                               batch_id=batch.id)
4 
5 # repeatedly check run status until run is complete
6 status = client.apps.runs.status(run.id)
7 import time  # optionally move this up to the program's `imports` section
8 while status.status == 'RUNNING':
9     time.sleep(5)  # polling interval in seconds
10     status = client.apps.runs.status(run.id)
11 
12 # get app run rests
13 results = client.apps.runs.results(run.id)

Define the following values in the script:

Parameter or variable	Type	Required	Description
`<APP-NAME>`	string	Yes	The name of a prebuilt or custom AI Hub app through which you want to process the uploaded files.
`owner`	string	No	The account that generated the app. If left as `None`, defaults to your AI Hub username. For custom AI Hub apps created by you, accept the default. For public AI Hub 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, as 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 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 batch object and uploads files to the batch.
Runs the specified app using the batch as input.
Automatically polls the app run’s status for completion.
Returns the app run’s results in JSON format. See the Get run results endpoint for an example of app run results.

Complete script

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>", api_root="<API-ROOT>", ib_context="<IB-CONTEXT>")
7 
8 # Creates a batch and adds files.
9 batch = client.batches.create(name='<BATCH-NAME>')
10 file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>']
11 for file_path in file_paths:
12     with open(file_path, "rb") as file:
13         client.batches.add_file(batch_id=batch.id, file_name=os.path.basename(file_path), file=file)
14 
15 # Runs an app and gets the results when the app run is complete.
16 run = client.apps.runs.create(app_name='<APP-NAME>', owner=None, batch_id=batch.id)
17 
18 # Get status
19 status = client.apps.runs.status(run.id)
20 
21 # Continuously checks the run status until it's done.
22 while status.status == 'RUNNING':
23     time.sleep(5)  # Polling interval
24     status = client.apps.runs.status(run.id)
25 
26 results = client.apps.runs.results(run.id)

User-defined values

To recap, this table 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	Defaults to your user ID. If undefined, requests are made with your community account. Used when initializing the API client.
`<BATCH-NAME>`	string	Yes	Name of the batch. Maximum length is 255 characters.
`file_paths`	list	Yes	A list of local file paths of files to upload to the batch.
`<APP-NAME>`	string	Yes	The name of a prebuilt or custom AI Hub app through which you want to process the uploaded files.
`owner`	string	No	The account that generated the app. If left as `None`, defaults to your AI Hub username. For custom AI Hub apps created by you, accept the default. For public AI Hub apps published by Instabase, specify `instabase`.

1	# create a batch
2	batch = client.batches.create(name='<BATCH-NAME>')
3
4	# add files to the batch
5	import os # optionally move this up to the program's `imports` section
6	file_paths = ['<path/to/sample1.pdf>', '<path/to/sample2.docx>']
7	for file_path in file_paths:
8	with open(file_path, 'rb') as file:
9	client.batches.add_file(batch_id=batch.id,
10	file_name=os.path.basename(file_path),
11	file=file)

1	run = client.apps.runs.create(app_name='<APP-NAME>',
2	owner=None,
3	batch_id=batch.id)
4
5	# repeatedly check run status until run is complete
6	status = client.apps.runs.status(run.id)
7	import time # optionally move this up to the program's `imports` section
8	while status.status == 'RUNNING':
9	time.sleep(5) # polling interval in seconds
10	status = client.apps.runs.status(run.id)
11
12	# get app run rests
13	results = client.apps.runs.results(run.id)

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>", api_root="<API-ROOT>", ib_context="<IB-CONTEXT>")
7
8	# Creates a batch and adds files.
9	batch = client.batches.create(name='<BATCH-NAME>')
10	file_paths = ['<inner/folder/sample1.pdf>', '<.../sample2.docx>', '<.../sample3.png>']
11	for file_path in file_paths:
12	with open(file_path, "rb") as file:
13	client.batches.add_file(batch_id=batch.id, file_name=os.path.basename(file_path), file=file)
14
15	# Runs an app and gets the results when the app run is complete.
16	run = client.apps.runs.create(app_name='<APP-NAME>', owner=None, batch_id=batch.id)
17
18	# Get status
19	status = client.apps.runs.status(run.id)
20
21	# Continuously checks the run status until it's done.
22	while status.status == 'RUNNING':
23	time.sleep(5) # Polling interval
24	status = client.apps.runs.status(run.id)
25
26	results = client.apps.runs.results(run.id)