langroid 0.54.1__py3-none-any.whl → 0.55.0__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/done_sequence_parser.py

@@ -0,0 +1,151 @@
+"""Parser for done sequence DSL (Domain Specific Language).
+
+Converts string patterns into DoneSequence objects for convenient task completion
+configuration.
+
+Examples:
+    "T, A" -> Tool followed by Agent response
+    "T[calculator], A" -> Specific tool 'calculator' followed by Agent response
+    "L, T, A, L" -> LLM, Tool, Agent, LLM sequence
+    "C[quit|exit]" -> Content matching regex pattern
+"""
+
+import re
+from typing import List, Union
+
+from langroid.pydantic_v1 import BaseModel
+
+from .task import AgentEvent, DoneSequence, EventType
+
+
+def parse_done_sequence(sequence: Union[str, DoneSequence]) -> DoneSequence:
+    """Parse a string pattern or return existing DoneSequence unchanged.
+
+    Args:
+        sequence: Either a DoneSequence object or a string pattern to parse
+
+    Returns:
+        DoneSequence object
+
+    Raises:
+        ValueError: If the string pattern is invalid
+    """
+    if isinstance(sequence, DoneSequence):
+        return sequence
+
+    if not isinstance(sequence, str):
+        raise ValueError(f"Expected string or DoneSequence, got {type(sequence)}")
+
+    events = _parse_string_pattern(sequence)
+    return DoneSequence(events=events)
+
+
+def _parse_string_pattern(pattern: str) -> List[AgentEvent]:
+    """Parse a string pattern into a list of AgentEvent objects.
+
+    Pattern format:
+        - Single letter codes: T, A, L, U, N, C
+        - Specific tools: T[tool_name]
+        - Content match: C[regex_pattern]
+        - Separated by commas, spaces allowed
+
+    Args:
+        pattern: String pattern to parse
+
+    Returns:
+        List of AgentEvent objects
+
+    Raises:
+        ValueError: If pattern is invalid
+    """
+    events = []
+
+    # Split by comma and strip whitespace
+    parts = [p.strip() for p in pattern.split(",")]
+
+    for part in parts:
+        if not part:
+            continue
+
+        event = _parse_event_token(part)
+        events.append(event)
+
+    if not events:
+        raise ValueError(f"No valid events found in pattern: {pattern}")
+
+    return events
+
+
+def _parse_event_token(token: str) -> AgentEvent:
+    """Parse a single event token into an AgentEvent.
+
+    Args:
+        token: Single event token (e.g., "T", "T[calc]", "C[quit|exit]")
+
+    Returns:
+        AgentEvent object
+
+    Raises:
+        ValueError: If token is invalid
+    """
+    # Check for bracket notation
+    bracket_match = re.match(r"^([A-Z])\[([^\]]+)\]$", token)
+
+    if bracket_match:
+        event_code = bracket_match.group(1)
+        param = bracket_match.group(2)
+
+        if event_code == "T":
+            # Specific tool: T[tool_name]
+            return AgentEvent(event_type=EventType.SPECIFIC_TOOL, tool_name=param)
+        elif event_code == "C":
+            # Content match: C[regex_pattern]
+            return AgentEvent(event_type=EventType.CONTENT_MATCH, content_pattern=param)
+        else:
+            raise ValueError(
+                f"Invalid event code with brackets: {event_code}. "
+                "Only T[tool] and C[pattern] are supported."
+            )
+
+    # Simple single-letter codes
+    event_map = {
+        "T": EventType.TOOL,
+        "A": EventType.AGENT_RESPONSE,
+        "L": EventType.LLM_RESPONSE,
+        "U": EventType.USER_RESPONSE,
+        "N": EventType.NO_RESPONSE,
+        "C": EventType.CONTENT_MATCH,  # C without brackets matches any content
+    }
+
+    if token in event_map:
+        return AgentEvent(event_type=event_map[token])
+
+    # If not a single letter, could be a full event type name
+    token_upper = token.upper()
+    if token_upper == "TOOL":
+        return AgentEvent(event_type=EventType.TOOL)
+    elif token_upper == "AGENT":
+        return AgentEvent(event_type=EventType.AGENT_RESPONSE)
+    elif token_upper == "LLM":
+        return AgentEvent(event_type=EventType.LLM_RESPONSE)
+    elif token_upper == "USER":
+        return AgentEvent(event_type=EventType.USER_RESPONSE)
+    else:
+        raise ValueError(
+            f"Invalid event token: '{token}'. "
+            "Valid tokens are: T, A, L, U, N, C, or T[tool_name], C[pattern]"
+        )
+
+
+def parse_done_sequences(
+    sequences: List[Union[str, DoneSequence]]
+) -> List[DoneSequence]:
+    """Parse a list of mixed string patterns and DoneSequence objects.
+
+    Args:
+        sequences: List containing strings and/or DoneSequence objects
+
+    Returns:
+        List of DoneSequence objects
+    """
+    return [parse_done_sequence(seq) for seq in sequences]

