From 7002d5c123b2592eb424c92da1431ee9d52be612 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Fri, 25 Sep 2026 14:54:14 -0700 Subject: [PATCH 01/21] add first thoughts for taskdb update --- src/openfe/orchestration/exorcist_utils.py | 27 ++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 0d430c760..f21a62c69 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -153,3 +153,30 @@ def get_dependency_df(task_db: exorcist.TaskStatusDB) -> pd.DataFrame: """ return pd.read_sql_table("dependencies", task_db.engine) + + +def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int, task_id: str) -> None: + """Update the `max_tries` column of a TaskStatusDB + + Parameters + ---------- + task_db : exorcist.TaskStatusDB + TaskStatusDB to update + max_tries : int + new value of ``max_tries`` to assign row matching task_id + task_id : the task_id used to select the row to update + """ + + import sqlalchemy as sqla + from exorcist import TaskStatus + + # TODO: update all rows if task_id==None + # TODO: bump all ``TOO_MANY_RETRIES`` + if task_id: + update_task_max_tries = task_db._task_row_update_statement( + task_id, + max_tries=max_tries, + ) + with task_db.engine.begin() as conn: + result = conn.execute(update_task_max_tries) + task_db._validate_update_result(result) From 18c8811c6845f6489b4f33d2d7dcdf6929475aa5 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 29 Sep 2026 16:23:16 -0700 Subject: [PATCH 02/21] add minimal working version --- src/openfe/orchestration/__init__.py | 1 + src/openfe/orchestration/exorcist_utils.py | 23 ++++++++++++++++++++++ 2 files changed, 24 insertions(+) diff --git a/src/openfe/orchestration/__init__.py b/src/openfe/orchestration/__init__.py index 25b0e416d..0e61162d4 100644 --- a/src/openfe/orchestration/__init__.py +++ b/src/openfe/orchestration/__init__.py @@ -4,5 +4,6 @@ get_dependency_df, get_task_df, setup_task_campaign, + update_max_tries, ) from .worker import Worker diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index f21a62c69..b32fa2111 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -75,6 +75,7 @@ def _alchemical_network_to_task_graph( return global_task_dag +# TODO: add `exists_okay` option to add to an existing campaign def setup_task_campaign( alchemical_network: AlchemicalNetwork, warehouse_dir: Path, # TODO: make optional? @@ -180,3 +181,25 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int, task_id: st with task_db.engine.begin() as conn: result = conn.execute(update_task_max_tries) task_db._validate_update_result(result) + + +def update_max_tries(task_db: exorcist.TaskStatusDB, value: int): + import sqlalchemy as sqla + from exorcist.models import TaskStatus + + """ + Update the "max_tries" column to `value`. + Only rows that do _not_ have status=COMPLETED will be operated on. + + """ + # TODO: if "TOO MANY TRIES", update to AVAILABLE + # TODO: only allow increases if TOO MANY TRIES? maybe only operate on rows where max_tries < val? + # TODO: select a single task_id? + update_statement = ( + sqla.update(task_db.tasks_table) + .where(task_db.tasks_table.c.status != TaskStatus.COMPLETED.value) + .values(max_tries=value) + ) + + with task_db.engine.begin() as conn: + result = conn.execute(update_statement) From e59c107b30cbc71c6353e7659401535a52fc4dcd Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Wed, 30 Sep 2026 08:51:29 -0700 Subject: [PATCH 03/21] pull in test fixtures from exorcist --- .../orchestration/test_exorcist_utils.py | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index 6f93e3f75..10d8eb841 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -268,3 +268,55 @@ def test_get_dependency_df(benzene_star_map_task_db): assert isinstance(df, pd.DataFrame) assert list(df.columns) == ["from", "to", "blocking"] assert len(df) == 504 + + +# NOTE: pulled this fixture from exorcist, since I expect to upstream the tests below +from datetime import datetime + +from exorcist import TaskStatus, TaskStatusDB + +_DEFAULT_DATETIME = datetime(1970, 1, 1) + + +def patch_datetime_now(with_datetime=_DEFAULT_DATETIME): + # turns out we can't patch just the now() method (datetime is immutable, + # probably C code?) so we have to patch the entire datetime module + loc = "exorcist.taskdb.datetime" + datetime_now = mock.Mock(now=mock.Mock(return_value=with_datetime)) + return mock.patch(loc, datetime_now) + + +def get_tasks_and_deps(db): + with db.engine.connect() as conn: + tasks = set(conn.execute(sqla.select(db.tasks_table))) + deps = set(conn.execute(sqla.select(db.dependencies_table))) + return tasks, deps + + +def task_row(taskid, status, last_modified, tries, max_tries, task_type=""): + return (taskid, status.value, last_modified, tries, max_tries, task_type) + + +@pytest.fixture +def fresh_db(): + # create an empty database; for "real" (non-sqlite) databases, drop + # existing tables + echo = False # switch this for debugging + engine = sqla.create_engine("sqlite://", echo=echo) + + yield TaskStatusDB(engine) + + +def test_task_type_preserved_through_checkout_and_completion(fresh_db): + fresh_db.add_task("gpu-task", requirements=[], max_tries=3, task_type="gpu") + + with patch_datetime_now(): + taskid = fresh_db.check_out_task() + assert taskid == "gpu-task" + + with patch_datetime_now(): + fresh_db.mark_task_completed(taskid, success=True) + + tasks, deps = get_tasks_and_deps(fresh_db) + assert tasks == {task_row("gpu-task", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 3, "gpu")} + assert deps == set() From bf3f8cafe9f46d93df98e43cbb92d4c42e30fdb8 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 10:35:21 -0700 Subject: [PATCH 04/21] remove duplicate --- src/openfe/orchestration/exorcist_utils.py | 28 +--------------------- 1 file changed, 1 insertion(+), 27 deletions(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index b32fa2111..6000cd2d3 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -156,33 +156,6 @@ def get_dependency_df(task_db: exorcist.TaskStatusDB) -> pd.DataFrame: return pd.read_sql_table("dependencies", task_db.engine) -def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int, task_id: str) -> None: - """Update the `max_tries` column of a TaskStatusDB - - Parameters - ---------- - task_db : exorcist.TaskStatusDB - TaskStatusDB to update - max_tries : int - new value of ``max_tries`` to assign row matching task_id - task_id : the task_id used to select the row to update - """ - - import sqlalchemy as sqla - from exorcist import TaskStatus - - # TODO: update all rows if task_id==None - # TODO: bump all ``TOO_MANY_RETRIES`` - if task_id: - update_task_max_tries = task_db._task_row_update_statement( - task_id, - max_tries=max_tries, - ) - with task_db.engine.begin() as conn: - result = conn.execute(update_task_max_tries) - task_db._validate_update_result(result) - - def update_max_tries(task_db: exorcist.TaskStatusDB, value: int): import sqlalchemy as sqla from exorcist.models import TaskStatus @@ -203,3 +176,4 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, value: int): with task_db.engine.begin() as conn: result = conn.execute(update_statement) + # task_db._validate_update_result(result) From 7d63a64ef5048fcf7f2571421e618ce0cc67d36a Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 13:53:22 -0700 Subject: [PATCH 05/21] add test task status db --- .../orchestration/test_exorcist_utils.py | 36 ++++++++++++------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index 10d8eb841..623e0a415 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -299,24 +299,34 @@ def task_row(taskid, status, last_modified, tries, max_tries, task_type=""): @pytest.fixture def fresh_db(): - # create an empty database; for "real" (non-sqlite) databases, drop - # existing tables + # create an empty database echo = False # switch this for debugging engine = sqla.create_engine("sqlite://", echo=echo) yield TaskStatusDB(engine) -def test_task_type_preserved_through_checkout_and_completion(fresh_db): - fresh_db.add_task("gpu-task", requirements=[], max_tries=3, task_type="gpu") +def test_update_max_tries(fresh_db): + task_db = fresh_db + task_db.add_task("task_a", requirements=[], max_tries=1) + task_db.add_task("task_b", requirements=["task_a"], max_tries=1) + task_db.add_task("task_c", requirements=[], max_tries=1) with patch_datetime_now(): - taskid = fresh_db.check_out_task() - assert taskid == "gpu-task" - - with patch_datetime_now(): - fresh_db.mark_task_completed(taskid, success=True) - - tasks, deps = get_tasks_and_deps(fresh_db) - assert tasks == {task_row("gpu-task", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 3, "gpu")} - assert deps == set() + taskid = task_db.check_out_task() + assert taskid == "task_a" + task_db.mark_task_completed(taskid, success=True) + + taskid = task_db.check_out_task() + assert taskid == "task_b" + task_db.mark_task_completed(taskid, success=False) + + tasks, deps = get_tasks_and_deps(task_db) + + expected_tasks = { + task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""), + task_row("task_b", TaskStatus.TOO_MANY_RETRIES, _DEFAULT_DATETIME, 1, 1, ""), + task_row("task_c", TaskStatus.AVAILABLE, None, 0, 1, ""), + } + assert tasks == expected_tasks + assert deps == {("task_a", "task_b", False)} From eb2bacc09d2b0e4b170524fea890e2d24744ac91 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 13:56:52 -0700 Subject: [PATCH 06/21] add test for current (incomplete) behavior --- .../tests/orchestration/test_exorcist_utils.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index 623e0a415..08bd93c42 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -14,7 +14,7 @@ get_task_df, setup_task_campaign, ) -from openfe.orchestration.exorcist_utils import _alchemical_network_to_task_graph +from openfe.orchestration.exorcist_utils import _alchemical_network_to_task_graph, update_max_tries from openfe.storage.warehouse import WarehouseBaseClass @@ -323,10 +323,18 @@ def test_update_max_tries(fresh_db): tasks, deps = get_tasks_and_deps(task_db) - expected_tasks = { + assert tasks == { task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""), task_row("task_b", TaskStatus.TOO_MANY_RETRIES, _DEFAULT_DATETIME, 1, 1, ""), task_row("task_c", TaskStatus.AVAILABLE, None, 0, 1, ""), } - assert tasks == expected_tasks assert deps == {("task_a", "task_b", False)} + + update_max_tries(task_db=task_db, value=18) + tasks, deps = get_tasks_and_deps(task_db) + + assert tasks == { + task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""), + task_row("task_b", TaskStatus.TOO_MANY_RETRIES, _DEFAULT_DATETIME, 1, 18, ""), + task_row("task_c", TaskStatus.AVAILABLE, None, 0, 18, ""), + } From 63f32e775ef3e4ee210daf1698005f40b2b56bdf Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 15:29:26 -0700 Subject: [PATCH 07/21] cover typical use cases --- src/openfe/orchestration/exorcist_utils.py | 46 ++++++++++++++----- .../orchestration/test_exorcist_utils.py | 17 +++++-- 2 files changed, 46 insertions(+), 17 deletions(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 6000cd2d3..9750c6457 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -4,6 +4,7 @@ structures and can initialize an Exorcist task database from that graph. """ +from datetime import datetime from pathlib import Path import exorcist @@ -156,24 +157,45 @@ def get_dependency_df(task_db: exorcist.TaskStatusDB) -> pd.DataFrame: return pd.read_sql_table("dependencies", task_db.engine) -def update_max_tries(task_db: exorcist.TaskStatusDB, value: int): - import sqlalchemy as sqla - from exorcist.models import TaskStatus - - """ - Update the "max_tries" column to `value`. +def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): + """Update the "max_tries" column to `max_tries`. Only rows that do _not_ have status=COMPLETED will be operated on. + Parameters + ---------- + task_db : openfe.TaskStatusDB + The TaskStatusDB to update + value : int + The integer value to assign as ``max_tries`` for the updated columns. + """ - # TODO: if "TOO MANY TRIES", update to AVAILABLE - # TODO: only allow increases if TOO MANY TRIES? maybe only operate on rows where max_tries < val? + + import sqlalchemy as sqla + from exorcist.models import TaskStatus + # TODO: select a single task_id? - update_statement = ( + + values = {"max_tries": max_tries, "last_modified": datetime.now()} + + # on the rows that already hit TOO_MANY_RETRIES, only allow increasing max_tries, + # otherwise the state is invalid, and set to AVAILABLE + stmt_update_too_many_retries = ( + sqla.update(task_db.tasks_table) + .where(task_db.tasks_table.c.status == TaskStatus.TOO_MANY_RETRIES.value) + .where(task_db.tasks_table.c.max_tries < max_tries) + .values(**values, status=TaskStatus.AVAILABLE.value) + ) + + # COMPLETED tasks should not be updated, and never allow max_tries to be less than + # the number of attempts already made (tries), otherwise the state is invalid. + stmt_update_uncompleted_tasks = ( sqla.update(task_db.tasks_table) .where(task_db.tasks_table.c.status != TaskStatus.COMPLETED.value) - .values(max_tries=value) + .where(task_db.tasks_table.c.tries < max_tries) + .values(**values) ) with task_db.engine.begin() as conn: - result = conn.execute(update_statement) - # task_db._validate_update_result(result) + # TODO: is there a better way than calling this twice? + conn.execute(stmt_update_too_many_retries) + conn.execute(stmt_update_uncompleted_tasks) diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index 08bd93c42..2d6eff0d8 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -278,7 +278,7 @@ def test_get_dependency_df(benzene_star_map_task_db): _DEFAULT_DATETIME = datetime(1970, 1, 1) -def patch_datetime_now(with_datetime=_DEFAULT_DATETIME): +def patch_exorcist_datetime(with_datetime=_DEFAULT_DATETIME): # turns out we can't patch just the now() method (datetime is immutable, # probably C code?) so we have to patch the entire datetime module loc = "exorcist.taskdb.datetime" @@ -286,6 +286,12 @@ def patch_datetime_now(with_datetime=_DEFAULT_DATETIME): return mock.patch(loc, datetime_now) +def patch_openfe_datetime(with_datetime=_DEFAULT_DATETIME): + loc = "openfe.orchestration.exorcist_utils.datetime" + datetime_now = mock.Mock(now=mock.Mock(return_value=with_datetime)) + return mock.patch(loc, datetime_now) + + def get_tasks_and_deps(db): with db.engine.connect() as conn: tasks = set(conn.execute(sqla.select(db.tasks_table))) @@ -312,7 +318,7 @@ def test_update_max_tries(fresh_db): task_db.add_task("task_b", requirements=["task_a"], max_tries=1) task_db.add_task("task_c", requirements=[], max_tries=1) - with patch_datetime_now(): + with patch_exorcist_datetime(): taskid = task_db.check_out_task() assert taskid == "task_a" task_db.mark_task_completed(taskid, success=True) @@ -330,11 +336,12 @@ def test_update_max_tries(fresh_db): } assert deps == {("task_a", "task_b", False)} - update_max_tries(task_db=task_db, value=18) + with patch_openfe_datetime(): + update_max_tries(task_db=task_db, max_tries=18) tasks, deps = get_tasks_and_deps(task_db) assert tasks == { task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""), - task_row("task_b", TaskStatus.TOO_MANY_RETRIES, _DEFAULT_DATETIME, 1, 18, ""), - task_row("task_c", TaskStatus.AVAILABLE, None, 0, 18, ""), + task_row("task_b", TaskStatus.AVAILABLE, _DEFAULT_DATETIME, 1, 18, ""), + task_row("task_c", TaskStatus.AVAILABLE, _DEFAULT_DATETIME, 0, 18, ""), } From efbd10afed9757ee22afa8292af76c4545200580 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 15:34:50 -0700 Subject: [PATCH 08/21] make sure only the updated columns datetimes change --- src/openfe/tests/orchestration/test_exorcist_utils.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index 2d6eff0d8..e27979e13 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -336,12 +336,13 @@ def test_update_max_tries(fresh_db): } assert deps == {("task_a", "task_b", False)} - with patch_openfe_datetime(): + datetime2 = datetime(1999, 1, 1) + with patch_openfe_datetime(datetime2): update_max_tries(task_db=task_db, max_tries=18) tasks, deps = get_tasks_and_deps(task_db) assert tasks == { task_row("task_a", TaskStatus.COMPLETED, _DEFAULT_DATETIME, 1, 1, ""), - task_row("task_b", TaskStatus.AVAILABLE, _DEFAULT_DATETIME, 1, 18, ""), - task_row("task_c", TaskStatus.AVAILABLE, _DEFAULT_DATETIME, 0, 18, ""), + task_row("task_b", TaskStatus.AVAILABLE, datetime2, 1, 18, ""), + task_row("task_c", TaskStatus.AVAILABLE, datetime2, 0, 18, ""), } From 52617cbcf04c06e3a98dbe683a79d1464a320d93 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Mon, 5 Oct 2026 15:39:21 -0700 Subject: [PATCH 09/21] remove todo --- src/openfe/orchestration/exorcist_utils.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 9750c6457..a8804e725 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -76,7 +76,6 @@ def _alchemical_network_to_task_graph( return global_task_dag -# TODO: add `exists_okay` option to add to an existing campaign def setup_task_campaign( alchemical_network: AlchemicalNetwork, warehouse_dir: Path, # TODO: make optional? From d41476b2c0402b4966c602b38723749e827568a4 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Tue, 6 Oct 2026 11:37:34 -0700 Subject: [PATCH 10/21] Update src/openfe/orchestration/exorcist_utils.py Co-authored-by: Irfan Alibay --- src/openfe/orchestration/exorcist_utils.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index a8804e725..622f1463b 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -164,7 +164,7 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): ---------- task_db : openfe.TaskStatusDB The TaskStatusDB to update - value : int + max_tries : int The integer value to assign as ``max_tries`` for the updated columns. """ From 79786f654f493afbe2fb9ce8986104000038481d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 11:44:55 -0700 Subject: [PATCH 11/21] add additional filter suggestion from ialibay --- src/openfe/orchestration/exorcist_utils.py | 1 + 1 file changed, 1 insertion(+) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 622f1463b..00bfea12d 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -191,6 +191,7 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): sqla.update(task_db.tasks_table) .where(task_db.tasks_table.c.status != TaskStatus.COMPLETED.value) .where(task_db.tasks_table.c.tries < max_tries) + .where(task_db.tasks_table.c.max_tries != max_tries) .values(**values) ) From e54c0c16c035fbec2de38d162f18c1beceacc91a Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 11:54:14 -0700 Subject: [PATCH 12/21] add input validation for max_tries --- src/openfe/orchestration/exorcist_utils.py | 6 ++++++ src/openfe/tests/orchestration/test_exorcist_utils.py | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 00bfea12d..b72d88d9d 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -167,12 +167,18 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): max_tries : int The integer value to assign as ``max_tries`` for the updated columns. + Raises + ------ + ValueError: If max_tries is not a positive integer. + """ import sqlalchemy as sqla from exorcist.models import TaskStatus # TODO: select a single task_id? + if not isinstance(max_tries, int) or max_tries <= 0: + raise ValueError("`max_tries` must be a positive integer.") values = {"max_tries": max_tries, "last_modified": datetime.now()} diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index e27979e13..b16c5b934 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -346,3 +346,9 @@ def test_update_max_tries(fresh_db): task_row("task_b", TaskStatus.AVAILABLE, datetime2, 1, 18, ""), task_row("task_c", TaskStatus.AVAILABLE, datetime2, 0, 18, ""), } + + +@pytest.mark.parametrize("bad_value", ["1", -2, 3.0, 0]) +def test_update_max_tries_invalid_val(fresh_db, bad_value): + with pytest.raises(ValueError, match="must be a positive integer"): + update_max_tries(task_db=fresh_db, max_tries=bad_value) From 85a333f4844471371dc86ddb450e74e19ff0aa6f Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 11:57:28 -0700 Subject: [PATCH 13/21] expose API and add to reference docs --- .../defining_and_executing_simulations.rst | 1 + news/max_tries.rst | 23 +++++++++++++++++++ src/openfe/__init__.py | 2 +- 3 files changed, 25 insertions(+), 1 deletion(-) create mode 100644 news/max_tries.rst diff --git a/docs/reference/api/defining_and_executing_simulations.rst b/docs/reference/api/defining_and_executing_simulations.rst index 6bbf76cdd..29d43287d 100644 --- a/docs/reference/api/defining_and_executing_simulations.rst +++ b/docs/reference/api/defining_and_executing_simulations.rst @@ -21,6 +21,7 @@ Executing Simulations TaskStatusDB get_task_df get_dependency_df + update_max_tries storage.FileSystemWarehouse diff --git a/news/max_tries.rst b/news/max_tries.rst new file mode 100644 index 000000000..f1918037b --- /dev/null +++ b/news/max_tries.rst @@ -0,0 +1,23 @@ +**Added:** + +* Added ``openfe.update_max_tries()`` for updating a ``TaskStatusDB`` (`PR #2227 `_). + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/openfe/__init__.py b/src/openfe/__init__.py index 210feb40e..d7ba46a46 100644 --- a/src/openfe/__init__.py +++ b/src/openfe/__init__.py @@ -73,7 +73,7 @@ ) from . import analysis, orchestration, setup, storage, utils -from .orchestration import get_dependency_df, get_task_df, setup_task_campaign +from .orchestration import get_dependency_df, get_task_df, setup_task_campaign, update_max_tries from .orchestration.worker import Worker from .setup import ( KartografAtomMapper, From e7225891bedb5441c53cc9a3c17e158bac85f761 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 12:43:31 -0700 Subject: [PATCH 14/21] positive int type hint --- src/openfe/orchestration/exorcist_utils.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index b72d88d9d..5a8232c14 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -10,6 +10,7 @@ import exorcist import networkx as nx import pandas as pd +from annotated_types import Annotated, Gt from gufe import AlchemicalNetwork, ProtocolDAG from ..storage.warehouse import FileSystemWarehouse, WarehouseBaseClass @@ -156,7 +157,7 @@ def get_dependency_df(task_db: exorcist.TaskStatusDB) -> pd.DataFrame: return pd.read_sql_table("dependencies", task_db.engine) -def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): +def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: Annotated[int, Gt(0)]): """Update the "max_tries" column to `max_tries`. Only rows that do _not_ have status=COMPLETED will be operated on. @@ -165,7 +166,7 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: int): task_db : openfe.TaskStatusDB The TaskStatusDB to update max_tries : int - The integer value to assign as ``max_tries`` for the updated columns. + The positive integer value to assign as ``max_tries`` for the updated columns. Raises ------ From 22014e1884966bb869b8309ba42a7ab653837562 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 12:44:05 -0700 Subject: [PATCH 15/21] add CLI update-task-db --- src/openfecli/commands/update_task_db.py | 106 ++++++++++++++++++ .../tests/commands/test_update_task_db.py | 40 +++++++ 2 files changed, 146 insertions(+) create mode 100644 src/openfecli/commands/update_task_db.py create mode 100644 src/openfecli/tests/commands/test_update_task_db.py diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py new file mode 100644 index 000000000..f749048ed --- /dev/null +++ b/src/openfecli/commands/update_task_db.py @@ -0,0 +1,106 @@ +# This code is part of OpenFE and is licensed under the MIT license. +# For details, see https://github.com/OpenFreeEnergy/openfe + +from pathlib import Path + +import click + +from openfecli import OFECommandPlugin +from openfecli.utils import write + + +def update_task_db_main( + task_db_path: Path, + max_tries: int, +): + from openfe.orchestration.exorcist_utils import update_max_tries + + """ + Parameters + ---------- + task_db_path : pathlib.Path + Path to a task.db + + max_tries: value to update "max_tries" column to, for applicable rows + + + Example + ------- + >>> openfe status task.db + + ┌─────────────────────────────┬──────────────────┬─────────────────────┬───────┬───────────┐ + │ task_id │ status │ last_modified │ tries │ max_tries │ + ├─────────────────────────────┼──────────────────┼─────────────────────┼───────┼───────────┤ + │ SetupUnit-d568ebe569b445c7… │ COMPLETED │ 2026-08-14 11:19:16 │ 1 │ 3 │ + │ SetupUnit-17dc05e0d79747e7… │ COMPLETED │ 2026-08-14 11:19:21 │ 1 │ 3 │ + │ SetupUnit-78321eda905c4c2c… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │ + │ SetupUnit-0238f65b55044b1e… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │ + │ MultiStateSimulationUnit-2… │ COMPLETED │ 2026-08-14 11:25:10 │ 1 │ 3 │ + │ MultiStateSimulationUnit-1… │ COMPLETED │ 2026-08-14 11:25:34 │ 1 │ 3 │ + │ MultiStateSimulationUnit-f… │ COMPLETED │ 2026-08-14 11:26:22 │ 1 │ 3 │ + │ MultiStateSimulationUnit-c… │ TOO_MANY_RETRIES │ 2026-08-14 11:26:24 │ 3 │ 3 │ + │ MultiStateAnalysisUnit-a72… │ COMPLETED │ 2026-08-14 11:26:51 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-e44… │ COMPLETED │ 2026-08-14 11:26:26 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-7e9… │ COMPLETED │ 2026-08-14 11:29:07 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-72c… │ BLOCKED │ NaT │ 0 │ 3 │ + └─────────────────────────────┴──────────────────┴─────────────────────┴───────┴───────────┘ + + >>> openfe update-task-db task.db --max-tries=6 + ┌─────────────────────────────┬──────────────────┬─────────────────────┬───────┬───────────┐ + │ task_id │ status │ last_modified │ tries │ max_tries │ + ├─────────────────────────────┼──────────────────┼─────────────────────┼───────┼───────────┤ + │ SetupUnit-d568ebe569b445c7… │ COMPLETED │ 2026-08-14 11:19:16 │ 1 │ 3 │ + │ SetupUnit-17dc05e0d79747e7… │ COMPLETED │ 2026-08-14 11:19:21 │ 1 │ 3 │ + │ SetupUnit-78321eda905c4c2c… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │ + │ SetupUnit-0238f65b55044b1e… │ COMPLETED │ 2026-08-14 11:19:22 │ 1 │ 3 │ + │ MultiStateSimulationUnit-2… │ COMPLETED │ 2026-08-14 11:25:10 │ 1 │ 3 │ + │ MultiStateSimulationUnit-1… │ COMPLETED │ 2026-08-14 11:25:34 │ 1 │ 3 │ + │ MultiStateSimulationUnit-f… │ COMPLETED │ 2026-08-14 11:26:22 │ 1 │ 3 │ + │ MultiStateSimulationUnit-c… │ TOO_MANY_RETRIES │ 2026-08-14 11:26:24 │ 3 │ 6 │ + │ MultiStateAnalysisUnit-a72… │ COMPLETED │ 2026-08-14 11:26:51 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-e44… │ COMPLETED │ 2026-08-14 11:26:26 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-7e9… │ COMPLETED │ 2026-08-14 11:29:07 │ 1 │ 3 │ + │ MultiStateAnalysisUnit-72c… │ BLOCKED │ NaT │ 0 │ 6 │ + └─────────────────────────────┴──────────────────┴─────────────────────┴───────┴───────────┘ + + """ + + from exorcist import TaskStatusDB + + from openfe.orchestration.exorcist_utils import update_max_tries + + task_db = TaskStatusDB.from_filename(task_db_path) + update_max_tries(task_db, max_tries) + + +@click.command("update-task-db", short_help="Update the 'max_tries' column.") +@click.option( + "--task-db", + type=click.Path( + exists=True, + readable=True, + file_okay=True, + dir_okay=False, + path_type=Path, + ), + required=True, + help="Path to a TaskDB file.", +) +@click.option( + "--max-tries", + type=click.INT, + default=False, + help="The positive integer value to assign as 'max_tries' for the updated columns.", +) +def update_task_db(task_db: Path, max_tries: int): + """ + Update the 'max_tries' column for applicable tasks. COMPLETED tasks and tasks with tries > the input 'max-tries' will not be updated. + + """ + + # TODO: add loading bar + write("Loading task db ...") + update_task_db_main(task_db_path=task_db, max_tries=max_tries) + + +PLUGIN = OFECommandPlugin(command=update_task_db_main, section="Execution", requires_ofe=(1, 13)) diff --git a/src/openfecli/tests/commands/test_update_task_db.py b/src/openfecli/tests/commands/test_update_task_db.py new file mode 100644 index 000000000..362165ee1 --- /dev/null +++ b/src/openfecli/tests/commands/test_update_task_db.py @@ -0,0 +1,40 @@ +import exorcist +import networkx as nx +import pytest +import sqlalchemy as sqla +from click.testing import CliRunner + +from openfecli.commands.update_task_db import update_task_db + +from ..utils import assert_click_success + + +@pytest.fixture +def simple_task_graph(): + task_graph = nx.DiGraph() + node_ids = ["HybridTopologySetupUnit-123", "HybridTopologySetupUnit-456"] + + for id in node_ids: + task_graph.add_node(id) + + return task_graph, node_ids + + +def test_update_task_db(simple_task_graph): + runner = CliRunner() + with runner.isolated_filesystem(): + task_graph, _ = simple_task_graph + db_path = "test.db" + db = exorcist.TaskStatusDB.from_filename(db_path) + db.add_task_network(task_graph, max_tries=2) + input_max_tries = 7 + result = runner.invoke( + update_task_db, ["--task-db", db_path, "--max-tries", str(input_max_tries)] + ) + assert_click_success(result) + + # just make sure the table is actually modified. all edge cases etc. are handled in the Python API tests + with db.engine.connect() as conn: + new_max_tries = set(conn.execute(sqla.select(db.tasks_table.c.max_tries))) + + assert new_max_tries == {(input_max_tries,)} From a77a775a2c993ec62950320d8c9bcfefe8012d1b Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 12:50:32 -0700 Subject: [PATCH 16/21] add docs --- docs/reference/cli/index.rst | 1 + docs/reference/cli/update_task_db.rst | 7 +++++++ src/openfecli/commands/update_task_db.py | 1 + 3 files changed, 9 insertions(+) create mode 100644 docs/reference/cli/update_task_db.rst diff --git a/docs/reference/cli/index.rst b/docs/reference/cli/index.rst index d2769e1db..7a2bdb714 100644 --- a/docs/reference/cli/index.rst +++ b/docs/reference/cli/index.rst @@ -21,6 +21,7 @@ Execution Commands run_task status + update_task_db quickrun Results Gathering Commands diff --git a/docs/reference/cli/update_task_db.rst b/docs/reference/cli/update_task_db.rst new file mode 100644 index 000000000..6838a791d --- /dev/null +++ b/docs/reference/cli/update_task_db.rst @@ -0,0 +1,7 @@ +.. _cli_update_task_db: + +``openfe update-task-db`` +========================= + +.. click:: openfecli.commands.update_task_db:update_task_db + :prog: openfe update-task-db \ No newline at end of file diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py index f749048ed..6fa6b5411 100644 --- a/src/openfecli/commands/update_task_db.py +++ b/src/openfecli/commands/update_task_db.py @@ -92,6 +92,7 @@ def update_task_db_main( default=False, help="The positive integer value to assign as 'max_tries' for the updated columns.", ) +# NOTE: this is named intentionally broad so that we can add "update_task_type" in a future version def update_task_db(task_db: Path, max_tries: int): """ Update the 'max_tries' column for applicable tasks. COMPLETED tasks and tasks with tries > the input 'max-tries' will not be updated. From 247fcd7831e0a8e06c201d061dfc7e7bd005105d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 12:59:05 -0700 Subject: [PATCH 17/21] make --max-tries option required (for now) --- src/openfecli/commands/update_task_db.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py index 6fa6b5411..7ffbf6886 100644 --- a/src/openfecli/commands/update_task_db.py +++ b/src/openfecli/commands/update_task_db.py @@ -89,7 +89,7 @@ def update_task_db_main( @click.option( "--max-tries", type=click.INT, - default=False, + required=True, help="The positive integer value to assign as 'max_tries' for the updated columns.", ) # NOTE: this is named intentionally broad so that we can add "update_task_type" in a future version From 71e06daa72be0e6bee6ad9c858c5c2556fb1e551 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Tue, 6 Oct 2026 18:21:21 -0700 Subject: [PATCH 18/21] fix docstring --- src/openfecli/commands/update_task_db.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py index 7ffbf6886..97de57209 100644 --- a/src/openfecli/commands/update_task_db.py +++ b/src/openfecli/commands/update_task_db.py @@ -21,7 +21,8 @@ def update_task_db_main( task_db_path : pathlib.Path Path to a task.db - max_tries: value to update "max_tries" column to, for applicable rows + max_tries: int + Value to update "max_tries" column to, for applicable rows Example From 14fd11b47f902e00348f72a9068052eec7d22421 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz <31974495+atravitz@users.noreply.github.com> Date: Wed, 7 Oct 2026 07:37:36 -0700 Subject: [PATCH 19/21] Apply batched suggestions from code review Co-authored-by: Irfan Alibay --- src/openfecli/commands/update_task_db.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py index 97de57209..07a7f7ea7 100644 --- a/src/openfecli/commands/update_task_db.py +++ b/src/openfecli/commands/update_task_db.py @@ -13,7 +13,6 @@ def update_task_db_main( task_db_path: Path, max_tries: int, ): - from openfe.orchestration.exorcist_utils import update_max_tries """ Parameters @@ -27,7 +26,7 @@ def update_task_db_main( Example ------- - >>> openfe status task.db + >>> openfe status --task-db task.db ┌─────────────────────────────┬──────────────────┬─────────────────────┬───────┬───────────┐ │ task_id │ status │ last_modified │ tries │ max_tries │ @@ -89,7 +88,7 @@ def update_task_db_main( ) @click.option( "--max-tries", - type=click.INT, + type=click.IntRange(min=1), required=True, help="The positive integer value to assign as 'max_tries' for the updated columns.", ) @@ -105,4 +104,4 @@ def update_task_db(task_db: Path, max_tries: int): update_task_db_main(task_db_path=task_db, max_tries=max_tries) -PLUGIN = OFECommandPlugin(command=update_task_db_main, section="Execution", requires_ofe=(1, 13)) +PLUGIN = OFECommandPlugin(command=update_task_db, section="Execution", requires_ofe=(1, 13)) From aec1b413420904575cdd52cad53ba05a8da19247 Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Wed, 7 Oct 2026 07:39:45 -0700 Subject: [PATCH 20/21] fix example --- src/openfecli/commands/update_task_db.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/openfecli/commands/update_task_db.py b/src/openfecli/commands/update_task_db.py index 07a7f7ea7..fc242b2c9 100644 --- a/src/openfecli/commands/update_task_db.py +++ b/src/openfecli/commands/update_task_db.py @@ -13,7 +13,6 @@ def update_task_db_main( task_db_path: Path, max_tries: int, ): - """ Parameters ---------- @@ -56,7 +55,7 @@ def update_task_db_main( │ MultiStateSimulationUnit-2… │ COMPLETED │ 2026-08-14 11:25:10 │ 1 │ 3 │ │ MultiStateSimulationUnit-1… │ COMPLETED │ 2026-08-14 11:25:34 │ 1 │ 3 │ │ MultiStateSimulationUnit-f… │ COMPLETED │ 2026-08-14 11:26:22 │ 1 │ 3 │ - │ MultiStateSimulationUnit-c… │ TOO_MANY_RETRIES │ 2026-08-14 11:26:24 │ 3 │ 6 │ + │ MultiStateSimulationUnit-c… │ AVAILABLE │ 2026-08-14 11:27:24 │ 3 │ 6 │ │ MultiStateAnalysisUnit-a72… │ COMPLETED │ 2026-08-14 11:26:51 │ 1 │ 3 │ │ MultiStateAnalysisUnit-e44… │ COMPLETED │ 2026-08-14 11:26:26 │ 1 │ 3 │ │ MultiStateAnalysisUnit-7e9… │ COMPLETED │ 2026-08-14 11:29:07 │ 1 │ 3 │ From 9620cbb6d28a5dd47b018ec76732f601d4db815d Mon Sep 17 00:00:00 2001 From: Alyssa Travitz Date: Wed, 7 Oct 2026 07:50:45 -0700 Subject: [PATCH 21/21] update type checking --- src/openfe/orchestration/exorcist_utils.py | 2 +- src/openfe/tests/orchestration/test_exorcist_utils.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/openfe/orchestration/exorcist_utils.py b/src/openfe/orchestration/exorcist_utils.py index 5a8232c14..42677b62f 100644 --- a/src/openfe/orchestration/exorcist_utils.py +++ b/src/openfe/orchestration/exorcist_utils.py @@ -178,7 +178,7 @@ def update_max_tries(task_db: exorcist.TaskStatusDB, max_tries: Annotated[int, G from exorcist.models import TaskStatus # TODO: select a single task_id? - if not isinstance(max_tries, int) or max_tries <= 0: + if type(max_tries) is not int or max_tries <= 0: raise ValueError("`max_tries` must be a positive integer.") values = {"max_tries": max_tries, "last_modified": datetime.now()} diff --git a/src/openfe/tests/orchestration/test_exorcist_utils.py b/src/openfe/tests/orchestration/test_exorcist_utils.py index b16c5b934..91e1f807f 100644 --- a/src/openfe/tests/orchestration/test_exorcist_utils.py +++ b/src/openfe/tests/orchestration/test_exorcist_utils.py @@ -348,7 +348,7 @@ def test_update_max_tries(fresh_db): } -@pytest.mark.parametrize("bad_value", ["1", -2, 3.0, 0]) +@pytest.mark.parametrize("bad_value", ["1", -2, 3.0, 0, True]) def test_update_max_tries_invalid_val(fresh_db, bad_value): with pytest.raises(ValueError, match="must be a positive integer"): update_max_tries(task_db=fresh_db, max_tries=bad_value)