update release v0.2.3

Author: zhe-pang

.pre-commit-config.yaml

@@ -14,7 +14,7 @@
 
 repos:
   # Standard hooks
-  - repo: https://github.com/pre-commit/pre-commit-hooks
+  - repo: https://github.com/pre-commit/pre-commit-hooks.git
     rev: v5.0.0
     hooks:
       - id: check-added-large-files
@@ -28,14 +28,14 @@ repos:
       - id: trailing-whitespace
 
   # Changes tabs to spaces
-  - repo: https://github.com/Lucas-C/pre-commit-hooks
+  - repo: https://github.com/Lucas-C/pre-commit-hooks.git
     rev: v1.5.5
     hooks:
       - id: remove-tabs
       - id: remove-crlf
 
   # Formatters
-  - repo: https://github.com/pre-commit/mirrors-clang-format
+  - repo: https://github.com/pre-commit/mirrors-clang-format.git
     rev: v19.1.1
     hooks:
       - id: clang-format
@@ -49,15 +49,15 @@ repos:
         exclude: |
           (?x)^(3rdparty/.*)$
 
-  -   repo: https://github.com/pre-commit/mirrors-mypy
+  -   repo: https://github.com/pre-commit/mirrors-mypy.git
       rev: 'v1.17.1'  # Use the sha / tag you want to point at
       hooks:
       -   id: mypy
           args: ["--config-file", "pyproject.toml"]
           files: ^mate/
           exclude: ^(wrappers/|3rdparty/|build/)
 
-  - repo: https://github.com/astral-sh/ruff-pre-commit
+  - repo: https://github.com/astral-sh/ruff-pre-commit.git
     # Ruff version.
     rev: v0.12.8
     hooks:

AGENTS.md

@@ -90,6 +90,7 @@ When working with MATE's dependencies and tools, refer to these official documen
 - Always read relevant files before modifying code
 - For non-trivial tasks, create a plan first
 - Validate changes by running tests
+- After completing a task, always run `pre-commit run -a` to format/check code and fix any reported issues before handing off
 - Prefer minimal, localized changes
 - When running as `root` in the container, restore edited tracked files to the
   workspace owner/group and keep them user/group writable before handing off.

README.md

@@ -5,7 +5,8 @@ MATE (**M**USA **A**I **T**ensor **E**ngine) is a centralized library for Genera
 ## Highlights
 
 - High-performance attention and GEMM operators for MUSA
-- Compatibility wrappers for `flash_attn_3`, `sageattention`, `flash_mla`, and `deep_gemm`
+- Compatibility wrappers for `flash_attn_3`, `sageattention`, `flash_mla`,
+  `flash_kda`, and `deep_gemm`
 - CLI tools for environment checks, configuration inspection, and replay
 
 ## Requirements
@@ -16,6 +17,16 @@ MATE (**M**USA **A**I **T**ensor **E**ngine) is a centralized library for Genera
 | TorchMUSA | `2.7` or later |
 | Architecture | `Pinghu (MP31)` |
 
+## Recommended Workflow
+
+For Moore Threads platforms, the normal integration flow is wrapper-first:
+
+1. Install MATE on top of an existing MUSA-enabled `torch` / `torch_musa` stack
+2. Install the wrapper package that matches the Python package surface your framework already expects
+3. Keep the upstream import path and high-level API shape as stable as possible
+4. Use `mate check`, `mate show-config`, `mate env`, logging, and replay if something fails
+5. Use native MATE APIs only when no wrapper matches your workload or the wrapper does not cover the feature you need
+
 ## Quick Start
 
 Use these commands after the MUSA-enabled `torch` / `torch_musa` stack is
@@ -56,6 +67,48 @@ Customize AOT coverage when needed:
 python -m mate.aot --attention-aot-level 0 --add-gemm true --add-moe false
 ```
 
+### Install a Wrapper
+
+After MATE is installed, install the wrapper that matches your framework's
+expected Python package surface.
+
+| Wrapper directory | Package | Import path | Typical use |
+| --- | --- | --- | --- |
+| `wrappers/flash-attention` | `flash_attn_3` | `flash_attn_interface` | FlashAttention-3 style integration |
+| `wrappers/FlashMLA` | `flash_mla` | `flash_mla` | FlashMLA style integration |
+| `wrappers/FlashKDA` | `flash_kda` | `flash_kda` | FlashKDA style integration |
+| `wrappers/DeepGEMM` | `deep-gemm` | `deep_gemm` | DeepGEMM style integration |
+| `wrappers/SageAttention` | `sageattention` | `sageattention` | SageAttention style integration |
+
+Generic editable install pattern:
+
+```bash
+cd wrappers/flash-attention
+pip install --no-build-isolation -e .
+```
+
+Generic wheel install pattern:
+
+```bash
+cd wrappers/flash-attention
+python -m build --wheel
+pip install dist/flash_attn_3-*.whl
+```
+
+Repeat the same workflow for `wrappers/FlashMLA`, `wrappers/FlashKDA`,
+`wrappers/DeepGEMM`, or `wrappers/SageAttention` when those package surfaces
+match your framework.
+
+### Verify and Diagnose
+
+Start with these commands after installation:
+
+```bash
+mate check
+mate show-config
+mate env
+```
+
 ### Notes
 
 - If the checkout was cloned without `--recursive`, run `git submodule update --init --recursive`.
@@ -75,6 +128,7 @@ MATE provides a command-line interface for configuration, debugging, diagnostics
 | `mate check` | Validate the runtime environment |
 | `mate show-config` | Display installation and runtime configuration |
 | `mate env` | Show relevant environment variables |
+| `mate guard-run -- COMMAND` | Run a workload with the guarded MUSA allocator installed at startup |
 | `mate replay --dir PATH` | Replay API calls from Level 10 dumps |
 | `mate list-dumps PATH` | List recorded dump directories |
 
@@ -84,6 +138,7 @@ Example:
 mate check
 mate show-config
 mate env
+mate guard-run -- python your_script.py
 mate replay --dir mate_dumps/
 mate list-dumps mate_dumps/
 ```
