aip-agents-binary 0.4.8__cp312-cp312-win_amd64.whl → 0.5.4__cp312-cp312-win_amd64.whl

aip_agents/utils/sse_chunk_transformer.pyi

@@ -0,0 +1,166 @@
+from _typeshed import Incomplete
+from aip_agents.schema.a2a import A2AEvent
+from collections.abc import AsyncGenerator
+from enum import StrEnum
+from typing import Any
+
+__all__ = ['SSEChunkTransformer', 'TaskState', 'ChunkStatus', 'ChunkReason', 'ChunkFieldKeys']
+
+class TaskState(StrEnum):
+    """Task state values for SSE chunks."""
+    WORKING: str
+    COMPLETED: str
+    FAILED: str
+
+class ChunkStatus(StrEnum):
+    """Status values for SSE chunks."""
+    SUCCESS: str
+    ERROR: str
+
+class ChunkReason(StrEnum):
+    """Reason codes for special chunk states."""
+    EMPTY_PAYLOAD: str
+
+class ChunkFieldKeys(StrEnum):
+    """Field name constants for SSE chunk structure."""
+    STATUS: str
+    TASK_STATE: str
+    CONTENT: str
+    EVENT_TYPE: str
+    FINAL: str
+    METADATA: str
+    TIMESTAMP: str
+    TASK_ID: str
+    CONTEXT_ID: str
+    ARTIFACTS: str
+    REASON: str
+
+class SSEChunkTransformer:
+    '''Transforms A2AEvent stream to SSE-compatible output.
+
+    This class converts events from arun_a2a_stream into the normalized dict format
+    matching A2AConnector.astream_to_agent output.
+
+    Lifecycle:
+        Single-stream instance. Must NOT be reused across concurrent streams.
+        Each arun_sse_stream call creates a fresh instance.
+
+    Attributes:
+        task_id: Optional task identifier for the stream.
+        context_id: Optional context identifier for the stream.
+
+    Example:
+        >>> transformer = SSEChunkTransformer(task_id="task-123")
+        >>> async for chunk in transformer.transform_stream(agent.arun_a2a_stream("query")):
+        ...     print(chunk)
+    '''
+    task_id: Incomplete
+    context_id: Incomplete
+    def __init__(self, task_id: str | None = None, context_id: str | None = None, pii_mapping: dict[str, str] | None = None) -> None:
+        """Initialize the transformer with optional task and context IDs.
+
+        Args:
+            task_id: Optional task identifier for the stream.
+            context_id: Optional context identifier for the stream.
+            pii_mapping: Optional PII mapping to inject into each chunk's metadata.
+        """
+    @staticmethod
+    def normalize_metadata_enums(data: Any) -> Any:
+        """Recursively convert enum keys/values to their string values.
+
+        This is a pure normalization utility that converts any enum instances
+        (MetadataFieldKeys, Kind, Status, etc.) to their .value strings.
+
+        Args:
+            data: Dict, list, or value that may contain enum keys/values.
+
+        Returns:
+            Normalized data with all enums converted to their .value strings.
+        """
+    @staticmethod
+    def normalize_event_type_value(event_type: Any) -> str | None:
+        """Convert A2AStreamEventType enum to string.
+
+        Args:
+            event_type: Event type (enum, string, or None).
+
+        Returns:
+            String value of the event type, or None if invalid.
+        """
+    @staticmethod
+    def create_artifact_hash(artifact: dict[str, Any]) -> str:
+        """Create a stable hash for artifact deduplication.
+
+        Uses name, content_type, mime_type, and file_data for hashing,
+        excluding artifact_id which may be randomly generated.
+
+        Args:
+            artifact: Artifact dict with name, content_type, mime_type, and optionally file_data.
+
+        Returns:
+            SHA256 hexdigest hash string for deduplication.
+        """
+    @staticmethod
+    def extract_tool_outputs(tool_calls: list[dict[str, Any]]) -> list[str]:
+        """Extract human-readable output strings from tool calls.
+
+        Args:
+            tool_calls: List of tool call dictionaries.
+
+        Returns:
+            List of human-readable output strings.
+        """
+    @staticmethod
+    def format_tool_output(output: Any, tool_name: str) -> str:
+        """Format a single tool output for display.
+
+        Args:
+            output: The tool output to format.
+            tool_name: The name of the tool.
+
+        Returns:
+            The formatted output string.
+        """
+    @staticmethod
+    def apply_hitl_content_override(content: str | None, event_type_str: str, metadata: dict[str, Any]) -> str | None:
+        """Apply HITL content override when HITL is active and tool results are available.
+
+        This method overrides the content with human-readable tool output when HITL
+        is active, matching A2AConnector behavior.
+
+        Args:
+            content: The original content/status message.
+            event_type_str: The type of event being processed (normalized string).
+            metadata: The metadata dictionary containing tool_info and hitl flag.
+
+        Returns:
+            The original content or human-readable tool output if HITL is active.
+        """
+    def transform_event(self, event: A2AEvent) -> dict[str, Any]:
+        """Transform a single A2AEvent to SSE chunk format.
+
+        Converts the A2AEvent structure to the normalized SSE chunk format,
+        relocating fields like tool_info and thinking_and_activity_info into
+        metadata, and normalizing enum values to strings.
+
+        Args:
+            event: Single A2AEvent dict from arun_a2a_stream.
+
+        Returns:
+            SSEChunk dict with normalized structure.
+        """
+    async def transform_stream(self, stream: AsyncGenerator[A2AEvent, None]) -> AsyncGenerator[dict[str, Any], None]:
+        """Transform A2AEvent stream to SSE-compatible chunks.
+
+        Wraps the input stream and transforms each event, handling artifact
+        deduplication and time tracking across the stream.
+
+        Args:
+            stream: Async generator yielding A2AEvent dicts.
+
+        Yields:
+            SSEChunk dicts with normalized structure.
+
+        Raises:
+            Exceptions from underlying stream propagate to caller.
+        """

