aip-agents-binary 0.5.17__py3-none-any.whl → 0.5.19__py3-none-any.whl

aip_agents/utils/metadata/activity_narrative/builder.pyi

@@ -0,0 +1,35 @@
+from _typeshed import Incomplete
+from aip_agents.schema.hitl import ApprovalDecisionType as ApprovalDecisionType, HitlMetadata as HitlMetadata
+from aip_agents.utils.formatter_llm_client import FormatterInvocationError as FormatterInvocationError, FormatterInvokerUnavailableError as FormatterInvokerUnavailableError, get_formatter_llm_client as get_formatter_llm_client
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata.activity_narrative.constants import DELEGATE_PREFIX as DELEGATE_PREFIX, HITL_DECISION_MESSAGES as HITL_DECISION_MESSAGES, HITL_PENDING_DESCRIPTION as HITL_PENDING_DESCRIPTION, HITL_PENDING_TITLE as HITL_PENDING_TITLE, OUTPUT_EXCERPT_MAX_CHARS as OUTPUT_EXCERPT_MAX_CHARS, SYSTEM_PROMPT as SYSTEM_PROMPT
+from aip_agents.utils.metadata.activity_narrative.context import ActivityContext as ActivityContext, ActivityPhase as ActivityPhase
+from aip_agents.utils.metadata.activity_narrative.formatters import ArgsFormatter as ArgsFormatter, OutputFormatter as OutputFormatter, SensitiveInfoFilter as SensitiveInfoFilter
+from typing import Any
+
+logger: Incomplete
+
+class ActivityNarrativeBuilder:
+    """Generate structured activity payloads via formatter LLM.
+
+    High-level flow:
+    1. Gather raw metadata about a tool/delegate event and normalize it into an ``ActivityContext``.
+    2. Sanitize arguments and outputs so no sensitive values reach downstream renderers or the formatter model.
+    3. Prompt the shared formatter with phase-specific instructions (e.g., describe intent on start, summarize results on end).
+    4. If the formatter responds with usable heading/body text, surface it; otherwise fall back to deterministic templates
+       built from the sanitized context.
+
+    This approach keeps SSE activity cards readable when the formatter is healthy while still providing sensible copy when
+    the formatter is unavailable or returns low-quality text.
+    """
+    def __init__(self) -> None:
+        """Initialize the activity narrative builder."""
+    def build_payload(self, metadata: dict[str, Any] | None) -> dict[str, Any] | None:
+        """Build enriched payload for the provided metadata.
+
+        Args:
+            metadata: The metadata dictionary containing tool_info, hitl, and other context.
+
+        Returns:
+            Dictionary payload with a rendered message, or None when not available.
+        """

aip_agents/utils/metadata/activity_narrative/constants.pyi

@@ -0,0 +1,10 @@
+from aip_agents.schema.hitl import ApprovalDecisionType
+
+__all__ = ['SYSTEM_PROMPT', 'DELEGATE_PREFIX', 'OUTPUT_EXCERPT_MAX_CHARS', 'HITL_PENDING_TITLE', 'HITL_PENDING_DESCRIPTION', 'HITL_DECISION_MESSAGES']
+
+SYSTEM_PROMPT: str
+DELEGATE_PREFIX: str
+OUTPUT_EXCERPT_MAX_CHARS: int
+HITL_PENDING_TITLE: str
+HITL_PENDING_DESCRIPTION: str
+HITL_DECISION_MESSAGES: dict[ApprovalDecisionType, tuple[str, str]]

aip_agents/utils/metadata/activity_narrative/context.pyi

@@ -0,0 +1,32 @@
+from aip_agents.schema.hitl import ApprovalDecisionType, HitlMetadata
+from dataclasses import dataclass
+from enum import StrEnum
+
+__all__ = ['ActivityContext', 'ActivityPhase']
+
+class ActivityPhase(StrEnum):
+    """Lifecycle phases for tool, delegate, and HITL events."""
+    TOOL_START: str
+    TOOL_END: str
+    DELEGATE_START: str
+    DELEGATE_END: str
+    HITL_PENDING: str
+    HITL_RESOLVED: str
+JSONScalar = str | int | float | bool | None
+
+@dataclass
+class ActivityContext:
+    """Structured representation of an activity event."""
+    phase: ActivityPhase
+    agent_name: str | None
+    subject_name: str | None
+    sanitized_args: dict[str, JSONValue] | None
+    sanitized_output: JSONValue | None
+    arguments_excerpt: str | None
+    output_excerpt: str | None
+    error_excerpt: str | None
+    step_id: str | None = ...
+    is_delegate: bool = ...
+    hitl_metadata: HitlMetadata | None = ...
+    hitl_decision: ApprovalDecisionType | None = ...
+    default_heading: str | None = ...

