kele 0.0.1a1__cp313-cp313-win32.whl

kele/knowledge_bases/builtin_base/builtin_operators.py

@@ -0,0 +1,105 @@
+from typing import TypeGuard
+
+from kele.syntax import Operator, Constant, Variable, FlatCompoundTerm
+from kele.knowledge_bases.builtin_base.builtin_concepts import COMPLEX_NUMBER_CONCEPT, EQUATION_CONCEPT
+
+
+def _is_constant(x: Constant | Variable) -> TypeGuard[Constant]:
+    return isinstance(x, Constant)
+
+
+def _unpack2_numbers(term: FlatCompoundTerm):  # type: ignore[no-untyped-def]  # noqa: ANN202
+    a0, a1 = term.arguments
+    if not _is_constant(a0) or not _is_constant(a1):
+        raise TypeError(f"This operator expects Constant arguments, got{[str(a0), str(a1)]} .")
+    return a0.symbol, a1.symbol
+
+
+def _unpack1_number(term: FlatCompoundTerm):  # type: ignore[no-untyped-def]  # noqa: ANN202
+    a0 = term.arguments[0]
+    if not _is_constant(a0):
+        raise TypeError("This operator expects a Constant argument, not a Variable.")
+    return a0.symbol
+
+
+def _plus(term: FlatCompoundTerm) -> Constant:
+    v0, v1 = _unpack2_numbers(term)
+    return Constant(v0 + v1, COMPLEX_NUMBER_CONCEPT)
+
+
+arithmetic_plus_op = Operator(
+    name="arithmetic_plus_op",
+    input_concepts=[COMPLEX_NUMBER_CONCEPT, COMPLEX_NUMBER_CONCEPT],
+    output_concept=COMPLEX_NUMBER_CONCEPT,
+    implement_func=_plus,
+)
+
+
+def _minus(term: FlatCompoundTerm) -> Constant:
+    v0, v1 = _unpack2_numbers(term)
+    return Constant(v0 - v1, COMPLEX_NUMBER_CONCEPT)
+
+
+arithmetic_minus_op = Operator(
+    name="arithmetic_minus_op",
+    input_concepts=[COMPLEX_NUMBER_CONCEPT, COMPLEX_NUMBER_CONCEPT],
+    output_concept=COMPLEX_NUMBER_CONCEPT,
+    implement_func=_minus,
+)
+
+
+def _times(term: FlatCompoundTerm) -> Constant:
+    v0, v1 = _unpack2_numbers(term)
+    return Constant(v0 * v1, COMPLEX_NUMBER_CONCEPT)
+
+
+arithmetic_times_op = Operator(
+    name="arithmetic_times_op",
+    input_concepts=[COMPLEX_NUMBER_CONCEPT, COMPLEX_NUMBER_CONCEPT],
+    output_concept=COMPLEX_NUMBER_CONCEPT,
+    implement_func=_times,
+)
+
+
+def _divide(term: FlatCompoundTerm) -> Constant:
+    v0, v1 = _unpack2_numbers(term)
+    if v1 == 0:
+        raise ZeroDivisionError("Division by zero in arithmetic_divide_op.")
+    return Constant(v0 / v1, COMPLEX_NUMBER_CONCEPT)
+
+
+arithmetic_divide_op = Operator(
+    name="arithmetic_divide_op",
+    input_concepts=[COMPLEX_NUMBER_CONCEPT, COMPLEX_NUMBER_CONCEPT],
+    output_concept=COMPLEX_NUMBER_CONCEPT,
+    implement_func=_divide,
+)
+
+
+def _negate(term: FlatCompoundTerm) -> Constant:
+    v0 = _unpack1_number(term)
+    return Constant(-v0, COMPLEX_NUMBER_CONCEPT)
+
+
+arithmetic_negate_op = Operator(
+    name="arithmetic_negate_op",
+    input_concepts=[COMPLEX_NUMBER_CONCEPT],
+    output_concept=COMPLEX_NUMBER_CONCEPT,
+    implement_func=_negate,
+)
+
+get_arithmetic_equation_op = Operator("get_arithmetic_equation_op", [COMPLEX_NUMBER_CONCEPT, COMPLEX_NUMBER_CONCEPT], EQUATION_CONCEPT)
+
+# Example Operators
+example_operator_1 = Operator(
+    name="parent_example",
+    input_concepts=['Person_Example', 'Person_Example'],  # example_concept_1在builtin_concepts.py中定义
+    # 我们在此处模拟“使用者自行声明本体的场景”，且concept和operator分别放置于两个文件内。此时系统无法直接定位到builtin_concepts.py
+    # 的父目录，所以要么使用者使用字符串使用concept，要么需要自行控制sys.path或concept相关声明文件的位置，使得导入可以顺利进行。
+    output_concept='Person_Example',
+)
+example_operator_2 = Operator(
+    name="color_of_example",
+    input_concepts=['Object_Example'],
+    output_concept='Color_Example',
+)

