kele 0.0.1a2__cp314-cp314-win_amd64.whl → 0.0.1b1__cp314-cp314-win_amd64.whl

kele/_version.py

@@ -1 +1 @@
-version = "0.0.1a2"
+version = "0.0.1b1"

kele/config.py

@@ -50,7 +50,12 @@ class InferenceStrategyConfig:
     select_rules_num: int | Literal[-1] = -1  # Number of rules to select.
     select_facts_num: int | Literal[-1] = -1  # Number of facts to select; -1 means all facts.
     # premise_selection_strategy: Literal[''] = ''  # Premise selection algorithm. TODO: Unused.
-    grounding_rule_strategy: Literal['SequentialCyclic', 'SequentialCyclicWithPriority'] = "SequentialCyclic"  # Rule selection strategy in grounding.
+    grounding_rule_strategy: Literal[
+        'SequentialCyclic',
+        'SequentialCyclicWithPriority',
+        'SccSort',
+        'ReverseSccSort'
+    ] = "SequentialCyclic"  # Rule selection strategy in grounding.
     # executing_sort_strategy: Literal[''] = ''  # Execution order strategy. TODO: Unused.
     grounding_term_strategy: Literal['Exhausted'] = "Exhausted"  # Term selection strategy in grounding.
     question_rule_interval: int = 1  # Insert a question rule every N rules; -1 uses total rule count as the interval.

kele/control/builtin_hooks.py

@@ -1,24 +1,30 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
+
+from kele.utils import format_mapping
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Mapping
 
-    from kele.grounder import GroundedRule
     from kele.grounder.grounded_rule_ds._nodes import _AssertionNode
-    from kele.syntax import CompoundTerm, Constant, Rule, Variable
+    from kele.syntax import CompoundTerm, Constant, Rule, Variable, Assertion
 
 logger = logging.getLogger(__name__)
 
 
+class AssertionCheckHookMatch(Protocol):
+    """the protocol of output func (on_match in register_assertion_check_hook) in assertion check hook"""
+    def __call__(self, rule: Rule, assertion: Assertion, combination: dict[Variable, Constant | CompoundTerm], *, result: bool) \
+            -> None: ...  # noqa: D102
+
+
 def register_assertion_check_hook(
-    grounded_rule: GroundedRule,
     *,
     rule_name: str | None = None,
     vars_filter: Mapping[str, str] | None = None,
-    on_match: Callable[[Rule, _AssertionNode, dict[Variable, Constant | CompoundTerm], bool], None] | None = None,
+    on_match: AssertionCheckHookMatch | None = None,
     break_on_match: bool = False,
 ) -> None:
     """
@@ -33,7 +39,6 @@ def register_assertion_check_hook(
             print(rule.name, assertion.content, combination, result)
 
         register_assertion_check_hook(
-            grounded_rule,
             rule_name="rule_3",
             vars_filter={"p1": "f", "p2": "a", "p13": "b", "p14": "c"},
             on_match=log_match,
@@ -55,7 +60,7 @@ def register_assertion_check_hook(
         combination_str = {str(k): str(v) for k, v in combination.items()}
         if normalized_vars_filter:
             for key, value in normalized_vars_filter.items():
-                if combination_str.get(key) != value:
+                if combination_str.get(key) != str(value):
                     return
 
         if on_match is None:
@@ -63,16 +68,18 @@ def register_assertion_check_hook(
                 "Assertion check hook: rule=%s content=%s combination=%s result=%s",
                 rule,
                 assertion.content,
-                combination_str,
+                format_mapping(combination_str),
                 result,
             )
         else:
-            on_match(rule, assertion, combination, result)
+            on_match(rule, assertion.content, combination, result=result)
 
         if break_on_match:
             breakpoint()  # noqa: T100
 
-    grounded_rule.register_hook("assertion_check", _hook)
+    from kele.grounder import GroundedRule  # noqa: PLC0415
+
+    GroundedRule.register_class_hook("assertion_check", _hook)
 
 
 class BuiltinHookEnabler:
@@ -80,12 +87,11 @@ class BuiltinHookEnabler:
     Enabler for built-in hooks by name.
 
     This class does not register hooks by itself. Create an instance and call
-    ``enable`` to attach a built-in hook to a grounded rule.
+    ``enable`` to attach a built-in hook to every grounded rule instance.
 
     Example:
         hooks = BuiltinHookEnabler()
         hooks.enable(
-            grounded_rule,
             "assertion_check",
             rule_name="rule_3",
             vars_filter={"p1": "f"},
@@ -103,17 +109,17 @@ class BuiltinHookEnabler:
         """
         return sorted(self._hooks)
 
