kele 0.0.1a1__cp313-cp313-win32.whl

kele/control/grounding_selector/_rule_strategies/__init__.py

@@ -0,0 +1,24 @@
+# 导入所有rule strategies
+import importlib
+import logging
+import pathlib
+
+from .strategy_protocol import get_strategy_class
+
+current_dir = pathlib.Path(__file__).resolve().parent
+package_name = __package__ or current_dir.name
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.WARNING)
+
+for filename in current_dir.iterdir():
+    if filename.suffix == '.py' and filename.stem.endswith('_strategy') and filename.stem.startswith('_'):
+        module_name = filename.stem
+        logger.info('successfully imported module: "%s"', module_name)
+        try:
+            module = importlib.import_module(f'{package_name}.{module_name}')
+        except ImportError:
+            logger.exception('Failed to import %s', module_name)
+            continue
+
+__all__ = ["get_strategy_class"]

kele/control/grounding_selector/_rule_strategies/_sequential_strategy.py

@@ -0,0 +1,42 @@
+from collections.abc import Sequence
+
+from .strategy_protocol import Feedback, register_strategy, RuleSelectionStrategy
+from kele.syntax import Rule
+
+
+@register_strategy('SequentialCyclic')
+class SequentialCyclicStrategy(RuleSelectionStrategy):
+    """
+    按顺序循环遍历策略：
+    r0, r1, ..., rN-1, r0, r1, ...
+    """
+    def __init__(self) -> None:
+        self._idx: int = 0
+
+    def set_rules(self, rules: Sequence[Rule]) -> None:
+        self._rules = list(rules)
+        if not self._rules:
+            raise ValueError("rules cannot be empty")
+        self._idx = 0
+
+    def reset(self) -> None:
+        self._idx = 0
+
+    def select_next(self) -> Sequence[Rule]:
+        # 循环顺序取下一条
+        r = self._rules[self._idx]
+        self._idx = (self._idx + 1) % len(self._rules)
+        return [r]
+
+    def on_feedback(self, feedback: Feedback) -> None:  # noqa: PLR6301  # 尚未实现，不需要转static
+        # 顺序循环策略不依赖反馈，空实现即可
+        return
+
+
+@register_strategy("SequentialCyclicWithPriority")
+class SequentialCyclicWithPriorityStrategy(SequentialCyclicStrategy):
+    """将规则按优先级排序，优先级高的先取"""
+
+    def set_rules(self, rules: Sequence[Rule]) -> None:
+        rules = sorted(rules, key=lambda r: r.priority, reverse=True)
+        super().set_rules(rules)

kele/control/grounding_selector/_rule_strategies/strategy_protocol.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from kele.syntax import Rule
+    from collections.abc import Callable
+
+
+@runtime_checkable
+class RuleSelectionStrategy(Protocol):
+    """
+    选取策略的统一接口。允许根据需求返回任意规则。
+    """
+    def __init__(self) -> None: ...
+    def set_rules(self, rules: Sequence[Rule]) -> None: ...
+    def reset(self) -> None: ...
+    def select_next(self) -> Sequence[Rule]: ...
+    def on_feedback(self, feedback: Feedback) -> None: ...    # 给策略回传一次选择后的反馈
+
+
+@dataclass
+class Feedback:
+    """一次选择后的可选反馈信息；字段都可缺省，策略按需使用。"""
+    rule: Rule | None = None  # 这次反馈关联到的规则；hack: 后面增加其他的相关信息，可能有facts等等
+
+
+rule_strategy_registry: dict[str, type[RuleSelectionStrategy]] = {}
+
+
+def register_strategy(name: str) -> Callable[[type[RuleSelectionStrategy]], type[RuleSelectionStrategy]]:
+    """装饰器：将策略类注册到全局表中"""
+    def decorator(cls: type[RuleSelectionStrategy]) -> type[RuleSelectionStrategy]:
+        rule_strategy_registry[name] = cls
+        return cls
+    return decorator
+
+
+def get_strategy_class(name: str) -> type[RuleSelectionStrategy]:
+    try:
+        return rule_strategy_registry[name]
+    except KeyError as err:
+        raise KeyError(
+            f"Rule selection strategy '{name}' is not registered. Available strategies: "
+            f"{list(rule_strategy_registry.keys())}"
+        ) from err
+
+
+def _available_strategies() -> list[str]:
+    return list(rule_strategy_registry.keys())

