### Quick Start IvoryOS

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Begin using ivoryOS by importing and running the main function. This is the basic setup for starting the framework.

```python
import ivoryos

ivoryos.run(__name__)
```

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

### Initialize and Use IvoryosClient

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/client.md

Demonstrates how to initialize the IvoryosClient with connection details and use it as a context manager to interact with the ivoryOS backend. Includes examples for getting platform info, checking execution status, and executing a task.

```python
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
    result = client.execute_task("sdl", "dose_solid", {"amount_in_mg": "5"})
    print(result)
```

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

### Quick Start IvoryOS Integration

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/README.md

Integrate IvoryOS into your Python script to run the web interface. This example shows how to initialize your robot and start the IvoryOS server.

```python
my_robot = Robot()

import ivoryos

ivoryos.run(__name__)
```

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

### Setup Development Environment for ivoryOS Client

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/client.md

Commands to clone the ivoryOS client repository and install it in development mode with all necessary dependencies. This is for developers contributing to the project.

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

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

### Install MCP Server

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Install the IvoryOS MCP server by cloning the repository, installing dependencies using `uv`, and then installing the server itself.

```bash
# Install MCP server
git clone https://gitlab.com/heingroup/ivoryos-mpc
cd ivoryos-mcp
pip install uv
uv pip install -r uv.lock
mcp install ivoryos_mcp/server.py
```

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

### Start IvoryOS Web Server

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

The main entry point to start the IvoryOS web server. Visit http://localhost:8000 after starting. Default login is admin/admin.

```python
import ivoryos

# Basic usage - start with current module's hardware
class Robot:
    def move(self, x: float, y: float) -> dict:
        """Move robot to position"""
        return {"x": x, "y": y, "status": "moved"}

    def grab(self, item: str) -> bool:
        """Grab an item"""
        return True

robot = Robot()
ivoryos.run(__name__)  # Visit http://localhost:8000, login: admin/admin
```

```python
# With custom configuration
ivoryos.run(
    __name__,
    host="0.0.0.0",
    port=8000,
    debug=True,
    logger="my_logger",                    # Single logger
    logger=["logger1", "logger2"],         # Multiple loggers
    logger_output_name="experiment.log",   # Custom log filename
    enable_design=True,                    # Enable workflow design canvas
    exclude_names=["internal_module"],     # Exclude modules from UI
)
```

```python
# With LLM design agent (OpenAI)
ivoryos.run(
    __name__,
    model="gpt-4o",
    llm_server="https://api.openai.com/v1"
)
```

```python
# With local LLM (Ollama)
ivoryos.run(
    __name__,
    model="qwen3-30b-a3b-instruct-2507",
    llm_server="http://localhost:11434/v1/"
)
```

```python
# Offline mode (uses saved blueprint from previous run)
ivoryos.run()
```

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

### Install ivoryOS Client

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/client.md

Install the ivoryOS client library using pip. This command should be run in your terminal.

```bash
pip install ivoryos-client
```

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

### Install IvoryOS

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/index.md

Install the IvoryOS library using pip. Ensure you are in a Python virtual environment.

```console
(.venv) $ pip install ivoryos
```

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

### Install IvoryOS MCP Server

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/mcp.md

Install the IvoryOS MCP server using the `mcp install` command. This command is used when integrating with Claude Desktop.

```bash
mcp install ivoryos_mcp/server.py
```

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

### 32-bit Windows Installation for IvoryOS

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/README.md

Specific installation steps for 32-bit Windows environments, addressing potential compatibility issues with certain dependencies like Flask-Session and greenlet.

```bash
# 1. Install Flask-Session<0.7 (that doesn't depend on msgspec) and pandas (some pandas versions are not compatible with 32-bit Windows)
pip install Flask-Session<0.7
pip install pandas --user --only-binary=:all:

# 2. Install greenlet from conda-forge (32-bit PyPI wheels are no longer available)
conda install -c conda-forge greenlet -y

# 3. Finally, install IvoryOS
pip install ivoryos
```

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

### GET /ivoryos/instruments/new/

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Interface for connecting to a new instrument.

```APIDOC
## GET /ivoryos/instruments/new/

### Description
Interface for connecting to a new instrument.

### Method
GET

### Endpoint
/ivoryos/instruments/new/

### Parameters
#### Query Parameters
- **instrument** (string) - Required - Instrument name
```

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

### Install IvoryOS via Pip

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/README.md

Install the IvoryOS package using pip. This is the standard installation method for most users.

```bash
pip install ivoryos
```

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

### Install Dependencies with uv

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/mcp.md

Install project dependencies using `uv pip install`. This command reads dependencies from `uv.lock`. Ensure you have activated your virtual environment first.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r uv.lock
```

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

### GET /instruments/new/

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Retrieves information or initiates connection for a new instrument.

```APIDOC
## GET /instruments/new/

### Description
Interface for connecting to a new instrument.

### Method
GET

### Endpoint
/instruments/new/