-    def enable(self, grounded_rule: GroundedRule, name: str, **kwargs: object) -> None:
+    def enable(self, name: str, **kwargs: object) -> None:
         """
         Enable a built-in hook by name.
         """
         if name not in self._hooks:
             raise KeyError(f"Unknown built-in hook: {name}")
-        self._hooks[name](grounded_rule, **kwargs)
+        self._hooks[name](**kwargs)
 
-    def enable_many(self, grounded_rule: GroundedRule, names: list[str], **kwargs: object) -> None:
+    def enable_many(self, names: list[str], **kwargs: object) -> None:
         """
         Enable multiple built-in hooks by name.
         """
         for hook_name in names:
-            self.enable(grounded_rule, hook_name, **kwargs)
+            self.enable(hook_name, **kwargs)

kele/control/callback.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import TYPE_CHECKING, Any
+from threading import RLock
+from typing import TYPE_CHECKING, Any, ClassVar
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -18,9 +19,36 @@ class HookMixin:
 
     :ivar _hooks: 事件名称到钩子函数列表的映射。
     """
+    _class_hooks: ClassVar[dict[str, list[Callable[..., None]]]]
+    _hooks_lock: ClassVar[RLock] = RLock()
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        parent_hooks = getattr(cls, "_class_hooks", None)
+        class_hooks: dict[str, list[Callable[..., None]]] = defaultdict(list)
+        if parent_hooks:
+            for event_name, hooks in parent_hooks.items():
+                class_hooks[event_name] = list(hooks)
+        cls._class_hooks = class_hooks
+
     def __init__(self) -> None:
         self._hooks: dict[str, list[Callable[..., None]]] = defaultdict(list)
 
+    @classmethod
+    def register_class_hook(cls, event_name: str, hook_fn: Callable[..., None], *, unique: bool = True) -> None:
+        """
+        在类级别注册 hook，所有实例触发事件时都会执行该 hook。
+
+        :param event_name: 要监听的事件名称。
+        :param hook_fn: 接受任意参数的可调用钩子函数。
+        :param unique: 是否防止同一 hook 重复注册。
+        """
+        with cls._hooks_lock:
+            hooks = cls._class_hooks[event_name]
+            if unique and any(fn is hook_fn for fn in hooks):
+                return
+            hooks.append(hook_fn)
+
     def register_hook(self, event_name: str, hook_fn: Callable[..., None]) -> None:
         """
         为指定事件注册钩子函数。
