langroid 0.54.1__py3-none-any.whl → 0.54.2__py3-none-any.whl

langroid/agent/base.py

@@ -251,6 +251,172 @@ class Agent(ABC):
     def clear_dialog(self) -> None:
         self.dialog = []
 
+    def _analyze_handler_params(
+        self, handler_method: Any
+    ) -> Tuple[bool, Optional[str], Optional[str]]:
+        """
+        Analyze parameters of a handler method to determine their types.
+
+        Returns:
+            Tuple of (has_annotations, agent_param_name, chat_doc_param_name)
+            - has_annotations: True if useful type annotations were found
+            - agent_param_name: Name of the agent parameter if found
+            - chat_doc_param_name: Name of the chat_doc parameter if found
+        """
+        sig = inspect.signature(handler_method)
+        params = list(sig.parameters.values())
+        # Remove 'self' parameter
+        params = [p for p in params if p.name != "self"]
+
+        agent_param = None
+        chat_doc_param = None
+        has_annotations = False
+
+        for param in params:
+            # First try type annotations
+            if param.annotation != inspect.Parameter.empty:
+                ann_str = str(param.annotation)
+                # Check for Agent-like types
+                if (
+                    param.annotation == self.__class__
+                    or "Agent" in ann_str
+                    or (
+                        hasattr(param.annotation, "__name__")
+                        and "Agent" in param.annotation.__name__
+                    )
+                ):
+                    agent_param = param.name
+                    has_annotations = True
+                # Check for ChatDocument-like types
+                elif "ChatDocument" in ann_str or "ChatDoc" in ann_str:
+                    chat_doc_param = param.name
+                    has_annotations = True
+
+            # Fallback to parameter names
+            elif param.name == "agent":
+                agent_param = param.name
+            elif param.name == "chat_doc":
+                chat_doc_param = param.name
+
+        return has_annotations, agent_param, chat_doc_param
+
+    @no_type_check
+    def _create_handler_wrapper(
+        self,
+        message_class: Type[ToolMessage],
+        handler_method: Any,
+        is_async: bool = False,
+    ) -> Any:
+        """
+        Create a wrapper function for a handler method based on its signature.
+
+        Args:
+            message_class: The ToolMessage class
+            handler_method: The handle/handle_async method
+            is_async: Whether this is for an async handler
+
+        Returns:
+            Appropriate wrapper function
+        """
+        sig = inspect.signature(handler_method)
+        params = list(sig.parameters.values())
+        params = [p for p in params if p.name != "self"]
+
+        has_annotations, agent_param, chat_doc_param = self._analyze_handler_params(
+            handler_method,
+        )
+
+        # Build wrapper based on found parameters
+        if len(params) == 0:
+            if is_async:
+
+                async def wrapper(obj: Any) -> Any:
+                    return await obj.handle_async()
+
+            else:
+
+                def wrapper(obj: Any) -> Any:
+                    return obj.handle()
+
+        elif agent_param and chat_doc_param:
+            # Both parameters present - build wrapper respecting their order
+            param_names = [p.name for p in params]
+            if param_names.index(agent_param) < param_names.index(chat_doc_param):
+                # agent is first parameter
+                if is_async:
+
+                    async def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return await obj.handle_async(self, chat_doc)
+
+                else:
+
+                    def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return obj.handle(self, chat_doc)
+
+            else:
+                # chat_doc is first parameter
+                if is_async:
+
+                    async def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return await obj.handle_async(chat_doc, self)
+
+                else:
+
+                    def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return obj.handle(chat_doc, self)
+
+        elif agent_param and not chat_doc_param:
+            # Only agent parameter
+            if is_async:
+
+                async def wrapper(obj: Any) -> Any:
+                    return await obj.handle_async(self)
+
+            else:
+
+                def wrapper(obj: Any) -> Any:
+                    return obj.handle(self)
+
+        elif chat_doc_param and not agent_param:
+            # Only chat_doc parameter
+            if is_async:
+
+                async def wrapper(obj: Any, chat_doc: Any) -> Any:
+                    return await obj.handle_async(chat_doc)
+
+            else:
+
+                def wrapper(obj: Any, chat_doc: Any) -> Any:
+                    return obj.handle(chat_doc)
+
+        else:
+            # No recognized parameters - backward compatibility
+            # Assume single parameter is chat_doc (legacy behavior)
+            if len(params) == 1:
+                if is_async:
+
+                    async def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return await obj.handle_async(chat_doc)
+
+                else:
+
+                    def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return obj.handle(chat_doc)
+
+            else:
+                # Multiple unrecognized parameters - best guess
+                if is_async:
+
+                    async def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return await obj.handle_async(chat_doc)
+
+                else:
+
+                    def wrapper(obj: Any, chat_doc: Any) -> Any:
+                        return obj.handle(chat_doc)
+
+        return wrapper
+
     def _get_tool_list(
         self, message_class: Optional[Type[ToolMessage]] = None
     ) -> List[str]:
