"""Abstract base class for red-team attack strategies."""

from abc import ABC, abstractmethod
from typing import Optional


class RedTeamStrategy(ABC):
    """Abstract base for all red-team attack strategies."""

    @abstractmethod
    def build_system_prompt(
        self,
        target: str,
        current_turn: int,
        total_turns: int,
        scenario_description: str,
        metaprompt_plan: str = "",
        last_response_score: Optional[int] = None,
        adaptation_hint: Optional[str] = None,
        backtrack_history: Optional[list] = None,
        **kwargs,
    ) -> str:
        """Return the system prompt for this turn.

        Args:
            target: The attack objective.
            current_turn: Current turn number (1-indexed).
            total_turns: Total turns in the conversation.
            scenario_description: Description of the scenario/agent under test.
            metaprompt_plan: The attack plan generated by the metaprompt model.
            last_response_score: 0-10 score of the target's last response toward
                the attack goal. None on the first turn (no response yet).
            adaptation_hint: One-sentence instruction on how to adapt this turn
                based on the previous response score. None on the first turn.
            backtrack_history: List of dicts with keys "turn", "attack", "refusal"
                for approaches that were backtracked due to hard refusals.
                The target does NOT remember these exchanges.
            **kwargs: Additional strategy-specific parameters.
        """
        raise NotImplementedError

    @abstractmethod
    def get_phase_name(self, current_turn: int, total_turns: int) -> str:
        """Return the name of the current phase for a given turn.

        Used for logging and observability without accessing private internals.

        Args:
            current_turn: Current turn number (1-indexed).
            total_turns: Total turns in the conversation.

        Returns:
            Phase name string (e.g. "warmup", "probing", "escalation", "direct").
        """
        raise NotImplementedError
