feat(ws1): Add PyTorch matmul reference operator

[a-kaa]

Summary

Adds the PyTorch reference GEMM/Matmul operator for Issue #108.

This implements NativeMatmulOp as the fp32 ground-truth baseline for dense projection
matmuls. The operator follows the frozen #108 interface contract:

• forward_fp32(a, b) casts inputs to fp32 and calls torch.matmul once
• op_class = "reduction"
• registry dispatch via kernel_registry.get_op("matmul")

Also adds operator documentation under docs/operators/matmul.md.

Implementation

• Added rl_engine/kernels/ops/pytorch/linear/matmul.py
• Added rl_engine/kernels/ops/pytorch/linear/__init__.py
• Registered PYTORCH_NATIVE_MATMUL in rl_engine/kernels/registry.py
• Added tests/test_matmul.py
• Added Matmul operator docs and linked them from docs/operators/README.md

Summary by CodeRabbit

• New Features

  • Added a new matmul operator with a native PyTorch reference implementation.
  • Enabled automatic matmul dispatch on CPU, CUDA, and ROCm.

• Documentation

  • Added a dedicated matmul operator documentation page.
  • Updated the operators index to include matmul.

• Tests

  • Added comprehensive matmul tests covering correctness, dtype behavior (including FP32 casting), supported shapes, batch invariance, and registry integration.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 15198113-4727-4cb8-8cd7-0127d7642df6

📥 Commits

Reviewing files that changed from the base of the PR and between 18a6640 and c545946.

📒 Files selected for processing (1)

• tests/test_matmul.py

🚧 Files skipped from review as they are similar to previous changes (1)

• tests/test_matmul.py

---

📝 Walkthrough

Walkthrough

Adds NativeMatmulOp, a PyTorch fp32-reference matrix multiplication operator, to rl_engine/kernels/ops/pytorch/linear/. The class is exported from the linear package init, registered under a new OpBackend.PYTORCH_NATIVE_MATMUL enum value, and wired into KernelRegistry._priority_map for CUDA, ROCm, and CPU. A new test module and operator documentation page are included.

Changes

NativeMatmulOp Feature

Layer / File(s)	Summary
NativeMatmulOp implementation and registry wiring rl_engine/kernels/ops/pytorch/linear/matmul.py, rl_engine/kernels/ops/pytorch/linear/__init__.py, rl_engine/kernels/registry.py	NativeMatmulOp defines forward (casts inputs to fp32, calls torch.matmul, returns result in original dtype), forward_fp32 (returns fp32 result directly), and __call__ (delegates to forward). __init__.py exports it via __all__. registry.py adds OpBackend.PYTORCH_NATIVE_MATMUL enum member and inserts "matmul" entries into _priority_map for "cuda", "rocm", and "cpu" platforms.
NativeMatmulOp test suite tests/test_matmul.py	Five test classes validate output shape, forward/forward_fp32 dtype contract, __call__/forward equivalence, bitwise fp32 match to torch.matmul, non-mutation of inputs, op_class = "reduction" metadata, batch invariance (per-row vs. full batch, padded batch), dtype-parameterized accuracy for float32/bfloat16/float16, Qwen3 projection shapes, and registry dispatch returning a NativeMatmulOp instance.
Matmul operator documentation docs/operators/matmul.md, docs/operators/README.md	New matmul.md documents entry points, backend dispatch, tensor contract, Qwen3 projection shape coverage, reference semantics, accuracy expectations, test command, and relevant files. README.md adds a bullet linking to matmul.md in the "Current Pages" list.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

🐇 Hop hop, a matrix joins the fold,
Two tensors meet in fp32 gold,
The registry maps the path with care,
Batch-invariant, dtype-aware!
The docs are fresh, the tests are bright—
torch.matmul shines in reference light. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: adding a PyTorch matmul reference operator, which aligns with the primary objective of the PR across all modified files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}