### Parameters
#### Query Parameters
- **instrument** (string) - Required - Instrument name
```

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

### GET /ivoryos/instruments/new/{instrument}

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Interface for connecting to a new instrument.

```APIDOC
## GET /ivoryos/instruments/new/{instrument}

### Description
Interface for connecting to a new instrument.

### Method
GET

### Endpoint
/ivoryos/instruments/new/{instrument}
```

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

### GET /ivoryos/help

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/home.md

Provides static information about IvoryOS.

```APIDOC
## GET /ivoryos/help

### Description
IvoryOS info page

### Method
GET

### Endpoint
/ivoryos/help
```

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

### Get Available Instruments (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Use this GET request to list all instruments available on the IvoryOS system. Ensure the server is running at the specified address.

```bash
# Get all available instruments
curl -X GET http://localhost:8000/ivoryos/instruments \
  -H "Content-Type: application/json"
```

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

### Core API: ivoryos.run()

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

The main entry point to start the IvoryOS web server. It dynamically exposes initialized Python modules as controllable instruments through a visual interface. Supports various configurations including online/offline modes, LLM integration, and custom logging.

```APIDOC
## ivoryos.run()

### Description
Starts the IvoryOS web server, exposing Python modules as controllable instruments via a visual interface. Supports online/offline modes, LLM integration, and custom configurations.

### Method
Python function call

### Endpoint
N/A (local server)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import ivoryos

# Basic usage
ivoryos.run(__name__)

# With custom configuration
ivoryos.run(
    __name__,
    host="0.0.0.0",
    port=8000,
    debug=True,
    logger="my_logger",
    logger=["logger1", "logger2"],
    logger_output_name="experiment.log",
    enable_design=True,
    exclude_names=["internal_module"]
)

# With LLM design agent (OpenAI)
ivoryos.run(
    __name__,
    model="gpt-4o",
    llm_server="https://api.openai.com/v1"
)

# With local LLM (Ollama)
ivoryos.run(
    __name__,
    model="qwen3-30b-a3b-instruct-2507",
    llm_server="http://localhost:11434/v1/"
)

# Offline mode
ivoryos.run()
```

### Response
#### Success Response (200)
N/A (starts a web server)

#### Response Example
N/A
```

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

### Example Function with Type Hinting

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Demonstrates how to use type hints for automatic parameter conversion in workflow functions. Supported types include int, float, str, bool, list, and tuple.

```python
def example_function(param1: int, param2: float, param3: str, param4: bool, param5: list):
    """
    When calling example_function from the workflow interface:
    param1 will be converted to int
    param2 will be converted to float
    param3 will remain as str
    param4 will be converted to bool
    param5 will be converted to list
    """
    pass

ivoryos.run(__name__)
```

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

### Get Platform Information

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Retrieve information about the IvoryOS platform, including available instruments. This is typically done after initializing the client.

```python
# Get platform info
info = client.get_platform_info()
print(f"Instruments: {info['instruments']}")
```

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

### Define Hardware API with Type Hints and Docstrings

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Structure hardware APIs for IvoryOS integration. Methods with type hints and docstrings are automatically exposed in the UI. Private methods starting with '_' are hidden.

```python
from enum import Enum
from typing import Optional
import logging

class Solvent(Enum):
    """Enum values appear as dropdowns in UI"""
    Methanol = "Methanol"
    Ethanol = "Ethanol"
    Acetone = "Acetone"

class AbstractPump:
    def __init__(self, com_port: str):
        self.com_port = com_port

    def dose_liquid(self, amount_in_ml: float, rate_ml_per_minute: float = 1.0) -> bool:
        """Dose liquid at specified rate"""
        # Hardware communication logic
        return True

    def prime(self, volume_ml: float = 5.0) -> bool:
        """Prime the pump lines"""
        return True

class AbstractBalance:
    def __init__(self, com_port: str):
        self.com_port = com_port

    def tare(self) -> bool:
        """Tare the balance"""
        return True

    def weigh_sample(self) -> float:
        """Get current weight reading"""
        return 0.0

    def dose_solid(self, amount_in_mg: float) -> float:
        """Dose solid material"""
        return amount_in_mg

class AbstractSDL:
    """Self-driving Lab API - docstring used by LLM design agent"""

    def __init__(self, pump: AbstractPump, balance: AbstractBalance):
        self.pump = pump
        self.balance = balance
        self.logger = logging.getLogger("sdl_logger")

    def analyze(self, param_1: int, param_2: int) -> float:
        """Analyze current chemical sample"""
        self.logger.info(f"Analyzing with params: {param_1}, {param_2}")
        import random
        return random.random()

    def dose_solid(self, amount_in_mg: float = 5.0, solid_name: str = "acetaminophen") -> int:
        """Dose specified amount of solid material"""
        self.balance.dose_solid(amount_in_mg=amount_in_mg)
        self.balance.weigh_sample()
        self.logger.info(f"Dosed {amount_in_mg}mg of {solid_name}")
        return 1

    def dose_solvent(self,
                     solvent_name: Optional[Solvent] = None,
                     amount_in_ml: float = 5.0,
                     rate_ml_per_minute: float = 1.0) -> int:
        """Dose solvent at specified rate"""
        if solvent_name is None:
            solvent_name = Solvent.Methanol
        self.pump.dose_liquid(amount_in_ml, rate_ml_per_minute)
        self.logger.info(f"Dosed {amount_in_ml}mL of {solvent_name.value}")
        return 1

    def equilibrate(self, temp: float, duration: float) -> None:
        """Equilibrate sample at temperature for duration (minutes)"""
        self.logger.info(f"Equilibrating at {temp}C for {duration} min")

    def _send_command(self) -> None:
        """Helper functions starting with _ are hidden from UI"""
        pass

# Initialize hardware
balance = AbstractBalance("COM1")
pump = AbstractPump("COM2")
sdl = AbstractSDL(pump, balance)

if __name__ == "__main__":
    import ivoryos
    ivoryos.run(__name__, logger="sdl_logger")
```

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