kele/control/grounding_selector/_selector_utils.py

@@ -0,0 +1,123 @@
+import itertools
+import warnings
+from collections.abc import Sequence
+
+from kele.knowledge_bases.builtin_base.builtin_concepts import FREEVARANY_CONCEPT
+from kele.syntax import (FACT_TYPE, TERM_TYPE, Assertion, Formula, CompoundTerm,
+                                        Constant, Variable, ATOM_TYPE, Rule)
+from functools import singledispatch
+
+
+@singledispatch
+def _unify_all_terms(fact: FACT_TYPE | TERM_TYPE) -> tuple[CompoundTerm | Constant, ...]:
+    """
+    主要是将作为formula的fact拆开成Assertion用的，对于单个的Assertion，我们拆成TERMTYPE，传入其他函数处理
+    这里直接拆到FlatCompoundTerm方便一些
+    """
+    return ()
+
+
+@_unify_all_terms.register(Assertion)
+def _(fact: Assertion) -> tuple[CompoundTerm | Constant, ...]:
+    return _unify_all_terms(fact.lhs) + _unify_all_terms(fact.rhs)
+
+
+@_unify_all_terms.register(Formula)
+def _(fact: Formula) -> tuple[CompoundTerm | Constant, ...]:
+    tuple_left = _unify_all_terms(fact.formula_left)
+    tuple_right = _unify_all_terms(fact.formula_right) if fact.formula_right is not None else ()
+    return tuple_right + tuple_left
+
+
+@_unify_all_terms.register(CompoundTerm)
+def _(fact: CompoundTerm) -> tuple[CompoundTerm | Constant, ...]:
+    return tuple(_split_all_terms(fact))
+
+
+@_unify_all_terms.register(Constant)
+def _(fact: Constant) -> tuple[CompoundTerm | Constant, ...]:
+    return (fact, )
+
+
+@_unify_all_terms.register(Variable)
+def _(fact: Variable) -> tuple[CompoundTerm | Constant, ...]:
+    warnings.warn("Variable should not exist in fact", stacklevel=2)
+    return ()
+
+
+class FREEVARANY(Constant):
+    """
+    ANY标签，在free_variables用于占位，暂定为一种特殊的Constant。
+    本引擎在flat term的level上进行grounding操作，即规则、事实中的fact都会被拆解到flat term层级进行匹配。因此nested term需要被拆解为多个
+    flat term完成，并且nested term的arguments里的Term类型的值，需要被替换为通配符，即FREEVARANY类
+    """
+
+    def __init__(self, value: str) -> None:
+        concept = FREEVARANY_CONCEPT
+        super().__init__(value, concept)
+
+
+FREEANY = FREEVARANY('FREEVARANY')
+
+
+def _split_all_terms(term: CompoundTerm) -> list[CompoundTerm]:
+    """
+    这个函能将CompoundTerm拆分成FlatCompoundTerm，并且返回一个list
+    返回的过程中，除非所有的arguments都是Term，否则都会标记之后生成FlatCompoundTerm
+    这个函数只应当用在Fact当中，因为它不处理含有Variable的情况
+    """
+    # NOTE: 常量在 _unify_all_terms 层面单独处理，这里仅拆分 CompoundTerm
+    split_terms: list[CompoundTerm] = []
+    split_terms.append(term)  # 将一个复合的term中的复合子结构取出来
+
+    for var in term.arguments:
+        if isinstance(var, CompoundTerm):
+            split_terms.extend(_split_all_terms(var))
+    return split_terms
+
+
+def flatten_arguments(arguments: Sequence[TERM_TYPE]) -> tuple[ATOM_TYPE, ...]:  # 暂时先作为对外函数，
+    # 另外这一页的singledispatch按说可以改成正常的if，以获得更清晰的阅读体验（比如把class丢最上面）
+    """
+    给定一个term，这个函数会将term的arguments中的所有Term替换为$F
+    无论在fact还是rule中这个函数都是可用的，因为是否存在variable并不影响这个函数的工作
+    """
+    return tuple(
+        FREEANY if isinstance(var, CompoundTerm) else var
+        for var in arguments
+    )
+
+
+@singledispatch
+def _unify_into_terms(fact: FACT_TYPE | TERM_TYPE) -> tuple[TERM_TYPE, ...]:
+    """
+    主要是将作为formula的fact拆开成Assertion用的，对于单个的Assertion，我们拆成TERMTYPE，传入其他函数处理
+    这里直接拆到FlatCompoundTerm方便一些
+    """
+    return ()
+
+
+@_unify_into_terms.register(Assertion)
+def _(fact: Assertion) -> tuple[TERM_TYPE, ...]:
+    return (fact.lhs, fact.rhs)
+
+
+@_unify_into_terms.register(Formula)
+def _(fact: Formula) -> tuple[TERM_TYPE, ...]:
+    tuple_left = _unify_all_terms(fact.formula_left)
+    tuple_right = _unify_all_terms(fact.formula_right) if fact.formula_right is not None else ()
+    return tuple_right + tuple_left
+
+
+@_unify_into_terms.register(TERM_TYPE)
+def _(fact: TERM_TYPE) -> tuple[TERM_TYPE, ...]:
+    return (fact, )
+
+
+def _unify_ground_terms_from_rule(rule: Rule) -> tuple[TERM_TYPE, ...]:
+    terms = _unify_all_terms(rule.head) + _unify_all_terms(rule.body)
+    return tuple(term for term in terms if not term.free_variables)
+
+
+def _unify_ground_terms_from_rules(rules: Sequence[Rule]) -> tuple[TERM_TYPE, ...]:
+    return tuple(itertools.chain.from_iterable(_unify_ground_terms_from_rule(rule) for rule in rules))

