ivoryos 1.3.7__tar.gz → 1.4.6__tar.gz

{ivoryos-1.3.7 → ivoryos-1.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ivoryos
-Version: 1.3.7
+Version: 1.4.6
 Summary: an open-source Python package enabling Self-Driving Labs (SDLs) interoperability
 Author-email: Ivory Zhang <ivoryzhang@chem.ubc.ca>
 License: MIT
@@ -17,6 +17,7 @@ Requires-Dist: Flask-SQLAlchemy
 Requires-Dist: Flask-WTF
 Requires-Dist: SQLAlchemy-Utils
 Requires-Dist: python-dotenv
+Requires-Dist: pandas
 Requires-Dist: astor; python_version < "3.9"
 Provides-Extra: optimizer-ax
 Requires-Dist: ax-platform; extra == "optimizer-ax"
@@ -24,9 +25,10 @@ Provides-Extra: optimizer-baybe
 Requires-Dist: baybe; extra == "optimizer-baybe"
 Provides-Extra: optimizer-nimo
 Requires-Dist: nimo; extra == "optimizer-nimo"
-Provides-Extra: optimizer
-Requires-Dist: ax-platform>=1.1.2; extra == "optimizer"
-Requires-Dist: baybe; extra == "optimizer"
+Provides-Extra: optimizers
+Requires-Dist: ax-platform>=1.1.2; extra == "optimizers"
+Requires-Dist: baybe>=0.14.0; extra == "optimizers"
+Requires-Dist: nimo; extra == "optimizers"
 Provides-Extra: doc
 Requires-Dist: sphinx; extra == "doc"
 Requires-Dist: sphinx-rtd-theme; extra == "doc"
@@ -41,34 +43,35 @@ Dynamic: license-file
 [![YouTube](https://img.shields.io/badge/YouTube-tutorial-red?logo=youtube)](https://youtu.be/dFfJv9I2-1g)
 [![YouTube](https://img.shields.io/badge/YouTube-demo-red?logo=youtube)](https://youtu.be/flr5ydiE96s)
 [![Published](https://img.shields.io/badge/Nature_Comm.-paper-blue)](https://www.nature.com/articles/s41467-025-60514-w)
+[![Community](https://img.shields.io/discord/1313641159356059770?label=Discord&logo=discord&color=5865F2)](https://discord.gg/AX5P9EdGVX)
 
-[//]: # ([![Discord]&#40;https://img.shields.io/discord/1313641159356059770?label=Discord&logo=discord&color=5865F2&#41;]&#40;https://discord.gg/AX5P9EdGVX&#41;)
+![ivoryos_logo.png](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/ivoryos_logo.png)
 
-![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/ivoryos.png)
-# ivoryOS: interoperable Web UI for self-driving laboratories (SDLs)
-A **plug-and-play** web interface for flexible SDLs 
+# [IvoryOS](https://ivoryos.ai): interoperable orchestrator for self-driving laboratories (SDLs) 
+
+A **plug-and-play** web interface for flexible, modular SDLs —
+you focus on developing protocols, IvoryOS handles the rest.
+
+![code_launch_design.png](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/code_launch_design.png)
 
 ---
 
 ## Table of Contents
-- [Description](#description)
+- [What IvoryOS does](#what-ivoryos-does)
 - [System requirements](#system-requirements)
 - [Installation](#installation)
-- [Quick Start](#quick-start)
 - [Features](#features)
 - [Demo](#demo)
 - [Roadmap](#roadmap)
+- [Contributing](#contributing)
 - [Acknowledgements](#acknowledgements)
 
 ---
-## Description
-Building UIs for SDLs is challenging because flexibility and modularity make them unpredictable — yet accessibility is essential for **democratisation** of AI-driven scientific discovery.
-
-**IvoryOS** bridges the gap by:
-- Dynamically inspecting initialized Python modules (hardware APIs, high-level functions, or workflows)
-- Automatically displaying functions and parameters in a web UI
-- Allowing users to **design**, **manage**, and **execute** experimental workflows with minimal changes to existing scripts
-- Providing natural language support for workflow design and execution, check [IvoryOS MCP](https://gitlab.com/heingroup/ivoryos-suite/ivoryos-mcp) for more details.
+## What IvoryOS Does
+- Turns Python modules into UIs by dynamically inspecting your hardware APIs, functions, and workflows.
+- Standardizes optimization inputs/outputs, making any optimizer plug-and-play.
+- Provides a visual workflow builder for designing and running experiments.
+- Adds natural-language control for creating and executing workflows, see [IvoryOS MCP](https://gitlab.com/heingroup/ivoryos-suite/ivoryos-mcp) for more details.
 
 ----
 ## System Requirements
@@ -90,10 +93,13 @@ Building UIs for SDLs is challenging because flexibility and modularity make the
 - SQLAlchemy-Utils~=0.41  
 - Flask-WTF~=1.2  
 - python-dotenv==1.0.1  
+- pandas
 
 **Optional:**
-- ax-platform (≥1.0, Python≥3.10)
-- baybe
+- ax-platform==1.1.2
+- baybe==0.14.0
+- nimo
+- slack-sdk
 </details>
 
 ---
@@ -104,16 +110,22 @@ From PyPI:
 ```bash
 pip install ivoryos
 ```
-From source:
-```bash
-git clone https://gitlab.com/heingroup/ivoryos.git
-cd ivoryos
-pip install -e .
-```
+
+[//]: # (From source:)
+
+[//]: # (```bash)
+
+[//]: # (git clone https://gitlab.com/heingroup/ivoryos.git)
+
+[//]: # (cd ivoryos)
+
+[//]: # (pip install -e .)
+
+[//]: # (```)
 
 
 ## Quick start
-In your SDL script, 
+In your script, where you initialize or import your robot:
 ```python
 my_robot = Robot()
 
@@ -121,8 +133,8 @@ import ivoryos
 
 ivoryos.run(__name__)
 ```
-You can now access the web UI at http://127.0.0.1:8000,
-create an account, login, and start designing workflows!
+Then run the script and visit `http://localhost:8000` in your browser.
+Use `admin` for both username and password, and start building workflows!
 
 ----
 ## Features
@@ -145,7 +157,8 @@ ivoryos.run(__name__, logger="logger name")
 ivoryos.run(__name__, logger=["logger 1", "logger 2"])
 ```
 ### Human-in-the-loop
-Add single or multiple notification handlers for `pause` feature in flow control:
+Use `pause` in flow control to pause the workflow and send a notification with custom message handler(s). 
+When run into `pause`, it will pause, send a message, and wait for human's response. Example of a Slack bot:
 ```python
 
 def slack_bot(msg: str = "Hi"):
@@ -168,24 +181,24 @@ ivoryos.run(__name__, notification_handler=slack_bot)
 
 ### Directory Structure
 
-Created automatically on first run:
+Created automatically in the same working directory on the first run:
+<details>
+<summary>click to see the data folder structure</summary>
+
 - **`ivoryos_data/`**: 
-  - **`ivoryos_data/config_csv/`**: Batch configuration `csv`
-  - **`ivoryos_data/pseudo_deck/`**: Offline deck `.pkl`
-  - **`ivoryos_data/results/`**: Execution results
-  - **`ivoryos_data/scripts/`**: Compiled workflows Python scripts
-- **`default.log`**: Application logs
-- **`ivoryos.db`**: Local database
+  - **`config_csv/`**: Batch configuration `csv`
+  - **`pseudo_deck/`**: Offline deck `.pkl`
+  - **`results/`**: Execution results
+  - **`scripts/`**: Compiled workflows Python scripts
+  - **`default.log`**: Application logs
+  - **`ivoryos.db`**: Local database
+</details>
+
 ---
-## Demo
-In the [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/example/abstract_sdl_example/abstract_sdl.py)
-```Python
-ivoryos.run(__name__)
-```
 
- * Running on all addresses (0.0.0.0)
- * Running on http://127.0.0.1:8000
- * Running on http://0.0.0.0:8000
+## Demo
+Online demo at [demo.ivoryos.ai](https://demo.ivoryos.ai). 
+Local version in [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/community/examples/abstract_sdl_example/abstract_sdl.py)
 
 ---
 
@@ -193,14 +206,22 @@ ivoryos.run(__name__)
 
 - [ ] dropdown input 
 - [ ] snapshot version control
-- [ ] optimizer-agnostic
-- [ ] prefect compatibility
 - [ ] check batch-config file compatibility
 
 ---
 
+## Contributing
+
+We welcome all contributions — from core improvements to new drivers, plugins, and real-world use cases.
+See `CONTRIBUTING.md` for details and let us know you're interested: https://forms.gle/fPSvw5LEGrweUQUH8
+
+---
+
 ## Citing
 
+<details>
+<summary>Click to see citations</summary>
+
 If you find this project useful, please consider citing the following manuscript:
 
 > Zhang, W., Hao, L., Lai, V. et al. [IvoryOS: an interoperable web interface for orchestrating Python-based self-driving laboratories.](https://www.nature.com/articles/s41467-025-60514-w) Nat Commun 16, 5182 (2025).
@@ -234,6 +255,8 @@ For an additional perspective related to the development of the tool, please see
   url          = {https://communities.springernature.com/posts/behind-ivoryos-empowering-scientists-to-harness-self-driving-labs-for-accelerated-discovery}
 }
 ```
+</details>
+
 ---
 ## Acknowledgements
 Authors acknowledge Telescope Innovations Corp., UBC Hein Lab, and Acceleration Consortium members for their valuable suggestions and contributions.

{ivoryos-1.3.7 → ivoryos-1.4.6}/README.md

@@ -4,34 +4,35 @@
 [![YouTube](https://img.shields.io/badge/YouTube-tutorial-red?logo=youtube)](https://youtu.be/dFfJv9I2-1g)
 [![YouTube](https://img.shields.io/badge/YouTube-demo-red?logo=youtube)](https://youtu.be/flr5ydiE96s)
 [![Published](https://img.shields.io/badge/Nature_Comm.-paper-blue)](https://www.nature.com/articles/s41467-025-60514-w)
+[![Community](https://img.shields.io/discord/1313641159356059770?label=Discord&logo=discord&color=5865F2)](https://discord.gg/AX5P9EdGVX)
 
-[//]: # ([![Discord](https://img.shields.io/discord/1313641159356059770?label=Discord&logo=discord&color=5865F2)](https://discord.gg/AX5P9EdGVX))
+![ivoryos_logo.png](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/ivoryos_logo.png)
 
-![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/ivoryos.png)
-# ivoryOS: interoperable Web UI for self-driving laboratories (SDLs)
-A **plug-and-play** web interface for flexible SDLs 
+# [IvoryOS](https://ivoryos.ai): interoperable orchestrator for self-driving laboratories (SDLs) 
+
+A **plug-and-play** web interface for flexible, modular SDLs —
+you focus on developing protocols, IvoryOS handles the rest.
+
+![code_launch_design.png](https://gitlab.com/heingroup/ivoryos/raw/main/docs/source/_static/code_launch_design.png)
 
 ---
 
 ## Table of Contents
-- [Description](#description)
+- [What IvoryOS does](#what-ivoryos-does)
 - [System requirements](#system-requirements)
 - [Installation](#installation)
-- [Quick Start](#quick-start)
 - [Features](#features)
 - [Demo](#demo)
 - [Roadmap](#roadmap)
+- [Contributing](#contributing)
 - [Acknowledgements](#acknowledgements)
 
 ---
-## Description
-Building UIs for SDLs is challenging because flexibility and modularity make them unpredictable — yet accessibility is essential for **democratisation** of AI-driven scientific discovery.
-
-**IvoryOS** bridges the gap by:
-- Dynamically inspecting initialized Python modules (hardware APIs, high-level functions, or workflows)
-- Automatically displaying functions and parameters in a web UI
-- Allowing users to **design**, **manage**, and **execute** experimental workflows with minimal changes to existing scripts
-- Providing natural language support for workflow design and execution, check [IvoryOS MCP](https://gitlab.com/heingroup/ivoryos-suite/ivoryos-mcp) for more details.
+## What IvoryOS Does
+- Turns Python modules into UIs by dynamically inspecting your hardware APIs, functions, and workflows.
+- Standardizes optimization inputs/outputs, making any optimizer plug-and-play.
+- Provides a visual workflow builder for designing and running experiments.
+- Adds natural-language control for creating and executing workflows, see [IvoryOS MCP](https://gitlab.com/heingroup/ivoryos-suite/ivoryos-mcp) for more details.
 
 ----
 ## System Requirements
@@ -53,10 +54,13 @@ Building UIs for SDLs is challenging because flexibility and modularity make the
 - SQLAlchemy-Utils~=0.41  
 - Flask-WTF~=1.2  
 - python-dotenv==1.0.1  
+- pandas
 
 **Optional:**
-- ax-platform (≥1.0, Python≥3.10)
-- baybe
+- ax-platform==1.1.2
+- baybe==0.14.0
+- nimo
+- slack-sdk
 </details>
 
 ---
@@ -67,16 +71,22 @@ From PyPI:
 ```bash
 pip install ivoryos
 ```
-From source:
-```bash
-git clone https://gitlab.com/heingroup/ivoryos.git
-cd ivoryos
-pip install -e .
-```
+
+[//]: # (From source:)
+
+[//]: # (```bash)
+
+[//]: # (git clone https://gitlab.com/heingroup/ivoryos.git)
+
+[//]: # (cd ivoryos)
+
+[//]: # (pip install -e .)
+
+[//]: # (```)
 
 
 ## Quick start
-In your SDL script, 
+In your script, where you initialize or import your robot:
 ```python
 my_robot = Robot()
 
@@ -84,8 +94,8 @@ import ivoryos
 
 ivoryos.run(__name__)
 ```
-You can now access the web UI at http://127.0.0.1:8000,
-create an account, login, and start designing workflows!
+Then run the script and visit `http://localhost:8000` in your browser.
+Use `admin` for both username and password, and start building workflows!
 
 ----
 ## Features
@@ -108,7 +118,8 @@ ivoryos.run(__name__, logger="logger name")
 ivoryos.run(__name__, logger=["logger 1", "logger 2"])
 ```
 ### Human-in-the-loop
-Add single or multiple notification handlers for `pause` feature in flow control:
+Use `pause` in flow control to pause the workflow and send a notification with custom message handler(s). 
+When run into `pause`, it will pause, send a message, and wait for human's response. Example of a Slack bot:
 ```python
 
 def slack_bot(msg: str = "Hi"):
@@ -131,24 +142,24 @@ ivoryos.run(__name__, notification_handler=slack_bot)
 
 ### Directory Structure
 
-Created automatically on first run:
+Created automatically in the same working directory on the first run:
+<details>
+<summary>click to see the data folder structure</summary>
+
 - **`ivoryos_data/`**: 
-  - **`ivoryos_data/config_csv/`**: Batch configuration `csv`
-  - **`ivoryos_data/pseudo_deck/`**: Offline deck `.pkl`
-  - **`ivoryos_data/results/`**: Execution results
-  - **`ivoryos_data/scripts/`**: Compiled workflows Python scripts
-- **`default.log`**: Application logs
-- **`ivoryos.db`**: Local database
+  - **`config_csv/`**: Batch configuration `csv`
+  - **`pseudo_deck/`**: Offline deck `.pkl`
+  - **`results/`**: Execution results
+  - **`scripts/`**: Compiled workflows Python scripts
+  - **`default.log`**: Application logs
+  - **`ivoryos.db`**: Local database
+</details>
+
 ---
-## Demo
-In the [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/example/abstract_sdl_example/abstract_sdl.py)
-```Python
-ivoryos.run(__name__)
-```
 
- * Running on all addresses (0.0.0.0)
- * Running on http://127.0.0.1:8000
- * Running on http://0.0.0.0:8000
+## Demo
+Online demo at [demo.ivoryos.ai](https://demo.ivoryos.ai). 
+Local version in [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/community/examples/abstract_sdl_example/abstract_sdl.py)
 
 ---
 
@@ -156,14 +167,22 @@ ivoryos.run(__name__)
 
 - [ ] dropdown input 
 - [ ] snapshot version control
-- [ ] optimizer-agnostic
-- [ ] prefect compatibility
 - [ ] check batch-config file compatibility
 
 ---
 
+## Contributing
+
+We welcome all contributions — from core improvements to new drivers, plugins, and real-world use cases.
+See `CONTRIBUTING.md` for details and let us know you're interested: https://forms.gle/fPSvw5LEGrweUQUH8
+
+---
+
 ## Citing
 
+<details>
+<summary>Click to see citations</summary>
+
 If you find this project useful, please consider citing the following manuscript:
 
 > Zhang, W., Hao, L., Lai, V. et al. [IvoryOS: an interoperable web interface for orchestrating Python-based self-driving laboratories.](https://www.nature.com/articles/s41467-025-60514-w) Nat Commun 16, 5182 (2025).
@@ -197,6 +216,8 @@ For an additional perspective related to the development of the tool, please see
   url          = {https://communities.springernature.com/posts/behind-ivoryos-empowering-scientists-to-harness-self-driving-labs-for-accelerated-discovery}
 }
 ```
+</details>
+
 ---
 ## Acknowledgements
 Authors acknowledge Telescope Innovations Corp., UBC Hein Lab, and Acceleration Consortium members for their valuable suggestions and contributions.

ivoryos-1.4.6/docs/source/conf.py

@@ -0,0 +1,84 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import sys
+import urllib
+
+import requests
+
+# -- General configuration
+sys.path.insert(0, os.path.abspath('../../'))
+from ivoryos.version import __version__
+
+
+# appending suite readme.rst to doc
+
+external_readme = [
+    {
+        "name": 'plugin.rst',
+        "url": "https://gitlab.com/heingroup/ivoryos-suite/ivoryos-plugin-template/-/raw/main/README.rst"
+    },
+    {
+        "name": 'client.rst',
+        "url": "https://gitlab.com/heingroup/ivoryos-suite/ivoryos-client/-/raw/main/README.rst"
+    },
+    {
+        "name": 'mcp.rst',
+        "url": "https://gitlab.com/heingroup/ivoryos-suite/ivoryos-mcp/-/raw/main/README.rst"
+    }
+]
+
+for item in external_readme:
+    readme_url = item['url']
+    name = item['name']
+    output_path = os.path.join(os.path.dirname(__file__), name)
+    r = requests.get(readme_url, verify=False)
+    if not os.path.exists(output_path):
+        with open(output_path, "wb") as f:
+            f.write(r.content)
+
+# -- Project information
+project = 'ivoryOS'
+copyright = '2024, Ivory Zhang'
+author = 'Ivory Zhang, Lucy Hao'
+version = __version__
+
+extensions = [
+    'sphinx.ext.duration',
+    'sphinx.ext.doctest',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.intersphinx',
+    'sphinxcontrib.httpdomain',
+    'sphinxcontrib.autohttp.flask',
+    'sphinxcontrib.autohttp.flaskqref'
+]
+
+install_requires = [
+    'sphinx-autodoc-typehints'
+]
+autodoc_mock_imports = ["flask_sqlalchemy", "another_hard_to_import_lib"]
+
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+    'sphinx': ('https://www.sphinx-doc.org/en/master/', None),
+}
+intersphinx_disabled_domains = ['std']
+
+templates_path = ['_templates']
+
+html_static_path = ['_static']
+html_css_files = [
+    'custom.css',
+]
+
+html_allow_raw_html = True
+
+# -- Options for HTML output
+
+html_theme = 'sphinx_rtd_theme'
+
+# -- Options for EPUB output
+epub_show_urls = 'footnote'
+
+# The master toctree document.
+master_doc = 'index'

{ivoryos-1.3.7 → ivoryos-1.4.6}/ivoryos/app.py

@@ -1,24 +1,22 @@
 import os
 import uuid
 
+import bcrypt
 from flask import Flask, session, g, redirect, url_for
 from flask_login import AnonymousUserMixin
 
 from ivoryos.utils import utils
-from ivoryos.utils.db_models import db
-from ivoryos.config import Config, get_config
+from ivoryos.utils.db_models import db, User
 from ivoryos.routes.auth.auth import auth, login_manager
 from ivoryos.routes.control.control import control
 from ivoryos.routes.data.data import data
 from ivoryos.routes.library.library import library
 from ivoryos.routes.design.design import design
 from ivoryos.routes.execute.execute import execute
-from ivoryos.routes.api.api import api
 from ivoryos.socket_handlers import socketio
 from ivoryos.routes.main.main import main
 from ivoryos.version import __version__ as ivoryos_version
 from sqlalchemy import inspect, text
-from flask import current_app
 
 url_prefix = os.getenv('URL_PREFIX', "/ivoryos")
 app = Flask(__name__, static_url_path=f'{url_prefix}/static', static_folder='static')
@@ -29,7 +27,7 @@ app.register_blueprint(control, url_prefix=f'{url_prefix}/instruments')
 app.register_blueprint(design, url_prefix=f'{url_prefix}')
 app.register_blueprint(execute, url_prefix=f'{url_prefix}')
 app.register_blueprint(data, url_prefix=f'{url_prefix}')
-app.register_blueprint(api, url_prefix=f'{url_prefix}/{api.name}')
+# app.register_blueprint(api, url_prefix=f'{url_prefix}/{api.name}')
 
 def reset_old_schema(engine, db_dir):
     inspector = inspect(engine)
@@ -60,11 +58,36 @@ def reset_old_schema(engine, db_dir):
                 conn.execute(text("DROP TABLE IF EXISTS workflow_steps"))
             if old_workflow_run:
                 conn.execute(text("DROP TABLE IF EXISTS workflow_runs"))
+    with engine.begin() as conn:
+        try:
+            conn.execute(
+                text("ALTER TABLE user ADD COLUMN settings TEXT")
+            )
+        except Exception:
+            pass
 
     # Recreate new schema
     db.create_all()  # creates workflow_runs, workflow_phases, workflow_steps
 
 
+def create_admin():
+    """
+    Create an admin user with username 'admin' and password 'admin' if it doesn't exist.
+    """
+    with app.app_context():
+        admin_user = User.query.filter_by(username='admin').first()
+        if not admin_user:
+            print("Creating default admin user...")
+            admin_user = User(
+                username='admin',
+                password=bcrypt.hashpw("admin".encode('utf-8'), bcrypt.gensalt()),
+            )
+            db.session.add(admin_user)
+            db.session.commit()
+        else:
+            print("Admin user already exists.")
+
+
 def create_app(config_class=None):
     """
     create app, init database
@@ -82,6 +105,7 @@ def create_app(config_class=None):
     with app.app_context():
         # db.create_all()
         reset_old_schema(db.engine, app.config['OUTPUT_FOLDER'])
+        create_admin()
 
     # Additional setup
     utils.create_gui_dir(app.config['OUTPUT_FOLDER'])