ivoryos 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

ivoryos/__init__.py

@@ -72,7 +72,7 @@ def run(module=None, host="0.0.0.0", port=None, debug=None, llm_server=None, mod
         app.config["MODULE"] = module
         app.config["OFF_LINE"] = False
         global_config.deck = sys.modules[module]
-        global_config.deck_variables = utils.parse_deck(global_config.deck, output_path=app.config["DUMMY_DECK"], save=True)
+        global_config.deck_snapshot = utils.create_deck_snapshot(global_config.deck, output_path=app.config["DUMMY_DECK"], save=True)
         # global_config.runner = ScriptRunner(globals())
     else:
         app.config["OFF_LINE"] = True

ivoryos/config.py

@@ -15,6 +15,7 @@ class Config:
     SCRIPT_FOLDER = os.path.join(OUTPUT_FOLDER, 'scripts/')
     DATA_FOLDER = os.path.join(OUTPUT_FOLDER, 'results/')
     DUMMY_DECK = os.path.join(OUTPUT_FOLDER, 'pseudo_deck/')
+    LLM_OUTPUT = os.path.join(OUTPUT_FOLDER, 'llm_output/')
     DECK_HISTORY = os.path.join(OUTPUT_FOLDER, 'deck_history.txt')
     LOGGERS_PATH = "default.log"
 

ivoryos/routes/control/control.py

@@ -1,8 +1,6 @@
 import os
-import pickle
-import sys
 
-from flask import Blueprint, redirect, url_for, flash, request, render_template, session, current_app
+from flask import Blueprint, redirect, url_for, flash, request, render_template, session, current_app, jsonify
 from flask_login import login_required
 
 from ivoryos.utils.global_config import GlobalConfig
@@ -17,7 +15,7 @@ control = Blueprint('control', __name__, template_folder='templates/control')
 @control.route("/my_deck")
 @login_required
 def deck_controllers():
-    deck_variables = global_config.deck_variables.keys()
+    deck_variables = global_config.deck_snapshot.keys()
     deck_list = utils.import_history(os.path.join(current_app.config["OUTPUT_FOLDER"], 'deck_history.txt'))
     return render_template('controllers_home.html', defined_variables=deck_variables, deck=True, history=deck_list)
 
@@ -77,12 +75,15 @@ def controllers_home():
 def controllers(instrument):
     inst_object = find_instrument_by_name(instrument)
     _forms = create_form_from_module(sdl_module=inst_object, autofill=False, design=False)
-    card_order = session.get('card_order')
-    order = card_order.get(instrument, _forms.keys())
-    if instrument not in card_order:
-        card_order[instrument] = list(order)
-        session['card_order'] = card_order
-        # print(session['card_order'])
+    functions = list(_forms.keys())
+
+    order = get_session_by_instrument('card_order', instrument)
+    hidden_functions = get_session_by_instrument('hide_function', instrument)
+
+    for function in functions:
+        if function not in hidden_functions and function not in order:
+            order.append(function)
+    post_session_by_instrument('card_order', instrument, order)
     forms = {name: _forms[name] for name in order if name in _forms}
     if request.method == 'POST':
         all_kwargs = request.form.copy()
@@ -103,6 +104,32 @@ def controllers(instrument):
     return render_template('controllers.html', instrument=instrument, forms=forms, format_name=format_name)
 
 
+@control.route("/backend_control/<instrument>", methods=['GET', 'POST'])
+@login_required
+def backend_control(instrument):
+    inst_object = find_instrument_by_name(instrument)
+    forms = create_form_from_module(sdl_module=inst_object, autofill=False, design=False)
+    if request.method == 'POST':
+        all_kwargs = request.form.copy()
+        method_name = all_kwargs.pop("hidden_name", None)
+        # if method_name is not None:
+        form = forms.get(method_name, None)
+        kwargs = {field.name: field.data for field in form if field.name != 'csrf_token'}
+        function_executable = getattr(inst_object, method_name)
+        if form:
+            # print(kwargs)
+            try:
+                kwargs.pop("hidden_name")
+                output = function_executable(**kwargs)
+                json_output = jsonify(output)
+            except Exception as e:
+                json_output = jsonify(e.__str__())
+                return json_output, 400
+        else:
+            return "instrument not exist", 400
+    return json_output, 200
+
+
 @control.route("/import_api", methods=['GET', 'POST'])
 def import_api():
     filepath = request.form.get('filepath')
@@ -164,12 +191,12 @@ def import_deck():
     try:
         module = utils.import_module_by_filepath(filepath=filepath, name=name)
         utils.save_to_history(filepath, current_app.config["DECK_HISTORY"])
-        module_sigs = utils.parse_deck(module, save=update, output_path=current_app.config["DUMMY_DECK"])
+        module_sigs = utils.create_deck_snapshot(module, save=update, output_path=current_app.config["DUMMY_DECK"])
         if not len(module_sigs) > 0:
             flash("Invalid hardware deck, connect instruments in deck script", "error")
             return redirect(url_for("control.deck_controllers"))
         global_config.deck = module
-        global_config.deck_variables = module_sigs
+        global_config.deck_snapshot = module_sigs
 
         if script.deck is None:
             script.deck = module.__name__
@@ -183,47 +210,59 @@ def import_deck():
 def save_order(instrument):
     # Save the new order for the specified group to session
     data = request.json
-    card_order = session.get("card_order", {})
-    card_order[instrument] = data['order']
-    session['card_order'] = card_order
+    post_session_by_instrument('card_order', instrument, data['order'])
     return '', 204
 
 
 @control.route('/hide_function/<instrument>/<function>')
 def hide_function(instrument, function):
     back = request.referrer
-    hidden_functions = session.get("hidden_functions")
-    functions = hidden_functions.get(instrument, [])
-    card_order = session.get("card_order")
-    order = card_order.get(instrument)
+    functions = get_session_by_instrument("hidden_functions", instrument)
+    order = get_session_by_instrument("card_order", instrument)
     if function not in functions:
         functions.append(function)
         order.remove(function)
-    hidden_functions[instrument] = functions
-    card_order[instrument] = order
-    session['hidden_functions'] = hidden_functions
-    session['card_order'] = card_order
+    post_session_by_instrument('hidden_functions', instrument, functions)
+    post_session_by_instrument('card_order', instrument, order)
     return redirect(back)
 
 
 @control.route('/remove_hidden/<instrument>/<function>')
 def remove_hidden(instrument, function):
     back = request.referrer
-    hidden_functions = session.get("hidden_functions")
-    functions = hidden_functions.get(instrument, [])
-    card_order = session.get("card_order")
-    order = card_order.get(instrument)
+    functions = get_session_by_instrument("hidden_functions", instrument)
+    order = get_session_by_instrument("card_order", instrument)
     if function in functions:
         functions.remove(function)
         order.append(function)
-    hidden_functions[instrument] = functions
-    card_order[instrument] = order
-    session['hidden_functions'] = hidden_functions
-    session['card_order'] = card_order
+    post_session_by_instrument('hidden_functions', instrument, functions)
+    post_session_by_instrument('card_order', instrument, order)
     return redirect(back)
 
 
+def get_session_by_instrument(session_name, instrument):
+    """get data from session by instrument"""
+    session_object = session.get(session_name, {})
+    functions = session_object.get(instrument, [])
+    return functions
+
+
+def post_session_by_instrument(session_name, instrument, data):
+    """
+    save new data to session by instrument
+    :param session_name: "card_order" or "hidden_functions"
+    :param instrument: function name of class object
+    :param data: order list or hidden function list
+    """
+    session_object = session.get(session_name, {})
+    session_object[instrument] = data
+    session[session_name] = session_object
+
+
 def find_instrument_by_name(name: str):
+    """
+    find instrument class object by instance name
+    """
     if name.startswith("deck"):
         name = name.replace("deck.", "")
         return getattr(global_config.deck, name)

ivoryos/routes/control/templates/control/controllers.html

@@ -8,9 +8,12 @@
         </div>
     </div>
     <h1>{{instrument}} controller</h1>
+    {% set hidden = session.get('hidden_functions', {}) %}
     <div class="grid-container" id="sortable-grid">
         {% for function, form in forms.items() %}
-            {% if function not in session['hidden_functions'][instrument] %}
+
+            {% set hidden_instrument = hidden.get(instrument, []) %}
+            {% if function not in hidden_instrument %}
                 <div class="card" id="{{function}}">
                     <div class="bg-white rounded shadow-sm flex-fill">
                         <a style="float: right" aria-label="Close" href="{{ url_for('control.hide_function', instrument=instrument, function=function) }}"><i class="bi bi-eye-slash-fill"></i></a>
@@ -53,7 +56,8 @@
         </div>
         <div id="hidden" class="accordion-collapse collapse" data-bs-parent="#accordionActions">
             <div class="accordion-body">
-                {% for function in session['hidden_functions'][instrument] %}
+                {% set hidden_instrument = hidden.get(instrument, []) %}
+                {% for function in hidden_instrument %}
                     <div>
                         {{ function }} <a href="{{ url_for('control.remove_hidden', instrument=instrument, function=function) }}"><i class="bi bi-eye-fill"></i></a>
                     </div>

ivoryos/routes/database/database.py

@@ -61,8 +61,9 @@ def publish():
 def finalize():
     script = get_script_file()
     script.finalize()
-    db.session.merge(script)
-    db.session.commit()
+    if script.name:
+        db.session.merge(script)
+        db.session.commit()
     post_script_file(script)
     return redirect(url_for('design.experiment_builder'))
 

ivoryos/routes/design/design.py

@@ -13,10 +13,10 @@ from werkzeug.utils import secure_filename
 from ivoryos.utils import utils
 from ivoryos.utils.global_config import GlobalConfig
 from ivoryos.utils.form import create_builtin_form, create_action_button, format_name, create_form_from_pseudo
-from ivoryos.utils.llm_agent import LlmAgent
 from ivoryos.utils.db_models import Script
 from ivoryos.utils.script_runner import ScriptRunner
 
+
 socketio = SocketIO()
 design = Blueprint('design', __name__, template_folder='templates/design')
 
@@ -69,7 +69,7 @@ def experiment_builder(instrument=None):
 
     functions = []
     if deck:
-        deck_variables = global_config.deck_variables.keys()
+        deck_variables = global_config.deck_snapshot.keys()
     else:
         deck_variables = list(pseudo_deck.keys()) if pseudo_deck else []
         deck_variables.remove("deck_name") if len(deck_variables) > 0 else deck_variables
@@ -78,7 +78,7 @@ def experiment_builder(instrument=None):
             forms = create_builtin_form(instrument)
         else:
             if deck:
-                function_metadata = global_config.deck_variables.get(instrument, {})
+                function_metadata = global_config.deck_snapshot.get(instrument, {})
             elif pseudo_deck:
                 function_metadata = pseudo_deck.get(instrument, {})
             functions = {key: data.get('signature', {}) for key, data in function_metadata.items()}
@@ -158,13 +158,14 @@ def generate_code():
         prompt = request.form.get("prompt")
         session['prompt'][instrument] = prompt
         # sdl_module = utils.parse_functions(find_instrument_by_name(f'deck.{instrument}'), doc_string=True)
-        sdl_module = global_config.deck_variables.get(instrument, {})
+        sdl_module = global_config.deck_snapshot.get(instrument, {})
         empty_script = Script(author=session.get('user'))
         if enable_llm and agent is None:
             try:
                 model = current_app.config["LLM_MODEL"]
                 server = current_app.config["LLM_SERVER"]
                 module = current_app.config["MODULE"]
+                from ivoryos.utils.llm_agent import LlmAgent
                 agent = LlmAgent(host=server, model=model, output_path=os.path.dirname(os.path.abspath(module)))
             except Exception as e:
                 flash(e.__str__())
@@ -241,7 +242,7 @@ def experiment_run():
             bo_args = request.form.to_dict()
             # ax_client = utils.ax_initiation(bo_args)
         if "online-config" in request.form:
-            config = utils.process_data(request.form.to_dict(), config_list)
+            config = utils.web_config_entry_wrapper(request.form.to_dict(), config_list)
         repeat = request.form.get('repeat', None)
 
         try:

ivoryos/routes/main/templates/main/help.html

@@ -134,9 +134,6 @@
                 <div class="accordion-body">
                     This is project is a work in progress. In case of any bugs or suggestions, reach out to Ivory: ivoryzhang@chem.ubc.ca or create an issue on GitLab:
                     <a href="https://gitlab.com/heingroup/ivoryos">https://gitlab.com/heingroup/ivoryos</a>.
-{#                    <img src="{{url_for('static', filename='gui_annotation/installation_guide.PNG')}}">#}
-
-{#                    <object webui_data="{{ url_for('static', filename='setup-help.pdf')}}" type="application/pdf" style="min-height:80vh;width:100%"></object>#}
                 </div>
             </div>
         </div>

ivoryos/utils/db_models.py

@@ -88,16 +88,16 @@ class Script(db.Model):
                 if action['uuid'] == int(uuid):
                     return action
 
-    def _convert(self, args, arg_types):
+    def _convert_type(self, args, arg_types):
         if type(arg_types) is not list:
             arg_types = [arg_types]
-        for i in arg_types:
+        for arg_type in arg_types:
             try:
-                args = eval(i + "('" + args + "')")
+                args = eval(f"{arg_type}('{args}')")
                 return
             except Exception:
                 pass
-        raise TypeError(f"Input type error: cannot convert '{args}' to {i}.")
+        raise TypeError(f"Input type error: cannot convert '{args}' to {arg_type}.")
 
     def update_by_uuid(self, uuid, args, output):
         bool_dict = {"True": True, "False": False}
@@ -113,7 +113,7 @@ class Script(db.Model):
                     else:
                         if arg in action['arg_types']:
                             arg_types = action['arg_types'][arg]
-                            self._convert(args[arg], arg_types)
+                            self._convert_type(args[arg], arg_types)
                         else:
                             try:
                                 args[arg] = eval(args[arg])
@@ -128,7 +128,7 @@ class Script(db.Model):
                 else:
                     if 'arg_types' in action:
                         arg_types = action['arg_types']
-                        self._convert(args, arg_types)
+                        self._convert_type(args, arg_types)
 
                     # print(args)
         action['args'] = args
@@ -337,14 +337,13 @@ class Script(db.Model):
 
     @staticmethod
     def validate_function_name(name):
-        # Replace invalid characters with underscores
+        """Replace invalid characters with underscores"""
         name = re.sub(r'\W|^(?=\d)', '_', name)
         # Check if it's a Python keyword and adjust if necessary
         if keyword.iskeyword(name):
             name += '_'
         return name
 
-
     def _generate_function_header(self, run_name, stype):
         """
         Generate the function header.

ivoryos/utils/form.py

@@ -1,5 +1,4 @@
 from wtforms.fields.core import Field
-from wtforms.utils import UnsetValue
 from wtforms.validators import InputRequired
 from wtforms.widgets.core import TextInput
 
@@ -88,7 +87,7 @@ class VariableOrFloatField(Field):
             raise ValueError(self.gettext("Not a valid float value.")) from exc
 
 
-unset_value = UnsetValue()
+# unset_value = UnsetValue()
 
 
 class VariableOrIntField(Field):

ivoryos/utils/global_config.py

@@ -11,7 +11,7 @@ class GlobalConfig:
             cls._instance._agent = None
             cls._instance._defined_variables = {}
             cls._instance._api_variables = set()
-            cls._instance._deck_variables = {}
+            cls._instance._deck_snapshot = {}
             cls._instance._runner = None
         return cls._instance
 
@@ -26,12 +26,12 @@ class GlobalConfig:
 
 
     @property
-    def deck_variables(self):
-        return self._deck_variables
+    def deck_snapshot(self):
+        return self._deck_snapshot
 
-    @deck_variables.setter
-    def deck_variables(self, value):
-        self._deck_variables = value
+    @deck_snapshot.setter
+    def deck_snapshot(self, value):
+        self._deck_snapshot = value
 
 
     @property

ivoryos/utils/utils.py

@@ -14,6 +14,7 @@ from ivoryos.utils.db_models import Script
 
 
 def get_script_file():
+    """Get script from Flask session and returns the script"""
     session_script = session.get("scripts")
     if session_script:
         s = Script()
@@ -24,6 +25,11 @@ def get_script_file():
 
 
 def post_script_file(script, is_dict=False):
+    """
+    Post script to Flask. Script will be converted to a dict if it is a Script object
+    :param script: Script to post
+    :param is_dict: if the script is a dictionary,
+    """
     if is_dict:
         session['scripts'] = script
     else:
@@ -31,12 +37,19 @@ def post_script_file(script, is_dict=False):
 
 
 def create_gui_dir(parent_path):
+    """
+    Creates folders for ivoryos data
+    """
     os.makedirs(parent_path, exist_ok=True)
     for path in ["config_csv", "scripts", "results", "pseudo_deck"]:
         os.makedirs(os.path.join(parent_path, path), exist_ok=True)
 
 
 def save_to_history(filepath, history_path):
+    """
+    For manual deck connection only
+    save deck file path that successfully connected to ivoryos to a history file
+    """
     connections = []
     try:
         with open(history_path, 'r') as file:
@@ -50,6 +63,10 @@ def save_to_history(filepath, history_path):
 
 
 def import_history(history_path):
+    """
+    For manual deck connection only
+    load deck connection history from history file
+    """
     connections = []
     try:
         with open(history_path, 'r') as file:
@@ -62,11 +79,20 @@ def import_history(history_path):
 
 
 def available_pseudo_deck(path):
+    """
+    load pseudo deck (snapshot) from connection history
+    """
     import os
     return os.listdir(path)
 
 
-def parse_functions(class_object=None, debug=False):
+def _inspect_class(class_object=None, debug=False):
+    """
+    inspect class object: inspect function signature if not name.startswith("_")
+    :param class_object: class object
+    :param debug: debug mode will inspect function.startswith("_")
+    :return: function: Dict[str, Dict[str, Union[Signature, str, None]]]
+    """
     functions = {}
     under_score = "_"
     if debug:
@@ -79,7 +105,7 @@ def parse_functions(class_object=None, debug=False):
                 docstring = inspect.getdoc(method)
                 functions[function] = dict(signature=annotation, docstring=docstring)
 
-                # handle getter setters
+                # handle getter setters todo
                 # if callable(att):
                 #     functions[function] = inspect.signature(att)
                 # else:
@@ -95,6 +121,7 @@ def parse_functions(class_object=None, debug=False):
 
 
 def _get_type_from_parameters(arg, parameters):
+    """get argument types from inspection"""
     arg_type = ''
     if type(parameters) is inspect.Signature:
         p = parameters.parameters
@@ -135,24 +162,29 @@ def find_variable_in_script(script: Script, args: Dict[str, str]) -> Optional[Tu
 
 
 def _convert_by_str(args, arg_types):
-    # print(arg_types)
+    """
+    Converts a value to type through eval(f'{type}("{args}")')
+    """
     if type(arg_types) is not list:
         arg_types = [arg_types]
-    for i in arg_types:
-        if i == "any":
+    for arg_type in arg_types:
+        if arg_type == "any":
             try:
                 args = eval(args)
             except Exception:
                 pass
             return args
         try:
-            args = eval(f'{i}("{args}")')
+            args = eval(f'{arg_type}("{args}")')
             return args
         except Exception:
-            raise TypeError(f"Input type error: cannot convert '{args}' to {i}.")
+            raise TypeError(f"Input type error: cannot convert '{args}' to {arg_type}.")
 
 
 def _convert_by_class(args, arg_types):
+    """
+    Converts a value to type through type(arg)
+    """
     if arg_types.__module__ == 'builtins':
         args = arg_types(args)
         return args
@@ -170,6 +202,9 @@ def _convert_by_class(args, arg_types):
 
 
 def convert_config_type(args, arg_types, is_class: bool = False):
+    """
+    Converts an argument from str to an arg type
+    """
     bool_dict = {"True": True, "False": False}
     # print(args, arg_types)
     # print(globals())
@@ -193,6 +228,11 @@ def convert_config_type(args, arg_types, is_class: bool = False):
 
 
 def import_module_by_filepath(filepath: str, name: str):
+    """
+    Import module by file path
+    :param filepath: full path of module
+    :param name: module's name
+    """
     spec = importlib.util.spec_from_file_location(name, filepath)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
@@ -212,6 +252,9 @@ class SocketIOHandler(logging.Handler):
 
 
 def start_logger(socketio: SocketIO, logger_name: str, log_filename: str = None):
+    """
+    stream logger to web through web socketIO
+    """
     # logging.basicConfig( format='%(asctime)s - %(message)s')
     formatter = logging.Formatter(fmt='%(asctime)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S')
     logger = logging.getLogger(logger_name)
@@ -226,7 +269,26 @@ def start_logger(socketio: SocketIO, logger_name: str, log_filename: str = None)
     return logger
 
 
-def ax_wrapper(data):
+def ax_wrapper(data: dict):
+    """
+    Ax platform wrapper function for creating optimization campaign parameters and objective from the web form input
+    :param data: e.g.,
+    {
+        "param_1_type": "range", "param_1_value": [1,2],
+        "param_2_type": "range", "param_2_value": [1,2],
+        "obj_1_min": True,
+        "obj_2_min": True
+    }
+    :return: the optimization campaign parameters
+    parameter=[
+        {"name": "param_1", "type": "range", "bounds": [1,2]},
+        {"name": "param_1", "type": "range", "bounds": [1,2]}
+    ]
+    objectives=[
+        {"name": "obj_1", "min": True, "threshold": None},
+        {"name": "obj_2", "min": True, "threshold": None},
+    ]
+    """
     from ax.service.utils.instantiation import ObjectiveProperties
     parameter = []
     objectives = {}
@@ -259,6 +321,10 @@ def ax_wrapper(data):
 
 
 def ax_initiation(data):
+    """
+    create Ax campaign from the web form input
+    :param data:
+    """
     install_and_import("ax", "ax-platform")
     parameter, objectives = ax_wrapper(data)
     from ax.service.ax_client import AxClient
@@ -277,6 +343,11 @@ def get_arg_type(args, parameters):
 
 
 def install_and_import(package, package_name=None):
+    """
+    Install the package and import it
+    :param package: package to import and install
+    :param package_name: pip install package name if different from package
+    """
     try:
         # Check if the package is already installed
         importlib.import_module(package)
@@ -288,7 +359,12 @@ def install_and_import(package, package_name=None):
         # print(f"{package} has been installed successfully.")
 
 
-def process_data(data, config_type):
+def web_config_entry_wrapper(data: dict, config_type: list):
+    """
+    Wrap the data dictionary from web config entries during execution configuration
+    :param data: data dictionary
+    :param config_type: data entry types ["str", "int", "float", "bool"]
+    """
     rows = {}  # Dictionary to hold webui_data organized by rows
 
     # Organize webui_data by rows
@@ -311,22 +387,32 @@ def process_data(data, config_type):
     return filtered_rows
 
 
-def parse_deck(deck, save=False, output_path=''):
-    deck_variables = {f"deck.{name}": parse_functions(val) for name, val in vars(deck).items()
-                      if not type(val).__module__ == 'builtins'
-                      and not name[0].isupper()
-                      and not name.startswith("_")}
-    if deck_variables and save:
+def create_deck_snapshot(deck, save: bool = False, output_path: str = ''):
+    """
+    Create a deck snapshot of the given script
+    :param deck: python module name to create the deck snapshot from e.g. __main__
+    :param save: save the deck snapshot into pickle file
+    :param output_path: path to save the pickle file
+    """
+    deck_snapshot = {f"deck.{name}": _inspect_class(val) for name, val in vars(deck).items()
+                     if not type(val).__module__ == 'builtins'
+                     and not name[0].isupper()
+                     and not name.startswith("_")}
+    if deck_snapshot and save:
         # pseudo_deck = parse_dict
-        parse_dict = deck_variables.copy()
+        parse_dict = deck_snapshot.copy()
         parse_dict["deck_name"] = os.path.splitext(os.path.basename(deck.__file__))[
             0] if deck.__name__ == "__main__" else deck.__name__
         with open(os.path.join(output_path, f"{parse_dict['deck_name']}.pkl"), 'wb') as file:
             pickle.dump(parse_dict, file)
-    return deck_variables
+    return deck_snapshot
 
 
-def load_deck(pkl_name):
+def load_deck(pkl_name: str):
+    """
+    Loads a pickled deck snapshot from disk on offline mode
+    :param pkl_name: name of the pickle file
+    """
     if not pkl_name:
         return None
     try:

ivoryos-0.1.6.dist-info/METADATA

@@ -0,0 +1,166 @@
+Metadata-Version: 2.1
+Name: ivoryos
+Version: 0.1.6
+Summary: an open-source Python package enabling Self-Driving Labs (SDLs) interoperability
+Home-page: https://gitlab.com/heingroup/ivoryos
+Author: Ivory Zhang
+Author-email: ivoryzhang@chem.ubc.ca
+License: MIT
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: bcrypt
+Requires-Dist: Flask-Login
+Requires-Dist: Flask-Session
+Requires-Dist: Flask-SocketIO
+Requires-Dist: Flask-SQLAlchemy
+Requires-Dist: Flask-WTF
+Requires-Dist: SQLAlchemy-Utils
+Requires-Dist: python-dotenv
+
+![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/ivoryos.png)
+# ivoryOS: interoperable Web UI for self-driving laboratories (SDLs)
+"plug and play" web UI extension for flexible SDLs.
+
+## Table of Contents
+- [Description](#description)
+- [System requirements](#system-requirements)
+- [Installation](#installation)
+- [Instructions for use](#instructions-for-use)
+- [Demo](#demo)
+- [License](#license)
+
+## Description
+Granting SDLs flexibility and modularity makes it almost impossible to design a UI, yet it's a necessity for allowing more people to interact with it (democratisation). 
+This web UI aims to ease up the control of any Python-based SDLs by displaying functions and parameters for initialized modules dynamically. 
+The modules can be hardware API, high-level functions, or experiment workflow.
+With the least modification of the current workflow, user can design, manage and execute their experimental designs and monitor the execution process. 
+
+## System requirements
+This software is developed and tested using Windows. This software and its dependencies are compatible across major platforms: Linux, macOS, and Windows. Some dependencies (Flask-SQLAlchemy) may require additional setup.
+
+### Python Version
+Python >=3.7 for best compatibility.
+### Python dependencies
+This software is compatible with the latest versions of all dependencies. 
+- bcrypt~=4.0
+- Flask-Login~=0.6
+- Flask-Session~=0.8
+- Flask-SocketIO~=5.3
+- Flask-SQLAlchemy~=3.1
+- SQLAlchemy-Utils~=0.41
+- Flask-WTF~=1.2
+- python-dotenv==1.0.1
+- openai (optional ~=1.53)
+- ax-platform (optional ~=0.3 or ~=0.4 for Python>=3.9)
+
+## Installation
+```bash
+pip install ivoryos
+```
+or
+```bash
+git clone https://gitlab.com/heingroup/ivoryos.git
+cd ivoryos
+pip install -e .
+```
+
+The installation may take 10 to 30 seconds to install. The installation time may vary and take up to several minutes, depending on the network speed, computer performance, and virtual environment settings.
+
+## Instructions for use
+### Quick start
+In your SDL script, use `ivoryos(__name__)`. 
+```python
+import ivoryos
+
+ivoryos.run(__name__)
+```
+### Login
+Create an account and login (local database)
+### Features
+- **Direct control**: direct function calling _Device_ tab
+- **Workflow design and iteration**:
+  - **Design**: add function to canvas in _Design_ tab. click `Compile and Run` button to go to the execution page
+  - **Execution**: configure iteration methods and parameters in _Compile/Run_ tab. 
+  - **Database**: manage workflows in _Library_ tab.
+- **Info page**: additional info in _About_ tab.
+
+
+### Additional settings
+#### AI assistant
+To streamline the experimental design on SDLs, we also integrate Large Language Models (LLMs) to interpret the inspected functions and generate code according to task descriptions.
+
+#### Enable LLMs with [OpenAI API](https://github.com/openai/openai-python)
+1. Create a `.env` file for `OPENAI_API_KEY`
+```
+OPENAI_API_KEY="Your API Key"
+```
+2. In your SDL script, define model, you can use any GPT models.
+
+```python
+ivoryos.run(__name__, model="gpt-3.5-turbo")
+```
+
+#### Enable local LLMs with [Ollama](https://ollama.com/)
+1. Download Ollama.
+2. pull models from Ollama
+3. In your SDL script, define LLM server and model, you can use any models available on Ollama.
+
+```python
+ivoryos.run(__name__, llm_server="localhost", model="llama3.1")
+```
+
+#### Add additional logger(s)
+```python
+ivoryos.run(__name__, logger="logger name")
+```
+or
+```python
+ivoryos.run(__name__, logger=["logger 1", "logger 2"])
+```
+#### Offline (design without hardware connection)
+After one successful connection, a blueprint will be automatically saved and made accessible without hardware connection. In a new Python script in the same directory, use `ivoryos.run()` to start offline mode.
+
+```python
+ivoryos.run()
+```
+## Demo
+In the [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/example/sdl_example/abstract_sdl.py), where instances of `AbstractSDL` is created as `sdl`,
+addresses will be available on terminal.
+```Python
+ivoryos.run(__name__)
+```
+
+ * Running on all addresses (0.0.0.0)
+ * Running on http://127.0.0.1:8000
+ * Running on http://xxx.xx.xx.xxx:8000
+
+### Deck function and web form 
+![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/demo.gif)
+
+### Directory structure
+
+When you run the application for the first time, it will automatically create the following folders and files in the same directory:
+
+- **`ivoryos_data/`**: Main directory for application-related data.
+  - **`ivoryos_data/config_csv/`**: Contains iteration configuration files in CSV format.
+  - **`ivoryos_data/llm_output/`**: Stores raw prompt generated for the large language model.
+  - **`ivoryos_data/pseudo_deck/`**: Contains pseudo-deck `.pkl` files for offline access.
+  - **`ivoryos_data/results/`**: Used for storing results or outputs during workflow execution.
+  - **`ivoryos_data/scripts/`**: Holds Python scripts compiled from the visual programming script design.
+
+- **`default.log`**: Log file that captures application logs.
+- **`ivoryos.db`**: Database file that stores application data locally.
+
+
+### Demo video
+Intro + Tutorial + Demo with PurPOSE platform
+https://youtu.be/dFfJv9I2-1g 
+
+
+## Authors and Acknowledgement
+Ivory Zhang, Lucy Hao
+
+Authors acknowledge all former and current Hein Lab members for their valuable suggestions. 
+
+## License
+[LICENSE](LICENSE)

{ivoryos-0.1.5.dist-info → ivoryos-0.1.6.dist-info}/RECORD

@@ -1,25 +1,25 @@
-ivoryos/__init__.py,sha256=XCKzSohAH86YPczmErM4njggMrnUsRBxsG8Uj7CKLyk,3526
-ivoryos/config.py,sha256=wi0sDjr4E-TImj85BQbKcT-wY3TlZbcGVTpJda7twvE,1297
+ivoryos/__init__.py,sha256=prqANp0lD5gqHOsvVEhnuAgaCvKg2BcC3zWiXZbJS_U,3535
+ivoryos/config.py,sha256=K03jdGmbUfJ9o4kK6NOtDGJtydGHFq8-oU8nvCyq5zQ,1358
 ivoryos/routes/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ivoryos/routes/auth/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ivoryos/routes/auth/auth.py,sha256=NWII2gQEUHxQmuwd4QKRrGczKVo6uWMuPq24P9TUUss,2381
 ivoryos/routes/auth/templates/auth/login.html,sha256=1uxYU7NpxVaA4sfwkC6CuzZXJdy1VnxBzztmsMPcrxE,1232
 ivoryos/routes/auth/templates/auth/signup.html,sha256=QQ7n4OBnF8TNFS5_4s11n4BCqSePn429rZfA6vO8qw8,1497
 ivoryos/routes/control/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ivoryos/routes/control/control.py,sha256=xicTfpMo2hF6AVz2ZC9Y8qLXqGH8vyqPsKzrCZZ1BQ0,9607
-ivoryos/routes/control/templates/control/controllers.html,sha256=nPQ7JmM0KmPV8bh1VMdZmyfyGEEb7fb4nsThdk9ZaoY,3984
+ivoryos/routes/control/control.py,sha256=YKM1T_bDIggbW_NF6Ld6-rb3d0KbAjyikJztN-ka_XM,11305
+ivoryos/routes/control/templates/control/controllers.html,sha256=CD1DEm9DuBBlKg_ltrEWgNxWhTIR9C2_a0-AkxwGre0,4146
 ivoryos/routes/control/templates/control/controllers_home.html,sha256=IND1T3_mPZd-MzfuyodbedMnmsTowiTVdRp5ez6NoZM,2783
 ivoryos/routes/control/templates/control/controllers_new.html,sha256=Wqn9x9D6K7RWHkLFxvZkzbIJxHJR1zywQ6WDgySXOig,5010
 ivoryos/routes/database/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ivoryos/routes/database/database.py,sha256=HF5JyUHtpR9L6IBBVCnyNTDgc1OH6XnVc2Y5RgXIejo,4328
+ivoryos/routes/database/database.py,sha256=e1OpmQayM0KYUTPiYQzXHo-zLVd5yHtS0EYNce7vcmQ,4357
 ivoryos/routes/database/templates/database/experiment_database.html,sha256=x9zf4u4KbG6BEICnH_TOVNNUkp5oAmGBB12OUX0PPl4,3506
 ivoryos/routes/design/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ivoryos/routes/design/design.py,sha256=AOSbz7a-TZWkh_EUNCSXF-D_XjMjLKfmLYHwncYvW9s,16886
+ivoryos/routes/design/design.py,sha256=g1V4HYLldD7O6K5brtdxV8uoyOVGTpM3rC1lOmw91AA,16913
 ivoryos/routes/design/templates/design/experiment_builder.html,sha256=IAU9XvtbcEWDlnCqf2Z81gcBB7bNDFOfod3xLJfRbQc,27371
 ivoryos/routes/design/templates/design/experiment_run.html,sha256=xoEHH8CC83KCWTPavwP9JWUI8SE5HX9bkEfJN6vMg5s,22845
 ivoryos/routes/main/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 ivoryos/routes/main/main.py,sha256=Zkagtw0E67FaspNJ87jkYpc-wqqoTq99dyyB7qdnOVM,655
-ivoryos/routes/main/templates/main/help.html,sha256=RMHCDMKn0AyKfADNF7iex1CYid_KJQP7CtpervIM2NM,9786
+ivoryos/routes/main/templates/main/help.html,sha256=TY6uD-v8MXpiZlGucchko1Bas5jHRzARIgCgneBZ_ok,9511
 ivoryos/routes/main/templates/main/home.html,sha256=fjeSSXkuVDr2y-CQmskNHf1yYFFdrPPI4wn6_XPb6AY,3252
 ivoryos/static/favicon.ico,sha256=RhlrPtfITOkzC9BjP1UB1V5L9Oyp6NwNtWeMcGOnpyc,15406
 ivoryos/static/logo.png,sha256=7lNyToDllflGPUK2sj7IBR8FkHLC-6gi-OVSL9o4jrs,63464
@@ -32,15 +32,15 @@ ivoryos/static/js/sortable_card.js,sha256=mDVd2YjhusLokUw3xL6YOZLXIzty9yKDsC1U5y
 ivoryos/static/js/sortable_design.js,sha256=BxNXzqET_yY0xpS1Fc0iwPCnkkDwYMiuVqkgOPMb6JY,1156
 ivoryos/templates/base.html,sha256=cu6MZMlfOR0IhuNrMin_pWYtm1_TpJLHI6KH5NomopI,7763
 ivoryos/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-ivoryos/utils/db_models.py,sha256=VXkOSnYVABoYgCTYo1F9BH-Zd922ToMuvwyRaFtG7cc,19248
-ivoryos/utils/form.py,sha256=2dFtuhwcu5g_fksXd-FH414z5y_htTfHB0btfPxD7b0,12262
-ivoryos/utils/global_config.py,sha256=oCegHTk2k9rGrODNFrnwrgFaww-5QUp0dGdO5sz-GO8,1662
+ivoryos/utils/db_models.py,sha256=umEATdxDP-sR_AMaLrOW2PBUcmBf1w38DLeFkBvVjJE,19280
+ivoryos/utils/form.py,sha256=W8fSGybeWSCfPqySEfH1mKJbdoYmRb3vwpy15w2rj_Q,12226
+ivoryos/utils/global_config.py,sha256=JCQvmZB0pNC-EjveRu48Tp4uvcNwn9DP3Ema6Xd9fJY,1656
 ivoryos/utils/llm_agent.py,sha256=pxiaiIVHzbGA_Tq4yOZY3iyIDikx6-_chIvPEjlywLg,6607
 ivoryos/utils/script_runner.py,sha256=jlJMCFLmcS6GOlOfEmLXAzG47sU18nNtRPtojjdN018,6919
 ivoryos/utils/task_manager.py,sha256=xfQ1s9ywWDrCYYpdgliVvoWED0s2xARmo3LXvAy6fgY,2517
-ivoryos/utils/utils.py,sha256=Oia2ZITlW-oRglmjc_Y02FP-dwHeEFB_nrZ-4bNHkVY,12060
-ivoryos-0.1.5.dist-info/LICENSE,sha256=psyqat4GJkzi42551i0kH-bXLbEzrQEnjPDwy2TVhv8,1105
-ivoryos-0.1.5.dist-info/METADATA,sha256=ljumv9yicCP_tMkfeFl5P7yTGw4WhYPqdDFQSL2yb8g,3585
-ivoryos-0.1.5.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
-ivoryos-0.1.5.dist-info/top_level.txt,sha256=FRIWWdiEvRKqw-XfF_UK3XV0CrnNb6EmVbEgjaVazRM,8
-ivoryos-0.1.5.dist-info/RECORD,,
+ivoryos/utils/utils.py,sha256=8GMuMwKUKKMjz8hvilavNlV4RANcQWsJy8hZpbXanRg,15042
+ivoryos-0.1.6.dist-info/LICENSE,sha256=psyqat4GJkzi42551i0kH-bXLbEzrQEnjPDwy2TVhv8,1105
+ivoryos-0.1.6.dist-info/METADATA,sha256=QTek7bK8bAPqXCo0RIY6w_YTUeisTWFcg2ythkjqYc4,6101
+ivoryos-0.1.6.dist-info/WHEEL,sha256=yQN5g4mg4AybRjkgi-9yy4iQEFibGQmlz78Pik5Or-A,92
+ivoryos-0.1.6.dist-info/top_level.txt,sha256=FRIWWdiEvRKqw-XfF_UK3XV0CrnNb6EmVbEgjaVazRM,8
+ivoryos-0.1.6.dist-info/RECORD,,

ivoryos-0.1.5.dist-info/METADATA

@@ -1,96 +0,0 @@
-Metadata-Version: 2.1
-Name: ivoryos
-Version: 0.1.5
-Summary: an open-source Python package enabling Self-Driving Labs (SDLs) interoperability
-Home-page: https://gitlab.com/heingroup/ivoryos
-Author: Ivory Zhang
-Author-email: ivoryzhang@chem.ubc.ca
-License: MIT
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: bcrypt
-Requires-Dist: Flask-Login
-Requires-Dist: Flask-Session
-Requires-Dist: Flask-SocketIO
-Requires-Dist: Flask-SQLAlchemy
-Requires-Dist: Flask-WTF
-Requires-Dist: SQLAlchemy-Utils
-Requires-Dist: python-dotenv
-
-![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/ivoryos.png)
-# ivoryOS: interoperable Web UI for self-driving laboratories (SDLs)
-ivoryOS is a "plug and play" web UI extension for flexible SDLs, enabling interoperability between SDLs.
-## Description
-Granting SDLs flexibility and modularity makes it almost impossible to design a UI, yet it's a necessity for allowing more people to interact with it (democratisation). 
-This web UI aims to ease up the control of any Python-based SDLs by displaying functions and parameters for initialized modules dynamically. 
-The modules can be hardware API, high-level functions, or experiment workflow.
-With the least modification of the current workflow, user can design, manage and execute their experimental designs and monitor the execution process. 
-## AI assistant
-To streamline the experimental design on SDLs, we also integrate Large Language Models (LLMs) to interpret the inspected functions and generate code according to task descriptions.
-
-## Installation
-```
-pip install ivoryos
-```
-
-## Usage
-### Quick start
-In your SDL script, use `ivoryos(__name__)`. Example in [abstract_sdl.py](https://gitlab.com/heingroup/ivoryos/-/blob/main/example/dummy_ur/dummy_deck.py)
-
-```python
-import ivoryos
-
-ivoryos.run(__name__)
-```
-
-### Additional settings
-#### Enable LLMs with [OpenAI API](https://github.com/openai/openai-python)
-1. Create a `.env` file for `OPENAI_API_KEY`
-```
-OPENAI_API_KEY="Your API Key"
-```
-2. In your SDL script, define model, you can use any GPT models.
-
-```python
-ivoryos.run(__name__, model="gpt-3.5-turbo")
-```
-
-#### Enable local LLMs with [Ollama](https://ollama.com/)
-1. Download Ollama.
-2. pull models from Ollama
-3. In your SDL script, define LLM server and model, you can use any models available on Ollama.
-
-```python
-ivoryos.run(__name__, llm_server="localhost", model="llama3.1")
-```
-
-#### Add additional logger(s)
-```python
-ivoryos.run(__name__, logger="logger name")
-```
-or
-```python
-ivoryos.run(__name__, logger=["logger 1", "logger 2"])
-```
-#### Offline (design without hardware connection)
-After one successful connection, a blueprint will be automatically saved and made accessible without hardware connection. In a new Python script in the same directory, use `ivoryos.run()` to start offline mode.
-
-```python
-ivoryos.run()
-```
-## Deck snapshot example
-![](https://gitlab.com/heingroup/ivoryos/raw/main/docs/demo.gif)
-## Developing
-This is a wip project. Here are some future actions.
-1. Support @setter decorator.
-2. Documentation: white paper wip
-3. Compatibility: compatability report to open-source lab hardware APIs will soon be added. As of now, due to the limitation of web form, the usability of APIs with object inputs (e.g. Opentron Python API) is very limited.
-
-
-## Authors and Acknowledgement
-Ivory Zhang, Lucy Hao
-
-Authors acknowledge all former and current Hein Lab members for their valuable suggestions. 
-
-## License
-[LICENSE](LICENSE)