"""Provider interface + the provider-agnostic agent variable payload."""

from abc import ABC, abstractmethod


def build_agent_variables(candidate, job):
    """The variable payload every provider's agent receives."""
    return {
        "candidate_name": f"{candidate.first_name} {candidate.last_name}".strip(),
        "phone": candidate.phone_number or "",
        "job_title": job.title if job else "",
        "required_experience": job.experience_band if job else "",
        "required_skills": job.must_have_skills if job else "",
        "job_description": (job.work_details or "")[:2000] if job else "",
        "job_location": job.location if job else "",
    }


class BaseProvider(ABC):
    """One outbound-call backend. Implementations must be stateless."""

    name = "base"

    def validate_config(self) -> None:
        """Raise RuntimeError if this provider is missing required configuration.

        Called before a call is queued so a misconfiguration surfaces immediately
        as an error to the recruiter, rather than as a call that appears to start
        and then fails in the background. Default: nothing to check.
        """
        return None

    @abstractmethod
    def start_call(self, ai_call) -> str:
        """Place the call. Returns the provider's call id; raises on failure
        (the caller marks the AICall FAILED with the exception message)."""

    def cancel_call(self, ai_call) -> bool:
        """Best-effort cancel of a running call. Returns True if the provider
        accepted the cancellation."""
        return False