@@ -304,13 +470,12 @@ class Agent(ABC):
             in one place, i.e. in the message class.
             See `tests/main/test_stateless_tool_messages.py` for an example.
             """
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.handle).parameters) > 1
+            wrapper = self._create_handler_wrapper(
+                message_class,
+                message_class.handle,
+                is_async=False,
             )
-            if has_chat_doc_arg:
-                setattr(self, handler, lambda obj, chat_doc: obj.handle(chat_doc))
-            else:
-                setattr(self, handler, lambda obj: obj.handle())
+            setattr(self, handler, wrapper)
         elif (
             hasattr(message_class, "response")
             and inspect.isfunction(message_class.response)
@@ -320,11 +485,17 @@ class Agent(ABC):
                 len(inspect.signature(message_class.response).parameters) > 2
             )
             if has_chat_doc_arg:
-                setattr(
-                    self, handler, lambda obj, chat_doc: obj.response(self, chat_doc)
-                )
+
+                def response_wrapper_with_chat_doc(obj: Any, chat_doc: Any) -> Any:
+                    return obj.response(self, chat_doc)
+
+                setattr(self, handler, response_wrapper_with_chat_doc)
             else:
-                setattr(self, handler, lambda obj: obj.response(self))
+
+                def response_wrapper_no_chat_doc(obj: Any) -> Any:
+                    return obj.response(self)
+
+                setattr(self, handler, response_wrapper_no_chat_doc)
 
         if hasattr(message_class, "handle_message_fallback") and (
             inspect.isfunction(message_class.handle_message_fallback)
@@ -334,10 +505,13 @@ class Agent(ABC):
             # `handle_message_fallback` method (which does nothing).
             # It's possible multiple tool messages have a `handle_message_fallback`,
             # in which case, the last one inserted will be used.
+            def fallback_wrapper(msg: Any) -> Any:
+                return message_class.handle_message_fallback(self, msg)
+
             setattr(
                 self,
                 "handle_message_fallback",
-                lambda msg: message_class.handle_message_fallback(self, msg),
+                fallback_wrapper,
             )
 
         async_handler_name = f"{handler}_async"
@@ -346,23 +520,12 @@ class Agent(ABC):
             and inspect.isfunction(message_class.handle_async)
             and not hasattr(self, async_handler_name)
         ):
-            has_chat_doc_arg = (
-                len(inspect.signature(message_class.handle_async).parameters) > 1
+            wrapper = self._create_handler_wrapper(
+                message_class,
+                message_class.handle_async,
+                is_async=True,
             )
-
-            if has_chat_doc_arg:
-
-                @no_type_check
-                async def handler(obj, chat_doc):
-                    return await obj.handle_async(chat_doc)
-
-            else:
-
-                @no_type_check
-                async def handler(obj):
-                    return await obj.handle_async()
-
-            setattr(self, async_handler_name, handler)
+            setattr(self, async_handler_name, wrapper)
         elif (
             hasattr(message_class, "response_async")
             and inspect.isfunction(message_class.response_async)

langroid/agent/tools/mcp/fastmcp_client.py

@@ -1,6 +1,8 @@
 import asyncio
 import datetime
 import logging
+from base64 import b64decode
+from io import BytesIO
 from typing import Any, Dict, List, Optional, Tuple, Type, TypeAlias, cast
 
 from dotenv import load_dotenv
@@ -16,9 +18,20 @@ from mcp.client.session import (
     LoggingFnT,
     MessageHandlerFnT,
 )
-from mcp.types import CallToolResult, TextContent, Tool
+from mcp.types import (
+    BlobResourceContents,
+    CallToolResult,
+    EmbeddedResource,
+    ImageContent,
+    TextContent,
+    TextResourceContents,
+    Tool,
+)
 
+from langroid.agent.base import Agent
+from langroid.agent.chat_document import ChatDocument
 from langroid.agent.tool_message import ToolMessage
+from langroid.parsing.file_attachment import FileAttachment
 from langroid.pydantic_v1 import AnyUrl, BaseModel, Field, create_model
 
 load_dotenv()  # load environment variables from .env
@@ -39,6 +52,10 @@ class FastMCPClient:
     def __init__(
         self,
         server: FastMCPServerSpec,
+        persist_connection: bool = False,
+        forward_images: bool = True,
+        forward_text_resources: bool = False,
+        forward_blob_resources: bool = False,
         sampling_handler: SamplingHandler | None = None,  # type: ignore
         roots: RootsList | RootsHandler | None = None,  # type: ignore
         log_handler: LoggingFnT | None = None,
@@ -58,6 +75,10 @@ class FastMCPClient:
         self.log_handler = log_handler
         self.message_handler = message_handler
         self.read_timeout_seconds = read_timeout_seconds
+        self.persist_connection = persist_connection
+        self.forward_text_resources = forward_text_resources
+        self.forward_blob_resources = forward_blob_resources
+        self.forward_images = forward_images
 
     async def __aenter__(self) -> "FastMCPClient":
         """Enter the async context manager and connect inner client."""
@@ -96,6 +117,19 @@ class FastMCPClient:
         self.client = None
         self._cm = None
 
+    def __del__(self) -> None:
+        """Warn about unclosed persistent connections."""
+        if self.client is not None and self.persist_connection:
+            import warnings
+
+            warnings.warn(
+                f"FastMCPClient with persist_connection=True was not properly closed. "
+                f"Connection to {self.server} may leak resources. "
+                f"Use 'async with' or call await client.close()",
+                ResourceWarning,
+                stacklevel=2,
+            )
+
     def _schema_to_field(
         self, name: str, schema: Dict[str, Any], prefix: str
     ) -> Tuple[Any, Any]:
@@ -151,7 +185,13 @@ class FastMCPClient:
         with the given `tool_name`.
         """
         if not self.client:
-            raise RuntimeError("Client not initialized. Use async with FastMCPClient.")
+            if self.persist_connection:
+                await self.connect()
+                assert self.client
+            else:
+                raise RuntimeError(
+                    "Client not initialized. Use async with FastMCPClient."
+                )
         target = await self.get_mcp_tool_async(tool_name)
         if target is None:
             raise ValueError(f"No tool named {tool_name}")
@@ -209,36 +249,68 @@ class FastMCPClient:
         tool_model._renamed_fields = renamed  # type: ignore[attr-defined]
 
         # 2) define an arg-free call_tool_async()
-        async def call_tool_async(self: ToolMessage) -> Any:
+        async def call_tool_async(itself: ToolMessage) -> Any:
             from langroid.agent.tools.mcp.fastmcp_client import FastMCPClient
 
             # pack up the payload
-            payload = self.dict(
-                exclude=self.Config.schema_extra["exclude"].union(
+            payload = itself.dict(
+                exclude=itself.Config.schema_extra["exclude"].union(
                     ["request", "purpose"]
                 ),
             )
 
             # restore any renamed fields
-            for orig, new in self.__class__._renamed_fields.items():  # type: ignore
+            for orig, new in itself.__class__._renamed_fields.items():  # type: ignore
                 if new in payload:
                     payload[orig] = payload.pop(new)
 
-            client_cfg = getattr(self.__class__, "_client_config", None)  # type: ignore
+            client_cfg = getattr(itself.__class__, "_client_config", None)  # type: ignore
             if not client_cfg:
                 # Fallback or error - ideally _client_config should always exist
-                raise RuntimeError(f"Client config missing on {self.__class__}")
+                raise RuntimeError(f"Client config missing on {itself.__class__}")
+
+            # Connect the client if not yet connected and keep the connection open
+            if self.persist_connection:
+                if not self.client:
+                    await self.connect()
+
+                return await self.call_mcp_tool(itself.request, payload)
+
             # open a fresh client, call the tool, then close
             async with FastMCPClient(**client_cfg) as client:  # type: ignore
-                return await client.call_mcp_tool(self.request, payload)
+                return await client.call_mcp_tool(itself.request, payload)
 
         tool_model.call_tool_async = call_tool_async  # type: ignore
 
         if not hasattr(tool_model, "handle_async"):
-            # 3) define an arg-free handle_async() method
-            # if the tool model doesn't already have one
-            async def handle_async(self: ToolMessage) -> Any:
-                return await self.call_tool_async()  # type: ignore[attr-defined]
+            # 3) define handle_async() method with optional agent parameter
+            from typing import Union
+
+            async def handle_async(
+                self: ToolMessage, agent: Optional[Agent] = None
+            ) -> Union[str, Optional[ChatDocument]]:
+                """
+                Auto-generated handler for MCP tool. Returns ChatDocument with files
+                if files are present and agent is provided, otherwise returns text.
+
+                To override: define your own handle_async method with matching signature
+                if you need file handling, or simpler signature if you only need text.
+                """
+                response = await self.call_tool_async()  # type: ignore[attr-defined]
+                if response is None:
+                    return None
+
+                content, files = response
+
+                # If we have files and an agent is provided, return a ChatDocument
+                if files and agent is not None:
+                    return agent.create_agent_response(
+                        content=content,
+                        files=files,
+                    )
+                else:
+                    # Otherwise, just return the text content
+                    return str(content) if content is not None else None
 
             # add the handle_async() method to the tool model
             tool_model.handle_async = handle_async  # type: ignore
@@ -251,7 +323,13 @@ class FastMCPClient:
         handling nested schemas, with `handle_async` methods
         """
         if not self.client:
-            raise RuntimeError("Client not initialized. Use async with FastMCPClient.")
+            if self.persist_connection:
+                await self.connect()
+                assert self.client
+            else:
+                raise RuntimeError(
+                    "Client not initialized. Use async with FastMCPClient."
+                )
         resp = await self.client.list_tools()
         return [await self.get_tool_async(t.name) for t in resp]
 
@@ -267,7 +345,13 @@ class FastMCPClient:
             The raw Tool object from the server, or None.
         """
         if not self.client:
-            raise RuntimeError("Client not initialized. Use async with FastMCPClient.")
+            if self.persist_connection:
+                await self.connect()
+                assert self.client
+            else:
+                raise RuntimeError(
+                    "Client not initialized. Use async with FastMCPClient."
+                )
         resp: List[Tool] = await self.client.list_tools()
         return next((t for t in resp if t.name == name), None)
 
@@ -275,7 +359,7 @@ class FastMCPClient:
         self,
         tool_name: str,
         result: CallToolResult,
-    ) -> List[str] | str | None:
+    ) -> Optional[str | tuple[str, list[FileAttachment]]]:
         if result.isError:
             # Log more detailed error information
             error_content = None
