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

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/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, content=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,17 @@
+"""Planning Middleware package.
+
+Provides composable middleware components for enhancing agent capabilities with
+planning and custom lifecycle hooks.
+"""
+
+from aip_agents.middleware.base import AgentMiddleware, ModelRequest
+from aip_agents.middleware.manager import MiddlewareManager
+from aip_agents.middleware.todolist import TodoListMiddleware, TodoStatus
+
+__all__ = [
+    "AgentMiddleware",
+    "ModelRequest",
+    "MiddlewareManager",
+    "TodoListMiddleware",
+    "TodoStatus",
+]

aip_agents/middleware/base.py

@@ -0,0 +1,88 @@
+"""Base protocol and types for agent middleware.
+
+This module defines the core AgentMiddleware protocol that all middleware components
+must implement, along with the ModelRequest type for model invocations.
+"""
+
+from typing import Any, Protocol, TypedDict
+
+from langchain_core.tools import BaseTool
+
+
+class ModelRequest(TypedDict, total=False):
+    """Represents parameters for a model invocation that middleware can modify.
+
+    This TypedDict defines the structure of requests passed to the LLM, allowing
+    middleware to add tools or modify prompts before each invocation.
+
+    Attributes:
+        messages: List of messages in the conversation.
+        tools: List of tools available to the model.
+        system_prompt: System-level instruction for the model.
+    """
+
+    messages: list[Any]
+    tools: list[BaseTool]
+    system_prompt: str
+
+
+class AgentMiddleware(Protocol):
+    """Protocol defining the interface for composable agent middleware.
+
+    Middleware components can contribute tools, enhance system prompts, and provide
+    lifecycle hooks that execute before, during, and after model invocations.
+
+    All middleware must implement this protocol to be compatible with MiddlewareManager.
+
+    Attributes:
+        tools: List of tools contributed by this middleware.
+        system_prompt_additions: Optional text to append to the agent's system prompt.
+    """
+
+    tools: list[BaseTool]
+    system_prompt_additions: str | None
+
+    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Hook executed before each model invocation.
+
+        Use this hook to prepare state, log context, or perform setup tasks
+        before the model is called.
+
+        Args:
+            state: Current agent state containing messages and other context.
+
+        Returns:
+            Dict of state updates to merge into the agent state. Return empty dict
+            if no updates are needed.
+        """
+        return {}  # pragma: no cover  # Protocol default - cannot be executed directly
+
+    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
+        """Hook to modify the model request before invocation.
+
+        Use this hook to add tools, modify the system prompt, adjust model parameters,
+        or change tool selection strategy.
+
+        Args:
+            request: The model request that will be sent to the LLM.
+            state: Current agent state for context.
+
+        Returns:
+            Modified ModelRequest. Can return the same request if no changes needed.
+        """
+        return request  # pragma: no cover  # Protocol default - cannot be executed directly  # pragma: no cover  # Protocol default - cannot be executed directly
+
+    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Hook executed after each model invocation.
+
+        Use this hook for cleanup, logging, state updates, or post-processing
+        of model outputs.
+
+        Args:
+            state: Current agent state after model invocation.
+
+        Returns:
+            Dict of state updates to merge into the agent state. Return empty dict
+            if no updates are needed.
+        """
+        return {}  # pragma: no cover  # Protocol default - cannot be executed directly

aip_agents/middleware/manager.py

@@ -0,0 +1,128 @@
+"""Middleware orchestration and lifecycle management.
+
+This module provides MiddlewareManager, which coordinates multiple middleware
+components and manages their lifecycle hooks.
+"""
+
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+from aip_agents.middleware.base import AgentMiddleware, ModelRequest
+
+
+class MiddlewareManager:
+    """Orchestrates multiple middleware components and manages hook execution.
+
+    The manager collects tools from all middleware, builds enhanced system prompts,
+    and executes lifecycle hooks in the correct order (forward for setup, reverse
+    for cleanup).
+
+    Attributes:
+        middleware: List of middleware components in registration order.
+    """
+
+    def __init__(self, middleware: list[AgentMiddleware]) -> None:
+        """Initialize the middleware manager.
+
+        Args:
+            middleware: List of middleware components to manage. Order matters:
+                       hooks execute forward (first to last) for before/modify,
+                       and reverse (last to first) for after.
+        """
+        self.middleware = middleware
+
+    def get_all_tools(self) -> list[BaseTool]:
+        """Collect tools from all registered middleware.
+
+        Returns:
+            Combined list of all tools contributed by all middleware components.
+            Empty list if no middleware or if middleware provide no tools.
+        """
+        tools: list[BaseTool] = []
+        for mw in self.middleware:
+            tools.extend(mw.tools)
+        return tools
+
+    def build_system_prompt(self, base_instruction: str) -> str:
+        """Build enhanced system prompt by concatenating base instruction with middleware additions.
+
+        Args:
+            base_instruction: The base system prompt for the agent.
+
+        Returns:
+            Enhanced system prompt with all middleware additions appended.
+            If no middleware provide additions, returns base_instruction unchanged.
+        """
+        parts = [base_instruction]
+
+        for mw in self.middleware:
+            if mw.system_prompt_additions:
+                parts.append(mw.system_prompt_additions)
+
+        return "\n\n".join(parts)
+
+    def before_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Execute before_model hooks for all middleware in forward order.
+
+        Hooks run first to last, allowing earlier middleware to prepare state
+        for later middleware.
+
+        Args:
+            state: Current agent state.
+
+        Returns:
+            Merged dictionary of all state updates from all middleware.
+            Updates are accumulated in order of execution.
+        """
+        state_updates: dict[str, Any] = {}
+
+        for mw in self.middleware:
+            mw_updates = mw.before_model(state)
+            if mw_updates:
+                state_updates.update(mw_updates)
+
+        return state_updates
+
+    def modify_model_request(self, request: ModelRequest, state: dict[str, Any]) -> ModelRequest:
+        """Execute modify_model_request hooks for all middleware in forward order.
+
+        Each middleware receives the request modified by previous middleware,
+        allowing them to build on each other's changes.
+
+        Args:
+            request: The model request to be modified.
+            state: Current agent state for context.
+
+        Returns:
+            Final modified request after all middleware have processed it.
+        """
+        current_request = request
+
+        for mw in self.middleware:
+            current_request = mw.modify_model_request(current_request, state)
+
+        return current_request
+
+    def after_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Execute after_model hooks for all middleware in reverse order.
+
+        Hooks run last to first (reverse of registration order), allowing
+        proper cleanup and unwinding of middleware operations.
+
+        Args:
+            state: Current agent state after model invocation.
+
+        Returns:
+            Merged dictionary of all state updates from all middleware.
+            Updates are accumulated in reverse order of execution.
+        """
+        updates: dict[str, Any] = {}
+
+        # Execute in reverse order
+        for mw in reversed(self.middleware):
+            mw_updates = mw.after_model(state)
+            if mw_updates:
+                updates.update(mw_updates)
+
+        return updates