aip-agents-binary 0.5.20__py3-none-any.whl → 0.5.22__py3-none-any.whl

aip_agents/tools/gl_connector/tool.py

@@ -1,7 +1,8 @@
-"""GL Connector tool wrapper for BOSA connector tools.
+"""Wrapper for GL Connectors.
 
 Authors:
     Saul Sayers (saul.sayers@gdplabs.id)
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
 
 Reference:
     https://gl-docs.gitbook.io/bosa/gl-connector/gl-connector
@@ -13,19 +14,30 @@ import os
 from collections.abc import Iterable
 from typing import Any
 
+from aip_agents.tools.constants import ToolType
 from bosa_connectors import BosaConnector, BOSAConnectorToolGenerator
 from langchain_core.runnables import RunnableConfig
 from langchain_core.tools import BaseTool
 from pydantic import ConfigDict, PrivateAttr
 
-from aip_agents.tools.constants import ToolType
-
 _REQUIRED_ENV_VARS: tuple[str, ...] = (
-    "BOSA_BASE_URL",
-    "BOSA_API_KEY",
-    "BOSA_USERNAME",
-    "BOSA_PASSWORD",
+    "GL_CONNECTORS_BASE_URL",
+    "GL_CONNECTORS_API_KEY",
+    "GL_CONNECTORS_USERNAME",
+    "GL_CONNECTORS_PASSWORD",
 )