aip_agents/utils/step_limit_manager.pyi

@@ -0,0 +1,112 @@
+from _typeshed import Incomplete
+from aip_agents.schema.step_limit import MaxDelegationDepthExceededError as MaxDelegationDepthExceededError, MaxStepsExceededError as MaxStepsExceededError, StepLimitConfig as StepLimitConfig, StepLimitErrorResponse as StepLimitErrorResponse, StepLimitErrorType as StepLimitErrorType
+from dataclasses import dataclass, field
+from typing import Any
+
+@dataclass
+class StepExecutionContext:
+    """Runtime context for tracking step execution and delegation depth.
+
+    Attributes:
+        current_step: Current step number (0-indexed).
+        delegation_depth: Current depth in delegation chain (0 for root agent).
+        remaining_step_budget: Steps remaining before limit is hit.
+        delegation_chain: List of agent names in the delegation chain.
+    """
+    current_step: int = ...
+    delegation_depth: int = ...
+    remaining_step_budget: int | None = ...
+    delegation_chain: list[str] = field(default_factory=list)
+
+class StepLimitManager:
+    """Manages step and delegation limit enforcement during agent execution.
+
+    This manager integrates with LangGraph's existing step mechanisms and adds
+    delegation depth tracking and budget propagation.
+
+    Attributes:
+        config: Step limit configuration.
+        context: Current execution context.
+    """
+    config: Incomplete
+    context: Incomplete
+    def __init__(self, config: StepLimitConfig | None = None, initial_delegation_depth: int = 0, parent_step_budget: int | None = None) -> None:
+        """Initialize step limit manager.
+
+        Args:
+            config: Optional step limit configuration. Uses defaults if None.
+            initial_delegation_depth: Starting delegation depth (from parent).
+            parent_step_budget: Remaining step budget inherited from parent agent.
+        """
+    def check_step_limit(self, agent_name: str = 'agent', count: int = 1) -> None:
+        """Check if taking 'count' steps would exceed limit.
+
+        Args:
+            agent_name: Name of the agent to identify in error message.
+            count: Number of steps to check (useful for parallel tool batches).
+
+        Raises:
+            MaxStepsExceededError: If max_steps limit is exceeded.
+        """
+    def check_delegation_depth(self, target_agent_name: str) -> None:
+        """Check if delegation to target agent would exceed depth limit.
+
+        Args:
+            target_agent_name: Name of the agent to delegate to.
+
+        Raises:
+            MaxDelegationDepthExceededError: If delegation depth limit exceeded.
+        """
+    def increment_step(self, count: int = 1) -> None:
+        """Increment step counter and update remaining budget.
+
+        Args:
+            count: Number of steps to consume (defaults to 1).
+        """
+    def get_child_budget(self, child_max_steps: int | None = None) -> int:
+        """Calculate step budget to allocate to child agent.
+
+        Algorithm:
+        1. If remaining_step_budget is None (root with no limit), use config.max_steps - 1
+        2. If remaining_step_budget <= 1, return 0 (no budget left for child)
+        3. Calculate child_budget = remaining_step_budget - 1 (reserve 1 for parent)
+        4. If child has own max_steps config, return min(child_budget, child.max_steps)
+        5. Otherwise return child_budget
+
+        Args:
+            child_max_steps: Optional child agent's own max_steps limit.
+
+        Returns:
+            Step budget for child agent, accounting for parent's continuation.
+            Returns 0 if no budget available for child.
+
+        Edge Cases:
+            - remaining=1: Returns 0 (parent needs the last step)
+            - remaining=None: Uses config.max_steps - 1
+            - child has own limit: Returns min(calculated_budget, child_limit)
+        """
+    def add_to_delegation_chain(self, agent_name: str) -> None:
+        """Add agent to delegation chain for tracking.
+
+        Args:
+            agent_name: Name of the agent being delegated to.
+        """
+    @classmethod
+    def from_state(cls, state: dict[str, Any], config: StepLimitConfig | None = None) -> StepLimitManager:
+        """Create manager from LangGraph state.
+
+        Args:
+            state: LangGraph agent state containing remaining_steps, etc.
+            config: Optional step limit configuration.
+
+        Returns:
+            Initialized step limit manager.
+        """
+    def set_context(self) -> None:
+        """Set context variables for downstream consumption (e.g. by delegation tools)."""
+    def to_state_update(self) -> dict[str, Any]:
+        """Convert current context to LangGraph state update.
+
+        Returns:
+            Dictionary of state fields to update.
+        """

