1# Copyright 2026 Huawei Technologies Co., Ltd
2#
3# Licensed under the Apache License, Version 2.0 (the "License");
4# you may not use this file except in compliance with the License.
5# You may obtain a copy of the License at
6#
7# http://www.apache.org/licenses/LICENSE-2.0
8#
9# Unless required by applicable law or agreed to in writing, software
10# distributed under the License is distributed on an "AS IS" BASIS,
11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12# See the License for the specific language governing permissions and
13# limitations under the License.
14# ============================================================================
15"""Lazy adapter for the external FLA Triton-Ascend KDA backend."""
16from __future__ import annotations
17
18
19__all__ = [
20 "FLAKDAStagedOps",
21 "get_fla_kda_staged_ops",
22 "is_fla_triton_kda_available",
23 "run_fla_chunk_kda",
24]
25
26import importlib
27import importlib.util
28import re
29from dataclasses import dataclass
30from functools import lru_cache
31from typing import Any, Callable, Optional
32
33import torch
34
35
36_MIN_FLA_VERSION = (0, 6, 0)
37
38
39@dataclass(frozen=True)
40class FLAKDAStagedOps:
41 """FLA operators required around Hyper's affine state summary."""
42
43 l2norm_fwd: Callable[..., Any]
44 l2norm_bwd: Callable[..., Any]
45 fused_beta_sigmoid: Callable[..., Any]
46 fused_beta_sigmoid_bwd: Callable[..., Any]
47 kda_gate_chunk_cumsum: Callable[..., Any]
48 kda_gate_bwd: Callable[..., Any]
49 chunk_kda_fwd_intra: Callable[..., Any]
50 recompute_w_u_fwd: Callable[..., Any]
51 chunk_gated_delta_rule_fwd_h: Callable[..., Any]
52 chunk_gla_fwd_o_gk: Callable[..., Any]
53 chunk_kda_bwd_dav: Callable[..., Any]
54 chunk_gated_delta_rule_bwd_dhu: Callable[..., Any]
55 chunk_kda_bwd_wy_dqkg_fused: Callable[..., Any]
56 chunk_kda_bwd_intra: Callable[..., Any]
57 chunk_local_cumsum: Callable[..., Any]
58
59
60@dataclass(frozen=True)
61class _FLAKDARuntime:
62 """Resolved external FLA runtime and its required KDA entry points."""
63
64 version: str
65 chunk_kda: Callable[..., Any]
66 staged: FLAKDAStagedOps
67
68
69def _get_attribute(module_name: str, attribute: str) -> Any:
70 """Import one required FLA symbol with a useful compatibility error."""
71 try:
72 module = importlib.import_module(module_name)
73 except ModuleNotFoundError as exc:
74 missing_name = getattr(exc, "name", None)
75 is_fla_module = (
76 missing_name is not None and str(missing_name).startswith("fla.")
77 )
78 if missing_name == module_name or is_fla_module:
79 raise RuntimeError(
80 "The installed FLA package is incompatible with Hyper KDA: "
81 f"missing module {module_name}."
82 ) from exc
83 raise RuntimeError(
84 f"FLA module {module_name} could not load runtime dependency "
85 f"{missing_name!r}."
86 ) from exc
87 except ImportError as exc:
88 raise RuntimeError(
89 f"FLA module {module_name} failed to import; inspect the chained "
90 "exception for the incompatible runtime library."
91 ) from exc
92 try:
93 return getattr(module, attribute)
94 except AttributeError as exc:
95 raise RuntimeError(
96 "The installed FLA package is incompatible with Hyper KDA: "
97 f"missing {module_name}.{attribute}. Install an FLA revision with "
98 "the Triton-Ascend KDA backend."
99 ) from exc
100
101
102def _parse_version(version: str) -> tuple[int, int, int]:
103 """Parse the numeric prefix of an FLA semantic version."""
104 match = re.match(r"^(\d+)\.(\d+)\.(\d+)", version)
105 if match is None:
106 raise RuntimeError(f"Unable to parse the installed FLA version {version!r}.")
107 return tuple(int(part) for part in match.groups())
108
109
110def _require_triton_ascend() -> None:
111 """Require the external FLA runtime to have a Triton Ascend backend."""
112 try:
113 importlib.import_module("triton")
114 ascend_backend = importlib.util.find_spec("triton.backends.ascend")
115 except (ImportError, ModuleNotFoundError) as exc:
116 raise RuntimeError(
117 "KDA backend='triton' requires Triton-Ascend in the runtime environment."
118 ) from exc
119 if ascend_backend is None:
120 raise RuntimeError(
121 "KDA backend='triton' found Triton, but its Ascend backend is missing."
122 )
123
124
125def _require_npu_backends() -> None:
126 """Verify that FLA registered every backend used by the staged P2P path."""
127 backend_specs = (
128 (
129 "fla.ops.kda.backends.triton_ascend",
130 "TritonAscendKDABackend",
131 ),
132 (
133 "fla.ops.common.backends.triton_ascend",
134 "TritonAscendCommonBackend",
135 ),
136 (
137 "fla.ops.gla.backends.triton_ascend",
138 "TritonAscendGLABackend",
139 ),
140 )
141 for module_name, class_name in backend_specs:
142 backend = _get_attribute(module_name, class_name)
143 if not backend.is_available():
144 raise RuntimeError(
145 "KDA backend='triton' requires FLA's Triton-Ascend backend "
146 f"{class_name}, but it is unavailable in this process."
147 )
148
149
150@lru_cache(maxsize=1)
151def _require_fla_kda_runtime() -> _FLAKDARuntime:
152 """Resolve and validate the optional external FLA dependency once."""
153 try:
154 fla = importlib.import_module("fla")
155 except ModuleNotFoundError as exc:
156 missing_name = getattr(exc, "name", None)
157 if missing_name != "fla":
158 raise RuntimeError(
159 "The external FLA package is present but cannot load runtime "
160 f"dependency {missing_name!r}."
161 ) from exc
162 raise RuntimeError(
163 "KDA backend='triton' requires the optional flash-linear-attention "
164 "package with its Triton-Ascend KDA backend."
165 ) from exc
166 except ImportError as exc:
167 raise RuntimeError(
168 "The external FLA package is present but failed to import; inspect "
169 "the chained exception for the incompatible runtime library."
170 ) from exc
171
172 version = getattr(fla, "__version__", None)
173 if not isinstance(version, str):
174 raise RuntimeError("The installed FLA package does not expose __version__.")
175 if _parse_version(version) < _MIN_FLA_VERSION:
176 minimum = ".".join(str(part) for part in _MIN_FLA_VERSION)
177 raise RuntimeError(
178 f"KDA backend='triton' requires FLA >= {minimum}, got {version}."
179 )
180
181 _require_triton_ascend()
182 _require_npu_backends()
183 staged = FLAKDAStagedOps(
184 l2norm_fwd=_get_attribute("fla.modules.l2norm", "l2norm_fwd"),
185 l2norm_bwd=_get_attribute("fla.modules.l2norm", "l2norm_bwd"),
186 fused_beta_sigmoid=_get_attribute(
187 "fla.ops.common.gate", "fused_beta_sigmoid"
188 ),
189 fused_beta_sigmoid_bwd=_get_attribute(
190 "fla.ops.common.gate", "fused_beta_sigmoid_bwd"
191 ),
192 kda_gate_chunk_cumsum=_get_attribute(
193 "fla.ops.kda.gate", "kda_gate_chunk_cumsum"
194 ),
195 kda_gate_bwd=_get_attribute("fla.ops.kda.gate", "kda_gate_bwd"),
196 chunk_kda_fwd_intra=_get_attribute(
197 "fla.ops.kda.chunk_intra", "chunk_kda_fwd_intra"
198 ),
199 recompute_w_u_fwd=_get_attribute(
200 "fla.ops.kda.wy_fast", "recompute_w_u_fwd"
201 ),
202 chunk_gated_delta_rule_fwd_h=_get_attribute(
203 "fla.ops.common.chunk_delta_h", "chunk_gated_delta_rule_fwd_h"
204 ),
205 chunk_gla_fwd_o_gk=_get_attribute(
206 "fla.ops.gla.chunk", "chunk_gla_fwd_o_gk"
207 ),
208 chunk_kda_bwd_dav=_get_attribute(
209 "fla.ops.kda.chunk_bwd", "chunk_kda_bwd_dAv"
210 ),
211 chunk_gated_delta_rule_bwd_dhu=_get_attribute(
212 "fla.ops.common.chunk_delta_h", "chunk_gated_delta_rule_bwd_dhu"
213 ),
214 chunk_kda_bwd_wy_dqkg_fused=_get_attribute(
215 "fla.ops.kda.chunk_bwd", "chunk_kda_bwd_wy_dqkg_fused"
216 ),
217 chunk_kda_bwd_intra=_get_attribute(
218 "fla.ops.kda.chunk_intra", "chunk_kda_bwd_intra"
219 ),
220 chunk_local_cumsum=_get_attribute(
221 "fla.ops.utils.cumsum", "chunk_local_cumsum"
222 ),
223 )
224 return _FLAKDARuntime(
225 version=version,
226 chunk_kda=_get_attribute("fla.ops.kda", "chunk_kda"),
227 staged=staged,
228 )
229
230
231def is_fla_triton_kda_available() -> bool:
232 """Return whether the optional external FLA KDA backend is usable."""
233 try:
234 _require_fla_kda_runtime()
235 except RuntimeError:
236 return False
237 return True
238
239
240def get_fla_kda_staged_ops() -> FLAKDAStagedOps:
241 """Return FLA staged operators for Hyper's state-P2P autograd function."""
242 return _require_fla_kda_runtime().staged
243
244
245def run_fla_chunk_kda(
246 query: torch.Tensor,
247 key: torch.Tensor,
248 value: torch.Tensor,
249 gate: torch.Tensor,
250 beta: torch.Tensor,
251 *,
252 a_log: torch.Tensor,
253 dt_bias: torch.Tensor,
254 scale: Optional[float] = None,
255 initial_state: Optional[torch.Tensor] = None,
256 output_final_state: bool = False,
257 lower_bound: float = -5.0,
258 chunk_size: int = 64,
259 safe_gate: bool = True,
260 cu_seqlens: Optional[torch.Tensor] = None,
261) -> tuple[torch.Tensor, Optional[torch.Tensor]]:
262 """Run FLA's public KDA API with the validated Kimi K3 fused contract."""
263 runtime = _require_fla_kda_runtime()
264 return runtime.chunk_kda(
265 q=query,
266 k=key,
267 v=value,
268 g=gate,
269 beta=beta,
270 A_log=a_log,
271 dt_bias=dt_bias,
272 scale=scale,
273 initial_state=initial_state,
274 output_final_state=output_final_state,
275 use_qk_l2norm_in_kernel=True,
276 use_gate_in_kernel=True,
277 use_beta_sigmoid_in_kernel=True,
278 safe_gate=safe_gate,
279 lower_bound=lower_bound,
280 chunk_size=chunk_size,
281 cu_seqlens=cu_seqlens,
282 )