Skip to content

PowerMind InsightML Python SDK Reference & Guide

The insightml-sdk library provides complete programmatic control over your machine learning workspaces. Use the SDK to automate ingestion, schedule model training, build CI/CD deployment pipelines, or call prediction endpoints.

1. Installation

Install the wheel package generated by the build process: 

pip install insightml_sdk-0.1.0-py3-none-any.whl

2. Client Initialization

Explicit Initialization

from insightml_sdk import InsightMLClient

client = InsightMLClient(
    base_url="http://localhost:8000",
    api_key="IML_live_platform_your_key_here",
    ssl_verify=True,   # Set to False to bypass self-signed SSL certificate errors (alias: verify_ssl)
    timeout=30.0,      # Request timeout in seconds
)

Environment-Based Initialization

You can initialize the client without arguments if you configure the following environment variables:

  • INSIGHTML_BASE_URL (Required)
  • INSIGHTML_API_KEY (Optional, for platform actions)
  • INSIGHTML_DEPLOYMENT_API_KEY (Optional, for serving predictions)
  • INSIGHTML_TIMEOUT (Optional, request timeout in seconds, default: 30.0)
  • INSIGHTML_VERIFY_SSL or INSIGHTML_SSL_VERIFY (Optional, set to False to bypass self-signed SSL errors, default: True)

export INSIGHTML_BASE_URL="http://localhost:8000"
export INSIGHTML_API_KEY="IML_live_platform_your_key_here"

from insightml_sdk import InsightMLClient

client = InsightMLClient.from_env()

3. End-to-End Walkthrough Example

Here is the complete end-to-end workflow walkthrough showing project creation, CSV upload, dataset previewing, AutoML training, polling, downloading the resulting model, deploying, creating a key, and getting predictions.

import time
from pathlib import Path
from insightml_sdk import InsightMLClient, InferenceInput

# 1. Initialize client
client = InsightMLClient(
    base_url="http://localhost:8000",
    api_key="IML_live_platform_key_here"
)

# 2. Setup workspace and project
ws = client.create_workspace(name="Production Predictive Analytics")
workspace_id = ws["id"]

proj = client.create_project(name="Customer Churn Forecast", workspace_id=workspace_id)
project_id = proj["id"]

# 3. Create dummy dataset & upload
data_file = Path("sample_churn.csv")
data_file.write_text("age,tenure,monthly_charges,churn\n30,12,50.5,0\n21,2,70.0,1\n55,36,95.0,0\n")

dataset = client.upload_dataset(
    project_id=project_id,
    name="churn-data",
    file_path=data_file
)
dataset_id = dataset["id"]

# 4. Preview dataset
preview = client.preview_dataset(dataset_id)
print("Preview columns:", preview["columns"])
print("Sample rows:", preview["rows"])

# 5. Run AutoML Training & Poll
run = client.run_automl(
    name="churn-prediction-exp",
    project_id=project_id,
    dataset_id=dataset_id,
    problem_type="classification",
    target_column="churn"
)
experiment_id = run["experiment_id"]

while True:
    exp = client.get_experiment(experiment_id)
    status = exp["status"]
    print(f"Training status: {status}")
    if status in ("completed", "failed"):
        break
    time.sleep(3)

print("Best Model Name:", exp["best_model"])

# 6. Retrieve and download model from registry
models = client.list_models_by_experiment(experiment_id)
best_model_id = models["data"][0]["id"]

# Stream download to local file
client.download_model(model_id=best_model_id, output_path="churn_model.joblib")

# 7. Deploy model
dpl = client.create_deployment(model_id=best_model_id)
dpl_id = dpl["deployment_id"]

print("Waiting for deployment to spin up...")
dpl_detail = client.wait_for_deployment(deployment_id=dpl_id)
print(f"Deployment status: {dpl_detail['status']}")

# 8. Create serving/prediction API Key & Predict
key_payload = client.create_deployment_api_key(deployment_id=dpl_id, name="client-app-key")
dpl_key = key_payload["api_key"]

# Authenticate client with deployment API key
client.set_deployment_api_key(dpl_key)

# Query predictions
result = client.infer(
    deployment_name=dpl_detail["deployment_name"],
    inputs=[
        InferenceInput(
            name="input__0",
            shape=[1, 3],
            datatype="FP32",
            data=[35.0, 15.0, 50.0]
        )
    ]
)
print("Prediction response:", result)