langroid/agent/task.py

@@ -6,6 +6,7 @@ import logging
 import re
 import threading
 from collections import Counter, OrderedDict, deque
+from enum import Enum
 from pathlib import Path
 from types import SimpleNamespace
 from typing import (
@@ -20,6 +21,7 @@ from typing import (
     Tuple,
     Type,
     TypeVar,
+    Union,
     cast,
     overload,
 )
@@ -69,6 +71,38 @@ def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
     pass
 
 
+class EventType(str, Enum):
+    """Types of events that can occur in a task"""
+
+    TOOL = "tool"  # Any tool generated
+    SPECIFIC_TOOL = "specific_tool"  # Specific tool by name
+    LLM_RESPONSE = "llm_response"  # LLM generates response
+    AGENT_RESPONSE = "agent_response"  # Agent responds
+    USER_RESPONSE = "user_response"  # User responds
+    CONTENT_MATCH = "content_match"  # Response matches pattern
+    NO_RESPONSE = "no_response"  # No valid response from entity
+    CUSTOM = "custom"  # Custom condition
+
+
+class AgentEvent(BaseModel):
+    """Single event in a task sequence"""
+
+    event_type: EventType
+    tool_name: Optional[str] = None  # For SPECIFIC_TOOL
+    content_pattern: Optional[str] = None  # For CONTENT_MATCH (regex)
+    responder: Optional[str] = None  # Specific responder name
+    # Optionally match only if the responder was specific entity/task
+    sender: Optional[str] = None  # Entity name or Task name that sent the message
+
+
+class DoneSequence(BaseModel):
+    """A sequence of events that triggers task completion"""
+
+    events: List[AgentEvent]
+    # Optional name for debugging
+    name: Optional[str] = None
+
+
 class TaskConfig(BaseModel):
     """Configuration for a Task. This is a container for any params that
     we didn't include in the task `__init__` method.
@@ -108,6 +142,9 @@ class TaskConfig(BaseModel):
             contains a Tool attempt by the LLM
             (including tools not handled by the agent).
             Default is False.
+        done_sequences (List[DoneSequence]): List of event sequences that trigger task
+            completion. Task is done if ANY sequence matches the recent event history.
+            Each sequence is checked against the message parent chain.
 
     """
 
@@ -120,6 +157,7 @@ class TaskConfig(BaseModel):
     allow_subtask_multi_oai_tools: bool = True
     recognize_string_signals: bool = True
     done_if_tool: bool = False
+    done_sequences: Optional[List[Union[str, DoneSequence]]] = None
 
 
 class Task:
@@ -257,6 +295,14 @@ class Task:
             set_parent_agent=noop_fn,
         )
         self.config = config
+        # Store parsed done sequences
+        self._parsed_done_sequences: Optional[List[DoneSequence]] = None
+        if self.config.done_sequences:
+            from .done_sequence_parser import parse_done_sequences
+
+            self._parsed_done_sequences = parse_done_sequences(
+                self.config.done_sequences
+            )
         # how to behave as a sub-task; can be overridden by `add_sub_task()`
         self.config_sub_task = copy.deepcopy(config)
         # counts of distinct pending messages in history,
@@ -360,6 +406,8 @@ class Task:
         self.single_round = single_round
         self.turns = -1  # no limit
         self.llm_delegate = llm_delegate
+        # Track last responder for done sequence checking
+        self._last_responder: Optional[Responder] = None
         if llm_delegate:
             if self.single_round:
                 # 0: User instructs (delegating to LLM);
@@ -1276,6 +1324,9 @@ class Task:
 
         self._update_no_answer_vars(result)
 
+        # Store the last responder for done sequence checking
+        self._last_responder = r
+
         # pending_sender is of type Responder,
         # i.e. it is either one of the agent's entities
         # OR a sub-task, that has produced a valid response.
@@ -1841,6 +1892,23 @@ class Task:
             ):
                 return (True, StatusCode.DONE)
 
+        # Check done sequences
+        if self._parsed_done_sequences and result is not None:
+            # Get the message chain from the current result
+            msg_chain = self._get_message_chain(result)
+
+            # Use last responder if r not provided
+            responder = r if r is not None else self._last_responder
+
+            # Check each sequence
+            for sequence in self._parsed_done_sequences:
+                if self._matches_sequence_with_current(
+                    msg_chain, sequence, result, responder
+                ):
+                    seq_name = sequence.name or "unnamed"
+                    logger.info(f"Task {self.name} done: matched sequence '{seq_name}'")
+                    return (True, StatusCode.DONE)
+
         allow_done_string = self.config.recognize_string_signals
         # An entity decided task is done, either via DoneTool,
         # or by explicitly saying DONE