### User Signup API

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/auth.md

Handles user signup functionality. Supports both POST for creating a new account and GET for loading the signup form.

```APIDOC
## POST /ivoryos/auth/signup

### Description
Signs up a new user for an account.

### Method
POST

### Endpoint
/ivoryos/auth/signup

### Parameters
#### Request Body
- **username** (string) - Required - The desired username.
- **password** (string) - Required - The user's password.

### Response
#### Success Response (302 Found)
Redirects to GET /ivoryos/auth/login upon successful signup.

#### Error Response (409 Conflict)
Returned when a user with the provided username already exists. Redirects to GET /ivoryos/auth/signup.
```

```APIDOC
## GET /ivoryos/auth/signup

### Description
Loads the user signup form.

### Method
GET

### Endpoint
/ivoryos/auth/signup
```

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

### Clone IvoryOS MCP Repository

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/mcp.md

Clone the IvoryOS MCP repository and navigate into the project directory. This is the first step in the installation process.

```bash
git clone https://gitlab.com/heingroup/ivoryos-mpc
cd ivoryos-mcp
```

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

### GET /ivoryos/

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/home.md

Retrieves the homepage for IvoryOS, listing all available routes.

```APIDOC
## GET /ivoryos/

### Description
Home page for all available routes

### Method
GET

### Endpoint
/ivoryos/
```

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

### Get Instrument Methods (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Query for the available methods of a specific instrument by providing its name in the URL. This helps in understanding what actions can be performed.

```bash
# Get methods for specific instrument
curl -X GET http://localhost:8000/ivoryos/instruments/pump \
  -H "Content-Type: application/json"
```

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

### Run IvoryOS in Offline Mode

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Start ivoryOS in offline mode using a previously saved blueprint. This requires no active hardware connection.

```python
ivoryos.run()
```

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

### Run Plugin as Standalone Flask App with WebSocket

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/plugin.md

Configures and runs the plugin as a standalone Flask application with WebSocket support using SocketIO. It initializes SocketIO and starts the server with debugging enabled.

```python
if __name__ == '__main__':
    app = Flask(__name__)
    app.register_blueprint(plugin)
    socketio = SocketIO(app)
    init_socketio(socketio)
    socketio.run(app, debug=True, allow_unsafe_werkzeug=True)
```

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

### Example Solubility Test Template

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

This JSON defines a template for a solubility test experiment. It includes preparation, script, cleanup steps, and configurable parameters.

```json
{
  "name": "solubility_test",
  "author": "admin",
  "prep": "balance.tare()",
  "script": "sdl.dose_solid(amount_in_mg=#amount)\nsdl.dose_solvent(amount_in_ml=#volume)\nsdl.equilibrate(temp=#temp, duration=10)\nresult = sdl.analyze(param_1=1, param_2=2)",
  "cleanup": "sdl.equilibrate(temp=25, duration=5)",
  "parameters": {
    "amount": {"type": "float", "default": 5.0},
    "volume": {"type": "float", "default": 10.0},
    "temp": {"type": "float", "default": 50.0}
  }
}
```

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

### Setup vis.js Timeline for Workflow Visualization

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/data/templates/workflow_view.html

Initializes a vis.js Timeline component to display workflow execution steps. Configure options like horizontal scrolling and zoom behavior. The timeline is interactive, allowing selection of iteration items to scroll to corresponding cards.

