leaf-framework 0.1.0__py3-none-any.whl

leaf/adapters/core_adapters/continuous_experiment_adapter.py

@@ -0,0 +1,100 @@
+from typing import Optional, Any
+
+from leaf.modules.process_modules.continous_module import ContinousProcess
+from leaf.modules.process_modules.process_module import ProcessModule
+from leaf.modules.phase_modules.start import StartPhase
+from leaf.modules.phase_modules.stop import StopPhase
+from leaf.modules.phase_modules.measure import MeasurePhase
+from leaf.modules.phase_modules.initialisation import InitialisationPhase
+
+from leaf_register.metadata import MetadataManager
+from leaf.error_handler.error_holder import ErrorHolder
+
+from leaf.modules.input_modules.event_watcher import EventWatcher
+from leaf.modules.input_modules.external_event_watcher import ExternalEventWatcher
+from leaf.modules.output_modules.output_module import OutputModule
+
+from leaf.adapters.equipment_adapter import EquipmentAdapter
+from leaf.adapters.equipment_adapter import AbstractInterpreter
+
+
+class ContinuousExperimentAdapter(EquipmentAdapter):
+    """
+    Adapter that implements a continuous process workflow for equipment 
+    without defined experiment start/stop boundaries.
+    
+    It runs the measurement process continuously and wraps start/stop/details
+    in a parallel control process.
+    """
+
+    def __init__(
+        self,
+        instance_data: dict[str, Any],
+        watcher: EventWatcher,
+        output: OutputModule,
+        interpreter: AbstractInterpreter,
+        maximum_message_size: Optional[int] = 1,
+        error_holder: Optional[ErrorHolder] = None,
+        metadata_manager: Optional[MetadataManager] = None,
+        experiment_timeout: Optional[int] = None,
+        external_watcher: Optional[ExternalEventWatcher] = None,
+    ):
+        """
+        Initialise the ContinuousExperimentAdapter.
+
+        Args:
+            instance_data (dict): Configuration and metadata for this adapter.
+            watcher (EventWatcher): Input module that monitors raw data/events.
+            output (OutputModule): Output module to transmit processed data.
+            interpreter (AbstractInterpreter): Parses and transforms raw inputs.
+            maximum_message_size (Optional[int]): Limit for batching measurement messages.
+            error_holder (Optional[ErrorHolder]): Shared error collector.
+            metadata_manager (Optional[MetadataManager]): Metadata manager instance.
+            experiment_timeout (Optional[int]): Optional timeout between measurements.
+            external_watcher (Optional[ExternalEventWatcher]): Optional external input module.
+        """
+        # Initialize phases
+        start_p = StartPhase(metadata_manager)
+        stop_p = StopPhase(metadata_manager)
+        measure_p = MeasurePhase(metadata_manager, maximum_message_size=maximum_message_size)
+        details_p = InitialisationPhase(metadata_manager)
+
+        # Set up continuous and control processes
+        measurement_process = ContinousProcess(
+            output,
+            measure_p,
+            metadata_manager=metadata_manager,
+            error_holder=error_holder
+        )
+
+        self._control_process = ProcessModule(
+            output,
+            [start_p, stop_p, details_p],
+            metadata_manager=metadata_manager,
+            error_holder=error_holder
+        )
+
+        processes = [measurement_process, self._control_process]
+
+        super().__init__(
+            instance_data,
+            watcher,
+            output,
+            processes,
+            interpreter,
+            metadata_manager=metadata_manager,
+            error_holder=error_holder,
+            experiment_timeout=experiment_timeout,
+            external_watcher=external_watcher
+        )
+
+    def start(self) -> None:
+        """
+        Trigger the start phase and launch the adapter loop.
+
+        Injects a synthetic start message via the control process
+        to initialise any start-specific logic or output.
+        """
+        start_topic = self._metadata_manager.experiment.start
+        self._control_process.process_input(start_topic, {})
+        super().start()

leaf/adapters/core_adapters/discrete_experiment_adapter.py

