rulelearn-ripper-interactive 0.2.3__py3-none-any.whl

rulelearn_ri/algorithms/ripper/single_rule.py

@@ -0,0 +1,425 @@
+import numpy as np
+from pandas import DataFrame, Series
+
+from rulelearn_ri.algorithms.ripper.base import _encoding_for_parallel, init_encoder, encode_nominal, \
+    _split_instances
+from rulelearn_ri.algorithms.ripper.binding import _find_best_literal, Literal, LE, GE, EQ, _bind_literal, \
+    _filter_contradicted_instances, append_literal, _bind_rule
+from rulelearn_ri.algorithms.ripper.pruning import _pruning_irep
+
+from rulelearn_ri.trxf.core import Conjunction
+from rulelearn_ri.trxf.core import Feature
+from rulelearn_ri.trxf.core import Predicate, Relation
+
+
+def optimize_single_rule(
+        train: DataFrame,
+        y: Series,
+        target_label,
+        fixed_attributes=None,
+        fixed_predicates=None,
+        forbidden_attributes=None,
+        pruning_threshold: int = 20,
+        random_state: int = 0,
+        ratio: float = 2 / 3,
+):
+    """
+    Optimize a single conjunctive rule for the given target label.
+
+    Optionally, certain features can be forced to appear in the rule via ``fixed_attributes``,
+    and/or certain whole predicates (with fixed boundaries) can be given via ``fixed_predicates``.
+    Both can be specified together; attributes already covered by fixed_predicates are skipped.
+    Conversely, ``forbidden_attributes`` lists features that must NOT appear in the rule; these
+    must not overlap with the forced attributes or predicates, otherwise a ValueError is raised.
+    The algorithm grows additional literals and prunes to produce a single optimized rule.
+
+    Args:
+        train (pd.DataFrame): Training features
+        y (pd.Series): Training labels
+        target_label: The positive class label for the rule; must be one of the values in ``y``
+        fixed_attributes (list of str, optional): Column names that must appear in the rule
+        fixed_predicates (list of Predicate, optional): Predicates that must be included as-is
+        forbidden_attributes (list of str, optional): Column names that must not appear in the rule
+        pruning_threshold (int): Minimum instances for grow/prune split. Defaults to 20.
+        random_state (int): Random seed for data splitting. Defaults to 0.
+        ratio (float): Fraction of data for growing. Defaults to 2/3.
+
+    Returns:
+        Conjunction: The optimized rule as a TRXF Conjunction
+
+    Raises:
+        ValueError: If ``target_label`` does not occur in ``y`` (e.g. no positive instances, or a label
+            of the wrong type such as ``'True'`` for a boolean ``y``), mirroring ``RipperExplainer.fit``
+    """
+    labels = np.unique(y).tolist()
+    if target_label not in labels:
+        raise ValueError('target_label {!r} not found in y (values: {})'.format(target_label, labels))
+
+    train = train.copy()
+    y = y.copy()
+
+    nominal_encoders = init_encoder(train)
+    encode_nominal(nominal_encoders, train)
+    column_name_list = train.columns.values
+    column_name_index_map = {name: idx for idx, name in enumerate(column_name_list)}
+    condition_mat = _encoding_for_parallel(train, column_name_index_map)
+
+    # Build the unified forced feature set and optional predefined rule
+    forced_literals = []
+    forced_features = set()
+    if fixed_predicates is not None:
+        forced_literals = _predicates_to_literals(
+            fixed_predicates, column_name_index_map, nominal_encoders)
+        forced_features = set(lit.name for lit in forced_literals)
+
+    required_features = set()
+    if fixed_attributes is not None:
+        required_features = set(column_name_index_map[attr]
+                                for attr in fixed_attributes)
+
+    forbidden_features = set()
+    if forbidden_attributes is not None:
+        forbidden_features = set(column_name_index_map[attr]
+                                 for attr in forbidden_attributes)
+
+    _validate_forbidden_clash(column_name_list, forbidden_features,
+                              required_features | forced_features)
+
+    train_arr = train.to_numpy(dtype=np.float64)
+    y_arr = y.values if isinstance(y, Series) else np.array(y)
+
+    pos = train_arr[y_arr == target_label]
+    neg = train_arr[y_arr != target_label]
+
+    neg = _filter_contradicted_instances(pos, neg)
+
+    if len(pos) == 0:
+        return Conjunction([])
+
+    # fixed_predicates already cover some attributes -- skip those
+    remaining_required_features = required_features - forced_features
+
+    has_predicates = len(forced_literals) > 0
+    has_remaining_attrs = len(remaining_required_features) > 0
+
+    if len(pos) > pruning_threshold:
+        pos_grow, pos_prune, neg_grow, neg_prune = _split_instances(
+            pos, neg, ratio, random_state)
+    else:
+        pos_grow = pos_prune = pos
+        neg_grow = neg_prune = neg
+
+    if has_predicates:
+        # Grow from fixed predicates first
+        rule = _grow_rule_standalone(
+            pos_grow, neg_grow, condition_mat, predefined_rule=forced_literals,
+            forbidden_features=forbidden_features)
+
+        if has_remaining_attrs:
+            # Bind data to the rule so far, then force-include remaining attributes
+            pos_bound = pos_grow
+            neg_bound = neg_grow
+            for lit in rule:
+                pos_bound = _bind_literal(pos_bound, lit.name, lit.op,
+                                          lit.num_val, lit.nom_val)
+                neg_bound = _bind_literal(neg_bound, lit.name, lit.op,
+                                          lit.num_val, lit.nom_val)
+            rule = _grow_rule_with_required_features(
+                pos_bound, neg_bound, remaining_required_features,
+                condition_mat, learned_rule=rule,
+                forbidden_features=forbidden_features)
+    elif has_remaining_attrs:
+        # Attributes only — grow from scratch forcing required features
+        rule = _grow_rule_with_required_features(
+            pos_grow, neg_grow, required_features, condition_mat,
+            forbidden_features=forbidden_features)
+    else:
+        # Unconstrained — standard grow
+        rule = _grow_rule_standalone(
+            pos_grow, neg_grow, condition_mat,
+            forbidden_features=forbidden_features)
+
+    # All forced features (from both predicates and attributes)
+    all_forced = forced_features | required_features
+
+    if len(all_forced) > 0:
+        rule = _prune_keeping_forced(pos_prune, neg_prune, rule, all_forced)
+    else:
+        rule = _pruning_irep(pos_prune, neg_prune, rule)
+
+    return _rule_to_trxf_conjunction(rule, column_name_list, nominal_encoders)
+
+
+def _predicates_to_literals(predicates, column_name_index_map, nominal_encoders):
+    """
+    Convert TRXF Predicate objects to internal Literal objects.
+    """
+    literals = []
+    for pred in predicates:
+        name = pred.feature.variable_names[0]
+        col_idx = column_name_index_map[name]
+        relation = pred.relation
+
+        if relation == Relation.EQ:
+            if name in nominal_encoders:
+                label_map = {val: label for label, val in
+                             enumerate(nominal_encoders[name].classes_)}
+                nom_val = label_map[pred.value]
+            else:
+                nom_val = int(pred.value)
+            literals.append(Literal(col_idx, EQ, -1, nom_val))
+        elif relation == Relation.LE:
+            literals.append(Literal(col_idx, LE, pred.value, -1))
+        elif relation == Relation.GE:
+            literals.append(Literal(col_idx, GE, pred.value, -1))
+        else:
+            raise ValueError(
+                'Unsupported relation {} for fixed_predicates. '
+                'Only EQ, LE, GE are supported.'.format(relation))
+    return literals
+
+
+def _validate_forbidden_clash(column_name_list, forbidden_features, forced_features):
+    """
+    Ensure that forbidden features do not overlap with features that are
+    forced via fixed_attributes or fixed_predicates.
+    """
+    clash = forbidden_features & forced_features
+    if clash:
+        names = [column_name_list[idx] for idx in sorted(clash)]
+        raise ValueError(
+            'forbidden_attributes must not overlap with fixed_attributes or '
+            'fixed_predicates. Conflicting column(s): {}'.format(', '.join(names)))
+
+
+def _exclude_features(condition_mat, forbidden_features):
+    """
+    Return the condition matrices with literals of forbidden features removed.
+    Returns None when no allowed literals remain.
+    """
+    if not forbidden_features:
+        return condition_mat
+    mask = ~np.isin(condition_mat[0], list(forbidden_features))
+    if not mask.any():
+        return None
+    return [arr[mask] for arr in condition_mat]
+
+
+def _grow_rule_standalone(pos, neg, condition_mat, predefined_rule=None,
+                          forbidden_features=None):
+    """
+    Standalone version of RIPPER's grow rule, parameterized by condition_mat.
+    """
+    if len(pos) == 0:
+        raise AssertionError('pos must not be empty')
+
+    neg = _filter_contradicted_instances(pos, neg)
+
+    if predefined_rule is not None:
+        pos = _bind_rule(pos, predefined_rule)
+        neg = _bind_rule(neg, predefined_rule)
+        if len(pos) == 0 or len(neg) == 0:
+            return list(predefined_rule)
+        learned_rule = list(predefined_rule)
+    else:
+        learned_rule = []
+
+    grow_mat = _exclude_features(condition_mat, forbidden_features)
+
+    while len(neg) > 0:
+        if grow_mat is None or len(pos) == 0:
+            break
+        pos = np.asfortranarray(pos)
+        neg = np.asfortranarray(neg)
+        prev_pos_len = len(pos)
+        prev_neg_len = len(neg)
+
+        best_literal_index = _find_best_literal(
+            pos, neg,
+            grow_mat[0], grow_mat[1],
+            grow_mat[2], grow_mat[3]
+        )
+        literal = Literal(
+            grow_mat[0][best_literal_index],
+            grow_mat[1][best_literal_index],
+            grow_mat[2][best_literal_index],
+            grow_mat[3][best_literal_index]
+        )
+        new_pos = _bind_literal(pos, literal.name, literal.op,
+                                literal.num_val, literal.nom_val)
+        new_neg = _bind_literal(neg, literal.name, literal.op,
+                                literal.num_val, literal.nom_val)
+
+        # a literal that filters neither set only restricts unseen data
+        if len(new_pos) == len(pos) and len(new_neg) == len(neg):
+            break
+        append_literal(learned_rule, literal)
+        pos, neg = new_pos, new_neg
+
+        if len(pos) == prev_pos_len and len(neg) == prev_neg_len:
+            break
+
+    return learned_rule
+
+
+def _grow_rule_with_required_features(pos, neg, required_features, condition_mat,
+                                     learned_rule=None, forbidden_features=None):
+    """
+    Grow a rule ensuring that every feature in ``required_features``
+    (a set of column indices) appears in the rule.
+
+    When ``learned_rule`` is given, literals are appended to it and
+    filtering of contradicting instances is skipped (caller is responsible).
+
+    Phase 1: restrict literal selection to remaining required features.
+    Phase 2: grow freely to eliminate remaining negatives, excluding any
+    forbidden features.
+    """
+    if len(pos) == 0:
+        raise AssertionError('pos must not be empty')
+
+    if learned_rule is None:
+        neg = _filter_contradicted_instances(pos, neg)
+        learned_rule = []
+    remaining = set(required_features)
+
+    # Phase 1: force-include required features (one literal each)
+    while remaining and len(neg) > 0:
+        mask = np.isin(condition_mat[0], list(remaining))
+        if not mask.any():
+            break
+        filtered_mat = [arr[mask] for arr in condition_mat]
+
+        pos_f = np.asfortranarray(pos)
+        neg_f = np.asfortranarray(neg)
+        best_idx = _find_best_literal(
+            pos_f, neg_f,
+            filtered_mat[0], filtered_mat[1],
+            filtered_mat[2], filtered_mat[3]
+        )
+        literal = Literal(
+            filtered_mat[0][best_idx],
+            filtered_mat[1][best_idx],
+            filtered_mat[2][best_idx],
+            filtered_mat[3][best_idx]
+        )
+        append_literal(learned_rule, literal)
+        remaining.discard(literal.name)
+
+        pos = _bind_literal(pos, literal.name, literal.op,
+                            literal.num_val, literal.nom_val)
+        neg = _bind_literal(neg, literal.name, literal.op,
+                            literal.num_val, literal.nom_val)
+
+        if len(pos) == 0:
+            break
+
+    # Phase 1b: force-include any remaining required features even if
+    # negatives are already eliminated (user explicitly requested them)
+    for feat_idx in sorted(remaining):
+        mask = condition_mat[0] == feat_idx
+        if not mask.any():
+            continue
+        filtered_mat = [arr[mask] for arr in condition_mat]
+
+        pos_f = np.asfortranarray(pos)
+        neg_f = np.asfortranarray(neg)
+        best_idx = _find_best_literal(
+            pos_f, neg_f,
+            filtered_mat[0], filtered_mat[1],
+            filtered_mat[2], filtered_mat[3]
+        )
+        literal = Literal(
+            filtered_mat[0][best_idx],
+            filtered_mat[1][best_idx],
+            filtered_mat[2][best_idx],
+            filtered_mat[3][best_idx]
+        )
+        append_literal(learned_rule, literal)
+
+        pos = _bind_literal(pos, literal.name, literal.op,
+                            literal.num_val, literal.nom_val)
+        neg = _bind_literal(neg, literal.name, literal.op,
+                            literal.num_val, literal.nom_val)
+
+    # Phase 2: grow freely
+    grow_mat = _exclude_features(condition_mat, forbidden_features)
+
+    while len(neg) > 0:
+        if grow_mat is None or len(pos) == 0:
+            break
+        pos = np.asfortranarray(pos)
+        neg = np.asfortranarray(neg)
+        prev_pos_len = len(pos)
+        prev_neg_len = len(neg)
+
+        best_idx = _find_best_literal(
+            pos, neg,
+            grow_mat[0], grow_mat[1],
+            grow_mat[2], grow_mat[3]
+        )
+        literal = Literal(
+            grow_mat[0][best_idx],
+            grow_mat[1][best_idx],
+            grow_mat[2][best_idx],
+            grow_mat[3][best_idx]
+        )
+        new_pos = _bind_literal(pos, literal.name, literal.op,
+                                literal.num_val, literal.nom_val)
+        new_neg = _bind_literal(neg, literal.name, literal.op,
+                                literal.num_val, literal.nom_val)
+
+        # a literal that filters neither set only restricts unseen data
+        if len(new_pos) == len(pos) and len(new_neg) == len(neg):
+            break
+        append_literal(learned_rule, literal)
+        pos, neg = new_pos, new_neg
+
+        if len(pos) == prev_pos_len and len(neg) == prev_neg_len:
+            break
+
+    return learned_rule
+
+
+def _prune_keeping_forced(pos_prune, neg_prune, rule, forced_features):
+    """
+    Prune only the non-forced literals. Forced literals are bound first
+    to restrict the data, then pruning applies to the free suffix.
+    """
+    forced = [lit for lit in rule if lit.name in forced_features]
+    free = [lit for lit in rule if lit.name not in forced_features]
+
+    bound_pos = pos_prune
+    bound_neg = neg_prune
+    for lit in forced:
+        bound_pos = _bind_literal(bound_pos, lit.name, lit.op,
+                                  lit.num_val, lit.nom_val)
+        bound_neg = _bind_literal(bound_neg, lit.name, lit.op,
+                                  lit.num_val, lit.nom_val)
+
+    if len(free) == 0:
+        return forced
+
+    pruned_free = _pruning_irep(bound_pos, bound_neg, free)
+    return forced + pruned_free
+
+
+def _rule_to_trxf_conjunction(rule, column_name_list, nominal_encoders):
+    """
+    Convert a list of Literal objects to a TRXF Conjunction.
+    """
+    conjunction = Conjunction([])
+    for lit in rule:
+        name = column_name_list[lit.name]
+        feature = Feature(name)
+        if lit.op == EQ:
+            relation = Relation.EQ
+            value = nominal_encoders[name].classes_[lit.nom_val]
+        elif lit.op == LE:
+            relation = Relation.LE
+            value = lit.num_val
+        else:
+            relation = Relation.GE
+            value = lit.num_val
+        conjunction.add_predicate(Predicate(feature, relation, value))
+    return conjunction

