glaip-sdk 0.6.5b5__py3-none-any.whl → 0.6.5b9__py3-none-any.whl

glaip_sdk/runner/langgraph.py

@@ -0,0 +1,597 @@
+"""LangGraph-based runner for local agent execution.
+
+This module provides the LangGraphRunner which executes glaip-sdk agents
+locally via the aip-agents LangGraphReactAgent, without requiring the AIP server.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+
+Example:
+    >>> from glaip_sdk.runner import LangGraphRunner
+    >>> from glaip_sdk.agents import Agent
+    >>>
+    >>> runner = LangGraphRunner()
+    >>> agent = Agent(name="my-agent", instruction="You are helpful.")
+    >>> result = runner.run(agent, "Hello, world!")
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from glaip_sdk.runner.base import BaseRunner
+from glaip_sdk.runner.deps import (
+    check_local_runtime_available,
+    get_local_runtime_missing_message,
+)
+from glaip_sdk.utils.a2a import A2AEventStreamProcessor
+from gllm_core.utils import LoggerManager
+
+if TYPE_CHECKING:
+    from glaip_sdk.agents.base import Agent
+
+logger = LoggerManager().get_logger(__name__)
+
+# Default A2A event processor
+_event_processor = A2AEventStreamProcessor()
+
+
+@dataclass(frozen=True, slots=True)
+class LangGraphRunner(BaseRunner):
+    """Runner implementation using aip-agents LangGraphReactAgent.
+
+    MVP scope:
+    - Execute via `LangGraphReactAgent.arun_a2a_stream()`
+    - Extract and return final text from the emitted `final_response` event
+
+    Attributes:
+        default_model: Model name to use when agent.model is not set.
+            Defaults to "gpt-4o-mini".
+    """
+
+    default_model: str = "openai/gpt-4o-mini"
+
+    def run(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,  # noqa: ARG002 - Used in PR-04+
+        chat_history: (list[dict[str, str]] | None) = None,  # noqa: ARG002 - Used in PR-03
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent synchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None. (Implemented in PR-04+)
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None. (Implemented in PR-03)
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If the local runtime dependencies are not available.
+            RuntimeError: If no final response is received from the agent.
+        """
+        if not check_local_runtime_available():
+            raise RuntimeError(get_local_runtime_missing_message())
+
+        return asyncio.run(
+            self._arun_internal(
+                agent=agent,
+                message=message,
+                verbose=verbose,
+                runtime_config=runtime_config,
+                **kwargs,
+            )
+        )
+
+    async def arun(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        chat_history: (list[dict[str, str]] | None) = None,  # noqa: ARG002 - Used in PR-03
+        **kwargs: Any,
+    ) -> str:
+        """Execute agent asynchronously and return final response text.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+                Defaults to False.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+                Defaults to None. (Implemented in PR-04+)
+            chat_history: Optional list of prior conversation messages.
+                Defaults to None. (Implemented in PR-03)
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+
+        Raises:
+            RuntimeError: If no final response is received from the agent.
+        """
+        return await self._arun_internal(
+            agent=agent,
+            message=message,
+            verbose=verbose,
+            runtime_config=runtime_config,
+            **kwargs,
+        )
+
+    async def _arun_internal(
+        self,
+        agent: Agent,
+        message: str,
+        verbose: bool = False,
+        runtime_config: dict[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> str:
+        """Internal async implementation of agent execution.
+
+        Args:
+            agent: The glaip_sdk Agent to execute.
+            message: The user message to send to the agent.
+            verbose: If True, emit debug trace output during execution.
+            runtime_config: Optional runtime configuration for tools, MCPs, etc.
+            **kwargs: Additional keyword arguments passed to the backend.
+
+        Returns:
+            The final response text from the agent.
+        """
+        # Build the local LangGraphReactAgent from the glaip_sdk Agent
+        local_agent = self.build_langgraph_agent(agent, runtime_config=runtime_config)
+
+        # Collect A2AEvents from the stream and extract final response
+        events: list[dict[str, Any]] = []
+
+        async for event in local_agent.arun_a2a_stream(message, **kwargs):
+            if verbose:
+                self._log_event(event)
+            events.append(event)
+
+        return _event_processor.extract_final_response(events)
+
+    def build_langgraph_agent(
+        self,
+        agent: Agent,
+        runtime_config: dict[str, Any] | None = None,
+    ) -> Any:
+        """Build a LangGraphReactAgent from a glaip_sdk Agent definition.
+
+        Args:
+            agent: The glaip_sdk Agent to convert.
+            runtime_config: Optional runtime configuration with tool_configs,
+                mcp_configs, agent_config, and agent-specific overrides.
+
+        Returns:
+            A configured LangGraphReactAgent instance.
+
+        Raises:
+            ImportError: If aip-agents is not installed.
+            ValueError: If agent has unsupported tools, MCPs, or sub-agents for local mode.
+        """
+        from aip_agents.agent import LangGraphReactAgent  # noqa: PLC0415
+        from glaip_sdk.runner.tool_adapter import LangChainToolAdapter  # noqa: PLC0415
+
+        # Adapt tools for local execution
+        langchain_tools: list[Any] = []
+        if agent.tools:
+            adapter = LangChainToolAdapter()
+            langchain_tools = adapter.adapt_tools(agent.tools)
+
+        # Build sub-agents recursively
+        sub_agent_instances = self._build_sub_agents(agent.agents, runtime_config)
+
+        # Normalize runtime config: merge global and agent-specific configs
+        normalized_config = self._normalize_runtime_config(runtime_config, agent)
+
+        # Merge tool_configs: agent definition < runtime config
+        tool_configs = self._merge_tool_configs(agent, normalized_config)
+
+        # Merge mcp_configs: agent definition < runtime config
+        mcp_configs = self._merge_mcp_configs(agent, normalized_config)
+
+        # Merge agent_config: agent definition < runtime config
+        merged_agent_config = self._merge_agent_config(agent, normalized_config)
+        agent_config_params, agent_config_kwargs = self._apply_agent_config(merged_agent_config)
+
+        # Build the LangGraphReactAgent with tools, sub-agents, and configs
+        local_agent = LangGraphReactAgent(
+            name=agent.name,
+            instruction=agent.instruction,
+            description=agent.description,
+            model=agent.model or self.default_model,
+            tools=langchain_tools,
+            agents=sub_agent_instances if sub_agent_instances else None,
+            tool_configs=tool_configs if tool_configs else None,
+            **agent_config_params,
+            **agent_config_kwargs,
+        )
+
+        # Add MCP servers if configured
+        self._add_mcp_servers(local_agent, agent, mcp_configs)
+
+        logger.debug(
+            "Built local LangGraphReactAgent for agent '%s' with %d tools, %d sub-agents, and %d MCPs",
+            agent.name,
+            len(langchain_tools),
+            len(sub_agent_instances),
+            len(agent.mcps) if agent.mcps else 0,
+        )
+        return local_agent
+
+    def _build_sub_agents(
+        self,
+        sub_agents: list[Any] | None,
+        runtime_config: dict[str, Any] | None,
+    ) -> list[Any]:
+        """Build sub-agent instances recursively.
+
+        Args:
+            sub_agents: List of sub-agent definitions.
+            runtime_config: Runtime config to pass to sub-agents.
+
+        Returns:
+            List of built sub-agent instances.
+
+        Raises:
+            ValueError: If sub-agent is platform-only.
+        """
+        if not sub_agents:
+            return []
+
+        sub_agent_instances = []
+        for sub_agent in sub_agents:
+            if getattr(sub_agent, "_lookup_only", False):
+                agent_name = getattr(sub_agent, "name", "<unknown>")
+                raise ValueError(
+                    f"Sub-agent '{agent_name}' is not supported in local mode. "
+                    "Platform agents (from_id, from_native) cannot be used as "
+                    "sub-agents in local execution. "
+                    "Define the sub-agent locally with Agent(name=..., instruction=...) instead."
+                )
+            sub_agent_instances.append(self.build_langgraph_agent(sub_agent, runtime_config))
+        return sub_agent_instances
+
+    def _add_mcp_servers(
+        self,
+        local_agent: Any,
+        agent: Agent,
+        merged_mcp_configs: dict[str, Any],
+    ) -> None:
+        """Add MCP servers to a built agent.
+
+        Args:
+            local_agent: The LangGraphReactAgent to add MCPs to.
+            agent: The glaip_sdk Agent with MCP definitions.
+            merged_mcp_configs: Merged mcp_configs (agent definition + runtime).
+        """
+        if not agent.mcps:
+            return
+
+        from glaip_sdk.runner.mcp_adapter import LangChainMCPAdapter  # noqa: PLC0415
+
+        mcp_adapter = LangChainMCPAdapter()
+        base_mcp_configs = mcp_adapter.adapt_mcps(agent.mcps)
+        logger.debug("Base MCP configs from adapter: %s", base_mcp_configs)
+
+        # Apply merged mcp_configs overrides (agent definition + runtime)
+        logger.debug("Merged mcp_configs to apply: %s", merged_mcp_configs)
+        if merged_mcp_configs:
+            base_mcp_configs = self._apply_runtime_mcp_configs(base_mcp_configs, merged_mcp_configs)
+            logger.debug("MCP configs after override: %s", base_mcp_configs)
+
+        if base_mcp_configs:
+            logger.info("MCP configs being sent to aip-agents: %s", base_mcp_configs)
+            local_agent.add_mcp_server(base_mcp_configs)
+            logger.debug(
+                "Registered %d MCP server(s) for agent '%s'",
+                len(base_mcp_configs),
+                agent.name,
+            )
+
+    def _normalize_runtime_config(
+        self,
+        runtime_config: dict[str, Any] | None,
+        agent: Agent,
+    ) -> dict[str, Any]:
+        """Normalize runtime_config for local execution.
+
+        Merges global and agent-specific configs with proper priority.
+        Keys are resolved from instances/classes to string names.
+
+        Args:
+            runtime_config: Raw runtime config from user.
+            agent: The agent being built (for resolving agent-specific overrides).
+
+        Returns:
+            Normalized config with string keys and merged priorities.
+        """
+        from glaip_sdk.utils.runtime_config import (  # noqa: PLC0415
+            merge_configs,
+            normalize_local_config_keys,
+        )
+
+        if not runtime_config:
+            return {}
+
+        # 1. Extract global configs and normalize keys
+        global_tool_configs = normalize_local_config_keys(runtime_config.get("tool_configs", {}))
+        global_mcp_configs = normalize_local_config_keys(runtime_config.get("mcp_configs", {}))
+        global_agent_config = runtime_config.get("agent_config", {})
+
+        # 2. Extract agent-specific overrides (highest priority)
+        agent_specific = self._get_agent_specific_config(runtime_config, agent)
+        agent_tool_configs = normalize_local_config_keys(agent_specific.get("tool_configs", {}))
+        agent_mcp_configs = normalize_local_config_keys(agent_specific.get("mcp_configs", {}))
+        agent_config_override = agent_specific.get("agent_config", {})
+
+        # 3. Merge with priority: global < agent-specific
+        merged_result = {
+            "tool_configs": merge_configs(global_tool_configs, agent_tool_configs),
+            "mcp_configs": merge_configs(global_mcp_configs, agent_mcp_configs),
+            "agent_config": merge_configs(global_agent_config, agent_config_override),
+        }
+        return merged_result
+
+    def _get_agent_specific_config(
+        self,
+        runtime_config: dict[str, Any],
+        agent: Agent,
+    ) -> dict[str, Any]:
+        """Extract agent-specific config from runtime_config.
+
+        Args:
+            runtime_config: Runtime config that may contain agent-specific overrides.
+            agent: The agent to find config for.
+
+        Returns:
+            Agent-specific config dict, or empty dict if not found.
+        """
+        from glaip_sdk.utils.runtime_config import get_name_from_key  # noqa: PLC0415
+
+        # Reserved keys at the top level
+        reserved_keys = {"tool_configs", "mcp_configs", "agent_config"}
+
+        # Try finding agent by instance, class, or name
+        for key, value in runtime_config.items():
+            if key in reserved_keys:
+                continue  # Skip global configs
+
+            # Check if this key matches the agent
+            try:
+                key_name = get_name_from_key(key)
+            except ValueError:
+                continue  # Skip invalid keys
+
+            if key_name and key_name == agent.name:
+                return value if isinstance(value, dict) else {}
+
+        return {}
+
+    def _merge_tool_configs(
+        self,
+        agent: Agent,
+        normalized_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Merge agent.tool_configs with runtime tool_configs.
+
+        Priority (lowest to highest):
+        1. Agent definition (agent.tool_configs)
+        2. Runtime config (normalized_config["tool_configs"])
+
+        Args:
+            agent: The agent with optional tool_configs property.
+            normalized_config: Normalized runtime config.
+
+        Returns:
+            Merged tool_configs dict.
+        """
+        from glaip_sdk.utils.runtime_config import (  # noqa: PLC0415
+            merge_configs,
+            normalize_local_config_keys,
+        )
+
+        # Get agent's tool_configs if defined
+        agent_tool_configs = {}
+        if hasattr(agent, "tool_configs") and agent.tool_configs:
+            agent_tool_configs = normalize_local_config_keys(agent.tool_configs)
+
+        # Get runtime tool_configs
+        runtime_tool_configs = normalized_config.get("tool_configs", {})
+
+        # Merge: agent definition < runtime config
+        return merge_configs(agent_tool_configs, runtime_tool_configs)
+
+    def _merge_mcp_configs(
+        self,
+        agent: Agent,
+        normalized_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Merge agent.mcp_configs with runtime mcp_configs.
+
+        Priority (lowest to highest):
+        1. Agent definition (agent.mcp_configs)
+        2. Runtime config (normalized_config["mcp_configs"])
+
+        Args:
+            agent: The agent with optional mcp_configs property.
+            normalized_config: Normalized runtime config.
+
+        Returns:
+            Merged mcp_configs dict.
+        """
+        from glaip_sdk.utils.runtime_config import (  # noqa: PLC0415
+            merge_configs,
+            normalize_local_config_keys,
+        )
+
+        # Get agent's mcp_configs if defined
+        agent_mcp_configs = {}
+        if hasattr(agent, "mcp_configs") and agent.mcp_configs:
+            agent_mcp_configs = normalize_local_config_keys(agent.mcp_configs)
+
+        # Get runtime mcp_configs
+        runtime_mcp_configs = normalized_config.get("mcp_configs", {})
+
+        # Merge: agent definition < runtime config
+        return merge_configs(agent_mcp_configs, runtime_mcp_configs)
+
+    def _merge_agent_config(
+        self,
+        agent: Agent,
+        normalized_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Merge agent.agent_config with runtime agent_config.
+
+        Priority (lowest to highest):
+        1. Agent definition (agent.agent_config)
+        2. Runtime config (normalized_config["agent_config"])
+
+        Args:
+            agent: The agent with optional agent_config property.
+            normalized_config: Normalized runtime config.
+
+        Returns:
+            Merged agent_config dict.
+        """
+        from glaip_sdk.utils.runtime_config import merge_configs  # noqa: PLC0415
+
+        # Get agent's agent_config if defined
+        agent_agent_config = {}
+        if hasattr(agent, "agent_config") and agent.agent_config:
+            agent_agent_config = agent.agent_config
+
+        # Get runtime agent_config
+        runtime_agent_config = normalized_config.get("agent_config", {})
+
+        # Merge: agent definition < runtime config
+        return merge_configs(agent_agent_config, runtime_agent_config)
+
+    def _apply_agent_config(
+        self,
+        agent_config: dict[str, Any],
+    ) -> tuple[dict[str, Any], dict[str, Any]]:
+        """Extract and separate agent_config into direct params and kwargs.
+
+        Separates agent_config into parameters that go directly to LangGraphReactAgent
+        constructor vs those that go through **kwargs.
+
+        Args:
+            agent_config: Runtime agent configuration dict.
+
+        Returns:
+            Tuple of (direct_params, kwargs_params):
+            - direct_params: Parameters passed directly to LangGraphReactAgent.__init__()
+            - kwargs_params: Parameters passed via **kwargs to BaseAgent
+        """
+        direct_params = {}
+        kwargs_params = {}
+
+        # Direct constructor parameters
+        if "planning" in agent_config:
+            direct_params["planning"] = agent_config["planning"]
+
+        # Kwargs parameters (passed through **kwargs to BaseAgent)
+        if "memory" in agent_config:
+            # Map "memory" to "memory_backend" for aip-agents compatibility
+            kwargs_params["memory_backend"] = agent_config["memory"]
+
+        # Additional memory-related settings
+        memory_settings = ["agent_id", "memory_namespace", "save_interaction_to_memory"]
+        for key in memory_settings:
+            if key in agent_config:
+                kwargs_params[key] = agent_config[key]
+
+        return direct_params, kwargs_params
+
+    def _apply_runtime_mcp_configs(
+        self,
+        base_configs: dict[str, Any],
+        runtime_overrides: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Apply runtime mcp_configs overrides to base MCP configurations.
+
+        Merges runtime overrides into the base configs, handling authentication
+        conversion to headers using MCPConfigBuilder.
+
+        Args:
+            base_configs: Base MCP configs from adapter (server_name -> config).
+            runtime_overrides: Runtime mcp_configs overrides (server_name -> config).
+
+        Returns:
+            Merged MCP configs with authentication converted to headers.
+        """
+        return {
+            server_name: self._merge_single_mcp_config(server_name, base_config, runtime_overrides.get(server_name))
+            for server_name, base_config in base_configs.items()
+        }
+
+    def _merge_single_mcp_config(
+        self,
+        server_name: str,
+        base_config: dict[str, Any],
+        override: dict[str, Any] | None,
+    ) -> dict[str, Any]:
+        """Merge a single MCP config with runtime override.
+
+        Args:
+            server_name: Name of the MCP server.
+            base_config: Base config from adapter.
+            override: Optional runtime override config.
+
+        Returns:
+            Merged config dict.
+        """
+        merged = base_config.copy()
+
+        if not override:
+            return merged
+
+        from glaip_sdk.runner.mcp_adapter.mcp_config_builder import (  # noqa: PLC0415
+            MCPConfigBuilder,
+        )
+
+        # Handle authentication override
+        if "authentication" in override:
+            headers = MCPConfigBuilder.build_headers_from_auth(override["authentication"])
+            if headers:
+                merged["headers"] = headers
+                logger.debug("Applied runtime authentication headers for MCP '%s'", server_name)
+
+        # Merge other config keys (excluding authentication since we converted it)
+        for key, value in override.items():
+            if key != "authentication":
+                merged[key] = value
+
+        return merged
+
+    def _log_event(self, event: dict[str, Any]) -> None:
+        """Log an A2AEvent for verbose debug output.
+
+        Args:
+            event: The A2AEvent dictionary to log.
+        """
+        event_type = event.get("event_type", "unknown")
+        content = event.get("content", "")
+        is_final = event.get("is_final", False)
+
+        # Truncate long content for readability
+        content_str = str(content) if content else ""
+        content_preview = content_str[:100] + "..." if len(content_str) > 100 else content_str
+
+        final_marker = "(final)" if is_final else ""
+        logger.info("[%s] %s %s", event_type, final_marker, content_preview)

glaip_sdk/runner/mcp_adapter/__init__.py

@@ -0,0 +1,13 @@
+"""MCP adapter module for local agent runtime.
+
+This module provides MCP adapters for converting glaip-sdk MCP references
+to backend-specific MCP configuration formats.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from glaip_sdk.runner.mcp_adapter.base_mcp_adapter import BaseMCPAdapter
+from glaip_sdk.runner.mcp_adapter.langchain_mcp_adapter import LangChainMCPAdapter
+
+__all__ = ["BaseMCPAdapter", "LangChainMCPAdapter"]

glaip_sdk/runner/mcp_adapter/base_mcp_adapter.py

@@ -0,0 +1,43 @@
+"""Base MCP adapter for local agent runtime.
+
+This module defines the abstract base class for MCP adapters.
+Different backends (LangGraph, Google ADK) implement their own adapters.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class BaseMCPAdapter(ABC):
+    """Abstract base class for MCP adapters.
+
+    One Interface, Multiple Implementations:
+    - LangChainMCPAdapter: Adapts to aip-agents mcp_config format
+    - GoogleADKMCPAdapter: Adapts to Google ADK format (future)
+
+    Each backend implements this interface to adapt glaip-sdk MCPs
+    to their specific MCP configuration format.
+    """
+
+    @abstractmethod
+    def adapt_mcps(self, mcp_refs: list[Any]) -> dict[str, Any]:
+        """Adapt glaip-sdk MCP references to backend-specific format.
+
+        Args:
+            mcp_refs: List of MCP references from Agent definition.
+                Can be: MCP class instances, MCP.from_native() refs, etc.
+
+        Returns:
+            Backend-specific MCP configuration.
+            For LangChain/aip-agents: dict[str, dict[str, Any]] mapping server names to config.
+            For Google ADK: dict in Google ADK MCP format.
+
+        Raises:
+            ValueError: If MCP is not supported by this backend.
+        """
+        ...