Instabase AI Hub

https://docs.instabase.com
Admin
Instabase AI Hub is a platform that uses large language models to deliver document understanding and...
Tokens:190,792
Snippets:1,368
Trust Score:9.8
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Example: Deductions table with structured output

Source: https://docs.instabase.com/automate/llms-custom-functions

Reads a file from context['file_path'], uses the file client to get content, and calls generate_content with a prompt, file data, and a response schema to return a deductions table. Handles missing clients by returning None.

```python
file_path = context['file_path']
clients = context.get('clients', {})
file_client = clients.get('ibfile')
llm_client = clients.get('llm_client')
if llm_client is None or file_client is None:
    return None  # or your fallback when the LLM client isn't available
file_content, err = file_client.read_file(file_path)
resp_text = llm_client.generate_content(
    prompt='Return the deductions table. remove any extra symbols from the amount deducted',
    file_data=file_content,
    mime_type='application/pdf',
    file_path=file_path,
    response_schema={
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "description": {"type": "string"},
                "amount deducted": {"type": "float"},
            },
        },
        "description": "deductions table"
    }
)
return resp_text
```

--------------------------------

### Install instabase-aihub with pip

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/2-prepare

Install the instabase-aihub module from PyPI using pip.

```bash
pip install instabase-aihub
```

--------------------------------

### Example response for listing files in a batch

Source: https://docs.instabase.com/api-sdk/api-reference/batches/list-files

Example JSON response from the list files endpoint, showing file nodes with metadata, permissions, pagination token, and has_more flag.

```json
{
  "nodes": [
    {
      "full_path": "/path/to/document1.pdf",
      "metadata": {
        "node_type": "file",
        "size": 1024,
        "modified_timestamp": 1647532800
      },
      "perms": {
        "can_read": true,
        "can_write": true,
        "can_delete": true
      },
      "name": "document1.pdf"
    },
    {
      "full_path": "/path/to/document2.pdf",
      "metadata": {
        "node_type": "file",
        "size": 2048,
        "modified_timestamp": 1647619200
      },
      "perms": {
        "can_read": true,
        "can_write": false,
        "can_delete": false
      },
      "name": "document2.pdf"
    }
  ],
  "next_page_token": "eyJwYWdlIjogMn0=",
  "has_more": true
}

```

--------------------------------

### Example response for listing runs

Source: https://docs.instabase.com/api-sdk/api-reference/runs/list-runs

Example 200 response showing a run object with fields such as id, status, timestamps, and tags.

```json
{
  "runs": [
    {
      "id": "run_9f8b7c6d5e4a3b2c1d0e",
      "status": "CANCELLED",
      "start_timestamp": 1685606400000000000,
      "finish_timestamp": 1685608200000000000,
      "msg": "User cancelled the run due to incorrect input parameters.",
      "batch_id": 42,
      "input_dir": "/data/input/batch_42",
      "app_id": "app_1234567890abcdef",
      "deployment_id": "deploy_0987654321fedcba",
      "tags": [
        "urgent",
        "test-run"
      ]
    }
  ]
}

```

--------------------------------

### Get run status response example

Source: https://docs.instabase.com/api-sdk/api-reference/runs/get-run-status

Example JSON response returned by the Get run status endpoint. The status field can be CANCELLED, COMPLETE, FAILED, PAUSED, RUNNING, or STOPPED_AT_CHECKPOINT. finish_timestamp is null if the run is still in progress.

```json
{
  "id": "string",
  "status": "CANCELLED",
  "start_timestamp": 1,
  "finish_timestamp": 1,
  "msg": "string",
  "batch_id": 1,
  "input_dir": "string",
  "app_id": "string",
  "deployment_id": "string",
  "tags": [
    "string"
  ]
}
```

--------------------------------

### Complete test program

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/3-test

The full program that imports the SDK, initializes the client, creates a batch, and prints success messages. Includes comments explaining each step.

