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

aip_agents/memory/adapters/base_adapter.pyi

@@ -0,0 +1,176 @@
+from _typeshed import Incomplete
+from aip_agents.memory.base import BaseMemory as BaseMemory
+from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
+from aip_agents.types import ChatMessage as ChatMessage
+from aip_agents.utils.datetime import format_created_updated_label as format_created_updated_label
+from aip_agents.utils.logger import get_logger as get_logger
+from concurrent.futures import Future
+from dataclasses import dataclass
+from gllm_memory import MemoryManager
+from gllm_memory.enums import MemoryScope
+from typing import Any, ClassVar
+
+MemoryManager = Any
+MemoryScope = Any
+logger: Incomplete
+DEFAULT_SCOPE: ClassVar[set[MemoryScope]]
+
+@dataclass(frozen=True)
+class _RetrieveOptions:
+    user_id: str
+    top_k: int
+    metadata: dict[str, str] | None
+    keywords: Any
+    page: int
+    categories: list[str] | None
+
+class _AsyncRunner:
+    """Runs async coroutines on a dedicated background event loop."""
+    def __init__(self) -> None: ...
+    def run(self, awaitable: Any) -> Any:
+        """Execute an awaitable on the background loop and block for the result.
+
+        Args:
+            awaitable: The coroutine to execute.
+
+        Returns:
+            The result of the coroutine execution.
+        """
+    def shutdown(self, timeout: float | None = 5.0) -> None:
+        """Gracefully stop the event loop thread.
+
+        Args:
+            timeout: Maximum time to wait for the thread to stop.
+        """
+    def __del__(self) -> None: ...
+
+class BaseMemoryAdapter(BaseMemory):
+    """Provider-agnostic long-term memory adapter backed by gllm_memory."""
+    agent_id: Incomplete
+    namespace: Incomplete
+    limit: Incomplete
+    max_chars: Incomplete
+    def __init__(self, *, agent_id: str, manager: MemoryManager, namespace: str | None = None, limit: int = ..., max_chars: int = ...) -> None:
+        """Initialize the GLLM memory adapter.
+
+        Args:
+            agent_id: Unique identifier for the agent using this memory.
+            manager: Configured gllm_memory MemoryManager instance.
+            namespace: Optional namespace for organizing memories.
+            limit: Maximum number of memories to retrieve in search operations.
+            max_chars: Maximum character length for text content.
+        """
+    @classmethod
+    def validate_env(cls) -> None:
+        """Base adapter does not enforce environment validation."""
+    def get_messages(self) -> list[ChatMessage]:
+        """Retrieve all stored chat messages.
+
+        Returns:
+            An empty list as GLLM adapter doesn't support message retrieval.
+        """
+    def add_message(self, message: ChatMessage) -> None:
+        """Best-effort single-message persistence for API parity.
+
+        Args:
+            message: The chat message to add to memory.
+        """
+    def clear(self) -> None:
+        """Clear all stored memories.
+
+        Raises:
+            NotImplementedError: This method is not implemented for GLLM adapter.
+        """
+    def search(self, query: str, *, user_id: str, limit: int | None = None, filters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+        """Search for memories using a text query.
+
+        Args:
+            query: The search query string.
+            user_id: User identifier for the search scope.
+            limit: Maximum number of results to return.
+            filters: Optional filters to apply to the search.
+
+        Returns:
+            List of memory hits matching the search criteria.
+        """
+    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 with optional search query and filters.
+
+        Args:
+            query: Optional search query string. If None, retrieves all memories.
+            user_id: User identifier for the retrieval scope.
+            limit: Maximum number of results to return.
+            filters: Optional filters to apply to the retrieval.
+            page: Page number for pagination.
+
+        Returns:
+            List of memory hits matching the criteria.
+        """
+    def delete_by_query(self, *, query: str, user_id: str, metadata: dict[str, Any] | None = None, threshold: float | None = None, top_k: int | None = None, categories: list[str] | None = None) -> Any:
+        """Delete memories by semantic query.
+
+        Args:
+            query: Semantic query describing memories to delete.
+            user_id: User identifier for the deletion scope.
+            metadata: Optional metadata filters to constrain deletion.
+            threshold: Optional semantic threshold (if supported by backend).
+            top_k: Optional max number of memories to delete by query.
+            categories: Optional categories to filter by (best-effort).
+
+        Returns:
+            Backend-specific delete result or None on failure.
+        """
+    def delete(self, *, memory_ids: list[str] | None, user_id: str, metadata: dict[str, Any] | None = None, categories: list[str] | None = None) -> Any:
+        """Delete memories by IDs or by user scope when IDs are None.
+
+        Args:
+            memory_ids: Optional list of memory IDs to delete.
+            user_id: User identifier for the deletion scope.
+            metadata: Optional metadata filters to constrain deletion.
+            categories: Optional categories to filter by (best-effort).
+
+        Returns:
+            Backend-specific delete result or None on failure.
+        """
+    def save_interaction(self, *, user_text: str, ai_text: str, user_id: str) -> None:
+        """Save a user-AI interaction as memories.
+
+        Args:
+            user_text: The user's input text.
+            ai_text: The AI's response text.
+            user_id: User identifier for the memory storage.
+        """
+    def save_interaction_async(self, *, user_text: str, ai_text: str, user_id: str) -> Future[Any]:
+        """Schedule save_interaction without blocking the caller.
+
+        Args:
+            user_text: The user's input text to save.
+            ai_text: The AI's response text to save.
+            user_id: User identifier for the memory storage.
+        """
+    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 the output.
+            with_tag: Whether to wrap the output with memory tags.
+
+        Returns:
+            Formatted string representation of the memory hits.
+        """
+    def flush_pending_writes(self, timeout: float | None = None) -> None:
+        """Block until current async writes complete.
+
+        Args:
+            timeout: Maximum time to wait for pending writes to complete.
+        """
+    def close(self, *, wait: bool = True, timeout: float | None = None) -> None:
+        """Release background resources and optionally wait for pending saves.
+
+        Args:
+            wait: Whether to wait for pending async operations to complete.
+            timeout: Maximum time to wait when wait=True.
+        """
+    def __del__(self) -> None:
+        """Clean up resources when the adapter is garbage collected."""

aip_agents/memory/adapters/mem0.py

@@ -0,0 +1,84 @@
+"""Mem0-specific adapter built on top of the BaseMemoryAdapter.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+try:
+    from gllm_memory import MemoryManager
+
+    _HAS_GLLM_MEMORY = True
+except ImportError:  # pragma: no cover
+    MemoryManager = Any  # type: ignore[assignment]
+    _HAS_GLLM_MEMORY = False
+
+from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter
+from aip_agents.memory.constants import MemoryDefaults
+
+
+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")
+
+        manager = self._initialize_manager(host=host, instruction=instruction)
+        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 is available."""
+        cls._resolve_api_key()
+
+    @staticmethod
+    def _resolve_api_key() -> str:
+        api_key = os.getenv("MEM0_API_KEY") or os.getenv("GLLM_MEMORY_API_KEY")
+        if not api_key:
+            raise ValueError("MEM0_API_KEY (or GLLM_MEMORY_API_KEY) must be configured for Mem0 access.")
+        return api_key
+
+    def _initialize_manager(self, host: str | None, instruction: str | 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.
+
+        Returns:
+            Configured MemoryManager instance for Mem0.
+        """
+        api_key = self._resolve_api_key()
+        resolved_host = host or os.getenv("MEM0_HOST") or os.getenv("GLLM_MEMORY_HOST")
+        resolved_instruction = instruction or os.getenv("GLLM_MEMORY_INSTRUCTION")
+        return MemoryManager(api_key=api_key, host=resolved_host, instruction=resolved_instruction)

aip_agents/memory/adapters/mem0.pyi

@@ -0,0 +1,22 @@
+from aip_agents.memory.adapters.base_adapter import BaseMemoryAdapter as BaseMemoryAdapter
+from aip_agents.memory.constants import MemoryDefaults as MemoryDefaults
+from typing import Any
+
+MemoryManager = Any
+
+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 = ..., max_chars: int = ..., 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.
+        """
+    @classmethod
+    def validate_env(cls) -> None:
+        """Ensure the Mem0 API key is available."""

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/base.pyi

@@ -0,0 +1,60 @@
+from abc import ABC, abstractmethod
+from aip_agents.types import ChatMessage as ChatMessage
+from collections.abc import Sequence
+from typing import Any
+
+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:
+        """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.
+        """
+    @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.
+        """
+    @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.
+        """

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/constants.pyi

@@ -0,0 +1,25 @@
+from _typeshed import Incomplete
+
+class MemoryMethod:
+    """Constants for memory method names used in hasattr checks."""
+    SEARCH: str
+    SAVE_INTERACTION: str
+    FORMAT_HITS: str
+
+class MemoryDefaults:
+    """Default values for memory configuration parameters."""
+    MAX_ITEMS: int
+    RETRIEVAL_LIMIT: int
+    MAX_CHARS: int
+    LOG_PREVIEW_LENGTH: int
+    SMALL_PREVIEW_LENGTH: int
+    AGENT_ID_PREFIX: str
+    MEMORY_TAG_OPEN: str
+    MEMORY_TAG_CLOSE: str
+    DEFAULT_USER_ID: str
+    DATE_STRING_LENGTH: int
+
+class MemoryBackends:
+    """Supported memory backend identifiers."""
+    MEM0: str
+    SUPPORTED: Incomplete

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/factory.pyi

@@ -0,0 +1,24 @@
+from _typeshed import Incomplete
+from aip_agents.memory.base import BaseMemory as BaseMemory
+from aip_agents.utils.logger import get_logger as get_logger
+from typing import Any
+
+logger: Incomplete
+BACKENDS: Incomplete
+
+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.
+        '''

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/guidance.pyi

@@ -0,0 +1,3 @@
+from _typeshed import Incomplete
+
+MEM0_MEMORY_RECALL_GUIDANCE: Incomplete