@@ -0,0 +1,74 @@
+from typing import Optional, Any
+
+from leaf.modules.process_modules.discrete_module import DiscreteProcess
+from leaf.modules.phase_modules.start import StartPhase
+from leaf.modules.phase_modules.stop import StopPhase
+from leaf.modules.phase_modules.measure import MeasurePhase
+from leaf.modules.phase_modules.initialisation import InitialisationPhase
+
+from leaf_register.metadata import MetadataManager
+from leaf.error_handler.error_holder import ErrorHolder
+
+from leaf.modules.input_modules.event_watcher import EventWatcher
+from leaf.modules.input_modules.external_event_watcher import ExternalEventWatcher
+from leaf.modules.output_modules.output_module import OutputModule
+
+from leaf.adapters.equipment_adapter import EquipmentAdapter, AbstractInterpreter
+
+
+class DiscreteExperimentAdapter(EquipmentAdapter):
+    """
+    Adapter that implements a discrete start-stop process workflow.
+
+    It sets up individual phases for start, stop, measure, and details.
+    The process is triggered by incoming events, not continuous monitoring.
+    """
+
+    def __init__(
+        self,
+        instance_data: dict[str, Any],
+        watcher: EventWatcher,
+        output: OutputModule,
+        interpreter: AbstractInterpreter,
+        maximum_message_size: Optional[int] = 1,
+        error_holder: Optional[ErrorHolder] = None,
+        metadata_manager: Optional[MetadataManager] = None,
+        experiment_timeout: Optional[int] = None,
+        external_watcher: Optional[ExternalEventWatcher] = None,
+    ):
+        """
+        Initialise the DiscreteExperimentAdapter.
+
+        Args:
+            instance_data (dict): Configuration and instance-level metadata.
+            watcher (EventWatcher): Monitors input events to trigger phase execution.
+            output (OutputModule): Module to transmit processed data externally.
+            interpreter (AbstractInterpreter): Translates raw data into structured output.
+            maximum_message_size (Optional[int]): Max batch size for messages in MeasurePhase.
+            error_holder (Optional[ErrorHolder]): Shared error container.
+            metadata_manager (Optional[MetadataManager]): Optional metadata manager.
+            experiment_timeout (Optional[int]): Max time allowed between measurements.
+            external_watcher (Optional[ExternalEventWatcher]): Input for out-of-band events (optional).
+        """
+        # Initialize phase modules
+        start_p = StartPhase(metadata_manager)
+        stop_p = StopPhase(metadata_manager)
+        measure_p = MeasurePhase(metadata_manager, 
+                                 maximum_message_size=maximum_message_size)
+        details_p = InitialisationPhase(metadata_manager)
+
+        # Combine into a discrete process
+        phases = [start_p, measure_p, stop_p, details_p]
+        processes = [DiscreteProcess(output, phases)]
+
+        super().__init__(
+            instance_data,
+            watcher,
+            output,
+            processes,
+            interpreter,
+            metadata_manager=metadata_manager,
+            error_holder=error_holder,
+            experiment_timeout=experiment_timeout,
+            external_watcher=external_watcher
+        )

leaf/adapters/core_adapters/upload_adapter.py