kele/control/grounding_selector/_term_strategies/__init__.py

@@ -0,0 +1,24 @@
+# 导入所有term strategies
+import importlib
+import logging
+import pathlib
+
+from .strategy_protocol import get_strategy_class
+
+current_dir = pathlib.Path(__file__).resolve().parent
+package_name = __package__ or current_dir.name
+
+logger = logging.getLogger(__name__)
+logger.setLevel(logging.WARNING)
+
+for filename in current_dir.iterdir():
+    if filename.suffix == '.py' and filename.stem.endswith('_strategy') and filename.stem.startswith('_'):
+        module_name = filename.stem
+        logger.info('successfully imported module: "%s"', module_name)
+        try:
+            module = importlib.import_module(f'{package_name}.{module_name}')
+        except ImportError:
+            logger.exception('Failed to import %s', module_name)
+            continue
+
+__all__ = ["get_strategy_class"]

kele/control/grounding_selector/_term_strategies/_exhausted_strategy.py

@@ -0,0 +1,34 @@
+from collections import defaultdict
+from collections.abc import Sequence
+
+from .strategy_protocol import Feedback, register_strategy, TermSelectionStrategy
+from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, Rule, TERM_TYPE
+
+
+@register_strategy('Exhausted')
+class ExhuastedStrategy(TermSelectionStrategy):
+    """
+    每次选择剩余的所有terms
+    """
+    def __init__(self) -> None:
+        self._terms: list[GROUNDED_TYPE_FOR_UNIFICATION] = []  # _terms应当对所有的rule都成立，只是有的被用掉了。需要有去重的方案
+        self._rules_used_id: dict[Rule, int] = defaultdict(lambda: 0)
+
+    def add_terms(self, terms: Sequence[TERM_TYPE]) -> None:
+        self._terms.extend(terms)
+
+    def reset(self) -> None:  # HACK: 这个还没用
+        self._terms.clear()
+        self._rules_used_id = defaultdict(lambda: 0)
+
+    def select_next(self, rule: Rule) -> Sequence[GROUNDED_TYPE_FOR_UNIFICATION]:
+        # 循环顺序取下一条
+        start_id = self._rules_used_id[rule]
+        selected_terms = list(self._terms[start_id:])
+        self._rules_used_id[rule] = len(self._terms)
+
+        return selected_terms
+
+    def on_feedback(self, feedback: Feedback) -> None:  # noqa: PLR6301  # 尚未实现，不需要转static
+        # 顺序循环策略不依赖反馈，空实现即可
+        return