@@ -38,7 +66,10 @@ class HookMixin:
         :param args: 传递给钩子的所有位置参数。
         :param kwargs: 传递给钩子的所有关键字参数。
         """
-        for hook in self._hooks.get(event_name, []):
+        with self._hooks_lock:
+            class_hooks = list(self.__class__._class_hooks.get(event_name, []))  # noqa: SLF001
+        instance_hooks = list(self._hooks.get(event_name, []))
+        for hook in class_hooks + instance_hooks:
             hook(*args, **kwargs)
 
     def run_hooks(self, event_name: str, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401

kele/control/grounding_selector/_rule_strategies/_scc_sort_strategy.py

@@ -0,0 +1,110 @@
+import itertools
+import typing
+import warnings
+
+import networkx as nx
+
+from kele.control.registry import register
+from kele.syntax.base_classes import FACT_TYPE, Assertion, CompoundTerm, Constant, Formula, Operator, Rule, Variable
+
+from .strategy_protocol import Feedback, RuleSelectionStrategy
+
+
+class SccSortStrategyBase(RuleSelectionStrategy):
+    _reverse_order: bool
+
+    def __init__(self) -> None:
+        warnings.warn("SccSort and ReverseSccSort are not stable features. Use them at your own risk.", stacklevel=3)
+        self._rules: list[Rule]
+        self._graph: nx.DiGraph
+        """Under current implementation, this is a bipartite graph. There may
+        be further performance optimizations with this property?"""
+        self._order: list[Rule]
+        self._stateful_gen: typing.Generator[Rule]
+
+    @classmethod
+    def _all_operators_in_fact_type(cls, f: FACT_TYPE | CompoundTerm | Constant | Variable | None) -> set[Operator]:
+        match f:
+            case CompoundTerm(operator=operator, arguments=arguments):
+                s = set()
+                s.add(operator)
+                for argument in arguments:
+                    s |= cls._all_operators_in_fact_type(argument)
+                return s
+            case Assertion(lhs=lhs, rhs=rhs):
+                return cls._all_operators_in_fact_type(lhs) | cls._all_operators_in_fact_type(rhs)
+            case Formula(formula_left=l, formula_right=r):
+                return cls._all_operators_in_fact_type(l) | cls._all_operators_in_fact_type(r)
+            case _:
+                return set()
+
+    def _rules_to_graph(self, rules: list[Rule]) -> nx.DiGraph:
+        graph = nx.DiGraph()
+        nodes_left = []
+        for rule in rules:
+            graph.add_node(rule, type_='rule')
+            nodes_left.append(rule)
+            heads = self._all_operators_in_fact_type(rule.head)
+            bodies = self._all_operators_in_fact_type(rule.body)
+
+            for op in bodies:
+                graph.add_edge(op, rule)
+            for op in heads:
+                graph.add_edge(rule, op)
+        return graph
+
+    @staticmethod
+    def _compile_order(graph: nx.DiGraph) -> typing.Generator[Rule]:
+        def _order_within_scc(subgraph: nx.DiGraph) -> typing.Generator[Rule]:
+            temp_g = subgraph.copy()
+            while temp_g.nodes:
+                out_d = dict(temp_g.out_degree)
+                in_d = dict(temp_g.in_degree)
+                n = max(temp_g.nodes, key=lambda x: out_d[x] - in_d[x])
+                yield n
+                temp_g.remove_node(n)
+
+        scc_dag = nx.condensation(graph)
+        scc_order = nx.topological_sort(scc_dag)
+        for scc_id in scc_order:
+            members: frozenset[Rule | Operator] = scc_dag.nodes[scc_id]['members']
+            subgraph = typing.cast("nx.DiGraph", graph.subgraph(members))
+            for m in _order_within_scc(subgraph):
+                node = graph.nodes[m]
+                # This "isinstance" clause is useless, just to satisfy the LSP
+                if node.get('type_', None) == 'rule' and isinstance(m, Rule):
+                    yield m
+
+    def _select_next_generator(self) -> typing.Generator[Rule]:
+        yield from itertools.cycle(self._order)
+
+    def set_rules(self, rules: typing.Sequence[Rule]) -> None:
+        self._rules = list(rules)
+        if not self._rules:
+            raise ValueError('rules cannot be empty')
+        self._graph = self._rules_to_graph(self._rules)
+        self._order = list(self._compile_order(self._graph))
+        if self._reverse_order:
+            self._order.reverse()
+        self._stateful_gen = self._select_next_generator()
+
+    def reset(self) -> None:
+        self._rules = []
+        self._graph = nx.DiGraph()
+        self._order = []
+
+    def select_next(self) -> typing.Sequence[Rule]:
+        return [next(self._stateful_gen)]
+
+    def on_feedback(self, feedback: Feedback) -> None:  # noqa: PLR6301
+        return
+
+
+@register.rule_selector('SccSort')
+class SccSortStrategy(SccSortStrategyBase):
+    _reverse_order = False
+
+
+@register.rule_selector('ReverseSccSort')
+class ReverseSccSortStrategy(SccSortStrategyBase):
+    _reverse_order = True

kele/executer/executing.py

@@ -8,7 +8,7 @@ from kele.equality import Equivalence
 from kele.grounder import GroundedRule
 from kele.knowledge_bases import FactBase
 from kele.syntax import FACT_TYPE, CompoundTerm, Constant, Question, SankuManagementSystem, Variable, _QuestionRule
-from kele._utils import summarize_items
+from kele.utils import summarize_items
 
 logger = logging.getLogger(__name__)