kele 0.0.1a1__cp314-cp314-macosx_11_0_arm64.whl

kele/equality/equivalence.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+import warnings
+from typing import cast, overload, TYPE_CHECKING
+
+
+from kele.egg_equiv import EggEquivalence
+from kele.equality._utils import fact_validator  # FIXME: 内部函数
+from kele.syntax import Formula, Assertion, CompoundTerm, FACT_TYPE, Constant
+from kele.grounder.grounded_rule_ds.grounded_ds_utils import split_all_terms
+
+if TYPE_CHECKING:
+    from kele.config import Config
+    from kele.syntax.base_classes import TERM_TYPE, Variable, HashableAndStringable
+    from collections.abc import Sequence
+
+
+class Equivalence:
+    """
+    这个类是等价类的主要代码，用于实现维护等价类
+    这个类主要的属性是father和length
+    """
+    def __init__(self, args: Config) -> None:
+        self._args = args
+        self.engine: EggEquivalence = EggEquivalence(trace=False)  # HACK: 暂时不通过egraph获取等价关系解释
+        self._fact_validator = fact_validator
+
+    def get_related_item(self, input_item: TERM_TYPE) -> list[TERM_TYPE]:
+        # HACK: 此功能实际上应该由term_selector实现，或者调用egraph的相关函数来获取所有可能的等价形式
+        """
+        获取与item相关的所有节点
+        相关节点定义为：与item等价的所有节点，与term的某个复合子结构等价的所有节点，以及item本身
+
+        :param item: 要获取相关元素的元素
+        :returns: 返回与item相关的所有元素
+        """
+        if isinstance(input_item, CompoundTerm):
+            if TYPE_CHECKING:
+                input_item = cast("CompoundTerm[Constant | CompoundTerm[Constant | Variable | HashableAndStringable]]", input_item)
+            all_depth_terms = split_all_terms(input_item)
+            result_set = set()
+            for term in all_depth_terms:
+                result_set.update(self.engine.get_equiv_elem(term))
+            return list(result_set)
+        return self.get_equiv_item(input_item)
+
+    def get_equiv_item(self, input_item: TERM_TYPE) -> list[TERM_TYPE]:
+        """
+        获取与item等价的所有节点
+        如果item是与某个BOOL_CONCEPT等价，或者其本身是BOOL_CONCEPT，那么将*不会返回*和该BOOL_CONCEPT等价的元素
+
+        :param item: 要获取等价元素的元素
+        :returns: 返回与item等价的所有元素
+        """
+        return self.engine.get_equiv_elem(input_item)
+
+    def update_equiv_class(
+        self,
+        facts_or_equiv_rels: Sequence[FACT_TYPE],
+    ) -> None:
+        """更新等价类的对外接口"""
+        for item in facts_or_equiv_rels:
+            self._update_by_facts(item)
+
+    def get_represent_elem(self, input_item: Constant | CompoundTerm) -> Constant | CompoundTerm[Constant | CompoundTerm]:
+        """
+        获取与item等价的代表元素
+
+        :param item: 要获取等价元素的元素
+        :returns: 返回与item等价的代表元素
+        """
+        return self.engine.get_represent_elem(input_item)
+
+    @overload
+    def query_equivalence(self, facts: Assertion) -> bool: ...
+
+    @overload
+    def query_equivalence(self, facts: Sequence[Assertion]) -> list[bool]: ...
+
+    def query_equivalence(
+        self,
+        facts: Sequence[Assertion] | Assertion,
+    ) -> bool | list[bool]:
+        """
+        查询某个Assertion是否成立，即检查左右式是否匹配。
+
+        :param facts: 传入单个事实或者一组事实
+        :returns: 为每一个Assertion查询返回一个bool，对单个事实返回一个bool，对多个事实返回list[bool]
+
+        risk: 不确定设计是否合适，毕竟如果用并查集实现的话，本身也很难支持a=?的查询（先不考虑耗费O(n)时间能查询）
+        risk: 需要考虑是否区分unknown和false，此刻的方案不区分。
+        """
+        if isinstance(facts, Assertion):
+            return self._query_equivalence(facts)
+        result_list: list[bool] = []  # 这是用于储存匹配结果的，每个元素是一个bool，代表一个匹配结果
+        for assert_item in facts:
+            if self._query_equivalence(assert_item):  # 调用函数执行查询，成功则加入True，失败则加入False
+                result_list.append(True)
+            else:
+                result_list.append(False)
+        return result_list
+
+    def clear(self) -> None:
+        """清空等价类"""
+        self._id_counter = 0
+        self.engine.clear()
+
+    def _update_by_facts(self, facts: FACT_TYPE | None) -> None:
+        """
+        用于新事实对等价类模块的更新，一般出现在初始化KB、引擎
+
+        :param facts: 断言内的等号指示了等价关系。注意到Formula中，仅有and是可以直接拆分更新等价类的、or无法确定等价关系、not会删除等价类（暂不允许)、
+        imply先不管、equivalent也可以不管、forall现在的模式难以支持、exists无法确定等价关系
+        :returns: None
+        """
+        if isinstance(facts, Assertion) and self._fact_validator(facts):
+            if TYPE_CHECKING:
+                # Assertion中不可能含有Variable
+                facts.lhs = cast("CompoundTerm | Constant", facts.lhs)
+                facts.rhs = cast("CompoundTerm | Constant", facts.rhs)
+            self.engine.add_to_equiv(facts.lhs, facts.rhs)
+        elif isinstance(facts, Formula):
+            if facts.connective == 'AND':
+                self._update_by_facts(facts.formula_left)
+                self._update_by_facts(facts.formula_right)
+            else:
+                warnings.warn(f"Connective '{facts.connective}' cannot update equivalence classes.", stacklevel=2)
+        else:
+            warnings.warn(
+                f"Invalid fact type: {facts} has type {type(facts)} and cannot update equivalence classes.",
+                stacklevel=1,
+            )
+
+    def _query_equivalence(
+        self,
+        fact: Assertion,
+    ) -> bool:
+        if TYPE_CHECKING:
+            # Assertion中不可能含有Variable
+            fact.lhs = cast("CompoundTerm | Constant", fact.lhs)
+            fact.rhs = cast("CompoundTerm | Constant", fact.rhs)
+        return self.engine.query_equivalence(fact.lhs, fact.rhs)

