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

aip_agents/memory/adapters/mem0.py

@@ -0,0 +1,286 @@
+"""Mem0-specific adapter built on top of the BaseMemoryAdapter.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from typing import Any
+
+from aip_agents.memory.adapters.base_adapter import DEFAULT_SCOPE, BaseMemoryAdapter, _RetrieveOptions
+from aip_agents.memory.constants import MemoryDefaults
+
+logger = logging.getLogger(__name__)
+
+# The hosted search API does not support pagination (only top_k). When
+# cross-agent noise fills the top N slots, client-side filtering may return
+# fewer results than requested. Use a generous window to reduce this risk.
+# TODO: replace with paginated search when the backend supports it.
+_HOSTED_SEARCH_WINDOW = 100
+
+try:
+    from gllm_memory import MemoryManager
+
+    _HAS_GLLM_MEMORY = True
+except ImportError:  # pragma: no cover
+    MemoryManager = Any  # type: ignore[assignment]
+    _HAS_GLLM_MEMORY = False
+
+
+class Mem0Memory(BaseMemoryAdapter):
+    """Mem0-backed long-term memory adapter using the gllm_memory SDK."""
+
+    def __init__(
+        self,
+        *,
+        agent_id: str,
+        namespace: str | None = None,
+        limit: int = MemoryDefaults.RETRIEVAL_LIMIT,
+        max_chars: int = MemoryDefaults.MAX_CHARS,
+        host: str | None = None,
+        instruction: str | None = None,
+    ) -> None:
+        """Initialize the Mem0 memory adapter.
+
+        Args:
+            agent_id: Unique identifier for the agent using this memory.
+            namespace: Optional namespace for organizing memories.
+            limit: Maximum number of memories to retrieve in search operations.
+            max_chars: Maximum character length for text content.
+            host: Optional host URL for the Mem0 service.
+            instruction: Optional instruction text for memory operations.
+        """
+        if not _HAS_GLLM_MEMORY:
+            raise ImportError("optional dependency 'gllm-memory' is required for Mem0Memory")
+
+        resolved_host = host or os.getenv("MEM0_HOST") or os.getenv("GLLM_MEMORY_HOST")
+        resolved_api_key = self._resolve_api_key()
+        self._uses_hosted_backend = bool(resolved_host or resolved_api_key)
+        manager = self._initialize_manager(host=resolved_host, instruction=instruction, api_key=resolved_api_key)
+        super().__init__(
+            agent_id=agent_id,
+            manager=manager,
+            namespace=namespace,
+            limit=limit,
+            max_chars=max_chars,
+        )
+
+    @classmethod
+    def validate_env(cls) -> None:
+        """Ensure the Mem0 API key or host is available."""
+        host = os.getenv("MEM0_HOST") or os.getenv("GLLM_MEMORY_HOST")
+        if host:
+            return  # Host is sufficient
+        api_key = os.getenv("MEM0_API_KEY") or os.getenv("GLLM_MEMORY_API_KEY")
+        if not api_key:
+            raise ValueError(
+                "Either MEM0_HOST (or GLLM_MEMORY_HOST) or "
+                "MEM0_API_KEY (or GLLM_MEMORY_API_KEY) must be configured for Mem0 access."
+            )
+
+    @staticmethod
+    def _resolve_api_key() -> str | None:
+        """Resolve the Mem0 API key from environment.
+
+        Returns:
+            The API key if set, or None if only host-based auth is used.
+        """
+        return os.getenv("MEM0_API_KEY") or os.getenv("GLLM_MEMORY_API_KEY") or None
+
+    def _initialize_manager(
+        self, host: str | None, instruction: str | None, api_key: str | None = None
+    ) -> MemoryManager:
+        """Create a MemoryManager tailored for the Mem0 backend.
+
+        Args:
+            host: Optional host URL for the Mem0 service.
+            instruction: Optional instruction text for memory operations.
+            api_key: Optional pre-resolved API key; re-reads env if not provided.
+
+        Returns:
+            Configured MemoryManager instance for Mem0.
+        """
+        resolved_host = host or os.getenv("MEM0_HOST") or os.getenv("GLLM_MEMORY_HOST")
+        resolved_instruction = instruction or os.getenv("GLLM_MEMORY_INSTRUCTION")
+        resolved_api_key = api_key if api_key is not None else (self._resolve_api_key() or "")
+        if not resolved_host and not resolved_api_key:
+            raise ValueError(  # pragma: no cover
+                "Either MEM0_HOST (or GLLM_MEMORY_HOST) or "
+                "MEM0_API_KEY (or GLLM_MEMORY_API_KEY) must be configured for Mem0 access."
+            )
+        return MemoryManager(
+            api_key=resolved_api_key,
+            host=resolved_host,
+            instruction=resolved_instruction,
+        )
+
+    def _create_retrieve_task(self, query: str | None, options: _RetrieveOptions) -> Any:
+        if not self._uses_hosted_backend:
+            return super()._create_retrieve_task(query, options)  # pragma: no cover
+
+        if query:
+            # Use a generous search window — cross-agent noise can otherwise
+            # exhaust top_k before we find enough matching chunks to return.
+            window = max(_HOSTED_SEARCH_WINDOW, options.top_k)
+            task = self._manager.search(
+                query=query,
+                user_id=options.user_id,
+                agent_id=None,
+                scopes=DEFAULT_SCOPE,
+                metadata=None,
+                top_k=window,
+            )
+        else:
+            task = self._manager.list_memories(
+                user_id=options.user_id,
+                agent_id=None,
+                scopes=DEFAULT_SCOPE,
+                metadata=None,
+                keywords=options.keywords,
+                page=options.page,
+                page_size=options.top_k,
+            )
+        return self._filter_hosted_scope(task, limit=options.top_k if query else None)
+
+    def delete_by_query(
+        self,
+        *,
+        query: str,
+        user_id: str,
+        top_k: int | None = None,
+        threshold: float | None = 0.3,
+        filters: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Delete hosted mem0 memories by user-scoped search when metadata filters are unsupported."""
+        options = self._build_retrieve_options(user_id=user_id, limit=top_k, filters=filters, page=None)
+        if not self._uses_hosted_backend:
+            return super().delete_by_query(  # pragma: no cover
+                query=query,
+                user_id=user_id,
+                top_k=top_k,
+                threshold=threshold,
+                filters=filters,
+            )
+
+        try:
+            # Use a larger search window to reduce the chance that cross-agent
+            # noise exhausts top_k before we find all matching memories.
+            window = max(_HOSTED_SEARCH_WINDOW, options.top_k)
+            chunks = self._runner.run(
+                self._filter_hosted_scope(
+                    self._manager.search(
+                        query=query,
+                        user_id=options.user_id,
+                        agent_id=None,
+                        scopes=DEFAULT_SCOPE,
+                        metadata=None,
+                        threshold=threshold,
+                        top_k=window,
+                    ),
+                    limit=options.top_k,
+                )
+            )
+            memory_ids = [str(chunk.id) for chunk in chunks if getattr(chunk, "id", None)]
+            if not memory_ids:
+                return []
+            # Deletion by IDs is deterministic (no search window issue).
+            deleted = self._delete_hosted_memory_ids(memory_ids=memory_ids, user_id=options.user_id)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Mem0Memory.delete_by_query hosted path error: %s", exc)
+            return []
+
+        return [self._chunk_to_hit(chunk) for chunk in deleted]
+
+    def delete(
+        self,
+        *,
+        memory_ids: list[str] | None,
+        user_id: str,
+        metadata: dict[str, Any] | None = None,
+        categories: list[str] | None = None,
+    ) -> Any:
+        """Delete hosted mem0 memories while avoiding unsupported metadata filters.
+
+        The hosted backend's agent_id/metadata filtering is broken, so the
+        clear-all path always uses the hosted workaround (list+filter locally)
+        regardless of metadata/categories — those filters are best-effort and
+        applied server-side only when routing through super().
+        """
+        if memory_ids is not None or not self._uses_hosted_backend:
+            return super().delete(memory_ids=memory_ids, user_id=user_id, metadata=metadata, categories=categories)
+
+        effective_user = user_id or self.agent_id or MemoryDefaults.DEFAULT_USER_ID
+        try:
+            scoped_ids: list[str] = []
+            page = 1
+            page_size = 100
+            while True:
+                chunks = self._runner.run(
+                    self._manager.list_memories(
+                        user_id=effective_user,
+                        agent_id=None,
+                        scopes=DEFAULT_SCOPE,
+                        metadata=None,
+                        page=page,
+                        page_size=page_size,
+                    )
+                )
+                scoped_ids.extend(
+                    str(chunk.id)
+                    for chunk in chunks
+                    if getattr(chunk, "id", None) and self._hosted_chunk_matches_scope(chunk)
+                )
+                if len(chunks) < page_size:
+                    break
+                page += 1
+            if not scoped_ids:
+                return []
+            return self._delete_hosted_memory_ids(memory_ids=scoped_ids, user_id=effective_user)
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("Mem0Memory.delete hosted path error: %s", exc)
+            return []
+
+    def _delete_hosted_memory_ids(self, *, memory_ids: list[str], user_id: str) -> Any:
+        deleted = self._runner.run(
+            self._manager.delete(
+                memory_ids=memory_ids,
+                user_id=user_id,
+                agent_id=self.agent_id,
+                scopes=DEFAULT_SCOPE,
+                metadata=None,
+            )
+        )
+        if deleted:
+            return deleted
+        return self._runner.run(
+            self._manager.delete(
+                memory_ids=memory_ids,
+                user_id=user_id,
+                agent_id=None,
+                scopes=DEFAULT_SCOPE,
+                metadata=None,
+            )
+        )
+
+    async def _filter_hosted_scope(self, task: Any, limit: int | None = None) -> list[Any]:
+        chunks = await task
+        scoped = [chunk for chunk in chunks if self._hosted_chunk_matches_scope(chunk)]
+        return scoped[:limit] if limit is not None else scoped
+
+    def _hosted_chunk_matches_scope(self, chunk: Any) -> bool:
+        """Return True when the chunk belongs to this adapter's scope.
+
+        When the chunk has no target/agent_id metadata, always reject —
+        self.agent_id is never None/empty (coerced to DEFAULT_USER_ID in
+        BaseMemoryAdapter.__init__), so the previously-documented "unscoped
+        mode" was unreachable dead code. When the chunk has a target, it
+        must match this adapter's agent_id exactly.
+        """
+        metadata = dict(getattr(chunk, "metadata", {}) or {})
+        target = metadata.get("target") or metadata.get("agent_id")
+        if target in (None, ""):
+            return False
+        return target == self.agent_id

