[Feature] PEPPER in enviPath (#332)

Co-authored-by: Tim Lorsbach <tim@lorsba.ch>
Reviewed-on: enviPath/enviPy#332

bridge/contracts.py

@@ -0,0 +1,233 @@
+import enum
+from abc import ABC, abstractmethod
+
+from .dto import BuildResult, EnviPyDTO, EvaluationResult, RunResult
+
+
+class PropertyType(enum.Enum):
+    """
+    Enumeration representing different types of properties.
+
+    PropertyType is an Enum class that defines categories or types of properties
+    based on their weight or nature. It can typically be used when classifying
+    objects or entities by their weight classification, such as lightweight or heavy.
+    """
+
+    LIGHTWEIGHT = "lightweight"
+    HEAVY = "heavy"
+
+
+class Plugin(ABC):
+    """
+    Defines an abstract base class Plugin to serve as a blueprint for plugins.
+
+    This class establishes the structure that all plugin implementations must
+    follow. It enforces the presence of required methods to ensure consistent
+    functionality across all derived classes.
+
+    """
+
+    @abstractmethod
+    def identifier(self) -> str:
+        pass
+
+    @abstractmethod
+    def name(self) -> str:
+        """
+        Represents an abstract method that provides a contract for implementing a method
+        to return a name as a string. Must be implemented in subclasses.
+        Name must be unique across all plugins.
+
+        Methods
+        -------
+        name() -> str
+            Abstract method to be defined in subclasses, which returns a string
+            representing a name.
+        """
+        pass
+
+    @abstractmethod
+    def display(self) -> str:
+        """
+        An abstract method that must be implemented by subclasses to display
+        specific information or behavior. The method ensures that all subclasses
+        provide their own implementation of the display functionality.
+
+        Raises:
+            NotImplementedError: Raises this error when the method is not implemented
+            in a subclass.
+
+        Returns:
+            str: A string used in dropdown menus or other user interfaces to display
+        """
+        pass
+
+
+class Property(Plugin):
+    @abstractmethod
+    def requires_rule_packages(self) -> bool:
+        """
+        Defines an abstract method to determine whether rule packages are required.
+
+        This method should be implemented by subclasses to specify if they depend
+        on rule packages for their functioning.
+
+        Raises:
+            NotImplementedError: If the subclass has not implemented this method.
+
+        @return: A boolean indicating if rule packages are required.
+        """
+        pass
+
+    @abstractmethod
+    def requires_data_packages(self) -> bool:
+        """
+        Defines an abstract method to determine whether data packages are required.
+
+        This method should be implemented by subclasses to specify if they depend
+        on data packages for their functioning.
+
+        Raises:
+            NotImplementedError: If the subclass has not implemented this method.
+
+        Returns:
+            bool: True if the service requires data packages, False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def get_type(self) -> PropertyType:
+        """
+        An abstract method that provides the type of property. This method must
+        be implemented by subclasses to specify the appropriate property type.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by a subclass.
+
+        Returns:
+            PropertyType: The type of the property associated with the implementation.
+        """
+        pass
+
+    def is_heavy(self):
+        """
+        Determines if the current property type is heavy.
+
+        This method evaluates whether the property type returned from the `get_type()`
+        method is classified as `HEAVY`. It utilizes the `PropertyType.HEAVY` constant
+        for this comparison.
+
+        Raises:
+            AttributeError: If the `get_type()` method is not defined or does not return
+            a valid value.
+
+        Returns:
+            bool: True if the property type is `HEAVY`, otherwise False.
+        """
+        return self.get_type() == PropertyType.HEAVY
+
+    @abstractmethod
+    def build(self, eP: EnviPyDTO, *args, **kwargs) -> BuildResult | None:
+        """
+        Abstract method to prepare and construct a specific build process based on the provided
+        environment data transfer object (EnviPyDTO). This method should be implemented by
+        subclasses to handle the particular requirements of the environment.
+
+        Parameters:
+        eP : EnviPyDTO
+            The data transfer object containing environment details for the build process.
+
+        *args :
+            Additional positional arguments required for the build.
+
+        **kwargs :
+            Additional keyword arguments to offer flexibility and customization for
+            the build process.
+
+        Returns:
+        BuildResult | None
+            Returns a BuildResult instance if the build operation succeeds, else returns None.
+
+        Raises:
+        NotImplementedError
+            If the method is not implemented in a subclass.
+        """
+        pass
+
+    @abstractmethod
+    def run(self, eP: EnviPyDTO, *args, **kwargs) -> RunResult:
+        """
+        Represents an abstract base class for executing a generic process with
+        provided parameters and returning a standardized result.
+
+        Attributes:
+            None.
+
+        Methods:
+            run(eP, *args, **kwargs):
+                Executes a task with specified input parameters and optional
+                arguments, returning the outcome in the form of a RunResult object.
+                This is an abstract method and must be implemented in subclasses.
+
+        Raises:
+            NotImplementedError: If the subclass does not implement the abstract
+            method.
+
+        Parameters:
+            eP (EnviPyDTO): The primary object containing information or data required
+            for processing. Mandatory.
+            *args: Variable length argument list for additional positional arguments.
+            **kwargs: Arbitrary keyword arguments for additional options or settings.
+
+        Returns:
+            RunResult: A result object encapsulating the status, output, or details
+            of the process execution.
+
+        """
+        pass
+
+    @abstractmethod
+    def evaluate(self, eP: EnviPyDTO, *args, **kwargs) -> EvaluationResult:
+        """
+        Abstract method for evaluating data based on the given input and additional arguments.
+
+        This method is intended to be implemented by subclasses and provides
+        a mechanism to perform an evaluation procedure based on input encapsulated
+        in an EnviPyDTO object.
+
+        Parameters:
+        eP : EnviPyDTO
+            The data transfer object containing necessary input for evaluation.
+        *args : tuple
+            Additional positional arguments for the evaluation process.
+        **kwargs : dict
+            Additional keyword arguments for the evaluation process.
+
+        Returns:
+        EvaluationResult
+            The result of the evaluation performed by the method.
+
+        Raises:
+        NotImplementedError
+            If the method is not implemented in the subclass.
+        """
+        pass
+
+    @abstractmethod
+    def build_and_evaluate(self, eP: EnviPyDTO, *args, **kwargs) -> EvaluationResult:
+        """
+        An abstract method designed to build and evaluate a model or system using the provided
+        environmental parameters and additional optional arguments.
+
+        Args:
+            eP (EnviPyDTO): The environmental parameters required for building and evaluating.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            EvaluationResult: The result of the evaluation process.
+
+        Raises:
+            NotImplementedError: If the method is not implemented by a subclass.
+        """
+        pass

bridge/dto.py

@@ -0,0 +1,140 @@
+from dataclasses import dataclass
+from typing import Any, List, Optional, Protocol
+
+from envipy_additional_information import EnviPyModel, register
+from pydantic import HttpUrl
+
+from utilities.chem import FormatConverter, ProductSet
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    uuid: str
+    url: str
+    work_dir: str
+
+
+class CompoundProto(Protocol):
+    url: str | None
+    name: str | None
+    smiles: str
+
+
+class RuleProto(Protocol):
+    url: str
+    name: str
+
+    def apply(self, smiles, *args, **kwargs): ...
+
+
+class ReactionProto(Protocol):
+    url: str
+    name: str
+    rules: List[RuleProto]
+
+
+class EnviPyDTO(Protocol):
+    def get_context(self) -> Context: ...
+
+    def get_compounds(self) -> List[CompoundProto]: ...
+
+    def get_reactions(self) -> List[ReactionProto]: ...
+
+    def get_rules(self) -> List[RuleProto]: ...
+
+    @staticmethod
+    def standardize(smiles, remove_stereo=False, canonicalize_tautomers=False): ...
+
+    @staticmethod
+    def apply(
+        smiles: str,
+        smirks: str,
+        preprocess_smiles: bool = True,
+        bracketize: bool = True,
+        standardize: bool = True,
+        kekulize: bool = True,
+        remove_stereo: bool = True,
+        reactant_filter_smarts: str | None = None,
+        product_filter_smarts: str | None = None,
+    ) -> List["ProductSet"]: ...
+
+
+class PredictedProperty(EnviPyModel):
+    pass
+
+
+@register("buildresult")
+class BuildResult(EnviPyModel):
+    data: dict[str, Any] | List[dict[str, Any]] | None
+
+
+@register("runresult")
+class RunResult(EnviPyModel):
+    producer: HttpUrl
+    description: Optional[str] = None
+    result: PredictedProperty | List[PredictedProperty]
+
+
+@register("evaluationresult")
+class EvaluationResult(EnviPyModel):
+    data: dict[str, Any] | List[dict[str, Any]] | None
+
+
+class BaseDTO(EnviPyDTO):
+    def __init__(
+        self,
+        uuid: str,
+        url: str,
+        work_dir: str,
+        compounds: List[CompoundProto],
+        reactions: List[ReactionProto],
+        rules: List[RuleProto],
+    ):
+        self.uuid = uuid
+        self.url = url
+        self.work_dir = work_dir
+        self.compounds = compounds
+        self.reactions = reactions
+        self.rules = rules
+
+    def get_context(self) -> Context:
+        return Context(uuid=self.uuid, url=self.url, work_dir=self.work_dir)
+
+    def get_compounds(self) -> List[CompoundProto]:
+        return self.compounds
+
+    def get_reactions(self) -> List[ReactionProto]:
+        return self.reactions
+
+    def get_rules(self) -> List[RuleProto]:
+        return self.rules
+
+    @staticmethod
+    def standardize(smiles, remove_stereo=False, canonicalize_tautomers=False):
+        return FormatConverter.standardize(
+            smiles, remove_stereo=remove_stereo, canonicalize_tautomers=canonicalize_tautomers
+        )
+
+    @staticmethod
+    def apply(
+        smiles: str,
+        smirks: str,
+        preprocess_smiles: bool = True,
+        bracketize: bool = True,
+        standardize: bool = True,
+        kekulize: bool = True,
+        remove_stereo: bool = True,
+        reactant_filter_smarts: str | None = None,
+        product_filter_smarts: str | None = None,
+    ) -> List["ProductSet"]:
+        return FormatConverter.apply(
+            smiles,
+            smirks,
+            preprocess_smiles,
+            bracketize,
+            standardize,
+            kekulize,
+            remove_stereo,
+            reactant_filter_smarts,
+            product_filter_smarts,
+        )