@@ -92,15 +147,22 @@ See [docs/mate_cli.md](docs/mate_cli.md) for full CLI documentation.
 See [docs/environment_variables.md](docs/environment_variables.md) for the
 complete environment variable reference.
 
+## Memory Debug / Guard Allocator
+
+MATE includes a guarded MUSA allocator that can replace the default `torch_musa` allocator during debugging to help localize out-of-bounds reads and writes across MUSA workloads. Start with `mate guard-run --mode tail -- python your_script.py`, or enable it in tests with `pytest --guard-alloc`. The detailed workflow, pytest defaults, and limitations are documented in [docs/guard_allocator.md](docs/guard_allocator.md).
+
 ## Wrappers
 
 MATE uses the packages under `wrappers/` as a compatibility layer for CUDA-oriented software stacks on MUSA. These wrappers preserve familiar package names and high-level APIs while routing execution to MATE operators and kernels on MUSA, which helps existing integrations migrate with smaller code changes.
 
+For the guided wrapper-first documentation path, start with [docs/source/overview.rst](docs/source/overview.rst) and [docs/source/wrapper_tutorials.rst](docs/source/wrapper_tutorials.rst) for the wrapper quickstart flow.
+
 | Wrapper | Package | Import Path | Purpose | Documentation |
 | --- | --- | --- | --- | --- |
-| `wrappers/flash-attention` | `flash_attn_3` | `flash_attn_interface` | FlashAttention-3-compatible APIs on top of MATE attention operators on MUSA | [wrapper README](wrappers/flash-attention/README.md), [compatibility summary](docs/flash_attention.md) |
+| `wrappers/flash-attention` | `flash_attn_3` | `flash_attn_interface` | FlashAttention-3-compatible APIs on top of MATE attention operators on MUSA | [wrapper README](wrappers/flash-attention/README.md), [compatibility summary](docs/source/wrappers/flash_attention_forward_compatibility.md) |
 | `wrappers/SageAttention` | `sageattention` | `sageattention` | SageAttention-compatible dense quantized attention wrapper on top of MATE on MUSA | [wrapper README](wrappers/SageAttention/README.md) |
 | `wrappers/FlashMLA` | `flash_mla` | `flash_mla` | FlashMLA-compatible MLA dense/sparse decode and sparse prefill APIs on top of MATE MLA operators on MUSA | [wrapper README](wrappers/FlashMLA/README.md) |
+| `wrappers/FlashKDA` | `flash_kda` | `flash_kda` | FlashKDA-compatible KDA forward APIs on top of MATE KDA operators on MUSA | [wrapper README](wrappers/FlashKDA/README.md) |
 | `wrappers/DeepGEMM` | `deep-gemm` | `deep_gemm` | DeepGEMM-compatible APIs on top of MATE GEMM operators on MUSA | [wrapper README](wrappers/DeepGEMM/README.md) |
 
 ## Repository Layout
@@ -118,19 +180,21 @@ MATE uses the packages under `wrappers/` as a compatibility layer for CUDA-orien
 After installing `mate`, build the Sphinx docs with:
 
 ```bash
-pip install sphinx furo
+pip install sphinx furo myst-parser
 cd docs
 make html
 ```
 
 ## Quick Links
 
 - CLI documentation: [docs/mate_cli.md](docs/mate_cli.md)
+- Guard allocator debugging: [docs/guard_allocator.md](docs/guard_allocator.md)
 - Environment variables: [docs/environment_variables.md](docs/environment_variables.md)
-- FlashAttention-3 compatibility summary: [docs/flash_attention.md](docs/flash_attention.md)
+- FlashAttention-3 compatibility summary: [docs/source/wrappers/flash_attention_forward_compatibility.md](docs/source/wrappers/flash_attention_forward_compatibility.md)
 - FlashAttention-3 wrapper: [wrappers/flash-attention/README.md](wrappers/flash-attention/README.md)
 - SageAttention wrapper: [wrappers/SageAttention/README.md](wrappers/SageAttention/README.md)
 - FlashMLA wrapper: [wrappers/FlashMLA/README.md](wrappers/FlashMLA/README.md)
+- FlashKDA wrapper: [wrappers/FlashKDA/README.md](wrappers/FlashKDA/README.md)
 - DeepGEMM wrapper: [wrappers/DeepGEMM/README.md](wrappers/DeepGEMM/README.md)
 
 ## Acknowledgement