ripple-down-rules 0.6.49__py3-none-any.whl → 0.6.50__py3-none-any.whl

ripple_down_rules/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.6.49"
+__version__ = "0.6.50"
 
 import logging
 import sys

ripple_down_rules/rdr_decorators.py

@@ -4,17 +4,18 @@ that can be used with any python function such that this function can benefit fr
 of the RDRs.
 """
 import os.path
+from dataclasses import dataclass, field
 from functools import wraps
 from typing import get_origin
 
 from typing_extensions import Callable, Optional, Type, Tuple, Dict, Any, Self, get_type_hints, List, Union, Sequence
 
-from .utils import get_type_from_type_hint
 from .datastructures.case import Case
 from .datastructures.dataclasses import CaseQuery
 from .experts import Expert, Human
 from .rdr import GeneralRDR
-from . import logger
+from .utils import get_type_from_type_hint
+
 try:
     from .user_interface.gui import RDRCaseViewer
 except ImportError:
@@ -23,63 +24,92 @@ from .utils import get_method_args_as_dict, get_func_rdr_model_name, make_set, \
     get_method_class_if_exists, str_to_snake_case, make_list
 
 
+@dataclass(unsafe_hash=True)
 class RDRDecorator:
-    rdr: GeneralRDR
-
-    def __init__(self, models_dir: str,
-                 output_type: Tuple[Type],
-                 mutual_exclusive: bool,
-                 output_name: str = "output_",
-                 fit: bool = True,
-                 expert: Optional[Expert] = None,
-                 update_existing_rules: bool = True,
-                 viewer: Optional[RDRCaseViewer] = None,
-                 package_name: Optional[str] = None,
-                 use_generated_classifier: bool = False,
-                 ask_now: Callable[Dict[str, Any], bool] = lambda _: True,
-                 fitting_decorator: Optional[Callable] = None,
-                 generate_dot_file: bool = False) -> None:
-        """
-        :param models_dir: The directory to save/load the RDR models.
-        :param output_type: The type of the output. This is used to create the RDR model.
-        :param mutual_exclusive: If True, the output types are mutually exclusive.
-         If None, the RDR model will not be saved as a python file.
-        :param output_name: The name of the output. This is used to create the RDR model.
-        :param fit: If True, the function will be in fit mode. This means that the RDR will prompt the user for the
-            correct output if the function's output is not in the RDR model. If False, the function will be in
-            classification mode. This means that the RDR will classify the function's output based on the RDR model.
-        :param expert: The expert that will be used to prompt the user for the correct output. If None, a Human
-            expert will be used.
-        :param update_existing_rules: If True, the function will update the existing RDR rules
-         even if they gave an output.
-        :param viewer: The viewer to use for the RDR model. If None, no viewer will be used.
-        :param package_name: The package name to use for relative imports in the RDR model.
-        :param use_generated_classifier: If True, the function will use the generated classifier instead of the RDR model.
-        :param ask_now: A callable that takes the case dictionary and returns True if the user should be asked for
-            the output, or False if the function should return the output without asking.
-        :param fitting_decorator: A decorator to use for the fitting function. If None, no decorator will be used.
-        :param generate_dot_file: If True, the RDR model will generate a dot file for visualization.
-        :return: A decorator to use a GeneralRDR as a classifier that monitors and modifies the function's output.
-        """
-        self.rdr_models_dir = models_dir
-        self.model_name: Optional[str] = None
-        self.output_type = output_type
-        self.parsed_output_type: List[Type] = []
-        self.mutual_exclusive = mutual_exclusive
-        self.output_name = output_name
-        self.fit: bool = fit
-        self.expert: Optional[Expert] = expert
-        self.update_existing_rules = update_existing_rules
-        self.viewer = viewer
-        self.package_name = package_name
-        self.use_generated_classifier = use_generated_classifier
-        self.generated_classifier: Optional[Callable] = None
-        self.ask_now = ask_now
-        self.fitting_decorator = fitting_decorator if fitting_decorator is not None else \
-            lambda f: f  # Default to no fitting decorator
-        self.generate_dot_file = generate_dot_file
-        self.not_none_output_found: bool = False
-        self.origin_type: Optional[Type] = None
+    models_dir: str
+    """
+    The directory to save the RDR models in.
+    """
+    output_type: Tuple[Type, ...]
+    """
+    The type(s) of the output produced by the RDR model (The type(s) of the queried attribute).
+    """
+    mutual_exclusive: bool
+    """
+    Whether the queried attribute is mutually exclusive (i.e. allows for only one possible value) or not.
+    """
+    fit: bool = field(default=True)
+    """
+    Whether to run in fitting mode and prompt the expert or just classify using existing rules.
+    """
+    expert: Optional[Expert] = field(default=None)
+    """
+    The expert instance, this is used by the rdr to prompt for answers.
+    """
+    update_existing_rules: bool = field(default=True)
+    """
+    When in fitting mode, whether to ask for answers for existing rules as well or not.
+    """
+    package_name: Optional[str] = field(default=None)
+    """
+    The name of the user python package where the RDR model will be saved, this is useful for generating relative
+    imports in the generated rdr model files.
+    """
+    use_generated_classifier: bool = field(default=False)
+    """
+    Whether to use the generated classifier files of the rdr model instead of the RDR instance itself, this is useful
+    when you want to debug inside the rules.
+    """
+    ask_now: Callable[Dict[str, Any], bool] = field(default=lambda _: True)
+    """
+    A user provided callable function that outputs a boolean indicating when to ask the expert for an answer. The input
+    to the `ask_now` function is a dictionary with the original function arguments, while arguments like `self` and
+    `cls` are passed as a special key `self_` or `cls_` respectively.
+    """
+    fitting_decorator: Optional[Callable] = field(default=lambda f: f)
+    """
+    A user provided decorator that wraps the `py:meth:ripple_down_rules.rdr.RippleDownRules.fit_case` method which is 
+    used when in fitting mode, this is useful when you want special logic pre and post the fitting operation, you can
+    for example freeze your system during fitting such that you have a stable state that you can query and use while 
+    writing and testing your answer/rule.
+    """
+    generate_dot_file: bool = field(default=False)
+    """
+    Whether to generate a dynamic dot file representing the state of the rule tree each time the rdr is queried, showing
+    which rules fired and which rules didn't get evaluated, ...etc.
+    """
+    model_name: Optional[str] = field(default=None)
+    """
+    The name of the rdr model, this gets auto generated from the function signature and the class/file it is contained
+    in.
+    """
+    rdr: GeneralRDR = field(init=False)
+    """
+    The ripple down rules instance of the decorator class.
+    """
+    parsed_output_type: List[Type] = field(init=False, default_factory=list)
+    """
+    The output of a post processing done on the output types, for example converting typing module types 
+    (i.e. type hints) to python types.
+    """
+    origin_type: Optional[Type] = field(init=False, default=None)
+    """
+    The origin of the type hint of the attribute, useful in the case of not mutually exclusive attributes to map the 
+    result to the specified container type (e.g. a list instead of a set which is the default container type for rdr
+    output).
+    """
+    output_name: str = field(init=False, default='output_')
+    """
+    This is used to refer to the output value of the decorated function, this is used as part of the case as input to 
+    the rdr model, but is never used in the rule logic to prevent cycles from happening. The correct way to use the 
+    output of an rdr in the rules logic is in the case when mutually exclusive is False, or through refinements of 
+    existing rules when mutually exclusive is True, which happens automatically by the rdr prompting for refinements.
+    """
+    _not_none_output_found: bool = field(init=False, default=False)
+    """
+    This is a flag that indicates that a not None output for the rdr has been inferred, this is used to update the 
+    generated dot file if it is set to `True`.
+    """
 
     def decorator(self, func: Callable) -> Callable:
 
@@ -102,33 +132,33 @@ class RDRDecorator:
                 if len(self.parsed_output_type) == 0:
                     self.parsed_output_type = self.parse_output_type(func, self.output_type, *args)
                 if self.expert is None:
-                    self.expert = Human(answers_save_path=self.rdr_models_dir + f'/{self.model_name}/expert_answers')
+                    self.expert = Human(answers_save_path=self.models_dir + f'/{self.model_name}/expert_answers')
                 case_query = self.create_case_query_from_method(func, func_output,
                                                                 self.parsed_output_type,
                                                                 self.mutual_exclusive,
                                                                 case, case_dict,
                                                                 *args, **kwargs)
                 output = self.rdr.fit_case(case_query, expert=self.expert,
-                                           update_existing_rules=self.update_existing_rules,
-                                           viewer=self.viewer)
+                                           update_existing_rules=self.update_existing_rules)
                 return output
-            
+
             if self.fit and not self.use_generated_classifier and self.ask_now(case_dict):
                 output = fit()
             else:
                 if self.use_generated_classifier:
                     if self.generated_classifier is None:
-                        model_path = os.path.join(self.rdr_models_dir, self.model_name)
+                        model_path = os.path.join(self.models_dir, self.model_name)
                         self.generated_classifier = self.rdr.get_rdr_classifier_from_python_file(model_path)
                     output = self.generated_classifier(case)
                 else:
                     output = self.rdr.classify(case)
                     if self.generate_dot_file:
                         eval_rule_tree = self.rdr.get_evaluated_rule_tree()
-                        if not self.not_none_output_found or (eval_rule_tree and len(eval_rule_tree) > 1):
-                            self.rdr.render_evaluated_rule_tree(self.rdr_models_dir + f'/{self.model_name}', show_full_tree=True)
+                        if not self._not_none_output_found or (eval_rule_tree and len(eval_rule_tree) > 1):
+                            self.rdr.render_evaluated_rule_tree(self.models_dir + f'/{self.model_name}',
+                                                                show_full_tree=True)
                         if eval_rule_tree and len(eval_rule_tree) > 1:
-                            self.not_none_output_found = True
+                            self._not_none_output_found = True
 
             if self.output_name in output:
                 if self.origin_type == list:
@@ -189,7 +219,6 @@ class RDRDecorator:
         return Case(dict, id(case_dict), case_name, case_dict, **case_dict), case_dict
 
     def initialize_rdr_model_name_and_load(self, func: Callable) -> None:
-        self.viewer = RDRCaseViewer.instances[0] if RDRCaseViewer is not None and len(RDRCaseViewer.instances) > 0 else self.viewer
         model_file_name = get_func_rdr_model_name(func, include_file_name=True)
         self.model_name = str_to_snake_case(model_file_name)
         self.load()
@@ -209,20 +238,8 @@ class RDRDecorator:
                 parsed_output_type.append(ot)
         return parsed_output_type
 
-    def save(self):
-        """
-        Save the RDR model to the specified directory.
-        """
-        self.rdr.save(self.rdr_models_dir, self.model_name, package_name=self.package_name)
-
     def load(self):
         """