aip_agents/utils/metadata/activity_narrative/formatters.pyi

@@ -0,0 +1,48 @@
+from _typeshed import Incomplete
+from collections.abc import Callable
+
+__all__ = ['ArgsFormatter', 'OutputFormatter', 'SensitiveInfoFilter']
+
+JSONScalar = str | int | float | bool | None
+
+class SensitiveInfoFilter:
+    """Redact sensitive argument/output values before rendering or sending to LLMs."""
+    REDACTED: str
+    SENSITIVE_KEY_PATTERNS: Incomplete
+    def __init__(self) -> None:
+        """Initialize the sensitive info filter."""
+    def sanitize(self, args: dict[str, JSONValue] | None, output: JSONValue | None, tool_sanitizer: Callable[[dict[str, JSONValue] | None, JSONValue | None], dict[str, JSONValue]] | None = None) -> tuple[dict[str, JSONValue] | None, JSONValue | None]:
+        """Return sanitized arguments/output with optional tool overrides.
+
+        Args:
+            args: Raw arguments dictionary emitted by the tool.
+            output: Raw tool output which may be nested JSON.
+            tool_sanitizer: Optional callable that can override sanitized values.
+
+        Returns:
+            tuple: Sanitized args and output payloads.
+        """
+
+class ArgsFormatter:
+    """Simple formatter that surfaces at most two argument key/value pairs."""
+    def format(self, args: dict[str, JSONValue] | None) -> str | None:
+        """Format tool arguments into a short excerpt.
+
+        Args:
+            args: Tool arguments dictionary.
+
+        Returns:
+            str | None: Concise representation of up to two key/value pairs.
+        """
+
+class OutputFormatter:
+    """Lightweight formatter that truncates serialized output."""
+    def format(self, output: JSONValue | None) -> str | None:
+        """Format tool output into a readable excerpt.
+
+        Args:
+            output: Raw tool output.
+
+        Returns:
+            str | None: Truncated representation suitable for logs.
+        """

aip_agents/utils/metadata/activity_narrative/utils.pyi

@@ -0,0 +1,12 @@
+__all__ = ['_format_tool_or_subagent_name']
+
+def _format_tool_or_subagent_name(name: str, remove_delegate_prefix: bool = False) -> str:
+    """Format tool/agent names to 'Camel Case' consistently.
+
+    Args:
+        name: Raw tool or sub-agent identifier.
+        remove_delegate_prefix: Whether to strip the ``delegate::`` prefix before formatting.
+
+    Returns:
+        str: Display-friendly tool or agent name.
+    """

aip_agents/utils/metadata/schemas/__init__.pyi

@@ -0,0 +1,4 @@
+from aip_agents.utils.metadata.schemas.activity_schema import Activity as Activity, ActivityDataType as ActivityDataType
+from aip_agents.utils.metadata.schemas.thinking_schema import Thinking as Thinking
+
+__all__ = ['Activity', 'ActivityDataType', 'Thinking']

aip_agents/utils/metadata/schemas/activity_schema.pyi

@@ -0,0 +1,18 @@
+from enum import StrEnum
+from pydantic import BaseModel
+
+class ActivityDataType(StrEnum):
+    """Enumeration of activity data types."""
+    ACTIVITY: str
+
+class Activity(BaseModel):
+    '''Schema for activity info payload.
+
+    Fields:
+    - data_type: always "activity"
+    - id: UUID string identifying this activity event
+    - data_value: JSON string with additional info (e.g., {"message": "..."})
+    '''
+    data_type: ActivityDataType
+    id: str
+    data_value: str

aip_agents/utils/metadata/schemas/thinking_schema.pyi

@@ -0,0 +1,20 @@
+from enum import StrEnum
+from pydantic import BaseModel
+
+class ThinkingDataType(StrEnum):
+    """Enum for thinking data types."""
+    THINKING: str
+    THINKING_START: str
+    THINKING_END: str
+
+class Thinking(BaseModel):
+    '''Schema for thinking info payload.
+
+    Fields:
+    - data_type: type of thinking event
+    - id: UUID string identifying this thinking event
+    - data_value: JSON string with additional info (e.g., {"message": "..."})
+    '''
+    data_type: ThinkingDataType
+    id: str
+    data_value: str

