aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.11__py3-none-any.whl

aip_agents/utils/datetime/normalization.py

@@ -0,0 +1,231 @@
+"""Timestamp normalization helpers.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from typing import Any, Final
+
+from aip_agents.utils.logger import get_logger
+
+__all__ = [
+    "normalize_timestamp_to_date",
+    "format_created_updated_label",
+    "is_valid_date_string",
+    "next_day_iso",
+]
+
+
+logger: Final = get_logger(__name__)
+
+DEFAULT_DATE_FORMAT: Final[str] = "%Y-%m-%d"
+DATETIME_FORMAT: Final[str] = "%Y-%m-%d %H:%M:%S"
+ISO_FORMATS: Final[list[str | None]] = [
+    None,  # ISO format
+    "%Y-%m-%d %H:%M:%S",
+    "%Y-%m-%d",
+    "%Y-%m-%dT%H:%M:%S",
+    "%Y-%m-%dT%H:%M:%S%z",
+    "%Y-%m-%dT%H:%M:%S.%f",
+    "%Y-%m-%dT%H:%M:%S.%f%z",
+]
+
+
+def normalize_timestamp_to_date(value: Any) -> str | None:
+    """Normalize various timestamp representations into a YYYY-MM-DD string.
+
+    This function handles multiple input types and formats, converting them to
+    a standardized ISO date string. It gracefully handles invalid inputs by
+    returning None or the string representation.
+
+    Args:
+        value: The timestamp value to normalize. Can be:
+            - None or empty string: Returns None
+            - int/float: Unix timestamp (seconds since epoch)
+            - str: ISO format, datetime string, or other string representation
+            - Other types: Converted to string representation
+
+    Returns:
+        str | None: A YYYY-MM-DD formatted date string, or None if the input
+            cannot be parsed as a valid date.
+
+    Raises:
+        ValueError: If the timestamp value is invalid (e.g., negative timestamp).
+
+    Examples:
+        >>> normalize_timestamp_to_date(1640995200)  # Unix timestamp
+        '2022-01-01'
+        >>> normalize_timestamp_to_date("2022-01-01T12:00:00")
+        '2022-01-01'
+        >>> normalize_timestamp_to_date("invalid")
+        'invalid'
+        >>> normalize_timestamp_to_date(None)
+        None
+    """
+    # Handle None and empty values
+    if value in (None, ""):
+        return None
+
+    if isinstance(value, int | float):
+        return _normalize_numeric_timestamp(value)
+    elif isinstance(value, str):
+        return _normalize_string_timestamp(value)
+    else:
+        # For any other type, convert to string
+        return str(value)
+
+
+def _normalize_numeric_timestamp(value: int | float) -> str | None:
+    """Normalize numeric timestamp to ISO date string.
+
+    Args:
+        value: Numeric timestamp (seconds since epoch).
+
+    Returns:
+        ISO date string or None if invalid.
+
+    Raises:
+        ValueError: If timestamp is negative.
+    """
+    try:
+        if value < 0:
+            raise ValueError(f"Negative timestamp value: {value}")
+        return datetime.fromtimestamp(value).date().isoformat()
+    except (OSError, OverflowError, ValueError):
+        logger.warning(f"Invalid timestamp value: {value}")
+        return None
+
+
+def _normalize_string_timestamp(ts: str) -> str | None:
+    """Normalize string timestamp to ISO date string.
+
+    Args:
+        ts: String timestamp in various formats.
+
+    Returns:
+        ISO date string, original string if unparseable, or None if empty.
+    """
+    ts = ts.strip()
+    if not ts:
+        return None
+
+    # Handle ISO format with timezone
+    iso_candidate = ts.replace("Z", "+00:00") if ts.endswith("Z") else ts
+
+    # Try different parsing strategies
+    for fmt in ISO_FORMATS:
+        try:
+            if fmt is None:
+                dt = datetime.fromisoformat(iso_candidate)
+            else:
+                dt = datetime.strptime(ts, fmt)
+            return dt.date().isoformat()
+        except ValueError:
+            continue
+
+    # If no format worked, return the original string
+    # This preserves the original behavior for unparseable strings
+    return ts
+
+
+def format_created_updated_label(created_at: Any | None, updated_at: Any | None) -> str | None:
+    """Build a compact label combining created/updated timestamps when available.
+
+    Creates a human-readable label that shows creation and update timestamps
+    in a compact format. If both dates are the same, only shows one date.
+
+    Args:
+        created_at: The creation timestamp (any format supported by normalize_timestamp_to_date).
+        updated_at: The update timestamp (any format supported by normalize_timestamp_to_date).
+
+    Returns:
+        str | None: A formatted label string, or None if both inputs are invalid/empty.
+            Examples: "2022-01-01", "2022-01-01 (updated 2022-01-02)", "updated 2022-01-01"
+
+    Examples:
+        >>> format_created_updated_label("2022-01-01", "2022-01-02")
+        '2022-01-01 (updated 2022-01-02)'
+        >>> format_created_updated_label("2022-01-01", "2022-01-01")
+        '2022-01-01'
+        >>> format_created_updated_label(None, "2022-01-01")
+        'updated 2022-01-01'
+        >>> format_created_updated_label("2022-01-01", None)
+        '2022-01-01'
+    """
+    created = normalize_timestamp_to_date(created_at)
+    updated = normalize_timestamp_to_date(updated_at)
+
+    if created and updated:
+        if created == updated:
+            return created
+        return f"{created} (updated {updated})"
+    if created:
+        return created
+    if updated:
+        return f"updated {updated}"
+    return None
+
+
+def is_valid_date_string(date_str: str, fmt: str = DEFAULT_DATE_FORMAT) -> bool:
+    """Validate that a date string matches the provided strftime format.
+
+    Args:
+        date_str: The date string to validate. Must be a non-empty string.
+        fmt: The strftime format pattern to validate against.
+            Defaults to YYYY-MM-DD format.
+
+    Returns:
+        bool: True if the date string matches the format, False otherwise.
+
+    Raises:
+        ValueError: If the format string is empty or invalid, or if date_str is not a string.
+
+    Examples:
+        >>> is_valid_date_string("2022-01-01")
+        True
+        >>> is_valid_date_string("2022-13-01")
+        False
+        >>> is_valid_date_string("01-01-2022", "%m-%d-%Y")
+        True
+        >>> is_valid_date_string("", "%Y-%m-%d")
+        False
+    """
+    if not isinstance(date_str, str):
+        raise ValueError(f"date_str must be a string, got {type(date_str).__name__}")
+
+    if not fmt or not fmt.strip():
+        raise ValueError("Format string cannot be empty")
+
+    if not date_str or not date_str.strip():
+        return False
+
+    try:
+        datetime.strptime(date_str.strip(), fmt)
+        return True
+    except (ValueError, TypeError) as e:
+        logger.debug(f"Date string '{date_str}' does not match format '{fmt}': {e}")
+        return False
+
+
+def next_day_iso(date_str: str) -> str:
+    """Return the ISO date string for the day after the given ``YYYY-MM-DD`` date.
+
+    Args:
+        date_str: A date string in ``YYYY-MM-DD`` format.
+
+    Returns:
+        str: The next day's date in ``YYYY-MM-DD`` format.
+
+    Raises:
+        ValueError: If ``date_str`` is not a valid ``YYYY-MM-DD`` date string.
+    """
+    try:
+        pivot = datetime.strptime(date_str.strip(), "%Y-%m-%d")
+    except ValueError as exc:
+        raise ValueError(f"Invalid date string '{date_str}'. Expected YYYY-MM-DD.") from exc
+
+    next_day = pivot + timedelta(days=1)
+    return next_day.date().isoformat()

aip_agents/utils/datetime/normalization.pyi

@@ -0,0 +1,95 @@
+from typing import Any
+
+__all__ = ['normalize_timestamp_to_date', 'format_created_updated_label', 'is_valid_date_string', 'next_day_iso']
+
+def normalize_timestamp_to_date(value: Any) -> str | None:
+    '''Normalize various timestamp representations into a YYYY-MM-DD string.
+
+    This function handles multiple input types and formats, converting them to
+    a standardized ISO date string. It gracefully handles invalid inputs by
+    returning None or the string representation.
+
+    Args:
+        value: The timestamp value to normalize. Can be:
+            - None or empty string: Returns None
+            - int/float: Unix timestamp (seconds since epoch)
+            - str: ISO format, datetime string, or other string representation
+            - Other types: Converted to string representation
+
+    Returns:
+        str | None: A YYYY-MM-DD formatted date string, or None if the input
+            cannot be parsed as a valid date.
+
+    Raises:
+        ValueError: If the timestamp value is invalid (e.g., negative timestamp).
+
+    Examples:
+        >>> normalize_timestamp_to_date(1640995200)  # Unix timestamp
+        \'2022-01-01\'
+        >>> normalize_timestamp_to_date("2022-01-01T12:00:00")
+        \'2022-01-01\'
+        >>> normalize_timestamp_to_date("invalid")
+        \'invalid\'
+        >>> normalize_timestamp_to_date(None)
+        None
+    '''
+def format_created_updated_label(created_at: Any | None, updated_at: Any | None) -> str | None:
+    '''Build a compact label combining created/updated timestamps when available.
+
+    Creates a human-readable label that shows creation and update timestamps
+    in a compact format. If both dates are the same, only shows one date.
+
+    Args:
+        created_at: The creation timestamp (any format supported by normalize_timestamp_to_date).
+        updated_at: The update timestamp (any format supported by normalize_timestamp_to_date).
+
+    Returns:
+        str | None: A formatted label string, or None if both inputs are invalid/empty.
+            Examples: "2022-01-01", "2022-01-01 (updated 2022-01-02)", "updated 2022-01-01"
+
+    Examples:
+        >>> format_created_updated_label("2022-01-01", "2022-01-02")
+        \'2022-01-01 (updated 2022-01-02)\'
+        >>> format_created_updated_label("2022-01-01", "2022-01-01")
+        \'2022-01-01\'
+        >>> format_created_updated_label(None, "2022-01-01")
+        \'updated 2022-01-01\'
+        >>> format_created_updated_label("2022-01-01", None)
+        \'2022-01-01\'
+    '''
+def is_valid_date_string(date_str: str, fmt: str = ...) -> bool:
+    '''Validate that a date string matches the provided strftime format.
+
+    Args:
+        date_str: The date string to validate. Must be a non-empty string.
+        fmt: The strftime format pattern to validate against.
+            Defaults to YYYY-MM-DD format.
+
+    Returns:
+        bool: True if the date string matches the format, False otherwise.
+
+    Raises:
+        ValueError: If the format string is empty or invalid, or if date_str is not a string.
+
+    Examples:
+        >>> is_valid_date_string("2022-01-01")
+        True
+        >>> is_valid_date_string("2022-13-01")
+        False
+        >>> is_valid_date_string("01-01-2022", "%m-%d-%Y")
+        True
+        >>> is_valid_date_string("", "%Y-%m-%d")
+        False
+    '''
+def next_day_iso(date_str: str) -> str:
+    """Return the ISO date string for the day after the given ``YYYY-MM-DD`` date.
+
+    Args:
+        date_str: A date string in ``YYYY-MM-DD`` format.
+
+    Returns:
+        str: The next day's date in ``YYYY-MM-DD`` format.
+
+    Raises:
+        ValueError: If ``date_str`` is not a valid ``YYYY-MM-DD`` date string.
+    """

aip_agents/utils/datetime/timezone.py

@@ -0,0 +1,206 @@
+"""Timezone-related helper functions."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Final
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from aip_agents.utils.logger import get_logger
+
+__all__ = ["get_timezone_aware_now", "ensure_utc_datetime"]
+
+logger: Final = get_logger(__name__)
+
+
+def get_timezone_aware_now(timezone: str, fallback_timezone: str = "UTC") -> tuple[datetime, str, bool]:
+    """Return a timezone-aware datetime alongside a timezone label.
+
+    This function creates a timezone-aware datetime object using the modern
+    zoneinfo module (Python 3.9+). It gracefully falls back to UTC if the
+    requested timezone is invalid.
+
+    Args:
+        timezone: Desired timezone name in IANA format (e.g., "America/New_York",
+            "Europe/London", "Asia/Tokyo"). Must be a non-empty string.
+        fallback_timezone: Fallback timezone name to use when the primary
+            timezone is invalid. Defaults to "UTC". Must be a non-empty string.
+
+    Returns:
+        tuple[datetime, str, bool]: A 3-tuple containing:
+            - now: A timezone-aware datetime object representing the current time
+            - timezone_label: A human-readable timezone label (e.g., "EST", "UTC")
+            - used_fallback: Boolean indicating whether the fallback timezone was used
+
+    Raises:
+        ValueError: If timezone or fallback_timezone are empty/invalid, or if both
+            the requested timezone and fallback timezone are invalid.
+
+    Examples:
+        >>> now, label, fallback = get_timezone_aware_now("America/New_York")
+        >>> print(f"Current time: {now}, Timezone: {label}, Used fallback: {fallback}")
+        Current time: 2024-01-15 10:30:00-05:00, Timezone: EST, Used fallback: False
+
+        >>> now, label, fallback = get_timezone_aware_now("Invalid/Timezone")
+        >>> print(f"Used fallback: {fallback}, Label: {label}")
+        Used fallback: True, Label: UTC
+    """
+    timezone = _normalize_timezone("timezone", timezone)
+    fallback_timezone = _normalize_timezone("fallback_timezone", fallback_timezone)
+
+    tz, used_fallback = _load_timezone_with_case_enforcement(timezone, fallback_timezone)
+    now = datetime.now(tz)
+    timezone_label = _resolve_timezone_label(now, timezone, fallback_timezone, used_fallback)
+
+    return now, timezone_label, used_fallback
+
+
+def ensure_utc_datetime(value: datetime) -> datetime:
+    """Normalize a datetime to UTC (attaching UTC to naive values).
+
+    Args:
+        value: Datetime to normalize.
+
+    Returns:
+        datetime: Timezone-aware datetime expressed in UTC.
+
+    Raises:
+        TypeError: If ``value`` is not a ``datetime`` instance.
+    """
+    if not isinstance(value, datetime):
+        raise TypeError(f"Expected datetime, received {type(value).__name__}")
+
+    if value.tzinfo is None or value.tzinfo.utcoffset(value) is None:
+        return value.replace(tzinfo=ZoneInfo("UTC"))
+
+    return value.astimezone(ZoneInfo("UTC"))
+
+
+def _normalize_timezone(param_name: str, value: str) -> str:
+    """Validate and normalize a timezone parameter.
+
+    Args:
+        param_name: Name of the parameter being validated, used in error messages.
+        value: Raw timezone string provided by the caller.
+
+    Returns:
+        A stripped, non-empty timezone string.
+
+    Raises:
+        ValueError: If ``value`` is not a non-empty string.
+    """
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f"{param_name} must be a non-empty string")
+    return value.strip()
+
+
+def _load_timezone_with_case_enforcement(timezone: str, fallback_timezone: str) -> tuple[ZoneInfo, bool]:
+    """Load timezone ensuring case-sensitive behavior, falling back when needed.
+
+    Args:
+        timezone: Requested timezone name in IANA format.
+        fallback_timezone: Fallback timezone to use when the requested one is invalid.
+
+    Returns:
+        A tuple containing the resolved ``ZoneInfo`` object and a boolean indicating
+        whether the fallback timezone was used.
+
+    Raises:
+        ValueError: If both ``timezone`` and ``fallback_timezone`` are invalid.
+    """
+    requested_tz = _load_requested_timezone(timezone)
+    if requested_tz is not None:
+        return requested_tz, False
+
+    logger.warning(
+        "Timezone '%s' unavailable, attempting fallback to '%s'",
+        timezone,
+        fallback_timezone,
+    )
+    return _load_fallback_timezone(timezone, fallback_timezone)
+
+
+def _load_requested_timezone(timezone: str) -> ZoneInfo | None:
+    """Attempt to load the requested timezone with case enforcement.
+
+    Args:
+        timezone: Requested timezone name in IANA format.
+
+    Returns:
+        The corresponding ``ZoneInfo`` if the timezone exists and matches case,
+        otherwise ``None``.
+    """
+    try:
+        candidate_tz = ZoneInfo(timezone)
+    except ZoneInfoNotFoundError:
+        logger.warning("Timezone '%s' was not found", timezone)
+        return None
+
+    canonical_key = getattr(candidate_tz, "key", None)
+    if canonical_key and canonical_key.lower() == timezone.lower() and canonical_key != timezone:
+        logger.warning(
+            "Timezone '%s' resolved to canonical key '%s'; case-sensitive handling requires an exact match",
+            timezone,
+            canonical_key,
+        )
+        return None
+
+    logger.debug("Successfully loaded timezone: %s", timezone)
+    return candidate_tz
+
+
+def _load_fallback_timezone(timezone: str, fallback_timezone: str) -> tuple[ZoneInfo, bool]:
+    """Load the fallback timezone or raise a descriptive error.
+
+    Args:
+        timezone: Original requested timezone name, used for error messaging.
+        fallback_timezone: Fallback timezone to attempt loading.
+
+    Returns:
+        A tuple containing the fallback ``ZoneInfo`` and ``True`` to indicate that the
+        fallback was used.
+
+    Raises:
+        ValueError: If the fallback timezone is also invalid.
+    """
+    try:
+        fallback_tz = ZoneInfo(fallback_timezone)
+    except ZoneInfoNotFoundError as ex:
+        error_msg = (
+            f"Both requested timezone '{timezone}' and fallback timezone "
+            f"'{fallback_timezone}' are invalid. Please provide valid IANA timezone names."
+        )
+        logger.error(error_msg)
+        raise ValueError(error_msg) from ex
+
+    logger.debug("Successfully loaded fallback timezone: %s", fallback_timezone)
+    return fallback_tz, True
+
+
+def _resolve_timezone_label(
+    now: datetime,
+    timezone: str,
+    fallback_timezone: str,
+    used_fallback: bool,
+) -> str:
+    """Determine the human-readable label for the timezone used.
+
+    Args:
+        now: The timezone-aware datetime generated using the resolved timezone.
+        timezone: Requested timezone name in IANA format.
+        fallback_timezone: Fallback timezone name in IANA format.
+        used_fallback: Whether the fallback timezone was used.
+
+    Returns:
+        A human-readable timezone label for display purposes.
+    """
+    if used_fallback:
+        return fallback_timezone
+
+    try:
+        timezone_label = now.strftime("%Z")
+        if not timezone_label:
+            return timezone
+        return timezone_label
+    except (ValueError, OSError):
+        return timezone

