Skip to main content

qualia_mcp/tools/
wgsl_forge.rs

1//! MCP tool for WGSL Forge: deterministic WGSL generation, validation, certification, and tuning.
2//!
3//! Follows `AGENTS.md` §0-B (<500 lines).
4
5use crate::types::{parse_tool_args, McpSystemError};
6use qualia_core_db::poet_host::PoetSnapshot;
7use qualia_core_db::wgsl_forge::{
8    generate_builtin, roofline_for, synthesize_causal_attention, validate_wgsl,
9    AdapterConstraints, AttentionSchedule, AttentionShape, BuiltinKernel, Schedule,
10    ScheduleSpace, TargetBackend,
11};
12use serde_json::{json, Value};
13use std::str::FromStr;
14
15/// `wgsl_forge` tool — deterministic WGSL kernel generation, validation, roofline analysis, and attention synthesis.
16pub fn wgsl_forge(raw_args: &[u8]) -> Result<String, McpSystemError> {
17    let v = parse_tool_args(raw_args)?;
18    let op = v
19        .get("op")
20        .and_then(Value::as_str)
21        .unwrap_or("list_kernels");
22
23    // Attempt dispatch via PoetSnapshot invoke host first
24    let canonical_id = if op.starts_with("WgslForge.") {
25        op.to_string()
26    } else {
27        format!("WgslForge.{op}")
28    };
29    let vibe_args = super::vibe::json_to_vibe(&v);
30    let mut snap = PoetSnapshot::live();
31
32    if let Ok(res) = snap.invoke_id(&canonical_id, vibe_args) {
33        return Ok(json!({
34            "status": "ok",
35            "op": op,
36            "id": canonical_id,
37            "result": super::vibe::vibe_to_json(&res),
38        })
39        .to_string());
40    }
41
42    // Direct WGSL Forge dispatch fallback
43    match op {
44        "list_kernels" => {
45            let filter = v.get("filter").and_then(Value::as_str).unwrap_or("");
46            let mut kernels = Vec::new();
47            for builtin in BuiltinKernel::ALL {
48                let name = builtin.name();
49                if !filter.is_empty() && !name.contains(filter) {
50                    continue;
51                }
52                let spec = builtin.spec();
53                kernels.push(json!({
54                    "name": name,
55                    "version": spec.semantic_version,
56                    "description": spec.description,
57                    "has_gpu_oracle": builtin.has_gpu_oracle(),
58                }));
59            }
60
61            let viewport_pipelines = vec![
62                "cyber_glass",
63                "barnes_hut_graph_physics",
64                "wire_particles",
65                "manifold_grid_10d",
66                "aurora_curtains",
67                "terrain_pbr_pom",
68                "ocean_gerstner",
69                "black_hole_lensing",
70            ];
71
72            Ok(json!({
73                "status": "ok",
74                "op": "list_kernels",
75                "kernel_count": kernels.len(),
76                "kernels": kernels,
77                "viewport_pipelines": viewport_pipelines,
78            })
79            .to_string())
80        }
81
82        "generate" => {
83            let kernel_name = v.get("kernel").and_then(Value::as_str).unwrap_or("affine-f32");
84            let target_str = v.get("target").and_then(Value::as_str).unwrap_or("wgsl");
85            let workgroup_size = v
86                .get("workgroup_size")
87                .and_then(Value::as_u64)
88                .unwrap_or(64) as u32;
89            let items_per_invocation = v
90                .get("items_per_invocation")
91                .and_then(Value::as_u64)
92                .unwrap_or(1) as u32;
93            let vector_width = v
94                .get("vector_width")
95                .and_then(Value::as_u64)
96                .unwrap_or(1) as u32;
97
98            let builtin = BuiltinKernel::from_str(kernel_name).map_err(|e| {
99                McpSystemError::ExecutionFailed(format!("WgslForge.generate unknown kernel: {e}"))
100            })?;
101            let target = TargetBackend::from_str(target_str).map_err(|e| {
102                McpSystemError::ExecutionFailed(format!("WgslForge.generate invalid target: {e}"))
103            })?;
104            let schedule = Schedule {
105                workgroup_size,
106                items_per_invocation,
107                vector_width,
108                ..Default::default()
109            };
110
111            let generated = generate_builtin(builtin, schedule, target).map_err(|e| {
112                McpSystemError::ExecutionFailed(format!("WgslForge.generate failed: {e}"))
113            })?;
114
115            Ok(json!({
116                "status": "ok",
117                "op": "generate",
118                "kernel_id": generated.kernel_id,
119                "target": target_str,
120                "entry_point": "main",
121                "semantic_hash": generated.semantic_hash,
122                "source_hash": generated.source_hash,
123                "workgroup_size": workgroup_size,
124                "source": generated.source,
125            })
126            .to_string())
127        }
128
129        "validate" => {
130            let source_to_validate = if let Some(src) = v.get("source").and_then(Value::as_str) {
131                src.to_string()
132            } else {
133                let kernel_name = v.get("kernel").and_then(Value::as_str).unwrap_or("affine-f32");
134                let workgroup_size = v
135                    .get("workgroup_size")
136                    .and_then(Value::as_u64)
137                    .unwrap_or(64) as u32;
138                let items_per_invocation = v
139                    .get("items_per_invocation")
140                    .and_then(Value::as_u64)
141                    .unwrap_or(1) as u32;
142                let vector_width = v
143                    .get("vector_width")
144                    .and_then(Value::as_u64)
145                    .unwrap_or(1) as u32;
146                let builtin = BuiltinKernel::from_str(kernel_name).map_err(|e| {
147                    McpSystemError::ExecutionFailed(format!("WgslForge.validate unknown kernel: {e}"))
148                })?;
149                let schedule = Schedule {
150                    workgroup_size,
151                    items_per_invocation,
152                    vector_width,
153                    ..Default::default()
154                };
155                generate_builtin(builtin, schedule, TargetBackend::Wgsl)
156                    .map_err(|e| {
157                        McpSystemError::ExecutionFailed(format!("WgslForge.validate generation failed: {e}"))
158                    })?
159                    .source
160            };
161
162            let report = validate_wgsl(&source_to_validate).map_err(|e| {
163                McpSystemError::ExecutionFailed(format!("WgslForge.validate Naga error: {e}"))
164            })?;
165
166            Ok(json!({
167                "status": "ok",
168                "op": "validate",
169                "naga_validated": report.naga_validated,
170                "binding_count": report.binding_count,
171                "entry_points": report.entry_points,
172            })
173            .to_string())
174        }
175
176        "roofline" => {
177            let kernel_name = v.get("kernel").and_then(Value::as_str).unwrap_or("affine-f32");
178            let n = v.get("n").and_then(Value::as_u64).unwrap_or(65_536).max(1);
179            let builtin = BuiltinKernel::from_str(kernel_name).map_err(|e| {
180                McpSystemError::ExecutionFailed(format!("WgslForge.roofline unknown kernel: {e}"))
181            })?;
182            let est = roofline_for(builtin, n);
183
184            Ok(json!({
185                "status": "ok",
186                "op": "roofline",
187                "kernel": builtin.name(),
188                "n": n,
189                "flops": est.flops,
190                "bytes": est.bytes,
191                "arithmetic_intensity": est.arithmetic_intensity,
192                "bound": format!("{:?}", est.bound),
193            })
194            .to_string())
195        }
196
197        "schedule_candidates" => {
198            let kernel_name = v.get("kernel").and_then(Value::as_str).unwrap_or("affine-f32");
199            let builtin = BuiltinKernel::from_str(kernel_name).map_err(|e| {
200                McpSystemError::ExecutionFailed(format!("WgslForge.schedule_candidates unknown kernel: {e}"))
201            })?;
202            let spec = builtin.spec();
203            let constraints = AdapterConstraints::portable();
204            let space = ScheduleSpace::default();
205            let candidates = space.candidates(&spec, &constraints);
206
207            let list: Vec<Value> = candidates
208                .iter()
209                .map(|c| {
210                    json!({
211                        "workgroup_size": c.workgroup_size,
212                        "items_per_invocation": c.items_per_invocation,
213                        "vector_width": c.vector_width,
214                    })
215                })
216                .collect();
217
218            Ok(json!({
219                "status": "ok",
220                "op": "schedule_candidates",
221                "kernel": builtin.name(),
222                "candidate_count": list.len(),
223                "candidates": list,
224            })
225            .to_string())
226        }
227
228        "attention_synthesize" => {
229            let head_dim = v.get("head_dim").and_then(Value::as_u64).unwrap_or(64) as u32;
230            let head_count = v.get("head_count").and_then(Value::as_u64).unwrap_or(16) as u32;
231            let context_tokens = v
232                .get("context_tokens")
233                .and_then(Value::as_u64)
234                .unwrap_or(512) as u32;
235            let batch_tokens = v.get("batch_tokens").and_then(Value::as_u64).unwrap_or(1) as u32;
236            let mode = v.get("mode").and_then(Value::as_str).unwrap_or("decode");
237
238            let shape = AttentionShape {
239                head_dim,
240                head_count,
241                context_tokens,
242                batch_tokens,
243            };
244            let schedule = if mode.eq_ignore_ascii_case("prefill") {
245                AttentionSchedule::a2000_prefill()
246            } else {
247                AttentionSchedule::a2000_decode()
248            };
249
250            let shader = synthesize_causal_attention(shape, schedule).map_err(|e| {
251                McpSystemError::ExecutionFailed(format!("WgslForge.attention_synthesize failed: {e}"))
252            })?;
253
254            Ok(json!({
255                "status": "ok",
256                "op": "attention_synthesize",
257                "source_hash": shader.source_hash,
258                "workgroup_size": shader.schedule.workgroup_size,
259                "naga_validated": shader.validation.naga_validated,
260                "binding_count": shader.validation.binding_count,
261                "source": shader.source,
262            })
263            .to_string())
264        }
265
266        other => Err(McpSystemError::ExecutionFailed(format!(
267            "Unsupported wgsl_forge operation: {other}"
268        ))),
269    }
270}