```javascript
document.addEventListener('DOMContentLoaded', function() {
    // ---------------- Timeline Setup ----------------
    const container = document.getElementById('visualization');
    const groups = [
        { id: 'all', content: 'Workflow Execution' }
    ];
    const items = [
        {% if grouped.prep %} {
            id: 'prep',
            content: 'Prep',
            start: '{{ grouped.prep[0].start_time }}',
            end: '{{ grouped.prep[-1].end_time }}',
            className: 'prep',
            group: 'all'
        }, {% endif %}
        {% for repeat_index, step_list in grouped.script.items()|sort %} {
            id: 'iter{{ repeat_index }}',
            content: 'Iteration {{ repeat_index }}',
            start: '{{ step_list[0].start_time }}',
            end: '{{ step_list[-1].end_time }}',
            className: 'script',
            group: 'all'
        }, {% for step in step_list %} {% if step.method_name == "stop" %} {
            id: 'stop-{{ step.id }}',
            content: '🛑 Stop',
            start: '{{ step.start_time }}',
            type: 'point',
            className: 'stop',
            group: 'all',
            title: 'Stop event at {{ step.start_time }}'
        }, {% endif %} {% endfor %} {% endfor %}
        {% if grouped.cleanup %} {
            id: 'cleanup',
            content: 'Cleanup ',
            start: '{{ grouped.cleanup[0].start_time }}',
            end: '{{ grouped.cleanup[-1].end_time }}',
            className: 'cleanup',
            group: 'all'
        }, {% endif %}
    ];
    var timeline = new vis.Timeline(container, items, groups, {
        clickToUse: true,
        stack: false, // keep items from overlapping vertically
        horizontalScroll: true,
        zoomKey: 'ctrlKey'
    });
    timeline.on('select', function (props) {
        const id = props.items[0];
        if (id && id.startsWith('iter')) {
            const card = document.getElementById('card-' + id);
            if (card) {
                const yOffset = -80;
                const y = card.getBoundingClientRect().top + window.pageYOffset + yOffset;
                window.scrollTo({
                    top: y,
                    behavior: 'smooth'
                });
            }
        }
    });
```

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

### Run Plugin as Standalone Flask App

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/plugin.md

This code snippet shows how to run the plugin as a standalone Flask application. It registers the plugin blueprint and starts the Flask development server.

```python
if __name__ == '__main__':
    app = Flask(__name__)
    app.register_blueprint(plugin)
    app.run()
```

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

### Display Workflow Information with Jinja2

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/data/templates/workflow_database.html

This Jinja2 template iterates through a list of workflows, displaying key details such as name, ID, start time, end time, and a link to download data. It also includes conditional logic for displaying a delete link based on user session and workflow author.

```html
{% extends 'base.html' %} {% block title %}IvoryOS | Design Database{% endblock %} {% block body %} 

{% for workflow in workflows %} {% endfor %} 

Workflow name

Workflow ID

Start time

End time

Data

[{{ workflow.name }}]({{ url_for('data.workflow_logs', workflow_id=workflow.id) }})

{{ workflow.id }}

{{ workflow.start_time.strftime("%Y-%m-%d %H:%M:%S") if workflow.start_time else '' }}

{{ workflow.end_time.strftime("%Y-%m-%d %H:%M:%S") if workflow.end_time else '' }}

{% if workflow.data_path %} [{{ workflow.data_path }}]({{ url_for('data.download_results', filename=workflow.data_path) }}) {% endif %}

{% if session['user'] == 'admin' or session['user'] == workflow.author %} {# [delete]({{ url_for('data.delete_workflow_data', workflow_id=workflow.id) }})#} [Delete](#) {% else %} delete {% endif %}

{# paging#}

[Previous]({{ url_for('data.list_workflows', page=workflows.prev_num) }})

{% for num in workflows.iter_pages() %} {% if num %} 

[{{ num }}]({{ url_for('data.list_workflows', page=num) }})

{% else %} 

…

{% endif %} {% endfor %}

[Next]({{ url_for('data.list_workflows', page=workflows.next_num) }})

{% endblock %}
```

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

### POST /instruments/new/

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Connects to a new instrument using provided device name and dynamic initialization arguments.

```APIDOC
## POST /instruments/new/

### Description
Connect to a new instrument.

### Method
POST

### Endpoint
/instruments/new/

### Parameters
#### Request Body
- **device_name** (string) - Required - Module instance name (e.g. my_instance = MyClass())
- **kwargs** (object) - Optional - Dynamic module initialization kwargs fields
```

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

### Access Hardware Components in IvoryOS Plugin

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/plugin.md

Demonstrates how to import and access hardware components initialized for IvoryOS using `GlobalConfig`. Uncomment the block to enable hardware access.

```python
# [access hardware] Comment back this block if need access to control hardware
# to get the component, user global_config.deck.hardware_name (e.g. global_config.deck.balance)
from ivoryos.utils.global_config import GlobalConfig
global_config = GlobalConfig()
```

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

### Initialize IvoryOS Client

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Initialize the IvoryOS client with connection details and authentication credentials. Consider using the context manager for recommended usage.

```python
from ivoryos_client import IvoryosClient, AuthenticationError, WorkflowError

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

```python
# Context manager usage (recommended)
with IvoryosClient(url="http://localhost:8000/ivoryos", username="admin", password="admin") as client:
```

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

### Configure MCP Server via .env File

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Set up the MCP server configuration using a `.env` file in the `ivoryos-mcp` directory, specifying connection details for IvoryOS.

```bash
# Alternative: Configure via .env file
# Create .env in ivoryos-mcp directory:
IVORYOS_URL=http://127.0.0.1:8000/ivoryos
IVORYOS_USERNAME=admin
IVORYOS_PASSWORD=admin
```

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

### GET /ivoryos/files/script-json

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/design.md

Exports a workflow design file in JSON format.

```APIDOC
## GET /ivoryos/files/script-json

### Description
Export a workflow design file (.JSON)

