kele 0.0.1a1__cp313-cp313-win32.whl → 0.0.1a2__cp313-cp313-win32.whl

kele/__init__.py

@@ -1,15 +1,16 @@
 """支持断言逻辑的推理引擎"""
-from kele.main import EngineRunResult, InferenceEngine, QueryStructure
 from kele.config import (
     Config,
-    RunControlConfig,
-    InferenceStrategyConfig,
-    GrounderConfig,
     ExecutorConfig,
-    PathConfig,
+    GrounderConfig,
+    InferenceStrategyConfig,
     KBConfig,
+    PathConfig,
+    RunControlConfig,
 )
-from kele.syntax.base_classes import Constant, Concept, Operator, Variable, CompoundTerm, Assertion, Formula, Rule
+from kele.control import register
+from kele.main import EngineRunResult, InferenceEngine, QueryStructure
+from kele.syntax.base_classes import Assertion, CompoundTerm, Concept, Constant, Formula, Operator, Rule, Variable
 
 try:
     from ._version import version as __version__
@@ -35,4 +36,5 @@ __all__ = [
     'Rule',
     'RunControlConfig',
     'Variable',
+    'register',
 ]

kele/_utils.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+T = TypeVar("T")
+
+
+def summarize_items(
+    items: Sequence[T],
+    *,
+    sample_size: int = 5,
+    formatter: Callable[[T], str] = str,
+) -> dict[str, Any]:
+    """Summarize a sequence for debug logging."""
+    total = len(items)
+    sample = [formatter(item) for item in items[:sample_size]]
+    return {
+        "rows": total,
+        "sample": sample,
+    }

kele/_version.py

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

kele/config.py

@@ -1,17 +1,17 @@
 # ruff: noqa: ERA001  # Commented parameters are either not implemented yet or depend on unfinished upstream/downstream modules.
-import warnings
-from typing import Any, cast, Literal
-
+import json
 import logging
-from dataclasses import dataclass, fields, field
-from datetime import datetime, UTC
+import warnings
+from dataclasses import dataclass, field, fields
+from datetime import UTC, datetime
 from pathlib import Path
-import yaml
-import json
-import tyro
-from tyro.conf import OmitArgPrefixes
+from typing import Any, Literal, cast
+
 import dacite
+import tyro
+import yaml
 from dacite.config import Config as daConfig
+from tyro.conf import OmitArgPrefixes
 
 RESULT_LEVEL = 25
 logging.RESULT = RESULT_LEVEL  # type: ignore[attr-defined]  # This fails mypy; setattr fails ruff.
@@ -59,12 +59,50 @@ class InferenceStrategyConfig:
 @dataclass
 class GrounderConfig:
     """Grounder-related parameters."""
-    grounding_rules_num_every_step: int | Literal[-1] = -1
-    grounding_facts_num_for_each_rule: int | Literal[-1] = -1
+    grounding_rules_per_step: int | Literal[-1] = -1
+    grounding_facts_per_rule: int | Literal[-1] = -1
+    grounding_rules_num_every_step: int | Literal[-1] | None = None
+    grounding_facts_num_for_each_rule: int | Literal[-1] | None = None
     allow_unify_with_nested_term: bool = True  # Allow Variables to be replaced by CompoundTerms.
     conceptual_fuzzy_unification: bool = True  # Use strict concept constraints to accelerate inference.
     # This depends on correct concept subsumption and full constant.belong_concepts settings; beginners should use loose matching.
 