@@ -2127,3 +2195,196 @@ class Task:
                 return False, addressee, content_to_send
 
         return None, None, None
+
+    def _classify_event(
+        self, msg: ChatDocument | None, responder: Responder | None
+    ) -> Optional[AgentEvent]:
+        """Classify a message into an AgentEvent for sequence matching."""
+        if msg is None:
+            return AgentEvent(event_type=EventType.NO_RESPONSE)
+
+        # Determine the event type based on responder and message content
+        event_type = EventType.NO_RESPONSE
+        tool_name = None
+
+        # Check if there are tool messages
+        tool_messages = self.agent.try_get_tool_messages(msg, all_tools=True)
+        if tool_messages:
+            event_type = EventType.TOOL
+            if len(tool_messages) == 1:
+                tool_name = tool_messages[0].request
+
+        # Check responder type
+        if responder == Entity.LLM and not tool_messages:
+            event_type = EventType.LLM_RESPONSE
+        elif responder == Entity.AGENT:
+            event_type = EventType.AGENT_RESPONSE
+        elif responder == Entity.USER:
+            event_type = EventType.USER_RESPONSE
+        elif isinstance(responder, Task):
+            # For sub-task responses, check the sender in metadata
+            if msg.metadata.sender == Entity.LLM:
+                event_type = EventType.LLM_RESPONSE
+            elif msg.metadata.sender == Entity.AGENT:
+                event_type = EventType.AGENT_RESPONSE
+            else:
+                event_type = EventType.USER_RESPONSE
+
+        # Get sender name
+        sender_name = None
+        if isinstance(responder, Entity):
+            sender_name = responder.value
+        elif isinstance(responder, Task):
+            sender_name = responder.name
+
+        return AgentEvent(
+            event_type=event_type,
+            tool_name=tool_name,
+            sender=sender_name,
+        )
+
+    def _get_message_chain(
+        self, msg: ChatDocument | None, max_depth: Optional[int] = None
+    ) -> List[ChatDocument]:
+        """Get the chain of messages by following parent pointers."""
+        if max_depth is None:
+            # Get max depth needed from all sequences
+            max_depth = 50  # default fallback
+            if self._parsed_done_sequences:
+                max_depth = max(len(seq.events) for seq in self._parsed_done_sequences)
+
+        chain = []
+        current = msg
+        depth = 0
+
+        while current is not None and depth < max_depth:
+            chain.append(current)
+            current = current.parent
+            depth += 1
+
+        # Reverse to get chronological order (oldest first)
+        return list(reversed(chain))
+
+    def _matches_event(self, actual: AgentEvent, expected: AgentEvent) -> bool:
+        """Check if an actual event matches an expected event pattern."""
+        # Check event type
+        if expected.event_type == EventType.SPECIFIC_TOOL:
+            if actual.event_type != EventType.TOOL:
+                return False
+            if expected.tool_name and actual.tool_name != expected.tool_name:
+                return False
+        elif actual.event_type != expected.event_type:
+            return False
+
+        # Check sender if specified
+        if expected.sender and actual.sender != expected.sender:
+            return False
+
+        # TODO: Add content pattern matching for CONTENT_MATCH type
+
+        return True
+
+    def _matches_sequence(
+        self, msg_chain: List[ChatDocument], sequence: DoneSequence
+    ) -> bool:
+        """Check if a message chain matches a done sequence.
+
+        We traverse the message chain and try to match the sequence events.
+        The events don't have to be consecutive in the chain.
+        """
+        if not sequence.events:
+            return False
+
+        # Convert messages to events
+        events = []
+        for i, msg in enumerate(msg_chain):
+            # Determine responder from metadata or by checking previous message
+            responder = None
+            if msg.metadata.sender:
+                responder = msg.metadata.sender
+            elif msg.metadata.sender_name:
+                # Could be a task name - keep as None for now since we can't resolve
+                # the actual Task object from just the name
+                responder = None
+
+            event = self._classify_event(msg, responder)
+            if event:
+                events.append(event)
+
+        # Try to match the sequence
+        seq_idx = 0
+        for event in events:
+            if seq_idx >= len(sequence.events):
+                break
+
+            expected = sequence.events[seq_idx]
+            if self._matches_event(event, expected):
+                seq_idx += 1
+
+        # Check if we matched the entire sequence
+        return seq_idx == len(sequence.events)
+
+    def _matches_sequence_with_current(
+        self,
+        msg_chain: List[ChatDocument],
+        sequence: DoneSequence,
+        current_msg: ChatDocument,
+        current_responder: Optional[Responder],
+    ) -> bool:
+        """Check if the message chain plus current message matches a done sequence.
+
+        Process messages in reverse order (newest first) and match against
+        the sequence events in reverse order.
+        """
+        # Add current message to chain if not already there
+        if not msg_chain or msg_chain[-1].id() != current_msg.id():
+            msg_chain = msg_chain + [current_msg]
+
+        # If we don't have enough messages for the sequence, can't match
+        if len(msg_chain) < len(sequence.events):
+            return False
+
+        # Process in reverse order - start from the end of both lists
+        seq_idx = len(sequence.events) - 1
+        msg_idx = len(msg_chain) - 1
+
+        while seq_idx >= 0 and msg_idx >= 0:
+            msg = msg_chain[msg_idx]
+            expected = sequence.events[seq_idx]
+
+            # Determine responder for this message
+            if msg_idx == len(msg_chain) - 1 and current_responder is not None:
+                # For the last message, use the current responder
+                responder = current_responder
+            else:
+                # For other messages, determine from metadata
+                responder = msg.metadata.sender
+
+            # Classify the event
+            event = self._classify_event(msg, responder)
+            if not event:
+                return False
+
+            # Check if it matches
+            matched = False
+
+            # Special handling for CONTENT_MATCH
+            if (
+                expected.event_type == EventType.CONTENT_MATCH
+                and expected.content_pattern
+            ):
+                if re.search(expected.content_pattern, msg.content, re.IGNORECASE):
+                    matched = True
+            elif self._matches_event(event, expected):
+                matched = True
+
+            if not matched:
+                # Strict matching - no skipping allowed
+                return False
+            else:
+                # Matched! Move to next expected event
+                seq_idx -= 1
+                msg_idx -= 1
+
+        # We matched if we've matched all events in the sequence
+        return seq_idx < 0

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.55.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: langroid
-Version: 0.54.1
+Version: 0.55.0
 Summary: Harness LLMs with Multi-Agent Programming
 Author-email: Prasad Chalasani <pchalasani@gmail.com>
 License: MIT