### Method
GET

### Endpoint
/ivoryos/files/script-json
```

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

### POST /ivoryos/instruments/new/{instrument}

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Provides an interface for connecting to a new instrument.

```APIDOC
## POST /ivoryos/instruments/new/{instrument}

### Description
Interface for connecting to a new instrument.

### Method
POST

### Endpoint
/ivoryos/instruments/new/{instrument}
```

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

### GET /ivoryos/files/script-python

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/design.md

Exports a workflow design file in Python format.

```APIDOC
## GET /ivoryos/files/script-python

### Description
Export a workflow design file (.py)

### Method
GET

### Endpoint
/ivoryos/files/script-python
```

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

### Get Instrument Methods

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/design.md

Retrieves methods for a specific instrument in the workflow design.

```APIDOC
## GET /draft/instruments/<string:instrument>

### Description
Retrieve methods for a specific instrument in the workflow design.

### Method
GET

### Endpoint
/draft/instruments/<string:instrument>

### Parameters
#### Path Parameters
- **instrument** (string) - Required - The name of the instrument to handle methods for.

### Response
#### Success Response (200)
- **methods** (array) - A list of methods for the specified instrument.
```

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

### Get Data for Plotting

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Retrieve data specifically formatted for plotting from a workflow execution.

```bash
curl -X GET http://localhost:8000/ivoryos/executions/data/1
```

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

### Define Main Plugin Blueprint Route

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/plugin.md

Defines the main Flask Blueprint for the plugin and sets up the root route ('/'). This route renders an 'example.html' template and checks for the existence of 'base.html'.

```python
from flask import render_template, Blueprint, current_app
import os

plugin = Blueprint("plugin", __name__, template_folder=os.path.join(os.path.dirname(__file__), "templates"))

@plugin.route('/')
def main():
    base_exists = "base.html" in current_app.jinja_loader.list_templates()
    return render_template('example.html', base_exists=base_exists)
```

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

### IvoryosClient Initialization Parameters

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/client.md

Shows the parameters required for initializing the IvoryosClient. The timeout parameter is optional and defaults to 30.0 seconds.

```python
IvoryosClient(url, username, password, timeout=30.0)
```

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

### Get Specific Workflow Data

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Retrieve detailed data for a specific workflow execution by its ID.

```bash
curl -X GET http://localhost:8000/ivoryos/executions/records/1
```

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

### POST /ivoryos/instruments/new/module

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Manually imports API module(s) for advanced features.

```APIDOC
## POST /ivoryos/instruments/new/module

### Description
Manually import API module(s).

### Method
POST

### Endpoint
/ivoryos/instruments/new/module

### Parameters
#### Request Body
- **filepath** (string) - Required - API (Python class) module filepath

