kele 0.0.1a1__tar.gz → 0.0.1a2__tar.gz

{kele-0.0.1a1 → kele-0.0.1a2}/.pre-commit-config.yaml

@@ -24,3 +24,12 @@ repos:
     hooks:
       - id: mypy
         args: ["."]
+
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args: ["kele"]
+        additional_dependencies:
+          - Flake8-pyproject==1.2.4
+          - pydoclint[flake8]==0.8.3

{kele-0.0.1a1 → kele-0.0.1a2}/.ruff.toml

@@ -9,9 +9,7 @@ lint.select = [
     "C4",    # flake8-comprehensions
     "C90",   # mccabe
     "COM",   # flake8-commas
-    "DOC202", "DOC402", "DOC403", "DOC501", "DOC502", "D101", "D102", "D103", "D104", "D419",  # pydoclint
-    # TODO: 这里有个问题的，501用于提醒有raise命令无注释。我需要这个检查，但我不需要必须按docstring的格式解决这一问题，毕竟仓库用的是
-    # reStructuredText格式。但我没有找到可用的reStructuredText linter，所以暂时不行。ruff的#9003好像也不太一样
+    "D101", "D102", "D103", "D104", "D419",
     "DTZ",   # flake8-datetimez
     "E",     # pycodestyle
     "ERA",   # eradicate
@@ -60,10 +58,9 @@ lint.ignore = [
     "COM812",                      # Do not force trailing commas
     "Q000",                        # Using single quotes instead of double quotes
     "TRY003",                      # Allow exception message with any length
-    "PTH123",                      # Allow builtin-open
 ]
 
-exclude = ['docs/', '.git']
+exclude = ['docs/', '.git', '.venv', '__pycache__', 'target']
 
 [lint.per-file-ignores]
 # 对 tests 文件夹中的所有 Python 文件忽略规则

{kele-0.0.1a1 → kele-0.0.1a2}/CONTRIBUTING.md

@@ -14,8 +14,8 @@ If you have any questions, please use the GitHub discussions.
 The code structure of KELE is following the standard Python package structure.
 We organize the package code into the folder named `KELE`, the tests into the folder named `tests`,
 and the documents into the folder named `docs`.
-The file `pyproject.toml` is used to define the package metadata.
-There are also some other files such as `.ruff.toml`, `mypy.ini`, `.pre-commit-config.yaml` used to format and lint the code.
+The file `pyproject.toml` is used to define the package metadata and lint configuration.
+There are also some other files such as `.ruff.toml`, `mypy.ini`, and `.pre-commit-config.yaml` used to format and lint the code.
 
 ## How to get involved
 
@@ -24,6 +24,7 @@ We use the git flow mode to merge the pull requests.
 Please provide the essential information with proper formatting in the git commit message and the pull request description.
 
 Please make sure that your code is properly formatted, linted and typed when you submit a pull request.
+We lint with `ruff`, and we supplement its DOC-series docstring checks with `pydoclint` (via `flake8`) to support reST-style docstrings. Static typing is checked with `mypy`.
 The comments in the code are expected to be enough for other developers to understand your code.
 Please add docstrings to the code in reStructuredText style.
 If necessary, please update documentations and add tests for your changes.

{kele-0.0.1a1 → kele-0.0.1a2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: kele
-Version: 0.0.1a1
-Summary: 推理引擎
+Version: 0.0.1a2
+Summary: Knowledge Equations based Logic Engine, a forward chaining inference engine with Assertional Logic
 Author: Bingqian Li, BoYang Zhang, Weiming Hong, Hao Zhang, Yi Zhou
 Maintainer-email: Bingqian Li <libq2022@alumni.shanghaitech.edu.cn>, Yi Zhou <yi_zhou@ustc.edu.cn>
 License: BSD-3-Clause
@@ -17,6 +17,7 @@ Requires-Dist: polars>=1.32
 Requires-Dist: prometheus-client>=0.22
 Requires-Dist: psutil>=7.0
 Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: python-baseconv<2.0,>=1.0
 Requires-Dist: python-sat<2.0,>=1.7.dev0
 Requires-Dist: pyvis<0.4,>=0.3
 Requires-Dist: pyyaml<7.0,>=6.0
@@ -51,6 +52,7 @@ It supports **term-level facts**, **nested terms**, **equivalence axioms**, and
 - **Equivalence axioms**: convenient equivalence expressions with internal maintenance
 - **Nested compound terms**: operators can nest to build complex structures
 - **Implement functions for operators**: implement functions for operators (e.g., arithmetic, equation solving)
+- **Built-in hook enabler**: enable built-in hooks for inspection/debugging via `BuiltinHookEnabler`
 
 > Implement functions for operators ≈ Prolog meta-predicates / ASP HEX external predicates (not identical semantics, similar usage).
 
@@ -150,13 +152,21 @@ print(engine.infer_query(query))
 
 * **Tutorial**: https://msg-bq.github.io/
 
+### 🧩 Custom registries
+
+KELE exposes a top-level `register` hub so you can customize internal strategies (such as term/rule selectors) to fit domain-specific needs.
+
+* Built-in tasks: `register.rule_selector` and `register.term_selector`.
+* Each task registry supports `register(name)` as a decorator plus `get(name)` helpers.
+* Additional registries may be introduced in the future; today only rule/term selectors are supported.
+
 ### 🗺️ Roadmap
 
 WIP
 
 ### 🤝 Contributing
 
-Issues/PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md), and consider enabling `ruff` and `mypy`.
+Issues/PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md), and consider enabling `ruff`, `mypy`, and `pydoclint` (via `flake8`). Ruff's `DOC` rules are powered by `pydoclint`.
 
 If you have any questions about using the engine—including usage, syntax/semantics, or theoretical foundations—please open an issue or contact us.
 

