Python SDK

📘
This SDK tool is under active development.
For any bug found or feature request, feel free to open any issue regarding this SDK here.

Requirements

Python 3.9 - 3.11
Pip | Poetry

Please note that the Python SDK currently doesn't support Python 3.12. If you are using Python 3.12, please downgrade to Python 3.11.

Installation

Install it directly into an activated virtual environment:

pip install instill-sdk

poetry add instill-sdk

🚧
If your host machine is on arm64 architecture (including Apple silicon machines, equipped with m1/m2 processors), there are some issues when installing grpcio within conda environment. You will have to manually build and install it like below. Read more about this issue here.

GRPC_PYTHON_LDFLAGS=" -framework CoreFoundation" pip install grpcio --no-binary :all:

Check Import

After installation, you can check if it has been installed correctly:

python
>>> import instill
>>> instill.__version__

Usage

Create Client

Simply import the init_core_client function to initiate the client that are connected to all services.

from instill.clients import init_core_client

client = init_core_client(api_token="instill_sk_***", url="HOST_URL")

📘
If you are using Instill Core as a managed service, set HOST_URL to {user.managedApiBaseUrl}. If you are self-hosting Instill Core, use {user.ApiBaseUrl}.

If you have not set up Pipeline or Model, you will get a warning like this:

2023-09-27 18:49:04,871.871 WARNING  Pipeline is not serving, Pipeline functionalities will not work
2023-09-27 18:49:04,907.907 WARNING  Model is not serving, Model functionalities will not work

You can check the readiness of each service:

client.mgmt.is_serving()
# True
client.pipeline.is_serving()
# True
client.model.is_serving()
# True
client.artifact.is_serving()
# True

📘
Depends on which project(Pipeline or Model or both) you had launched locally, some services might not be available.

After making sure all desired services are serving, we can check the user status by:

client.mgmt.get_user()

If you have a valid api_token in your config file, you should see something like this:

name: "users/admin"
uid: "4767b74d-640a-4cdf-9c6d-7bb0e36098a0"
id: "admin"
create_time {
  seconds: 1695589596
  nanos: 36522000
}
update_time {
  seconds: 1695589749
  nanos: 544980000
}
profile {
  display_name: "Instill"
  bio: ""
  avatar: "http://localhost:8080/core/v1beta/users/admin/avatar"
  public_email: ""
  company_name: "Instill AI"
}

📘
Remember to call client.close() at the end of script to release the channel and the underlying resources.