aip_agents/utils/token_usage_helper.pyi

@@ -1,4 +1,4 @@
-from langchain_core.messages.ai import AIMessage as AIMessage, UsageMetadata as UsageMetadata
+from langchain_core.messages.ai import AIMessage, UsageMetadata
 from langchain_core.messages.tool import ToolMessage as ToolMessage
 from langgraph.types import Command
 from typing import Any

aip_agents.pyi

@@ -1,6 +1,19 @@
 # This file was generated by Nuitka
 
 # Stubs included by default
+from __future__ import annotations
+from __future__ import annotations
+from typing import Any
+import importlib
+import sys
+
+__all__: list[str] = []
+def _export(module_name: str) -> None:
+    ...
+
+__version__ = '0.0.0'
+def __getattr__(name: str) -> Any:
+    ...
 
 
 __name__ = ...
@@ -9,13 +22,18 @@ __name__ = ...
 
 # Modules used internally, to allow implicit dependencies to be seen:
 import os
+import __future__
+import importlib
+import sys
+import typing
 import asyncio
 import time
 import uuid
 import abc
+import collections
+import collections.abc
 import dataclasses
 import datetime
-import typing
 import a2a
 import a2a.server
 import a2a.server.agent_execution
@@ -28,7 +46,6 @@ import a2a.utils.artifact
 import aip_agents.types.A2AEvent
 import aip_agents.types.A2AStreamEventType
 import aip_agents.utils.serialize_references_for_metadata
-import aip_agents.agent.BaseLangGraphAgent
 import base64
 import enum
 import pydantic
@@ -44,7 +61,6 @@ import gllm_inference
 import gllm_inference.builder
 import gllm_inference.lm_invoker
 import gllm_inference.lm_invoker.lm_invoker
-import gllm_inference.schema
 import langchain_core
 import langchain_core.language_models
 import starlette
@@ -52,9 +68,15 @@ import starlette.applications
 import copy
 import hashlib
 import json
+import concurrent
+import concurrent.futures
+import concurrent.futures.Future
+import contextlib
 import contextvars
+import aiostream
 import gllm_core.event
 import gllm_core.event.handler
+import gllm_core.schema
 import langchain_core.messages
 import langchain_core.tools
 import langgraph
@@ -63,12 +85,12 @@ import langgraph.graph.message
 import langgraph.graph.state
 import langgraph.types
 import typing_extensions
-import aip_agents.mcp.client.langchain.LangchainMCPClient
+import aip_agents.mcp.client.LangchainMCPClient
 import aip_agents.memory.BaseMemory
 import aip_agents.memory.MemoryFactory
 import aip_agents.memory.MemoryMethod
 import aip_agents.utils.validate_references
-import contextlib
+import aip_agents.utils.pii.deanonymize_final_response_content
 import google
 import google.adk
 import google.adk.agents
@@ -84,37 +106,37 @@ import google.genai
 import google.genai.types
 import langchain
 import langchain.tools
-import aip_agents.mcp.client.GoogleADKMCPClient
-import collections
-import collections.abc
-import functools
+import aip_agents.agent.hitl.prompt.BasePromptHandler
+import aip_agents.agent.hitl.prompt.DeferredPromptHandler
+import langgraph.config
+import aip_agents.utils.datetime.ensure_utc_datetime
+import aip_agents.clients.langflow.LangflowApiClient
 import textwrap
+import functools
 import deprecated
-import gllm_core.schema
 import langchain_core.messages.ai
-import langgraph.config
 import langgraph.managed
 import aip_agents.utils.add_references_chunks
 import aip_agents.utils.langgraph.convert_langchain_messages_to_gllm_messages
 import aip_agents.utils.langgraph.convert_lm_output_to_langchain_message
+import aip_agents.utils.pii.ToolPIIHandler
+import aip_agents.utils.pii.add_pii_mappings
+import aip_agents.utils.datetime.get_timezone_aware_now
 import _frozen_importlib_external
