ripple-down-rules 0.0.0__py3-none-any.whl

ripple_down_rules/experts.py

@@ -0,0 +1,281 @@
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+
+from sqlalchemy.orm import DeclarativeBase as SQLTable, MappedColumn as SQLColumn, Session
+from typing_extensions import Optional, Dict, TYPE_CHECKING, List, Tuple, Type, Union, Any
+
+from .datastructures import (Case, PromptFor, CallableExpression, Column, CaseQuery)
+from .datastructures.table import show_current_and_corner_cases
+from .prompt import prompt_user_for_expression, prompt_user_about_case
+from .utils import get_all_subclasses
+
+if TYPE_CHECKING:
+    from .rdr import Rule
+
+
+class Expert(ABC):
+    """
+    The Abstract Expert class, all experts should inherit from this class.
+    An expert is a class that can provide differentiating features and conclusions for a case when asked.
+    The expert can compare a case with a corner case and provide the differentiating features and can also
+    provide one or multiple conclusions for a case.
+    """
+    all_expert_answers: Optional[List] = None
+    """
+    A list of all expert answers, used for testing purposes.
+    """
+    use_loaded_answers: bool = False
+    """
+    A flag to indicate if the expert should use loaded answers or not.
+    """
+    known_categories: Optional[Dict[str, Type[Column]]] = None
+    """
+    The known categories (i.e. Column types) to use.
+    """
+
+    @abstractmethod
+    def ask_for_conditions(self, x: Case, targets: List[Column], last_evaluated_rule: Optional[Rule] = None) \
+            -> CallableExpression:
+        """
+        Ask the expert to provide the differentiating features between two cases or unique features for a case
+        that doesn't have a corner case to compare to.
+
+        :param x: The case to classify.
+        :param targets: The target categories to compare the case with.
+        :param last_evaluated_rule: The last evaluated rule.
+        :return: The differentiating features as new rule conditions.
+        """
+        pass
+
+    @abstractmethod
+    def ask_for_extra_conclusions(self, x: Case, current_conclusions: List[Column]) \
+            -> Dict[Column, CallableExpression]:
+        """
+        Ask the expert to provide extra conclusions for a case by providing a pair of category and conditions for
+        that category.
+
+        :param x: The case to classify.
+        :param current_conclusions: The current conclusions for the case.
+        :return: The extra conclusions for the case.
+        """
+        pass
+
+    @abstractmethod
+    def ask_if_conclusion_is_correct(self, x: Case, conclusion: Column,
+                                     targets: Optional[List[Column]] = None,
+                                     current_conclusions: Optional[List[Column]] = None) -> bool:
+        """
+        Ask the expert if the conclusion is correct.
+
+        :param x: The case to classify.
+        :param conclusion: The conclusion to check.
+        :param targets: The target categories to compare the case with.
+        :param current_conclusions: The current conclusions for the case.
+        """
+        pass
+
+    def ask_for_conclusion(self, case_query: CaseQuery,
+                           session: Optional[Session] = None) -> Optional[CallableExpression]:
+        """
+        Ask the expert to provide a relational conclusion for the case.
+
+        :param case_query: The case query containing the case to find a conclusion for.
+        :param session: The sqlalchemy orm session to use if the case is a Table.
+        :return: A callable expression that can be called with a new case as an argument.
+        """
+
+
+class Human(Expert):
+    """
+    The Human Expert class, an expert that asks the human to provide differentiating features and conclusions.
+    """
+
+    def __init__(self, use_loaded_answers: bool = False, session: Optional[Session] = None):
+        self.all_expert_answers = []
+        self.use_loaded_answers = use_loaded_answers
+        self.session = session
+
+    def save_answers(self, path: str):
+        """
+        Save the expert answers to a file.
+
+        :param path: The path to save the answers to.
+        """
+        with open(path + '.json', "w") as f:
+            json.dump(self.all_expert_answers, f)
+
+    def load_answers(self, path: str):
+        """
+        Load the expert answers from a file.
+
+        :param path: The path to load the answers from.
+        """
+        with open(path + '.json', "r") as f:
+            self.all_expert_answers = json.load(f)
+
+    def ask_for_conditions(self, case: Case,
+                           targets: Union[List[Column], List[Column]],
+                           last_evaluated_rule: Optional[Rule] = None) \
+            -> CallableExpression:
+        if not self.use_loaded_answers:
+            show_current_and_corner_cases(case, targets, last_evaluated_rule=last_evaluated_rule)
+        return self._get_conditions(case, targets)
+
+    def _get_conditions(self, case: Case, targets: List[Column]) \
+            -> CallableExpression:
+        """
+        Ask the expert to provide the differentiating features between two cases or unique features for a case
+        that doesn't have a corner case to compare to.
+
+        :param case: The case to classify.
+        :param targets: The target categories to compare the case with.
+        :return: The differentiating features as new rule conditions.
+        """
+        targets = targets if isinstance(targets, list) else [targets]
+        condition = None
+        for target in targets:
+            target_name = target.__class__.__name__
+            user_input = None
+            if self.use_loaded_answers:
+                user_input = self.all_expert_answers.pop(0)
+            if user_input:
+                condition = CallableExpression(user_input, bool, session=self.session)
+            else:
+                user_input, condition = prompt_user_for_expression(case, PromptFor.Conditions, target_name, bool)
+            if not self.use_loaded_answers:
+                self.all_expert_answers.append(user_input)
+        return condition
+
+    def ask_for_extra_conclusions(self, case: Case, current_conclusions: List[Column]) \
+            -> Dict[Column, CallableExpression]:
+        """
+        Ask the expert to provide extra conclusions for a case by providing a pair of category and conditions for
+        that category.
+
+        :param case: The case to classify.
+        :param current_conclusions: The current conclusions for the case.
+        :return: The extra conclusions for the case.
+        """
+        extra_conclusions = {}
+        while True:
+            category = self.ask_for_conclusion(CaseQuery(case), current_conclusions)
+            if not category:
+                break
+            extra_conclusions[category] = self._get_conditions(case, category)
+        return extra_conclusions
+
+    def ask_for_conclusion(self, case_query: CaseQuery,
+                           current_conclusions: Optional[List[Any]] = None)\
+            -> Optional[CallableExpression]:
+        """
+        Ask the expert to provide a conclusion for the case.
+
+        :param case_query: The case query containing the case to find a conclusion for.
+        :param current_conclusions: The current conclusions for the case if any.
+        :return: The conclusion for the case.
+        """
+        case = case_query.case
+        attribute_name = case_query.attribute_name
+        attribute_type = case_query.attribute_type
+        if self.use_loaded_answers:
+            expert_input = self.all_expert_answers.pop(0)
+            expression = CallableExpression(expert_input, conclusion_type=attribute_type, session=self.session)
+        else:
+            show_current_and_corner_cases(case, current_conclusions=current_conclusions)
+            expert_input, expression = prompt_user_for_expression(case, PromptFor.Conclusion, attribute_name,
+                                                                  attribute_type)
+            self.all_expert_answers.append(expert_input)
+        return expression
+
+    def create_category_instance(self, cat_name: str, cat_value: Union[str, int, float, set]) -> Column:
+        """
+        Create a new category instance.
+
+        :param cat_name: The name of the category.
+        :param cat_value: The value of the category.
+        :return: A new instance of the category.
+        """
+        category_type = self.get_category_type(cat_name)
+        if not category_type:
+            category_type = self.create_new_category_type(cat_name)
+        return category_type(cat_value)
+
+    def get_category_type(self, cat_name: str) -> Optional[Type[Column]]:
+        """
+        Get the category type from the known categories.
+
+        :param cat_name: The name of the category.
+        :return: The category type.
+        """
+        cat_name = cat_name.lower()
+        self.known_categories = get_all_subclasses(Column) if not self.known_categories else self.known_categories
+        self.known_categories.update(Column.registry)
+        category_type = None
+        if cat_name in self.known_categories:
+            category_type = self.known_categories[cat_name]
+        return category_type
+
+    def create_new_category_type(self, cat_name: str) -> Type[Column]:
+        """
+        Create a new category type.
+
+        :param cat_name: The name of the category.
+        :return: A new category type.
+        """
+        if self.ask_if_category_is_mutually_exclusive(cat_name):
+            category_type: Type[Column] = Column.create(cat_name, set(), mutually_exclusive=True)
+        else:
+            category_type: Type[Column] = Column.create(cat_name, set())
+        return category_type
+
+    def ask_if_category_is_mutually_exclusive(self, category_name: str) -> bool:
+        """
+        Ask the expert if the new category can have multiple values.
+
+        :param category_name: The name of the category to ask about.
+        """
+        question = f"Can a case have multiple values of the new category {category_name}? (y/n):"
+        return not self.ask_yes_no_question(question)
+
+    def ask_if_conclusion_is_correct(self, x: Case, conclusion: Column,
+                                     targets: Optional[List[Column]] = None,
+                                     current_conclusions: Optional[List[Column]] = None) -> bool:
+        """
+        Ask the expert if the conclusion is correct.
+
+        :param x: The case to classify.
+        :param conclusion: The conclusion to check.
+        :param targets: The target categories to compare the case with.
+        :param current_conclusions: The current conclusions for the case.
+        """
+        question = ""
+        if not self.use_loaded_answers:
+            targets = targets or []
+            targets = targets if isinstance(targets, list) else [targets]
+            x.conclusions = current_conclusions
+            x.targets = targets
+            question = f"Is the conclusion {conclusion} correct for the case (y/n):" \
+                       f"\n{str(x)}"
+        return self.ask_yes_no_question(question)
+
+    def ask_yes_no_question(self, question: str) -> bool:
+        """
+        Ask the expert a yes or no question.
+
+        :param question: The question to ask.
+        :return: The answer to the question.
+        """
+        if not self.use_loaded_answers:
+            print(question)
+        while True:
+            if self.use_loaded_answers:
+                answer = self.all_expert_answers.pop(0)
+            else:
+                answer = input()
+                self.all_expert_answers.append(answer)
+            if answer.lower() == "y":
+                return True
+            elif answer.lower() == "n":
+                return False