aip_agents/utils/datetime/timezone.pyi

@@ -0,0 +1,48 @@
+from datetime import datetime
+
+__all__ = ['get_timezone_aware_now', 'ensure_utc_datetime']
+
+def get_timezone_aware_now(timezone: str, fallback_timezone: str = 'UTC') -> tuple[datetime, str, bool]:
+    '''Return a timezone-aware datetime alongside a timezone label.
+
+    This function creates a timezone-aware datetime object using the modern
+    zoneinfo module (Python 3.9+). It gracefully falls back to UTC if the
+    requested timezone is invalid.
+
+    Args:
+        timezone: Desired timezone name in IANA format (e.g., "America/New_York",
+            "Europe/London", "Asia/Tokyo"). Must be a non-empty string.
+        fallback_timezone: Fallback timezone name to use when the primary
+            timezone is invalid. Defaults to "UTC". Must be a non-empty string.
+
+    Returns:
+        tuple[datetime, str, bool]: A 3-tuple containing:
+            - now: A timezone-aware datetime object representing the current time
+            - timezone_label: A human-readable timezone label (e.g., "EST", "UTC")
+            - used_fallback: Boolean indicating whether the fallback timezone was used
+
+    Raises:
+        ValueError: If timezone or fallback_timezone are empty/invalid, or if both
+            the requested timezone and fallback timezone are invalid.
+
+    Examples:
+        >>> now, label, fallback = get_timezone_aware_now("America/New_York")
+        >>> print(f"Current time: {now}, Timezone: {label}, Used fallback: {fallback}")
+        Current time: 2024-01-15 10:30:00-05:00, Timezone: EST, Used fallback: False
+
+        >>> now, label, fallback = get_timezone_aware_now("Invalid/Timezone")
+        >>> print(f"Used fallback: {fallback}, Label: {label}")
+        Used fallback: True, Label: UTC
+    '''
+def ensure_utc_datetime(value: datetime) -> datetime:
+    """Normalize a datetime to UTC (attaching UTC to naive values).
+
+    Args:
+        value: Datetime to normalize.
+
+    Returns:
+        datetime: Timezone-aware datetime expressed in UTC.
+
+    Raises:
+        TypeError: If ``value`` is not a ``datetime`` instance.
+    """