+    def __post_init__(self) -> None:
+        if self.grounding_rules_num_every_step is not None:
+            warnings.warn(
+                "grounding_rules_num_every_step is deprecated; use grounding_rules_per_step instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if self.grounding_rules_per_step == -1:
+                self.grounding_rules_per_step = self.grounding_rules_num_every_step
+            elif self.grounding_rules_per_step != self.grounding_rules_num_every_step:
+                warnings.warn(
+                    "Both grounding_rules_per_step and grounding_rules_num_every_step are set; using grounding_rules_per_step.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+        if self.grounding_facts_num_for_each_rule is not None:
+            warnings.warn(
+                "grounding_facts_num_for_each_rule is deprecated; use grounding_facts_per_rule instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if self.grounding_facts_per_rule == -1:
+                self.grounding_facts_per_rule = self.grounding_facts_num_for_each_rule
+            elif self.grounding_facts_per_rule != self.grounding_facts_num_for_each_rule:
+                warnings.warn(
+                    "Both grounding_facts_per_rule and grounding_facts_num_for_each_rule are set; using grounding_facts_per_rule.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+        if self.grounding_rules_num_every_step is None:
+            self.grounding_rules_num_every_step = self.grounding_rules_per_step
+        if self.grounding_facts_num_for_each_rule is None:
+            self.grounding_facts_num_for_each_rule = self.grounding_facts_per_rule
+
 
 @dataclass
 class ExecutorConfig:
@@ -103,7 +141,7 @@ class Config:
 
 
 def _load_config_file(path: str) -> dict[str, Any]:
-    with open(path, encoding="utf-8") as f:
+    with Path(path).open(encoding="utf-8") as f:
         if path.endswith(('.yaml', '.yml')):
             data = yaml.safe_load(f)
         elif path.endswith('.json'):
@@ -117,7 +155,7 @@ def _load_config_file(path: str) -> dict[str, Any]:
 
 
 def _save_config(config: dict[str, Any], path: str) -> None:
-    with open(path, 'w', encoding='utf8') as f:
+    with Path(path).open('w', encoding='utf8') as f:
         yaml.dump(config, f, sort_keys=False)
 
 
@@ -197,7 +235,7 @@ def _build_config(user_config: Config | None = None,
 
     :raises: ValueError: If `user_config` is used together with `config_file_path`
             or when `user_config.config` is set.
-    """  # noqa: DOC501
+    """
     if user_config and (user_config.config or config_file_path):
         raise ValueError("default config instance and config file cannot be used together")
 

kele/control/__init__.py

@@ -1,14 +1,17 @@
 """用于callbacks和推理路径的记录"""
-from .callback import HookMixin, Callback, CallbackManager
+from .callback import Callback, CallbackManager, HookMixin
+from .grounding_selector import GroundingRuleSelector
+from .builtin_hooks import BuiltinHookEnabler, register_assertion_check_hook
+from .infer_path import InferencePath
+from .registry import register
 from .status import (
     InferenceStatus,
-    create_main_loop_manager,
     create_executor_manager,
+    create_main_loop_manager,
 )
-from .grounding_selector import GroundingRuleSelector
-from .infer_path import InferencePath
 
 __all__ = [
+    'BuiltinHookEnabler',
     'Callback',
     'CallbackManager',
     'GroundingRuleSelector',
@@ -17,4 +20,6 @@ __all__ = [
     'InferenceStatus',
     'create_executor_manager',
     'create_main_loop_manager',
+    'register',
+    'register_assertion_check_hook',
 ]

kele/control/builtin_hooks.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+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
+
+logger = logging.getLogger(__name__)
+
+
+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,
+    break_on_match: bool = False,
+) -> None:
+    """
+    Register a built-in hook that observes assertion check results.
+
+    This is a user-facing inspection hook: it lets you capture whether a specific
+    assertion evaluation (for a given variable binding) is True/False, and optionally
+    stop on matches for deep debugging.
+
+    Example:
+        def log_match(rule, assertion, combination, result):
+            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,
+            break_on_match=True,
+        )
+    """
+    normalized_vars_filter = dict(vars_filter) if vars_filter is not None else None
+
+    def _hook(
+        *,
+        rule: Rule,
+        assertion: _AssertionNode,
+        combination: dict[Variable, Constant | CompoundTerm],
+        result: bool,
+    ) -> None:
+        if rule_name and rule.name != rule_name:
+            return
+
+        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:
+                    return
+
+        if on_match is None:
+            logger.debug(
+                "Assertion check hook: rule=%s content=%s combination=%s result=%s",
+                rule,
+                assertion.content,
+                combination_str,
+                result,
+            )
+        else:
+            on_match(rule, assertion, combination, result)
+
+        if break_on_match:
+            breakpoint()  # noqa: T100
+
+    grounded_rule.register_hook("assertion_check", _hook)
+
+
+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.
+
+    Example:
+        hooks = BuiltinHookEnabler()
+        hooks.enable(
+            grounded_rule,
+            "assertion_check",
+            rule_name="rule_3",
+            vars_filter={"p1": "f"},
+        )
+    """
+
+    def __init__(self) -> None:
+        self._hooks: dict[str, Callable[..., None]] = {
+            "assertion_check": register_assertion_check_hook,
+        }
+
+    def available_hooks(self) -> list[str]:
+        """
+        Return the names of available built-in hooks.
+        """
+        return sorted(self._hooks)
+
+    def enable(self, grounded_rule: GroundedRule, 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)
+
+    def enable_many(self, grounded_rule: GroundedRule, 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)

kele/control/callback.py

@@ -1,15 +1,15 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import Any, TYPE_CHECKING
-
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from kele.equality import Equivalence
     from kele.grounder import GroundedRule
     from kele.knowledge_bases import FactBase, RuleBase
-    from kele.syntax import Question, Rule, FACT_TYPE, Variable, Constant, CompoundTerm
-    from collections.abc import Callable
+    from kele.syntax import FACT_TYPE, CompoundTerm, Constant, Question, Rule, Variable
 
 
 class HookMixin:
@@ -41,6 +41,16 @@ class HookMixin:
         for hook in self._hooks.get(event_name, []):
             hook(*args, **kwargs)
 
+    def run_hooks(self, event_name: str, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401
+        """
+        对外公开的钩子触发入口。
+
+        :param event_name: 事件名称。
+        :param args: 传递给钩子的所有位置参数。
+        :param kwargs: 传递给钩子的所有关键字参数。
+        """
+        self._run_hooks(event_name, *args, **kwargs)
+
 
 class Callback:
     """回调接口——在推理各阶段采集指标的Hook"""

kele/control/grounding_selector/__init__.py

@@ -1,5 +1,11 @@
 """grounding相关的选择器"""
+from kele.control.registry import register
+
 from .rule_selector import GroundingRuleSelector
 from .term_selector import GroundingFlatTermWithWildCardSelector
 
-__all__ = ["GroundingFlatTermWithWildCardSelector", "GroundingRuleSelector"]
+__all__ = [
+    "GroundingFlatTermWithWildCardSelector",
+    "GroundingRuleSelector",
+    "register",
+]

kele/control/grounding_selector/_rule_strategies/README.md

@@ -9,5 +9,29 @@
 ## 创建自己的strategy
 1. 创建一个py文件，命名要求为`_<name>_strategy.py`；
 2. 继承RuleSelectionStrategy类，并至少声明此Protocol要求的函数；
-3. 使用`@register_strategy('<name>')`注册你的策略类，后续即可通过`grounding_rule_strategy`使用策略；
+3. 从`kele.control`导入并使用`@register.rule_selector('<name>')`注册你的策略类，后续即可通过`grounding_rule_strategy`使用策略；
 4. 注意调整`grounding_rule_strategy`的类型标注（增加Literal的候选值）。
+
+示例：
+```python
+from kele.control import register
+from kele.control.grounding_selector._rule_strategies.strategy_protocol import RuleSelectionStrategy
+
+
+@register.rule_selector("MyRuleStrategy")
+class MyRuleStrategy:
+    def __init__(self) -> None:
+        self._rules = []
+
+    def set_rules(self, rules):
+        self._rules = list(rules)
+
+    def reset(self) -> None:
+        self._rules = []
+
+    def select_next(self):
+        return self._rules[:1]
+
+    def on_feedback(self, feedback):
+        return None
+```

kele/control/grounding_selector/_rule_strategies/__init__.py

@@ -3,7 +3,7 @@ import importlib
 import logging
 import pathlib
 
-from .strategy_protocol import get_strategy_class
+from kele.control.registry import get_rule_strategy_class
 
 current_dir = pathlib.Path(__file__).resolve().parent
 package_name = __package__ or current_dir.name
@@ -21,4 +21,4 @@ for filename in current_dir.iterdir():
             logger.exception('Failed to import %s', module_name)
             continue
 
-__all__ = ["get_strategy_class"]
+__all__ = ["get_rule_strategy_class"]

kele/control/grounding_selector/_rule_strategies/_sequential_strategy.py

@@ -1,10 +1,12 @@
 from collections.abc import Sequence
 
-from .strategy_protocol import Feedback, register_strategy, RuleSelectionStrategy
+from kele.control.registry import register
 from kele.syntax import Rule
 
+from .strategy_protocol import Feedback, RuleSelectionStrategy
 
-@register_strategy('SequentialCyclic')
+
+@register.rule_selector('SequentialCyclic')
 class SequentialCyclicStrategy(RuleSelectionStrategy):
     """
     按顺序循环遍历策略：
@@ -33,7 +35,7 @@ class SequentialCyclicStrategy(RuleSelectionStrategy):
         return
 
 
-@register_strategy("SequentialCyclicWithPriority")
+@register.rule_selector("SequentialCyclicWithPriority")
 class SequentialCyclicWithPriorityStrategy(SequentialCyclicStrategy):
     """将规则按优先级排序，优先级高的先取"""
 

kele/control/grounding_selector/_rule_strategies/strategy_protocol.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Protocol, runtime_checkable, TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
+
     from kele.syntax import Rule
-    from collections.abc import Callable
 
 
 @runtime_checkable
@@ -24,28 +25,3 @@ class RuleSelectionStrategy(Protocol):
 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

@@ -1,11 +1,9 @@
 import itertools
-import warnings
 from collections.abc import Sequence
+from functools import singledispatch
 
 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
+from kele.syntax import ATOM_TYPE, FACT_TYPE, TERM_TYPE, Assertion, CompoundTerm, Constant, Formula, Rule
 
 
 @singledispatch
@@ -39,12 +37,6 @@ 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。

kele/control/grounding_selector/_term_strategies/README.md

@@ -0,0 +1,34 @@
+## 默认strategy
+
+### Exhausted
+穷尽所有可用term的策略实现。
+
+## 创建自己的strategy
+1. 创建一个py文件，命名要求为`_<name>_strategy.py`；
+2. 继承TermSelectionStrategy类，并至少声明此Protocol要求的函数；
+3. 从`kele.control`导入并使用`@register.term_selector('<name>')`注册你的策略类，后续即可通过`grounding_term_strategy`使用策略；
+4. 注意调整`grounding_term_strategy`的类型标注（增加Literal的候选值）。
+
+示例：
+```python
+from kele.control import register
+from kele.control.grounding_selector._term_strategies.strategy_protocol import TermSelectionStrategy
+
+
+@register.term_selector("MyTermStrategy")
+class MyTermStrategy:
+    def __init__(self) -> None:
+        self._terms = []
+
+    def add_terms(self, terms):
+        self._terms.extend(terms)
+
+    def reset(self) -> None:
+        self._terms = []
+
+    def select_next(self, rule):
+        return list(self._terms)
+
+    def on_feedback(self, feedback):
+        return None
+```

kele/control/grounding_selector/_term_strategies/__init__.py

@@ -3,7 +3,7 @@ import importlib
 import logging
 import pathlib
 
-from .strategy_protocol import get_strategy_class
+from kele.control.registry import get_term_strategy_class
 
 current_dir = pathlib.Path(__file__).resolve().parent
 package_name = __package__ or current_dir.name
@@ -21,4 +21,4 @@ for filename in current_dir.iterdir():
             logger.exception('Failed to import %s', module_name)
             continue
 
-__all__ = ["get_strategy_class"]
+__all__ = ["get_term_strategy_class"]

kele/control/grounding_selector/_term_strategies/_exhausted_strategy.py

@@ -1,11 +1,13 @@
 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
+from kele.control.registry import register
+from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, TERM_TYPE, Rule
 
+from .strategy_protocol import Feedback, TermSelectionStrategy
 
-@register_strategy('Exhausted')
+
+@register.term_selector('Exhausted')
 class ExhuastedStrategy(TermSelectionStrategy):
     """
     每次选择剩余的所有terms

kele/control/grounding_selector/_term_strategies/strategy_protocol.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
+
 from dataclasses import dataclass
-from typing import Protocol, runtime_checkable, TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
-    from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, Rule, TERM_TYPE
-    from collections.abc import Callable
+
+    from kele.syntax import GROUNDED_TYPE_FOR_UNIFICATION, TERM_TYPE, Rule
 
 
 @runtime_checkable
@@ -23,28 +24,3 @@ class TermSelectionStrategy(Protocol):
 @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

@@ -2,13 +2,16 @@ from __future__ import annotations
 
 import warnings
 from typing import TYPE_CHECKING
-from ._rule_strategies import get_strategy_class
+
+from ._rule_strategies import get_rule_strategy_class
 
 if TYPE_CHECKING:
-    from ._rule_strategies.strategy_protocol import RuleSelectionStrategy, Feedback
     from collections.abc import Sequence
+
     from kele.syntax import Rule, _QuestionRule
 
+    from ._rule_strategies.strategy_protocol import Feedback, RuleSelectionStrategy
+
 
 class GroundingRuleSelector:
     """
@@ -17,7 +20,7 @@ class GroundingRuleSelector:
     - 允许更新规则集合
     """
     def __init__(self, strategy: str = "sequential_cyclic", question_rule_interval: int = -1) -> None:
-        strategy_cls = get_strategy_class(strategy)
+        strategy_cls = get_rule_strategy_class(strategy)
         self._strategy = strategy_cls()
         self._normal_rules: list[Rule] | None = None
 
@@ -33,7 +36,7 @@ class GroundingRuleSelector:
     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
@@ -60,6 +63,12 @@ class GroundingRuleSelector:
 
         return rules
 
+    def active_rules_count(self) -> int | None:
+        """返回当前候选规则数量，若未初始化则返回 None。"""
+        if self._normal_rules is None:
+            return None
+        return len(self._normal_rules)
+
     def reset(self) -> None:
         """重置选择器"""
         self._strategy.reset()
@@ -81,7 +90,7 @@ class GroundingRuleSelector:
         """
         更新规则集合，并同步给当前策略
         :raise: ValueError: 没有可选rules时报错
-        """  # noqa: DOC501
+        """
         if not normal_rules:
             raise ValueError("rules cannot be empty")