kele/executer/__init__.py

@@ -0,0 +1,4 @@
+"""进行规则前件正确性的判断和执行"""
+from .executing import Executor
+
+__all__ = ['Executor']

kele/executer/executing.py

@@ -0,0 +1,139 @@
+import logging
+from collections.abc import Sequence, Mapping
+
+from kele.config import RunControlConfig
+from kele.control import InferencePath
+from kele.control.status import MainLoopManager, QuerySolutionManager
+from kele.equality import Equivalence
+from kele.knowledge_bases import FactBase
+from kele.syntax import Question, FACT_TYPE, SankuManagementSystem, Variable, Constant, CompoundTerm
+from kele.syntax import _QuestionRule
+from kele.grounder import GroundedRule
+from kele.control import InferenceStatus, create_executor_manager
+logger = logging.getLogger(__name__)
+
+
+class Executor:
+    """执行器，负责对 grounded rules 执行 check 并更新事实库。"""
+    def __init__(self,  # noqa: PLR0913
+                 equivalence: Equivalence,
+                 sk_system_handler: SankuManagementSystem,
+                 fact_base: FactBase,
+                 *,
+                 main_loop_manager: MainLoopManager | None = None,  # 仅用于更新主循环控制器。如在测试executor功能时可以为空
+                 solution_manager: QuerySolutionManager,
+                 inference_path: InferencePath | None = None,  # 如在测试executor功能时可以为空
+                 select_num: int = 5,
+                 max_steps: int = 1000
+                 ):
+        """:param select_num: 每轮最多执行的 grounded rules 数量，-1 表示不限制。"""
+        self.grounded_rules: Sequence[GroundedRule]
+        self.select_num = int(1e9) if select_num == -1 else select_num
+        # TODO: 此时的select num是从abstract rule层面进行选择的，但理想情况下能否进一步，对每个abstract rule选择其候选值。
+        #  不过也要考虑到的是，这里的选择和grounder结束时的选择是接近重复的
+        self.equivalence = equivalence
+        self.sk_system_handler = sk_system_handler
+
+        self.fact_base = fact_base  # 仅用于更新全局事实，不用于推理
+
+        self.executor_manager = create_executor_manager(
+            equivalence, sk_system_handler,
+            solution_manager=solution_manager,
+            max_steps=max_steps
+        )
+
+        self.main_loop_manager = main_loop_manager
+
+        self.inference_path = inference_path if inference_path is not None else InferencePath(args=RunControlConfig(), equivalence=self.equivalence)
+        # FIXME: 只是为了本次PR改动不要太大的妥协，正常是executor要传一个args参的。另外这个参数None仅用于测试需求
+
+    def get_equivalence(self) -> Equivalence:
+        """获取等价关系处理器"""
+        return self.equivalence
+
+    def _sort_grounded_rules(self, question: Question) -> None:
+        """
+        将 grounded rules 按优先级排序，使更有价值的规则先被执行。
+        """
+        self.grounded_rules = self.grounded_rules   # TODO: 这里是要优化为更优策略的
+
+    def execute(self, grounded_rules: Sequence[GroundedRule], question: Question) -> InferenceStatus:
+        """
+        执行 grounded rules 的 check 阶段，并更新事实库。
+
+        会在每条规则执行后更新主循环状态，并在满足终止条件时返回。
+        """
+        logger.info("Starting execution for %s", question.description)
+
+        self.grounded_rules = grounded_rules
+        self._sort_grounded_rules(question)
+
+        try:
+            for i in range(min(self.select_num, len(self.grounded_rules))):
+                grounding_result = grounded_rules[i].check_grounding()
+
+                logger.info(
+                    "Generate %s%i%s grounded rules from %s%s%s",
+                    "\033[91m", len(grounding_result), "\033[0m",  # \033[91m红色，\033[0m黑色
+                    "\033[96m", grounded_rules[i].rule, "\033[0m"  # \033[96m青绿色
+                )
+
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug(
+                        "all grounded rule text (unique rows: %s): %s",
+                        grounded_rules[i].total_table_unique_height(),
+                        grounded_rules[i].print_all_grounded_rules(),
+                    )
+
+                added_facts = self._update_facts(grounding_result)
+                logger.info(
+                    "%s%i%s new facts are derived from Rule %s%s%s",
+                    "\033[91m", len(added_facts), "\033[0m",  # \033[91m红色，\033[0m黑色
+                    "\033[96m", grounded_rules[i].rule, "\033[0m"  # \033[96m青绿色
+                )
+
+                if logger.isEnabledFor(logging.DEBUG):
+                    logger.debug("new facts: %s", [str(f) for f in added_facts])
+
+                if self.main_loop_manager and not isinstance(grounded_rules[i].rule, _QuestionRule):
+                    self.main_loop_manager.update_normal_rule_activation(new_facts=added_facts, used_rule=grounded_rules[i].rule)
+
+                solutions: list[Mapping[Variable, Constant | CompoundTerm]] = []
+                question_rule: _QuestionRule | None = None
+
+                if isinstance(grounded_rules[i].rule, _QuestionRule):
+                    solutions, question_rule = grounded_rules[i].get_question_solutions()
+
+                # 检查执行器状态
+                status = self.executor_manager.check_status(
+                    new_facts=added_facts,
+                    question=question,
+                    solutions=solutions,
+                    question_rule=question_rule
+                )
+                logger.info("Step %d status: %s", self.executor_manager.step_num, status.log_message())
+                if not isinstance(grounded_rules[i].rule, _QuestionRule):
+                    self.executor_manager.next_step()
+
+                if status.is_terminal_for_executor():
+                    return status
+
+        except SystemExit:
+            logger.exception("Execution interrupted by SystemExit")
+            return InferenceStatus.EXTERNALLY_INTERRUPTED
+
+        return InferenceStatus.NO_MORE_RULES
+
+    def _update_facts(self, new_facts: list[FACT_TYPE]) -> list[FACT_TYPE]:
+        """
+        更新事实库
+        :param new_facts : 这一轮实例化的结果
+        """
+        added_facts = self.fact_base.add_facts(facts=new_facts)  # 更新事实库后就不需要单独更新等价类了
+        self.sk_system_handler.update_facts(new_facts)
+
+        return added_facts
+
+    def reset(self) -> None:
+        """当面向新问题推理时，对当前类进行reset"""
+        self.executor_manager.reset_for_new_inference()