### Notes
Imports the module and redirects to [`GET /ivoryos/instruments/new/`](#get--ivoryos-instruments-new-).
```

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

### Get Workflow Data for Plotting

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/data.md

Retrieves workflow data specifically formatted for plotting purposes.

```APIDOC
## GET /ivoryos/executions/data/(int:workflow_id)

### Description
Gets workflow data for plotting by workflow ID.

### Method
GET

### Endpoint
/ivoryos/executions/data/{workflow_id}

### Parameters
#### Path Parameters
- **workflow_id** (int) - Required - The ID of the workflow execution.
```

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

### Abort Pending Workflow

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Cancel any workflows that are currently in the pending state. This action prevents them from starting execution.

```python
client.abort_pending_workflow()
```

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

### Get Action Step Editing Form

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/design.md

Retrieves the editing form for a specific action step in the workflow design.

```APIDOC
## GET /draft/steps/<int:uuid>

### Description
Get the editing form for an action step.

### Method
GET

### Endpoint
/draft/steps/<int:uuid>

### Parameters
#### Path Parameters
- **uuid** (integer) - Required - The step number ID.

### Response
#### Success Response (200)
- **form** (object) - The editing form for the action step.
```

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

### Get Available Variables

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/design.md

Retrieves available variables for the current script state. Can be filtered by a specific step ID.

```APIDOC
## GET /ivoryos/draft/variables

### Description
Get available variables for the current script state.

### Method
GET

### Endpoint
/ivoryos/draft/variables

### Parameters
#### Query Parameters
- **before_id** (integer) - Optional - Filter variables available before this step ID.

### Response
#### Success Response (200)
- **variables** (array) - A list of available variables.
```

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

### Client Initialization

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/client.md

Initializes the ivoryOS client with the server URL, username, and password. It can also be used as a context manager.

```APIDOC
## Client Initialization

### Description
Initializes the ivoryOS client with the server URL, username, and password. It can also be used as a context manager.

### Parameters
- **url** (string) - Required - The base URL of the ivoryOS backend.
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.
- **timeout** (float) - Optional - The timeout in seconds for requests. Defaults to 30.0.

### Request Example
```python
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:
    pass
```
```

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

### Import Templates from Directory

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Use this function to import experiment templates from a specified directory. Ensure the directory path is correct.

```python
from ivoryos import import_templates_from_dir
import_templates_from_dir("/path/to/templates")
```

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

### User Login API

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/auth.md

Handles user login functionality. Supports both POST for credentials and GET for loading the login form.

```APIDOC
## POST /ivoryos/auth/login

### Description
Logs in a user.

### Method
POST

### Endpoint
/ivoryos/auth/login

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Response
#### Success Response (302 Found)
Redirects to the homepage upon successful login.

#### Error Response (401 Unauthorized)
Returned when the username or password is incorrect. Redirects to GET /ivoryos/auth/login.
```

```APIDOC
## GET /ivoryos/auth/login

### Description
Loads the user login form.

### Method
GET

### Endpoint
/ivoryos/auth/login
```

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

### Get Execution Queue (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Retrieve the current execution queue, which lists pending tasks with their IDs, names, and statuses.

```bash
# Get execution queue
curl -X GET http://localhost:8000/ivoryos/executions/queue
```

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

### Configure API Key for Design Agent

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Set up the OpenAI API key for the design agent. This can be done via an environment variable or a .env file.

```text
OPENAI_API_KEY=<your_key_here>
```

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

### Display Import Preview

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/design/templates/components/modals/python_import_modal.html

Shows a preview of the workflows to be imported, including warnings for duplicates. Allows users to select which workflows to import or overwrite.

```javascript
function showPreview() {
    document.getElementById('pythonImportForm').style.display = 'none';
    document.getElementById('pythonImportPreview').style.display = 'block';
    document.getElementById('btnUploadPython').style.display = 'none';
    document.getElementById('btnConfirmPython').style.display = 'inline-block';
    const list = document.getElementById('pythonWorkflowList');
    list.innerHTML = '';
    const hasDuplicates = duplicateList.length > 0;
    if (hasDuplicates) {
        document.getElementById('pythonDuplicateWarning').style.display = 'block';
    }
    for (const name of Object.keys(importedWorkflows)) {
        const li = document.createElement('li');
        li.className = 'list-group-item';
        const isDuplicate = duplicateList.includes(name);
        const badge = isDuplicate ? '<span class="badge bg-warning text-dark">Exists</span>' : '<span class="badge bg-success">New</span>';
        // Checkbox to select for import
        // Default: check if new, uncheck if duplicate? user wants to choose.
        // "pop whether user want to overwrite that".
        // It's better to force user to check explicitly if they want to overwrite.
        const checked = !isDuplicate ? 'checked' : '';
        li.innerHTML = ` <div class="form-check">
            <input class="form-check-input workflow-checkbox" type="checkbox" value="${name}" id="cb_${name}" ${checked} data-is-duplicate="${isDuplicate}">
            <label class="form-check-label" for="cb_${name}"> ${name} ${badge} </label>
        </div> `;
        list.appendChild(li);
    }
}
```

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

### Configure Workflow Execution (Parameter Sets) (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Execute a workflow with multiple sets of parameters. Provide a list of JSON objects, where each object contains a distinct set of keyword arguments for the workflow.

```bash
# Run workflow with parameter sets
curl -X POST http://localhost:8000/ivoryos/executions/config \
  -H "Content-Type: application/json" \
  -d '{
    "kwargs_list": [
      {"amount_in_mg": 5, "temp": 25},
      {"amount_in_mg": 10, "temp": 30},
      {"amount_in_mg": 15, "temp": 35}
    ]
  }'
```

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

### Configure IvoryOS Credentials in .env

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/mcp.md

Set the IvoryOS URL and login credentials in the `.env` file. This is an alternative to configuring them directly in the server script.

```bash
IVORYOS_URL=http://127.0.0.1:8000/ivoryos
IVORYOS_USERNAME=admin
IVORYOS_PASSWORD=admin
```

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

### Get Workflow Data, Steps, and Logs by Workflow ID

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/data.md

Retrieves comprehensive workflow data, including steps and logs, for a specific workflow execution.

```APIDOC
## GET /ivoryos/executions/records/(int:workflow_id)

### Description
Gets workflow data, steps, and logs for a given workflow ID.

### Method
GET

### Endpoint
/ivoryos/executions/records/{workflow_id}

### Parameters
#### Path Parameters
- **workflow_id** (int) - Required - The ID of the workflow execution.
```

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

### POST /ivoryos/instruments/new/deck-python

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/control.md

Manually imports a deck module for advanced features.

```APIDOC
## POST /ivoryos/instruments/new/deck-python

### Description
Manually import a deck.

### Method
POST

### Endpoint
/ivoryos/instruments/new/deck-python

### Parameters
#### Request Body
- **filepath** (string) - Required - Deck module filepath