kele/knowledge_bases/builtin_base/builtin_rules.py

@@ -0,0 +1,14 @@
+from kele.syntax import Rule
+from .builtin_facts import example_assertion_1, example_formula_1
+
+# Example Rules
+example_rule_1 = Rule(
+    head=example_assertion_1,
+    body=example_assertion_1,
+    priority=0.1,
+)
+example_rule_2 = Rule(
+    head=example_assertion_1,
+    body=example_formula_1,
+    priority=0.5,
+)

kele/knowledge_bases/fact_base.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING
+
+from kele.syntax.base_classes import Assertion
+
+if TYPE_CHECKING:
+    from kele.config import KBConfig
+    from kele.syntax.base_classes import FACT_TYPE, Question
+    from collections.abc import Sequence
+    from kele.equality import Equivalence
+    from kele.syntax.external import SankuManagementSystem
+    from kele.control.grounding_selector import GroundingFlatTermWithWildCardSelector
+
+
+# FIXME: 存入事实库和规则库的信息应当满足safe的条件，我们将在 #132 中对CompoundTerm加入generic且引入safe的约束，以完成更精细的类型标注
+class FactBase:
+    """存储所有fact的总结构"""
+
+    def __init__(self,
+                 initial_facts_or_dir_or_path: Sequence[FACT_TYPE] | str,
+                 equivalence_handler: Equivalence,
+                 term_selector: GroundingFlatTermWithWildCardSelector,
+                 sk_system_handler: SankuManagementSystem,
+                 args: KBConfig,
+                 ):
+        if isinstance(initial_facts_or_dir_or_path, str):
+            self.facts: set[FACT_TYPE] = self._read_facts(initial_facts_or_dir_or_path)
+        else:
+            self.facts = set(initial_facts_or_dir_or_path)
+
+        for fact in self.facts:
+            self._validate_fact_for_storage(fact, check_free_variables=True)
+
+        self.equivalence_handler = equivalence_handler
+        self.term_selector = term_selector
+        self.sk_system_handler = sk_system_handler  # HACK: 三库系统在解题前，会执行一次initial_by_question更新事实库。考虑到
+        # 事实库的初始化是一个独立环节，此函数的调用被放置到FactBase内，而非最外层的InferenceEngine内。虽然从模块拆分的角度上FactBase和
+        # 三库系统是两个系统，可能会建议在main函数内完成二者的交互。
+        self._args = args
+        self.max_facts = self._args.fact_cache_size
+
+        self.initial_sign = False  # 引擎希望先挑选FactBase中的部分事实进行初始化。因此在__init__阶段我们认为初始化未完成，为False。
+        # 当初始化完成后、当前值为True时才应当进行后续其他操作
+        self.cur_facts: set[FACT_TYPE] = set()
+
+    def _read_facts(self, path: str) -> set[FACT_TYPE]:
+        """传入一个dir或文件，读取整个文件夹下面所有的文件或单个文件。TODO: 需要约定字符串书写格式（此刻还没有字符串的parser，先不实现）"""
+        raise NotImplementedError
+
+    def _add_or_not(self, fact: FACT_TYPE) -> bool:
+        """判断某条事实是否应当被加入事实库。"""
+
+        # 1. 判断事实是否已存在
+        if fact in self.facts:
+            return False  # 已存在的事实不再加入
+
+        # 2. 判断是否超过事实库大小上限
+        if self.max_facts != -1 and len(self.facts) >= self.max_facts:  # noqa: SIM103  # 函数还可以继续扩充，
+            # 不应当直接简化为return (self.max_facts is not None...)，因此注释掉SIM103
+            return False  # TODO: 如果事实库已满，最好是根据启发式决定是否丢弃现有事实或丢弃库内事实但保留当前事实
+
+        # 3. 不合需求没必要保留（依赖启发式/NN判断）
+
+        return True
+
+    def add_facts(
+        self,
+        facts: Sequence[FACT_TYPE],
+        *,
+        force_add: bool = False,
+        check_free_variables: bool = False,
+    ) -> list[FACT_TYPE]:
+        """
+        通过add加入的fact也会同步更新等价类。TODO: 为了效率可以拆分add_facts和add_fact，转C的时候留意下即可
+
+        :param facts: 要加入的事实序列
+        :param force_add: 是否强制加入，默认为False
+        :param check_free_variables: 是否检查事实中包含自由变量，仅对用户输入事实启用
+        :return: 实际加入的事实序列
+        :raise ValueError: 当事实包含自由变量时抛出
+        """
+        added_facts = []
+        for fact in facts:
+            self._validate_fact_for_storage(fact, check_free_variables=check_free_variables)
+
+        if force_add:  # 冗余一点避免多次判断force_add
+            for fact in facts:
+                self.facts.add(fact)
+                added_facts.append(fact)
+        else:
+            for fact in facts:
+                if self._add_or_not(fact):
+                    self.facts.add(fact)
+                    added_facts.append(fact)
+
+        self.cur_facts |= set(added_facts)
+        self.equivalence_handler.update_equiv_class(added_facts)
+        if added_facts:
+            self.term_selector.update_terms(facts=added_facts)
+
+        return added_facts
+
+    @staticmethod
+    def _validate_fact_for_storage(fact: FACT_TYPE, *, check_free_variables: bool) -> None:
+        if not isinstance(fact, Assertion):
+            raise TypeError(f"Fact {fact} is not an Assertion, which is not allowed in the fact base.")
+        if check_free_variables and fact.free_variables:
+            raise ValueError(f"Fact {fact} contains free variables, which is not allowed.")
+
+    def _select_initial_facts(self, question: Question, topn: int | None = None) -> list[FACT_TYPE]:
+        """根据问题选择最有可能有用的topn条事实，当没有num时将不对最终结果的数量做限制"""
+        all_facts = list(self.facts)
+
+        if topn is None or topn == -1 or topn >= len(all_facts):
+            return all_facts
+
+        return all_facts[:topn]  # TODO: 默认按插入顺序（或原始顺序）截取，是优化点
+
+    def initial_fact_base(self, question: Question, topn: int | None = None) -> None:
+        """作为整个解题流程开始前的一次筛选，需要选择充足的事实以免无法成功。此外也包括向三库获取一部分事实、初始化等价类等"""
+        selected_facts = self._select_initial_facts(question, topn)
+        self.equivalence_handler.update_equiv_class(selected_facts)
+        self.cur_facts |= set(selected_facts)
+
+        sk_facts = self.sk_system_handler.initial_by_question(question, topn)
+        self.add_facts(sk_facts)
+
+        self.cur_facts |= set(sk_facts)
+        self.initial_sign = True
+
+    def reset_fact_base(self) -> None:
+        """将事实库置回初始状态，sign为False，尚不确定等价类和sanku信息是否有必要移除"""
+        self.initial_sign = False
+        self.cur_facts.clear()
+        self.equivalence_handler.clear()  # 理论上如果这个函数仅有main调用，这一行是不应当有的。但我担心由于函数是外部的，如果被
+        # 凑巧谁的代码调用过时，一步clear的冗余可以减少风险
+
+    def get_facts(self) -> list[FACT_TYPE]:
+        """待定，取出正在使用的所有facts，可能用于一些日志追踪等，尤其是求解完毕后打印所有的facts"""
+        if self.initial_sign:
+            return list(self.cur_facts)
+
+        warnings.warn("Fact base has not been initialized yet.", stacklevel=2)
+        return list(self.facts)
+
+    def __str__(self) -> str:
+        fact_count = len(self.facts)
+        show_topn = 5
+
+        fact_summary = ', '.join(str(fact) for fact in list(self.facts)[:show_topn])  # 只展示前五条事实
+
+        # 如果事实数目大于5，提示用户后续还有更多
+        if fact_count > show_topn:
+            fact_summary += "..."
+
+        return f"FactBase with {fact_count} facts. First 5 facts: [{fact_summary}]"