kele/grounder/README.md

@@ -0,0 +1,83 @@
+# term-level grounding过程
+在grounder文件夹中，我们实现了term-level的实例化过程。
+## 各文件介绍
+
+```text
+├─ grouding.py:    # 整个结构的对外接口，通过实例化其中的Grounder类，并调用grounding_process方法，可以启动grounding过程
+│
+├─ grouded_rule_ds:
+│     │
+│     ├─ grounded_class.py:    # 文件中储存了GroundedRule类和GroundedRuleDs类，其中GroundedRule是我们进行grounding的基本单位，承担了unify过程和execute过程的方法
+│     │
+│     ├─ rule_check.py:        # 文件中有RuleCheckGraph类，这个类承担了构建图的方法
+      │
+      ├─ _grounded_ds_utils.py:# 包含将Term转化为FlatTerm的方法
+      │
+      └─ _nodes:               # 文件夹中储存了构建图的节点
+            ├─_assertion.py:   # 文件夹中储存了AssertionNode类
+            ├─_conn.py:        # 文件夹中储存了ConnectiveNode类
+            ├─_op.py:          # 文件夹中储存了OperatorNode类
+            ├─_root.py:        # 文件夹中储存了RootNode类
+            ├─_rule.py:        # 文件夹中储存了RuleNode类
+            ├─_term.py:        # 文件夹中储存了TermNode类
+            ├─_tftable.py:     # 储存用于传递index的结构
+            ├─_tupletable.py:  # 储存用于记录Variable取值的结构
+```
+
+## Node节点介绍
+
+对于任意一个节点，它大致有如下的函数：
+1. add_child：自底向上的过程是张图或者树，所以需要连边；
+2. exec：每个节点有自己要执行的任务，比如Term要进行unify过程，比如Assertion要进行合并两个Term的变量替换候选值等。目前的名字是exec_*的格式；
+3. pass：每个节点要把exec后的信息传递给子节点或某个公共地址，目前的名字是pass_*的格式。
+4. _join: exec的一部分，用于合并两组变量替换。例如P(x) = Q(x)这个Assertion，P(x)可能匹配到的是x =1,2,3、Q(x)匹配到的是x = 2,3，那最终只能保留2, 3。如果规则是P(x) = Q(y)，那就要从x=1,2,3和y=2,3合并为(1,2), (1,3), (2, 2)......
+
+## grounding流程介绍
+grounding主要分为四个流程。
+### 图的构建
+首先，给定一个rule，我们会将其转化为一个图，用一个节点来表示一个term（FlatCompundTermNode），一个Assertion（AssertionNode）或者一个逻辑连接词（ConnectiveNode）
+
+具体地，构建图的流程如下：
+1. 将输入的规则body部分(常常是一个Formula)拆解为一系列的term，term对应的assertion，以及连接assertion的connective。
+2. 将term拆解为**FlatCompoundTerm**，FlatCompoundTerm是这样的term：它的arguments列表里面没有其他term。换句话说，FlatCompoundTerm是**最简单的Term**，不存在复合结构。同时，对于一些本身有复合结构的term，我们**用标记符$F来代替复合结构**，使得它成为FlatCompoundTerm，从而可以按照FlatCompoundTerm来处理，用*FlatCompoundTermNode*来记录这些FlatCompoundTerm
+3. FlatCompoundTermNode存在**其中一个是另外一个的子部分**的情况，这种时候，我们会**用一条边**来表示这种结构，这样就记录下了term的复合结构，在代码中，对于每个FlatCompoundTermNode，我们用一个列表记录它的所有子节点。对于最末尾的FlatCompoundTermNode，它会被连接到AssertionNode。
+4. 在存在connective的情况下，我们通过将AssertionNode连接到**ConnectiveNode**来记录这个结构
+5. 在图结构的末尾，我们连接**RuleNode**，用以表示匹配的终点
+
+### unify过程
+
+接下来，我们需要基于给定的Facts，确定Term中的Variable的可能取值。下面是详细的流程:
+1. 每个FlatCompoundTermNode保有一个**freevar_table**表格，用于记录它的variables的可能取值列表
+2. 我们类似前面的操作，将事实中出现的term拆解为FlatCompoundTerm(**即复合的term在标记后变成FlatCompoundTerm**)，并且将这些FlatCompoundTerm基于OperatorNode的匹配，传入同一个Operator的FlatCompoundTermNode中。
+3. 这些FlatCompoundTerm会作为FlatCompoundTermNode的取值，如果满足下面三个条件
+    1. Node对应位置为Variable，此时FlatCompoundTerm在相应位置的取值没有限制
+    2. Node对应位置为$F，此时FlatCompoundTerm在相应位置的取值没有限制（Node也不会记录这个取值）
+    3. Node对应位置为Constant，此时FlatCompoundTerm在相应位置的取值必须与FlatCompoundTermNode的取值相同
+4. 将上面符合条件的FlatCompoundTerm记录在freevar_table表格中，记录方式是记录Node中所有Variable在符合条件的FlatCompoundTerm中的取值。注意，这里的Variable**不包含**复合结构中的Variable（**即$F占位符代替的Term中Variable的取值不会被记录**）
+
+### pass与join过程
+
+上面的unify过程已使得每个Node记录了它自己的freevar_table表格，但是我们期望得到的是一个在这个规则层面的全局freevar_table表格，用于记录所有Node中的Variable的可能取值，并基于这个总表进行后续的检查
+
+于是我们有pass与join过程：
+
+1. 从根节点开始，每个节点将自己的freevar_table和其父节点传递来的freevar_table，一起传递给自己的子节点，由子节点将他们记录下来
+2. 上述过程在AssertionNode终止，接着单个AssertionNode合并得到自身的freevar_table，接着groundedrule将进一步计算所有AssertionNode的freevar_table的合并
+
+此过程主要的目的是**去除绑定不一致的结果**，即我们要求在此Rule中同一个Variable的取值必须是一致的（这个要求的合理性基于：Rule通过DNF转化和拆解后已经不再有OR结构）
+
+### check_grounding过程
+
+接下来变量的取值已经记录在AssertionNode中了，我们已经可以开始检查，并将检查结果向下传递到RuleNode了。
+
+具体地有以下步骤
+1. AssertionNode获取总freevar_table中的一部分（即涉及到当前AssertionNode使用的Variable的列）
+2. AssertionNode将它需要处理的Assertion中的Variable替换为Constant，然后对替换后的Assertion查询是否成立
+3. 将1中得到的table拆成TrueTable和FalseTable两部分，记录在TfTable结构中，并向下传递
+4. 接着将TfTables传递，每个ConnectiveNode需要依据自身的逻辑连接词（只处理AND, NOT两种，OR在DNF转化和规则拆解之后除去了）得到新的TfTable，
+
+    i. AND的情况下union两侧的TrueTable得到新的TrueTable，其他的组合(TF,FT,FF)两两union得到FalseTable，并继续向下传递
+
+    ii. NOT的情况下交换TrueTable和FalseTable，并继续向下传递
+
+5. 将最后的结果传递给RuleNode，RuleNode基于TfTable中的TrueTable来生成新的事实

