aip-agents-binary 0.5.25b1__py3-none-macosx_13_0_arm64.whl

aip_agents/tools/memory_search/base.py

@@ -0,0 +1,200 @@
+"""Abstract base class for long-term memory search tools.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any, ClassVar, Protocol, runtime_checkable
+
+from langchain_core.runnables import RunnableConfig
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel
+
+from aip_agents.memory.constants import MemoryDefaults
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput, MemoryConfig
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+@runtime_checkable
+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 = MemoryDefaults.MAX_ITEMS,
+        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 = "long_term_memory_search"
+    description: str = "Abstract interface for tools that retrieve long-term memories."
+    args_schema: type[LongTermMemorySearchInput] = LongTermMemorySearchInput
+    tool_config_schema: type[BaseModel] = MemoryConfig
+    memory: LongTermMemoryBackend
+    default_user_id: str | None = None
+    user_id_provider: Callable[[], str | None] | None = None
+    MINIMUM_MEMORY_RETRIEVAL: ClassVar[int] = 5
+    LOG_PREFIX: ClassVar[str] = "LongTermMemorySearchTool"
+
+    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.
+        """
+        required_attributes = {"retrieve", "format_hits"}
+        if not all(hasattr(memory, attr) for attr in required_attributes):
+            raise ValueError(
+                "LongTermMemorySearchTool requires a memory instance that implements retrieve() and format_hits()."
+            )
+
+        super().__init__(
+            memory=memory,
+            default_user_id=default_user_id,
+            user_id_provider=user_id_provider,
+            **kwargs,
+        )
+
+    @abstractmethod
+    async def _arun(
+        self,
+        query: str | None = None,
+        config: RunnableConfig | None = None,
+        run_manager: Any | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute provider-specific retrieval logic.
+
+        Args:
+            query: Optional search query string.
+            config: Runnable configuration for the execution.
+            run_manager: Optional run manager for execution tracking.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Formatted string of retrieved memories.
+        """
+
+    def _run(
+        self,
+        query: str | None = None,
+        config: RunnableConfig | None = None,
+        run_manager: Any | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Synchronous wrapper that delegates to `_arun` using `asyncio.run`.
+
+        Args:
+            query: Optional search query string.
+            config: Runnable configuration for the execution.
+            run_manager: Optional run manager for execution tracking.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Formatted string of retrieved memories.
+        """
+        return asyncio.run(self._arun(query=query, config=config, run_manager=run_manager, **kwargs))
+
+    def _resolve_user_id(self, metadata: dict[str, Any] | None, config: RunnableConfig | None = None) -> str:
+        """Resolve the user ID for memory operations in a provider-agnostic way.
+
+        Args:
+            metadata: Optional metadata dictionary that may contain user_id.
+            config: Optional runnable configuration for tool context.
+
+        Returns:
+            The resolved user ID string.
+        """
+        user_id: str | None = None
+
+        if isinstance(metadata, dict):
+            user_id = metadata.get("user_id")
+
+        if not user_id and config and hasattr(self, "get_tool_config"):
+            logger.info("%s: Resolving user_id from RunnableConfig", self.LOG_PREFIX)
+            try:
+                tool_config = self.get_tool_config(config)  # injected by tool_config_injector
+                logger.info("%s: Injected tool_config: %s", self.LOG_PREFIX, tool_config)
+                if tool_config and hasattr(tool_config, "user_id"):
+                    user_id = tool_config.user_id
+                    logger.info("%s: Using user_id from tool config: %s", self.LOG_PREFIX, user_id)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("%s: get_tool_config failed: %s", self.LOG_PREFIX, exc)
+
+        if not user_id and self.user_id_provider:
+            try:
+                user_id = self.user_id_provider()
+                logger.info("%s: Using user_id from provider: %s", self.LOG_PREFIX, user_id)
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("%s: user_id_provider failed: %s", self.LOG_PREFIX, exc)
+
+        resolved_user_id = user_id or self.default_user_id or MemoryDefaults.DEFAULT_USER_ID
+        logger.info("%s: Resolved user_id: %s", self.LOG_PREFIX, resolved_user_id)
+        return resolved_user_id
+
+    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.
+        """
+        return self.memory.format_hits(hits, max_items=len(hits), with_tag=with_tag)

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

@@ -0,0 +1,258 @@
+"""Mem0-specific implementation of the long-term memory search tool.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, ClassVar
+
+from langchain_core.runnables import RunnableConfig
+
+from aip_agents.memory.constants import MemoryDefaults
+from aip_agents.tools.memory_search.base import LongTermMemorySearchTool
+from aip_agents.tools.memory_search.schema import LongTermMemorySearchInput
+from aip_agents.utils.datetime import is_valid_date_string, next_day_iso
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+MEMORY_SEARCH_TOOL_NAME = "built_in_mem0_search"
+
+
+class Mem0SearchTool(LongTermMemorySearchTool):
+    """Mem0-specific implementation of the long-term memory search tool."""
+
+    name: str = MEMORY_SEARCH_TOOL_NAME
+    description: str = (
+        "Search or retrieve memories from long-term mem0 storage. Supports two modes:\n"
+        "1. SEMANTIC SEARCH: Provide 'query' to search for relevant memories by content\n"
+        "2. DATE-BASED RECALL: Omit 'query' to get all memories from an explicit date period\n\n"
+        "Time periods only support explicit dates ('start_date'/'end_date' in YYYY-MM-DD format).\n\n"
+        "Use for: names, preferences, past plans, conversations, or when user asks "
+        "'What did we discuss last week?' or 'Search for project notes'"
+    )
+    args_schema: type[LongTermMemorySearchInput] = LongTermMemorySearchInput
+    LOG_PREFIX: ClassVar[str] = "Mem0SearchTool"
+    METADATA_FILTER_BLOCKLIST: ClassVar[set[str]] = {"user_id", "memory_user_id"}
+
+    async def _arun(
+        self,
+        query: str | None = None,
+        config: RunnableConfig | None = None,
+        run_manager: Any | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Execute the memory search asynchronously for LangChain.
+
+        Args:
+            query: Semantic search query when provided.
+            config: Runnable configuration containing LangChain metadata.
+            run_manager: LangChain callbacks (unused).
+            **kwargs: Additional filters such as ``start_date``, ``end_date``, ``limit``, ``categories``, ``metadata``.
+
+        Returns:
+            str: JSON-encoded retrieval results or an error message.
+        """
+        logger.info("%s: Received config: %s", self.LOG_PREFIX, config)
+
+        start_date: str | None = kwargs.get("start_date")
+        end_date: str | None = kwargs.get("end_date")
+        limit: int | None = kwargs.get("limit")
+        categories: list[str] | None = kwargs.get("categories")
+        metadata: dict[str, Any] | None = kwargs.get("metadata")
+
+        user_id = self._resolve_user_id(metadata=metadata, config=config)
+
+        metadata_filter = None
+        if isinstance(metadata, dict):
+            metadata_filter = {k: v for k, v in metadata.items() if k not in self.METADATA_FILTER_BLOCKLIST} or None
+
+        date_filter_result = self._parse_date_filters(
+            start_date=start_date,
+            end_date=end_date,
+            user_id=user_id,
+        )
+
+        if "error" in date_filter_result:
+            return f"Error: {date_filter_result['error']}"
+
+        filters = self._add_additional_filters(
+            filters=date_filter_result["filters"],
+            categories=categories,
+            metadata=metadata_filter,
+            user_id=user_id,
+        )
+
+        time_spec = f"{start_date or 'unbounded'} to {end_date or 'unbounded'}"
+
+        raw_results = self._perform_retrieval(
+            query=query,
+            user_id=user_id,
+            limit=limit,
+            filters=filters,
+            time_spec=time_spec,
+        )
+
+        return json.dumps(raw_results)
+
+    def _parse_date_filters(
+        self,
+        *,
+        start_date: str | None,
+        end_date: str | None,
+        user_id: str,
+    ) -> dict[str, Any]:
+        """Build normalized date filters validated against YYYY-MM-DD strings.
+
+        Args:
+            start_date: Inclusive start date for recall filtering.
+            end_date: Inclusive end date for recall filtering.
+            user_id: User identifier to scope the memories.
+
+        Returns:
+            dict[str, Any]: Payload including ``filters`` or an ``error`` entry when validation fails.
+        """
+        filters: dict[str, Any] = {"AND": [{"user_id": user_id}]}
+        if start_date or end_date:
+            try:
+                date_range_filter = self._build_explicit_date_filter(start_date, end_date)
+                if date_range_filter:
+                    filters["AND"].append(date_range_filter)
+                    logger.info(
+                        "%s: Using explicit date range [%s, %s] for user_id='%s'",
+                        self.LOG_PREFIX,
+                        start_date or "unbounded",
+                        end_date or "unbounded",
+                        user_id,
+                    )
+            except ValueError as exc:
+                logger.warning("%s: Invalid explicit date range: %s", self.LOG_PREFIX, exc)
+                return {"error": str(exc), "hits": [], "count": 0}
+
+        return {"filters": filters}
+
+    def _build_explicit_date_filter(self, start_date: str | None, end_date: str | None) -> dict[str, Any] | None:
+        """Return the mem0-compatible date clause for explicit ranges.
+
+        Args:
+            start_date: Inclusive start date string.
+            end_date: Inclusive end date string.
+
+        Returns:
+            dict[str, Any] | None: Date filter clause or None when no bounds were provided.
+
+        Raises:
+            ValueError: If either date fails the YYYY-MM-DD validation.
+        """
+        if not start_date and not end_date:
+            return None
+
+        date_filter: dict[str, Any] = {}
+
+        if start_date:
+            if not is_valid_date_string(start_date, "%Y-%m-%d"):
+                raise ValueError(f"Invalid start_date format '{start_date}'. Expected YYYY-MM-DD.")
+            date_filter["gte"] = start_date
+
+        if end_date:
+            if not is_valid_date_string(end_date, "%Y-%m-%d"):
+                raise ValueError(f"Invalid end_date format '{end_date}'. Expected YYYY-MM-DD.")
+            date_filter["lt"] = next_day_iso(end_date)
+
+        return {"created_at": date_filter}
+
+    def _add_additional_filters(
+        self,
+        *,
+        filters: dict[str, Any],
+        categories: list[str] | None,
+        metadata: dict[str, Any] | None,
+        user_id: str,
+    ) -> dict[str, Any]:
+        """Augment filters with categories and metadata selections.
+
+        Args:
+            filters: Existing filter payload (mutated in place).
+            categories: Optional category list attached to the request.
+            metadata: Additional metadata equality filters.
+            user_id: User identifier for logging context.
+
+        Returns:
+            dict[str, Any]: Updated filters object.
+        """
+        if categories:
+            filters["AND"].append({"categories": {"in": categories}})
+            logger.info("%s: Added categories filter %s for user_id='%s'", self.LOG_PREFIX, categories, user_id)
+
+        if metadata:
+            filters["AND"].append({"metadata": metadata})
+            logger.info("%s: Added metadata filter %s for user_id='%s'", self.LOG_PREFIX, metadata, user_id)
+
+        return filters
+
+    def _perform_retrieval(
+        self,
+        *,
+        query: str | None,
+        user_id: str,
+        limit: int | None,
+        filters: dict[str, Any],
+        time_spec: str,
+    ) -> list[dict[str, Any]]:
+        """Execute the underlying memory retrieval call with guardrails.
+
+        Args:
+            query: Semantic query string or None for chronological listing.
+            user_id: Identifier associated with the stored memories.
+            limit: Requested number of memories to fetch.
+            filters: Filter payload produced by ``_add_additional_filters``.
+            time_spec: Human-readable time range string used for logging.
+
+        Returns:
+            list[dict[str, Any]]: Retrieved memories or empty list on failure.
+        """
+        effective_limit = max(limit or MemoryDefaults.RETRIEVAL_LIMIT, self.MINIMUM_MEMORY_RETRIEVAL)
+        if limit is not None and effective_limit != limit:
+            logger.info(
+                "%s: Enforced minimum limit of %s (requested: %s, using: %s)",
+                self.LOG_PREFIX,
+                self.MINIMUM_MEMORY_RETRIEVAL,
+                limit,
+                effective_limit,
+            )
+
+        try:
+            results = self.memory.retrieve(
+                query=query,
+                user_id=user_id,
+                limit=effective_limit,
+                filters=filters,
+            )
+
+            retrieval_mode = "semantic search" if query else "date-based recall"
+
+            logger.info(
+                "%s: %s complete for user_id='%s', query='%s', time_spec='%s', "
+                "limit=%s (effective: %s), filters=%s, results_count=%s",
+                self.LOG_PREFIX,
+                retrieval_mode.title(),
+                user_id,
+                query or "None",
+                time_spec,
+                limit,
+                effective_limit,
+                filters,
+                len(results),
+            )
+
+            return results
+
+        except Exception as exc:  # noqa: BLE001
+            logger.error("%s: Retrieval failed for user_id='%s': %s", self.LOG_PREFIX, user_id, exc)
+            return []
+
+
+Mem0SearchInput = LongTermMemorySearchInput

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

@@ -0,0 +1,48 @@
+"""Pydantic schemas shared by memory search tools.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class MemoryConfig(BaseModel):
+    """Tool configuration schema for memory operations."""
+
+    user_id: str = Field(description="User identifier for memory scoping")
+
+
+class LongTermMemorySearchInput(BaseModel):
+    """Input schema for unified long-term memory retrieval."""
+
+    query: str | None = Field(
+        None,
+        description="Optional semantic query for searching memories. If provided, performs semantic search. "
+        "If omitted, performs pure date-based recall using time filters.",
+    )
+    start_date: str | None = Field(
+        None,
+        description="Explicit start date in YYYY-MM-DD format. Used with end_date for precise date ranges. "
+        "If omitted, recall is unbounded at the start.",
+    )
+    end_date: str | None = Field(
+        None,
+        description="Explicit end date in YYYY-MM-DD format. Used with start_date for precise date ranges. "
+        "If omitted, recall is unbounded at the end.",
+    )
+    limit: int | None = Field(
+        None,
+        description="Maximum number of memories to retrieve. If not specified, uses default. "
+        "Values below 5 are automatically increased to ensure adequate context.",
+    )
+    categories: list[str] | None = Field(
+        None,
+        description="Optional categories to filter by (uses 'in' operator).",
+    )
+    metadata: dict[str, Any] | None = Field(
+        None,
+        description="Optional metadata dict to filter by (exact key-value match).",
+    )

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

@@ -0,0 +1,26 @@
+"""Backward-compatible shim for the memory search tool module.
+
+The actual implementations now live under ``aip_agents.tools.memory_search``.
+Importing from this module continues to work for existing callers.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.tools.memory_search import (
+    MEMORY_SEARCH_TOOL_NAME,
+    LongTermMemorySearchInput,
+    LongTermMemorySearchTool,
+    Mem0SearchInput,
+    Mem0SearchTool,
+    MemoryConfig,
+)
+
+__all__ = [
+    "MemoryConfig",
+    "LongTermMemorySearchInput",
+    "LongTermMemorySearchTool",
+    "Mem0SearchInput",
+    "Mem0SearchTool",
+    "MEMORY_SEARCH_TOOL_NAME",
+]

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']