kele/knowledge_bases/ontology_base.py

@@ -0,0 +1,67 @@
+"""本体库的导入文件"""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _py_auto_load(filename: Path) -> ModuleType:
+    """
+    从给定的文件路径动态加载一个 Python 模块。
+
+    :param filename: Python 文件路径。
+    :type filename: Path
+    :return: 加载的模块对象。
+    :rtype: types.ModuleType
+    :raises ImportError: 如果无法加载模块。
+    """  # noqa: DOC501
+    module_name = filename.stem  # 获取不带扩展名的文件名作为模块名
+    spec = importlib.util.spec_from_file_location(module_name, str(filename))
+    if spec and spec.loader:
+        module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(module)
+        return module
+
+    raise ImportError(f"Unable to import module from {filename}")
+
+
+def load_ontologies(
+    concept_dir_or_path: str | Path,
+    operator_dir_or_path: str | Path,
+) -> None:
+    """
+    从概念目录和算子目录（或文件）加载所有 Python 本体模块。
+
+    :param: concept_dir_or_path: 概念模块的目录或文件路径或yaml文件。
+    :param: operator_dir_or_path: 算子模块的目录或文件路径或yaml文件。
+    """
+    def _collect_files(path: str | Path, suffix: str = '.py') -> list[Path]:
+        """
+        收集指定路径下所有 Python 文件。
+
+        参数:
+            path (str | Path): 文件路径或目录路径。
+
+        返回:
+            List[Path]: 所有符合条件的 Python 文件路径。
+        """
+        path = Path(path)
+        if path.is_dir():
+            # 返回目录下所有 .py 文件（不包括子目录）
+            return sorted(path.glob(f"*{suffix}"))
+
+        if path.is_file() and path.suffix == ".py":
+            return [path]
+
+        return []
+
+    # 收集概念和算子模块的 Python 文件
+    concept_py_files = _collect_files(concept_dir_or_path)
+    operator_py_files = _collect_files(operator_dir_or_path)
+
+    all_modules = []
+    for file in concept_py_files + operator_py_files:
+        module = _py_auto_load(file)
+        all_modules.append(module)
+
+    # TODO: 收集概念和算子模块的 yaml 文件