```python
# make the AI Hub SDK available for use
from aihub import AIHub
# initialize the "client" variable as an instance of the AIHub class,
# configured with authorization details for our AI Hub account
client = AIHub(api_root="PASTE YOUR API ROOT HERE",
               api_key="PASTE YOUR API KEY HERE",
               ib_context="PASTE YOUR IB-CONTEXT HERE")
# create a new batch called "test batch" in the
# "SDK-Tutorial" workspace
create_batch_resp = client.batches.create(name="test batch",
                                          workspace="SDK-Tutorial")
# If the batch was created successfully, the program prints the
# messages below and quits normally. If it wasn't created successfully, 
# Python automatically prints an error message and quits the program.
print("Successfully created a batch.")
print("The AI Hub SDK is installed, authorized, and ready to use.")

```

--------------------------------

### Example 200 response for get run results

Source: https://docs.instabase.com/api-sdk/api-reference/runs/get-run-results

Example 200 response for a successful get run results request. Shows the run status, file documents with extracted fields, case_info with edit history, and the has_more flag indicating pagination. Field names in the response may be converted to valid Python variable names (e.g., 'due date' becomes 'due_date').

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETE",
  "message": "Completed single_flow",
  "start_timestamp": 1765912514238248700,
  "finish_timestamp": 1765912529614834000,
  "batch_id": "1235",
  "files": [
    {
      "original_file_name": "test.png",
      "input_file_path": "instabase-sandbox-org/test-org/fs/Instabase Drive/app-runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/input/test.png",
      "documents": [
        {
          "fields": [
            {
              "field_name": "employers_address_and_ZIP_code",
              "value": "123 STREET RD ANYWHERE, USA,12345",
              "type": "TEXT"
            }
          ],
          "class_name": "Wage And Tax Statement",
          "page_numbers": [
            1,
            2
          ]
        }
      ]
    },
    {
      "original_file_name": "test2.png",
      "input_file_path": "instabase-sandbox-org/test-org/fs/Instabase Drive/app-runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/input/test2.png",
      "documents": [
        {
          "fields": [
            {
              "field_name": "sex",
              "value": "Male",
              "type": "TEXT"
            }
          ],
          "class_name": "Driver License",
          "page_numbers": [
            1
          ]
        }
      ]
    }
  ],
  "keys": [
    {
      "custom": {}
    }
  ],
  "case_info": {
    "fields": [
      {
        "name": "Employee_Address",
        "value": "123 STREET RD ANYWHERE, USA,12345",
        "input_fields": [
          {
            "record_index": 0,
            "refined_phrase_name": "employers_address_and_ZIP_code"
          }
        ],
        "chosen_field": {
          "record_index": 0,
          "refined_phrase_name": "employers_address_and_ZIP_code"
        },
        "edit_history": [
          {
            "timestamp": "08/27/2025 00:58:39",
            "user_id": "john.doe_instabase.com",
            "modifications": [
              {
                "message": "Edited to \"123 STREET RD ANYWHERE, USA,12345\""
              }
            ]
          }
        ]
      },
      {
        "name": "Sex",
        "value": "Male",
        "input_fields": [
          {
            "record_index": 0,
            "refined_phrase_name": "sex"
          }
        ],
        "chosen_field": {
          "record_index": 0,
          "refined_phrase_name": "sex"
        }
      }
    ]
  },
  "has_more": false
}

```

--------------------------------

### Complete SDK script to initialize client, create batch, upload files, run app, and get results

Source: https://docs.instabase.com/api-sdk/apps-sdk

Use this complete script to initialize the SDK client, create a batch, upload local files, run an automation app, poll its status until complete, and retrieve results. The files are opened in binary mode and added to the batch. The script returns app run results as a Python dictionary. Requires valid API key, and optionally an api_root and ib_context.

```python
import os
import time
from aihub import AIHub
# initialize the SDK client
client = AIHub(api_root=<API-ROOT>,
               api_key=<API-TOKEN>,
               ib_context=<IB-CONTEXT>)
# create a batch
batch = client.batches.create(name=<BATCH-NAME>)
# add files to the batch
file_paths = [<PATH/TO/FILE1>, <PATH/TO/FILE2>]
for path in file_paths:
    with open(path, 'rb') as file:
        client.batches.add_file(batch_id=batch.id,
                                file_name=os.path.basename(path),
                                file=file)