kele/grounder/__init__.py

@@ -0,0 +1,17 @@
+"""
+这是将规则转化为图的实现，之后基于得到的图，将在图上进行游走从而实现规则匹配
+"""
+# 导入 grounding.py 中的grounder
+from .grounding import Grounder
+
+# 导入 grounded_class.py 中的推理过程结构
+from .grounded_rule_ds import (
+    GroundedRule,
+    GroundedRuleDS,
+    GroundedProcess
+)
+
+__all__ = [
+    # grounded_rule_ds
+    "GroundedProcess", "GroundedRule", "GroundedRuleDS", "Grounder"
+]

kele/grounder/grounded_rule_ds/__init__.py

@@ -0,0 +1,6 @@
+"""和grounding过程相关的一些类"""
+from .grounded_class import GroundedRule, GroundedRuleDS, GroundedProcess
+from .rule_check import RuleCheckGraph
+from .grounded_ds_utils import flatten_arguments, unify_all_terms
+
+__all__ = ['GroundedProcess', 'GroundedRule', 'GroundedRuleDS', 'RuleCheckGraph', 'flatten_arguments', 'unify_all_terms']

kele/grounder/grounded_rule_ds/_nodes/__init__.py

@@ -0,0 +1,24 @@
+from ._op import _OperatorNode
+from ._term import _BuildTerm, _FlatCompoundTermNode, _VariableNode, _TermNode, _ConstantNode
+from ._assertion import _AssertionNode
+from ._conn import _ConnectiveNode
+from ._rule import _RuleNode, _QuestionRuleNode
+from ._root import _RootNode
+from ._tupletable import _TupleTable
+from ._tftable import TfTables
+
+__all__ = [
+           'TfTables',
+           '_AssertionNode',
+           '_BuildTerm',
+           '_ConnectiveNode',
+           '_ConstantNode',
+           '_FlatCompoundTermNode',
+           '_OperatorNode',
+           '_QuestionRuleNode',
+           '_RootNode',
+           '_RuleNode',
+           '_TermNode',
+           '_TupleTable',
+           '_VariableNode',
+]