perf: tune bf16 gemv and add opt-in fused swiglu

- deepen common-shape BF16 GEMV tuning with warp-row tiling for LLaMA/Qwen2/GPT-NeoX/OPT decode projections
- add fused BF16 up/gate SwiGLU CUDA primitive with ASTRAI_SWIGLU=0/1/auto dispatch
- keep the unfused linear backend as the default path; auto enables no shape until per-architecture checkpoint gates pass
- fall back to the linear/torch chain when kernels are absent, on CPU, in training, or outside supported M/K/dtype shapes
- add gemv/swiglu benchmark scripts, dispatch and parity tests, and kernel documentation

Benchmark: NVIDIA L20 (sm_89), CUDA 12.8, PyTorch 2.11.0+cu128, idle GPU. AstrAI 1B config (24 layers, hidden 1536, vocab 100000), BF16, prompt 128, 32 greedy decode tokens, CUDA graphs enabled, A/B in separate interleaved processes (3 rounds, 8 trials each, medians). Default vs ASTRAI_SWIGLU=1 per generate call: batch 1 134.8->129.1 ms (+4.44%), batch 2 136.2->130.9 ms (+4.06%), batch 4 145.5->140.3 ms (+3.66%). Greedy output identical at batch 1, differs at batch 2/4, so auto stays unfused by default; kernelless fallback verified bit-identical greedy.

tests/extension/test_swiglu_dispatch.py

@@ -0,0 +1,94 @@
+import logging
+
+import pytest
+import torch
+import torch.nn.functional as F
+
+from astrai.extension import is_available, swiglu
+from astrai.model.components.mlp import MLP
+
+SWIGLU_AVAILABLE = (
+    torch.cuda.is_available()
+    and is_available("bf16_swiglu")
+    and torch.cuda.get_device_capability() >= (8, 0)
+)
+skip_no_swiglu = pytest.mark.skipif(
+    not SWIGLU_AVAILABLE,
+    reason="BF16 SwiGLU requires a built kernel and compute capability 8.0+",
+)
+
+
+def reference_swiglu(x, up_weight, gate_weight):
+    return F.linear(x, up_weight) * F.silu(F.linear(x, gate_weight))
+
+
+def test_cpu_and_training_calls_fall_back_with_gradients(monkeypatch):
+    monkeypatch.setenv("ASTRAI_SWIGLU", "1")
+    x = torch.randn(2, 8, requires_grad=True)
+    up_weight = torch.randn(4, 8, requires_grad=True)
+    gate_weight = torch.randn(4, 8, requires_grad=True)
+    actual = swiglu(x, up_weight, gate_weight)
+    expected = reference_swiglu(x, up_weight, gate_weight)
+    torch.testing.assert_close(actual, expected)
+    actual.sum().backward()
+    assert x.grad is not None
+    assert up_weight.grad is not None
+    assert gate_weight.grad is not None
+
+
+def test_invalid_mode_warns_and_uses_auto(monkeypatch, caplog):
+    monkeypatch.setenv("ASTRAI_SWIGLU", "invalid-test-mode")
+    with caplog.at_level(logging.WARNING):
+        actual = swiglu(torch.randn(2, 8), torch.randn(4, 8), torch.randn(4, 8))
+    assert actual.shape == (2, 4)
+    assert "using auto" in caplog.text
+
+
+def test_mlp_routes_through_swiglu_backend(monkeypatch):
+    sentinel = torch.randn(2, 4)
+
+    def fake_swiglu(x, up_weight, gate_weight):
+        assert x.shape == (2, 3)
+        assert up_weight.shape == gate_weight.shape == (4, 3)
+        return sentinel
+
+    monkeypatch.setattr("astrai.model.components.mlp.swiglu", fake_swiglu)
+    layer = MLP(3, 4)
+    output = layer(torch.randn(2, 3))
+    assert output["hidden_states"].shape == (2, 3)
+
+
+@skip_no_swiglu
+def test_mode_zero_disables_fused_kernel(monkeypatch):
+    monkeypatch.setenv("ASTRAI_SWIGLU", "0")
+    x = torch.randn(4, 1536, device="cuda", dtype=torch.bfloat16) * 0.1
+    up_weight = torch.randn(6912, 1536, device="cuda", dtype=torch.bfloat16) * 0.02
+    gate_weight = torch.randn_like(up_weight) * 0.02
+    with torch.no_grad():
+        actual = swiglu(x, up_weight, gate_weight)
+        expected = reference_swiglu(x, up_weight, gate_weight)
+    torch.testing.assert_close(actual, expected)
+
+
+@skip_no_swiglu
+def test_mode_one_forces_supported_shape(monkeypatch):
+    monkeypatch.setenv("ASTRAI_SWIGLU", "1")
+    x = torch.randn(4, 1536, device="cuda", dtype=torch.bfloat16) * 0.1
+    up_weight = torch.randn(6912, 1536, device="cuda", dtype=torch.bfloat16) * 0.02
+    gate_weight = torch.randn_like(up_weight) * 0.02
+    with torch.no_grad():
+        actual = swiglu(x, up_weight, gate_weight)
+        expected = reference_swiglu(x, up_weight, gate_weight)
+    torch.testing.assert_close(actual, expected, rtol=0.03, atol=0.01)
+
+
+@skip_no_swiglu
+def test_auto_falls_back_until_shape_is_qualified(monkeypatch):
+    monkeypatch.setenv("ASTRAI_SWIGLU", "auto")
+    x = torch.randn(4, 1536, device="cuda", dtype=torch.bfloat16)
+    up_weight = torch.randn(6912, 1536, device="cuda", dtype=torch.bfloat16)
+    gate_weight = torch.randn_like(up_weight)
+    with torch.no_grad():
+        actual = swiglu(x, up_weight, gate_weight)
+        expected = reference_swiglu(x, up_weight, gate_weight)
+    torch.testing.assert_close(actual, expected)