run = client.apps.runs.create(app_name=<APP-NAME>,
                              owner=<OWNER>,
                              batch_id=batch.id)
# repeatedly check run status until run is complete
status = client.apps.runs.status(run.id)
while status.status == 'RUNNING':
    time.sleep(5)  # polling interval in seconds
    status = client.apps.runs.status(run.id)
# get app run results
results = client.apps.runs.results(run.id)

```

--------------------------------

### Hello, SDK user in Go

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/1-intro

Go program that prints 'Hello, SDK user' to the console. Shown as a comparison to Java and Python versions.

```Go
package main
import "fmt"
func main() {
    fmt.Println("Hello, SDK user")
}
```

--------------------------------

### Full Pagination Example for /api/v1/flow_binary/results (Python)

Source: https://docs.instabase.com/api-sdk/api-reference/legacy/run-results-endpoint

Iterates through all pages of results by updating file_offset based on the last record's file_index. Continues until the response is empty. Requires the same setup as the basic request.

```python
url = url_base + '/api/v1/flow_binary/results'
args = {
  'ibresults_path': "/jaydoe/my_repo/fs/Instabase Drive/flow_proj/out/batch.ibflowresults",
  'options': {
    'refined_phrases_features': ['provenance_info'],
    'include_page_layouts': True,
  },
  'file_offset': 0
}
json_data = json.dumps(args)
headers = {
  'Authorization': 'Bearer {0}'.format(token)
}
r = requests.post(url, data=json_data, headers=headers)
resp_data = json.loads(r.content)
# Parse through pages until no more pages left to look through
all_records = [resp_data.get('records', [])]
while len(resp_data) > 0:
  # Retrieve the last file_index from the last record returned
  next_file_offset = resp_data['records'][-1]['file_index'] + 1
  args['file_offset'] = next_file_offset
  json_data = json.dumps(args)
  r = requests.post(url, data=json_data, headers=headers)
  resp_data = json.loads(r.content)
  resp_records = resp_data.get('records', [])
  all_records.extend(resp_records)
```

--------------------------------

### Sample package.json for custom library solution

Source: https://docs.instabase.com/flow/custom-functions/dev-packages

Example metadata file for a developer package named ib_classifier_docsplitting. Includes required fields (name, version, descriptions, authors, accelerator_type, industry, business_vertical, package_type, function_type) and optional fields (icon_url, beta, encryption_config).

```json
{
  "name": "ib_classifier_docsplitting",
  "version": "1.0.1",
  "short_description": "Classifier for variable-length document bundles",
  "long_description": "The docsplitting classifier learns to split a PDF bundle of documents, and predict the class of each document. Import FirstPageDocsplittingClassifier from docsplit_classifier in the solution.",
  "authors": [
        "Instabase"
    ],
  "accelerator_type": [
        "package"
    ],
  "industry": [],
  "business_vertical": [],
  "package_type": [
        "integration"
    ],
  "function_type": [
        "machine learning"
    ],
  "icon_url": "icon.png",
  "beta": true,
  "encryption_config": {
    "encryption_type": "v1"
  }
}