aip_agents/memory/base.py

@@ -0,0 +1,84 @@
+"""Base Memory Module for AIP Agents.
+
+This module defines the BaseMemory class which serves as a template
+for implementing different types of memory for agents.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+
+References:
+    https://github.com/GDP-ADMIN/gdplabs-exploration/blob/ai-agent-app/backend/aip_agents/memory/base.py
+"""
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Any
+
+from aip_agents.types import ChatMessage
+
+
+class BaseMemory(ABC):
+    """Base class for agent memory.
+
+    This concrete base class provides a default structure. Subclasses
+    can inherit from this class to implement specific memory management
+    behaviors.
+    """
+
+    @classmethod
+    def validate_env(cls) -> None:  # pragma: no cover - default no-op
+        """Validate environment prerequisites for a memory backend.
+
+        This hook allows memory implementations to fail fast when required
+        environment variables or credentials are missing. Default is a no-op.
+        """
+        return None
+
+    @abstractmethod
+    def get_messages(self) -> list[ChatMessage]:
+        """Retrieve a list of messages.
+
+        Returns:
+            List[ChatMessage]: A list of messages in a generic format.
+        """
+
+    @abstractmethod
+    def add_message(self, message: ChatMessage) -> None:
+        """Add a message to the memory.
+
+        Adds a single ChatMessage to the memory storage. The exact implementation
+        depends on the specific memory backend.
+
+        Args:
+            message: The ChatMessage object to add to memory. The message should
+                contain role and content information.
+        """
+
+    def add_messages(self, messages: Sequence[ChatMessage]) -> None:
+        """Add multiple messages to the memory.
+
+        Args:
+            messages: A sequence of ChatMessage objects to add.
+        """
+        for message in messages:
+            self.add_message(message)
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clears the memory or resets the state of the agent.
+
+        This method must be implemented to define the specific behavior
+        for clearing or resetting the memory of the agent.
+        """
+
+    def get_memory_variables(self) -> dict[str, Any]:
+        """Retrieve memory variables.
+
+        This method returns a dictionary containing memory-related variables.
+        The default implementation returns a dictionary with chat_history.
+
+        Returns:
+            Dict[str, Any]: A dictionary where keys are variable names and values
+            are the corresponding memory-related data.
+        """
+        return {"chat_history": self.get_messages()}

aip_agents/memory/constants.py

@@ -0,0 +1,49 @@
+"""Memory constants for AIP Agents.
+
+This module defines constants for memory-related method names and other
+memory-related constants to avoid magic strings and numbers throughout the codebase.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+
+class MemoryMethod:
+    """Constants for memory method names used in hasattr checks."""
+
+    SEARCH = "search"
+    SAVE_INTERACTION = "save_interaction"
+    FORMAT_HITS = "format_hits"
+
+
+class MemoryDefaults:
+    """Default values for memory configuration parameters."""
+
+    # Memory retrieval and formatting limits
+    MAX_ITEMS = 8  # Maximum number of memory items to include in formatted output
+    RETRIEVAL_LIMIT = 5  # Default number of memories to retrieve per search
+    MAX_CHARS = 1500  # Maximum characters per memory entry when saving
+
+    # Logging and display
+    LOG_PREVIEW_LENGTH = 100  # Length of text preview in logs
+    SMALL_PREVIEW_LENGTH = 16  # Length of text preview in logs
+
+    # Agent ID generation
+    AGENT_ID_PREFIX = "agent-"  # Prefix for generated agent IDs
+
+    # Memory formatting
+    MEMORY_TAG_OPEN = "<RELEVANT_MEMORY>"
+    MEMORY_TAG_CLOSE = "</RELEVANT_MEMORY>"
+
+    # Default user ID for compatibility
+    DEFAULT_USER_ID = "default"
+
+    # Date format constants
+    DATE_STRING_LENGTH = 10  # Length of "YYYY-MM-DD" format strings
+
+
+class MemoryBackends:
+    """Supported memory backend identifiers."""
+
+    MEM0 = "mem0"
+    SUPPORTED = frozenset({MEM0})