kele/control/grounding_selector/_term_strategies/strategy_protocol.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, Rule, TERM_TYPE
+    from collections.abc import Callable
+
+
+@runtime_checkable
+class TermSelectionStrategy(Protocol):
+    """
+    选取策略的统一接口。允许根据需求返回任意规则。
+    """
+    def __init__(self) -> None: ...
+    def add_terms(self, terms: Sequence[TERM_TYPE]) -> None: ...
+    def reset(self) -> None: ...
+    def select_next(self, rule: Rule) -> Sequence[GROUNDED_TYPE_FOR_UNIFICATION]: ...
+    def on_feedback(self, feedback: Feedback) -> None: ...    # 给策略回传一次选择后的反馈
+
+
+@dataclass
+class Feedback:
+    """一次选择后的可选反馈信息；字段都可缺省，策略按需使用。"""
+
+
+term_strategy_registry: dict[str, type[TermSelectionStrategy]] = {}
+
+
+def register_strategy(name: str) -> Callable[[type[TermSelectionStrategy]], type[TermSelectionStrategy]]:
+    """装饰器：将策略类注册到全局表中"""
+    def decorator(cls: type[TermSelectionStrategy]) -> type[TermSelectionStrategy]:
+        term_strategy_registry[name] = cls
+        return cls
+    return decorator
+
+
+def get_strategy_class(name: str) -> type[TermSelectionStrategy]:
+    try:
+        return term_strategy_registry[name]
+    except KeyError as err:
+        raise KeyError(
+            f"Term selection strategy '{name}' is not registered. Available strategies: "
+            f"{list(term_strategy_registry.keys())}"
+        ) from err
+
+
+def _available_strategies() -> list[str]:
+    return list(term_strategy_registry.keys())

kele/control/grounding_selector/rule_selector.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import warnings
+from typing import TYPE_CHECKING
+from ._rule_strategies import get_strategy_class
+
+if TYPE_CHECKING:
+    from ._rule_strategies.strategy_protocol import RuleSelectionStrategy, Feedback
+    from collections.abc import Sequence
+    from kele.syntax import Rule, _QuestionRule
+
+
+class GroundingRuleSelector:
+    """
+    对外统一入口，内部委托给策略实现。
+    - 允许切换策略（接口不限制“连续取中”）
+    - 允许更新规则集合
+    """
+    def __init__(self, strategy: str = "sequential_cyclic", question_rule_interval: int = -1) -> None:
+        strategy_cls = get_strategy_class(strategy)
+        self._strategy = strategy_cls()
+        self._normal_rules: list[Rule] | None = None
+
+        self.question_rule_interval = question_rule_interval
+        self.used_rule_cnt: int = 0
+        self._question_rules: list[Rule] = []
+        self._at_fixpoint: bool = False
+
+    def set_at_fixpoint(self, *, at_fixpoint: bool) -> None:
+        """设置是否已经达到不动点状态"""
+        self._at_fixpoint = at_fixpoint
+
+    def next_rules(self) -> Sequence[Rule]:
+        """选择一定数量的规则用于grounding，在一定轮次后会查看一次question是否被解决
+        :raises ValueError: 当 question_rule_interval 小于1且不为-1时抛出。
+        """  # noqa: DOC501
+        if self._at_fixpoint:
+            if self._question_rules:
+                self.used_rule_cnt = 0
+                return self._question_rules
+            return []
+
+        # 确定实际的检查间隔
+        if self.question_rule_interval < 1 and self.question_rule_interval != -1:
+            raise ValueError(
+                "question_rule_interval must be >= 1, or -1 to use the total count of normal rules as the interval"
+            )
+
+        interval = self.question_rule_interval
+        if interval == -1:
+            normal_count = len(self._normal_rules) if self._normal_rules is not None else 0
+            interval = normal_count or 1
+
+        if self.used_rule_cnt >= interval and self._question_rules:
+            self.used_rule_cnt = 0  # 重置计数器
+            return self._question_rules
+
+        rules = self._strategy.select_next()
+        self.used_rule_cnt += len(rules)
+
+        return rules
+
+    def reset(self) -> None:
+        """重置选择器"""
+        self._strategy.reset()
+        self._normal_rules = None
+        self._question_rules = []
+        self.used_rule_cnt = 0
+        self._at_fixpoint = False
+
+    def set_strategy(self, strategy: RuleSelectionStrategy) -> None:
+        """切换策略实现（不重置调用方传入策略的内部状态，由策略自行决定）。"""
+        self._strategy = strategy
+
+        if self._normal_rules is not None:
+            self._strategy.set_rules(self._normal_rules)
+        else:
+            warnings.warn("No given rules, please call set_rules after calling set_strategy.", stacklevel=2)
+
+    def set_rules(self, normal_rules: Sequence[Rule], question_rules: Sequence[_QuestionRule]) -> None:
+        """
+        更新规则集合，并同步给当前策略
+        :raise: ValueError: 没有可选rules时报错
+        """  # noqa: DOC501
+        if not normal_rules:
+            raise ValueError("rules cannot be empty")
+
+        self._normal_rules = list(normal_rules)
+        self._question_rules = list(question_rules)
+
+        self._strategy.set_rules(self._normal_rules)
+
+        # 重置计数器
+        self.used_rule_cnt = 0
+
+    def send_feedback(self, feedback: Feedback) -> None:
+        """把一次选择后的反馈转发给当前策略"""
+        self._strategy.on_feedback(feedback)

