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

aip_agents/utils/datetime/normalization.pyi

@@ -1,95 +0,0 @@
-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.pyi

@@ -1,48 +0,0 @@
-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.pyi

@@ -1,10 +0,0 @@
-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.pyi

@@ -1,23 +0,0 @@
-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.pyi

@@ -1,21 +0,0 @@
-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.
-    """

aip_agents/utils/final_response_builder.pyi

@@ -1,34 +0,0 @@
-from dataclasses import dataclass
-from datetime import datetime
-from typing import Any
-
-__all__ = ['FinalResponseMetadataOptions', 'assemble_final_response']
-
-@dataclass(slots=True)
-class FinalResponseMetadataOptions:
-    """Container for optional metadata fields on final response events."""
-    step_id: str | None = ...
-    previous_step_ids: list[str] | None = ...
-    tool_info: dict[str, Any] | None = ...
-    thinking_and_activity_info: dict[str, Any] | None = ...
-    completion_reason: str | None = ...
-    timeout_seconds: float | None = ...
-    message: dict[str, Any] | None = ...
-    partial_result: str | None = ...
-    metadata_extra: dict[str, Any] | None = ...
-
-def assemble_final_response(*, content: str, artifacts: list[dict[str, Any]] | None = None, metadata_options: FinalResponseMetadataOptions | None = None, status: str = 'success', task_state: str = 'completed', extra_fields: dict[str, Any] | None = None, timestamp: datetime | None = None) -> dict[str, Any]:
-    '''Create a final response event with optional artifacts and overrides.
-
-    Args:
-        content: Human readable message for the final response.
-        artifacts: Optional list of artifact dictionaries to attach.
-        metadata_options: Metadata overrides passed through to the underlying builder.
-        status: Top-level status string; defaults to ``"success"``.
-        task_state: State string describing the task; defaults to ``"completed"``.
-        extra_fields: Additional top-level fields to merge onto the event.
-        timestamp: Explicit timestamp for the event. Defaults to ``datetime.now(UTC)``.
-
-    Returns:
-        dict[str, Any]: Final response event payload ready for downstream streaming.
-    '''

aip_agents/utils/formatter_llm_client.pyi

@@ -1,71 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.utils.logger import get_logger as get_logger
-from collections.abc import Awaitable as Awaitable
-from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
-from typing import Any, TypeVar
-
-logger: Incomplete
-FORMATTER_ENV_VAR: str
-T = TypeVar('T')
-
-class FormatterInvokerUnavailableError(RuntimeError):
-    """Raised when no formatter LLM invoker can be resolved."""
-class FormatterInvocationError(RuntimeError):
-    """Raised when invoking the formatter LLM fails."""
-
-class FormatterLLMClient:
-    """Stateful helper that manages formatter invoker resolution and execution."""
-    def __init__(self) -> None:
-        """Initialize the formatter LLM client with caching and thread safety."""
-    def seed_default(self, default_model_id: str | None) -> None:
-        """Populate ``DEFAULT_MODEL_FORMATTER`` when unset.
-
-        Args:
-            default_model_id: Preferred formatter model id to use as a fallback.
-        """
-    def resolve_invoker(self, *, reset_cache: bool = False) -> BaseLMInvoker | None:
-        """Return the cached formatter invoker, optionally refreshing it.
-
-        Args:
-            reset_cache: When True, clear the cached invoker before resolving.
-
-        Returns:
-            BaseLMInvoker | None: Cached invoker if the formatter is configured, otherwise None.
-        """
-    async def invoke(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
-        """Dispatch formatter prompts asynchronously with timeout/error handling.
-
-        Args:
-            *args: Positional arguments forwarded to the invoker.
-            invoker: Explicit invoker instance to reuse instead of resolving one.
-            timeout: Optional timeout (seconds) enforced with ``asyncio.timeout``.
-            **kwargs: Keyword arguments forwarded to the invoker.
-
-        Returns:
-            Any: Result returned by the formatter LLM.
-
-        Raises:
-            FormatterInvokerUnavailableError: If no formatter model is configured.
-            FormatterInvocationError: When the invocation fails or exceeds the timeout.
-        """
-    def invoke_blocking(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
-        """Invoke the formatter LLM from synchronous contexts.
-
-        Args:
-            *args: Positional arguments forwarded to ``invoke``.
-            invoker: Optional invoker to reuse.
-            timeout: Optional timeout (seconds) for the async invocation.
-            **kwargs: Keyword arguments forwarded to ``invoke``.
-
-        Returns:
-            Any: Result returned by the formatter LLM.
-        """
-
-def get_formatter_llm_client() -> FormatterLLMClient:
-    """Return the process-wide formatter LLM client."""
-def seed_formatter_llm_default(default_model_id: str | None) -> None:
-    """Convenience wrapper for seeding the formatter default model.
-
-    Args:
-        default_model_id: Formatter model identifier to seed when missing.
-    """

aip_agents/utils/langgraph/__init__.pyi

@@ -1,3 +0,0 @@
-from aip_agents.utils.langgraph.converter import convert_gllm_tool_call_to_langchain_tool_call as convert_gllm_tool_call_to_langchain_tool_call, convert_langchain_messages_to_gllm_messages as convert_langchain_messages_to_gllm_messages, convert_langchain_tool_call_to_gllm_tool_call as convert_langchain_tool_call_to_gllm_tool_call, convert_lm_output_to_langchain_message as convert_lm_output_to_langchain_message
-
-__all__ = ['convert_gllm_tool_call_to_langchain_tool_call', 'convert_langchain_tool_call_to_gllm_tool_call', 'convert_lm_output_to_langchain_message', 'convert_langchain_messages_to_gllm_messages']

aip_agents/utils/langgraph/converter.pyi

@@ -1,49 +0,0 @@
-from collections.abc import Sequence
-from gllm_inference.schema import LMOutput, Message, ToolCall as GllmToolCall
-from langchain_core.messages import AIMessage, BaseMessage as BaseMessage
-from langchain_core.messages.tool import ToolCall as LangChainToolCall
-
-def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
-    """Convert LangChain messages to gllm-inference Message format.
-
-    This function transforms a sequence of LangChain messages into the Message
-    format expected by LM Invoker. It handles system messages, human messages, AI messages
-    with tool calls, and tool result messages.
-
-    Args:
-        messages: Sequence of LangChain BaseMessage objects to convert.
-        instruction: System instruction to prepend if not already present in messages.
-
-    Returns:
-        List of Message objects containing the converted message sequence.
-    """
-def convert_lm_output_to_langchain_message(response: LMOutput | str) -> AIMessage:
-    """Convert LM Invoker output to LangChain AIMessage.
-
-    This function transforms the output from LM Invoker back into LangChain's
-    AIMessage format, handling both text responses and tool calls.
-
-    Args:
-        response: The response from LM Invoker (MultimodalOutput).
-
-    Returns:
-        AIMessage containing the converted response.
-    """
-def convert_langchain_tool_call_to_gllm_tool_call(lc_tool_call: LangChainToolCall) -> GllmToolCall:
-    """Convert LangChain tool call to gllm ToolCall.
-
-    Args:
-        lc_tool_call: LangChain ToolCall (TypedDict).
-
-    Returns:
-        GllmToolCall object for gllm-inference.
-    """
-def convert_gllm_tool_call_to_langchain_tool_call(gllm_tool_call: GllmToolCall) -> LangChainToolCall:
-    """Convert gllm ToolCall to LangChain ToolCall format.
-
-    Args:
-        gllm_tool_call: GllmToolCall object from gllm-inference.
-
-    Returns:
-        LangChain ToolCall (TypedDict) with proper type annotation.
-    """

aip_agents/utils/langgraph/tool_managers/__init__.pyi

@@ -1,5 +0,0 @@
-from aip_agents.utils.langgraph.tool_managers.a2a_tool_manager import A2AToolManager as A2AToolManager
-from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
-from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import DelegationToolManager as DelegationToolManager
-
-__all__ = ['BaseLangGraphToolManager', 'A2AToolManager', 'DelegationToolManager']

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.pyi

@@ -1,35 +0,0 @@
-from _typeshed import Incomplete
-from a2a.types import AgentCard as AgentCard
-from aip_agents.utils.a2a_connector import A2AConnector as A2AConnector
-from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
-from aip_agents.utils.logger import get_logger as get_logger
-from langchain_core.tools import BaseTool
-
-logger: Incomplete
-
-class A2AToolManager(BaseLangGraphToolManager):
-    """Manages A2A communication tools for LangGraph agents.
-
-    This tool manager converts A2A agent cards into LangChain tools that can
-    be used in a unified ToolNode within LangGraph agents. Each A2A agent
-    becomes a tool that the LLM can call for external communication.
-    """
-    registered_agents: list
-    def __init__(self) -> None:
-        """Initialize the A2A tool manager."""
-    created_tools: Incomplete
-    def register_resources(self, agent_cards: list[AgentCard]) -> list[BaseTool]:
-        """Register A2A agents and convert them to LangChain tools.
-
-        Args:
-            agent_cards: List of AgentCard instances for external communication.
-
-        Returns:
-            List of created A2A communication tools.
-        """
-    def get_resource_names(self) -> list[str]:
-        """Get names of all registered A2A agents.
-
-        Returns:
-            list[str]: A list of names of all registered A2A agents.
-        """

aip_agents/utils/langgraph/tool_managers/base_tool_manager.pyi

@@ -1,48 +0,0 @@
-from _typeshed import Incomplete
-from abc import ABC, abstractmethod
-from aip_agents.utils.logger import get_logger as get_logger
-from langchain_core.tools import BaseTool as BaseTool
-from typing import Any
-
-logger: Incomplete
-
-class BaseLangGraphToolManager(ABC):
-    """Base class for managing specialized tools in LangGraph agents.
-
-    This abstract base class provides a common interface for tool managers
-    that convert different types of capabilities into LangChain tools for
-    use in LangGraph agents.
-
-    The design follows a simple pattern:
-    1. Register resources (agents, cards, etc.)
-    2. Convert resources to LangChain tools
-    3. Provide access to created tools
-    """
-    created_tools: list[BaseTool]
-    def __init__(self) -> None:
-        """Initialize the tool manager."""
-    @abstractmethod
-    def register_resources(self, resources: list[Any]) -> list[BaseTool]:
-        """Register resources and convert them to LangChain tools.
-
-        Args:
-            resources: List of resources to convert to tools.
-
-        Returns:
-            List of created tools.
-        """
-    def get_tools(self) -> list[BaseTool]:
-        """Get all created tools.
-
-        Returns:
-            Copy of created tools list.
-        """
-    def clear_tools(self) -> None:
-        """Clear all created tools."""
-    @abstractmethod
-    def get_resource_names(self) -> list[str]:
-        """Get names of all registered resources.
-
-        Returns:
-            List of resource names.
-        """

aip_agents/utils/langgraph/tool_managers/delegation_tool_manager.pyi

@@ -1,56 +0,0 @@
-from _typeshed import Incomplete
-from aip_agents.agent.base_agent import BaseAgent as BaseAgent
-from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError
-from aip_agents.types import A2AEvent as A2AEvent, A2AStreamEventType as A2AStreamEventType
-from aip_agents.utils.artifact_helpers import extract_artifacts_from_agent_response as extract_artifacts_from_agent_response
-from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
-from aip_agents.utils.logger import get_logger as get_logger
-from aip_agents.utils.metadata_helper import MetadataFieldKeys as MetadataFieldKeys, get_next_step_number as get_next_step_number
-from aip_agents.utils.pii.pii_helper import anonymize_final_response_content as anonymize_final_response_content, extract_pii_mapping_from_agent_response as extract_pii_mapping_from_agent_response
-from aip_agents.utils.reference_helper import extract_references_from_agent_response as extract_references_from_agent_response
-from aip_agents.utils.step_limit_manager import StepLimitManager as StepLimitManager
-from aip_agents.utils.token_usage_helper import STEP_USAGE_KEY as STEP_USAGE_KEY, TOTAL_USAGE_KEY as TOTAL_USAGE_KEY, USAGE_METADATA_KEY as USAGE_METADATA_KEY, extract_token_usage_from_agent_response as extract_token_usage_from_agent_response
-from langchain_core.tools import BaseTool
-
-logger: Incomplete
-OUTPUT_KEY: str
-RESULT_KEY: str
-ARTIFACTS_KEY: str
-METADATA_KEY: str
-METADATA_INTERNAL_PREFIXES: Incomplete
-METADATA_INTERNAL_KEYS: Incomplete
-AGENT_RUN_A2A_STREAMING_METHOD: str
-
-class DelegationToolManager(BaseLangGraphToolManager):
-    """Manages internal agent delegation tools for LangGraph agents.
-
-    This tool manager converts internal agent instances into LangChain tools
-    that can be used for task delegation within a unified ToolNode. Each
-    delegated agent becomes a tool that the coordinator can call.
-
-    Simplified version following legacy BaseLangChainAgent patterns.
-    """
-    registered_agents: list[BaseAgent]
-    parent_agent: Incomplete
-    def __init__(self, parent_agent: BaseAgent | None = None) -> None:
-        """Initialize the delegation tool manager.
-
-        Args:
-            parent_agent: The parent agent that creates delegation tools, used for parent step lookup.
-        """
-    created_tools: Incomplete
-    def register_resources(self, agents: list[BaseAgent]) -> list[BaseTool]:
-        """Register internal agents for delegation and convert them to tools.
-
-        Args:
-            agents: List of BaseAgent instances for internal task delegation.
-
-        Returns:
-            List of created delegation tools.
-        """
-    def get_resource_names(self) -> list[str]:
-        """Get names of all registered delegation agents.
-
-        Returns:
-            list[str]: A list of names of all registered delegation agents.
-        """