# 9. Resource Cleanup
client.set_api_key("IML_live_platform_key_here")  # Switch back to platform access
client.stop_deployment(dpl_id)
client.delete_deployment(dpl_id)
client.delete_project(project_id)
client.delete_workspace(workspace_id)
data_file.unlink()

4. API Reference: Classes & Exceptions

InferenceInput (dataclass)

Represents a Triton-compatible input tensor payload for inference.

  • Fields:
  • name (str): Name of the model input tensor (e.g., "input__0").
  • shape (list[int]): Shape dimensions of the input tensor (e.g., [1, 4]).
  • datatype (str): String representing the data type (e.g., "FP32").
  • data (list[Any]): Flattened values array.

Exceptions

  • InsightMLError: Base SDK exception class.
  • InsightMLConnectionError: Raised when the client fails to connect to the backend server.
  • InsightMLAPIError: Raised when the API returns an HTTP response code >= 400.
  • Properties:
    • status_code (int): The HTTP response status code (e.g. 401, 404, 500).
    • detail (Any): The parsed JSON details/error message returned by the server.
    • response_body (Any): The raw text or parsed body of the HTTP response.

5. API Reference: Client Methods

All client operations are methods of the InsightMLClient class.

Administrative & Service Status

health()

  • Description: Verify connection health to the API.
  • Parameters: None.
  • Returns: dict containing "status": "ok" and current timestamp.

ready()

  • Description: Check server readiness status.
  • Parameters: None.
  • Returns: dict containing "status": "ready".

version()

  • Description: Get service name and API release version.
  • Parameters: None.
  • Returns: dict containing "service" name and "version".

close()

  • Description: Close the requests session connection pool.
  • Parameters: None.
  • Returns: None.

set_api_key(api_key)

  • Description: Update the platform API key on the client instance.
  • Parameters:
  • api_key (str | None): The target API key, or None to clear.
  • Returns: None.

set_deployment_api_key(api_key)

  • Description: Update the deployment prediction API key on the client instance.
  • Parameters:
  • api_key (str | None): The target deployment-scoped key, or None to clear.
  • Returns: None.

Workspaces

create_workspace(*, name)

  • Description: Create a new workspace.
  • Parameters:
  • name (str): The name of the workspace to create.
  • Returns: dict containing the created workspace properties (id, name, owner_id).

list_workspaces()

  • Description: List all workspaces accessible by the current authenticated user.
  • Parameters: None.
  • Returns: list[dict] of workspace details.

get_workspace(workspace_id)

  • Description: Get details of a specific workspace.
  • Parameters:
  • workspace_id (str | uuid.UUID): The unique ID of the workspace.
  • Returns: dict of workspace properties.

delete_workspace(workspace_id)

  • Description: Delete a workspace and its associated projects, datasets, and deployments.
  • Parameters:
  • workspace_id (str | uuid.UUID): The unique ID of the workspace.
  • Returns: dict success status message.

FeatureHub Ingestion Configuration

upsert_workspace_featurehub_datasource(*, workspace_id, base_url, api_key, fhb_workspace_id)

  • Description: Link a FeatureHub deployment to the workspace.
  • Parameters:
  • workspace_id (str | uuid.UUID): Workspace to configure.
  • base_url (str): FeatureHub instance endpoint.
  • api_key (str): FeatureHub workspace access token.
  • fhb_workspace_id (str): FeatureHub target workspace ID.
  • Returns: dict configuration response.

get_workspace_featurehub_datasource_status(workspace_id)

  • Description: Fetch status/health of FeatureHub datasource connection.
  • Parameters:
  • workspace_id (str | uuid.UUID): Workspace to query.
  • Returns: dict connection status detail.

Projects

create_project(*, name, workspace_id)

  • Description: Create a new project.
  • Parameters:
  • name (str): Project name.
  • workspace_id (str | uuid.UUID): Parent workspace ID.
  • Returns: dict containing project properties (id, name, workspace_id).

list_projects(*, limit=10, offset=0)

  • Description: List projects with pagination.
  • Parameters:
  • limit (int, default: 10): Max projects to return (capped at 100).
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of projects.

get_project(project_id)

  • Description: Retrieve project metadata.
  • Parameters:
  • project_id (str | uuid.UUID): Target project ID.
  • Returns: dict of project properties.

delete_project(project_id)

  • Description: Delete a project.
  • Parameters:
  • project_id (str | uuid.UUID): Target project ID.
  • Returns: dict success status message.

Datasets