kele/control/grounding_selector/term_selector.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import itertools
+from typing import TYPE_CHECKING
+from ._term_strategies import get_strategy_class
+from kele.control.grounding_selector._selector_utils import (
+    _unify_ground_terms_from_rules,
+    _unify_into_terms,
+)
+
+if TYPE_CHECKING:
+    from kele.config import Config
+    from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, Rule
+    from kele.equality import Equivalence
+    from ._term_strategies.strategy_protocol import Feedback
+    from collections.abc import Sequence
+    from kele.syntax import FACT_TYPE
+
+
+class GroundingFlatTermWithWildCardSelector:  # 此时是FlatTerm-level grounding，所以进strategy不止是Term。但是strategy本身是Term和
+    # FlatTerm均合适的，所以strategy自己的标准仍然得是TERM_TYPE。
+    # 此外，目前通配符和flat term无法分割，所以命名强调了wild card
+    """
+    对外统一入口，内部委托给策略实现。
+    """
+    def __init__(self,
+                 equivalence: Equivalence,
+                 args: Config) -> None:
+
+        strategy_cls = get_strategy_class(args.strategy.grounding_term_strategy)
+        self._strategy = strategy_cls()
+        self._equivalence = equivalence
+        self._args = args
+
+    def next_terms(self, rule: Rule) -> list[GROUNDED_TYPE_FOR_UNIFICATION]:
+        """为给定规则选择候选事实/term 用于 grounding。"""
+        init_terms = list(self._strategy.select_next(rule))
+
+        if self._args.run.semi_eval_with_equality:
+            selected_terms: set[GROUNDED_TYPE_FOR_UNIFICATION] = set()
+
+            for t in init_terms:
+                if t not in selected_terms:
+                    equiv_terms = self._equivalence.get_related_item(t)
+                    selected_terms |= set(equiv_terms)  # TODO: 这里后面考虑是否把_unify_into_flat_terms挪到term selector
+
+                    # 在semi-evaluation中纳入等价类其余terms，这是由
+                    # 断言逻辑带来的内嵌、强制等词公理，和term-level grounding二者共同决定的算法，因为不放置于具体的Strategy中，而是作为
+                    # Selector自身的行为。
+            return list(selected_terms)
+
+        return list(set(init_terms))
+
+    def reset(self) -> None:
+        """重置选择器"""
+        self._strategy.reset()
+
+    def update_terms(self,
+                     terms: Sequence[GROUNDED_TYPE_FOR_UNIFICATION] | None = None,
+                     facts: Sequence[FACT_TYPE] | None = None) -> None:
+        """
+        更新事实集合，并同步给当前策略。
+        :raise: ValueError: 没有可选terms_or_facts时报错
+        """  # noqa: DOC501
+
+        if terms:
+            fact_terms = terms
+        elif facts:
+            fact_terms = list(itertools.chain.from_iterable(_unify_into_terms(f) for f in facts))  # FIXME: 更进一步地，其实只有Assertion
+            # 能触发等式公理
+        else:
+            raise ValueError("terms or facts cannot be empty")
+
+        # 不应有action operator的term。fact_terms = [f for f in fact_terms if f.operator.implement_func is not None]
+        self._strategy.add_terms(fact_terms)
+
+    def update_terms_from_rules(self, rules: Sequence[Rule]) -> None:
+        """
+        将规则/问题中无变量的term加入候选表。
+        """
+        rule_terms = _unify_ground_terms_from_rules(rules)
+        if not rule_terms:
+            return
+
+        self._strategy.add_terms(rule_terms)
+
+    def send_feedback(self, feedback: Feedback) -> None:
+        """把一次选择后的反馈转发给当前策略"""
+        self._strategy.on_feedback(feedback)