Agentic SYCL support

[danielfleischer]

Claude Code engine for SYCL XPU kernels (+ TFLOPS reporting, VTune profiling)

Summary

Adds a Claude Code optimization engine for SYCL/CUTLASS GEMM kernels on
Intel Xe, alongside the existing Triton path. The agent rewrites a whole .cpp
kernel each trial, then compiles (icpx) + benchmarks it via the existing
SyclExecutor, with correctness checked against a golden PyTorch/numpy
reference computed on the same bit-identical inputs. The change also adds a
TFLOPS / peak-utilization reporting convention and an independent VTune
gpu-hotspots profiler for SYCL kernels.

All GPU paths were developed and verified on real hardware — an Intel Arc Pro
B70 (Battlemage) with icpx + VTune 2026.0.

What's included

SYCL Claude engine (core)

• SyclExecutor.compare_with_reference() — runs the optimized kernel, loads
  D2.bin, reshapes to the golden's shape, compares with spec rtol/atol.
  The single mockable GPU seam. Also maps "Arc Pro B70" → the bmg-g31 AOT
  target.
• benchmark skill split into _run_triton / _run_sycl on --dsl; the SYCL
  path computes the golden via the PyTorch reference on the same
  A.bin/B0.bin inputs and prints the uniform baseline_us/triton_us line
  (the triton_us= token is kept verbatim so trial tooling parses uniformly
  across DSLs).
• cli reads {input}_pytorch.py as the golden reference for SYCL.
• validator gains SYCL static checks: missing_main, missing_io_contract,
  no_cutlass_include.

Workspace generation

• generator selects SYCL templates and a .cpp extension for dsl == sycl,
  substitutes a compilable starter stub when the input has no #include, and
  always writes the PyTorch golden reference as {name}_pytorch.py.
• New templates: CLAUDE.sycl.md.j2, optimize-kernel.sycl.md.j2,
  starter_kernel.sycl.cpp.j2 (a file-IO-honouring CUTLASS BMG GEMM).

Knowledge base

• sycl_io_contract.yaml — the runner harness contract (CLI args, A/B0/B1 .bin
  layout with bf16-as-int16, D2.bin f32 output, perf-line format, CUTLASS
  correctness constraints).
• sycl_vtune.yaml — VTune verbs + metric→CUTLASS-knob mapping.

TFLOPS / utilization reporting

• DeviceConfig.peak_tflops (default 160.0, PEAK_TFLOPS env override).
• Benchmark Performance: line appends tflops=<f>, util=<f>% on both DSL
  paths; the trial tree stores --tflops and shows it in trial status; the
  tool-runner agent surfaces it.

VTune profiling (independent gpu-hotspots module)

• SyclProfiler (core/sycl_profiler.py) — compiles via SyclExecutor, runs
  the binary under vtune -collect gpu-hotspots (characterization), parses the
  per-task report, and emits recommendations (memory-bound, low occupancy, high
  idle, low XMX/DPAS, L3 thrashing). Kept fully separate from the Triton
  gpu-offload profiler. profile skill dispatches on --dsl.

Example

• examples/sycl/ — hardware-verified worked example: baseline (t0, 256×256×32)
  and trial (t1, 128×128×32) CUTLASS GEMM kernels, a bf16 spec, the PyTorch
  golden reference, and a README with reproduction commands.

Design notes

• DSL-agnostic engine. ClaudeEngine / create_engine are unchanged; the
  work is DSL-aware workspace generation, a SYCL branch in the benchmark/profile
  skills, the golden-reference comparison, and SYCL templates/KB.
• Independent SYCL paths. SYCL kernels are compiled binaries with no
  PyTorch Model, so the benchmark and VTune paths don't reuse the Python-runner
  Triton code — they share data-layout conventions, not control flow.
• The file-IO contract is the load-bearing piece. No pre-existing .cpp
  implemented the A.bin/B0.bin/D2.bin + --input_dir/--output_dir
  contract; it lived only inside SyclExecutor. The starter kernel implements
  it and the KB documents it so the agent can produce a runnable kernel from
  scratch.

Verification (Intel Arc Pro B70, real hardware)

• Golden-reference correctness: bf16 GEMM vs f32 PyTorch matmul on identical
  inputs passes np.allclose at rtol=1e-2, atol=1e-2 (max abs diff ~2e-5).
• Benchmark skill: t0 compiles baseline+trial, checks vs golden →
  Correctness: PASSED, e.g. baseline_us=194.20, triton_us=83.10, speedup=2.34x, tflops=25.83, util=16.1%. Cached-baseline (t1+) path skips the
  baseline rerun.
• Workspace generation: .cpp input kept verbatim; PyTorch-only input
  substitutes the starter stub; SYCL CLAUDE.md / --dsl sycl command / golden
  ref / KB symlink all correct.
• VTune profiling: xe-forge-skill profile --dsl sycl produces real Xe
  hardware metrics (XVE Active/Stalled/Idle, occupancy, XMX/DPAS, L3) and
  correct recommendations.
• Unit tests: 52 pass (uv run pytest), platform-independent — the
  icpx/GPU/vtune seams are mocked. Ruff lint + format clean.

Hardware/tooling gotchas surfaced (documented in VTUNE.md / KB)

• VTune works on this box after the 2025.3→2026 upgrade, but
  vtune-self-checker.sh gives a false negative (its bundled DPC++ test app
  won't launch) — a real AOT bmg-g31 kernel profiles fine.
• The B70 uses the xe kernel driver (not i915); gpu-hotspots works.
• VTune column names containing a literal comma (GPU Memory Bandwidth, GB/sec:Read) break the -column parser; bandwidth is requested via the
  comma-free substring GB/sec in a separate report pass.
• _detect_device_target didn't recognize "Arc Pro B70" → added a bmg-g31
  mapping.

Scope / limitations (v1)

• GEMM-family kernels only (the file-IO inputs are GEMM-shaped). Non-GEMM
  ops are out of scope.
• Golden reference located by convention: {baseline_stem}_pytorch.py.
• VTune gpu-hotspots splits metrics across sampling passes, so memory-bandwidth
  can read near-zero for sub-millisecond kernels (sampling noise, not a parse
  bug); the stable signals are XVE/occupancy/XMX.

Commits

• Add SYCL golden-reference benchmarking infrastructure
• Add SYCL workspace generation to the Claude engine
• Add SYCL file-IO contract to the knowledge base
• Add SYCL Claude-engine GEMM example
• Add tests for the SYCL Claude engine
• Report TFLOPS and peak utilization across benchmark and trials
• Add SYCL VTune profiling via an independent gpu-hotspots module