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

aip_agents/memory/simple_memory.pyi

@@ -0,0 +1,23 @@
+from aip_agents.memory.base import BaseMemory as BaseMemory, ChatMessage as ChatMessage
+
+class SimpleMemory(BaseMemory):
+    """A simple memory implementation that stores messages in a list."""
+    messages: list[ChatMessage]
+    def __init__(self) -> None:
+        """Initialize the SimpleMemory instance with an empty message list."""
+    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.
+        '''
+    def get_messages(self) -> list[ChatMessage]:
+        """Get all messages from memory."""
+    def clear(self) -> None:
+        """Clear all messages from memory."""

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

@@ -0,0 +1,5 @@
+from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
+from aip_agents.middleware.manager import MiddlewareManager as MiddlewareManager
+from aip_agents.middleware.todolist import TodoListMiddleware as TodoListMiddleware, TodoStatus as TodoStatus
+
+__all__ = ['AgentMiddleware', 'ModelRequest', 'MiddlewareManager', 'TodoListMiddleware', 'TodoStatus']

aip_agents/middleware/base.py

@@ -0,0 +1,96 @@
+"""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
+
+    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronous version of before_model hook."""
+        return self.before_model(state)
+
+    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronous version of after_model hook."""
+        return self.after_model(state)

aip_agents/middleware/base.pyi

@@ -0,0 +1,75 @@
+from langchain_core.tools import BaseTool as BaseTool
+from typing import Any, Protocol, TypedDict
+
+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.
+        """
+    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.
+        """
+    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.
+        """
+    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronous version of before_model hook."""
+    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronous version of after_model hook."""

aip_agents/middleware/manager.py

@@ -0,0 +1,150 @@
+"""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
+
+    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously execute before_model hooks for all middleware."""
+        state_updates: dict[str, Any] = {}
+
+        for mw in self.middleware:
+            mw_updates = await mw.abefore_model(state)
+            if mw_updates:
+                state_updates.update(mw_updates)
+
+        return state_updates
+
+    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously execute after_model hooks for all middleware in reverse order."""
+        updates: dict[str, Any] = {}
+
+        for mw in reversed(self.middleware):
+            mw_updates = await mw.aafter_model(state)
+            if mw_updates:
+                updates.update(mw_updates)
+
+        return updates

aip_agents/middleware/manager.pyi

@@ -0,0 +1,84 @@
+from _typeshed import Incomplete
+from aip_agents.middleware.base import AgentMiddleware as AgentMiddleware, ModelRequest as ModelRequest
+from langchain_core.tools import BaseTool as BaseTool
+from typing import Any
+
+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.
+    """
+    middleware: Incomplete
+    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.
+        """
+    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.
+        """
+    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.
+        """
+    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.
+        """
+    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.
+        """
+    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.
+        """
+    async def abefore_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously execute before_model hooks for all middleware."""
+    async def aafter_model(self, state: dict[str, Any]) -> dict[str, Any]:
+        """Asynchronously execute after_model hooks for all middleware in reverse order."""