+
+_ENV_VAR_MAPPING: dict[str, tuple[str, ...]] = {
+    "GL_CONNECTORS_BASE_URL": (
+        "GL_CONNECTORS_BASE_URL",
+        "BOSA_BASE_URL",
+        "BOSA_API_BASE_URL",
+    ),
+    "GL_CONNECTORS_API_KEY": ("GL_CONNECTORS_API_KEY", "BOSA_API_KEY"),
+    "GL_CONNECTORS_USERNAME": ("GL_CONNECTORS_USERNAME", "BOSA_USERNAME"),
+    "GL_CONNECTORS_PASSWORD": ("GL_CONNECTORS_PASSWORD", "BOSA_PASSWORD"),
+    "GL_CONNECTORS_IDENTIFIER": ("GL_CONNECTORS_IDENTIFIER", "BOSA_IDENTIFIER"),
+}
 _TOP_LEVEL_KEYS: tuple[str, ...] = (
     "token",
     "identifier",
@@ -54,7 +66,9 @@ class _InjectedTool(BaseTool):
         Returns:
             None
         """
-        base_fields = {field: getattr(base_tool, field) for field in BaseTool.model_fields}
+        base_fields = {
+            field: getattr(base_tool, field) for field in BaseTool.model_fields
+        }
         super().__init__(**base_fields)
         self._base_tool = base_tool
         self._token = token
@@ -84,7 +98,9 @@ class _InjectedTool(BaseTool):
         """
         return await self._base_tool._arun(*args, **kwargs)
 
-    def invoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+    def invoke(
+        self, input: Any, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> Any:
         """Invoke the tool with token and optional identifier injected.
 
         Args:
@@ -98,7 +114,9 @@ class _InjectedTool(BaseTool):
         injected = _inject_params(input, self._token, self._identifier, self._base_tool)
         return super().invoke(injected, config=config, **kwargs)
 
-    async def ainvoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+    async def ainvoke(
+        self, input: Any, config: RunnableConfig | None = None, **kwargs: Any
+    ) -> Any:
         """Invoke the tool asynchronously with token and optional identifier injected.
 
         Args:
@@ -122,7 +140,9 @@ class _InjectedTool(BaseTool):
         Returns:
             The result of running the tool with injected parameters.
         """
-        injected = _inject_params(tool_input, self._token, self._identifier, self._base_tool)
+        injected = _inject_params(
+            tool_input, self._token, self._identifier, self._base_tool
+        )
         return super().run(injected, **kwargs)
 
     async def arun(self, tool_input: Any, **kwargs: Any) -> Any:
@@ -135,7 +155,9 @@ class _InjectedTool(BaseTool):
         Returns:
             The result of running the tool with injected parameters.
         """
-        injected = _inject_params(tool_input, self._token, self._identifier, self._base_tool)
+        injected = _inject_params(
+            tool_input, self._token, self._identifier, self._base_tool
+        )
         return await super().arun(injected, **kwargs)
 
 
@@ -145,12 +167,12 @@ def GLConnectorTool(
     api_key: str | None = None,
     identifier: str | None = None,
 ) -> BaseTool:
-    """Create a single GL Connector tool by exact tool name.
+    """Create a single tool from GL Connectors by exact tool name.
 
     Args:
         tool_name: Exact tool name (not module name).
-        api_key: Optional override for BOSA API key.
-        identifier: Optional override for BOSA identifier.
+        api_key: Optional override for GL Connectors API key.
+        identifier: Optional override for GL Connectors identifier.
 
     Returns:
         A single LangChain BaseTool with token injection.
@@ -159,14 +181,17 @@ def GLConnectorTool(
         raise ValueError("tool_name must be a non-empty string")
 
     env_values = _load_env(api_key=api_key, identifier=identifier)
-    connector = BosaConnector(api_base_url=env_values["BOSA_BASE_URL"], api_key=env_values["BOSA_API_KEY"])
+    connector = BosaConnector(
+        api_base_url=env_values["GL_CONNECTORS_BASE_URL"],
+        api_key=env_values["GL_CONNECTORS_API_KEY"],
+    )
 
     modules = _get_available_modules(connector)
     module_name = _resolve_module(tool_name, modules)
 
     generator = BOSAConnectorToolGenerator(
-        api_base_url=env_values["BOSA_BASE_URL"],
-        api_key=env_values["BOSA_API_KEY"],
+        api_base_url=env_values["GL_CONNECTORS_BASE_URL"],
+        api_key=env_values["GL_CONNECTORS_API_KEY"],
         app_name=module_name,
     )
     tools = generator.generate_tools(tool_type=ToolType.LANGCHAIN)
@@ -175,18 +200,24 @@ def GLConnectorTool(
     if not matching:
         raise ValueError(f"Tool '{tool_name}' not found in module '{module_name}'")
     if len(matching) > 1:
-        raise ValueError(f"Multiple tools named '{tool_name}' found in module '{module_name}'")
-
-    token = _create_token(connector, env_values["BOSA_USERNAME"], env_values["BOSA_PASSWORD"])
-    return _InjectedTool(matching[0], token, env_values.get("BOSA_IDENTIFIER"))
+        raise ValueError(
+            f"Multiple tools named '{tool_name}' found in module '{module_name}'"
+        )
+
+    token = _create_token(
+        connector,
+        env_values["GL_CONNECTORS_USERNAME"],
+        env_values["GL_CONNECTORS_PASSWORD"],
+    )
+    return _InjectedTool(matching[0], token, env_values.get("GL_CONNECTORS_IDENTIFIER"))
 
 
 def _load_env(*, api_key: str | None, identifier: str | None) -> dict[str, str]:
     """Load and validate environment configuration for connector access.
 
     Args:
-        api_key: Optional override for BOSA API key.
-        identifier: Optional override for BOSA identifier.
+        api_key: Optional override for GL Connectors API key.
+        identifier: Optional override for GL Connectors identifier.
 
     Returns:
         Dictionary containing environment configuration values.
@@ -194,28 +225,42 @@ def _load_env(*, api_key: str | None, identifier: str | None) -> dict[str, str]:
     Raises:
         ValueError: If required environment variables are missing.
     """
-    env = {key: os.getenv(key) for key in _REQUIRED_ENV_VARS}
+    env: dict[str, str | None] = {}
 
-    resolved_api_key = api_key or env["BOSA_API_KEY"]
-    env["BOSA_API_KEY"] = resolved_api_key
+    # Load from environment using mapping (prefers GL_CONNECTORS_* over BOSA_*)
+    for internal_key, env_vars in _ENV_VAR_MAPPING.items():
+        val = None
+        for var_name in env_vars:
+            val = os.getenv(var_name)
+            if val:
+                break
+        env[internal_key] = val
 
-    optional_identifier = identifier or os.getenv("BOSA_IDENTIFIER")
+    if api_key:
+        env["GL_CONNECTORS_API_KEY"] = api_key
 
-    if optional_identifier:
-        env["BOSA_IDENTIFIER"] = optional_identifier
+    if identifier:
+        env["GL_CONNECTORS_IDENTIFIER"] = identifier
 
-    missing = [key for key, value in env.items() if key in _REQUIRED_ENV_VARS and not value]
+    missing = [key for key in _REQUIRED_ENV_VARS if not env.get(key)]
     if missing:
-        raise ValueError(f"Missing required environment variables: {', '.join(missing)}")
+        # Map back to human-friendly names for the error message
+        friendly_missing = []
+        for m in missing:
+            preferred = _ENV_VAR_MAPPING[m][0]
+            friendly_missing.append(preferred)
+        raise ValueError(
+            f"Missing required environment variables: {', '.join(friendly_missing)}"
+        )
 
-    return {key: value for key, value in env.items() if value is not None}
+    return {k: v for k, v in env.items() if v is not None}
 
 
 def _get_available_modules(connector: BosaConnector) -> list[str]:
     """Return available connector modules or raise an actionable error.
 
     Args:
-        connector: BOSA connector instance to query for modules.
+        connector: GL Connectors instance to query for modules.
 
     Returns:
         List of available module names.
@@ -246,13 +291,21 @@ def _resolve_module(tool_name: str, modules: Iterable[str]) -> str:
     Raises:
         ValueError: If no matching module is found or multiple ambiguous matches exist.
     """
-    candidates = [module for module in modules if tool_name == module or tool_name.startswith(f"{module}_")]
+    candidates = [
+        module
+        for module in modules
+        if tool_name == module or tool_name.startswith(f"{module}_")
+    ]
     if not candidates:
-        raise ValueError(f"Unable to resolve module for tool '{tool_name}'. Available modules: {', '.join(modules)}")
+        raise ValueError(
+            f"Unable to resolve module for tool '{tool_name}'. Available modules: {', '.join(modules)}"
+        )
 
     candidates.sort(key=len, reverse=True)
     if len(candidates) > 1 and len(candidates[0]) == len(candidates[1]):
-        raise ValueError(f"Ambiguous module match for tool '{tool_name}'. Matches: {', '.join(candidates)}")
+        raise ValueError(
+            f"Ambiguous module match for tool '{tool_name}'. Matches: {', '.join(candidates)}"
+        )
     return candidates[0]
 
 
@@ -260,9 +313,9 @@ def _create_token(connector: BosaConnector, username: str, password: str) -> str
     """Authenticate the connector user and return a user token.
 
     Args:
-        connector: BOSA connector instance for authentication.
-        username: BOSA username for authentication.
-        password: BOSA password for authentication.
+        connector: GL Connectors instance for authentication.
+        username: GL Connectors username for authentication.
+        password: GL Connectors password for authentication.
 
     Returns:
         Authentication token string.
@@ -273,15 +326,17 @@ def _create_token(connector: BosaConnector, username: str, password: str) -> str
     try:
         user = connector.authenticate_bosa_user(username, password)
     except Exception as exc:
-        raise ValueError("Failed to authenticate BOSA user") from exc
+        raise ValueError("Failed to authenticate GL Connectors user") from exc
 
     token = getattr(user, "token", None)
     if not token:
-        raise ValueError("BOSA user token missing after authentication")
+        raise ValueError("GL Connectors user token missing after authentication")
     return token
 
 
-def _inject_params(tool_input: Any, token: str, identifier: str | None, base_tool: BaseTool) -> dict[str, Any]:
+def _inject_params(
+    tool_input: Any, token: str, identifier: str | None, base_tool: BaseTool
+) -> dict[str, Any]:
     """Inject token and optional identifier into tool input.
 
     Args:
@@ -319,7 +374,9 @@ def _inject_params(tool_input: Any, token: str, identifier: str | None, base_too
     return injected
 
 
-def _wrap_request_if_needed(tool_input: dict[str, Any], base_tool: BaseTool) -> dict[str, Any]:
+def _wrap_request_if_needed(
+    tool_input: dict[str, Any], base_tool: BaseTool
+) -> dict[str, Any]:
     """Wrap flat inputs into a 'request' payload when required by schema.
 
     Args:
@@ -330,7 +387,9 @@ def _wrap_request_if_needed(tool_input: dict[str, Any], base_tool: BaseTool) ->
         Dictionary with inputs wrapped in 'request' key if needed, otherwise unchanged.
     """
     args_schema = getattr(base_tool, "args_schema", None)
-    if not (isinstance(args_schema, dict) and "request" in args_schema.get("properties", {})):
+    if not (
+        isinstance(args_schema, dict) and "request" in args_schema.get("properties", {})
+    ):
         return tool_input
 
     request_payload = {}

aip_agents/tools/gl_connector/tool.pyi

@@ -0,0 +1,74 @@
+from _typeshed import Incomplete
+from aip_agents.tools.constants import ToolType as ToolType
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from typing import Any
+
+class _InjectedTool(BaseTool):
+    """Wrap a BaseTool to inject token and optional identifier into inputs."""
+    model_config: Incomplete
+    def __init__(self, base_tool: BaseTool, token: str, identifier: str | None) -> None:
+        """Initialize the injected tool wrapper.
+
+        Args:
+            base_tool: The base tool to wrap.
+            token: Authentication token to inject into tool inputs.
+            identifier: Optional identifier to inject into tool inputs.
+
+        Returns:
+            None
+        """
+    def invoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+        """Invoke the tool with token and optional identifier injected.
+
+        Args:
+            input: Tool input to process.
+            config: Optional runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of invoking the tool with injected parameters.
+        """
+    async def ainvoke(self, input: Any, config: RunnableConfig | None = None, **kwargs: Any) -> Any:
+        """Invoke the tool asynchronously with token and optional identifier injected.
+
+        Args:
+            input: Tool input to process.
+            config: Optional runnable configuration.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of invoking the tool with injected parameters.
+        """
+    def run(self, tool_input: Any, **kwargs: Any) -> Any:
+        """Run the tool with token and optional identifier injected.
+
+        Args:
+            tool_input: Tool input to process.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of running the tool with injected parameters.
+        """
+    async def arun(self, tool_input: Any, **kwargs: Any) -> Any:
+        """Run the tool asynchronously with token and optional identifier injected.
+
+        Args:
+            tool_input: Tool input to process.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            The result of running the tool with injected parameters.
+        """
+
+def GLConnectorTool(tool_name: str, *, api_key: str | None = None, identifier: str | None = None) -> BaseTool:
+    """Create a single tool from GL Connectors by exact tool name.
+
+    Args:
+        tool_name: Exact tool name (not module name).
+        api_key: Optional override for GL Connectors API key.
+        identifier: Optional override for GL Connectors identifier.
+
+    Returns:
+        A single LangChain BaseTool with token injection.
+    """

aip_agents/tools/gl_connector_tools.py

@@ -0,0 +1,122 @@
+"""Auto-generated tools from GL Connectors.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+from aip_agents.tools.constants import (
+    GL_CONNECTORS_API_KEY,
+    GL_CONNECTORS_BASE_URL,
+    GL_CONNECTORS_FETCH_MAX_RETRIES,
+    ToolType,
+)
+from aip_agents.utils.logger import get_logger
+from bosa_connectors import BosaConnector, BOSAConnectorToolGenerator
+from langchain_core.tools import BaseTool
+
+logger = get_logger(__name__)
+
+
+def get_gl_connector_modules_with_retry() -> list[str]:
+    """Try to get available modules with retries.
+
+    Returns:
+        List of available modules.
+    """
+    if not GL_CONNECTORS_BASE_URL or not GL_CONNECTORS_API_KEY:
+        logger.warning(
+            "GL Connectors credentials missing (base_url or api_key); returning empty modules list"
+        )
+        return []
+
+    connector = BosaConnector(
+        api_base_url=GL_CONNECTORS_BASE_URL, api_key=GL_CONNECTORS_API_KEY
+    )
+    modules = []
+    for attempt in range(GL_CONNECTORS_FETCH_MAX_RETRIES):
+        try:
+            modules = list(connector.get_available_modules())
+            if modules:
+                return modules
+            logger.warning(
+                f"Failed to get GL Connectors available modules, retrying... (attempt {attempt + 1} / {GL_CONNECTORS_FETCH_MAX_RETRIES})"
+            )
+        except Exception as e:
+            logger.exception(
+                f"Exception when getting GL Connectors available modules (attempt {attempt + 1} / {GL_CONNECTORS_FETCH_MAX_RETRIES}): {e}"
+            )
+    logger.error("Failed to get GL Connectors available modules after maximum retries")
+    return modules
+
+
+class LazyGLConnectorToolsDict(dict):
+    """Lazy dictionary for GL Connectors."""
+
+    def __missing__(self, app):
+        """When a key is missing, create the tools and store them in the dictionary.
+
+        Args:
+            app: Name of the GL Connectors.
+
+        Returns:
+            List of tools generated by the GL Connectors tool generator.
+        """
+        if app not in get_gl_connector_modules():
+            return []
+        tools = []
+        for attempt in range(GL_CONNECTORS_FETCH_MAX_RETRIES):
+            try:
+                tools = BOSAConnectorToolGenerator(
+                    api_base_url=GL_CONNECTORS_BASE_URL,
+                    api_key=GL_CONNECTORS_API_KEY,
+                    app_name=app,
+                ).generate_tools(tool_type=ToolType.LANGCHAIN)
+                if tools:
+                    self[app] = tools
+                    return tools
+                logger.warning(
+                    f"Failed to create GL Connectors, retrying... (attempt {attempt + 1} / {GL_CONNECTORS_FETCH_MAX_RETRIES})"
+                )
+            except Exception as e:
+                logger.exception(
+                    f"Exception when creating GL Connectors for app '{app}' "
+                    f"(attempt {attempt + 1} / {GL_CONNECTORS_FETCH_MAX_RETRIES}): {e}"
+                )
+        logger.error("Failed to create GL Connectors after maximum retries")
+        return tools
+
+
+# Supported modules (dynamic)
+def get_gl_connector_modules() -> list[str]:
+    """Lazily fetch and cache GL Connectors modules.
+
+    Returns:
+        List of GL Connectors modules.
+    """
+    if not hasattr(get_gl_connector_modules, "_cache"):
+        get_gl_connector_modules._cache = get_gl_connector_modules_with_retry()
+    return get_gl_connector_modules._cache
+
+
+# FOR BACKWARDS COMPATIBILITY
+def get_bosa_modules() -> list[str]:
+    """Backward-compatible alias for get_gl_connector_modules."""
+    return get_gl_connector_modules()
+
+
+GL_CONNECTORS_MODULES = [
+    "github",
+    "twitter",
+    "google",
+    "google_drive",
+    "google_mail",
+    "google_docs",
+]
+
+# FOR BACKWARDS COMPATIBILITY
+BOSA_MODULES = GL_CONNECTORS_MODULES
+
+GL_CONNECTORS_AUTOMATED_TOOLS: dict[str, list[BaseTool]] = LazyGLConnectorToolsDict()
+
+# FOR BACKWARDS COMPATIBILITY
+BOSA_AUTOMATED_TOOLS = GL_CONNECTORS_AUTOMATED_TOOLS

aip_agents/tools/gl_connector_tools.pyi

@@ -0,0 +1,39 @@
+from _typeshed import Incomplete
+from aip_agents.tools.constants import GL_CONNECTORS_API_KEY as GL_CONNECTORS_API_KEY, GL_CONNECTORS_BASE_URL as GL_CONNECTORS_BASE_URL, GL_CONNECTORS_FETCH_MAX_RETRIES as GL_CONNECTORS_FETCH_MAX_RETRIES, ToolType as ToolType
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool as BaseTool
+
+logger: Incomplete
+
+def get_gl_connector_modules_with_retry() -> list[str]:
+    """Try to get available modules with retries.
+
+    Returns:
+        List of available modules.
+    """
+
+class LazyGLConnectorToolsDict(dict):
+    """Lazy dictionary for GL Connectors."""
+    def __missing__(self, app):
+        """When a key is missing, create the tools and store them in the dictionary.
+
+        Args:
+            app: Name of the GL Connectors.
+
+        Returns:
+            List of tools generated by the GL Connectors tool generator.
+        """
+
+def get_gl_connector_modules() -> list[str]:
+    """Lazily fetch and cache GL Connectors modules.
+
+    Returns:
+        List of GL Connectors modules.
+    """
+def get_bosa_modules() -> list[str]:
+    """Backward-compatible alias for get_gl_connector_modules."""
+
+GL_CONNECTORS_MODULES: Incomplete
+BOSA_MODULES = GL_CONNECTORS_MODULES
+GL_CONNECTORS_AUTOMATED_TOOLS: dict[str, list[BaseTool]]
+BOSA_AUTOMATED_TOOLS = GL_CONNECTORS_AUTOMATED_TOOLS

aip_agents/tools/memory_search/__init__.pyi

@@ -0,0 +1,5 @@
+from aip_agents.tools.memory_search.base import LongTermMemorySearchTool as LongTermMemorySearchTool
+from aip_agents.tools.memory_search.mem0 import MEMORY_SEARCH_TOOL_NAME as MEMORY_SEARCH_TOOL_NAME, Mem0SearchInput as Mem0SearchInput, Mem0SearchTool as Mem0SearchTool
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput as LongTermMemorySearchInput, MemoryConfig as MemoryConfig
+
+__all__ = ['MemoryConfig', 'LongTermMemorySearchInput', 'LongTermMemorySearchTool', 'Mem0SearchInput', 'Mem0SearchTool', 'MEMORY_SEARCH_TOOL_NAME']

aip_agents/tools/memory_search/base.pyi

@@ -0,0 +1,69 @@
+from _typeshed import Incomplete
+from abc import ABC
+from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput as LongTermMemorySearchInput, MemoryConfig as MemoryConfig
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Callable
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel as BaseModel
+from typing import Any, ClassVar, Protocol
+
+logger: Incomplete
+
+class LongTermMemoryBackend(Protocol):
+    """Protocol for memory adapters that support retrieval and formatting."""
+    def retrieve(self, *, query: str | None, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None, page: int | None = None) -> list[dict[str, Any]]:
+        """Retrieve memories matching the given query and filters.
+
+        Args:
+            query: Optional search query string.
+            user_id: User identifier for scoped retrieval.
+            limit: Maximum number of results to return.
+            filters: Optional filters to apply to the retrieval.
+            page: Page number for pagination.
+
+        Returns:
+            List of memory hit dictionaries.
+        """
+    def format_hits(self, hits: list[dict[str, Any]], max_items: int = ..., with_tag: bool = True) -> str:
+        """Format memory hits into a readable string.
+
+        Args:
+            hits: List of memory hit dictionaries to format.
+            max_items: Maximum number of hits to include in output.
+            with_tag: Whether to wrap output with memory tags.
+
+        Returns:
+            Formatted string representation of memory hits.
+        """
+
+class LongTermMemorySearchTool(BaseTool, ABC):
+    """Abstract base class for provider-specific long-term memory search tools."""
+    name: str
+    description: str
+    args_schema: type[LongTermMemorySearchInput]
+    tool_config_schema: type[BaseModel]
+    memory: LongTermMemoryBackend
+    default_user_id: str | None
+    user_id_provider: Callable[[], str | None] | None
+    MINIMUM_MEMORY_RETRIEVAL: ClassVar[int]
+    LOG_PREFIX: ClassVar[str]
+    def __init__(self, memory: LongTermMemoryBackend, *, default_user_id: str | None = None, user_id_provider: Callable[[], str | None] | None = None, **kwargs: Any) -> None:
+        """Initialize the long-term memory search tool.
+
+        Args:
+            memory: Memory adapter instance with retrieve() and format_hits() methods.
+            default_user_id: Default user ID to use if not provided in metadata.
+            user_id_provider: Callable that returns a user ID.
+            **kwargs: Additional keyword arguments passed to the parent class.
+        """
+    def format_hits(self, hits: list[dict[str, Any]], with_tag: bool = False) -> str:
+        """Format hits into a string with optional tags.
+
+        Args:
+            hits: List of memory hit dictionaries to format.
+            with_tag: Whether to wrap the output with memory tags.
+
+        Returns:
+            Formatted string representation of the memory hits.
+        """

aip_agents/tools/memory_search/mem0.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Incomplete
+from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
+from aip_agents.tools.memory_search.base import LongTermMemorySearchTool as LongTermMemorySearchTool
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput as LongTermMemorySearchInput
+from aip_agents.utils.datetime import is_valid_date_string as is_valid_date_string, next_day_iso as next_day_iso
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import ClassVar
+
+logger: Incomplete
+MEMORY_SEARCH_TOOL_NAME: str
+
+class Mem0SearchTool(LongTermMemorySearchTool):
+    """Mem0-specific implementation of the long-term memory search tool."""
+    name: str
+    description: str
+    args_schema: type[LongTermMemorySearchInput]
+    LOG_PREFIX: ClassVar[str]
+    METADATA_FILTER_BLOCKLIST: ClassVar[set[str]]
+Mem0SearchInput = LongTermMemorySearchInput

aip_agents/tools/memory_search/schema.pyi

@@ -0,0 +1,15 @@
+from pydantic import BaseModel
+from typing import Any
+
+class MemoryConfig(BaseModel):
+    """Tool configuration schema for memory operations."""
+    user_id: str
+
+class LongTermMemorySearchInput(BaseModel):
+    """Input schema for unified long-term memory retrieval."""
+    query: str | None
+    start_date: str | None
+    end_date: str | None
+    limit: int | None
+    categories: list[str] | None
+    metadata: dict[str, Any] | None

aip_agents/tools/memory_search_tool.pyi

@@ -0,0 +1,3 @@
+from aip_agents.tools.memory_search import LongTermMemorySearchInput as LongTermMemorySearchInput, LongTermMemorySearchTool as LongTermMemorySearchTool, MEMORY_SEARCH_TOOL_NAME as MEMORY_SEARCH_TOOL_NAME, Mem0SearchInput as Mem0SearchInput, Mem0SearchTool as Mem0SearchTool, MemoryConfig as MemoryConfig
+
+__all__ = ['MemoryConfig', 'LongTermMemorySearchInput', 'LongTermMemorySearchTool', 'Mem0SearchInput', 'Mem0SearchTool', 'MEMORY_SEARCH_TOOL_NAME']

aip_agents/tools/time_tool.pyi

@@ -0,0 +1,16 @@
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+FORMAT_STRING: str
+DEFAULT_TIMEZONE: str
+
+class TimeToolInput(BaseModel):
+    """Input schema for the TimeTool."""
+    datetime_format: str
+    timezone: str | None
+
+class TimeTool(BaseTool):
+    """Tool to get the current time."""
+    name: str
+    description: str
+    args_schema: type[BaseModel]