fix: add backwards-compatible alias for deprecated parameter name

[yurekami]

Summary

This PR adds backwards compatibility for the renamed parameter in get_mla_metadata(), addressing issue #108.

Problem

The parameter name was changed from num_heads_per_head_k to num_q_tokens_per_head_k, breaking existing code that uses the old name.

Solution

Add support for the old parameter name as a deprecated alias:

# Old code still works (with deprecation warning)
get_mla_metadata(seqlens, num_heads_per_head_k=8, num_heads_k=1)

# New recommended usage
get_mla_metadata(seqlens, num_q_tokens_per_head_k=8, num_heads_k=1)

# Positional arguments continue to work
get_mla_metadata(seqlens, 8, 1)

Changes

• Add num_heads_per_head_k as keyword-only deprecated parameter
• Emit DeprecationWarning when deprecated name is used
• Raise clear error if both old and new names are specified
• Use sentinel value to properly detect unset required parameters
• Preserve positional argument compatibility

Example Warning

DeprecationWarning: The parameter 'num_heads_per_head_k' is deprecated and will be removed 
in a future version. Please use 'num_q_tokens_per_head_k' instead.

Test plan

• Positional arguments work: get_mla_metadata(seqlens, 8, 1)
• New keyword works: get_mla_metadata(seqlens, num_q_tokens_per_head_k=8, num_heads_k=1)
• Old keyword works with warning: get_mla_metadata(seqlens, num_heads_per_head_k=8, num_heads_k=1)
• Error on conflicting names

Fixes #108

🤖 Generated with Claude Code