pyfebiopt.monitoring.registry
=============================

.. py:module:: pyfebiopt.monitoring.registry

.. autoapi-nested-parse::

   Manage the JSONL-backed registry of optimization runs.



Exceptions
----------

.. autoapisummary::

   pyfebiopt.monitoring.registry.ActiveRunDeletionError


Classes
-------

.. autoapisummary::

   pyfebiopt.monitoring.registry.RunRegistry


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

.. py:exception:: ActiveRunDeletionError(run_id: str)

   Bases: :py:obj:`RuntimeError`


   Raised when attempting to delete an optimization run that is still active.

   Describe the active run that blocked deletion.

   :param run_id: Identifier of the active run.


   .. py:attribute:: run_id


.. py:class:: RunRegistry(db_path: pathlib.Path, *, max_history: int | None = None)

   Thread-safe registry storing optimization run snapshots backed by JSONL.

   Initialize the registry with the backing database path.


   .. py:attribute:: db_path


   .. py:method:: list_runs() -> list[pyfebiopt.monitoring.runstate.OptimizationRun]

      Return all tracked optimization runs.



   .. py:method:: get_run(run_id: str) -> pyfebiopt.monitoring.runstate.OptimizationRun | None

      Return the run snapshot for the given identifier.



   .. py:method:: apply_event(run_id: str, event: str, payload: dict[str, object], ts: float) -> None

      Incorporate an incoming event into the relevant run.



   .. py:method:: refresh() -> None

      Reload the registry contents from disk.



   .. py:method:: delete_run(run_id: str, *, force: bool = False) -> bool

      Remove a run if it is safe to delete or forcefully requested.

      :returns: True if deleted, False otherwise.
      :rtype: bool



   .. py:method:: clear(*, force: bool = False) -> list[str]

      Drop runs and list those kept either due to activity or force=False.

      :returns: Run ids that were not removed.
      :rtype: list[str]