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

aip_agents/utils/name_preprocessor/google_name_preprocessor.py

@@ -0,0 +1,100 @@
+"""Concrete implementation of NamePreprocessor according to Google's name requirements.
+
+This implementation provides the correction of name according to Google's name requirements.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.name_preprocessor import BaseNamePreprocessor
+
+logger = get_logger(__name__)
+
+
+class GoogleNamePreprocessor(BaseNamePreprocessor):
+    """Concrete implementation of NamePreprocessor according to Google's name requirements."""
+
+    NAME_SETTINGS = {
+        "tool": {
+            "prefix_fix": "Tool_",
+            "regex": r"[^a-zA-Z0-9_-]",
+        },
+        "agent": {
+            "prefix_fix": "Agent_",
+            "regex": r"\W",
+        },
+    }
+    CUT_OFF_INDEX = 63
+
+    def _ensure_name_starts_with_letter_or_underscore(self, prefix_fix: str, name: str) -> str:
+        """Preprocess an input name to be fixed if it doesn't start with a letter or an underscore.
+
+        Args:
+            prefix_fix: The prefix to add to the name if it doesn't start with a letter or an underscore.
+            name: The input name to preprocess.
+
+        Returns:
+            A name that starts with a letter or an underscore.
+
+        Notes:
+            Name should start with a letter (a-z, A-Z) or an underscore (_),
+            and can only contain letters, digits (0-9), and underscores.
+        """
+        if not name or (not name[0].isalpha() and name[0] != "_"):
+            logger.warning(f"Invalid agent name: {name}. Agent name should start with a letter or an underscore.")
+            prefix_fix = self._ensure_name_starts_with_letter_or_underscore("_", prefix_fix)
+            name = prefix_fix + name
+        return name
+
+    def _common_process(self, name_type: str, name: str) -> str:
+        """Preprocess an input name according to Google's name requirements.
+
+        Args:
+            name_type: The type of the name to preprocess ("tool" or "agent").
+            name: The input name to preprocess.
+
+        Returns:
+            A name that is valid for Google.
+        """
+        prefix_fix = self.NAME_SETTINGS[name_type]["prefix_fix"]
+        regex = self.NAME_SETTINGS[name_type]["regex"]
+        name = self._ensure_name_starts_with_letter_or_underscore(prefix_fix, name)
+        name = self.regex_substitute(name, regex, "_")
+        name = self.clean_up_name(name)
+        return name
+
+    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 )
+        """
+        name = self._common_process("agent", name)
+        return name
+
+    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.
+        """
+        name = self._common_process("tool", name)
+        name = name[: self.CUT_OFF_INDEX]
+        return name

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.py

@@ -0,0 +1,87 @@
+"""Utility functions for name preprocessing.
+
+This module provides functions to preprocess names according to Google's name requirements.
+
+References:
+    https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/function-calling
+
+Rules:
+- For GoogleADK Agent Name:
+    - Must start with a letter (a-z, A-Z) or an underscore (_),
+    - Can only contain letters, digits (0-9), and underscores.
+    - Has no length limit.
+- For Tool Name:
+    - Must start with a letter (a-z, A-Z) or an underscore (_),
+    - Can only contain letters, digits (0-9), underscores, and dashes.
+    - Has a length limit of 64 characters, but google throws error if the length is exactly 64, so cut to 63.
+- For OpenAI,
+    - they only have rule for tool name, and it is the same as Google's tool name rule,
+    - except it can start with any character as long as it is a valid character (alphanumeric, _, -)
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.name_preprocessor.base_name_preprocessor import BaseNamePreprocessor
+from aip_agents.utils.name_preprocessor.google_name_preprocessor import GoogleNamePreprocessor
+from aip_agents.utils.name_preprocessor.openai_name_preprocessor import OpenAINamePreprocessor
+
+logger = get_logger(__name__)
+
+
+class NamePreprocessor:
+    """Name Preprocessor for Google ADK and OpenAI compatible models.
+
+    Args:
+        provider: The provider of the model.
+    """
+
+    PROVIDER_TO_NAME_PREPROCESSOR_MAP = {
+        "openai": OpenAINamePreprocessor,
+        "openai-compatible": OpenAINamePreprocessor,
+        "google": GoogleNamePreprocessor,
+    }
+
+    def __init__(self, provider: str):
+        """Initialize the name preprocessor.
+
+        Args:
+            provider: The provider of the model.
+        """
+        self.provider = provider
+        self.preprocessor = self._get_preprocessor()
+
+    def _get_preprocessor(self) -> BaseNamePreprocessor:
+        """Get the name processor for the given provider.
+
+        Args:
+            provider: The provider of the model, i.e. openai, google, etc.
+            This is used to determine which name processor to use.
+
+        Returns:
+            A name processor for the given provider.
+        """
+        return self.PROVIDER_TO_NAME_PREPROCESSOR_MAP.get(self.provider, GoogleNamePreprocessor)()
+
+    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.
+        """
+        return self.preprocessor.sanitize_agent_name(name)
+
+    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.
+        """
+        return self.preprocessor.sanitize_tool_name(name)

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.py

@@ -0,0 +1,48 @@
+"""Concrete implementation of NamePreprocessor according to OpenAI's name requirements.
+
+Authors:
+    Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+from aip_agents.utils.logger import get_logger
+from aip_agents.utils.name_preprocessor import BaseNamePreprocessor
+
+logger = get_logger(__name__)
+
+
+class OpenAINamePreprocessor(BaseNamePreprocessor):
+    """Concrete implementation of NamePreprocessor according to OpenAI's name requirements."""
+
+    CUT_OFF_INDEX = 64
+
+    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.
+        """
+        return name
+
+    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.
+        """
+        name = self.regex_substitute(name, r"[^a-zA-Z0-9_-]", "_")
+        name = self.clean_up_name(name)
+        name = name[: self.CUT_OFF_INDEX]
+        return name

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__.py

@@ -0,0 +1,25 @@
+"""Public API for PII-related utilities.
+
+This subpackage groups all helpers for anonymizing/deanonymizing PII used by
+agents and tools.
+"""
+
+from aip_agents.utils.pii.pii_handler import ToolPIIHandler
+from aip_agents.utils.pii.pii_helper import (
+    add_pii_mappings,
+    anonymize_final_response_content,
+    deanonymize_final_response_content,
+    extract_pii_mapping_from_agent_response,
+    normalize_enable_pii,
+)
+from aip_agents.utils.pii.uuid_deanonymizer_mapping import 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/__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']