aip_agents/utils/metadata/thinking_metadata_helper.pyi

@@ -0,0 +1,4 @@
+from _typeshed import Incomplete
+from aip_agents.utils.metadata.schemas.thinking_schema import Thinking as Thinking, ThinkingDataType as ThinkingDataType
+
+FINAL_THINKING_INFO: Incomplete

aip_agents/utils/metadata_helper.pyi

@@ -0,0 +1,117 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.metadata import create_tool_activity_info as create_tool_activity_info
+from aip_agents.utils.token_usage_helper import STEP_USAGE_KEY as STEP_USAGE_KEY, TOTAL_USAGE_KEY as TOTAL_USAGE_KEY
+from enum import StrEnum
+from typing import Any
+
+logger: Incomplete
+
+def start_step_counter_scope(start: int = 1) -> None:
+    """Begin a step counter scope, resetting only when entering the outermost scope.
+
+    Args:
+        start: Starting step number for the counter. Defaults to 1.
+    """
+def end_step_counter_scope() -> None:
+    """Exit a step counter scope, maintaining parent scope counters.
+
+    Decrements the depth counter while preserving the step count for parent scopes.
+    """
+def get_next_step_number() -> int:
+    """Return the next step number within the active scope.
+
+    Returns:
+        int: The next sequential step number in the current scope.
+    """
+
+class DefaultStepMessages(StrEnum):
+    """Constants for default step indicator messages."""
+    EN: str
+    ID: str
+
+class Kind(StrEnum):
+    """Constants for metadata kind values."""
+    AGENT_STEP: str
+    AGENT_THINKING_STEP: str
+    FINAL_RESPONSE: str
+    FINAL_THINKING_STEP: str
+    AGENT_DEFAULT: str
+    TOKEN: str
+
+class Status(StrEnum):
+    """Constants for metadata status values."""
+    RUNNING: str
+    FINISHED: str
+    STOPPED: str
+
+class MetadataFieldKeys(StrEnum):
+    """Enumeration of standard metadata field keys used in A2A events."""
+    KIND: str
+    STATUS: str
+    TIME: str
+    MESSAGE: str
+    TOOL_INFO: str
+    REFERENCES: str
+    THINKING_AND_ACTIVITY_INFO: str
+    HITL: str
+    STEP_USAGE = STEP_USAGE_KEY
+    TOTAL_USAGE = TOTAL_USAGE_KEY
+    TOKEN_STREAMING: str
+    PII_MAPPING: str
+
+class MetadataTimeTracker:
+    """Tracks cumulative execution time across agent steps for final response metadata.
+
+    This class provides a clean way to accumulate execution times from individual
+    agent steps and apply the total time to final response metadata.
+
+    Attributes:
+        FLOAT_EPSILON: Epsilon value for floating point comparisons to avoid precision issues.
+    """
+    FLOAT_EPSILON: float
+    def __init__(self) -> None:
+        """Initialize the time tracker with zero accumulated time."""
+    def update_response_metadata(self, response: dict[str, Any]) -> dict[str, Any]:
+        """Update response metadata with accumulated time tracking.
+
+        Args:
+            response: Response dictionary containing metadata to update.
+
+        Returns:
+            dict[str, Any]: Response with updated metadata for final responses. If any error occurs,
+                returns the original response unchanged.
+        """
+
+def create_metadata(content: str = '', status: Status = ..., is_final: bool = False, existing_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Create metadata for A2A responses with content-based message.
+
+    Args:
+        content: The content to create metadata for.
+        status: The status of the content.
+        is_final: Whether the content is final.
+        existing_metadata: Optional existing metadata to merge with. Existing metadata
+            takes precedence over generated metadata for conflicting keys.
+
+    Returns:
+        dict[str, Any]: The metadata for the content, merged with existing metadata if provided.
+    """
+def create_tool_processing_metadata(original_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Create metadata for tool processing events (tool_call and tool_result).
+
+    Args:
+        original_metadata: Optional original metadata to merge with.
+
+    Returns:
+        dict[str, Any]: Metadata dictionary with agent_thinking_step kind and no message/time/status.
+    """
+def create_status_update_metadata(content: str, custom_metadata: dict[str, Any] | None = None) -> dict[str, Any]:
+    """Create metadata for status update events with content-based rules.
+
+    Args:
+        content: The content of the status update.
+        custom_metadata: Optional custom metadata to merge with.
+
+    Returns:
+        dict[str, Any]: Metadata dictionary following the specific rules for different content types.
+    """

aip_agents/utils/name_preprocessor/__init__.pyi

@@ -0,0 +1,6 @@
+from aip_agents.utils.name_preprocessor.base_name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
+from aip_agents.utils.name_preprocessor.google_name_preprocessor import GoogleNamePreprocessor as GoogleNamePreprocessor
+from aip_agents.utils.name_preprocessor.name_preprocessor import NamePreprocessor as NamePreprocessor
+from aip_agents.utils.name_preprocessor.openai_name_preprocessor import OpenAINamePreprocessor as OpenAINamePreprocessor
+
+__all__ = ['GoogleNamePreprocessor', 'OpenAINamePreprocessor', 'BaseNamePreprocessor', 'NamePreprocessor']

aip_agents/utils/name_preprocessor/base_name_preprocessor.pyi

@@ -0,0 +1,52 @@
+from abc import ABC, abstractmethod
+
+class BaseNamePreprocessor(ABC):
+    """Base class for name preprocessing.
+
+    It contains the common methods for name preprocessing.
+    """
+    def regex_substitute(self, name: str, regex: str, replacement: str) -> str:
+        """Substitute a regex pattern in a name.
+
+        Args:
+            name: The input name to preprocess.
+            regex: The regex pattern to substitute.
+            replacement: The replacement string.
+
+        Returns:
+            A name that is valid for the name processor.
+        """
+    def clean_up_name(self, name: str) -> str:
+        """Process a processed name.
+
+        Step:
+            1. collapse multiple underscores to single underscore
+            2. remove trailing underscores
+            3. if name is empty after clean up, add a single underscore
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that starts with a letter or an underscore.
+        """
+    @abstractmethod
+    def sanitize_agent_name(self, name: str) -> str:
+        """Process a name according to the rules of the name processor.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for the name processor.
+        """
+    @abstractmethod
+    def sanitize_tool_name(self, name: str) -> str:
+        """Process a name according to the rules of the name processor.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for the name processor.
+        """

aip_agents/utils/name_preprocessor/google_name_preprocessor.pyi

@@ -0,0 +1,38 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
+
+logger: Incomplete
+
+class GoogleNamePreprocessor(BaseNamePreprocessor):
+    """Concrete implementation of NamePreprocessor according to Google's name requirements."""
+    NAME_SETTINGS: Incomplete
+    CUT_OFF_INDEX: int
+    def sanitize_agent_name(self, name: str) -> str:
+        """Preprocess an input name according to Google's name requirements for agents.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for Google.
+
+        Notes:
+            Name should start with a letter (a-z, A-Z) or an underscore (_),
+            and can only contain letters, digits (0-9), and underscores.
+            It has no length limit. ( based on experiment )
+        """
+    def sanitize_tool_name(self, name: str) -> str:
+        """Preprocess an input name according to Google's name requirements for tools.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for Google.
+
+        Notes:
+            Name should start with a letter (a-z, A-Z) or an underscore (_),
+            and can only contain letters, digits (0-9), underscores, and dashes.
+            It has a length limit of 64 characters, but google throws error if the length is exactly 64, so cut to 63.
+        """

aip_agents/utils/name_preprocessor/name_preprocessor.pyi

@@ -0,0 +1,41 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.name_preprocessor.base_name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
+from aip_agents.utils.name_preprocessor.google_name_preprocessor import GoogleNamePreprocessor as GoogleNamePreprocessor
+from aip_agents.utils.name_preprocessor.openai_name_preprocessor import OpenAINamePreprocessor as OpenAINamePreprocessor
+
+logger: Incomplete
+
+class NamePreprocessor:
+    """Name Preprocessor for Google ADK and OpenAI compatible models.
+
+    Args:
+        provider: The provider of the model.
+    """
+    PROVIDER_TO_NAME_PREPROCESSOR_MAP: Incomplete
+    provider: Incomplete
+    preprocessor: Incomplete
+    def __init__(self, provider: str) -> None:
+        """Initialize the name preprocessor.
+
+        Args:
+            provider: The provider of the model.
+        """
+    def sanitize_agent_name(self, name: str) -> str:
+        """Preprocess an input name according to the rules of the name processor.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for the name processor.
+        """
+    def sanitize_tool_name(self, name: str) -> str:
+        """Preprocess an input name according to the rules of the name processor.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for the name processor.
+        """

aip_agents/utils/name_preprocessor/openai_name_preprocessor.pyi

@@ -0,0 +1,34 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from aip_agents.utils.name_preprocessor import BaseNamePreprocessor as BaseNamePreprocessor
+
+logger: Incomplete
+
+class OpenAINamePreprocessor(BaseNamePreprocessor):
+    """Concrete implementation of NamePreprocessor according to OpenAI's name requirements."""
+    CUT_OFF_INDEX: int
+    def sanitize_agent_name(self, name: str) -> str:
+        """Preprocess an input name according to OpenAI's name requirements for agents.
+
+        As of now, OpenAI only has rule for tool name, and it is the same as Google's tool name rule,
+        so just return the name as is.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for OpenAI.
+        """
+    def sanitize_tool_name(self, name: str) -> str:
+        """Preprocess an input name according to OpenAI's name requirements for tools.
+
+        Args:
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for OpenAI.
+
+        Notes:
+            Only contain letters (a-z, A-Z), digits (0-9), underscores (_), and dashes (-).
+            It has a length limit of 64 characters.
+        """

aip_agents/utils/pii/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.utils.pii.pii_handler import ToolPIIHandler as ToolPIIHandler
+from aip_agents.utils.pii.pii_helper import add_pii_mappings as add_pii_mappings, anonymize_final_response_content as anonymize_final_response_content, deanonymize_final_response_content as deanonymize_final_response_content, extract_pii_mapping_from_agent_response as extract_pii_mapping_from_agent_response, normalize_enable_pii as normalize_enable_pii
+from aip_agents.utils.pii.uuid_deanonymizer_mapping import UUIDDeanonymizerMapping as UUIDDeanonymizerMapping
+
+__all__ = ['ToolPIIHandler', 'add_pii_mappings', 'anonymize_final_response_content', 'deanonymize_final_response_content', 'extract_pii_mapping_from_agent_response', 'normalize_enable_pii', 'UUIDDeanonymizerMapping']

aip_agents/utils/pii/pii_handler.pyi

@@ -0,0 +1,96 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import LoggerManager as LoggerManager
+from aip_agents.utils.pii.uuid_deanonymizer_mapping import UUIDDeanonymizerMapping as UUIDDeanonymizerMapping
+from enum import Enum
+from gllm_privacy.pii_detector import TextAnalyzer, TextAnonymizer
+from typing import Any
+
+TextAnalyzer = Any
+TextAnonymizer = Any
+GDPLabsNerApiRemoteRecognizer = Any
+
+class _Operation(str, Enum):
+    ANONYMIZE: str
+    DEANONYMIZE: str
+
+logger: Incomplete
+NER_API_URL_ENV_VAR: str
+NER_API_KEY_ENV_VAR: str
+NER_API_TIMEOUT: int
+EXCLUDED_ENTITIES: Incomplete
+DEFAULT_SUPPORTED_ENTITIES: Incomplete
+
+class ToolPIIHandler:
+    """Handles PII masking/demasking for tool calling.
+
+    Tag replacement based on runner-provided mappings always works. Optional
+    NER-powered masking/de-masking is only enabled when NER_API_URL and
+    NER_API_KEY environment variables are set.
+
+    Attributes:
+        flat_pii_mapping: Flat mapping from runner service (tag → value)
+        text_analyzer: GLLM Privacy TextAnalyzer instance
+        text_anonymizer: GLLM Privacy TextAnonymizer instance
+        enable_ner: Whether NER is enabled
+    """
+    flat_pii_mapping: dict[str, str]
+    enable_ner: bool
+    text_analyzer: TextAnalyzer | None
+    text_anonymizer: TextAnonymizer | None
+    def __init__(self, pii_mapping: dict[str, str] | None = None, ner_api_url: str | None = None, ner_api_key: str | None = None) -> None:
+        """Initialize PII handler (private - use create_if_enabled() instead).
+
+        Initializes GLLM Privacy components (TextAnalyzer, TextAnonymizer) if NER credentials
+        are provided. Creates dual recognizers for Indonesian and English languages.
+        Pre-loads any existing PII mappings into the anonymizer's internal state.
+
+        Args:
+            pii_mapping: Existing PII mapping from runner service (flat format: tag -> value)
+            ner_api_url: NER API endpoint URL
+            ner_api_key: NER API authentication key
+        """
+    @classmethod
+    def create_if_enabled(cls, pii_mapping: dict[str, str] | None = None) -> ToolPIIHandler | None:
+        """Create ToolPIIHandler when mappings or NER configuration exist.
+
+        Args:
+            pii_mapping: Existing PII mapping from runner service
+
+        Returns:
+            ToolPIIHandler instance when mapping or NER config is available, None otherwise
+        """
+    @classmethod
+    def create_mapping_only(cls, pii_mapping: dict[str, str] | None = None) -> ToolPIIHandler | None:
+        """Create ToolPIIHandler in mapping-only mode (no NER).
+
+        Args:
+            pii_mapping: Existing PII mapping from runner service
+
+        Returns:
+            ToolPIIHandler instance when mapping exists, None otherwise
+        """
+    def deanonymize_tool_args(self, args: dict[str, Any]) -> dict[str, Any]:
+        """Replace PII tags in tool arguments with real values.
+
+        Recursively processes dictionaries, lists, and strings to replace all PII tags
+        (e.g., '<EMAIL_1>') with their corresponding real values from flat_pii_mapping.
+
+        Args:
+            args: Tool arguments that may contain PII tags
+
+        Returns:
+            Arguments with tags replaced by real values
+        """
+    def anonymize_tool_output(self, output: Any) -> tuple[Any, dict[str, str]]:
+        """Mask PII values in tool output.
+
+        Handles string and dictionary outputs. For strings, uses two-phase anonymization:
+        first masks known PII, then detects new PII via NER. For dictionaries, recursively
+        processes all string values. Returns updated mapping with any newly discovered PII.
+
+        Args:
+            output: Tool output that may contain PII values (string, dict, or other)
+
+        Returns:
+            Tuple of (anonymized_output, updated_flat_pii_mapping)
+        """

aip_agents/utils/pii/pii_helper.pyi

@@ -0,0 +1,78 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import LoggerManager as LoggerManager
+from typing import Any
+
+logger: Incomplete
+
+def normalize_enable_pii(enable_pii: Any) -> bool | None:
+    """Normalize enable_pii value from agent configuration.
+
+    Args:
+        enable_pii: Raw enable_pii value from agent configuration.
+
+    Returns:
+        The normalized enable_pii flag when explicitly set (True/False), otherwise None.
+    """
+def add_pii_mappings(left: dict[str, str] | None, right: dict[str, str] | None) -> dict[str, str]:
+    """Reducer function to merge PII mappings from multiple sources.
+
+    This is a LangGraph reducer function that merges PII mappings from:
+    - Parent agent's initial mapping
+    - Tool outputs with newly discovered PII
+    - Subagent responses with their discovered PII
+
+    Args:
+        left: Existing PII mapping (or None)
+        right: New PII mapping to merge (or None)
+
+    Returns:
+        Merged PII mapping dictionary
+
+    Note:
+        - Right (new) mappings take precedence over left (existing)
+        - Handles None/non-dict cases gracefully
+        - Preserves all unique PII tags
+        - Returns empty dict if both inputs are None/empty
+    """
+def extract_pii_mapping_from_agent_response(result: Any) -> dict[str, str] | None:
+    """Extract PII mapping from subagent response.
+
+    Used by DelegationToolManager to propagate PII mappings from subagents
+    back to parent agents.
+
+    Args:
+        result: The result returned by the delegated agent
+
+    Returns:
+        PII mapping dictionary if found, None otherwise
+
+    Note:
+        - Checks if result is a dict
+        - Extracts 'full_final_state' from result
+        - Extracts 'pii_mapping' from full_final_state
+        - Validates mapping is a non-empty dict
+        - Returns None if any step fails
+    """
+def deanonymize_final_response_content(content: str, is_final_response: bool, metadata: dict[str, Any] | None) -> str:
+    """Deanonymize final response content using PII mapping from metadata.
+
+    Args:
+        content: Final response content that may contain PII tags.
+        is_final_response: Flag indicating whether this message is a final response.
+        metadata: Optional metadata dict (or event payload containing ``metadata``) with
+            ``pii_mapping`` tag-to-value mapping.
+
+    Returns:
+        Content string with PII tags replaced by real values when applicable.
+    """
+def anonymize_final_response_content(content: str, metadata: dict[str, Any] | None) -> str:
+    """Anonymize final response content using PII mapping from metadata.
+
+    Args:
+        content: Final response content that may contain real PII values.
+        metadata: Metadata dict (or event payload containing ``metadata``) with
+            ``pii_mapping`` tag-to-value mapping.
+
+    Returns:
+        Content string with real PII values replaced by their PII tags when mapping is present.
+    """