motoko.task_manager
===================

.. py:module:: motoko.task_manager


Classes
-------

.. autoapisummary::

   motoko.task_manager.RunList
   motoko.task_manager.TaskSelectionEval
   motoko.task_manager.TaskSelection
   motoko.task_manager.TaskManager


Module Contents
---------------

.. py:class:: RunList(runs: list[tuple[BlackDynamite.run_zeo.RunZEO, BlackDynamite.job.JobZEO]])

   A ``RunList`` object represent a list of runs that can be `await`-ed
   until the state of all runs becomes ``FINISHED``. Its usage is for within
   asynchronous routines with a sequence like:

   .. code-block:: python

       some_runs = [...]  # list of run objects
       finished_runs = await RunList(some_runs)

   Some runs are typically produced by interaction with a workflow:

   .. code-block:: python

       created = await task_manager.createTask(param1=value1, param2=value2)


   .. py:attribute:: runs


.. py:class:: TaskSelectionEval(func: collections.abc.Callable[[], Any])

   .. py:attribute:: func


.. py:class:: TaskSelection(constraints: list[str], selector: Any, base: Any, study: str)

   Lazy BlackDynamite run selection.

   ``TaskManager.select`` returns this object instead of just a list. It can
   be used as a normal iterable/list-like value, called explicitly, converted
   to ``bool``, or awaited. Awaiting polls the underlying BlackDynamite
   selection until at least one run matches.


   .. py:attribute:: matching_condition
      :type:  collections.abc.Callable[Ellipsis, bool] | None
      :value: None



   .. py:attribute:: constraints


   .. py:attribute:: base


   .. py:attribute:: selector


   .. py:attribute:: study


   .. py:method:: exec() -> list[BlackDynamite.run_zeo.RunZEO]


   .. py:method:: all(*args: Any) -> TaskSelectionEval

      Wait until all selected runs satisfy one set of constraints.



.. py:class:: TaskManager(workflow: motoko.workflow.Workflow, study: str)

   Manages one BlackDynamite study inside a Motoko workflow.

   A task manager for a BD study named ``solve`` uses the directory
   ``<workflow-dir>/solve``. This directory contains the study's
   configuration file ``bd.yaml``, the Python script ``doIt.py`` that contains
   the code to be executed, and ``launch.sh`` that executes ``doIt.py``.

   The task manager deliberately keeps BlackDynamite concepts visible: jobs
   describe input parameter combinations, runs describe the execution (e.g.
   the used software), and run state is the coordination signal used by the
   workflow.

   Lifecycle within a workflow:

   1. Construction reads the task-manager entry from ``motoko.yaml`` and the
      study's ``bd.yaml``. The ``job_space`` and ``run_params`` entries in
      ``bd.yaml`` become defaults for every task created by this manager.
   2. ``bd_study.create_bd_study`` resets and initializes the underlying
      BlackDynamite database and starts its ZEO server.
   3. ``base`` lazily connects to the BlackDynamite ``Base`` for the study.
      The connection is cached so repeated selections and task creation share
      the same base object.
   4. ``createTask`` creates new runs/jobs.

   Run execution is handled externally by the BlackDynamite launcher daemons,
   which Motoko starts when the workflow is created.


   .. py:attribute:: workflow


   .. py:attribute:: study


   .. py:attribute:: config


   .. py:attribute:: selector
      :value: None



   .. py:method:: connect() -> BlackDynamite.base_zeo.BaseZEO


   .. py:property:: base
      :type: BlackDynamite.base_zeo.BaseZEO


      Return a cached BlackDynamite ``Base`` connection for this study.


   .. py:property:: bd_config
      :type: dict[str, Any]


      Load the study-local ``bd.yaml`` schema and defaults.


   .. py:property:: study_dir
      :type: str



   .. py:property:: bd_dir
      :type: str



   .. py:method:: createTask(run_params: dict[str, Any] | None = None, commit: bool = False, **kwargs: Any) -> RunList

      Create BlackDynamite runs for the current workflow run.

      The current ``workflow.run_name`` is mandatory. It is copied onto each
      run so selections can isolate one logical workflow execution from old
      runs in the same study. Motoko also records the Python caller name in
      the run's ``event_name`` field, making it easier to inspect which
      workflow action created each run.

      :param run_params: Optional run parameters stored on every created run.
                         They are merged with the default ``run_params`` from
                         ``bd.yaml``.
      :param commit: ``True`` immediately forwards to the underlying
                     BlackDynamite create/select calls to update the database.
                     ``False`` leaves transaction handling to Motoko's transaction
                     wrapper.
      :param \*\*kwargs: Job parameters. They are merged with the manager's
                         default ``job_space`` from ``bd.yaml`` and expanded through
                         BlackDynamite's parameter-space machinery. List-valued
                         parameters can create several jobs/runs.

      :returns: A ``task_manager.RunList`` object containing the created
                ``(run, job)`` pairs. The returned object is awaitable; if
                createTask is called with the ``await`` decorator, it waits until
                all runs reach the ``FINISHED`` state.

      :raises RuntimeError: If ``workflow.run_name`` is not set.



   .. py:method:: select(constraints: str | list[str] | None = None) -> TaskSelection

      Return runs matching BlackDynamite constraints as a
      ``TaskSelection`` object.

      The ``constraints`` may be ``None``, a single constraint string, or a
      list of constraint strings. When ``workflow.run_name`` is set, Motoko
      appends ``run_name = <value>`` so orchestration logic only handles runs
      belonging to the current workflow execution.