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

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/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_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/time_tool.py

@@ -0,0 +1,117 @@
+"""Tool to get the current time.
+
+Authors:
+    Saul Sayers (saul.sayers@gdplabs.id)
+"""
+
+import re
+from datetime import datetime, timedelta, timezone, tzinfo
+
+from dateutil import tz
+from langchain_core.tools import BaseTool
+from pydantic import BaseModel, Field
+
+FORMAT_STRING = "%m/%d/%y %H:%M:%S"
+DEFAULT_TIMEZONE = "UTC+7"
+
+
+class TimeToolInput(BaseModel):
+    """Input schema for the TimeTool."""
+
+    datetime_format: str = Field(
+        default=FORMAT_STRING,
+        description="""
+        Optional datetime format string. Default: '%m/%d/%y %H:%M:%S'
+
+        Common format codes:
+        %Y: Year with century (2024)
+        %m: Month as number (01-12)
+        %d: Day of month (01-31)
+        %A: Full weekday name (Wednesday)
+        %a: Short weekday name (Wed)
+        %H: Hour (00-23)
+        %M: Minute (00-59)
+        %S: Second (00-59)
+        %Z: Timezone name
+        %j: Day of year (001-366)
+        %W: Week number (00-53, Monday first)
+        %U: Week number (00-53, Sunday first)
+        %c: Locale's date and time
+        %x: Locale's date
+        %X: Locale's time
+        """,
+    )
+    timezone: str | None = Field(
+        default=DEFAULT_TIMEZONE,
+        description="""
+        Optional timezone identifier. Supports IANA names (e.g., 'Asia/Jakarta')
+        or offsets (e.g., 'UTC+7', 'UTC-04:30'). Default: 'UTC+7' (Asia/Jakarta).
+        Highly recommended to be filled when getting the current time to ensure
+        the time is in the correct timezone.
+        """,
+    )
+
+
+def _parse_timezone(timezone_value: str | None) -> tzinfo | None:
+    """Return a tzinfo instance for a given timezone string.
+
+    Args:
+        timezone_value: Timezone string (e.g., "UTC+7", "UTC-5:30") or None.
+
+    Returns:
+        tzinfo instance or None if invalid/None input.
+    """
+    if timezone_value is None:
+        return None
+
+    tz_string = timezone_value.strip()
+    if not tz_string:
+        return None
+
+    offset_match = re.fullmatch(r"UTC([+-])(\d{1,2})(?::?(\d{2}))?$", tz_string.upper())
+    if offset_match:
+        sign, hours_str, minutes_str = offset_match.groups()
+        hours = int(hours_str)
+        minutes = int(minutes_str) if minutes_str else 0
+        MAX_HOURS_OFFSET = 12
+        MINUTES_OFFSETS = [0, 30, 45]
+        if hours > MAX_HOURS_OFFSET or minutes not in MINUTES_OFFSETS:
+            raise ValueError(f"Invalid timezone offset: {timezone_value}")
+        delta = timedelta(hours=hours, minutes=minutes)
+        if sign == "-":
+            delta = -delta
+        return timezone(delta)
+
+    tzinfo = tz.gettz(tz_string)
+    if tzinfo is not None:
+        return tzinfo
+
+    raise ValueError(f"Unknown timezone: {timezone_value}")
+
+
+class TimeTool(BaseTool):
+    """Tool to get the current time."""
+
+    name: str = "time_tool"
+    description: str = """
+    Useful for getting the current time in a specified format and timezone.
+    Default format: '%m/%d/%y %H:%M:%S' (e.g., '05/15/24 17:30:00')
+
+    Supports timezone specification to get the current time in any timezone.
+    It is highly recommended to specify a timezone to ensure accurate results.
+    """
+    args_schema: type[BaseModel] = TimeToolInput
+
+    def _run(self, datetime_format: str = FORMAT_STRING, timezone: str | None = DEFAULT_TIMEZONE) -> str:
+        """Get current time formatted according to the specified format and timezone.
+
+        Args:
+            datetime_format: Format string for datetime (default: ISO format).
+            timezone: Timezone string (default: UTC).
+
+        Returns:
+            Formatted datetime string.
+        """
+        tzinfo = _parse_timezone(timezone)
+        current_time = datetime.now(tz=tzinfo)
+        return current_time.strftime(datetime_format)