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

aip_agents/utils/artifact_helpers.pyi

@@ -0,0 +1,203 @@
+from aip_agents.a2a.types import Artifact as Artifact, ArtifactType as ArtifactType, MimeType as MimeType, get_mime_type_from_filename as get_mime_type_from_filename
+from langgraph.types import Command
+from typing import Any
+
+class ArtifactHandler:
+    """Handler class for creating and managing artifacts in agent tools.
+
+    This class provides a clean, object-oriented interface for artifact creation
+    with built-in validation, deduplication, and standardized formatting.
+    """
+    def __init__(self) -> None:
+        """Initialize the ArtifactHandler."""
+    def create_file_artifact(self, result: str, artifact_data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
+        '''Deprecated. Use create_artifact instead.
+
+        Args:
+            result (str): The message/result to show to the agent.
+            artifact_data (bytes | str): The binary data for the artifact.
+            artifact_name (str): The name for the artifact file.
+            artifact_description (str, optional): Description of the artifact. Defaults to "".
+            mime_type (str | None, optional): MIME type of the artifact. If None, will be auto-detected.
+            enable_deduplication (bool, optional): Whether to deduplicate by content hash. Defaults to True.
+
+        Returns:
+            dict[str, Any]: Dictionary with \'result\' and \'artifact\' keys.
+        '''
+    def create_text_artifact(self, result: str, artifact_text: str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
+        '''Deprecated. Use create_artifact instead.
+
+        Args:
+            result (str): The message/result to show to the agent.
+            artifact_text (str): The text content for the artifact.
+            artifact_name (str): The name for the artifact file.
+            artifact_description (str, optional): Description of the artifact. Defaults to "".
+            mime_type (str | None, optional): MIME type of the artifact. If None, will be auto-detected.
+            enable_deduplication (bool, optional): Whether to deduplicate by content hash. Defaults to True.
+
+        Returns:
+            dict[str, Any]: Dictionary with \'result\' and \'artifact\' keys.
+        '''
+    def create_artifact(self, result: str, data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, enable_deduplication: bool = True) -> dict[str, Any]:
+        """Create an artifact with automatic text/binary handling.
+
+        Args:
+            result: The message/result to show to the agent.
+            data: The data for the artifact. Bytes for binary; str for text or base64.
+            artifact_name: The filename to present to users.
+            artifact_description: Description of the artifact.
+            mime_type: Optional MIME type. If None, inferred from filename.
+            enable_deduplication: Whether to deduplicate by content hash.
+
+        Returns:
+            Dictionary with 'result' and 'artifact' keys.
+        """
+    def create_error_response(self, error_message: str) -> str:
+        """Create a standardized error response for tools.
+
+        Args:
+            error_message: The error message to return.
+
+        Returns:
+            String with error information.
+        """
+    def clear_cache(self) -> None:
+        """Clear the artifact cache."""
+    def get_cache_size(self) -> int:
+        """Get the number of cached artifacts.
+
+        Returns:
+            Number of artifacts in cache.
+        """
+    @staticmethod
+    def generate_artifact_hash(artifact_data: str, name: str, mime_type: str) -> str:
+        """Generate a hash for artifact deduplication.
+
+        Args:
+            artifact_data: Base64 encoded artifact data.
+            name: Artifact name.
+            mime_type: MIME type.
+
+        Returns:
+            Hash string for deduplication.
+        """
+
+def create_artifact_response(result: str, artifact_data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None) -> dict[str, Any]:
+    '''Create a standardized artifact response for tools.
+
+    This function creates a response that separates the agent-facing result
+    from the user-facing artifact, following the established pattern for
+    artifact generation in the agent system.
+
+    Args:
+        result: The message/result to show to the agent (clean, no file data).
+        artifact_data: The binary data or base64 string for the artifact.
+        artifact_name: The name for the artifact file.
+        artifact_description: Description of the artifact. Defaults to "".
+        mime_type: MIME type of the artifact. If None, will be auto-detected from filename.
+
+    Returns:
+        Dictionary with \'result\' and \'artifacts\' keys (artifacts is always a list).
+
+    Example:
+        >>> import io
+        >>> csv_data = "Name,Age\\\\nAlice,30\\\\nBob,25"
+        >>> response = create_artifact_response(
+        ...     result="Generated a 2-row CSV table",
+        ...     artifact_data=csv_data.encode(\'utf-8\'),
+        ...     artifact_name="data.csv",
+        ...     artifact_description="Sample data table",
+        ...     mime_type="text/csv"
+        ... )
+        >>> assert "result" in response
+        >>> assert "artifacts" in response
+        >>> assert isinstance(response["artifacts"], list)
+    '''
+def create_text_artifact_response(result: str, artifact_text: str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None) -> dict[str, Any]:
+    """Create a standardized artifact response for tools.
+
+    Args:
+        result: The message/result to show to the agent.
+        artifact_text: The text content for the artifact.
+        artifact_name: The name for the artifact file.
+        artifact_description: Description of the artifact.
+        mime_type: MIME type of the artifact. If None, will be auto-detected from filename.
+
+    Returns:
+        Dictionary with 'result' and 'artifacts' keys (artifacts is always a list).
+    """
+def create_multiple_artifacts_response(result: str, artifacts: list[dict[str, Any]]) -> dict[str, Any]:
+    """Create a standardized response for multiple artifacts.
+
+    Args:
+        result: The message/result to show to the agent.
+        artifacts: List of artifact dictionaries.
+
+    Returns:
+        Dictionary with 'result' and 'artifacts' keys.
+    """
+def create_artifact_command(result: str, artifact_data: bytes | str, artifact_name: str, artifact_description: str = '', mime_type: str | None = None, metadata_update: dict[str, Any] | None = None) -> Command:
+    """Create a Command that updates artifacts (and optional metadata).
+
+    Args:
+        result: Message/result to show to the agent (for ToolMessage content).
+        artifact_data: The binary data or base64 string for the artifact.
+        artifact_name: The name for the artifact file.
+        artifact_description: Description of the artifact.
+        mime_type: MIME type of the artifact. If None, auto-detected from filename.
+        metadata_update: Optional metadata delta to merge into state metadata.
+
+    Returns:
+        Command: A LangGraph Command with update containing 'result', 'artifacts', and optional 'metadata'.
+    """
+def create_multiple_artifacts_command(result: str, artifacts: list[Artifact | dict[str, Any]] | None = None, metadata_update: dict[str, Any] | None = None) -> Command:
+    """Create a Command that updates multiple artifacts (and optional metadata).
+
+    The 'artifacts' list accepts mixed item types:
+    - Artifact: a typed artifact model (preferred). Will be converted via model_dump().
+    - dict: a prebuilt artifact dict ready for A2A.
+    - DataSpec dict: raw spec to build an artifact with keys:
+        {'data': bytes|str, 'artifact_name': str, 'artifact_description'?: str, 'mime_type'?: str}
+
+    Args:
+        result: Message/result to show to the agent.
+        artifacts: List of items (Artifact | dict) to attach or build.
+        metadata_update: Optional metadata delta to merge into state metadata.
+
+    Returns:
+        Command: A LangGraph Command with update containing 'result', 'artifacts', and optional 'metadata'.
+    """
+def create_error_response(error_message: str) -> str:
+    """Create a standardized error response for tools.
+
+    For error cases, we return a simple string that will be passed directly
+    to the agent without any artifact processing.
+
+    Args:
+        error_message: The error message to return.
+
+    Returns:
+        String with error information.
+    """
+def extract_artifacts_from_agent_response(result: Any) -> tuple[str, list[dict[str, Any]]]:
+    """Extract artifacts from agent response for delegation tools.
+
+    Args:
+        result: The result returned by the delegated agent.
+
+    Returns:
+        Tuple of (text_response, artifacts_list) where:
+        - text_response: The text content for the agent
+        - artifacts_list: List of artifacts to be passed through
+    """
+def create_delegation_response_with_artifacts(result: str, artifacts: list[dict[str, Any]], agent_name: str = '') -> Command:
+    """Create a delegation response that includes artifacts only when needed.
+
+    Args:
+        result: The text result from the delegated agent.
+        artifacts: List of artifacts from the delegated agent (always a list).
+        agent_name: Name of the agent for prefixing the result.
+
+    Returns:
+        Command containing 'result' and optional 'artifacts'.
+    """

aip_agents/utils/constants.py

@@ -0,0 +1,22 @@
+"""Shared constants for AIP Agents.
+
+This module defines commonly used constants across the agents library
+to avoid duplication and maintain consistency.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from enum import StrEnum
+from uuid import UUID
+
+__all__ = ["DefaultTimezone", "DEFAULT_PII_TAG_NAMESPACE"]
+
+
+class DefaultTimezone(StrEnum):
+    """Default timezone constants used across the application."""
+
+    JAKARTA = "Asia/Jakarta"
+
+
+DEFAULT_PII_TAG_NAMESPACE: UUID = UUID("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

aip_agents/utils/constants.pyi

@@ -0,0 +1,10 @@
+from enum import StrEnum
+from uuid import UUID
+
+__all__ = ['DefaultTimezone', 'DEFAULT_PII_TAG_NAMESPACE']
+
+class DefaultTimezone(StrEnum):
+    """Default timezone constants used across the application."""
+    JAKARTA: str
+
+DEFAULT_PII_TAG_NAMESPACE: UUID

aip_agents/utils/datetime/__init__.py

@@ -0,0 +1,34 @@
+"""Datetime-related helper utilities.
+
+This module provides utilities for working with dates, times, and timezones
+in a robust and consistent manner. It includes functions for normalizing
+timestamp formats, validating date strings, and working with timezone-aware
+datetimes.
+
+The module is organized into the following submodules:
+- normalization: Functions for normalizing and validating timestamp formats
+- timezone: Functions for working with timezone-aware datetimes
+
+All functions in this module are designed to be robust and handle edge cases
+gracefully, making them suitable for production use.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.utils.datetime.normalization import (
+    format_created_updated_label,
+    is_valid_date_string,
+    next_day_iso,
+    normalize_timestamp_to_date,
+)
+from aip_agents.utils.datetime.timezone import ensure_utc_datetime, get_timezone_aware_now
+
+__all__ = [
+    "normalize_timestamp_to_date",
+    "format_created_updated_label",
+    "is_valid_date_string",
+    "next_day_iso",
+    "ensure_utc_datetime",
+    "get_timezone_aware_now",
+]

aip_agents/utils/datetime/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.utils.datetime.normalization import format_created_updated_label as format_created_updated_label, is_valid_date_string as is_valid_date_string, next_day_iso as next_day_iso, normalize_timestamp_to_date as normalize_timestamp_to_date
+from aip_agents.utils.datetime.timezone import ensure_utc_datetime as ensure_utc_datetime, get_timezone_aware_now as get_timezone_aware_now
+
+__all__ = ['normalize_timestamp_to_date', 'format_created_updated_label', 'is_valid_date_string', 'next_day_iso', 'ensure_utc_datetime', 'get_timezone_aware_now']

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.
+    """