### Notes
Imports the module and redirects to the previous page.
```

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

### Load Workflow Script (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Fetch a specific workflow script by its name using a GET request. This is useful for inspecting script details before execution.

```bash
# Load a workflow script
curl -X GET http://localhost:8000/ivoryos/library/solubility_test
```

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

### Fetch and Display Current Run Configuration

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/execute/templates/components/logging_panel.html

Attaches an event listener to a button to fetch the current task's configuration details. It then renders these details in a modal, updating the modal title to 'Current Run Details'.

```javascript
document.getElementById('view-current-config').addEventListener('click', function() {
    fetch("{{ url_for('execute.get_current_task_details') }}")
    .then(response => {
        if (!response.ok) {
            return response.json().then(data => {
                throw new Error(data.error || "Failed to fetch current config");
            });
        }
        return response.json();
    })
    .then(data => {
        // Prepare the modal with 'data'
        // Using existing renderTaskDetails function meant for queued tasks
        const fullConfig = data["Full Config"] || null;
        renderTaskDetails(data, fullConfig);
        // Update modal title logic
        const modalHeader = document.querySelector('#queueDetailsModal .modal-title');
        if (modalHeader) {
            modalHeader.innerText = "Current Run Details";
        }
        const modal = new bootstrap.Modal(document.getElementById('queueDetailsModal'));
        modal.show();
    })
    .catch(error => {
        alert('Error: ' + error.message);
    });
});
```

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

### Unique Blueprint Naming Convention

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/plugin.md

Illustrates the requirement for a unique Blueprint name when defining a Flask Blueprint for an IvoryOS plugin. The name 'plugin' is used here as an example.

```python
plugin = Blueprint("plugin", __name__, template_folder=os.path.join(os.path.dirname(__file__), "templates"))
```

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

### Check Execution Status (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

This GET request allows you to check the current status of ongoing tasks, including whether the system is busy and details about the last executed task.

```bash
# Check execution status
curl -X GET http://localhost:8000/ivoryos/executions/status
```

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

### Sample Group Styling

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/design/templates/components/info_modal.html

Styles a container for sample groups within the workflow, using flexbox for horizontal alignment and applying a dashed border and background.

```css
.sample-group {
  display: flex;
  gap: 8px;
  padding: 10px;
  background: #f8f9fa;
  border-radius: 6px;
  border: 1px dashed #dee2e6;
}
```

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

### Download Execution Logs

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Download the execution logs for a specific workflow.

```bash
curl -X GET http://localhost:8000/ivoryos/executions/records/1/logs \
  -o workflow.log
```

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

### Get Current Form Data

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/execute/templates/components/tab_configuration.html

Extracts data from the table rows, including input, select, and textarea values. Only rows with at least one non-empty field are included in the returned data.

```javascript
function getCurrentFormData() {
  var tableBody = document.getElementById("tableBody");
  var rows = tableBody.getElementsByTagName('tr');
  var data = [];
  for (var i = 0; i < rows.length; i++) {
    var inputs = rows[i].querySelectorAll('input, select, textarea');
    var rowData = {};
    var hasData = false;
    for (var j = 0; j < inputs.length; j++) {
      var input = inputs[j];
      var name = input.name;
      if (name) {
        var columnName = name.substring(0, name.indexOf('['));
        rowData[columnName] = input.value;
        if (input.value.trim() !== '') {
          hasData = true;
        }
      }
    }
    if (hasData) {
      data.push(rowData);
    }
  }
  return data;
}
```

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

### Plugin System: Flask Blueprint Integration

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Extend IvoryOS with custom pages using Flask Blueprints. Plugins appear in the navigation panel and can access hardware components initialized for IvoryOS.

```APIDOC
## Flask Blueprint Integration

### Description
Allows extending IvoryOS with custom web pages and functionality by integrating Flask Blueprints. These plugins appear in the navigation panel and can interact with IvoryOS hardware components.

### Method
Flask Blueprint registration

### Endpoint
N/A (integrated into the IvoryOS web application)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from flask import render_template, Blueprint, Flask
from flask_socketio import SocketIO
import os

# Example of a custom plugin blueprint
custom_plugin_bp = Blueprint('custom_plugin', __name__,
                              static_folder='static',
                              template_folder='templates')

@custom_plugin_bp.route('/custom')
def custom_page():
    return render_template('custom_page.html')

# In your main IvoryOS application setup:
# app = Flask(__name__)
# socketio = SocketIO(app)
# app.register_blueprint(custom_plugin_bp, url_prefix='/plugins/custom')

# IvoryOS run command would then include the app object
# ivoryos.run(app=app, __name__)
```

### Response
#### Success Response (200)
N/A (integrates custom UI elements)

#### Response Example
N/A
```

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

### POST /executions/campaign

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/routes/execute.md

Initiates a campaign execution with specified parameters.

```APIDOC
## POST /executions/campaign

### Description
Initiates a campaign execution with specified parameters. This endpoint is used to start a new optimization or simulation run.

### Method
POST

### Endpoint
/executions/campaign

### Parameters
#### Form Parameters
- **repeat** (number) - Required - Number of iterations to run.
- **optimizer_type** (string) - Required - Type of optimizer to use.
- **existing_data** (any) - Optional - Existing data to use for optimization.
- **parameters** (object) - Optional - Parameters for optimization.
- **objectives** (object) - Optional - Objectives for optimization.

### Request Example
```json
{
  "repeat": 10,
  "optimizer_type": "genetic",
  "parameters": {
    "population_size": 50
  },
  "objectives": {
    "minimize_cost": true
  }
}
```

### Response
#### Success Response (200)
Details about the created campaign execution.
```

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

