algomancy-scenario 0.3.13__py3-none-any.whl

algomancy_scenario/__init__.py

@@ -0,0 +1,37 @@
+from algomancy_utils.baseparameterset import (
+    BaseParameterSet,
+    IntegerParameter,
+    StringParameter,
+    EnumParameter,
+    FloatParameter,
+    BooleanParameter,
+)
+from .algorithmfactory import AlgorithmFactory
+from .keyperformanceindicator import KpiError, BaseKPI, BASE_KPI, ImprovementDirection
+from .result import BaseScenarioResult, BASE_RESULT_BOUND, ScenarioResult
+from .scenario import Scenario, ScenarioStatus
+from .scenariomanager import ScenarioManager
+from .basealgorithm import ALGORITHM, BaseAlgorithm
+
+
+__all__ = [
+    "BaseParameterSet",
+    "IntegerParameter",
+    "StringParameter",
+    "EnumParameter",
+    "FloatParameter",
+    "BooleanParameter",
+    "BaseAlgorithm",
+    "ALGORITHM",
+    "AlgorithmFactory",
+    "ScenarioStatus",
+    "ImprovementDirection",
+    "KpiError",
+    "BaseKPI",
+    "BASE_KPI",
+    "BaseScenarioResult",
+    "BASE_RESULT_BOUND",
+    "ScenarioResult",
+    "Scenario",
+    "ScenarioManager",
+]

algomancy_scenario/algorithmfactory.py

@@ -0,0 +1,53 @@
+from algomancy_utils.baseparameterset import EmptyParameters
+from typing import Dict, Any, List, Type, Generic
+
+from algomancy_utils.logger import Logger
+from .basealgorithm import ALGORITHM
+
+
+class AlgorithmFactory(Generic[ALGORITHM]):
+    """
+    Creates algorithm objects
+    """
+
+    def __init__(self, templates: Dict[str, Type[ALGORITHM]], logger: Logger = None):
+        self._templates: Dict[str, Type[ALGORITHM]] = templates
+        self._logger = logger
+
+    @property
+    def available_algorithms(self) -> List[str]:
+        return [str(key) for key in self._templates.keys()]
+
+    @property
+    def templates(self) -> Dict[str, Type[ALGORITHM]]:
+        return self._templates
+
+    def create(self, input_name: str, input_params: Dict[str, Any]) -> ALGORITHM:
+        """
+
+        :param input_name:
+        :param input_params:
+        :raises AssertionError: Either algorithm template is not found or parameter validation fails.
+        :return:
+        """
+        template: Type[ALGORITHM] = (
+            self._templates[input_name] if input_name in self._templates else None
+        )
+        assert template, f"Algorithm template '{input_name}' not found."
+
+        algo_params = template.initialize_parameters()
+        algo_params.set_validated_values(input_params)
+
+        return template(algo_params)
+
+    def get_parameters(self, algo_name: str):
+        template: Type[ALGORITHM] = (
+            self._templates[algo_name] if algo_name in self._templates else None
+        )
+        assert template, f"Algorithm template '{algo_name}' not found."
+
+        algo_params = template.initialize_parameters()
+
+        data_params = EmptyParameters()
+
+        return algo_params, data_params

algomancy_scenario/basealgorithm.py

@@ -0,0 +1,74 @@
+from abc import ABC, abstractmethod
+from typing import TypeVar
+
+from algomancy_data import BASE_DATA_BOUND
+from .result import BASE_RESULT_BOUND
+from algomancy_utils.baseparameterset import BASE_PARAMS_BOUND
+
+
+class BaseAlgorithm(ABC):
+    def __init__(self, name: str, params: BASE_PARAMS_BOUND):
+        self._name: str = name
+        self.description = str(params.serialize())
+        self._params: BASE_PARAMS_BOUND = params
+        self._progress: float = 0
+
+    def __str__(self):
+        return f"{self.name} [{self._progress:.0f}%]: {self.description}"
+
+    @property
+    def params(self):
+        return self._params
+
+    @property
+    def get_progress(self) -> float:
+        return self._progress
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    def set_progress(self, progress: float):
+        assert 0 <= progress <= 100, "progress must be between 0 and 100"
+        self._progress = progress
+
+    def is_complete(self):
+        return self._progress == 100
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "parameters": self._params.serialize(),
+        }
+
+    def healthcheck(self) -> bool:
+        return True
+
+    @staticmethod
+    @abstractmethod
+    def initialize_parameters() -> BASE_PARAMS_BOUND:
+        """
+        Initializes parameters for the derived Algorithm, which is necessary
+        for the GUI logic. It should simply return a default object of the
+        associated AlgorithmParameters class.
+
+        Example:
+            @staticmethod
+            def initialize_parameters() -> ExampleAlgorithmParams:
+                return ExampleAlgorithmParams()
+
+        Raises:
+            NotImplementedError: If the method is not overridden.
+
+        Returns:
+            BASE_PARAMS_BOUND: The initialized set of parameters, derived
+                               from the BaseAlgorithmParameters class.
+        """
+        raise NotImplementedError("Abstract method")
+
+    @abstractmethod
+    def run(self, data: BASE_DATA_BOUND) -> BASE_RESULT_BOUND:
+        raise NotImplementedError("Abstract method")
+
+
+ALGORITHM: TypeVar = TypeVar("ALGORITHM", bound=BaseAlgorithm)