upload_dataset(*, project_id, name, file_path)

  • Description: Upload a local CSV dataset file to the platform.
  • Parameters:
  • project_id (str | uuid.UUID): Project ID to ingest this dataset into.
  • name (str): Ingested dataset name.
  • file_path (str | Path): Path to local CSV file.
  • Returns: dict dataset info (id, name, version, source_type).

list_datasets(project_id, *, limit=10, offset=0)

  • Description: List all datasets within a project.
  • Parameters:
  • project_id (str | uuid.UUID): Project ID to search.
  • limit (int, default: 10): Max datasets to return.
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of datasets.

preview_dataset(dataset_id)

  • Description: Fetch statistical overview and raw data rows of a dataset.
  • Parameters:
  • dataset_id (str | uuid.UUID): Dataset ID.
  • Returns: dict with list of "columns" and list of "rows".

create_featurehub_dataset(*, project_id, name, feature_name)

  • Description: Ingest a dataset exported from linked FeatureHub.
  • Parameters:
  • project_id (str | uuid.UUID): Target project.
  • name (str): Ingested dataset name.
  • feature_name (str): Feature name in the FeatureHub catalog.
  • Returns: dict dataset properties.

delete_dataset(dataset_id)

  • Description: Delete a dataset.
  • Parameters:
  • dataset_id (str | uuid.UUID): Target dataset ID.
  • Returns: dict success status message.

AutoML Experiments

run_automl(*, name, project_id, dataset_id, problem_type, target_column=None, n_clusters=None, time_column=None, forecast_horizon=1, auto_create_lags=None)

  • Description: Trigger an asynchronous AutoML run.
  • Parameters:
  • name (str): Experiment name.
  • project_id (str | uuid.UUID): Project ID.
  • dataset_id (str | uuid.UUID): Dataset ID to train on.
  • problem_type (str): Choice of "classification", "regression", "clustering", or "time_series".
  • target_column (str, optional): Label/target column (required for supervised and time-series).
  • n_clusters (int, optional): Number of clusters (clustering only).
  • time_column (str, optional): Datetime column (time-series forecasting only).
  • forecast_horizon (int, default: 1): Number of future steps to forecast (time-series forecasting only).
  • auto_create_lags (bool, optional): Whether to automatically generate lag and rolling features for time-series forecasting. If set to False, no lags are generated. If None or omitted, defaults to backend service behavior (which defaults to True).
  • Returns: dict containing "experiment_id", "status" ("queued"), "problem_type".

get_experiment(experiment_id)

  • Description: Query experiment progress, status, best model, and evaluation metrics.
  • Parameters:
  • experiment_id (str | uuid.UUID): Target experiment ID.
  • Returns: dict properties (id, name, status, best_model, metrics).

delete_experiment(experiment_id)

  • Description: Delete an experiment.
  • Parameters:
  • experiment_id (str | uuid.UUID): Target experiment ID.
  • Returns: dict success status message.

list_experiments(project_id, *, limit=10, offset=0)

  • Description: List experiments inside a project.
  • Parameters:
  • project_id (str | uuid.UUID): Project ID.
  • limit (int, default: 10): Max experiments to return.
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of experiments.

run_full_automl(*, workspace_id, project_name, dataset_name, problem_type, target_column=None, file_path, n_clusters=None, time_column=None, forecast_horizon=1, auto_create_lags=None)

  • Description: Single call helper to upload data, set up project, and run AutoML training asynchronously.
  • Parameters:
  • Reference parameters in run_automl and upload_dataset sections.
  • project_name (str): Created or matched project name.
  • dataset_name (str): Ingested dataset name.
  • auto_create_lags (bool, optional): Whether to automatically generate lag and rolling features for time-series forecasting.
  • Returns: dict summary status payload (project_id, dataset_id, experiment_id, "status": "queued").

Model Registry & Binary Downloads

list_models(*, project_id, limit=10, offset=0)

  • Description: List models registered inside a project.
  • Parameters:
  • project_id (str | uuid.UUID): Project ID.
  • limit (int, default: 10): Max models to return.
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of registered models.

list_models_by_experiment(experiment_id, *, limit=10, offset=0)

  • Description: List all models registered from a specific AutoML experiment.
  • Parameters:
  • experiment_id (str | uuid.UUID): Source experiment ID.
  • limit (int, default: 10): Max models to return.
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of registered models.

download_model(model_id, output_path=None)

  • Description: Download a model's weights/binary file (e.g. .joblib).
  • Parameters:
  • model_id (str | uuid.UUID): Target model ID.
  • output_path (str | Path, optional): Local file path to write binary output.
  • Returns:
  • Path (if output_path is provided) where file is saved.
  • bytes raw content (if output_path is None).