### Run Workflow Campaign

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Initiate a workflow campaign with defined parameters, objectives, and repetition count. This is useful for systematic exploration of experimental conditions.

```python
client.run_workflow_campaign(
    parameters={"amount": {"type": "range", "bounds": [1, 20]}},
    objectives={"yield": {"minimize": False}},
    repeat=25
)
```

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

### Implement Slack Notification Handler in IvoryOS

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/README.md

Use a custom notification handler for human-in-the-loop workflows. This example shows how to send a message to a Slack channel using the slack_sdk. Ensure your SLACK_TOKEN and user ID are correctly configured.

```python
def slack_bot(msg: str = "Hi"):
    """
    a function that can be used as a notification handler function("msg")
    :param msg: message to send
    """
    from slack_sdk import WebClient

    slack_token = "your slack token"
    client = WebClient(token=slack_token)

    my_user_id = "your user id"  # replace with your actual Slack user ID

    client.chat_postMessage(channel=my_user_id, text=msg)
```

```python
import ivoryos
ivoryos.run(__name__, notification_handler=slack_bot)
```

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

### Initialize and Manage Data Preview Modal

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/ivoryos/routes/execute/templates/components/tab_bayesian.html

Initializes a Bootstrap modal for data preview and handles its display logic. Ensures the modal is correctly appended to the body to avoid z-index issues.

```javascript
const optimizerSchema = {{ optimizer_schema| tojson }};
document.addEventListener('DOMContentLoaded', function () {
    const dataSelect = document.getElementById('existing_data');
    const previewBtn = document.getElementById('previewBtn');
    const previewContent = document.getElementById('data_preview_content');
    const previewFilename = document.getElementById('previewFilename');
    const optimizerSelect = document.getElementById("optimizer_type");
    const toggle = document.getElementById('data_mode_toggle');
    const existingSection = document.getElementById('existing_data_section');
    const uploadSection = document.getElementById('upload_data_section');
    let previewModal = null; // Initialize Modal
    const modalEl = document.getElementById('dataPreviewModal');
    if (modalEl) {
        // Move modal to body to prevent z-index/display issues with tabs
        document.body.appendChild(modalEl);
        try {
            previewModal = new bootstrap.Modal(modalEl);
        } catch (e) {
            console.error("Failed to initialize Bootstrap Modal:", e);
        }
    }
```

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

### Run Bayesian Optimization Campaign (REST API)

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Initiate a Bayesian optimization campaign for workflow execution. Specify the number of repeats, optimizer type, parameter bounds, and objective functions.

```bash
# Run Bayesian optimization campaign
curl -X POST http://localhost:8000/ivoryos/executions/campaign \
  -H "Content-Type: application/json" \
  -d '{
    "repeat": 25,
    "optimizer_type": "ax",
    "parameters": {
      "amount_in_mg": {"type": "range", "bounds": [1.0, 20.0]},
      "temp": {"type": "range", "bounds": [20.0, 80.0]}
    },
    "objectives": {
      "yield": {"minimize": false}
    }
  }'
```

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

### Initialize IvoryOS with Local LLM

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Run ivoryOS in offline mode with a locally hosted LLM. This configuration uses the OpenAI API specification for local model interaction.

```python
import ivoryos

if __name__ == "__main__":
    ivoryos.run(model="qwen3-30b-a3b-instruct-2507", llm_server="http://localhost:11434/v1/")
```

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

### Configure IvoryOS MCP Server in Claude Desktop

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/mcp.md

Add IvoryOS MCP server configuration to the Claude Desktop configuration file. Ensure the `IVORYOS_URL`, `IVORYOS_USERNAME`, and `IVORYOS_PASSWORD` are correctly set.

```json
{
  "mcpServers": {
    "IvoryOS MCP": {
      "command": "uvx",
      "args": [
        "ivoryos-mcp"
      ],
      "env": {
        "IVORYOS_URL": "http://127.0.0.1:8000/ivoryos",
        "IVORYOS_USERNAME": "<IVORYOS_USERNAME>",
        "IVORYOS_PASSWORD": "<IVORYOS_PASSWORD>"
      }
    }
  }
}
```

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

### Initialize IvoryOS with Cloud LLM Provider

Source: https://github.com/accelerationconsortium/ivoryos/blob/main/docs/source/usage.md

Run ivoryOS in online mode, connecting to a cloud LLM provider like OpenAI. This configuration is suitable for using remote AI models.

```python
import ivoryos

if __name__ == "__main__":
    ivoryos.run(__name__, model="gpt-4o", llm_server="https://api.openai.com/v1")
```

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

### Run IvoryOS with Default Template Import

Source: https://context7.com/accelerationconsortium/ivoryos/llms.txt

Run IvoryOS, automatically importing workflow templates from the default './templates/' directory. Ensure your workflow JSON files are placed in this directory.

```python
import ivoryos

# Templates are automatically imported from ./templates/ directory by default
ivoryos.run(__name__)
```