"""
Shared retry observability utilities for LLM provider clients.

All provider clients (OpenAI, Azure, Bedrock, Ollama, etc.) import from here
so the retry record shape is defined once and consistent across providers.
"""
from __future__ import annotations

from typing import Any, Dict, List, Type


def build_retry_record(
    attempt: int,
    delay: float,
    exc_type: Type[BaseException],
    outcome: str,
) -> Dict[str, Any]:
    """Build a single retry attempt record."""
    return {
        "attempt": attempt,
        "delay_s": round(delay, 3),
        "exception_type": exc_type.__name__,
        "outcome": outcome,
    }


def build_retry_summary(history: List[Dict[str, Any]]) -> Dict[str, Any]:
    """Build a summary dict from a completed retry history list."""
    if not history:
        return {}
    last = history[-1]
    return {
        "total_attempts": len(history) + 1,
        "retries": len(history),
        "latest_exception_type": last["exception_type"],
        "latest_outcome": last["outcome"],
    }


__all__ = ["build_retry_record", "build_retry_summary"]
