agent/nodes/gate_node.py

"""
gate_node.py — Safety gate that controls access to the full solution.

Gate logic (priority order):
  1. If turn_count < 2 AND gap_magnitude <= 7  → force hint (too early)
  2. If gap_magnitude > 7                       → allow solution (completely lost)
  3. Otherwise                                  → force hint (encourage effort)

This prevents immediate solution bypass while still being helpful for users
who are genuinely stuck and unable to make progress.
"""

from agent.models import AgentState


def gate_solution(state: AgentState) -> dict:
    """
    Evaluates whether to allow solution reveal or force a hint.
    Updates request_mode to 'solution' or 'hint_forced' accordingly.
    Does NOT call the LLM — purely deterministic routing.
    """
    turn_count = state.get("turn_count", 0)
    gap = state.get("gap_magnitude", 5)

    # Already in solution mode — apply gate logic
    if state.get("request_mode") == "solution":
        if gap > 7:
            # User is completely stuck — allow solution compassionately
            return {"request_mode": "solution"}
        elif turn_count < 2:
            # Too early — redirect to hint flow
            return {
                "request_mode": "hint_forced",
                "final_response": None,  # Clear any stale response
            }
        else:
            # Enough turns done and not completely lost — still redirect
            return {"request_mode": "hint_forced", "final_response": None}

    # Not a solution request — pass through unchanged
    return {}