@@ -0,0 +1,80 @@
+from typing import Optional, Any
+
+from leaf.modules.process_modules.upload_module import UploadProcess
+from leaf.modules.phase_modules.start import StartPhase
+from leaf.modules.phase_modules.stop import StopPhase
+from leaf.modules.phase_modules.measure import MeasurePhase
+from leaf.modules.phase_modules.initialisation import InitialisationPhase
+
+from leaf.modules.input_modules.file_watcher import FileWatcher
+from leaf.modules.input_modules.external_event_watcher import ExternalEventWatcher
+from leaf.modules.output_modules.output_module import OutputModule
+
+from leaf_register.metadata import MetadataManager
+from leaf.error_handler.error_holder import ErrorHolder
+
+from leaf.adapters.equipment_adapter import EquipmentAdapter
+from leaf.adapters.equipment_adapter import AbstractInterpreter
+
+
+class UploadAdapter(EquipmentAdapter):
+    """
+    Adapter for equipment that stores data to a file all at once,
+    or where data must be manually uploaded into a watched directory.
+
+    This adapter uses a file watcher to detect new uploads and processes
+    the data through an artificial start-measure-stop sequence.
+    """
+
+    def __init__(
+        self,
+        instance_data: dict[str, Any],
+        output: OutputModule,
+        interpreter: AbstractInterpreter,
+        watch_dir: Optional[str] = None,
+        maximum_message_size: Optional[int] = 1,
+        error_holder: Optional[ErrorHolder] = None,
+        metadata_manager: Optional[MetadataManager] = None,
+        experiment_timeout: Optional[int] = None,
+        external_watcher: Optional[ExternalEventWatcher] = None,
+    ):
+        """
+        Initialise the UploadAdapter.
+
+        Args:
+            instance_data (dict): Instance-level configuration and metadata.
+            output (OutputModule): The output module used to transmit parsed data.
+            interpreter (AbstractInterpreter): Parses and translates raw data.
+            watch_dir (Optional[str]): Directory path to monitor for uploaded files.
+            maximum_message_size (Optional[int]): Max number of messages per transmission.
+            error_holder (Optional[ErrorHolder]): Error tracking object.
+            metadata_manager (Optional[MetadataManager]): Optional metadata manager.
+            experiment_timeout (Optional[int]): Timeout between measurements (not used here).
+            external_watcher (Optional[ExternalEventWatcher]): Optional listener for external inputs.
+        """
+        # Input module: watches a local directory
+        watcher = FileWatcher(watch_dir, metadata_manager, 
+                              error_holder=error_holder)
+
+        # Initialize discrete phases
+        start_p = StartPhase(metadata_manager)
+        stop_p = StopPhase(metadata_manager)
+        measure_p = MeasurePhase(metadata_manager, 
+                                 maximum_message_size=maximum_message_size)
+        details_p = InitialisationPhase(metadata_manager)
+
+        # Combine phases into a process
+        phases = [start_p, measure_p, stop_p, details_p]
+        processes = [UploadProcess(output, phases)]
+
+        super().__init__(
+            instance_data,
+            watcher,
+            output,
+            processes,
+            interpreter,
+            metadata_manager=metadata_manager,
+            error_holder=error_holder,
+            experiment_timeout=experiment_timeout,
+            external_watcher=external_watcher,
+        )

leaf/adapters/equipment_adapter.py