ripple_down_rules/failures.py

@@ -0,0 +1,10 @@
+
+
+class InvalidOperator(Exception):
+    def __init__(self, rule_str: str, valid_operators: list):
+        self.rule_str = rule_str
+        self.valid_operators = valid_operators
+
+    def __str__(self):
+        return f"Invalid operator in {self.rule_str}, valid operators are: {self.valid_operators}"
+

ripple_down_rules/prompt.py

@@ -0,0 +1,101 @@
+import ast
+import logging
+from _ast import AST
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import WordCompleter
+from sqlalchemy.orm import DeclarativeBase as SQLTable, Session
+from typing_extensions import Any, List, Optional, Tuple, Dict, Union, Type
+
+from .datastructures import Case, PromptFor, CallableExpression, create_row, parse_string_to_expression
+
+
+def prompt_user_for_expression(case: Union[Case, SQLTable], prompt_for: PromptFor, target_name: str,
+                               output_type: Type, session: Optional[Session] = None) -> Tuple[str, CallableExpression]:
+    """
+    Prompt the user for an executable python expression.
+
+    :param case: The case to classify.
+    :param prompt_for: The type of information ask user about.
+    :param target_name: The name of the target attribute to compare the case with.
+    :param output_type: The type of the output of the given statement from the user.
+    :param session: The sqlalchemy orm session.
+    :return: A callable expression that takes a case and executes user expression on it.
+    """
+    while True:
+        user_input, expression_tree = prompt_user_about_case(case, prompt_for, target_name)
+        callable_expression = CallableExpression(user_input, output_type, expression_tree=expression_tree, session=session)
+        try:
+            callable_expression(case)
+            break
+        except Exception as e:
+            logging.error(e)
+            print(e)
+    return user_input, callable_expression
+
+
+def prompt_user_about_case(case: Union[Case, SQLTable], prompt_for: PromptFor, target_name: str) \
+        -> Tuple[str, AST]:
+    """
+    Prompt the user for input.
+
+    :param case: The case to prompt the user on.
+    :param prompt_for: The type of information the user should provide for the given case.
+    :param target_name: The name of the target property of the case that is queried.
+    :return: The user input, and the executable expression that was parsed from the user input.
+    """
+    prompt_str = f"Give {prompt_for} for {case.__class__.__name__}.{target_name}"
+    session = get_prompt_session_for_obj(case)
+    user_input, expression_tree = prompt_user_input_and_parse_to_expression(prompt_str, session)
+    return user_input, expression_tree
+
+
+def get_completions(obj: Any) -> List[str]:
+    """
+    Get all completions for the object. This is used in the python prompt shell to provide completions for the user.
+
+    :param obj: The object to get completions for.
+    :return: A list of completions.
+    """
+    # Define completer with all object attributes and comparison operators
+    completions = ['==', '!=', '>', '<', '>=', '<=', 'in', 'not', 'and', 'or', 'is']
+    completions += ["isinstance(", "issubclass(", "type(", "len(", "hasattr(", "getattr(", "setattr(", "delattr("]
+    completions += list(create_row(obj).keys())
+    return completions
+
+
+def prompt_user_input_and_parse_to_expression(prompt: Optional[str] = None, session: Optional[PromptSession] = None,
+                                              user_input: Optional[str] = None) -> Tuple[str, ast.AST]:
+    """
+    Prompt the user for input.
+
+    :param prompt: The prompt to display to the user.
+    :param session: The prompt session to use.
+    :param user_input: The user input to use. If given, the user input will be used instead of prompting the user.
+    :return: The user input and the AST tree.
+    """
+    while True:
+        if not user_input:
+            user_input = session.prompt(f"\n{prompt} >>> ")
+        if user_input.lower() in ['exit', 'quit', '']:
+            break
+        try:
+            return user_input, parse_string_to_expression(user_input)
+        except Exception as e:
+            msg = f"Error parsing expression: {e}"
+            logging.error(msg)
+            print(msg)
+            user_input = None
+
+
+def get_prompt_session_for_obj(obj: Any) -> PromptSession:
+    """
+    Get a prompt session for an object.
+
+    :param obj: The object to get the prompt session for.
+    :return: The prompt session.
+    """
+    completions = get_completions(obj)
+    completer = WordCompleter(completions)
+    session = PromptSession(completer=completer)
+    return session