+import langchain_openai
+import aip_agents.agent.LangGraphAgent
 import click
 import uvicorn
-import langchain_openai
+import dotenv
 import aip_agents.agent.LangChainAgent
 import pprint
 import aip_agents.examples.tools.google_serper_tool
-import aip_agents.agent.LangGraphAgent
 import aip_agents.examples.tools.weather_tool_langchain
-import dotenv
-import sys
 import traceback
-import argparse
 import aip_agents.agent.LangGraphReactAgent
-import aip_agents.agent.langgraph_agent
+import logging
 import aip_agents.tools.BOSA_AUTOMATED_TOOLS
 import nest_asyncio
-import logging
 import io
 import subprocess
 import threading
@@ -122,14 +144,20 @@ import fastapi
 import fastapi.responses
 import fastapi.staticfiles
 import aip_agents.sentry.setup_telemetry
+import http
+import http.HTTPStatus
+import starlette.requests
+import starlette.responses
+import starlette.routing
+import random
 import mcp
 import mcp.server
 import mcp.server.fastmcp
-import random
 import PIL
 import langchain_core.runnables
 import csv
 import gllm_core.constants
+import gllm_inference.schema
 import langchain.agents
 import langchain.agents.tools
 import langchain_core.agents
@@ -140,16 +168,21 @@ import gllm_tools.mcp.client
 import gllm_tools.mcp.client.client
 import gllm_tools.mcp.client.config
 import gllm_tools.mcp.client.resource
-import gllm_tools.mcp.client.session
-import gllm_tools.mcp.client.tool
 import mcp.types
-import gllm_tools.mcp.client.langchain
-import gllm_tools.mcp.client.langchain.client
-import aip_agents.types.ChatMessage
-import importlib
-import mem0
-import mem0.configs
 import inspect
+import gllm_tools.mcp.client.tool
+import langchain_core.documents
+import langchain_core.documents.base
+import mcp.client
+import mcp.client.sse
+import mcp.client.stdio
+import mcp.client.streamable_http
+import concurrent.futures.ThreadPoolExecutor
+import gllm_inference.schema.message
+import gllm_memory
+import gllm_memory.enums
+import aip_agents.types.ChatMessage
+import aip_agents.utils.datetime.format_created_updated_label
 import bosa_core
 import bosa_core.telemetry
 import bosa_core.telemetry.opentelemetry
@@ -162,13 +195,38 @@ import urllib3
 import urllib3.exceptions
 import pickle
 import bosa_connectors
-import bosa_connectors.connector
-import concurrent
-import concurrent.futures
+import aip_agents.utils.datetime.is_valid_date_string
+import aip_agents.utils.datetime.next_day_iso
+import aip_agents.tools.memory_search.MEMORY_SEARCH_TOOL_NAME
+import aip_agents.tools.memory_search.LongTermMemorySearchInput
+import aip_agents.tools.memory_search.LongTermMemorySearchTool
+import aip_agents.tools.memory_search.Mem0SearchInput
+import aip_agents.tools.memory_search.Mem0SearchTool
+import aip_agents.tools.memory_search.MemoryConfig
 import a2a.client
+import zoneinfo
+import zoneinfo.ZoneInfo
+import zoneinfo.ZoneInfoNotFoundError
 import langchain_core.messages.tool
 import re
-import colorama
-import bosa_core.logger
-import bosa_core.logger.regex_pii_logger_handler
-import aip_agents.utils.name_preprocessor.BaseNamePreprocessor
+import re.Pattern
+import gllm_core.utils.logger_manager
+import aip_agents.utils.metadata.schemas.Activity
+import aip_agents.utils.metadata.schemas.ActivityDataType
+import aip_agents.utils.metadata.schemas.Thinking
+import aip_agents.utils.metadata.activity_narrative.DELEGATE_PREFIX
+import aip_agents.utils.metadata.activity_narrative.HITL_DECISION_MESSAGES
+import aip_agents.utils.metadata.activity_narrative.HITL_PENDING_DESCRIPTION
+import aip_agents.utils.metadata.activity_narrative.HITL_PENDING_TITLE
+import aip_agents.utils.metadata.activity_narrative.ActivityNarrativeBuilder
+import aip_agents.utils.metadata.activity_narrative._format_tool_or_subagent_name
+import aip_agents.utils.metadata.create_tool_activity_info
+import aip_agents.utils.name_preprocessor.BaseNamePreprocessor
+import gllm_privacy
+import gllm_privacy.pii_detector
+import gllm_privacy.pii_detector.anonymizer
+import gllm_privacy.pii_detector.constants
+import gllm_privacy.pii_detector.recognizer
+import gllm_privacy.pii_detector.recognizer.gdplabs_ner_api_remote_recognizer
+import gllm_privacy.pii_detector.utils
+import gllm_privacy.pii_detector.utils.deanonymizer_mapping