kele 0.0.1a2__tar.gz → 0.0.1b1__tar.gz

kele-0.0.1b1/.driftcheck.toml

@@ -0,0 +1,27 @@
+[general]
+enabled = true
+allow_push_on_error = false
+
+[docs]
+paths = [
+  "README.md",
+  "docs/tutorial/zh/**",
+  "docs/tutorial/en/**",
+]
+
+[llm]
+base_url = "https://integrate.api.nvidia.com/v1"
+model = "z-ai/glm4.7"
+timeout = 300
+max_retries = 2
+
+[tui]
+theme = "default"
+auto_apply = false
+
+[cache]
+enabled = true
+dir = ".git/driftcheck_cache"
+ttl = 3600
+
+[prompts]

kele-0.0.1b1/.github/workflows/driftcheck.yml

@@ -0,0 +1,35 @@
+name: Documentation Check
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  driftcheck:
+    if: ${{ vars.SUPPRESS_LLM_ACTIONS != 'true' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      # Optional: checkout tutorial repo into workspace (e.g. docs/tutorial/)
+      - uses: actions/checkout@v6
+        with:
+          repository: msg-bq/msg-bq.github.io
+          path: docs/tutorial
+          fetch-depth: 1
+
+      - name: Install ripgrep
+        run: sudo apt-get update && sudo apt-get install -y ripgrep
+
+      - name: Install driftcheck
+        run: |
+          curl -L https://github.com/deichrenner/driftcheck/releases/latest/download/driftcheck-linux-x86_64 -o driftcheck
+          chmod +x driftcheck
+          sudo mv driftcheck /usr/local/bin/
+
+      - name: Check documentation drift
+        env:
+          DRIFTCHECK_API_KEY: ${{ secrets.DRIFTCHECK_API_KEY }}
+        run: driftcheck check --range origin/${{ github.base_ref }}..HEAD --no-tui

{kele-0.0.1a2 → kele-0.0.1b1}/.github/workflows/lint.yml

@@ -31,6 +31,22 @@ jobs:
           python-version: 3.13
           enable-cache: true
       - name: Install ruff
-        run: uv sync --group ruff
+        run: uv sync --only-group ruff
       - name: Run ruff
-        run: uv run ruff check
+        run: uv run --no-sync ruff check
+
+  pydoclint:
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.event.pull_request.base.repo.full_name
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: 3.13
+          enable-cache: true
+      - name: Install pydoclint
+        run: uv sync --only-group pydoclint
+      - name: Run pydoclint (Sphinx/reST docstrings)
+        run: uv run --no-sync flake8 kele

kele-0.0.1b1/.github/workflows/pr_agent.yml

@@ -0,0 +1,34 @@
+name: PR Agent
+
+on:
+  pull_request:
+    types: [opened, reopened, ready_for_review, synchronize]
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+
+jobs:
+  pr_agent_job:
+    if: ${{ vars.SUPPRESS_LLM_ACTIONS != 'true' && github.event.sender.type != 'Bot' && (github.event_name != 'issue_comment' || github.event.issue.pull_request) }}
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: PR Agent action step
+        uses: qodo-ai/pr-agent@main
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NVIDIA_NIM_API_KEY: ${{ secrets.QODO_API_KEY }}
+          NVIDIA_NIM_API_BASE: https://integrate.api.nvidia.com/v1/
+          config.model: "nvidia_nim/moonshotai/kimi-k2.5"
+          config.fallback_models: '["nvidia_nim/moonshotai/kimi-k2.5"]'
+          config.custom_model_max_tokens: "128000"
+          config.ai_timeout: "600"
+          github_action_config.auto_review: "true"
+          github_action_config.auto_describe: "false"
+          github_action_config.auto_improve: "true"
+          github_action_config.pr_actions: '["opened","reopened","ready_for_review","review_requested","synchronize"]'

{kele-0.0.1a2 → kele-0.0.1b1}/.github/workflows/release.yml

@@ -193,7 +193,7 @@ jobs:
           fi
 
       - name: Download wheels
-        uses: actions/download-artifact@v6
+        uses: actions/download-artifact@v7
         with:
           pattern: wheels-*
           merge-multiple: true

{kele-0.0.1a2 → kele-0.0.1b1}/.github/workflows/test.yml

@@ -15,7 +15,7 @@ permissions:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.event.issue.number || github.ref }}
-  cancel-in-progress: ${{ vars.CANCEL_IN_PROGRESS == 'true' }}
+  cancel-in-progress: ${{ vars.CANCEL_IN_PROGRESS == 'true' && !(github.event_name == 'push' && github.ref == 'refs/heads/main') }}
 
 jobs:
   precheck:
@@ -210,14 +210,14 @@ jobs:
         run: uv run maturin develop --skip-install
         
       - name: Run examples static (current)
-        working-directory:  "."
+        working-directory: curr
         timeout-minutes: 3
         id: curr_static
         continue-on-error: true
         shell: bash
         run: |
           set +e
-          bash curr/_scripts/ci/run_examples_static_ci.sh curr curr_static.log
+          bash _scripts/ci/run_examples_static_ci.sh . curr_static.log
           code=$?
           set -e
           echo "exit_code=$code" >> "$GITHUB_OUTPUT"
@@ -232,15 +232,14 @@ jobs:
         run: uv run maturin develop --skip-install
 
       - name: Run examples static (base/main)
-        working-directory: "."
+        working-directory: base
         timeout-minutes: 3
         id: base_static
         continue-on-error: true
         shell: bash
-          # HACK: 等主线有了之后，run这里目录换base,然后就可以设置工作路径了
         run: |
           set +e
-          bash curr/_scripts/ci/run_examples_static_ci.sh base base_static.log
+          bash _scripts/ci/run_examples_static_ci.sh . base_static.log
           code=$?
           set -e
           echo "exit_code=$code" >> "$GITHUB_OUTPUT"
@@ -300,3 +299,13 @@ jobs:
           comment-id: ${{ steps.fc.outputs.comment-id }}
           body-path: pr_comment.md
           edit-mode: replace
+
+      - name: Fail if current examples static failed
+        if: ${{ always() && steps.curr_static.outputs.exit_code != '' && steps.curr_static.outputs.exit_code != '0' }}
+        shell: bash
+        run: |
+          curr_exit="${{ steps.curr_static.outputs.exit_code }}"
+          if [ "$curr_exit" != "0" ]; then
+            echo "Current examples static failed with exit code $curr_exit"
+            exit "$curr_exit"
+          fi

kele-0.0.1b1/.pr_agent.toml

@@ -0,0 +1,13 @@
+[config]
+model = "nvidia_nim/moonshotai/kimi-k2.5"
+fallback_models = ["nvidia_nim/moonshotai/kimi-k2.5"]
+custom_model_max_tokens = 128000
+ai_timeout = 600
+
+[github_action_config]
+auto_review = true
+auto_describe = false
+auto_improve = true
+
+[nvidia_nim]
+api_base = "https://integrate.api.nvidia.com/v1/"

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kele
-Version: 0.0.1a2
+Version: 0.0.1b1
 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>
@@ -11,8 +11,10 @@ Requires-Dist: bidict<1.0,>=0.23
 Requires-Dist: dacite<2.0,>=1.9
 Requires-Dist: graphviz==0.20.3
 Requires-Dist: lark<2.0,>=1.0
+Requires-Dist: mpmath<2.0,>=1.3
 Requires-Dist: networkx<4.0,>=3.5
 Requires-Dist: numpy>=2.3.3
+Requires-Dist: pathspec<2.0,>=1.0.4
 Requires-Dist: polars>=1.32
 Requires-Dist: prometheus-client>=0.22
 Requires-Dist: psutil>=7.0
@@ -29,6 +31,10 @@ Description-Content-Type: text/markdown
 
 [English](README.md) | [中文](README.zh.md)
 
