@cannbot-plugin/cannbot-harness 0.0.0-stage → 0.1.5

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/reduction/validate_gates.py

@@ -0,0 +1,194 @@
+# -----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# -----------------------------------------------------------------------------------------------------------
+
+"""Reduction paradigm design gates for validate_completeness.py.
+
+Checks that DESIGN.md contains actual code blocks (not prose descriptions)
+for critical Reduction kernel implementation components.
+
+Exposed API:
+    def validate_gates(design_text: str) -> list[str]:
+        Returns list of error strings. Empty = all gates passed.
+"""
+
+from __future__ import annotations
+
+import re
+
+
+def _extract_cpp_blocks(text: str) -> list[str]:
+    """Extract all ```cpp ... ``` code blocks from markdown text."""
+    pattern = re.compile(r"```(?:cpp|c\+\+)\s*\n(.*?)```", re.DOTALL)
+    return [m.group(1) for m in pattern.finditer(text)]
+
+
+def _block_lines(block: str) -> int:
+    """Count non-empty lines in a code block."""
+    return sum(1 for line in block.splitlines() if line.strip())
+
+
+def _has_function_definition(
+    blocks: list[str], func_name: str, min_lines: int = 0
+) -> bool:
+    """Check if any cpp block contains a function definition for func_name.
+
+    Matches patterns like:
+        void FunctionName(...) {
+        __aicore__ inline void FunctionName(...) {
+        static inline void FunctionName(...) {
+    """
+    # 匹配函数定义：可选的修饰符 + 返回类型 + 函数名 + 参数列表 + {
+    pattern = re.compile(
+        r"\b(?:__aicore__\s+)?(?:inline\s+)?(?:static\s+)?\w+\s+"
+        + re.escape(func_name)
+        + r"\s*\([^)]*\)\s*\{",
+        re.MULTILINE,
+    )
+    for block in blocks:
+        if pattern.search(block) and _block_lines(block) >= min_lines:
+            return True
+    return False
+
+
+def _has_ellipsis_placeholder(blocks: list[str]) -> list[str]:
+    """Find cpp blocks containing '// ...' as omission placeholder."""
+    pattern = re.compile(r"^\s*//\s*\.{3}\s*$", re.MULTILINE)
+    results = []
+    for i, block in enumerate(blocks):
+        matches = pattern.findall(block)
+        if matches:
+            results.append(
+                f"code block #{i + 1} contains {len(matches)} placeholder(s)"
+            )
+    return results
+
+
+def validate_gates(design_text: str) -> list[str]:
+    """Validate that DESIGN.md contains required code blocks for Reduction paradigm.
+
+    Args:
+        design_text: Full text of DESIGN.md
+
+    Returns:
+        List of error strings. Empty list means all gates passed.
+    """
+    errors: list[str] = []
+    blocks = _extract_cpp_blocks(design_text)
+
+    if not blocks:
+        errors.append("GATE-0: no cpp code blocks found in DESIGN.md")
+        return errors
+
+    # 1. Process() complete source block (>= 30 lines)
+    if not _has_function_definition(blocks, "Process", min_lines=30):
+        errors.append(
+            "GATE-1: missing Process() function definition "
+            "(need cpp block with Process() definition and >= 30 non-empty lines)"
+        )
+
+    # 2. CopyIn source (DoCopyInTile required)
+    if not _has_function_definition(blocks, "DoCopyInTile"):
+        errors.append("GATE-2: missing DoCopyInTile function definition in cpp blocks")
+
+    # 3. CopyOut three-path pseudocode (>= 15 lines)
+    if not _has_function_definition(blocks, "CopyOut", min_lines=15):
+        errors.append(
+            "GATE-3: missing CopyOut function definition "
+            "(need cpp block with CopyOut() definition and >= 15 non-empty lines)"
+        )
+
+    # 4. Cache tree (GetCacheID + DoCaching，两者都必须有，见 patterns.md [6.8.2])
+    has_cache_tree = _has_function_definition(
+        blocks, "GetCacheID"
+    ) and _has_function_definition(blocks, "DoCaching")
+    if not has_cache_tree:
+        errors.append(
+            "GATE-4: missing bisection cache tree function definitions "
+            "(need both GetCacheID() and DoCaching())"
+        )
+
+    # 5. Mandatory kernel functions per patterns [6.8.2]/[6.8.3]
+    required_funcs = [
+        "ClearChunkExtensionVf",
+        "MergeTmpBufVf",
+        "FindNearestPower2",
+        "CalLog2",
+    ]
+    missing_funcs = [name for name in required_funcs if name not in design_text]
+    if missing_funcs:
+        errors.append(
+            f"GATE-5: missing mandatory kernel function definitions: {', '.join(missing_funcs)} "
+            f"(ClearInnerBurstTailPadVf 按触发条件表决定是否产出，不强制)"
+        )
+
+    # 6. No ellipsis placeholders ('// ...') in cpp blocks
+    ellipsis_hits = _has_ellipsis_placeholder(blocks)
+    if ellipsis_hits:
+        errors.append(
+            f"GATE-6: ellipsis placeholder '// ...' found in cpp blocks: "
+            f"{'; '.join(ellipsis_hits)}"
+        )
+
+    # 7. TilingKey must have ASCENDC_TPL_ARGS_DECL and ASCENDC_TPL_SEL
+    has_decl = "ASCENDC_TPL_ARGS_DECL" in design_text
+    has_sel = "ASCENDC_TPL_SEL" in design_text
+    if not has_decl or not has_sel:
+        missing = []
+        if not has_decl:
+            missing.append("ASCENDC_TPL_ARGS_DECL")
+        if not has_sel:
+            missing.append("ASCENDC_TPL_SEL")
+        errors.append(
+            f"GATE-7: missing TilingKey macro definitions: {', '.join(missing)}"
+        )
+
+    # 8. TilingKey must not contain dtype —— 只检查 TPL 宏参数行，注释/正文中的 dtype 说明不误伤
+    for block in blocks:
+        if "ASCENDC_TPL_ARGS_DECL" in block or "ASCENDC_TPL_SEL" in block:
+            for line in block.splitlines():
+                if (
+                    "TPL_BOOL_DECL" in line
+                    or "TPL_SEL" in line
+                    or "TPL_ARGS_DECL" in line
+                ):
+                    if re.search(r"\b(dtype|DataType|DTYPE)\b", line, re.IGNORECASE):
+                        errors.append(
+                            "GATE-8: TilingKey contains dtype parameter — "
+                            "Reduction paradigm TilingKey should not split by dtype"
+                        )
+                        break
+            break
+
+    # 9. Tiling side: core function definitions
+    # ComputeGroupSplit 仅在算子使用 Group 模板时必查（overview §2.1：算子选择 1~3 个模板）
+    tiling_functions = [
+        "ComputeAUbFactor",
+        "ComputeRUbFactor",
+        "ExpandAIfRFullyLoaded",
+        "SetWorkspaceSize",
+        "FillAndLogTilingData",
+    ]
+    uses_group = (
+        "ProcessGroup" in design_text
+        or "GroupKernel" in design_text
+        or "ASCENDC_TPL_BOOL_SEL(isGroup, 1)" in design_text
+    )
+    if uses_group:
+        tiling_functions.append("ComputeGroupSplit")
+    missing_tiling = []
+    for func_name in tiling_functions:
+        if not _has_function_definition(blocks, func_name):
+            missing_tiling.append(func_name)
+    if missing_tiling:
+        errors.append(
+            f"GATE-9: missing tiling function definitions: {', '.join(missing_tiling)}"
+        )
+
+    return errors

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/resolve_example.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+
+# -----------------------------------------------------------------------------------------------------------
+# Copyright (c) 2026 Huawei Technologies Co., Ltd.
+# This program is free software, you can redistribute it and/or modify it under the terms and conditions of
+# CANN Open Software License Agreement Version 2.0 (the "License").
+# Please refer to the License for details. You may not use this file except in compliance with the License.
+# THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED,
+# INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE.
+# See LICENSE in the root of the software repository for the full text of the License.
+# -----------------------------------------------------------------------------------------------------------
+"""Resolve example-routes.yaml — accept spec.yaml, extract paradigms, map to reference example packages."""
+
+from __future__ import annotations
+
+import argparse
+import re
+from pathlib import Path
+
+import yaml
+
+
+def load_example_routes(skill_dir: Path) -> dict:
+    routes_file = skill_dir / "references" / "paradigms" / "example-routes.yaml"
+    if not routes_file.exists():
+        return {}
+    with open(routes_file) as f:
+        data = yaml.safe_load(f) or {}
+    return data.get("routes", {})
+
+
+def extract_paradigm_info(spec_text: str) -> tuple[str, list[str]]:
+    category = ""
+    paradigms: list[str] = []
+    in_op = False
+    for line in spec_text.splitlines():
+        if line.startswith("op:"):
+            in_op = True
+            continue
+        if in_op and line and not line.startswith((" ", "\t", "#")):
+            break
+        if in_op:
+            if "category:" in line:
+                category = line.split(":", 1)[1].strip()
+            if "paradigms:" in line:
+                items = re.findall(r"(\w+)", line.split(":", 1)[1])
+                paradigms = items
+    return category, paradigms
+
+
+def resolve_examples(
+    routes: dict,
+    paradigms: list[str],
+    skill_dir: Path,
+) -> dict[str, list[str]]:
+    para_routes = routes.get("paradigms", {})
+    result: dict[str, list[str]] = {}
+    seen: set[str] = set()
+
+    for p in paradigms:
+        for ref_path in para_routes.get(p, []):
+            full = skill_dir / ref_path
+            if full.exists():
+                if str(full) not in seen:
+                    result.setdefault(p, []).append(str(full))
+                    seen.add(str(full))
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve paradigms to example packages from example-routes.yaml"
+    )
+    parser.add_argument(
+        "--spec",
+        type=Path,
+        required=True,
+        help="operators/{op}/docs/spec.yaml",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="Output as JSON",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(__file__).resolve().parents[2]
+    spec_text = args.spec.read_text(encoding="utf-8")
+    _category, paradigms = extract_paradigm_info(spec_text)
+
+    routes = load_example_routes(skill_dir)
+    resolved = resolve_examples(routes, paradigms, skill_dir)
+
+    if args.json:
+        import json
+
+        print(json.dumps(resolved, indent=2, ensure_ascii=False))
+    else:
+        for para, paths in resolved.items():
+            print(f"[{para}]")
+            for p in paths:
+                print(f"  {p}")
+
+
+if __name__ == "__main__":
+    main()

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/routes.yaml

@@ -0,0 +1,39 @@
+# routes.yaml — 范式路由表
+#
+# 根据 spec.yaml 的 op.paradigms 注入范式参考材料。
+# 路径相对于 ascendc-regbase-best-practice skill 根目录。
+#
+# 匹配规则：
+#   op.paradigms 列表逐项匹配，结果自动去重。
+#
+# 加载粒度：每条路由仅加载对应范式的 patterns.md（入口索引）。
+# 其他细节文件在 patterns.md 中按需引用，由阅读者按需打开。
+#
+# 兜底机制：当 op.paradigms 在本表中没有任何匹配时，自动注入
+# references/paradigms/general-methodology.md 作为通用 Tiling 方法论 fallback。
+#
+# 未配置路由的 paradigm（按 fallback 走通用方法论）：
+#   ReductionComposite, ArgReduce,
+#   Padding, IndexGather, ScatterUpdate, AtomicUpdate, Interpolation,
+#   SortSelect, Histogram, SlidingWindow, ControlFlow,
+#   Spectral, RandomSampling,
+#   Sparse, CollectiveCommunication, FusedComposite
+
+routes:
+  paradigms:
+    Elementwise:
+      - references/paradigms/elewise/patterns.md
+    Broadcast:
+      - references/paradigms/broadcast/patterns.md
+    Reduction:
+      - references/paradigms/reduction/patterns.md
+    NumericalStable:
+      - references/paradigms/numerical_stable/patterns.md
+    DynamicShape:
+      - references/paradigms/dynamic_shape/patterns.md
+    VariableOutput:
+      - references/paradigms/variable_output/patterns.md
+    MaskPredicate:
+      - references/paradigms/mask_predicate/patterns.md
+    Stateful:
+      - references/paradigms/stateful/patterns.md

package/assets/ops-direct-invoke/skills/ascendc-regbase-best-practice/references/paradigms/stateful/patterns.md

@@ -0,0 +1,146 @@
+# Stateful 类算子场景路由
+
+> 本文档用于**场景判定**和**策略选择**。确定场景后，按链接进入对应详细文档。
+>
+> **Stateful 范式是修饰范式**，与主范式共同声明。主范式（broadcast / elewise / reduction 等）
+> 负责计算逻辑、Tiling 切分、Kernel 骨架；Stateful 只叠加 in-place 输入的数据流约束。
+
+---
+
+## 范式定义
+
+**Stateful 算子**：算子的某些输入被持久化——同一个 tensor **既当输入又当输出**，
+GM 地址重叠（assign 语义）。典型如：
+
+- Adam 优化器的 `var` / `m` / `v` / `max`（输入即输出，in-place 更新）
+- Assign / Parameter 更新类算子
+
+**核心设计问题**：GM 地址重叠带来的 CopyIn / CopyOut 顺序与 buffer 约束，
+而非计算逻辑本身。计算逻辑由主范式承载。
+
+---
+
+## 场景判定流程
+
+```
+给定: spec.yaml 的 inputs + outputs
+
+Step 1 — 是否存在 input 与 output 共享 GM 地址（assign 语义）？
+  ├─ NO  → 非 Stateful，按主范式处理
+  └─ YES → 进入 Step 2
+
+Step 2 — in-place 输入的读取模式判定：
+  ├─ 单次读取后覆写（如 Adam 的 var/m/v，一次 CopyIn 后最终 CopyOut 回写）
+  │       → 场景 A: 标准约束（见下方）
+  └─ 多轮迭代中跨轮复用（如 RNN hidden state 跨 kernel launch 持久化）
+          → 场景 B: GM workspace 持久化（TODO：待补充）
+```
+
+⛔ **必须执行场景判定，禁止跳过或默认选择。** 判定依据是 spec.yaml 中 input/output
+的 GM 地址关系，不是算子名或 category。
+
+---
+
+## 场景 A: 标准约束
+
+**判据**：in-place 输入在单次 kernel launch 内完成"读取 → 计算 → 回写"，
+不需要跨 launch 持久化中间状态。
+
+### 通用规则
+
+1. **UB 内禁止 in-place read-modify-write**
+   - RegBase 硬件不支持同一 UB buffer 同一循环内 in-place read-modify-write。
+   - 对单次二元操作仍需 `src0 + src1 + dst` 三块独立 UB buffer。
+   - CopyIn 与 CopyOut 必须使用独立 UB buffer，禁止把 CopyOut 目标 buffer 复用作 CopyIn 源。
+   - 来源：`broadcast/example/examples-adam-design/adam_apply_one_assign_design.md`
+     §2.2 "RegBase 边界"、§2.6 "RegBase 无法做到同等的 in-place 覆写"。
+
+2. **CopyOut 顺序约束**
+   - in-place 输入的 CopyOut 必须晚于该 input 所有 CopyIn 完成。
+   - GM 地址重叠：提前 CopyOut 覆写会污染尚未读取的输入数据。
+   - 多 tile 场景下，同一 in-place 输入的 CopyIn 与 CopyOut 必须按 tile 顺序串行，
+     禁止乱序回写。
+
+3. **多核顺序约束**
+   - 跨核时 in-place 输入的写回需考虑核间数据归属，禁止跨核覆写他人 tile。
+   - 多核切分按主范式执行，in-place 不改变切分逻辑，只约束写回时机。
+
+4. **TilingData 不需新增字段**
+   - in-place 是 GM 地址关系，不影响 Tiling 切分逻辑。
+   - 主范式的 TilingData 结构体原样使用，不新增 Stateful 专属字段。
+
+---
+
+## 场景 B: GM workspace 持久化
+
+> TODO：待补充。预留场景——in-place 输入需跨 kernel launch 持久化中间状态
+> （如 RNN / LSTM hidden state 跨次调用）。该场景涉及 GM workspace 布局、
+> 状态字段下发、跨次调用同步等，待基于参考源码补实。
+
+---
+
+## 与主范式融合
+
+Stateful 是修饰范式，与主范式共同声明：
+
+```yaml
+paradigms: [Broadcast, Stateful]   # 主范式 + 修饰范式
+```
+
+**默认主范式**：`op.paradigms` 只有 `Stateful` 一项时，按 `Elementwise` 处理。
+
+> 该默认只是兜底。in-place 更新通常伴随 broadcast（如 Adam）或归约场景，
+> 必须显式写出主范式——默认值不会替你补回主范式的 Tiling 与 Kernel 骨架。
+
+### 修改清单
+
+| 章节 | 修改 | 说明 |
+|------|------|------|
+| Kernel 入口 / CopyIn / 地址偏移 | ⚠️ 叠加顺序约束 | in-place 输入的 CopyIn/CopyOut 顺序按通用规则执行 |
+| CopyOut | ⚠️ 叠加顺序约束 | in-place 输入回写须晚于其所有 CopyIn |
+| Compute | ❌ 不改 | 跟主范式保持一致 |
+| 跨核分核 / TilingKey / 模板类 | ❌ 不改 | in-place 不改变切分与模板策略 |
+| TilingData | ❌ 不改 | 不新增 Stateful 专属字段 |
+| Buffer 清单 / UB 预算 | ❌ 不改 | in-place 是 GM 层关系，UB buffer 规划跟主范式 |
+
+### 文档书写风格
+
+**不改的章节**:
+```markdown
+## 3 Compute
+跟主范式保持一致。
+```
+
+**改的章节（叠加约束）**:
+```markdown
+## CopyOut
+**主范式**: DataCopyPad 回写 GM。
+
+**Stateful 约束**:
+1. in-place 输入 {var/m/v} 的 CopyOut 须晚于其所有 CopyIn 完成
+2. CopyOut 目标 UB buffer 与 CopyIn 源 buffer 物理独立
+```
+
+---
+
+## 跨场景参考
+
+| 主题 | 文档 |
+|------|------|
+| 主范式设计指南（按 op.paradigms 路由） | ascendc-regbase-best-practice skill: `references/paradigms/<主范式>/patterns.md` |
+| 通用 Tiling 方法论（主范式未匹配时 fallback） | ascendc-regbase-best-practice skill: `references/paradigms/general-methodology.md` |
+| in-place 硬件边界（RegBase 禁 in-place RMW） | `broadcast/example/examples-adam-design/adam_apply_one_assign_design.md` §2.2 / §2.6 |
+
+---
+
+## 阅读确认清单
+
+设计生成器完成阅读和设计后，逐项确认：
+
+- [ ] 已完成场景判定：场景 A / 场景 B / 非 Stateful
+- [ ] （场景 A）已确认 in-place 输入列表（spec.yaml 中与 output 共享 GM 地址的 input）
+- [ ] （场景 A）CopyOut 顺序约束已写入 DESIGN.md CopyOut 章节
+- [ ] （场景 A）UB 内禁止 in-place RMW 已声明，CopyIn/CopyOut buffer 物理独立
+- [ ] （场景 A）多核写回时机约束已说明
+- [ ] TilingData 未新增 Stateful 专属字段
+- [ ] 不改的章节已写"跟主范式保持一致"