aip_agents/memory/factory.py

@@ -0,0 +1,86 @@
+"""Memory factory for creating memory adapters by backend string.
+
+This module provides a single point of construction for memory backends,
+so agent code does not depend on concrete memory implementations.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+import importlib
+from typing import Any
+
+from aip_agents.memory.base import BaseMemory
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+BACKENDS = {
+    # backend_name: "module_path:ClassName"
+    "mem0": "aip_agents.memory.adapters.mem0:Mem0Memory",
+}
+
+
+def _import_class(path: str) -> type[BaseMemory]:
+    """Import a memory class from a module path string.
+
+    Dynamically imports a memory implementation class from a string path in
+    the format "module_path:ClassName".
+
+    Args:
+        path: A string in the format "module_path:ClassName" specifying the
+            module and class to import.
+
+    Returns:
+        type[BaseMemory]: The imported memory class that implements the
+            BaseMemory interface.
+
+    Raises:
+        ModuleNotFoundError: If the specified module cannot be imported.
+        AttributeError: If the specified class does not exist in the module.
+        ValueError: If the path format is invalid (does not contain ':').
+    """
+    module_path, class_name = path.split(":", 1)
+    module = importlib.import_module(module_path)
+    memory_cls = getattr(module, class_name)
+    return memory_cls
+
+
+class MemoryFactory:
+    """Factory to build concrete memory adapters by backend name."""
+
+    @staticmethod
+    def create(backend: str, **kwargs: Any) -> BaseMemory:
+        """Create a memory adapter instance.
+
+        Args:
+            backend: Backend identifier (e.g., "mem0").
+            **kwargs: Keyword args passed to adapter constructor (e.g., limit, max_chars, namespace).
+
+        Returns:
+            BaseMemory: A constructed memory adapter instance.
+
+        Raises:
+            ValueError: If backend is unknown or adapter can't be constructed.
+        """
+        if backend not in BACKENDS:
+            raise ValueError(f"Unknown memory backend: {backend}")
+
+        cls_path = BACKENDS[backend]
+        memory_cls = _import_class(cls_path)
+
+        # Validate environment (adapter may raise)
+        try:
+            if hasattr(memory_cls, "validate_env"):
+                memory_cls.validate_env()  # type: ignore[misc]
+        except Exception as e:  # noqa: BLE001
+            logger.error(f"MemoryFactory: environment validation failed for '{backend}': {e}")
+            raise
+
+        try:
+            instance = memory_cls(**kwargs)
+            return instance
+        except Exception as e:  # noqa: BLE001
+            logger.error(f"MemoryFactory: failed to create memory adapter '{backend}': {e}")
+            raise

aip_agents/memory/guidance.py

@@ -0,0 +1,20 @@
+"""Guidance text helpers for Mem0-based memory recall.
+
+Authors:
+    - Putu Ravindra Wiguna (putu.r.wiguna@gdplabs.id)
+"""
+
+import textwrap
+
+MEM0_MEMORY_RECALL_GUIDANCE = textwrap.dedent("""
+    Memory Recall Guidance:
+    - Use `built_in_mem0_search` whenever you need facts from long-term memory.
+    - You can also use `built_in_mem0_search` for explicit recall or recap requests of
+      conversation/chat/discussion by the user.
+      Reach for it when prior context such as but not limited to: names, decisions, or
+      preferences, will help you respond.
+      It is also appropriate when the user asks about the AI's previous responses.
+    - Provide a concise `query` that describes what you are looking for (e.g., 'project plan', 'user preferences').
+    - If the user specifies a time period for a memory, set `time_period` according to user query
+      to retrieve memories based on that time period.
+    """).strip()

aip_agents/memory/simple_memory.py

@@ -0,0 +1,47 @@
+"""Simple Memory Module for AIP Agents.
+
+This module provides a basic implementation of the BaseMemory class
+that stores messages in a simple list structure.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from aip_agents.memory.base import BaseMemory, ChatMessage
+
+
+class SimpleMemory(BaseMemory):
+    """A simple memory implementation that stores messages in a list."""
+
+    def __init__(self):
+        """Initialize the SimpleMemory instance with an empty message list."""
+        self.messages: list[ChatMessage] = []
+
+    def add_message(self, message_or_role: ChatMessage | str, content: str | None = None) -> None:
+        """Add a message to memory.
+
+        Supports two calling patterns for backward compatibility:
+        1. add_message(ChatMessage) - Adds a ChatMessage object directly
+        2. add_message(role, content) - Creates and adds a ChatMessage with the given role and content
+
+        Args:
+            message_or_role: Either a ChatMessage object or a string role (e.g., "user", "assistant").
+            content: Optional content string when using the role+content pattern.
+                Required when message_or_role is a string role.
+        """
+        if content is not None:
+            # Using the role+content pattern
+            self.messages.append(ChatMessage(role=message_or_role, content=content))
+        else:
+            # Using the ChatMessage object pattern
+            self.messages.append(message_or_role)
+
+    def get_messages(self) -> list[ChatMessage]:
+        """Get all messages from memory."""
+        return self.messages
+
+    def clear(self) -> None:
+        """Clear all messages from memory."""
+        self.messages = []
+
+    # Uses the default get_memory_variables implementation from BaseMemory