-        Load the RDR model from the specified directory.
-        """
-        self.rdr = GeneralRDR(save_dir=self.rdr_models_dir, model_name=self.model_name)
-
-    def update_from_python(self):
-        """
-        Update the RDR model from a python file.
+        Load the RDR model from the specified directory, otherwise create a new one.
         """
-        self.rdr.update_from_python(self.rdr_models_dir, parent_package_name=self.package_name)
+        self.rdr = GeneralRDR(save_dir=self.models_dir, model_name=self.model_name)

{ripple_down_rules-0.6.49.dist-info → ripple_down_rules-0.6.50.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.6.49
+Version: 0.6.50
 Summary: Implements the various versions of Ripple Down Rules (RDR) for knowledge representation and reasoning.
 Author-email: Abdelrhman Bassiouny <abassiou@uni-bremen.de>
 License:                     GNU GENERAL PUBLIC LICENSE

{ripple_down_rules-0.6.49.dist-info → ripple_down_rules-0.6.50.dist-info}/RECORD

@@ -1,9 +1,9 @@
-ripple_down_rules/__init__.py,sha256=GyypMGVzsHCBimVk-W61kWH2zma_ldearwOUdhYFOG4,375
+ripple_down_rules/__init__.py,sha256=6EQLRCLTgXJBkkqQ-9rcFfDRgNFPMVqlW-ofOWDjfAY,375
 ripple_down_rules/experts.py,sha256=KXwWCmDrCffu9HW3yNewqWc1e5rnPI5Rnc981w_5M7U,17896
 ripple_down_rules/failures.py,sha256=ZPypPwKjyVcJkY9YG6p538ld8ZzpdW6CrC1RmJi44Ek,42
 ripple_down_rules/helpers.py,sha256=sVU1Q7HPbMh57X8zDYP6vj1maDoaVAvnXHpUYIbr_As,5715
 ripple_down_rules/rdr.py,sha256=M7CEjHIegJWiDZtn-B8Qf9CpMvplAkrFX3HiiyGQC7M,84292
-ripple_down_rules/rdr_decorators.py,sha256=sbrbo5qfhnY9dIge4sFlkn4p8yPNBWWQ1Nq-NvMDx20,11756
+ripple_down_rules/rdr_decorators.py,sha256=H3ONvgTSgL5LS_Nv_hKAYY2nkqvn7KZ1zmIzIDi07dA,11870
 ripple_down_rules/rules.py,sha256=L4Ws-x3g5ljE0GrDt4LAib2qtR1C1_Ra4cRcIB-IQDI,28702
 ripple_down_rules/start-code-server.sh,sha256=otClk7VmDgBOX2TS_cjws6K0UwvgAUJhoA0ugkPCLqQ,949
 ripple_down_rules/utils.py,sha256=5UL4h-m5Q4l7RyCYqmUmDDxUAkFqPYpFa3QldDYoJUE,80752
@@ -18,8 +18,8 @@ ripple_down_rules/user_interface/ipython_custom_shell.py,sha256=GQf5Je5szkPH17g4
 ripple_down_rules/user_interface/object_diagram.py,sha256=FEa2HaYR9QmTE6NsOwBvZ0jqmu3DKyg6mig2VE5ZP4Y,4956
 ripple_down_rules/user_interface/prompt.py,sha256=WPbw_8_-8SpF2ISyRZRuFwPKBEuGC4HaX3lbCPFHhh8,10314
 ripple_down_rules/user_interface/template_file_creator.py,sha256=uSbosZS15MOR3Nv7M3MrFuoiKXyP4cBId-EK3I6stHM,13660
-ripple_down_rules-0.6.49.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
-ripple_down_rules-0.6.49.dist-info/METADATA,sha256=-xhdW2zRfqAdIa_deC_DHETUVV5_8PLWVe0YTDN4VXg,48294
-ripple_down_rules-0.6.49.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ripple_down_rules-0.6.49.dist-info/top_level.txt,sha256=VeoLhEhyK46M1OHwoPbCQLI1EifLjChqGzhQ6WEUqeM,18
-ripple_down_rules-0.6.49.dist-info/RECORD,,
+ripple_down_rules-0.6.50.dist-info/licenses/LICENSE,sha256=ixuiBLtpoK3iv89l7ylKkg9rs2GzF9ukPH7ynZYzK5s,35148
+ripple_down_rules-0.6.50.dist-info/METADATA,sha256=LVOjG94lFcXLJD80mILahLyK1sYrsHEsDogeKg-PBSU,48294
+ripple_down_rules-0.6.50.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ripple_down_rules-0.6.50.dist-info/top_level.txt,sha256=VeoLhEhyK46M1OHwoPbCQLI1EifLjChqGzhQ6WEUqeM,18
+ripple_down_rules-0.6.50.dist-info/RECORD,,