algomancy_scenario/core_configuration.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import os
+from typing import Any, Dict, List, Type
+
+from algomancy_data import InputFileConfiguration, BASE_DATA_BOUND
+from algomancy_scenario import AlgorithmFactory, ALGORITHM, BASE_KPI
+
+
+class CoreConfiguration:
+    """
+    Core configuration shared by GUI and CLI.
+
+    Contains only fields that are not GUI- or CLI-specific.
+    Validation is executed on construction.
+    """
+
+    def __init__(
+        self,
+        # === path specifications ===
+        data_path: str = "data",
+        # === data manager configuration ===
+        has_persistent_state: bool = False,
+        save_type: str | None = "json",
+        data_object_type: type[BASE_DATA_BOUND] | None = None,
+        # === scenario manager configuration ===
+        etl_factory: Any | None = None,
+        kpi_templates: Dict[str, Type[BASE_KPI]] | None = None,
+        algo_templates: Dict[str, Type[ALGORITHM]] | None = None,
+        input_configs: List[InputFileConfiguration] | None = None,
+        # === auto start/create features ===
+        autocreate: bool | None = None,
+        default_algo: str | None = None,
+        default_algo_params_values: Dict[str, Any] | None = None,
+        autorun: bool | None = None,
+        # === misc (core) ===
+        title: str = "Algomancy",
+        **_: Any,
+    ) -> None:
+        # paths
+        self.data_path = data_path
+
+        # data / scenario manager
+        self.has_persistent_state = has_persistent_state
+        self.save_type = save_type
+        self.data_object_type = data_object_type
+        self.etl_factory = etl_factory
+        self.kpi_templates = kpi_templates
+        self.algo_templates = algo_templates
+        self.input_configs = input_configs
+        self.autocreate = autocreate
+        self.default_algo = default_algo
+        self.default_algo_params_values = default_algo_params_values
+        self.autorun = autorun
+
+        # misc
+        self.title = title
+
+        self._validate_core()
+
+    # ----- public API -----
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "data_path": self.data_path,
+            "has_persistent_state": self.has_persistent_state,
+            "save_type": self.save_type,
+            "data_object_type": self.data_object_type,
+            "etl_factory": self.etl_factory,
+            "kpi_templates": self.kpi_templates,
+            "algo_templates": self.algo_templates,
+            "input_configs": self.input_configs,
+            "autocreate": self.autocreate,
+            "default_algo": self.default_algo,
+            "default_algo_params_values": self.default_algo_params_values,
+            "autorun": self.autorun,
+            "title": self.title,
+        }
+
+    # ----- validation -----
+    def _validate_core(self) -> None:
+        self._validate_paths_core()
+        self._validate_values_core()
+        self._validate_algorithm_parameters_core()
+
+    def _validate_paths_core(self) -> None:
+        if self.has_persistent_state:
+            if self.data_path is None or self.data_path == "":
+                raise ValueError("data_path must be provided")
+            if not os.path.isdir(self.data_path):
+                raise ValueError(
+                    f"data_path does not exist or is not a directory: {self.data_path}"
+                )
+
+    def _validate_values_core(self) -> None:
+        # required non-null entries for scenario/data managers
+        required_fields = {
+            "etl_factory": self.etl_factory,
+            "kpi_templates": self.kpi_templates,
+            "algo_templates": self.algo_templates,
+            "input_configs": self.input_configs,
+            "data_object_type": self.data_object_type,
+        }
+        missing = [k for k, v in required_fields.items() if v is None]
+        if missing:
+            raise ValueError(
+                f"Missing required configuration fields: {', '.join(missing)}"
+            )
+
+        # booleans allowed to be False, but must not be None if specified
+        for name, val in {
+            "has_persistent_state": self.has_persistent_state,
+            "autocreate": self.autocreate,
+            "autorun": self.autorun,
+        }.items():
+            if val is None:
+                raise ValueError(
+                    f"Boolean configuration '{name}' must be set to True or False, not None"
+                )
+
+        # save type
+        if self.save_type is None:
+            raise ValueError("save_type must be set to 'json' or 'parquet'")
+        if self.save_type not in {"json", "parquet"}:
+            raise ValueError("save_type must be either 'json' or 'parquet'")
+
+        # title
+        if not isinstance(self.title, str) or self.title.strip() == "":
+            raise ValueError("title must be a non-empty string")
+
+    def _validate_algorithm_parameters_core(self) -> None:
+        if self.autocreate:
+            tmp_factory = AlgorithmFactory(self.algo_templates)
+            test_algorithm = tmp_factory.create(
+                self.default_algo, self.default_algo_params_values
+            )
+            assert test_algorithm.healthcheck(), "Failed to create default algorithm"

algomancy_scenario/keyperformanceindicator.py