@@ -209,7 +209,7 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://img.shields.io/pypi/v/langroid)](https://pypi.org/project/langroid/)
 [![Downloads](https://img.shields.io/pypi/dm/langroid)](https://pypi.org/project/langroid/)
 [![Pytest](https://github.com/langroid/langroid/actions/workflows/pytest.yml/badge.svg)](https://github.com/langroid/langroid/actions/workflows/pytest.yml)
-[![codecov](https://codecov.io/gh/langroid/langroid/branch/main/graph/badge.svg?token=H94BX5F0TE)](https://codecov.io/gh/langroid/langroid)
+[![codecov](https://codecov.io/gh/langroid/langroid/graph/badge.svg)](https://codecov.io/gh/langroid/langroid)
 [![Multi-Architecture DockerHub](https://github.com/langroid/langroid/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/langroid/langroid/actions/workflows/docker-publish.yml)
 
 [![Static Badge](https://img.shields.io/badge/Documentation-blue?link=https%3A%2F%2Flangroid.github.io%2Flangroid%2F&link=https%3A%2F%2Flangroid.github.io%2Flangroid%2F)](https://langroid.github.io/langroid)

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

@@ -3,12 +3,13 @@ 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
+langroid/agent/done_sequence_parser.py,sha256=GiLTVtzzKb_YQcPpwqOajKu97RSUzZC6ae_ZagDmt_A,4425
 langroid/agent/openai_assistant.py,sha256=JkAcs02bIrgPNVvUWVR06VCthc5-ulla2QMBzux_q6o,34340
-langroid/agent/task.py,sha256=Ns9SoeMoAHDW7OEcPHJ22cgQKsHzWSt9UAWi9BFl4NM,91366
+langroid/agent/task.py,sha256=1xjey94vQRDDmXnhYCVu5D6Nw-3dVUaf_bUmXzRKxIk,101213
 langroid/agent/tool_message.py,sha256=BhjP-_TfQ2tgxuY4Yo_JHLOwwt0mJ4BwjPnREvEY4vk,14744
 langroid/agent/xml_tool_message.py,sha256=oeBKnJNoGaKdtz39XoWGMTNlVyXew2MWH5lgtYeh8wQ,15496
 langroid/agent/callbacks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
@@ -56,7 +57,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 +134,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.55.0.dist-info/METADATA,sha256=5RQdMjfiolUraCednhoHvcQVOaSHcOqxHj5e-JS3M6Q,65366
+langroid-0.55.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+langroid-0.55.0.dist-info/licenses/LICENSE,sha256=EgVbvA6VSYgUlvC3RvPKehSg7MFaxWDsFuzLOsPPfJg,1065
+langroid-0.55.0.dist-info/RECORD,,