kele/knowledge_bases/rule_base.py

@@ -0,0 +1,194 @@
+from typing import overload
+import warnings
+from collections.abc import Sequence
+
+from kele.config import KBConfig
+from kele.syntax import Variable, Constant
+from kele.syntax.base_classes import Rule, Question, Formula, Assertion, CompoundTerm, _QuestionRule
+from kele.syntax.dnf_converter import RuleSafetyProcesser
+from kele.knowledge_bases.builtin_base.builtin_facts import true_const
+
+
+class RuleBase:
+    """存储所有abstract rule的总结构"""
+
+    def __init__(self, rules_or_dir_or_path: Sequence[Rule] | str, args: KBConfig):
+        if isinstance(rules_or_dir_or_path, str):
+            self.rules = list(dict.fromkeys(self._read_rules(rules_or_dir_or_path)))
+            # 使用list代替set，以保持输入的规则顺序、因为set后的随机顺序会引入
+            # 不必要的不确定性，随意的排序也对于推理无益
+        else:
+            self.rules = list(dict.fromkeys(rules_or_dir_or_path))  # 加入去重操作
+
+        self.rule_suffix: int = 1
+
+        new_rules: list[Rule] = []
+        for single_rule in self.rules:
+            new_rules.extend(self._split_and_rename_rule(single_rule))
+        self.rules = new_rules
+
+        self.initial_sign: bool = False  # initial_rule_base后为True，和Fact base一样
+        self.cur_rules: list[Rule] = []  # FactBase由于经常需要更新而用了set，而abstract rule不变，为了便捷用了list
+
+        self.question_rule: list[_QuestionRule] = []  # 用于存储question转化成的rule，不干涉正常流程，不参与select等。
+
+        self._var_counter = 0
+
+        self._args = args
+
+    def _read_rules(self, path: str) -> list[Rule]:
+        """传入一个dir或文件，读取整个文件夹下面所有的文件或单个文件，文件格式需要py或yaml。TODO: 到时候需要约定字符串书写格式"""
+        raise NotImplementedError
+
+    def add_rule(self, rule: Rule) -> None:
+        """可能用不到的函数，添加rule"""
+        warnings.warn(
+            "Not supported yet. When runtime rule additions are enabled, SelectionStrategy must add add_rule and "
+            "adjust RuleCheckRule behavior as needed.",
+            stacklevel=2,
+        )
+        if rule not in self.rules:
+            splited_rules = self._split_and_rename_rule(rule)
+            splited_rules = [self._preprocess_rule(rule) for rule in splited_rules]
+
+            self.rules.extend(splited_rules)
+
+    def get_rules(self) -> list[Rule]:
+        """取出正在使用的所有rule，可能用于一些日志追踪等"""
+        if self.initial_sign:
+            return list(self.cur_rules)
+
+        warnings.warn("Rule base has not been initialized yet.", stacklevel=2)
+        return [r for r in self.rules if not isinstance(r, _QuestionRule)]
+
+    def get_question_rules(self) -> list[_QuestionRule]:
+        """取出所有由question转化来的规则"""
+        return self.question_rule
+
+    def _select_rules_from_current_question(self, question: Question, topn: int | None = None) -> list[Rule]:
+        """
+        根据当前问题的前提或目标问题选择一组规则。
+        可选地，通过 'topn' 参数限制选择的规则数量。
+        """
+        # 由于选前k个而需要list或tuple一下  TODO: 另外：暂时将所有规则视为可能相关的规则，以后可以添加过滤逻辑或排序什么的。
+        all_rules = list(self.rules)
+
+        # 如果没有指定限制则返回所有规则。
+        if topn is None or topn == -1 or topn >= len(all_rules):
+            return all_rules
+
+        return all_rules[:topn]
+
+    def initial_rule_base(self, question: Question, topn: int | None = None) -> None:
+        """作为整个解题流程开始前的一次筛选，需要选择充足的规则以免无法成功。可能Rule中本身带有和领域相关的标签"""
+        if question.question:
+            question_r = _QuestionRule.from_parts(head=Assertion.from_parts(_QuestionRule.QUESTION_SOLVED_FLAG, true_const),
+                               body=question.question, name=_QuestionRule.QUESTIONRULE_NAME)
+            splited = self._split_and_rename_rule(question_r)
+            self.question_rule.extend(splited)
+
+        selected_rules = self._select_rules_from_current_question(question, topn) + self.question_rule
+        self.cur_rules = [self._preprocess_rule(r) for r in selected_rules]
+        self.initial_sign = True
+
+    def reset_rule_base(self) -> None:
+        """
+        将RuleBase重置为其预初始化状态。清除所有活动规则并将initial_sign设置为False
+        """
+        self.cur_rules.clear()
+        self.initial_sign = False
+
+    def _preprocess_rule(self, rule: Rule) -> Rule:
+        return self._rename_rule_vars(rule)
+
+    def _rename_rule_vars(self, rule: Rule) -> Rule:
+        """调用_random_variable_name对规则中的变量重命名"""
+        var_map: dict[str, Variable] = {}  # 仅作为临时工作区
+        new_head = self._generate_renamed_item(rule.head, var_map)
+        new_body = self._generate_renamed_item(rule.body, var_map)
+
+        return rule.replace(head=new_head, body=new_body)
+
+    def _split_and_rename_rule[T1: Rule](self, rule: T1) -> Sequence[T1]:
+        """给没有命名的规则一个代称，并处理 DNF 拆分"""
+        origin_name = rule.name or f"rule_{self.rule_suffix}"
+        self.rule_suffix += 1
+
+        rule_spliter = RuleSafetyProcesser()
+        splited_rules = rule_spliter.split_rule_and_process_safety(rule)
+
+        if len(splited_rules) == 1:
+            return [splited_rules[0].replace(name=origin_name)]
+
+        result = []
+        for idx, single_rule in enumerate(splited_rules):
+            new_name = f"{origin_name}_{idx + 1}"
+            result.append(single_rule.replace(name=new_name))
+
+        return result
+
+    @overload
+    def _generate_renamed_item(self, item: Variable, var_map: dict[str, Variable]) -> Variable: ...
+    @overload
+    def _generate_renamed_item(self, item: Constant, var_map: dict[str, Variable]) -> Constant: ...
+    @overload
+    def _generate_renamed_item(self, item: CompoundTerm, var_map: dict[str, Variable]) -> CompoundTerm: ...
+    @overload
+    def _generate_renamed_item(self, item: Assertion, var_map: dict[str, Variable]) -> Assertion: ...
+    @overload
+    def _generate_renamed_item(self, item: Formula, var_map: dict[str, Variable]) -> Formula: ...
+    @overload
+    def _generate_renamed_item(self, item: None, var_map: dict[str, Variable]) -> None: ...
+
+    def _generate_renamed_item(self,
+                               item: Formula | Assertion | CompoundTerm | Variable | Constant | None,
+                               var_map: dict[str, Variable]) -> (
+            Formula | Assertion | CompoundTerm | Variable | Constant | None):
+        if isinstance(item, Variable):
+            if item.symbol not in var_map:
+                new_name = f"_v{self._var_counter}"
+                self._var_counter += 1
+                var_map[item.symbol] = item.create_renamed_variable(new_name)
+                # risk: 两条规则里如果都用到了x，然后使用者使用了同一个x的instance，
+                # 我们是否有理由认为它俩是一个x？（我认为不合理，所以我们应当不管instance，而只是取它的value本身。但这样会不会给使用者带来困惑？
+                # 他可能刻意用了同一个instance，甚至在里面存了一些自定义的信息。但我们可能是直接丢弃然后换个了新名字新地址）
+            return var_map[item.symbol]
+
+        if isinstance(item, Constant):
+            return item
+
+        if isinstance(item, CompoundTerm):
+            return CompoundTerm.from_parts(
+                item.operator,
+                tuple(self._generate_renamed_item(arg, var_map) for arg in item.arguments),
+            )
+
+        if isinstance(item, Assertion):
+            return Assertion.from_parts(
+                self._generate_renamed_item(item.lhs, var_map),
+                self._generate_renamed_item(item.rhs, var_map),
+            )
+
+        if isinstance(item, Formula):
+            return Formula(
+                self._generate_renamed_item(item.formula_left, var_map),
+                item.connective,
+                self._generate_renamed_item(item.formula_right, var_map),
+            )
+
+        if item is None:
+            return None
+
+        raise ValueError(f"Unknown item type: {type(item)}")
+
+    def __str__(self) -> str:
+        rule_count = len(self.rules)
+
+        show_topn = 5
+
+        # 展示前5条规则
+        preview_rules = ', '.join(str(rule) for rule in list(self.rules)[:5])
+        if rule_count > show_topn:
+            preview_rules += "..."
+
+        return f"RuleBase with {rule_count} rules. First 5 rules: [{preview_rules}]"