rewards/recursion_efficiency.py

"""Recursion efficiency reward component — REW-04 v2.

Linear decay on llm_call_count. Pure Python, stdlib-only.

Intended ranges:
  0 calls  → 1.0 (best — task didn't need recursion)
  1 call   → 0.75
  2 calls  → 0.50
  3 calls  → 0.25
  4+ calls → 0.00 (recursion spam is wasteful)

This score is *coupled to correctness* in compose.py — wrong answers don't
earn an efficiency bonus, which prevents the model from learning to spam
`llm(` strings in code blocks for free reward.
"""

def recursion_efficiency(llm_call_count: int, **_) -> float:
    """Linear-decay efficiency on call count; gated to correctness in compose."""
    count = max(0, int(llm_call_count))
    return max(0.0, 1.0 - 0.25 * count)


__all__ = ["recursion_efficiency"]