{kele-0.0.1a1 → kele-0.0.1a2}/README.md

@@ -25,6 +25,7 @@ It supports **term-level facts**, **nested terms**, **equivalence axioms**, and
 - **Equivalence axioms**: convenient equivalence expressions with internal maintenance
 - **Nested compound terms**: operators can nest to build complex structures
 - **Implement functions for operators**: implement functions for operators (e.g., arithmetic, equation solving)
+- **Built-in hook enabler**: enable built-in hooks for inspection/debugging via `BuiltinHookEnabler`
 
 > Implement functions for operators ≈ Prolog meta-predicates / ASP HEX external predicates (not identical semantics, similar usage).
 
@@ -124,13 +125,21 @@ print(engine.infer_query(query))
 
 * **Tutorial**: https://msg-bq.github.io/
 
+### 🧩 Custom registries
+
+KELE exposes a top-level `register` hub so you can customize internal strategies (such as term/rule selectors) to fit domain-specific needs.
+
+* Built-in tasks: `register.rule_selector` and `register.term_selector`.
+* Each task registry supports `register(name)` as a decorator plus `get(name)` helpers.
+* Additional registries may be introduced in the future; today only rule/term selectors are supported.
+
 ### 🗺️ Roadmap
 
 WIP
 
 ### 🤝 Contributing
 
-Issues/PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md), and consider enabling `ruff` and `mypy`.
+Issues/PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md), and consider enabling `ruff`, `mypy`, and `pydoclint` (via `flake8`). Ruff's `DOC` rules are powered by `pydoclint`.
 
 If you have any questions about using the engine—including usage, syntax/semantics, or theoretical foundations—please open an issue or contact us.
 

{kele-0.0.1a1 → kele-0.0.1a2}/README.zh.md

@@ -25,6 +25,7 @@ KELE 是基于[断言逻辑](https://link.springer.com/chapter/10.1007/978-3-319
 - **等词公理**：便捷表达等价关系，引擎内部自行维护
 - **可嵌套复合项**：允许嵌套项，算子可互相嵌套构成更复杂的复合结构
 - **算子的外部实现**：支持使用函数对算子进行自定义“实现”，如加法、解方程等
+- **内置 hook 启用器**：通过 `BuiltinHookEnabler` 启用内置 hooks 用于检查/调试
 
 > 外部实现 ≈ Prolog 元谓词 / ASP 中 HEX external predicate（语义不完全相同，但使用体验相近）。
 
@@ -118,13 +119,21 @@ print(engine.infer_query(query))
 
 * **使用教程**：https://msg-bq.github.io/
 
+### 🧩 自定义注册
+
+KELE 暴露了顶层 `register` 入口，用于自定义内部策略（如 term 与 rule 的选择策略），以适应领域的细节需求。
+
+* 内置任务：`register.rule_selector` 与 `register.term_selector`。
+* 每个任务注册表支持 `register(name)` 装饰器与 `available()` 查看已注册策略。
+* 目前仅支持规则/项选择器，后续可能会增加更多注册点。
+
 ### 🗺️ Roadmap
 
 WIP
 
 ### 🤝 参与贡献
 
-欢迎 Issue/PR！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，遵循相关规范；建议启用 `ruff`、`mypy`。
+欢迎 Issue/PR！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，遵循相关规范；建议启用 `ruff`、`mypy`，以及 `pydoclint`（通过 `flake8` 运行）。`ruff` 的 `DOC` 系列规则由 `pydoclint` 支持。
 
 如果对引擎的使用有问题，但不限于使用、语法语义、理论基础等任何方面的问题，都欢迎提 issue 或与我们联系。
 

{kele-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a2/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-0.0.1a2/kele/_version.py

@@ -0,0 +1 @@
+version = "0.0.1a2"

{kele-0.0.1a1 → kele-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-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a2/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-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a2/kele/control/grounding_selector/_rule_strategies/README.md

@@ -0,0 +1,37 @@
+## 默认strategy
+
+### SequentialCyclic
+按顺序逐个选择规则，每次选1条。
+
+### SequentialCyclicWithPriority
+根据规则的priority排序后，按顺序逐个选择规则，每次选1条。
+
+## 创建自己的strategy
+1. 创建一个py文件，命名要求为`_<name>_strategy.py`；
+2. 继承RuleSelectionStrategy类，并至少声明此Protocol要求的函数；
+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-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a1 → kele-0.0.1a2}/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-0.0.1a2/kele/control/grounding_selector/_rule_strategies/strategy_protocol.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from kele.syntax import Rule
+
+
+@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等等

{kele-0.0.1a1 → kele-0.0.1a2}/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。