@@ -0,0 +1,136 @@
+from abc import ABC, abstractmethod
+from enum import StrEnum, auto
+from typing import TypeVar
+
+from .result import BASE_RESULT_BOUND
+from algomancy_utils.unit import BaseMeasurement, Measurement, Unit
+
+
+class ImprovementDirection(StrEnum):
+    HIGHER = auto()
+    LOWER = auto()
+    AT_LEAST = auto()
+    AT_MOST = auto()
+
+
+class KpiError(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(self.message)
+
+
+class BaseKPI(ABC):
+    def __init__(
+        self,
+        name: str,
+        better_when: ImprovementDirection,
+        base_measurement: BaseMeasurement,
+        threshold: float | None = None,
+    ) -> None:
+        self._name = name
+        self._better_when = better_when
+        self._measurement = Measurement(base_measurement)
+        self._threshold = (
+            Measurement(base_measurement, threshold) if threshold else None
+        )
+
+    def __str__(self):
+        self.pretty()
+
+    @property
+    def measurement(self) -> Measurement:
+        return self._measurement
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def better_when(self) -> ImprovementDirection:
+        return self._better_when
+
+    @property
+    def value(self) -> float | None:
+        return self._measurement.value
+
+    @property
+    def is_binary_kpi(self) -> bool:
+        return self._better_when in [
+            ImprovementDirection.AT_MOST,
+            ImprovementDirection.AT_LEAST,
+        ]
+
+    @property
+    def success(self) -> bool:
+        # Check the validity of the call
+        if not self.is_binary_kpi:
+            raise ValueError(f"KPI success is not defined for {self.name}")
+        if self._threshold is None:
+            raise ValueError(f"KPI threshold is not defined for {self.name}")
+
+        # Compare with threshold and return
+        if self._better_when == ImprovementDirection.AT_MOST:
+            return self._measurement.value <= self._threshold.value
+        return self._measurement.value >= self._threshold.value
+
+    @value.setter
+    def value(self, value: float):
+        self._measurement.value = value
+
+    def get_threshold_str(self, unit: Unit | None = None) -> str:
+        if unit:
+            return str(self._threshold.scale_to_unit(unit))
+        else:
+            return self._threshold.pretty()
+
+    def pretty(self, unit: Unit | None = None) -> str:
+        if self.is_binary_kpi:
+            return "✓" if self.success else "✗"
+        return self.details(unit)
+
+    def get_pretty_unit(self) -> Unit:
+        return self._measurement.scale().unit
+
+    def details(self, unit: Unit | None = None) -> str | None:
+        if unit:
+            return str(self._measurement.scale_to_unit(unit))
+        else:
+            return self._measurement.pretty()
+
+    @abstractmethod
+    def compute(self, result: BASE_RESULT_BOUND) -> float:
+        raise NotImplementedError("Abstract method")
+
+    def compute_and_check(self, result: BASE_RESULT_BOUND) -> None:
+        """
+        Computes a key performance indicator (KPI) value using the provided result data
+        and a callback function.
+
+        This method attempts to compute the KPI by invoking a specified callback with
+        the result data. If an exception occurs during computation, it logs an error
+        message indicating the KPI name and raises a KpiError to indicate failure.
+
+        :param result: The result data of the type required for KPI computation.
+        :type result: Derived from BaseScenarioResult
+        :raises KpiError: If an error occurs during the KPI computation.
+        """
+        try:
+            value = self.compute(result)
+            if not isinstance(value, (int, float)):
+                raise KpiError("KPI callback must return a numeric value.")
+            self.value = value
+        except Exception as e:
+            print(f"Error computing KPI {self.name}: {e}")
+            raise KpiError(f"Error computing KPI {self.name}")
+
+    def to_dict(self):
+        return {
+            "name": self.name,
+            "better_when": self.better_when.name,
+            "basis": self._measurement.base_measurement,
+            "value": self.value,
+            "threshold": self._threshold,
+        }
+
+
+BASE_KPI = TypeVar("BASE_KPI", bound=BaseKPI)

algomancy_scenario/kpifactory.py

@@ -0,0 +1,49 @@
+from typing import Generic, Dict, Type, List
+
+from .keyperformanceindicator import BASE_KPI
+
+
+class KpiFactory(Generic[BASE_KPI]):
+    """
+    Factory class for creating KPI instances.
+
+    This class provides a mechanism to register multiple KPI templates and create
+    instances of those templates dynamically. It enables flexibility and reuse
+    of KPI-related components in a structured and modular way.
+
+    Attributes:
+        _templates (Dict[str, Type[BASE_KPI]]): Dictionary mapping template names
+            to their corresponding KPI classes.
+    """
+
+    def __init__(self, templates: Dict[str, Type[BASE_KPI]]):
+        self._templates = templates
+
+    def create_all(self):
+        """
+        Creates a dictionary of KPIs using predefined templates.
+
+        Returns:
+            dict: A dictionary where the keys are the original keys from the
+            `templates` dictionary, and the values are the results of calling
+            the template functions.
+        """
+        return {name: template() for name, template in self._templates.items()}
+
+    def create(self, subset: List[str]):
+        """
+        Creates a dictionary of template instances filtered by the specified subset.
+
+        Args:
+            subset (List[str]): A list of template names to include in the resulting
+                dictionary.
+
+        Returns:
+            dict: A dictionary where the keys are the names of the templates from the
+                subset and the values are their corresponding instantiated templates.
+        """
+        return {
+            name: template()
+            for name, template in self._templates.items()
+            if name in subset
+        }

algomancy_scenario/result.py

@@ -0,0 +1,27 @@
+from abc import ABC, abstractmethod
+from datetime import datetime
+from typing import TypeVar
+
+
+class BaseScenarioResult(ABC):
+    def __init__(self, data_id: str):
+        self.data_id = data_id
+        self.completed_at = datetime.now()
+
+    @abstractmethod
+    def to_dict(self):
+        raise NotImplementedError("Abstract method")
+
+
+BASE_RESULT_BOUND = TypeVar("BASE_RESULT_BOUND", bound=BaseScenarioResult)
+
+
+class ScenarioResult(BaseScenarioResult):
+    def __init__(self, data_id: str):
+        super().__init__(data_id)
+
+    def to_dict(self):
+        return {
+            "scenario_id": self.data_id,
+            "completed_at": self.completed_at,
+        }

algomancy_scenario/scenario.py

@@ -0,0 +1,175 @@
+"""
+scenario.py - Scenario Management
+
+This module defines the Scenario class and related enums for managing simulation scenarios.
+It provides functionality for creating, processing, and analyzing scenarios with different
+algorithms and parameters.
+"""
+
+import uuid
+from enum import StrEnum, auto
+from typing import Dict, Generic
+
+from algomancy_utils.logger import Logger
+from algomancy_data import BASE_DATA_BOUND
+from .basealgorithm import ALGORITHM
+from .keyperformanceindicator import BASE_KPI
+
+
+class ScenarioStatus(StrEnum):
+    """
+    Constants representing the possible states of a scenario.
+    """
+
+    CREATED = auto()
+    QUEUED = auto()
+    PROCESSING = auto()
+    COMPLETE = auto()
+    FAILED = auto()
+
+
+class Scenario(Generic[BASE_KPI]):
+    """
+    Represents a scenario with input data, algorithm, and results.
+
+    A scenario encapsulates the input data, processing algorithm, parameters,
+    and results of a simulation or analysis run.
+    """
+
+    def __init__(
+        self,
+        tag: str,
+        input_data: BASE_DATA_BOUND,
+        kpis: Dict[str, BASE_KPI],
+        algorithm: ALGORITHM,
+        provided_id: str = None,
+    ):
+        """
+        Initializes a new Scenario with the specified parameters.
+
+        Args:
+            tag (str): A user-defined label for the scenario
+            input_data (BASE_DATA_BOUND): The data source to use for the scenario. Derived from BaseDataSource.
+            kpis: (Dict[str, KPI]): A dictionary of KPIs to compute for the scenario
+            algorithm (str): The algorithm to use for processing
+            provided_id (str): An optional unique identifier for the scenario. If not provided, a UUID will be generated.
+        """
+        self.id = provided_id if provided_id else str(uuid.uuid4())
+        self.tag = tag  # user-defined label
+        self._input_data = input_data  # includes raw or preprocessed data
+        self._kpis = kpis
+        self._algorithm = algorithm
+
+        self.status = ScenarioStatus.CREATED
+        self.result = None
+
+    def __str__(self):
+        return f"Scenario: {self.tag} ({str(self._algorithm)}"
+
+    @property
+    def input_data_key(self) -> str:
+        return self._input_data.name
+
+    @property
+    def data_source(self) -> BASE_DATA_BOUND:
+        return self._input_data
+
+    @property
+    def algorithm_description(self) -> str:
+        return self._algorithm.description
+
+    @property
+    def kpis(self) -> Dict[str, BASE_KPI]:
+        return self._kpis
+
+    @property
+    def progress(self) -> float:
+        return self._algorithm.get_progress
+
+    def set_queued(self):
+        self.status = ScenarioStatus.QUEUED
+
+    def process(self, logger: Logger = None):
+        """
+        Processes the scenario using the specified algorithm.
+
+        This method runs the algorithm in the background, updates the scenario status,
+        and computes KPIs based on the results.
+
+        Exceptions during processing are caught, and the scenario status is set to FAILED.
+        """
+        if not (
+            self.status == ScenarioStatus.CREATED
+            or self.status == ScenarioStatus.QUEUED
+        ):
+            return
+
+        self.status = ScenarioStatus.PROCESSING
+        try:
+            self.result = self._algorithm.run(self._input_data)
+            self.compute_kpis()
+            self.status = ScenarioStatus.COMPLETE
+        except Exception as e:
+            self.status = ScenarioStatus.FAILED
+            if logger:
+                logger.error(f"Scenario '{self.tag}' failed to process: {str(e)}")
+            self.result = {"error": str(e)}
+
+    def cancel(self, logger: Logger = None):
+        if logger:
+            logger.warning(f"Not Yet Implemented: Scenario {self.tag} cancel")
+        pass
+
+    def refresh(self, logger: Logger = None):
+        self.status = ScenarioStatus.CREATED
+        self.result = None
+        if logger:
+            logger.log(f"Refreshed scenario {self.tag}")
+
+    def compute_kpis(self):
+        """
+        Calculates key performance indicators (KPIs) for the given scenario.
+
+        Raises:
+            ValueError: If there is no result available for the scenario.
+            KpiError: If one or more KPI calculations fail.
+        """
+        if not self.result:
+            raise ValueError("Scenario result is not available")
+
+        for kpi in self._kpis.values():
+            kpi.compute_and_check(self.result)
+
+    def to_dict(self) -> dict:
+        """
+        Converts the attributes of the instance into a dictionary representation.
+
+        This method creates a dictionary containing the key attributes of the instance by
+        converting them into a serializable format. Attributes that have a `to_dict` method
+        are recursively processed. If some attributes do not exist or cannot be accessed,
+        they may return `None`.
+
+        Returns:
+            dict: A dictionary representation of the instance's attributes.
+        """
+        return {
+            "id": self.id,
+            "tag": self.tag,
+            "input_data_id": self._input_data.id
+            if hasattr(self._input_data, "id")
+            else None,
+            "kpis": {
+                k: v.to_dict() if hasattr(v, "to_dict") else v
+                for k, v in self._kpis.items()
+            },
+            "algorithm": self._algorithm.to_dict()
+            if hasattr(self._algorithm, "to_dict")
+            else self._algorithm,
+            "status": self.status,
+            "result": self.result.to_dict()
+            if hasattr(self.result, "to_dict")
+            else self.result,
+        }
+
+    def is_completed(self) -> bool:
+        return self.status == ScenarioStatus.COMPLETE

algomancy_scenario/scenariofactory.py

@@ -0,0 +1,76 @@
+from typing import Dict, List, Optional, Type
+
+from algomancy_utils.logger import Logger
+from algomancy_data import DataManager
+
+from .algorithmfactory import AlgorithmFactory
+from .basealgorithm import ALGORITHM
+from .keyperformanceindicator import BASE_KPI
+from .kpifactory import KpiFactory
+from .scenario import Scenario
+
+
+class ScenarioFactory:
+    """
+    Creates scenarios, builds algorithms and KPIs, and performs parameter validation.
+    """
+
+    def __init__(
+        self,
+        kpi_templates: Dict[str, Type[BASE_KPI]],
+        algo_templates: Dict[str, Type[ALGORITHM]],
+        data_manager: DataManager,
+        logger: Logger | None = None,
+    ):
+        self.logger = logger
+        self._kpi_factory = KpiFactory(kpi_templates)
+        self._algorithm_factory = AlgorithmFactory(algo_templates, logger)
+        self._data_manager = data_manager
+
+    @property
+    def available_algorithms(self) -> List[str]:
+        return self._algorithm_factory.available_algorithms
+
+    @property
+    def algo_templates(self) -> Dict[str, Type[ALGORITHM]]:
+        return self._algorithm_factory.templates
+
+    def log(self, msg: str):
+        if self.logger:
+            self.logger.log(msg)
+
+    def create(
+        self,
+        tag: str,
+        dataset_key: str,
+        algo_name: str,
+        algo_params: Optional[dict] = None,
+    ) -> Scenario:
+        if algo_params is None:
+            algo_params = {}
+
+        assert (
+            algo_name in self.available_algorithms
+        ), f"Algorithm '{algo_name}' not found."
+        assert (
+            dataset_key in self._data_manager.get_data_keys()
+        ), f"Data '{dataset_key}' not found."
+
+        algorithm = self._algorithm_factory.create(
+            input_name=algo_name,
+            input_params=algo_params,
+        )
+
+        kpi_dict = self._kpi_factory.create_all()
+
+        scenario = Scenario(
+            tag=tag,
+            input_data=self._data_manager.get_data(dataset_key),
+            kpis=kpi_dict,
+            algorithm=algorithm,
+        )
+        self.log(f"Scenario '{scenario.tag}' created.")
+        return scenario
+
+    def get_associated_parameters(self, algo_name: str):
+        return self._algorithm_factory.get_parameters(algo_name)

algomancy_scenario/scenariomanager.py

@@ -0,0 +1,373 @@
+from typing import Dict, List, Optional, TypeVar, Type
+
+from algomancy_data import (
+    ETLFactory,
+    InputFileConfiguration,
+    StatefulDataManager,
+    StatelessDataManager,
+    BASE_DATA_BOUND,
+)
+from algomancy_utils.logger import Logger, MessageStatus
+from .basealgorithm import ALGORITHM
+from algomancy_utils.baseparameterset import BASE_PARAMS_BOUND
+
+from .keyperformanceindicator import BASE_KPI
+from .scenario import Scenario
+from .scenarioregistry import ScenarioRegistry
+from .scenariofactory import ScenarioFactory
+from .scenarioprocessor import ScenarioProcessor
+
+
+class ScenarioManager:
+    """
+    Facade that coordinates data management, scenario creation/registry, and processing.
+    """
+
+    E = TypeVar("E", bound=ETLFactory)
+
+    @classmethod
+    def from_config(cls, cfg) -> "ScenarioManager":
+        return cls(
+            etl_factory=cfg.etl_factory,
+            kpi_templates=cfg.kpi_templates,
+            algo_templates=cfg.algo_templates,
+            input_configs=cfg.input_configs,
+            data_object_type=cfg.data_object_type,
+            data_folder=cfg.data_path,
+            has_persistent_state=cfg.has_persistent_state,
+            save_type=cfg.save_type,
+            autocreate=cfg.autocreate,
+            default_algo_name=cfg.default_algo,
+            default_param_values=cfg.default_algo_params_values,
+            autorun=cfg.autorun,
+        )
+
+    def __init__(
+        self,
+        etl_factory: type[E],
+        kpi_templates: Dict[str, Type[BASE_KPI]],
+        algo_templates: Dict[str, Type[ALGORITHM]],
+        input_configs: List[InputFileConfiguration],
+        data_object_type: type[BASE_DATA_BOUND],  # for extensions of datasource
+        data_folder: str = None,
+        logger: Logger = None,
+        scenario_save_location: str = "scenarios.json",
+        has_persistent_state: bool = False,
+        save_type: str = "json",  # adjusts the format
+        autocreate: bool = False,
+        default_algo_name: str = None,
+        default_param_values: Dict[str, any] = None,
+        autorun: bool = False,
+    ) -> None:
+        self.logger = logger if logger else Logger()
+        self.scenario_save_location = scenario_save_location
+        self._has_persistent_state = has_persistent_state
+        self._auto_create_scenario = autocreate
+        self._default_algo_name = default_algo_name
+        self._default_param_values = default_param_values
+
+        assert save_type in ["json"], "Save type must be parquet or json."
+        self._save_type = save_type
+
+        # Components
+        if self._has_persistent_state:
+            assert data_folder, (
+                "Data folder must be specified if data manager has state."
+            )
+            self._dm = StatefulDataManager(
+                etl_factory=etl_factory,
+                input_configs=input_configs,
+                data_folder=data_folder,
+                save_type=save_type,
+                data_object_type=data_object_type,
+                logger=self.logger,
+            )
+        else:
+            self._dm = StatelessDataManager(
+                etl_factory=etl_factory,
+                input_configs=input_configs,
+                save_type=save_type,
+                logger=self.logger,
+                data_object_type=data_object_type,
+            )
+
+        self._registry = ScenarioRegistry(logger=self.logger)
+        self._factory = ScenarioFactory(
+            kpi_templates=kpi_templates,
+            algo_templates=algo_templates,
+            data_manager=self._dm,
+            logger=self.logger,
+        )
+        self._processor = ScenarioProcessor(logger=self.logger)
+        self.toggle_autorun(autorun)
+
+        # Keep inputs for accessors
+        # self._algo_templates = algo_templates
+        self._input_configs = input_configs
+
+        # Load initial data
+        try:
+            self._dm.startup()
+            if self._auto_create_scenario:
+                self.auto_create_scenarios(self._dm.get_data_keys())
+        except Exception as e:
+            self.log(f"Error loading initial data: {e}", status=MessageStatus.ERROR)
+
+        self.log("ScenarioManager initialized.")
+
+    # Logging
+    def log(self, message: str, status: MessageStatus = MessageStatus.INFO) -> None:
+        if self.logger:
+            self.logger.log(message, status)
+
+    @property
+    def has_persistent_state(self):
+        return self._has_persistent_state
+
+    # Accessors
+    @property
+    def save_type(self):
+        return self._save_type
+
+    @property
+    def input_configurations(self):
+        return self._input_configs
+
+    @property
+    def available_algorithms(self):
+        return self._factory.available_algorithms
+
+    @property
+    def auto_run_scenarios(self):
+        return self._processor.auto_run_scenarios
+
+    @property
+    def currently_processing(self) -> Optional[Scenario]:
+        return self._processor.currently_processing
+
+    def get_algorithm_parameters(self, key) -> BASE_PARAMS_BOUND:
+        return self._factory.algo_templates.get(key).initialize_parameters()
+
+    # Data operations (delegated)
+    def get_data_keys(self) -> List[str]:
+        return self._dm.get_data_keys()
+
+    def get_data(self, data_key):
+        return self._dm.get_data(data_key)
+
+    def set_data(self, data_key, data):
+        self._dm.set_data(data_key, data)
+
+    def derive_data(self, derive_from_key: str, new_data_key: str) -> None:
+        self._dm.derive_data(derive_from_key, new_data_key)
+        if self._auto_create_scenario:
+            self.auto_create_scenarios([new_data_key])
+
+    def delete_data(
+        self, data_key: str, prevent_masterdata_removal: bool = False
+    ) -> None:
+        # prevent delete if used by scenarios
+        assert data_key not in self._registry.used_datasets(), (
+            "Cannot delete data used in scenarios."
+        )
+        self._dm.delete_data(data_key, prevent_masterdata_removal)
+
+    def store_data(self, dataset_name: str, data):
+        if isinstance(self._dm, StatefulDataManager):
+            self._dm.store_data(dataset_name, data)
+        else:
+            if self.logger:
+                self.logger.error(
+                    "Store data is not supported for stateless data manager. "
+                )
+            pass
+
+    def toggle_autorun(self, value: bool = None) -> None:
+        if value is None:
+            self._processor.auto_run_scenarios = not self._processor.auto_run_scenarios
+        else:
+            self._processor.auto_run_scenarios = value
+        self.log(f"Auto-run scenarios set to {self._processor.auto_run_scenarios}")
+
+    # Processing operations (delegated)
+    def process_scenario_async(self, scenario):
+        self._processor.enqueue(scenario)
+
+    def wait_for_processing(self):
+        self._processor.wait_for_processing()
+
+    def shutdown_processing(self):
+        self._processor.shutdown()
+
+    # Scenario creation/registry
+    def get_associated_parameters(self, algo_name: str):
+        return self._factory.get_associated_parameters(algo_name)
+
+    def create_scenario(
+        self,
+        tag: str,
+        dataset_key: str = "Master data",
+        algo_name: str = "",
+        algo_params=None,
+    ) -> Scenario:
+        if self._registry.has_tag(tag):
+            self.log(f"Scenario with tag '{tag}' already exists. Skipping creation.")
+            raise ValueError(f"A scenario with tag '{tag}' already exists.")
+
+        scenario = self._factory.create(
+            tag=tag,
+            dataset_key=dataset_key,
+            algo_name=algo_name,
+            algo_params=algo_params,
+        )
+        self._registry.add(scenario)
+
+        if self._processor.auto_run_scenarios:
+            self._processor.enqueue(scenario)
+        return scenario
+
+    def get_by_id(self, scenario_id: str) -> Optional[Scenario]:
+        return self._registry.get_by_id(scenario_id)
+
+    def get_by_tag(self, tag: str) -> Optional[Scenario]:
+        return self._registry.get_by_tag(tag)
+
+    def delete_scenario(self, scenario_id: str) -> bool:
+        return self._registry.delete(scenario_id)
+
+    def list_scenarios(self) -> List[Scenario]:
+        return self._registry.list()
+
+    def list_ids(self):
+        return self._registry.list_ids()
+
+    def toggle_autocreate(
+        self, value: bool = None, default_algo_name: str = ""
+    ) -> None:
+        if value is None:
+            self._auto_create_scenario = not self._auto_create_scenario
+            self._default_algo_name = (
+                default_algo_name if self._auto_create_scenario else None
+            )
+        else:
+            self._auto_create_scenario = value
+            self._default_algo_name = (
+                default_algo_name if self._auto_create_scenario else None
+            )
+        self.log(f"Auto-create scenarios set to {self._auto_create_scenario}")
+
+    def add_datasource_from_json(self, json_string):
+        # Create data source from JSON
+        datasource = self._dm.data_object_type.from_json(json_string)
+
+        # Add data source to datamanager
+        self._dm.add_data_source(datasource)
+
+        # create scenario if auto-create is enabled
+        if self._auto_create_scenario:
+            self.auto_create_scenarios([datasource.name])
+
+    def etl_data(self, files, dataset_name: str) -> None:
+        # Process the files
+        self._dm.etl_data(files, dataset_name)
+
+        # create scenario if auto-create is enabled
+        if self._auto_create_scenario:
+            self.auto_create_scenarios([dataset_name])
+
+    def auto_create_scenarios(self, keys: List[str] = None):
+        for key in keys:
+            self.create_scenario(
+                tag=f"{key} [auto]",
+                dataset_key=key,
+                algo_name=self._default_algo_name,
+                algo_params=self._default_param_values,
+            )
+
+    def get_data_as_json(self, key: str) -> str:
+        return self._dm.get_data(key).to_json()
+
+    def store_data_as_json(self, set_name):
+        if isinstance(self._dm, StatefulDataManager):
+            self._dm.store_data_source_as_json(set_name)
+        else:
+            raise AttributeError(
+                "Stateless data manager does not support internal serialization."
+            )
+
+    def debug_load_data(self, dataset_name: str) -> None:
+        if isinstance(self._dm, StatefulDataManager):
+            self._dm.load_data_from_dir(dataset_name)
+        elif isinstance(self._dm, StatelessDataManager):
+            raise NotImplementedError(
+                "Todo: implement loading for stateless data manager."
+            )
+        else:
+            raise Exception("Data manager not initialized.")
+
+    def debug_create_and_run_scenario(
+        self,
+        scenario_tag: str,
+        dataset_key: str,
+        algo_name: str,
+        algo_params: Dict[str, any],
+    ) -> Scenario:
+        """
+        Creates and runs a scenario for debugging purposes. The method uses a factory to create a
+        scenario instance, registers it, enqueues it for processing, and waits for the processing to
+        complete. Returns the fully processed scenario.
+
+        Parameters:
+            scenario_tag (str): A unique identifier for the scenario being created and run.
+            dataset_key (str): The key for the dataset to be used in the scenario.
+            algo_name (str): The name of the algorithm to be applied in the scenario.
+            algo_params (Dict): Additional parameters for the algorithm.
+
+        Returns:
+            Scenario: The fully processed scenario created and executed within this method.
+        """
+        scenario = self._factory.create(
+            tag=scenario_tag,
+            dataset_key=dataset_key,
+            algo_name=algo_name,
+            algo_params=algo_params,
+        )
+        self._registry.add(scenario)
+        self._processor.enqueue(scenario)
+        self.wait_for_processing()
+        return scenario
+
+    def debug_etl_data(self, dataset_name: str) -> None:
+        """
+        Debugging utility to run ETL on a directory as if loaded on startup.
+        """
+        # Retrieve files from directory
+        if isinstance(self._dm, StatefulDataManager):
+            self._dm.load_data_from_dir(dataset_name)
+        else:
+            raise AttributeError(
+                "Stateless data manager does not support internal ETL."
+            )
+
+    def debug_load_serialized_data(self, file_name: str):
+        """
+        Debugging utility to upload a file as if loaded on startup.
+        """
+        if isinstance(self._dm, StatefulDataManager):
+            self._dm.load_data_from_file(file_name)
+        else:
+            raise AttributeError(
+                "Stateless data manager does not support internal deserialization."
+            )
+
+    def debug_import_data(self, directory: str) -> None:
+        """
+        Debugging utility to import data from a directory.
+        """
+        raise NotImplementedError("todo: write import data method")
+
+    def debug_upload_data(self, file_name: str) -> None:
+        """
+        Debugging utility to upload data from a file.
+        """
+        raise NotImplementedError("todo: write upload data method")

algomancy_scenario/scenarioprocessor.py

@@ -0,0 +1,66 @@
+import queue
+import threading
+from typing import Optional
+
+from algomancy_utils.logger import Logger
+
+from .scenario import Scenario
+
+
+class ScenarioProcessor:
+    """
+    Manages the processing queue, runs scenarios asynchronously, and tracks status.
+    """
+
+    def __init__(self, logger: Logger | None = None):
+        self.logger = logger
+        self._process_queue: queue.Queue[Scenario | None] = queue.Queue()
+        self._worker_thread = threading.Thread(
+            target=self._process_scenarios_worker, daemon=True
+        )
+        self._currently_processing: Optional[Scenario] = None
+        self._auto_run_scenarios = False
+        self._worker_thread.start()
+
+    # Properties
+    @property
+    def auto_run_scenarios(self) -> bool:
+        return self._auto_run_scenarios
+
+    @auto_run_scenarios.setter
+    def auto_run_scenarios(self, value: bool):
+        self._auto_run_scenarios = value
+
+    @property
+    def currently_processing(self) -> Optional[Scenario]:
+        return self._currently_processing
+
+    # Worker
+    def _process_scenarios_worker(self):
+        while True:
+            scenario = self._process_queue.get()
+            if scenario is None:
+                break
+
+            if self.logger:
+                self.logger.log(f"Processing scenario '{scenario.tag}'...")
+            self._currently_processing = scenario
+
+            scenario.process(logger=self.logger)
+
+            if self.logger:
+                self.logger.log(f"Scenario '{scenario.tag}' completed.")
+            self._currently_processing = None
+            self._process_queue.task_done()
+
+    # API
+    def enqueue(self, scenario: Scenario):
+        scenario.set_queued()
+        self._process_queue.put(scenario)
+
+    def wait_for_processing(self):
+        self._process_queue.join()
+
+    def shutdown(self):
+        self._process_queue.put(None)
+        self._worker_thread.join()

algomancy_scenario/scenarioregistry.py

@@ -0,0 +1,54 @@
+from typing import Dict, List, Optional
+
+from algomancy_utils.logger import Logger
+from .scenario import Scenario
+
+
+class ScenarioRegistry:
+    """
+    Stores and retrieves scenarios and maintains indices.
+    """
+
+    def __init__(self, logger: Logger | None = None):
+        self.logger = logger
+        self._scenarios: Dict[str, Scenario] = {}
+        self._tag_index: Dict[str, str] = {}
+
+    def log(self, msg: str):
+        if self.logger:
+            self.logger.log(msg)
+
+    # CRUD
+    def add(self, scenario: Scenario) -> None:
+        self._scenarios[scenario.id] = scenario
+        self._tag_index[scenario.tag] = scenario.id
+        self.log(f"Registered scenario '{scenario.tag}'.")
+
+    def get_by_id(self, scenario_id: str) -> Optional[Scenario]:
+        return self._scenarios.get(scenario_id)
+
+    def get_by_tag(self, tag: str) -> Optional[Scenario]:
+        scenario_id = self._tag_index.get(tag)
+        return self.get_by_id(scenario_id) if scenario_id else None
+
+    def delete(self, scenario_id: str) -> bool:
+        if scenario_id in self._scenarios:
+            tag = self._scenarios[scenario_id].tag
+            del self._scenarios[scenario_id]
+            if tag in self._tag_index:
+                del self._tag_index[tag]
+            self.log(f"Deleted scenario '{tag}'.")
+            return True
+        return False
+
+    def list(self) -> List[Scenario]:
+        return list(self._scenarios.values())
+
+    def list_ids(self) -> List[str]:
+        return list(self._scenarios.keys())
+
+    def has_tag(self, tag: str) -> bool:
+        return tag in self._tag_index
+
+    def used_datasets(self) -> List[str]:
+        return [s.input_data_key for s in self._scenarios.values()]

algomancy_scenario-0.3.13.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.3
+Name: algomancy-scenario
+Version: 0.3.13
+Summary: Scenario management model for the Algomancy library
+Author: Pepijn Wissing
+Author-email: Pepijn Wissing <Wsg@cqm.nl>
+Requires-Dist: algomancy-utils
+Requires-Dist: algomancy-data
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+### algomancy-scenario
+
+Scenario modeling utilities for Algomancy: define algorithms and parameters, run scenarios against data, and compute KPIs.
+
+#### Features
+- `Scenario` lifecycle with statuses (`CREATED`, `QUEUED`, `PROCESSING`, `COMPLETE`, `FAILED`)
+- `BaseAlgorithm` and parameter classes to define pluggable algorithms
+- KPI framework (`BaseKPI`) to compute metrics from algorithm results
+- Works with `algomancy-data` data sources and can be orchestrated from the GUI
+
+#### Installation
+```
+pip install -e packages/algomancy-scenario
+```
+
+Requires Python >= 3.14.
+
+#### Quick start
+Define a simple algorithm and KPI, then run a `Scenario`:
+
+```python
+from algomancy_scenario import (
+    Scenario, ScenarioStatus,
+    BaseAlgorithm, BaseParameterSet, BaseKPI,
+)
+from algomancy_data import DataSource, DataClassification
+
+
+# Minimal parameters type
+class ExampleParams(BaseParameterSet):
+    def serialize(self) -> dict:
+        return {"hello": "world"}
+
+
+# Minimal algorithm
+class ExampleAlgorithm(BaseAlgorithm):
+    def __init__(self):
+        super().__init__(name="Example", params=ExampleParams())
+
+    @staticmethod
+    def initialize_parameters() -> ExampleParams:  # used by GUI tooling
+        return ExampleParams()
+
+    def run(self, data: DataSource) -> dict:
+        # do something with data and return a result dictionary
+        self.set_progress(100)
+        return {"count_tables": len(data.list_tables())}
+
+
+# Minimal KPI
+class CountTablesKPI(BaseKPI):
+    def __init__(self):
+        super().__init__(name="Tables", improvement_direction=None)
+
+    def compute_and_check(self, result: dict):
+        self.value = result["count_tables"]
+
+
+# Prepare data
+ds = DataSource(ds_type=DataClassification.MASTER_DATA, name="warehouse")
+
+# Build and run scenario
+scenario = Scenario(
+    tag="demo",
+    input_data=ds,
+    kpis={"tables": CountTablesKPI()},
+    algorithm=ExampleAlgorithm(),
+)
+
+scenario.process()
+assert scenario.status == ScenarioStatus.COMPLETE
+print("Tables KPI:", scenario.kpis["tables"].value)
+```
+
+#### Related docs and examples
+- Example app demonstrates scenario wiring: `example/pages/ScenarioPageContent.py`
+- Algorithm/KPI examples: `example/templates/algorithm/` and `example/templates/kpi/`

algomancy_scenario-0.3.13.dist-info/RECORD

@@ -0,0 +1,16 @@
+algomancy_scenario/__init__.py,sha256=m6FLBac2tEwg8KGBG1eXSmOO84tQBsMfaMtP5YBnxPQ,952
+algomancy_scenario/algorithmfactory.py,sha256=HXobbXLkny1gIxPLda_NI7Bur6EeSYewFV-y-5lU4NA,1711
+algomancy_scenario/basealgorithm.py,sha256=5YatHK7ym9BHaqyowIs38_7k4QZrs8AAQTJxQOlzkKY,2160
+algomancy_scenario/core_configuration.py,sha256=F-kMj08x9YgNW7RBk28QAOc9TTx3pZQDPNBWz3yk58w,5126
+algomancy_scenario/keyperformanceindicator.py,sha256=PbuENywT9jLEaC1p_hbINaRl-815Wpx5NiFQo8Dagro,4296
+algomancy_scenario/kpifactory.py,sha256=cthdu7hCmy8XJD29jfOXlC3_nBgULkOL1mRlpbUPOBY,1682
+algomancy_scenario/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+algomancy_scenario/result.py,sha256=8g_SlhZ1j36yaVXSNnsElnmkX7cE7x0-vhlikjsGn00,667
+algomancy_scenario/scenario.py,sha256=VnCVDXiCfj727IwylzKtPBRUhXTe0UT8K_vfG9JMNsw,5680
+algomancy_scenario/scenariofactory.py,sha256=HKP6mDDzmiOlOSecRHDkqTfQzeN_lBDdGIpr1-5amS4,2243
+algomancy_scenario/scenariomanager.py,sha256=LEFCPSd8jbCWBJBeGcQBD376ipxneaosJf7PstHsHm8,13150
+algomancy_scenario/scenarioprocessor.py,sha256=iXQnV0SCG1Mdz4AwgLJmeIGTDTyXzlhD_SOdCb9_eKM,1898
+algomancy_scenario/scenarioregistry.py,sha256=VMtZUQTsX_n_Sd8-cLilK3GhyQ7NzLVZqT_tiMAEd20,1708
+algomancy_scenario-0.3.13.dist-info/WHEEL,sha256=XjEbIc5-wIORjWaafhI6vBtlxDBp7S9KiujWF1EM7Ak,79
+algomancy_scenario-0.3.13.dist-info/METADATA,sha256=8TEa4yXPWSWeOpr6Y8qYT3cGSau11ASfi1ubqIkDVRs,2556
+algomancy_scenario-0.3.13.dist-info/RECORD,,

algomancy_scenario-0.3.13.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.25
+Root-Is-Purelib: true
+Tag: py3-none-any