@@ -293,26 +377,41 @@ class FastMCPClient:
             )
             return f"ERROR: Tool call failed - {error_content}"
 
-        has_nontext_results = any(
-            not isinstance(item, TextContent) for item in result.content
-        )
-        if has_nontext_results:
-            self.logger.warning(
-                f"""
-                MCP Tool {tool_name} returned non-text results,
-                which will be skipped.
-                """,
-            )
-        results = [
+        results_text = [
             item.text for item in result.content if isinstance(item, TextContent)
         ]
-        if len(results) == 1:
-            return results[0]
-        return results
+        results_file = []
+
+        for item in result.content:
+            if isinstance(item, ImageContent) and self.forward_images:
+                results_file.append(
+                    FileAttachment.from_bytes(
+                        b64decode(item.data),
+                        mime_type=item.mimeType,
+                    )
+                )
+            elif isinstance(item, EmbeddedResource):
+                if (
+                    isinstance(item.resource, TextResourceContents)
+                    and self.forward_text_resources
+                ):
+                    results_text.append(item.resource.text)
+                elif (
+                    isinstance(item.resource, BlobResourceContents)
+                    and self.forward_blob_resources
+                ):
+                    results_file.append(
+                        FileAttachment.from_io(
+                            BytesIO(b64decode(item.resource.blob)),
+                            mime_type=item.resource.mimeType,
+                        )
+                    )
+
+        return "\n".join(results_text), results_file
 
     async def call_mcp_tool(
         self, tool_name: str, arguments: Dict[str, Any]
-    ) -> str | List[str] | None:
+    ) -> Optional[tuple[str, list[FileAttachment]]]:
         """Call an MCP tool with the given arguments.
 
         Args:
@@ -323,12 +422,23 @@ class FastMCPClient:
             The result of the tool call.
         """
         if not self.client:
-            raise RuntimeError("Client not initialized. Use async with FastMCPClient.")
+            if self.persist_connection:
+                await self.connect()
+                assert self.client
+            else:
+                raise RuntimeError(
+                    "Client not initialized. Use async with FastMCPClient."
+                )
         result: CallToolResult = await self.client.session.call_tool(
             tool_name,
             arguments,
         )
-        return self._convert_tool_result(tool_name, result)
+        results = self._convert_tool_result(tool_name, result)
+
+        if isinstance(results, str):
+            return results, []
+
+        return results
 
 
 # ==============================================================================