+<p align="center">
+  <img src="assets/cola-icon.svg" alt="Cola icon" width="120" />
+</p>
+
 <!-- Badges: If services are not configured, badges may show unknown/404; enable as needed. -->
 [![License](https://img.shields.io/github/license/USTC-KnowledgeComputingLab/KELE.svg)](LICENSE)
 [![Build](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml)
@@ -52,7 +58,6 @@ 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).
 
@@ -160,6 +165,10 @@ KELE exposes a top-level `register` hub so you can customize internal strategies
 * 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.
 
+### 🪝 Builtin hooks
+
+BuiltinHook provides built-in hook points for inspection/debugging; enable them with the `BuiltinHookEnabler` switch. Other hook utilities (such as `HookMixin` and `CallBack`) are still under development.
+
 ### 🗺️ Roadmap
 
 WIP

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

@@ -2,6 +2,10 @@
 
 [English](README.md) | [中文](README.zh.md)
 
+<p align="center">
+  <img src="assets/cola-icon.svg" alt="Cola icon" width="120" />
+</p>
+
 <!-- Badges: If services are not configured, badges may show unknown/404; enable as needed. -->
 [![License](https://img.shields.io/github/license/USTC-KnowledgeComputingLab/KELE.svg)](LICENSE)
 [![Build](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml)
@@ -25,7 +29,6 @@ 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).
 
@@ -133,6 +136,10 @@ KELE exposes a top-level `register` hub so you can customize internal strategies
 * 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.
 
+### 🪝 Builtin hooks
+
+BuiltinHook provides built-in hook points for inspection/debugging; enable them with the `BuiltinHookEnabler` switch. Other hook utilities (such as `HookMixin` and `CallBack`) are still under development.
+
 ### 🗺️ Roadmap
 
 WIP

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

@@ -2,6 +2,10 @@
 
 [中文](README.zh.md) | [English](README.md)
 
+<p align="center">
+  <img src="assets/cola-icon.svg" alt="Cola icon" width="120" />
+</p>
+
 <!-- Badges: If services are not configured, badges may show unknown/404; enable as needed. -->
 [![License](https://img.shields.io/github/license/USTC-KnowledgeComputingLab/KELE.svg)](LICENSE)
 [![Build](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/USTC-KnowledgeComputingLab/KELE/actions/workflows/release.yml)
@@ -25,7 +29,6 @@ KELE 是基于[断言逻辑](https://link.springer.com/chapter/10.1007/978-3-319
 - **等词公理**：便捷表达等价关系，引擎内部自行维护
 - **可嵌套复合项**：允许嵌套项，算子可互相嵌套构成更复杂的复合结构
 - **算子的外部实现**：支持使用函数对算子进行自定义“实现”，如加法、解方程等
-- **内置 hook 启用器**：通过 `BuiltinHookEnabler` 启用内置 hooks 用于检查/调试
 
 > 外部实现 ≈ Prolog 元谓词 / ASP 中 HEX external predicate（语义不完全相同，但使用体验相近）。
 
@@ -127,6 +130,10 @@ KELE 暴露了顶层 `register` 入口，用于自定义内部策略（如 term
 * 每个任务注册表支持 `register(name)` 装饰器与 `available()` 查看已注册策略。
 * 目前仅支持规则/项选择器，后续可能会增加更多注册点。
 
+### 🪝 Builtin hooks
+
+BuiltinHook 提供内置的 hook 点用于检查/调试，可通过 `BuiltinHookEnabler` 开关启用。其他 hook（如 `HookMixin`、`CallBack`）仍在开发中。
+
 ### 🗺️ Roadmap
 
 WIP

kele-0.0.1b1/assets/cola-icon.svg

@@ -0,0 +1,129 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Polished Soda Cup Icon">
+  <defs>
+    <!-- Background Card Gradient -->
+    <linearGradient id="bgGradNew" x1="32" y1="16" x2="224" y2="240" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFF5E5"/>
+      <stop offset="1" stop-color="#FFE0B2"/>
+    </linearGradient>
+
+    <!-- Deep Plastic Lid Gradient -->
+    <linearGradient id="lidGradNew" x1="140" y1="56" x2="140" y2="86" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFEDD5"/>
+      <stop offset="0.5" stop-color="#FFD1A3"/>
+      <stop offset="1" stop-color="#FFB87A"/>
+    </linearGradient>
+
+    <!-- Rich Cup Body Gradient (Generic Red/Orange) -->
+    <linearGradient id="cupGradNew" x1="90" y1="100" x2="190" y2="200" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FF7F50"/> <!-- Coral Red -->
+      <stop offset="0.6" stop-color="#E04020"/> <!-- Deep Red Orange -->
+      <stop offset="1" stop-color="#B82E14"/> <!-- Darker shadow red -->
+    </linearGradient>
+
+    <!-- Syrupy Cola Liquid Gradient -->
+    <linearGradient id="colaGradNew" x1="140" y1="120" x2="140" y2="200" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#9C5A1F"/>
+      <stop offset="0.7" stop-color="#63310B"/>
+      <stop offset="1" stop-color="#421C05"/>
+    </linearGradient>
+
+    <!-- Translucent Straw Gradient -->
+    <linearGradient id="strawGradNew" x1="150" y1="40" x2="170" y2="80" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFF0B3"/>
+      <stop offset="1" stop-color="#FFC72E"/>
+    </linearGradient>
+
+    <!-- Sharp Glossy Highlight for Plastic -->
+    <linearGradient id="glossHighlight" x1="100" y1="90" x2="115" y2="220" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.7"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0.1"/>
+    </linearGradient>
+    
+    <!-- Bubble Gradient -->
+    <radialGradient id="bubbleGrad" cx="0" cy="0" r="1" gradientUnits="userSpaceOnUse" gradientTransform="translate(0.5 0.5) scale(0.5)">
+        <stop stop-color="white" stop-opacity="0.8"/>
+        <stop offset="1" stop-color="white" stop-opacity="0.2"/>
+    </radialGradient>
+
+    <!-- Improved Soft Shadow -->
+    <filter id="softShadowNew" x="-40%" y="-40%" width="180%" height="180%">
+      <feDropShadow dx="0" dy="8" stdDeviation="10" flood-color="#421C05" flood-opacity="0.25"/>
+    </filter>
+    
+    <!-- Inner shadow for depth under the lid -->
+    <filter id="rimShadow">
+        <feOffset dy="4" dx="0"/>
+        <feGaussianBlur stdDeviation="3" result="offset-blur"/>
+        <feComposite operator="out" in="SourceGraphic" in2="offset-blur" result="inverse"/>
+        <feFlood flood-color="black" flood-opacity="0.3" result="color"/>
+        <feComposite operator="in" in="color" in2="inverse" result="shadow"/>
+        <feComposite operator="over" in="shadow" in2="SourceGraphic"/> 
+    </filter>
+
+    <!-- Clip path for liquid and bubbles -->
+    <clipPath id="liquidClip">
+        <path d="M112 122 Q 140 118, 168 122 L159.8 188.5C159.2 193.2 155.2 196.8 150.5 196.8H129.5C124.8 196.8 120.8 193.2 120.2 188.5L112 122Z"/>
+    </clipPath>
+  </defs>
+
+  <!-- Background Card -->
+  <rect width="256" height="256" rx="48" fill="url(#bgGradNew)"/>
+
+  <!-- Main Icon Group with Shadow -->
+  <g filter="url(#softShadowNew)">
+    
+    <!-- Straw (Back part) -->
+    <path d="M166 42 L150 86" stroke="url(#strawGradNew)" stroke-width="14" stroke-linecap="round"/>
+    <path d="M166 42 L150 86" stroke="#C49000" stroke-opacity="0.3" stroke-width="2" fill="none"/>
+
+    <!-- Cup Body -->
+    <g>
+        <!-- Main Body Shape -->
+        <path d="M88 88H192L176.6 208.8C175.5 217.2 168.4 224 160 224H120C111.6 224 104.5 217.2 103.4 208.8L88 88Z"
+          fill="url(#cupGradNew)"/>
+          
+        <!-- Subtle rim shadow at the top of the cup -->
+        <path d="M88 88H192V94C192 94 170 98 140 98C110 98 88 94 88 94V88Z" fill="#000000" opacity="0.15"/>
+
+        <!-- Liquid Inside (Cola) -->
+        <g clip-path="url(#liquidClip)">
+             <rect x="100" y="115" width="80" height="90" fill="url(#colaGradNew)"/>
+             
+             <!-- Fizz Bubbles Group -->
+             <g fill="url(#bubbleGrad)">
+                <!-- Small fizz -->
+                <circle cx="120" cy="180" r="2"/>
+                <circle cx="135" cy="190" r="1.5"/>
+                <circle cx="155" cy="175" r="2.5"/>
+                <circle cx="140" cy="160" r="1"/>
+                <!-- Medium bubbles -->
+                <circle cx="128" cy="150" r="4" opacity="0.7"/>
+                <circle cx="148" cy="165" r="3.5" opacity="0.8"/>
+                <!-- Larger bubbles near surface -->
+                <circle cx="135" cy="135" r="5.5" opacity="0.9"/>
+                <circle cx="158" cy="142" r="4.5" opacity="0.85"/>
+             </g>
+        </g>
+        <!-- Liquid Top Surface Line (Meniscus) -->
+        <path d="M112 122 Q 140 118, 168 122" stroke="#FFFFFF" stroke-opacity="0.4" stroke-width="2" fill="none" stroke-linecap="round"/>
+
+        <!-- Sharp Glossy Highlight on Cup Body -->
+        <path d="M102 92 C 108 130, 106 190, 112 220 L 122 220 C 116 190, 118 130, 112 92 Z" fill="url(#glossHighlight)" opacity="0.8"/>
+    </g>
+
+    <!-- Lid -->
+    <g>
+        <path d="M96 72C96 63.1634 103.163 56 112 56H168C176.837 56 184 63.1634 184 72V84C184 86.2 182.2 88 180 88H100C97.8 88 96 86.2 96 84V72Z"
+          fill="url(#lidGradNew)"/>
+        <!-- Sharp Rim Highlight -->
+        <path d="M98 86 H182" stroke="#FFFFFF" stroke-opacity="0.8" stroke-width="2" stroke-linecap="round"/>
+        <!-- Top Dome Highlight -->
+        <ellipse cx="140" cy="62" rx="30" ry="4" fill="white" opacity="0.3"/>
+    </g>
+
+    <!-- Straw (Top emerging part) -->
+    <path d="M162 54 L174 20" stroke="url(#strawGradNew)" stroke-width="14" stroke-linecap="round"/>
+    <path d="M162 54 L174 20" stroke="white" stroke-opacity="0.4" stroke-width="4" fill="none" stroke-linecap="round" transform="translate(-3, 0)"/>
+    
+  </g>
+</svg>

kele-0.0.1b1/kele/_version.py

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

{kele-0.0.1a2 → kele-0.0.1b1}/kele/config.py

@@ -50,7 +50,12 @@ class InferenceStrategyConfig:
     select_rules_num: int | Literal[-1] = -1  # Number of rules to select.
     select_facts_num: int | Literal[-1] = -1  # Number of facts to select; -1 means all facts.
     # premise_selection_strategy: Literal[''] = ''  # Premise selection algorithm. TODO: Unused.
-    grounding_rule_strategy: Literal['SequentialCyclic', 'SequentialCyclicWithPriority'] = "SequentialCyclic"  # Rule selection strategy in grounding.
+    grounding_rule_strategy: Literal[
+        'SequentialCyclic',
+        'SequentialCyclicWithPriority',
+        'SccSort',
+        'ReverseSccSort'
+    ] = "SequentialCyclic"  # Rule selection strategy in grounding.
     # executing_sort_strategy: Literal[''] = ''  # Execution order strategy. TODO: Unused.
     grounding_term_strategy: Literal['Exhausted'] = "Exhausted"  # Term selection strategy in grounding.
     question_rule_interval: int = 1  # Insert a question rule every N rules; -1 uses total rule count as the interval.

{kele-0.0.1a2 → kele-0.0.1b1}/kele/control/builtin_hooks.py

@@ -1,24 +1,30 @@
 from __future__ import annotations
 
 import logging
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Protocol
+
+from kele.utils import format_mapping
 
 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
+    from kele.syntax import CompoundTerm, Constant, Rule, Variable, Assertion
 
 logger = logging.getLogger(__name__)
 
 
+class AssertionCheckHookMatch(Protocol):
+    """the protocol of output func (on_match in register_assertion_check_hook) in assertion check hook"""
+    def __call__(self, rule: Rule, assertion: Assertion, combination: dict[Variable, Constant | CompoundTerm], *, result: bool) \
+            -> None: ...  # noqa: D102
+
+
 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,
+    on_match: AssertionCheckHookMatch | None = None,
     break_on_match: bool = False,
 ) -> None:
     """
@@ -33,7 +39,6 @@ def register_assertion_check_hook(
             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,
@@ -55,7 +60,7 @@ def register_assertion_check_hook(
         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:
+                if combination_str.get(key) != str(value):
                     return
 
         if on_match is None:
@@ -63,16 +68,18 @@ def register_assertion_check_hook(
                 "Assertion check hook: rule=%s content=%s combination=%s result=%s",
                 rule,
                 assertion.content,
-                combination_str,
+                format_mapping(combination_str),
                 result,
             )
         else:
-            on_match(rule, assertion, combination, result)
+            on_match(rule, assertion.content, combination, result=result)
 
         if break_on_match:
             breakpoint()  # noqa: T100
 
-    grounded_rule.register_hook("assertion_check", _hook)
+    from kele.grounder import GroundedRule  # noqa: PLC0415
+
+    GroundedRule.register_class_hook("assertion_check", _hook)
 
 
 class BuiltinHookEnabler:
@@ -80,12 +87,11 @@ 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.
+    ``enable`` to attach a built-in hook to every grounded rule instance.
 
     Example:
         hooks = BuiltinHookEnabler()
         hooks.enable(
-            grounded_rule,
             "assertion_check",
             rule_name="rule_3",
             vars_filter={"p1": "f"},
@@ -103,17 +109,17 @@ class BuiltinHookEnabler:
         """
         return sorted(self._hooks)
 
-    def enable(self, grounded_rule: GroundedRule, name: str, **kwargs: object) -> None:
+    def enable(self, 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)
+        self._hooks[name](**kwargs)
 
-    def enable_many(self, grounded_rule: GroundedRule, names: list[str], **kwargs: object) -> None:
+    def enable_many(self, 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)
+            self.enable(hook_name, **kwargs)

{kele-0.0.1a2 → kele-0.0.1b1}/kele/control/callback.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from collections import defaultdict
-from typing import TYPE_CHECKING, Any
+from threading import RLock
+from typing import TYPE_CHECKING, Any, ClassVar
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -18,9 +19,36 @@ class HookMixin:
 
     :ivar _hooks: 事件名称到钩子函数列表的映射。
     """
+    _class_hooks: ClassVar[dict[str, list[Callable[..., None]]]]
+    _hooks_lock: ClassVar[RLock] = RLock()
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        parent_hooks = getattr(cls, "_class_hooks", None)
+        class_hooks: dict[str, list[Callable[..., None]]] = defaultdict(list)
+        if parent_hooks:
+            for event_name, hooks in parent_hooks.items():
+                class_hooks[event_name] = list(hooks)
+        cls._class_hooks = class_hooks
+
     def __init__(self) -> None:
         self._hooks: dict[str, list[Callable[..., None]]] = defaultdict(list)
 
+    @classmethod
+    def register_class_hook(cls, event_name: str, hook_fn: Callable[..., None], *, unique: bool = True) -> None:
+        """
+        在类级别注册 hook，所有实例触发事件时都会执行该 hook。
+
+        :param event_name: 要监听的事件名称。
+        :param hook_fn: 接受任意参数的可调用钩子函数。
+        :param unique: 是否防止同一 hook 重复注册。
+        """
+        with cls._hooks_lock:
+            hooks = cls._class_hooks[event_name]
+            if unique and any(fn is hook_fn for fn in hooks):
+                return
+            hooks.append(hook_fn)
+
     def register_hook(self, event_name: str, hook_fn: Callable[..., None]) -> None:
         """
         为指定事件注册钩子函数。
@@ -38,7 +66,10 @@ class HookMixin:
         :param args: 传递给钩子的所有位置参数。
         :param kwargs: 传递给钩子的所有关键字参数。
         """
-        for hook in self._hooks.get(event_name, []):
+        with self._hooks_lock:
+            class_hooks = list(self.__class__._class_hooks.get(event_name, []))  # noqa: SLF001
+        instance_hooks = list(self._hooks.get(event_name, []))
+        for hook in class_hooks + instance_hooks:
             hook(*args, **kwargs)
 
     def run_hooks(self, event_name: str, *args: Any, **kwargs: Any) -> None:  # noqa: ANN401