@@ -0,0 +1,355 @@
+import logging
+import time
+from abc import ABC, abstractmethod
+from threading import Event
+from typing import Any, Optional
+
+from leaf_register.metadata import MetadataManager
+
+from leaf.error_handler import exceptions
+from leaf.error_handler.exceptions import LEAFError
+from leaf.error_handler.error_holder import ErrorHolder
+
+from leaf.modules.input_modules.event_watcher import EventWatcher
+from leaf.modules.input_modules.external_event_watcher import ExternalEventWatcher
+from leaf.modules.output_modules.output_module import OutputModule
+from leaf.utility.logger.logger_utils import get_logger
+from leaf.modules.process_modules.process_module import ProcessModule
+from leaf.modules.process_modules.external_event_process import ExternalEventProcess
+
+
+class AbstractInterpreter(ABC):
+    """
+    Abstract base class for interpreters.
+
+    Interpreters are responsible for transforming raw input data into a
+    structured format suitable for processing and output. Each adapter
+    uses one interpreter instance to convert metadata and measurement
+    input into a standardised structure.
+    """
+
+    def __init__(self, error_holder: Optional[ErrorHolder] = None):
+        """
+        Initialise the interpreter.
+
+        Args:
+            error_holder (Optional[ErrorHolder]): Optional holder for logging
+                                                  or deferring error handling.
+        """
+        self.id: str = "undefined"
+        self.TIMESTAMP_KEY: str = "timestamp"
+        self.EXPERIMENT_ID_KEY: str = "experiment_id"
+        self.MEASUREMENT_HEADING_KEY: str = "measurement_types"
+        self._error_holder = error_holder
+        self._last_measurement = None
+        self._is_running = False
+
+    def set_error_holder(self, error_holder: Optional[ErrorHolder]) -> None:
+        """Assign an ErrorHolder instance to the interpreter."""
+        self._error_holder = error_holder
+
+    @abstractmethod
+    def metadata(self, data: Any) -> dict[str, Any]:
+        """
+        Parse metadata input and return it in structured form.
+
+        Args:
+            data (Any): Raw metadata from input module.
+
+        Returns:
+            dict[str, Any]: Parsed metadata dictionary.
+        """
+        return {self.TIMESTAMP_KEY: time.time()}
+
+    @abstractmethod
+    def measurement(self, data: Any) -> Any:
+        """
+        Parse a measurement payload.
+
+        Args:
+            data (Any): Raw measurement data.
+
+        Returns:
+            Any: Parsed or transformed measurement data.
+        """
+        self._last_measurement = time.time()
+        return data
+
+    def get_last_measurement_time(self) -> Optional[float]:
+        """Return the timestamp of the last successful measurement."""
+        return self._last_measurement
+
+    def experiment_stop(self, data: Any = None) -> Any:
+        """
+        Clear internal state for stopping experiment tracking.
+
+        Args:
+            data (Any): Optional additional data for stop logic.
+
+        Returns:
+            Any: Forwarded or cleaned-up stop payload.
+        """
+        self._last_measurement = None
+        return data
+
+    def _handle_exception(self, exception: LEAFError) -> None:
+        """
+        Route exceptions to the error handler or raise directly.
+
+        Args:
+            exception (LEAFError): Exception to handle or raise.
+        """
+        if self._error_holder is not None:
+            self._error_holder.add_error(exception)
+        else:
+            raise exception
+
+
+class EquipmentAdapter(ABC):
+    """
+    Base class for all equipment adapters.
+
+    Handles coordination of:
+      - data input (via watchers),
+      - processing (via processes),
+      - output (via output modules),
+      - and error handling.
+
+    Subclasses implement concrete workflows (e.g., continuous, discrete).
+    """
+
+    def __init__(
+        self,
+        instance_data: dict[str, Any],
+        watcher: EventWatcher,
+        output: OutputModule,
+        process_adapters: ProcessModule | list[ProcessModule],
+        interpreter: AbstractInterpreter,
+        metadata_manager: Optional[MetadataManager] = None,
+        error_holder: Optional[ErrorHolder] = None,
+        experiment_timeout: Optional[int] = None,
+        external_watcher: Optional[ExternalEventWatcher] = None
+    ):
+        """
+        Initialise the equipment adapter.
+
+        Args:
+            instance_data (dict): Configuration and metadata for the adapter instance.
+            watcher (EventWatcher): Input module responsible for receiving input events.
+            output (OutputModule): Output module to send processed data.
+            process_adapters (ProcessModule | list): Phase processors to handle logic.
+            interpreter (AbstractInterpreter): Logic for transforming raw input to usable data.
+            metadata_manager (Optional[MetadataManager]): Metadata coordinator.
+            error_holder (Optional[ErrorHolder]): Centralised error recording and dispatch.
+            experiment_timeout (Optional[int]): Optional timeout in seconds for experiment stall detection.
+            external_watcher (Optional[ExternalEventWatcher]): Optional secondary input for external events.
+        """
+        self._output = output
+        self._error_holder = error_holder
+
+        if not isinstance(process_adapters, (list, tuple, set)):
+            process_adapters = [process_adapters]
+        self._processes: list[ProcessModule] = list(process_adapters)
+        for p in self._processes:
+            p.set_error_holder(error_holder)
+
+        self._interpreter = interpreter
+        for p in self._processes:
+            p.set_interpreter(interpreter)
+        interpreter.set_error_holder(error_holder)
+
+        self._metadata_manager = metadata_manager or MetadataManager()
+        self._metadata_manager.add_instance_data(instance_data)
+
+        self._watcher = watcher
+        for p in self._processes:
+            self._watcher.add_callback(p.process_input)
+            p.set_metadata_manager(self._metadata_manager)
+        self._watcher.set_error_holder(error_holder)
+
+        ins_id = self._metadata_manager.get_instance_id()
+        self._logger = get_logger(
+            name=f"{__name__}.{ins_id}",
+            log_file=f"{ins_id}.log",
+            error_log_file=f"{ins_id}_error.log",
+            log_level=logging.INFO,
+        )
+
+        self._stop_event = Event()
+        self._stop_event.set()
+        self._experiment_timeout = experiment_timeout
+
+        self._external_watcher = external_watcher
+        if self._external_watcher is not None:
+            self._external_watcher.set_metadata_manager(self._metadata_manager)
+            self._external_process = ExternalEventProcess(
+                output, self._metadata_manager, self._error_holder
+            )
+            self._external_process.set_error_holder(self._error_holder)
+            self._external_process.set_interpreter(interpreter)
+            self._external_watcher.add_callback(self._external_process.process_input)
+
+    def is_running(self) -> bool:
+        """
+        Check if the adapter is actively running.
+
+        Returns:
+            bool: True if input/output are active and adapter is not stopped.
+        """
+        return (self._watcher.is_running() and 
+                self._output.is_connected() and 
+                not self._stop_event.is_set())
+
+    def start(self) -> None:
+        """
+        Begin running the adapter.
+
+        Starts input watchers, begins monitoring for errors,
+        and invokes appropriate error-driven control logic.
+        """
+        if not self._metadata_manager.is_valid():
+            ins_id = self._metadata_manager.get_instance_id()
+            missing_data = self._metadata_manager.get_missing_metadata()
+            excp = exceptions.AdapterLogicError(
+                f"{ins_id} is missing data: {missing_data}",
+                severity=exceptions.SeverityLevel.CRITICAL,
+            )
+            self._logger.error("Critical error, shutting down adapter", exc_info=excp)
+            self._handle_exception(excp)
+            return self.stop()
+
+        try:
+            self._watcher.start()
+            if self._external_watcher:
+                self._external_watcher.start()
+
+            self._stop_event.clear()
+            # Expose adapter on all channels.
+            for process in self._processes:
+                process.process_input(self._metadata_manager.details,
+                                      self._metadata_manager.get_data())
+            while not self._stop_event.is_set():
+                time.sleep(1)
+                if not self._error_holder:
+                    continue
+
+                cur_errors = self._error_holder.get_unseen_errors()
+                self.transmit_errors(cur_errors)
+
+                for error, _ in cur_errors:
+                    if error.severity == exceptions.SeverityLevel.CRITICAL:
+                        self._logger.error("Critical error, stopping adapter", exc_info=error)
+                        self._stop_event.set()
+                        self.stop()
+
+                    elif error.severity == exceptions.SeverityLevel.ERROR:
+                        self._logger.error("Error, restarting adapter", exc_info=error)
+                        self.stop()
+                        return self.start()
+
+                    elif error.severity == exceptions.SeverityLevel.WARNING:
+                        self._handle_warning(error)
+
+                    elif error.severity == exceptions.SeverityLevel.INFO:
+                        self._logger.info("Info: %s", error, exc_info=error)
+
+                if self._experiment_timeout:
+                    lmt = self._interpreter.get_last_measurement_time()
+                    if lmt and (time.time() - lmt > self._experiment_timeout):
+                        self._handle_exception(exceptions.HardwareStalledError("Experiment timeout"))
+
+        except KeyboardInterrupt:
+            self._logger.info("Keyboard interrupt received.")
+            self._stop_event.set()
+
+        except Exception as e:
+            self._logger.error(f"Unexpected error: {e}", exc_info=True)
+            self._stop_event.set()
+
+        finally:
+            self._logger.info("Stopping adapter.")
+            self._watcher.stop()
+            self.stop()
+
+    def _handle_warning(self, error: LEAFError) -> None:
+        """
+        Handle warnings by attempting recovery actions (restart input, etc).
+
+        Args:
+            error (LEAFError): The warning-level exception to evaluate.
+        """
+        if isinstance(error, exceptions.InputError):
+            self._logger.warning("Input error, restarting watcher", exc_info=error)
+            if self._watcher.is_running():
+                self._watcher.stop()
+            self._watcher.start()
+
+        elif isinstance(error, exceptions.HardwareStalledError):
+            self._logger.warning("Hardware stalled, stopping processes", exc_info=error)
+            for p in self._processes:
+                p.stop()
+            self._interpreter.experiment_stop()
+            if self._watcher.is_running():
+                self._watcher.stop()
+            self._watcher.start()
+
+        elif isinstance(error, exceptions.ClientUnreachableError):
+            self._logger.warning("Client unreachable", exc_info=error)
+            if error.client:
+                error.client.disconnect()
+                time.sleep(1)
+                error.client.connect()
+
+    def stop(self) -> None:
+        """
+        Stop the adapter and all associated processes and watchers.
+        """
+        self._stop_event.set()
+        if self._watcher.is_running():
+            self._watcher.stop()
+
+        for p in self._processes:
+            p.stop()
+
+        if self._external_watcher:
+            self._external_watcher.stop()
+
+    def withdraw(self) -> None:
+        """
+        Withdraw the adapter from being visible, but leave it running.
+
+        Calls withdraw on each active process.
+        """
+        for process in self._processes:
+            process.withdraw()
+
+    def transmit_errors(self, errors: list[tuple[LEAFError, str]] = None) -> None:
+        """
+        Push errors to the output module(s) via each process.
+
+        Args:
+            errors (list[LEAFError], optional): A list of errors to transmit.
+        """
+        errors = errors or self._error_holder.get_unseen_errors()
+        for error, _ in errors:
+            if not isinstance(error, LEAFError):
+                self._logger.error("Non-LEAF error added to error holder", 
+                                   exc_info=error)
+                return self.stop()
+
+            error_json = error.to_json()
+            for process in self._processes:
+                process.transmit_error(error_json)
+                time.sleep(0.1)
+
+    def _handle_exception(self, exception: Exception) -> None:
+        """
+        Record or raise an exception.
+
+        Args:
+            exception (Exception): Exception to handle.
+        """
+        if self._error_holder:
+            self._error_holder.add_error(exception)
+        else:
+            raise exception