delete_model(model_id)

  • Description: Delete a model from registry.
  • Parameters:
  • model_id (str | uuid.UUID): Target model ID.
  • Returns: dict success status message.

Platform API Keys

create_api_key(*, workspace_id, name)

  • Description: Generate a platform API key to authenticate platform-scoped administrative SDK calls.
  • Parameters:
  • workspace_id (str | uuid.UUID): Target workspace.
  • name (str): Description name.
  • Returns: dict containing "api_key", "name", "workspace_id".

list_api_keys(*, workspace_id)

  • Description: List active platform API keys for the workspace.
  • Parameters:
  • workspace_id (str | uuid.UUID): Target workspace.
  • Returns: list[dict] of key metadata.

revoke_api_key(key_id)

  • Description: Revoke/delete a platform API key.
  • Parameters:
  • key_id (str | uuid.UUID): Unique database key ID.
  • Returns: dict containing "status": "revoked".

Deployments & Online Serving

create_deployment(*, model_id)

  • Description: Spin up an active serving container (Triton-backed) for the registered model.
  • Parameters:
  • model_id (str | uuid.UUID): ID of model to deploy.
  • Returns: dict containing "deployment_id", "status".

get_deployment(deployment_id)

  • Description: Get status and endpoint URL of a model deployment.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: dict containing deployment status metadata.

list_deployments(project_id, *, limit=10, offset=0)

  • Description: List all active model deployments in a project.
  • Parameters:
  • project_id (str | uuid.UUID): Project ID.
  • limit (int, default: 10): Max deployments to return.
  • offset (int, default: 0): Offset indices.
  • Returns: dict with "total", "limit", "offset", and "data" list of deployments.

get_deployment_health(deployment_id)

  • Description: Query serving container availability.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: dict containing health status.

start_deployment(deployment_id)

  • Description: Start or load a stopped deployment container.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: dict containing current status.

stop_deployment(deployment_id)

  • Description: Stop/unload a deployment.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: dict containing current status.

delete_deployment(deployment_id)

  • Description: Delete deployment metadata.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: dict success status message.

Deployment Keys (Inference Access)

create_deployment_api_key(*, deployment_id, name)

  • Description: Generate a scoped API key intended solely for querying prediction endpoints.
  • Parameters:
  • deployment_id (str | uuid.UUID): Target deployment ID.
  • name (str): Description name.
  • Returns: dict containing "api_key", "id", "name", "prefix".

list_deployment_api_keys(deployment_id)

  • Description: List inference API keys configured for the deployment.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment database ID.
  • Returns: list[dict] of key metadata.

revoke_deployment_api_key(*, deployment_id, key_id)

  • Description: Revoke a deployment inference key.
  • Parameters:
  • deployment_id (str | uuid.UUID): Target deployment.
  • key_id (str | uuid.UUID): Database key ID.
  • Returns: dict containing "status": "revoked".

Real-Time Inference & Engineering

infer(*, deployment_name, inputs, deployment_api_key=None)

  • Description: Send input tensors to a running deployment and fetch predictions.
  • Parameters:
  • deployment_name (str): Name of the deployed model endpoint (e.g. "logistic_regression_v1").
  • inputs (list[InferenceInput | dict]): Array of inputs.
  • deployment_api_key (str, optional): Key to authenticate. If not passed, uses client configuration.
  • Returns: dict response container with outputs, matching Triton serving standard.

compute_deployment_lags(*, deployment_id, historical_data, target_column, time_column)

  • Description: Compute lag and rolling features for time-series forecast model query.
  • Parameters:
  • deployment_id (str | uuid.UUID): Target time-series model deployment.
  • historical_data (list[dict]): Chronological points leading up to the forecast window.
  • target_column (str): Name of predictive target.
  • time_column (str): Name of the time reference column.
  • Returns: dict containing computed lag statistics, format-ready for prediction payload.

Wait Utilities

wait_for_deployment(*, deployment_id, timeout_sec=300.0, poll_interval_sec=3.0)

  • Description: Block execution until a deployment enters a "running" or "failed" state.
  • Parameters:
  • deployment_id (str | uuid.UUID): Deployment ID.
  • timeout_sec (float, default: 300.0): Timeout limit.
  • poll_interval_sec (float, default: 3.0): Polling interval.
  • Returns: dict of deployment details when ready.
  • Raises: TimeoutError if state is not resolved in target window.