aip_agents/utils/env_loader.py

@@ -0,0 +1,27 @@
+"""Utility helpers for loading local .env files in examples and apps."""
+
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def load_local_env(override: bool = True) -> None:
+    """Load environment variables from a .env file if python-dotenv is available.
+
+    Args:
+        override (bool, optional): Whether to override existing environment variables. Defaults to True.
+    """
+    try:
+        from dotenv import find_dotenv, load_dotenv  # type: ignore[import-not-found]  # noqa: PLC0415
+    except ImportError:
+        logger.warning("Could not load .env file: python-dotenv not installed")
+        return
+
+    try:
+        env_path = find_dotenv(usecwd=True)
+        load_dotenv(env_path, override=override)
+        logger.debug("Successfully loaded .env from %s", env_path)
+    except Exception as exc:  # pragma: no cover - behaviour depends on environment
+        logger.warning("Could not load .env file: %s", exc)

aip_agents/utils/env_loader.pyi

@@ -0,0 +1,10 @@
+from _typeshed import Incomplete
+
+logger: Incomplete
+
+def load_local_env(override: bool = True) -> None:
+    """Load environment variables from a .env file if python-dotenv is available.
+
+    Args:
+        override (bool, optional): Whether to override existing environment variables. Defaults to True.
+    """

