Runtime API reference

Installation

Install IvoryOS with pip:

pip install ivoryos

Launch IvoryOS

import ivoryos

ivoryos.run(__name__)
ivoryos.run(module=None, host='0.0.0.0', port=None, debug=None, llm_server=None, model=None, config: Config | None = None, logger: str | list | None = None, logger_output_name: str | None = None, enable_design: bool = True, blueprint_plugins: list | Blueprint = [], exclude_names: list = [], notification_handler=None, optimizer_registry: dict | None = None, templates_dir: str = 'templates')

Start ivoryOS app server.

Parameters:

  • module – module name, __name__ for current module

  • host – host address, defaults to 0.0.0.0

  • port – port, defaults to None, and will use 8000

  • debug – debug mode, defaults to None (True)

  • llm_server – llm server, defaults to None. If None or incorrect, app will run without design-agent feature

  • model – llm model, defaults to None. If None or incorrect, app will run without design-agent feature

  • config – config class, defaults to None

  • logger – logger name of list of logger names, defaults to None

  • logger_output_name – log file save name of logger, defaults to None, and will use “default.log”

  • enable_design – enable design canvas, database and workflow execution

  • blueprint_plugins – Union[list[Blueprint], Blueprint] custom Blueprint pages

  • exclude_names – list[str] module names to exclude from parsing

  • notification_handler – notification handler function

  • templates_dir – directory to import templates from, defaults to “templates”

Add loggers

To add one or more loggers:

ivoryos.run(__name__, logger="logger name")
ivoryos.run(__name__, logger=["logger 1", "logger 2"])

By default, logs are saved to default.log. You can choose another log file name:

from datetime import datetime

ivoryos.run(
    __name__,
    logger_output_name=f"log_{datetime.today().strftime('%Y-%m-%d')}.log",
)

Add notification handlers

Notification handlers can send messages, such as email, SMS, or Slack notifications, when a workflow uses Pause.

def slack_bot(message: str):
    # Send message to a Slack channel.
    pass


ivoryos.run(__name__, notification_handler=slack_bot)
ivoryos.run(__name__, notification_handler=[slack_bot, another_notification_handler])

Parameter type conversion

For the integrator-facing guide to typed UI controls, including Enum dropdowns, see Input types and UI controls.

The parameter converter supports the following basic types:

int, float, str, bool, list, tuple, set

When defining functions for scripting workflows, use these supported types as type hints to enable automatic parameter conversion.

If a parameter type hint is not one of the supported types, IvoryOS attempts to evaluate it with ast.literal_eval(). If evaluation fails, the parameter is treated as str.

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 str
    param4 will be converted to bool
    param5 will be converted to list
    """
    pass


ivoryos.run(__name__)

Design agent

The design agent simplifies workflow creation by allowing users to generate experimental actions with natural language. Instead of manually searching through available methods, you can describe your intent, and the agent extracts likely actions from all instruments in the current deck configuration. It also supports the flow-control functions wait and comment.

Natural language input with the abstract_sdl deck, using the qwen3-30b-a3b-instruct-2507 model.

Configuration

The design agent supports any large language model compatible with the OpenAI Chat Completions API v1. If OPENAI_API_KEY, model, or llm_server is missing or incorrect, IvoryOS starts without the design-agent feature.

Set the API key as an environment variable or create a .env file in the project root:

OPENAI_API_KEY=<your_key_here>

Pass the model name and llm_server base URL to ivoryos.run(...).

Cloud LLM provider

Use this configuration to connect to remote providers.

import ivoryos

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

Local LLM provider

The OpenAI-compatible API implementation also allows locally hosted LLMs.

import ivoryos

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

Note

For every request, the agent saves the full prompt and raw JSON response to ivoryos_data/llm_output/ for debugging and transparency.

Tips for model selection and daily use

  • Minimum model requirement: for consistent JSON output, a model equivalent to meta-llama-3.1-8b-instruct or better is recommended.

  • Model size: modern models and models with more than 8B parameters are usually more reliable but require more compute.

  • Avoid thinking models: reasoning models are not recommended because of increased output time.

  • Improve with documentation: rigorous method and class documentation improves accuracy because extracted docs are used as LLM context.

  • Prompt clarity: shorter and more direct user prompts tend to be more reliable.