"""Contracts and data models for deploy workflows."""

from __future__ import annotations

from collections.abc import Callable, Mapping
from dataclasses import dataclass, field
from typing import Any, Protocol


class ActionTrackerProtocol(Protocol):
    """Minimal ActionTracker surface consumed by deploy helpers."""

    def update_status(self, step_code: str, status: str, description: str) -> None:
        """Publish a lifecycle status update to the platform tracker.

        Args:
            step_code: Lifecycle step identifier (for example ``MDL_DPY_ACK``).
            status: Status level string such as ``OK`` or ``ERROR``.
            description: Human-readable status description.

        Returns:
            None.
        """
        ...

    def log_error(self, file_path: str, module: str, message: str) -> None:
        """Record an error event in the platform tracker.

        Args:
            file_path: Source file associated with the error event.
            module: Logical module or location string.
            message: Error detail to persist in tracking backend.

        Returns:
            None.
        """
        ...


RuntimeLoader = Callable[[Any], Any]
RuntimePredictor = Callable[[Any, bytes], Any]


@dataclass(frozen=True)
class RuntimeRoute:
    """Runtime-specific load and predict handlers."""

    loader: RuntimeLoader
    predictor: RuntimePredictor


@dataclass
class ModelBundle:
    """Loaded model bundle passed between deploy load/predict phases."""

    framework: str
    model: Any
    metadata: dict[str, Any] = field(default_factory=dict)


RouteRegistry = Mapping[str, RuntimeRoute]