rulelearn_ri/dise.py

@@ -0,0 +1,64 @@
+# Directly interpretable supervised explainers
+
+import abc
+import sys
+
+# Ensure compatibility with Python 2/3
+if sys.version_info >= (3, 4):
+    ABC = abc.ABC
+else:
+    ABC = abc.ABCMeta(str('ABC'), (), {})
+
+
+class DISExplainer(ABC):
+    """
+    DISExplainer is the base class for Directly Interpretable Supervised Explainers (DISE).
+    Such explainers attempt to train explainable models directly from data.
+    Examples include Boolean Decision Rules via Column Generation[#1]_, Generalized Linear Rule Models[#2]_,
+    TED: Teaching AI to Explain its Decisions[#3]_, etc.
+
+    References:
+        .. [#1] Boolean Decision Rules via Column Generation, NIPS 2018.
+        Dash, Gunluk, Wei. https://arxiv.org/abs/1805.09901
+        .. [#2] Generalized Linear Rule Models, ICML 2019.
+        Dennis Wei, Sanjeeb Dash, Tian Gao, Oktay Gunluk.
+        https://arxiv.org/abs/1906.01761
+        .. [#3] TED: Teaching AI to Explain its Decisions, AIES 2019.
+        Michael Hind, Dennis Wei, Murray Campbell, Noel C. F. Codella, Amit Dhurandhar,
+        Aleksandra Mojsilovic, Karthikeyan Natesan Ramamurthy, Kush R. Varshney.
+        https://arxiv.org/abs/1811.04896
+    """
+
+    def __init__(self, *argv, **kwargs):
+        """
+        Initialize a DISExplainer object.
+        ToDo: check common steps that need to be distilled here.
+        """
+
+    @abc.abstractmethod
+    def set_params(self, *argv, **kwargs):
+        """
+        Set parameters for the explainer.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def explain(self, *argv, **kwargs):
+        """
+        Explain the model
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def fit(self, *argv, **kwargs):
+        """
+        Fit a model on data.
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def predict(self, *argv, **kwargs):
+        """
+        Prediction for a batch of inputs (numpy array)
+        """
+        raise NotImplementedError

rulelearn_ri/trxf/classifier/ruleset_classifier.py

@@ -0,0 +1,153 @@
+import enum
+from collections import namedtuple
+from typing import Dict, List, Any
+
+import pandas as pd
+
+from rulelearn_ri.trxf.core.dnf_ruleset import DnfRuleSet
+from rulelearn_ri.trxf.metrics import compute_rule_metrics
+
+Rule = namedtuple('Rule', ['conjunction', 'label', 'record_count', 'nb_correct', 'confidence', 'weight'])
+
+
+class RuleSelectionMethod(enum.Enum):
+    FIRST_HIT = enum.auto()
+    WEIGHTED_MAX = enum.auto()
+    WEIGHTED_SUM = enum.auto()
+
+
+class ConfidenceMetric(enum.Enum):
+    LAPLACE = enum.auto()
+    ACCURACY = enum.auto()
+    CONSTANT = enum.auto()
+
+
+class WeightMetric(enum.Enum):
+    CONFIDENCE = enum.auto()
+    CONSTANT = enum.auto()
+
+
+class RuleSetClassifier:
+    """
+    This class implements a simple classifier constructed from a list of DNF rule sets.
+    Based on the specified RuleSelectionMethod, this classifier predicts the label for a given input.
+    """
+
+    def __init__(self,
+                 rule_sets: List[DnfRuleSet],
+                 rule_selection_method: RuleSelectionMethod,
+                 confidence_metric: ConfidenceMetric = None,
+                 weight_metric: WeightMetric = None,
+                 default_label: Any = None):
+        """
+        @param rule_sets: A list of dnf rule sets
+        @param rule_selection_method: Conflict resolution strategy for multiple fired rules
+        @param confidence_metric: Rule confidence definition to use
+        @param weight_metric: Rule weight definition to use depending on RuleSelectionMethod
+        @param default_label: Optional default label to be returned when no rule set matches the data input.
+        """
+        self._rule_sets = rule_sets
+        self._rule_selection_method = rule_selection_method
+        self._default_label = default_label
+        self._confidence_metric = confidence_metric
+        self._weight_metric = weight_metric
+        self._rules = [Rule(conjunction=c,
+                            label=ruleset.then_part,
+                            record_count=None,
+                            nb_correct=None,
+                            confidence=None,
+                            weight=None)
+                       for ruleset in self._rule_sets for c in ruleset.conjunctions]
+
+    @property
+    def rules(self):
+        return self._rules
+
+    @property
+    def rule_selection_method(self):
+        return self._rule_selection_method
+
+    @property
+    def default_label(self):
+        return self._default_label
+
+    def update_rules_with_metrics(self, X: pd.DataFrame, y: pd.Series) -> None:
+        """
+        Compute rule level metrics for the provided input, and update the Rules with them
+        @param X: pandas data frame to compute required confidence score for PMML exported rules
+        @param y: pandas series to hold labels to compute required confidence score for PMML exported rules
+        """
+        new_rules = []
+        for rule_set in self._rule_sets:
+            metric_list = compute_rule_metrics(rule_set, X, y)
+            for rule in metric_list:
+                confidence = self._compute_confidence(rule)
+                weight = self._compute_weight(rule)
+                new_rules.append(
+                    Rule(conjunction=rule.conjunction, label=rule_set.then_part, record_count=rule.n_records,
+                         nb_correct=rule.n_correct, confidence=confidence, weight=weight))
+        self._rules = new_rules
+
+    def predict(self, assignment: Dict[str, Any]) -> Any:
+        """
+        Predict the label for the given assignment
+        @param assignment: A valuation of the variables that occur in the rule sets
+        """
+        if self.rule_selection_method == RuleSelectionMethod.FIRST_HIT:
+            for rule in self.rules:
+                if rule.conjunction.evaluate(assignment):
+                    return rule.label
+            return self.default_label
+        elif self.rule_selection_method == RuleSelectionMethod.WEIGHTED_SUM:
+            assert self.rules[0].weight is not None
+            label_weights = {}
+            for rule in self.rules:
+                if rule.label not in label_weights:
+                    label_weights[rule.label] = rule.weight
+                else:
+                    label_weights[rule.label] += rule.weight
+            return max(label_weights, key=label_weights.get)
+        elif self.rule_selection_method == RuleSelectionMethod.WEIGHTED_MAX:
+            assert self.rules[0].weight is not None
+            label_weights = {}
+            for rule in self.rules:
+                if rule.label not in label_weights:
+                    label_weights[rule.label] = rule.weight
+                else:
+                    label_weights[rule.label] = max(rule.weight, label_weights[rule.label])
+            return max(label_weights, key=label_weights.get)
+        else:
+            raise ValueError("Unknown rule selection method: {}".format(self.rule_selection_method))
+
+    def _compute_confidence(self, rule):
+        if self._confidence_metric is None:
+            confidence = None
+        elif self._confidence_metric == ConfidenceMetric.LAPLACE:
+            confidence = rule.laplace_estimate
+        elif self._confidence_metric == ConfidenceMetric.ACCURACY:
+            confidence = rule.n_correct / rule.n_records
+        elif self._confidence_metric == ConfidenceMetric.CONSTANT:
+            confidence = 1
+        else:
+            raise ValueError("Unknown confidence metric: {}".format(self._confidence_metric))
+        return confidence
+
+    def _compute_weight(self, rule):
+        if self._weight_metric == WeightMetric.CONFIDENCE:
+            weight = self._compute_confidence(rule)
+        elif self._weight_metric == WeightMetric.CONSTANT:
+            weight = 1
+        else:
+            raise ValueError("Unknown weight metric: {}".format(self._weight_metric))
+        return weight
+
+    def __repr__(self):
+        return '%s(%r, %r)' % (self.__class__, self._rule_sets, self._default_label)
+
+    def __str__(self):
+        body = '\n'.join([str(rule_set) for rule_set in self._rule_sets])
+        else_clause = 'else ' + str(self.default_label)
+        return '\n'.join([body, else_clause])
+
+    def __eq__(self, other):
+        return (self._rule_sets == other.rule_sets) and (self.default_label == other.default_label)

rulelearn_ri/trxf/core/__init__.py

@@ -0,0 +1,5 @@
+from .conjunction import Conjunction
+from .predicate import Relation, Predicate
+from .feature import Feature
+from .dnf_ruleset import DnfRuleSet
+from .ruleset_generator import RuleSetGenerator

rulelearn_ri/trxf/core/boolean_evaluator.py

@@ -0,0 +1,15 @@
+import abc
+from typing import Dict, Any
+
+
+class BooleanEvaluator(metaclass=abc.ABCMeta):
+    @classmethod
+    def __subclasshook__(cls, subclass):
+        return callable(subclass.evaluate)
+
+    @abc.abstractmethod
+    def evaluate(self, assignment: Dict[str, Any]) -> bool:
+        """
+        Evaluate the truth value w.r.t. the variable assignment
+        """
+        raise NotImplementedError