IvoryOS client

Description

IvoryOS client automates the generation of client-side APIs based on server-defined robotic control script. It mirrors the control Python code features but sending command through HTTP request to the IvoryOS backend (where the actual robotic communication are happening) that receives the info and execute the actual control methods.

Installation

pip install ivoryos-client

Quick Start

from ivoryos_client import IvoryosClient

# Initialize client
client = IvoryosClient(
    url="http://localhost:8000/ivoryos",
    username="admin",
    password="admin"
)

# Or use as context manager
with IvoryosClient(url="http://localhost:8000/ivoryos", username="admin", password="admin") as client:
    # Get platform info
    info = client.get_platform_info()
    print(info)
    
    # Check execution status
    status = client.get_execution_status()
    print(status)
    
    # Execute a task and wait for its output
    result = client.execute_task("sdl", "dose_solid", {"amount_in_mg": "5"})
    print(result)  # {'success': True, 'output': ...}

You can also check out examples in community/examples

Features

• Task Execution: Execute robot tasks with parameters
• Workflow Management: Submit, load, and manage workflow scripts
• Workflow Execution: Run workflows with different strategies (repeat, kwargs, campaign)
• Data Management: List and load workflow execution data
• Status Monitoring: Check workflow execution status
• Error Handling: Comprehensive exception handling with specific error types

API Reference

Client Initialization

IvoryosClient(url, username, password, timeout=None)

timeout is the HTTP request timeout in seconds (None = no timeout). Keep it longer than your longest task if you use execute_task(..., wait=True).

Task Operations

• get_platform_info() - Get platform information and available functions
• execute_task(component, method, kwargs=None, wait=True) - Execute a task. wait=True (default) blocks until it finishes and returns {'success': ..., 'output': ...}; wait=False returns {'status': 'task started', 'task_id': ...} right away (or a 'busy' status if another task/workflow is running)
• get_execution_status() - Get current execution status
• get_task_status(task_id) - Get task execution output by task ID (end_time is None while running; failures are in run_error)
• wait_for_task(task_id, timeout=None, poll_interval=1.0) - Poll until the task finishes and return its record

On current ivoryOS versions a wait=False task does not get its output recorded, so wait_for_task can't return it (and on <= 1.6.12 it never finishes), and async def instrument methods are cancelled partway. Use wait=True (the default).

Workflow Script Operations

• list_workflow_scripts(search_key='', deck_name='') - List available scripts
• load_workflow_script(workflow_name) - Load a specific script
• submit_workflow_script(workflow_name, main_script='', cleanup_script='', prep_script='') - Submit a script

Workflow Execution

• run_workflow_repeat(repeat_time=None, batch_size=None) - Run workflow with simple repeat
• run_workflow_kwargs(kwargs_list=None, batch_size=1) - Run workflow with parameter sets
• run_workflow_campaign(optimizer_type, parameters, objectives, repeat=25, batch_size=1, steps={}, parameter_constraints=None, existing_data=None) - Run optimization campaign
• get_queue() - Get workflow queue

Workflow Control

• pause_and_resume() - Toggle workflow pause/resume
• abort_pending_workflow() - Abort pending executions
• stop_current_workflow() - Stop current execution

Data Operations

• list_workflow_data(workflow_name='') - List workflow execution data
• get_last_workflow_run_id(workflow_name='') - Get the most recent workflow run ID
• load_workflow_data(workflow_id) - Load specific workflow data

Exception Handling

The client provides specific exception types:

• IvoryosError - Base exception
• AuthenticationError - Authentication failures
• ConnectionError - Connection issues
• WorkflowError - Workflow operation failures
• TaskError - Task execution failures

from ivoryos_client import IvoryosClient, AuthenticationError, WorkflowError

try:
    with IvoryosClient(url="http://localhost:8000/ivoryos", username="admin", password="admin") as client:
        result = client.execute_task("sdl", "dose_solid", {"amount_in_mg": "5"})
except AuthenticationError:
    print("Authentication failed")
except WorkflowError as e:
    print(f"Workflow error: {e}")

Development

Setup Development Environment

git clone https://gitlab.com/heingroup/ivoryos-suite/ivoryos-client
cd ivoryos-client
pip install -e ".[dev]"

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request