aip_agents/utils/event_handler_registry.py

@@ -0,0 +1,58 @@
+"""Shared event handler registry for streaming payload processing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from aip_agents.schema.a2a import A2AStreamEventType
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class EventHandlerRegistry:
+    """Registry for tracking known streaming events with pass-through behaviour."""
+
+    def __init__(self) -> None:
+        """Initialize the event handler registry with known event types."""
+        self._known_events: set[str] = {self._normalize_event_type(event) for event in A2AStreamEventType}
+
+    def handle(self, event_type: A2AStreamEventType | str | None, payload: dict[str, Any]) -> dict[str, Any]:
+        """Return the payload unchanged while logging unknown events.
+
+        Args:
+            event_type (A2AStreamEventType | str | None): The type of the streaming event.
+            payload (dict[str, Any]): The event payload data.
+
+        Returns:
+            dict[str, Any]: The payload unchanged (pass-through).
+        """
+        normalized = self._normalize_event_type(event_type)
+        if normalized not in self._known_events:
+            logger.info(
+                "Unknown event type encountered in event handler registry; using default passthrough.",
+                extra={
+                    "event_type": normalized,
+                    "metadata_keys": list((payload.get("metadata") or {}).keys()) if isinstance(payload, dict) else [],
+                },
+            )
+        return payload
+
+    @staticmethod
+    def _normalize_event_type(event_type: A2AStreamEventType | str | None) -> str:
+        """Return a lowercase string for the supplied event type or ``unknown``.
+
+        Args:
+            event_type: Enum instance, string literal, or None representing the event.
+
+        Returns:
+            str: Normalized event type identifier.
+        """
+        if isinstance(event_type, A2AStreamEventType):
+            return event_type.value
+        if isinstance(event_type, str) and event_type:
+            return event_type
+        return "unknown"
+
+
+DEFAULT_EVENT_HANDLER_REGISTRY = EventHandlerRegistry()