"""Migration helpers for deprecated provider records.

Scans agent configuration records for deprecated provider values (e.g. "vllm")
and produces structured deprecation warnings to guide operators toward the
canonical protocol names.

Requirements: 2.2, 3.8
"""
from __future__ import annotations

from dataclasses import dataclass

from services.shared.inference.factory import PROTOCOL_ALIASES


@dataclass(frozen=True)
class ProviderDeprecationWarning:
    """Structured deprecation warning for an agent record using a deprecated provider.

    Attributes:
        agent_id: The ID of the agent with the deprecated provider.
        current_value: The current deprecated provider string (e.g. "vllm").
        recommended_value: The canonical protocol to migrate to.
        message: Human-readable migration guidance.
    """

    agent_id: str
    current_value: str
    recommended_value: str
    message: str


def check_deprecated_providers(
    agent_records: list[dict],
) -> list[ProviderDeprecationWarning]:
    """Scan agent records for deprecated provider values.

    Checks the ``model_provider`` field of each agent record against
    PROTOCOL_ALIASES. Records using deprecated aliases get a warning
    with migration guidance.

    Args:
        agent_records: List of dicts, each having at least ``agent_id``
            (or ``id``) and ``model_provider`` fields.

    Returns:
        List of ProviderDeprecationWarning for records using deprecated providers.
    """
    warnings_list: list[ProviderDeprecationWarning] = []

    for record in agent_records:
        agent_id = str(record.get("agent_id") or record.get("id", "unknown"))
        provider = (record.get("model_provider") or "").strip().lower()

        if provider in PROTOCOL_ALIASES:
            recommended = PROTOCOL_ALIASES[provider]
            warnings_list.append(
                ProviderDeprecationWarning(
                    agent_id=agent_id,
                    current_value=provider,
                    recommended_value=recommended,
                    message=(
                        f"Agent {agent_id} uses deprecated provider '{provider}'. "
                        f"Migrate to protocol '{recommended}'. "
                        f"The '{provider}' alias will be removed in a future version."
                    ),
                )
            )

    return warnings_list