leaf/error_handler/error_holder.py

@@ -0,0 +1,52 @@
+import threading
+import traceback
+from typing import Optional, List, Tuple
+from leaf.error_handler.exceptions import LEAFError
+class ErrorHolder:
+    """
+    A simplified error manager that stores errors once 
+    and lets you retrieve (and clear) all of them at once.
+    """
+
+    def __init__(self, adapter_id: Optional[str] = None):
+        """
+        Initialize the ErrorHolder instance.
+        
+        Args:
+            adapter_id (Optional[str]): Optional identifier 
+                                        for the adapter.
+        """
+        self._errors: List[dict] = []
+        self.lock = threading.Lock()
+        self._adapter_id = adapter_id
+
+    def add_error(self, exc: LEAFError) -> None:
+        """
+        Add an error entry with its traceback.
+
+        Args:
+            exc (LEAFError): The exception to add.
+        """
+        if not isinstance(exc, LEAFError):
+            raise TypeError("ErrorHolder only accepts LEAFError exceptions.")
+        with self.lock:
+            tb = traceback.format_exc()
+            error_entry = {
+                "error": exc,
+                "traceback": tb
+            }
+            self._errors.append(error_entry)
+
+    def get_unseen_errors(self) -> List[Tuple[LEAFError, str]]:
+        """
+        Retrieve all stored errors and clear the list.
+
+        Returns:
+            List[Tuple[Exception, str]]: 
+                A list of (exception, traceback) tuples.
+        """
+        with self.lock:
+            all_errors = [(err["error"], err["traceback"]) 
+                          for err in self._errors]
+            self._errors.clear()
+            return all_errors