ripple-down-rules 0.6.49__tar.gz → 0.6.51__tar.gz

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.6.49
+Version: 0.6.51
 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 → ripple_down_rules-0.6.51}/doc/intro.md

@@ -13,7 +13,7 @@ SCRDR, MCRDR, and GRDR logic were inspired from the book:
 ["Ripple Down Rules: An Alternative to Machine Learning"](https://www.taylorfrancis.com/books/mono/10.1201/9781003126157/ripple-rules-paul-compton-byeong-ho-kang) by Paul Compton, Byeong Ho Kang.
 
 
-## 🚀 Enhanced Ripple-Down Rules Engine – Key Features
+## 🚀 Key Features
 
 ### 🧠 Data Model (Ontology) + Rule Base as One Entity
 - 🧬 Unified data structure: Data Model (Ontology) and rules use the same Python data structures. 

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/doc/relational_example_tutorial.md

@@ -73,7 +73,7 @@ from ripple_down_rules import CaseQuery, GeneralRDR
 
 grdr = GeneralRDR(save_dir='./', model_name='part_containment_rdr')
 
-case_query = CaseQuery(robot, "contained_objects", (PhysicalObject,), False)
+case_query = CaseQuery(robot, "contained_objects", (PhysicalObject,), mutually_exclusive=False)
 ```
 
 ### Fit the Model to the Case Query by Answering the prompts.
@@ -83,7 +83,7 @@ grdr.fit_case(case_query)
 
 When prompted to write a rule, I press edit in GUI (or type %edit in the Ipython interface if not using GUI),
 I wrote the following inside the template function that the Ripple Down Rules created for me, this function takes a
-`case` object as input:
+`case` object as input, in this exampke the case is the `Robot` instance:
 
 ```python
 contained_objects = []

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/doc/relational_example_with_decorator_tutorial.md

@@ -86,7 +86,7 @@ assert contained_objects == [part_b]
 
 When prompted to write a rule, I press edit in GUI (or type %edit in the Ipython interface if not using GUI),
 I wrote the following inside the template function that the Ripple Down Rules created for me, this function takes a
-`case` object as input:
+`case` object as input, in this exampke the case is the `Robot` instance:
 
 ```python
 contained_objects = []
@@ -114,8 +114,10 @@ This means that the rule will only be applied if the robot has parts.
 We can let the fit mode be `True`, but give the rdr a function that tells it when to prompt for an answer.
 For example, we can ask for an answer only when the robot's name is "tracy", which will result in the rdr not asking 
 for an answer because the robot name is "pr2" for the current case.
-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.
+The {py:attr}`ripple_down_rules.rdr_decorators.RDRDecorator.ask_now` is 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.
 ```python
 robot.containment_rdr.fit = True
 robot.containment_rdr.ask_now = lambda case: case['self_'].name == "tracy"

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/src/ripple_down_rules/__init__.py

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

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/src/ripple_down_rules/datastructures/callable_expression.py

@@ -130,8 +130,10 @@ class CallableExpression(SubclassJSONSerializer):
                 conclusion_type = (conclusion_type,)
         self.conclusion_type = conclusion_type
         self.expected_types: Set[Type] = set(conclusion_type) if conclusion_type is not None else set()
-        if not mutually_exclusive:
-            self.expected_types.update({list, set})
+        if list in self.expected_types:
+            self.expected_types.remove(list)
+        if set in self.expected_types:
+            self.expected_types.add(set)
         self.scope: Optional[Dict[str, Any]] = scope if scope is not None else {}
         self.scope = get_used_scope(self.user_input, self.scope)
         self.expression_tree: AST = expression_tree if expression_tree else parse_string_to_expression(self.user_input)
@@ -149,6 +151,8 @@ class CallableExpression(SubclassJSONSerializer):
 
     def __call__(self, case: Any, **kwargs) -> Any:
         try:
+            # if not self.mutually_exclusive:
+            #     self.expected_types.update({list, set})
             if self.user_input is not None:
                 if not isinstance(case, Case):
                     case = create_case(case, max_recursion_idx=3)
@@ -160,7 +164,6 @@ class CallableExpression(SubclassJSONSerializer):
                     if self.mutually_exclusive and issubclass(type(output), (list, set)):
                         raise ValueError(f"Mutually exclusive types cannot be lists or sets, got {type(output)}")
                     output_types = {type(o) for o in make_list(output)}
-                    output_types.add(type(output))
                     if not are_results_subclass_of_types(output_types, self.expected_types):
                         raise ValueError(f"Not all result types {output_types} are subclasses of expected types"
                                          f" {self.conclusion_type}")

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/src/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,91 @@ 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 is through refinement rules 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 +131,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 +218,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 +237,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 → ripple_down_rules-0.6.51}/src/ripple_down_rules.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ripple_down_rules
-Version: 0.6.49
+Version: 0.6.51
 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 → ripple_down_rules-0.6.51}/test/test_rdr_decorators.py

@@ -14,7 +14,6 @@ class RDRDecoratorsTestCase(unittest.TestCase):
         self.physical_object._is_a_robot_rdr.fit = False
         self.assertFalse(self.physical_object.is_a_robot())
         self.assertTrue(self.robot.is_a_robot())
-        self.physical_object._is_a_robot_rdr.save()
 
     def test_select_objects_that_are_parts_of_robots(self):
         self.physical_object._select_parts_rdr.fit = False
@@ -24,4 +23,3 @@ class RDRDecoratorsTestCase(unittest.TestCase):
             self.assertIn(part, self.robot.parts)
         self.assertNotIn(self.part_3, selected_parts)
         self.assertNotIn(self.robot, selected_parts)
-        self.physical_object._select_parts_rdr.save()

{ripple_down_rules-0.6.49 → ripple_down_rules-0.6.51}/test/test_rdr_helpers_rdrs.py

@@ -11,8 +11,7 @@ save_dir = join(dirname(__file__), '..', 'src', 'ripple_down_rules')
 # viewer = RDRCaseViewer(save_dir=save_dir)
 viewer = None
 rdr_decorator: RDRDecorator = RDRDecorator(save_dir, (bool,), True,
-                                           fit=False,
-                                           viewer=viewer)
+                                           fit=False)
 
 
 @rdr_decorator.decorator