aip_agents/middleware/__init__.py

@@ -0,0 +1,65 @@
+"""Middleware package.
+
+Provides composable middleware components for enhancing agent capabilities with
+planning, file storage, memory, and custom lifecycle hooks.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from aip_agents.middleware.base import AgentMiddleware, ModelRequest
+from aip_agents.middleware.filesystem import FilesystemMiddleware
+from aip_agents.middleware.manager import MiddlewareManager
+from aip_agents.middleware.memory import MemoryMiddleware
+from aip_agents.middleware.pii_middleware import PIIMiddleware
+from aip_agents.middleware.task_delegation import TaskDelegationConfig, TaskDelegationMiddleware
+from aip_agents.middleware.todolist import TodoListMiddleware, TodoStatus
+from aip_agents.middleware.vision import VisionMiddleware
+
+if TYPE_CHECKING:
+    from aip_agents.middleware.skills import SkillsMiddleware
+
+__all__ = [
+    "AgentMiddleware",
+    "FilesystemMiddleware",
+    "ModelRequest",
+    "MiddlewareManager",
+    "MemoryMiddleware",
+    "PIIMiddleware",
+    "TaskDelegationConfig",
+    "TaskDelegationMiddleware",
+    "TodoListMiddleware",
+    "TodoStatus",
+    "SkillsMiddleware",
+    "VisionMiddleware",
+]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazy import middleware modules to avoid eager optional dependencies.
+
+    Args:
+        name (str): Attribute name requested from this module.
+
+    Returns:
+        Any: The requested attribute.
+
+    Raises:
+        AttributeError: If the attribute is not defined.
+    """
+    if name == "SkillsMiddleware":
+        from aip_agents.middleware.skills import SkillsMiddleware as SkillsMiddlewareType
+
+        return SkillsMiddlewareType
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Return module attributes for dir().
+
+    Returns:
+        list[str]: Sorted list of public attributes.
+    """
+    return sorted(__all__)