aip-agents-binary 0.6.4__py3-none-any.whl

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()

aip_agents/utils/event_handler_registry.pyi

@@ -0,0 +1,23 @@
+from _typeshed import Incomplete
+from aip_agents.schema.a2a import A2AStreamEventType as A2AStreamEventType
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+
+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."""
+    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).
+        """
+
+DEFAULT_EVENT_HANDLER_REGISTRY: Incomplete

aip_agents/utils/file_prompt_utils.py

@@ -0,0 +1,176 @@
+"""Utilities for augmenting prompts with local file path notes.
+
+This module adds file path metadata to queries but does not read file contents.
+
+Authors:
+    Fachriza Adhiatma (fachriza.d.adhiatma@gdplabs.id)
+"""
+
+import os
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+FILE_PATH_SYSTEM_NOTE = (
+    "\n\n[System Note: The user has provided a file named '{filename}'. "
+    "It is available at the following local path: {path}]"
+)
+FILE_PATH_INACCESSIBLE_NOTE = (
+    "\n\n[System Note: A file path was provided ({path}), but the file is not accessible. "
+    "Please inform the user about this issue.]"
+)
+FILE_URL_SYSTEM_NOTE = (
+    "\n\n[System Note: The file is also available at the following URL: {url} (expires in {expires_in} {hour_unit}).]"
+)
+
+
+def _normalize_file_entry(entry: str | dict[str, object]) -> dict[str, object] | None:
+    """Normalize a single file entry into a dict.
+
+    Args:
+        entry: A string file path or a metadata dict.
+
+    Returns:
+        A normalized metadata dict or None if the entry is falsy.
+
+    Raises:
+        ValueError: If metadata dicts do not include a valid path.
+    """
+    if not entry:
+        return None
+
+    if isinstance(entry, str):
+        return {"path": entry}
+
+    if isinstance(entry, dict):
+        path = entry.get("path") or entry.get("local_path")
+        if not isinstance(path, str) or not path:
+            raise ValueError("file metadata dicts must include a non-empty 'path'")
+        return {
+            "path": path,
+            "filename": entry.get("filename"),
+            "s3_url": entry.get("s3_url") or entry.get("url") or entry.get("file_uri"),
+            "expires_in_hours": entry.get("expires_in_hours"),
+        }
+
+    raise ValueError("files must be a list of strings or dicts")
+
+
+def _dedupe_file_entries(files: list[str | dict[str, object]]) -> list[dict[str, object]]:
+    """Normalize and deduplicate file entries by their resolved path.
+
+    Args:
+        files: List of local filesystem paths or file metadata dicts.
+
+    Returns:
+        Deduplicated list of normalized dict entries.
+    """
+    seen: set[str] = set()
+    deduped_entries: list[dict[str, object]] = []
+
+    for raw_entry in files:
+        try:
+            normalized = _normalize_file_entry(raw_entry)
+        except ValueError as exc:
+            logger.warning(f"Skipping invalid file entry: {exc}")
+            continue
+        if not normalized:
+            continue
+        path_value = normalized.get("path")
+        path = path_value if isinstance(path_value, str) else str(path_value)
+        if path in seen:
+            continue
+        seen.add(path)
+        deduped_entries.append(normalized)
+
+    return deduped_entries
+
+
+def _format_expiration_hours(expires_in_hours: object) -> tuple[object, str]:
+    """Format expiration hours for display.
+
+    Args:
+        expires_in_hours: Expiration hours value.
+
+    Returns:
+        Tuple of (expires_value, hour_unit).
+    """
+    if isinstance(expires_in_hours, int):
+        return expires_in_hours, "hour" if expires_in_hours == 1 else "hours"
+
+    if isinstance(expires_in_hours, str) and expires_in_hours.isdigit():
+        expires_value = int(expires_in_hours)
+        return expires_value, "hour" if expires_value == 1 else "hours"
+
+    return "unknown", "hours"
+
+
+def _build_file_path_note(entry: dict[str, object]) -> str:
+    """Build the system note for a file path entry.
+
+    Args:
+        entry: Normalized file metadata dict.
+
+    Returns:
+        System note string describing the file path accessibility.
+    """
+    path = str(entry["path"])
+    is_accessible = os.path.isfile(path) and os.access(path, os.R_OK)
+    if is_accessible:
+        filename_value = entry.get("filename")
+        filename = filename_value if isinstance(filename_value, str) and filename_value else os.path.basename(path)
+        return FILE_PATH_SYSTEM_NOTE.format(filename=filename, path=path)
+
+    logger.warning(f"File path is not accessible: {path}")
+    return FILE_PATH_INACCESSIBLE_NOTE.format(path=path)
+
+
+def _build_file_url_note(entry: dict[str, object]) -> str:
+    """Build the system note for a file URL entry.
+
+    Args:
+        entry: Normalized file metadata dict.
+
+    Returns:
+        System note string describing the URL, or an empty string if no URL exists.
+    """
+    url = entry.get("s3_url")
+    if not isinstance(url, str) or not url:
+        return ""
+
+    expires_value, hour_unit = _format_expiration_hours(entry.get("expires_in_hours"))
+    return FILE_URL_SYSTEM_NOTE.format(
+        url=url,
+        expires_in=expires_value,
+        hour_unit=hour_unit,
+    )
+
+
+def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
+    """Augment query with file path system notes.
+
+    Args:
+        query: The original user query string.
+        files: List of local filesystem paths or file metadata dicts to include.
+
+    Returns:
+        The query with system notes appended for each file path.
+
+    Raises:
+        ValueError: If files is not a list of strings or metadata dicts.
+    """
+    if not isinstance(files, list):
+        raise ValueError("files must be a list of strings or dicts")
+
+    deduped_entries = _dedupe_file_entries(files)
+
+    if not deduped_entries:
+        return query
+
+    augmented_query = query
+    for entry in deduped_entries:
+        augmented_query += _build_file_path_note(entry)
+        augmented_query += _build_file_url_note(entry)
+
+    return augmented_query

aip_agents/utils/file_prompt_utils.pyi

@@ -0,0 +1,21 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+
+logger: Incomplete
+FILE_PATH_SYSTEM_NOTE: str
+FILE_PATH_INACCESSIBLE_NOTE: str
+FILE_URL_SYSTEM_NOTE: str
+
+def augment_query_with_file_paths(query: str, files: list[str | dict[str, object]]) -> str:
+    """Augment query with file path system notes.
+
+    Args:
+        query: The original user query string.
+        files: List of local filesystem paths or file metadata dicts to include.
+
+    Returns:
+        The query with system notes appended for each file path.
+
+    Raises:
+        ValueError: If files is not a list of strings or metadata dicts.
+    """