```

--------------------------------

### Successful response JSON for get batch

Source: https://docs.instabase.com/api-sdk/api-reference/batches/get-batch

Example of a 200 response when the batch is successfully retrieved. The response includes fields such as id, name, workspace, mount_point, repo_owner, batch_owner, created_at_ms, updated_at_ms, and path_suffix.

```json
{
  "id": 1,
  "name": "string",
  "workspace": "string",
  "mount_point": "string",
  "repo_owner": "string",
  "batch_owner": "string",
  "created_at_ms": 1,
  "updated_at_ms": 1,
  "path_suffix": "string"
}
```

--------------------------------

### Successful run response

Source: https://docs.instabase.com/api-sdk/api-reference/runs/run-app

Example response returned when the run starts successfully. The status field indicates the run state, and the response includes the run ID, timestamps, batch ID, input directory, app ID, deployment ID, and tags.

```json
{
  "id": "a3f1c9d2-4b7e-4f8a-9d3e-2b7f9c1a5e6d",
  "status": "COMPLETE",
  "start_timestamp": 1711929600000000000,
  "finish_timestamp": 1711933200000000000,
  "msg": "Run completed successfully.",
  "batch_id": 98765,
  "input_dir": "/instabase/drive/projects/input_data",
  "app_id": "528c36e8-ac5b-490d-a41b-7eec9c404b87",
  "deployment_id": "d4f7a9b3-1c2e-4d5f-8a9b-7c3d2e1f0a4b",
  "tags": [
    "invoice-processing",
    "priority-high"
  ]
}
```

--------------------------------

### Example output from automate_with_sdk.py

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/4-automate

Example output from running automate_with_sdk.py. Shows the sequence of status messages and the extracted fields for two receipt files. The STOPPED_AT_CHECKPOINT status indicates the app wants human review of some values.

```text
creating an empty batch
uploading two files to the batch
running the app
checking the app status until it finishes
status: RUNNING
status: RUNNING
status: RUNNING
status: STOPPED_AT_CHECKPOINT
fetching the app results
file name: receipt-a.jpg
    Total_Amount: 164.46
    Vendor: Flo's Greasy Spoon Diner
    Date: 07/25/2025
    Transaction_ID: N/A
    Vendor_Address: 123 Main St Springfield, Missouri
    Subtotal: 152.99
    Tax: 11.47
    Tip: N/A
    Receipt_Item_Details: [{"Description": "Beluga  Caviar", "Quantity": "1", "Amount": "150.0"}, {"Description": "Cherry  Coke", "Quantity": "1", "Amount": "2.99"}]
---
file name: receipt-b.jpg
    Total_Amount: 9619.21
    Vendor: CJ's Burger Shack
    Date: 07/16/2025
    Transaction_ID: N/A
    Vendor_Address: 17 Montgomery Road Dallas, Texas
    Subtotal: 9204.99
    Tax: 414.22
    Tip: N/A
    Receipt_Item_Details: [{"Description": "Lg Basket Fries", "Quantity": "6", "Amount": "5.99"}, {"Description": "Bot Roman\u00e9e-Conti", "Quantity": "1", "Amount": "9199.00"}]
---
```

--------------------------------

### 202 Accepted response body for run deployment

Source: https://docs.instabase.com/api-sdk/api-reference/runs/run-deployment

Example 202 Accepted response body after successfully initiating a deployment run. Shows a cancelled run along with the run ID, start and finish timestamps, message, batch ID, input directory, app ID, deployment ID, and tags. Note that timestamps are in Unix time nanoseconds.

```json
{
  "id": "a3f1c9e2-7b4d-4f8a-9c2e-5d6f7a8b9c0d",
  "status": "CANCELLED",
  "start_timestamp": 1686806400000000000,
  "finish_timestamp": 1686810000000000000,
  "msg": "Run was cancelled by user request.",
  "batch_id": 98765,
  "input_dir": "acme/MarketingTeam/fs/GoogleDrive/ProjectX/InputFiles/",
  "app_id": "app-4f7e2d9c-1234-5678-9abc-def012345678",
  "deployment_id": "01902d6f-bb35-74cb-bd27-c09b38bbf20a",
  "tags": [
    "urgent",
    "Q2-report"
  ]
}
```

--------------------------------

### Hello, SDK user in Java

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/1-intro

Java program that prints 'Hello, SDK user' to the console. Shown as a comparison to Go and Python versions.

```Java
public class HelloSdkUser {
    public static void main(String[] args) {
        System.out.println("Hello, SDK user");
    }
}
```

--------------------------------

### Hello, SDK user in Python

Source: https://docs.instabase.com/api-sdk/sdk-for-beginners/1-intro

Python program that prints 'Hello, SDK user' to the console. Shown as a comparison to Go and Java versions.

```Python
print("Hello, SDK user")
```
Tokens:
Raw