aip-agents-binary 0.0.0b2__py3-none-any.whl → 0.5.11__py3-none-any.whl

aip_agents/utils/formatter_llm_client.pyi

@@ -0,0 +1,71 @@
+from _typeshed import Incomplete
+from aip_agents.utils.logger import get_logger as get_logger
+from collections.abc import Awaitable as Awaitable
+from gllm_inference.lm_invoker.lm_invoker import BaseLMInvoker
+from typing import Any, TypeVar
+
+logger: Incomplete
+FORMATTER_ENV_VAR: str
+T = TypeVar('T')
+
+class FormatterInvokerUnavailableError(RuntimeError):
+    """Raised when no formatter LLM invoker can be resolved."""
+class FormatterInvocationError(RuntimeError):
+    """Raised when invoking the formatter LLM fails."""
+
+class FormatterLLMClient:
+    """Stateful helper that manages formatter invoker resolution and execution."""
+    def __init__(self) -> None:
+        """Initialize the formatter LLM client with caching and thread safety."""
+    def seed_default(self, default_model_id: str | None) -> None:
+        """Populate ``DEFAULT_MODEL_FORMATTER`` when unset.
+
+        Args:
+            default_model_id: Preferred formatter model id to use as a fallback.
+        """
+    def resolve_invoker(self, *, reset_cache: bool = False) -> BaseLMInvoker | None:
+        """Return the cached formatter invoker, optionally refreshing it.
+
+        Args:
+            reset_cache: When True, clear the cached invoker before resolving.
+
+        Returns:
+            BaseLMInvoker | None: Cached invoker if the formatter is configured, otherwise None.
+        """
+    async def invoke(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Dispatch formatter prompts asynchronously with timeout/error handling.
+
+        Args:
+            *args: Positional arguments forwarded to the invoker.
+            invoker: Explicit invoker instance to reuse instead of resolving one.
+            timeout: Optional timeout (seconds) enforced with ``asyncio.timeout``.
+            **kwargs: Keyword arguments forwarded to the invoker.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+
+        Raises:
+            FormatterInvokerUnavailableError: If no formatter model is configured.
+            FormatterInvocationError: When the invocation fails or exceeds the timeout.
+        """
+    def invoke_blocking(self, *args: Any, invoker: BaseLMInvoker | None = None, timeout: float | None = None, **kwargs: Any) -> Any:
+        """Invoke the formatter LLM from synchronous contexts.
+
+        Args:
+            *args: Positional arguments forwarded to ``invoke``.
+            invoker: Optional invoker to reuse.
+            timeout: Optional timeout (seconds) for the async invocation.
+            **kwargs: Keyword arguments forwarded to ``invoke``.
+
+        Returns:
+            Any: Result returned by the formatter LLM.
+        """
+
+def get_formatter_llm_client() -> FormatterLLMClient:
+    """Return the process-wide formatter LLM client."""
+def seed_formatter_llm_default(default_model_id: str | None) -> None:
+    """Convenience wrapper for seeding the formatter default model.
+
+    Args:
+        default_model_id: Formatter model identifier to seed when missing.
+    """

aip_agents/utils/langgraph/__init__.py

@@ -0,0 +1,19 @@
+"""Define __init__ for langgraph converter.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.utils.langgraph.converter import (
+    convert_gllm_tool_call_to_langchain_tool_call,
+    convert_langchain_messages_to_gllm_messages,
+    convert_langchain_tool_call_to_gllm_tool_call,
+    convert_lm_output_to_langchain_message,
+)
+
+__all__ = [
+    "convert_gllm_tool_call_to_langchain_tool_call",
+    "convert_langchain_tool_call_to_gllm_tool_call",
+    "convert_lm_output_to_langchain_message",
+    "convert_langchain_messages_to_gllm_messages",
+]

aip_agents/utils/langgraph/converter.py

@@ -0,0 +1,128 @@
+"""Bridge utilities for converting between LangChain and LM Invoker formats.
+
+This module provides conversion functions between LangChain's message format
+and gllm-inference's Message format, enabling seamless integration
+of LM Invoker with LangChain-based agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from collections.abc import Sequence
+
+from gllm_inference.schema import LMOutput, Message, ToolResult
+from gllm_inference.schema import ToolCall as GllmToolCall
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage, ToolMessage
+from langchain_core.messages.tool import ToolCall as LangChainToolCall
+
+
+def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
+    """Convert LangChain messages to gllm-inference Message format.
+
+    This function transforms a sequence of LangChain messages into the Message
+    format expected by LM Invoker. It handles system messages, human messages, AI messages
+    with tool calls, and tool result messages.
+
+    Args:
+        messages: Sequence of LangChain BaseMessage objects to convert.
+        instruction: System instruction to prepend if not already present in messages.
+
+    Returns:
+        List of Message objects containing the converted message sequence.
+    """
+    converted_messages = []
+
+    # Add system instruction first if provided
+    if instruction:
+        converted_messages.append(Message.system(instruction))
+
+    for msg in messages:
+        if isinstance(msg, SystemMessage):
+            # Skip if we already added instruction, or append if different
+            if not instruction or msg.content != instruction:
+                converted_messages.append(Message.system(msg.content))
+        elif isinstance(msg, HumanMessage):
+            converted_messages.append(Message.user(msg.content))
+        elif isinstance(msg, AIMessage):
+            if msg.tool_calls:
+                # Convert LangChain tool calls to gllm ToolCall objects
+                tool_calls = [convert_langchain_tool_call_to_gllm_tool_call(tc) for tc in msg.tool_calls]
+                converted_messages.append(Message.assistant(tool_calls))
+            else:
+                converted_messages.append(Message.assistant(msg.content))
+        elif isinstance(msg, ToolMessage):
+            # Convert ToolMessage to ToolResult
+            tool_result = ToolResult(id=msg.tool_call_id, output=msg.content)
+            converted_messages.append(Message.user([tool_result]))
+
+    return converted_messages
+
+
+def convert_lm_output_to_langchain_message(response: LMOutput | str) -> AIMessage:
+    """Convert LM Invoker output to LangChain AIMessage.
+
+    This function transforms the output from LM Invoker back into LangChain's
+    AIMessage format, handling both text responses and tool calls.
+
+    Args:
+        response: The response from LM Invoker (MultimodalOutput).
+
+    Returns:
+        AIMessage containing the converted response.
+    """
+    if not isinstance(response, LMOutput):
+        # when output_analytics lm_invoker is false
+        return AIMessage(
+            content=str(response),
+            response_metadata={
+                "finish_reason": "stop",
+            },
+        )
+
+    tool_calls = []
+    if response.tool_calls:
+        tool_calls = [convert_gllm_tool_call_to_langchain_tool_call(tc) for tc in response.tool_calls]
+
+    usage_metadata = None
+    if response.token_usage:
+        usage_metadata = {
+            "input_tokens": response.token_usage.input_tokens,
+            "output_tokens": response.token_usage.output_tokens,
+            "total_tokens": response.token_usage.input_tokens + response.token_usage.output_tokens,
+        }
+
+    # if add finish reason stop fo non-tool call ai messages
+    response_metadata = {}
+    if not tool_calls:
+        response_metadata["finish_reason"] = "stop"
+
+    return AIMessage(
+        content=str(response.response),
+        tool_calls=tool_calls,
+        usage_metadata=usage_metadata,
+        response_metadata=response_metadata,
+    )
+
+
+def convert_langchain_tool_call_to_gllm_tool_call(lc_tool_call: LangChainToolCall) -> GllmToolCall:
+    """Convert LangChain tool call to gllm ToolCall.
+
+    Args:
+        lc_tool_call: LangChain ToolCall (TypedDict).
+
+    Returns:
+        GllmToolCall object for gllm-inference.
+    """
+    return GllmToolCall(id=lc_tool_call["id"], name=lc_tool_call["name"], args=lc_tool_call["args"])
+
+
+def convert_gllm_tool_call_to_langchain_tool_call(gllm_tool_call: GllmToolCall) -> LangChainToolCall:
+    """Convert gllm ToolCall to LangChain ToolCall format.
+
+    Args:
+        gllm_tool_call: GllmToolCall object from gllm-inference.
+
+    Returns:
+        LangChain ToolCall (TypedDict) with proper type annotation.
+    """
+    return LangChainToolCall(id=gllm_tool_call.id, name=gllm_tool_call.name, args=gllm_tool_call.args)

aip_agents/utils/langgraph/converter.pyi

@@ -1,7 +1,7 @@
+from collections.abc import Sequence
 from gllm_inference.schema import LMOutput, Message, ToolCall as GllmToolCall
 from langchain_core.messages import AIMessage, BaseMessage as BaseMessage
 from langchain_core.messages.tool import ToolCall as LangChainToolCall
-from typing import Sequence
 
 def convert_langchain_messages_to_gllm_messages(messages: Sequence[BaseMessage], instruction: str) -> list[Message]:
     """Convert LangChain messages to gllm-inference Message format.

aip_agents/utils/langgraph/tool_managers/__init__.py

@@ -0,0 +1,15 @@
+"""Tool managers for organizing LangGraph agent capabilities.
+
+This package contains tool managers that convert different types of capabilities
+(A2A communication, agent delegation) into unified LangChain tools for use in
+LangGraph agents.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from aip_agents.utils.langgraph.tool_managers.a2a_tool_manager import A2AToolManager
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager
+from aip_agents.utils.langgraph.tool_managers.delegation_tool_manager import DelegationToolManager
+
+__all__ = ["BaseLangGraphToolManager", "A2AToolManager", "DelegationToolManager"]

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.py

@@ -0,0 +1,99 @@
+"""A2A tool manager for LangGraph agents.
+
+This module provides the A2AToolManager class that converts A2A agent cards
+into LangChain tools for use in LangGraph agents.
+"""
+
+from a2a.types import AgentCard
+from langchain_core.tools import BaseTool, tool
+
+from aip_agents.utils.a2a_connector import A2AConnector
+from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class A2AToolManager(BaseLangGraphToolManager):
+    """Manages A2A communication tools for LangGraph agents.
+
+    This tool manager converts A2A agent cards into LangChain tools that can
+    be used in a unified ToolNode within LangGraph agents. Each A2A agent
+    becomes a tool that the LLM can call for external communication.
+    """
+
+    def __init__(self):
+        """Initialize the A2A tool manager."""
+        super().__init__()
+        self.registered_agents: list = []
+
+    def register_resources(self, agent_cards: list[AgentCard]) -> list[BaseTool]:
+        """Register A2A agents and convert them to LangChain tools.
+
+        Args:
+            agent_cards: List of AgentCard instances for external communication.
+
+        Returns:
+            List of created A2A communication tools.
+        """
+        self.registered_agents = list(agent_cards)
+        self.created_tools = [self._create_a2a_tool(card) for card in agent_cards]
+
+        logger.info(f"A2AToolManager: Created {len(self.created_tools)} A2A communication tools")
+        return self.created_tools
+
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered A2A agents.
+
+        Returns:
+            list[str]: A list of names of all registered A2A agents.
+        """
+        return [agent.name for agent in self.registered_agents]
+
+    def _create_a2a_tool(self, agent_card) -> BaseTool:
+        """Create a LangChain tool for A2A communication with a specific agent.
+
+        Following the legacy BaseLangChainAgent.create_a2a_tool pattern.
+
+        Args:
+            agent_card: The AgentCard instance for the agent to communicate with.
+
+        Returns:
+            BaseTool: A LangChain tool for A2A communication with the agent.
+        """
+
+        @tool
+        def communicate_with_agent(query: str) -> str:
+            """Communicate with external agent via A2A protocol.
+
+            Args:
+                query: The message to send to the external agent.
+
+            Returns:
+                The response from the external agent.
+            """
+            try:
+                logger.debug(f"A2AToolManager: Sending A2A message to '{agent_card.name}'")
+                response = A2AConnector.send_to_agent(agent_card, query)
+                logger.debug(f"A2AToolManager: Received A2A response from '{agent_card.name}'")
+
+                # Handle response format (following legacy pattern)
+                if isinstance(response, dict) and "content" in response:
+                    return str(response["content"])
+                else:
+                    return str(response)
+            except Exception as e:
+                error_msg = f"A2A communication with '{agent_card.name}' failed: {e}"
+                logger.error(f"A2AToolManager: {error_msg}")
+                return error_msg
+
+        # Set tool metadata for proper routing and identification
+        communicate_with_agent.name = agent_card.name
+        communicate_with_agent.description = (
+            f"Communicate with external agent '{agent_card.name}'. "
+            f"Use this when you need to: {agent_card.description or 'collaborate with this agent'}"
+        )
+        # Set __name__ for compatibility (following legacy pattern)
+        communicate_with_agent.__name__ = agent_card.name
+
+        return communicate_with_agent

aip_agents/utils/langgraph/tool_managers/a2a_tool_manager.pyi

@@ -2,8 +2,8 @@ from _typeshed import Incomplete
 from a2a.types import AgentCard as AgentCard
 from aip_agents.utils.a2a_connector import A2AConnector as A2AConnector
 from aip_agents.utils.langgraph.tool_managers.base_tool_manager import BaseLangGraphToolManager as BaseLangGraphToolManager
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
-from langchain_core.tools import BaseTool as BaseTool
+from aip_agents.utils.logger import get_logger as get_logger
+from langchain_core.tools import BaseTool
 
 logger: Incomplete
 

aip_agents/utils/langgraph/tool_managers/base_tool_manager.py

@@ -0,0 +1,66 @@
+"""Base class for LangGraph tool managers.
+
+This module provides the abstract base class for managing specialized tools
+in LangGraph agents. Tool managers convert different capabilities (A2A, delegation) into unified LangChain tools.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from langchain_core.tools import BaseTool
+
+from aip_agents.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class BaseLangGraphToolManager(ABC):
+    """Base class for managing specialized tools in LangGraph agents.
+
+    This abstract base class provides a common interface for tool managers
+    that convert different types of capabilities into LangChain tools for
+    use in LangGraph agents.
+
+    The design follows a simple pattern:
+    1. Register resources (agents, cards, etc.)
+    2. Convert resources to LangChain tools
+    3. Provide access to created tools
+    """
+
+    def __init__(self):
+        """Initialize the tool manager."""
+        self.created_tools: list[BaseTool] = []
+
+    @abstractmethod
+    def register_resources(self, resources: list[Any]) -> list[BaseTool]:
+        """Register resources and convert them to LangChain tools.
+
+        Args:
+            resources: List of resources to convert to tools.
+
+        Returns:
+            List of created tools.
+        """
+        pass  # pragma: no cover - abstract method, pass statement never executed
+
+    def get_tools(self) -> list[BaseTool]:
+        """Get all created tools.
+
+        Returns:
+            Copy of created tools list.
+        """
+        return self.created_tools.copy()
+
+    def clear_tools(self) -> None:
+        """Clear all created tools."""
+        self.created_tools.clear()
+        logger.debug(f"{self.__class__.__name__}: Cleared all tools")
+
+    @abstractmethod
+    def get_resource_names(self) -> list[str]:
+        """Get names of all registered resources.
+
+        Returns:
+            List of resource names.
+        """
+        pass  # pragma: no cover - abstract method, pass statement never executed

aip_agents/utils/langgraph/tool_managers/base_tool_manager.pyi

@@ -1,13 +1,12 @@
-import abc
 from _typeshed import Incomplete
 from abc import ABC, abstractmethod
-from aip_agents.utils.logger_manager import LoggerManager as LoggerManager
+from aip_agents.utils.logger import get_logger as get_logger
 from langchain_core.tools import BaseTool as BaseTool
 from typing import Any
 
 logger: Incomplete
 
-class BaseLangGraphToolManager(ABC, metaclass=abc.ABCMeta):
+class BaseLangGraphToolManager(ABC):
     """Base class for managing specialized tools in LangGraph agents.
 
     This abstract base class provides a common interface for tool managers