Add kernel iteration selection for metrix dispatch filtering

[mawad-amd]

Summary

• Add --kernel-iteration N and --kernel-iteration-range RANGE CLI options to metrix profile for selecting specific kernel launch indices via rocprofv3's jobs[].kernel_iteration_range YAML field
• Plumb kernel_iteration_range through the Python API (Metrix.profile()), all backends (CounterBackend, GFX90a, GFX942), and the MCP server
• Replace the old broken use_kernel_iteration_range: bool flag with user-controlled kernel_iteration_range: Optional[str]
• Update README, SKILL.md, and docstrings with iteration semantics and guidance to combine with --kernel

Test plan

• 135 unit tests pass (MI355X, Vultr, Docker, ROCm 7.2)
• Live test: --kernel-iteration 3 correctly profiles only the 3rd launch
• Live test: --kernel-iteration-range [2,4] correctly profiles launches 2-4
• --kernel-iteration and --kernel-iteration-range are mutually exclusive (CLI parser test)
• CI

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR adds user-controlled kernel launch index selection to Metrix profiling by plumbing rocprofv3’s jobs[].kernel_iteration_range from the CLI/Python API through the backends and into the generated rocprofv3 input YAML, with corresponding unit tests and docs updates.

Changes:

• Add --kernel-iteration N and --kernel-iteration-range RANGE CLI options and forward them through Metrix.profile() and backend profiling.
• Write kernel_iteration_range into rocprofv3 input YAML jobs entries via ROCProfV3Wrapper.
• Extend MCP server profile_metrics to accept kernel_filter, kernel_iteration_range, and num_replays; add/adjust unit tests for the new plumbing.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
metrix/src/metrix/cli/main.py	Adds CLI flags for kernel iteration selection (mutually exclusive)
metrix/src/metrix/cli/profile_cmd.py	Resolves iteration flags into a kernel_iteration_range string and forwards to backend
metrix/src/metrix/api.py	Adds kernel_iteration_range to public Python API and forwards to backend
metrix/src/metrix/backends/base.py	Replaces old boolean flag with kernel_iteration_range and applies it during profiling replays
metrix/src/metrix/backends/gfx942.py	Forwards kernel_iteration_range to the rocprof wrapper
metrix/src/metrix/backends/gfx90a.py	Forwards kernel_iteration_range to the rocprof wrapper
metrix/src/metrix/profiler/rocprof_wrapper.py	Writes kernel_iteration_range into rocprofv3 input YAML jobs section
metrix/src/metrix/mcp/server.py	Expands MCP tool parameters to include kernel filtering/iteration and replays
metrix/tests/unit/test_rocprof_wrapper.py	Adds unit test ensuring YAML contains kernel_iteration_range
metrix/tests/unit/test_cli_parser.py	Adds unit tests for new CLI parsing and mutual exclusivity
metrix/tests/unit/test_api.py	Adds unit test verifying API plumbing to backend.profile
metrix/skill/SKILL.md	Documents new CLI options and guidance
metrix/README.md	Updates README with iteration semantics and CLI help text

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.