{langroid-0.54.1.dist-info → langroid-0.54.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langroid
-Version: 0.54.1
+Version: 0.54.2
 Summary: Harness LLMs with Multi-Agent Programming
 Author-email: Prasad Chalasani <pchalasani@gmail.com>
 License: MIT

{langroid-0.54.1.dist-info → langroid-0.54.2.dist-info}/RECORD

@@ -3,7 +3,7 @@ langroid/exceptions.py,sha256=OPjece_8cwg94DLPcOGA1ddzy5bGh65pxzcHMnssTz8,2995
 langroid/mytypes.py,sha256=HIcYAqGeA9OK0Hlscym2FI5Oax9QFljDZoVgRlomhRk,4014
 langroid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 langroid/agent/__init__.py,sha256=ll0Cubd2DZ-fsCMl7e10hf9ZjFGKzphfBco396IKITY,786
-langroid/agent/base.py,sha256=9ZA2PhluFXReeqtGr7mdOUZZ7AXX6Eg_YymzdniUB-E,80181
+langroid/agent/base.py,sha256=a45iqoWet2W60h4wUIOyHDYlotgS0asqIjfbONT4fZQ,85706
 langroid/agent/batch.py,sha256=wpE9RqCNDVDhAXkCB7wEqfCIEAi6qKcrhaZ-Zr9T4C0,21375
 langroid/agent/chat_agent.py,sha256=2HIYzYxkrGkRIS97ioKfIqjaW3RbX89M39LjzBobBEY,88381
 langroid/agent/chat_document.py,sha256=6O20Fp4QrquykaF2jFtwNHkvcoDte1LLwVZNk9mVH9c,18057
@@ -56,7 +56,7 @@ langroid/agent/tools/segment_extract_tool.py,sha256=__srZ_VGYLVOdPrITUM8S0HpmX4q
 langroid/agent/tools/tavily_search_tool.py,sha256=soI-j0HdgVQLf09wRQScaEK4b5RpAX9C4cwOivRFWWI,1903
 langroid/agent/tools/mcp/__init__.py,sha256=DJNM0VeFnFS3pJKCyFGggT8JVjVu0rBzrGzasT1HaSM,387
 langroid/agent/tools/mcp/decorators.py,sha256=h7dterhsmvWJ8q4mp_OopmuG2DF71ty8cZwOyzdDZuk,1127
-langroid/agent/tools/mcp/fastmcp_client.py,sha256=WF3MhksDH2MzwXZF8cilMhux0hUmj6Z0dDdBYQMZwRs,18008
+langroid/agent/tools/mcp/fastmcp_client.py,sha256=rxdNRinJoxFLbuTEAy7gVocC0jFRwcwDcoz9KAJN7sg,22068
 langroid/cachedb/__init__.py,sha256=G2KyNnk3Qkhv7OKyxTOnpsxfDycx3NY0O_wXkJlalNY,96
 langroid/cachedb/base.py,sha256=ztVjB1DtN6pLCujCWnR6xruHxwVj3XkYniRTYAKKqk0,1354
 langroid/cachedb/redis_cachedb.py,sha256=7kgnbf4b5CKsCrlL97mHWKvdvlLt8zgn7lc528jEpiE,5141
@@ -133,7 +133,7 @@ langroid/vector_store/pineconedb.py,sha256=otxXZNaBKb9f_H75HTaU3lMHiaR2NUp5MqwLZ
 langroid/vector_store/postgres.py,sha256=wHPtIi2qM4fhO4pMQr95pz1ZCe7dTb2hxl4VYspGZoA,16104
 langroid/vector_store/qdrantdb.py,sha256=O6dSBoDZ0jzfeVBd7LLvsXu083xs2fxXtPa9gGX3JX4,18443
 langroid/vector_store/weaviatedb.py,sha256=Yn8pg139gOy3zkaPfoTbMXEEBCiLiYa1MU5d_3UA1K4,11847
-langroid-0.54.1.dist-info/METADATA,sha256=uamTXuB82_ONKDncZCXu8Lz_Xu1VpL2DT56kaaFLbDY,65395
-langroid-0.54.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-langroid-0.54.1.dist-info/licenses/LICENSE,sha256=EgVbvA6VSYgUlvC3RvPKehSg7MFaxWDsFuzLOsPPfJg,1065
-langroid-0.54.1.dist-info/RECORD,,
+langroid-0.54.2.dist-info/METADATA,sha256=MyoCOXBAWkcArSbJp4sYz9ORHKlYwpcyo2zOAUxe5TQ,65395
+langroid-0.54.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langroid-0.54.2.dist-info/licenses/LICENSE,sha256=EgVbvA6VSYgUlvC3RvPKehSg7MFaxWDsFuzLOsPPfJg,1065
+langroid-0.54.2.dist-info/RECORD,,