langroid 0.10.2__py3-none-any.whl → 0.11.0__py3-none-any.whl

langroid/agent/task.py

@@ -18,7 +18,9 @@ from typing import (
     Optional,
     Tuple,
     Type,
+    TypeVar,
     cast,
+    overload,
 )
 
 import numpy as np
@@ -33,8 +35,8 @@ from langroid.agent.chat_document import (
     ChatDocument,
     StatusCode,
 )
-from langroid.agent.tool_message import FinalResultTool, ToolMessage
-from langroid.agent.tools.orchestration import AgentDoneTool, DoneTool
+from langroid.agent.tool_message import ToolMessage
+from langroid.agent.tools.orchestration import AgentDoneTool, DoneTool, FinalResultTool
 from langroid.cachedb.redis_cachedb import RedisCache, RedisCacheConfig
 from langroid.exceptions import InfiniteLoopException
 from langroid.mytypes import Entity
@@ -53,11 +55,14 @@ from langroid.utils.constants import (
 from langroid.utils.logging import RichFileLogger, setup_file_logger
 from langroid.utils.object_registry import scheduled_cleanup
 from langroid.utils.system import hash
+from langroid.utils.types import to_string
 
 logger = logging.getLogger(__name__)
 
 Responder = Entity | Type["Task"]
 
+T = TypeVar("T")
+
 
 def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
     pass
@@ -153,6 +158,7 @@ class Task:
         erase_substeps: bool = False,
         allow_null_result: bool = False,
         max_stalled_steps: int = 5,
+        default_return_type: Optional[type] = None,
         done_if_no_response: List[Responder] = [],
         done_if_response: List[Responder] = [],
         config: TaskConfig = TaskConfig(),
@@ -190,6 +196,8 @@ class Task:
             default_human_response (str|None): default response from user; useful for
                 testing, to avoid interactive input from user.
                 [Instead of this, setting `interactive` usually suffices]
+            default_return_type: if not None, extracts a value of this type from the
+                result of self.run()
             interactive (bool): if true, wait for human input after each non-human
                 response (prevents infinite loop of non-human responses).
                 Default is true. If false, then `default_human_response` is set to ""
@@ -298,6 +306,7 @@ class Task:
         self.agent.interactive = interactive
         self.only_user_quits_root = only_user_quits_root
         self.message_history_idx = -1
+        self.default_return_type = default_return_type
 
         # set to True if we want to collapse multi-turn conversation with sub-tasks into
         # just the first outgoing message and last incoming message.
@@ -582,16 +591,50 @@ class Task:
         for t in self.sub_tasks:
             t.reset_all_sub_tasks()
 
+    def __getitem__(self, return_type: type) -> Task:
+        """Returns a (shallow) copy of `self` with a default return type."""
+        clone = copy.copy(self)
+        clone.default_return_type = return_type
+        return clone
+
+    @overload
+    def run(  # noqa
+        self,
+        msg: Any = None,
+        *,
+        turns: int = -1,
+        caller: None | Task = None,
+        max_cost: float = 0,
+        max_tokens: int = 0,
+        session_id: str = "",
+        allow_restart: bool = True,
+    ) -> Optional[ChatDocument]: ...  # noqa
+
+    @overload
+    def run(  # noqa
+        self,
+        msg: Any = None,
+        *,
+        turns: int = -1,
+        caller: None | Task = None,
+        max_cost: float = 0,
+        max_tokens: int = 0,
+        session_id: str = "",
+        allow_restart: bool = True,
+        return_type: Type[T],
+    ) -> Optional[T]: ...  # noqa
+
     def run(
         self,
-        msg: Optional[str | ChatDocument] = None,
+        msg: Any = None,
         turns: int = -1,
         caller: None | Task = None,
         max_cost: float = 0,
         max_tokens: int = 0,
         session_id: str = "",
         allow_restart: bool = True,
-    ) -> Optional[ChatDocument]:
+        return_type: Optional[Type[T]] = None,
+    ) -> Optional[ChatDocument | T]:
         """Synchronous version of `run_async()`.
         See `run_async()` for details."""
         if allow_restart and (
@@ -614,19 +657,18 @@ class Task:
         self._init_message_counter()
         self.history.clear()
 
-        assert (
-            msg is None or isinstance(msg, str) or isinstance(msg, ChatDocument)
-        ), f"msg arg in Task.run() must be None, str, or ChatDocument, not {type(msg)}"
+        msg_input = self.agent.to_ChatDocument(msg, author_entity=Entity.USER)
 
         if (
-            isinstance(msg, ChatDocument)
-            and msg.metadata.recipient != ""
-            and msg.metadata.recipient != self.name
+            isinstance(msg_input, ChatDocument)
+            and msg_input.metadata.recipient != ""
+            and msg_input.metadata.recipient != self.name
         ):
             # this task is not the intended recipient so return None
             return None
+
         self._pre_run_loop(
-            msg=msg,
+            msg=msg_input,
             caller=caller,
             is_async=False,
         )
@@ -677,24 +719,60 @@ class Task:
 
         final_result = self.result(status)
         self._post_run_loop()
+        if final_result is None:
+            return None
+
+        if return_type is None:
+            return_type = self.default_return_type
+
+        if return_type is not None and return_type != ChatDocument:
+            return self.agent.from_ChatDocument(final_result, return_type)
         return final_result
 
+    @overload
+    async def run_async(  # noqa
+        self,
+        msg: Any = None,
+        *,
+        turns: int = -1,
+        caller: None | Task = None,
+        max_cost: float = 0,
+        max_tokens: int = 0,
+        session_id: str = "",
+        allow_restart: bool = True,
+    ) -> Optional[ChatDocument]: ...  # noqa
+
+    @overload
+    async def run_async(  # noqa
+        self,
+        msg: Any = None,
+        *,
+        turns: int = -1,
+        caller: None | Task = None,
+        max_cost: float = 0,
+        max_tokens: int = 0,
+        session_id: str = "",
+        allow_restart: bool = True,
+        return_type: Type[T],
+    ) -> Optional[T]: ...  # noqa
+
     async def run_async(
         self,
-        msg: Optional[str | ChatDocument] = None,
+        msg: Any = None,
         turns: int = -1,
         caller: None | Task = None,
         max_cost: float = 0,
         max_tokens: int = 0,
         session_id: str = "",
         allow_restart: bool = True,
-    ) -> Optional[ChatDocument]:
+        return_type: Optional[Type[T]] = None,
+    ) -> Optional[ChatDocument | T]:
         """
         Loop over `step()` until task is considered done or `turns` is reached.
         Runs asynchronously.
 
         Args:
-            msg (str|ChatDocument): initial *user-role* message to process; if None,
+            msg (Any): initial *user-role* message to process; if None,
                 the LLM will respond to its initial `self.task_messages`
                 which set up and kick off the overall task.
                 The agent tries to achieve this goal by looping
@@ -710,6 +788,7 @@ class Task:
             max_tokens (int): max tokens allowed for the task (default 0 -> no limit)
             session_id (str): session id for the task
             allow_restart (bool): whether to allow restarting the task
+            return_type (Optional[Type[T]]): desired final result type
 
         Returns:
             Optional[ChatDocument]: valid result of the task.
@@ -740,17 +819,20 @@ class Task:
         self._init_message_counter()
         self.history.clear()
 
+        msg_input = self.agent.to_ChatDocument(msg, author_entity=Entity.USER)
+
         if (
-            isinstance(msg, ChatDocument)
-            and msg.metadata.recipient != ""
-            and msg.metadata.recipient != self.name
+            isinstance(msg_input, ChatDocument)
+            and msg_input.metadata.recipient != ""
+            and msg_input.metadata.recipient != self.name
         ):
             # this task is not the intended recipient so return None
             return None
+
         self._pre_run_loop(
-            msg=msg,
+            msg=msg_input,
             caller=caller,
-            is_async=True,
+            is_async=False,
         )
         # self.turns overrides if it is > 0 and turns not set (i.e. = -1)
         turns = self.turns if turns < 0 else turns
@@ -800,6 +882,14 @@ class Task:
 
         final_result = self.result(status)
         self._post_run_loop()
+        if final_result is None:
+            return None
+
+        if return_type is None:
+            return_type = self.default_return_type
+
+        if return_type is not None and return_type != ChatDocument:
+            return self.agent.from_ChatDocument(final_result, return_type)
         return final_result
 
     def _pre_run_loop(
@@ -1246,7 +1336,13 @@ class Task:
         else:
             response_fn = self._entity_responder_map[cast(Entity, e)]
             result = response_fn(self.pending_message)
-        return self._process_result_routing(result, e)
+
+        result_chat_doc = self.agent.to_ChatDocument(
+            result,
+            chat_doc=self.pending_message,
+            author_entity=e if isinstance(e, Entity) else Entity.USER,
+        )
+        return self._process_result_routing(result_chat_doc, e)
 
     def _process_result_routing(
         self, result: ChatDocument | None, e: Responder
@@ -1364,7 +1460,13 @@ class Task:
         else:
             response_fn = self._entity_responder_async_map[cast(Entity, e)]
             result = await response_fn(self.pending_message)
-        return self._process_result_routing(result, e)
+
+        result_chat_doc = self.agent.to_ChatDocument(
+            result,
+            chat_doc=self.pending_message,
+            author_entity=e if isinstance(e, Entity) else Entity.USER,
+        )
+        return self._process_result_routing(result_chat_doc, e)
 
     def result(self, status: StatusCode | None = None) -> ChatDocument | None:
         """
@@ -1386,6 +1488,7 @@ class Task:
         result_msg = self.pending_message
 
         content = result_msg.content if result_msg else ""
+        content_any = result_msg.content_any if result_msg else None
         if DONE in content:
             # assuming it is of the form "DONE: <content>"
             content = content.replace(DONE, "").strip()
@@ -1398,11 +1501,13 @@ class Task:
         for t in tool_messages:
             if isinstance(t, FinalResultTool):
                 content = ""
+                content_any = None
                 tool_messages = [t]  # pass it on to parent so it also quits
                 break
             elif isinstance(t, (AgentDoneTool, DoneTool)):
                 # there shouldn't be multiple tools like this; just take the first
-                content = t.content
+                content = to_string(t.content)
+                content_any = t.content
                 if isinstance(t, AgentDoneTool):
                     tool_messages = t.tools
                 break
@@ -1420,6 +1525,7 @@ class Task:
         # since to the "parent" task, this result is equivalent to a response from USER
         result_doc = ChatDocument(
             content=content,
+            content_any=content_any,
             oai_tool_calls=oai_tool_calls,
             oai_tool_id2result=oai_tool_id2result,
             function_call=fun_call,
@@ -1778,9 +1884,7 @@ class Task:
 
         if self.pending_message is None:
             return True
-        if isinstance(e, Task) and e.agent.has_only_unhandled_tools(
-            self.pending_message
-        ):
+        if isinstance(e, Task) and not e.agent.can_respond(self.pending_message):
             return False
 
         if self._recipient_mismatch(e):

langroid/agent/tool_message.py

@@ -15,11 +15,12 @@ from typing import Any, Dict, List, Tuple, Type
 from docstring_parser import parse
 
 from langroid.language_models.base import LLMFunctionSpec
-from langroid.pydantic_v1 import BaseModel, ConfigDict, Extra
+from langroid.pydantic_v1 import BaseModel, Extra
 from langroid.utils.pydantic_utils import (
     _recursive_purge_dict_key,
     generate_simple_schema,
 )
+from langroid.utils.types import is_instance_of
 
 
 class ToolMessage(ABC, BaseModel):
@@ -41,19 +42,18 @@ class ToolMessage(ABC, BaseModel):
     purpose: str
     id: str = ""  # placeholder for OpenAI-API tool_call_id
 
-    model_config = ConfigDict(extra=Extra.allow)
+    _allow_llm_use: bool = True  # allow an LLM to use (i.e. generate) this tool?
 
-    _handle_only: bool = False  # only allow handling, but not use (LLM-generation)?
+    # model_config = ConfigDict(extra=Extra.allow)
 
     class Config:
-        # only HANDLING allowed, NOT "use" (i.e LLM generation)
-        handle_only: bool = False
+        extra = Extra.allow
         arbitrary_types_allowed = False
         validate_all = True
         validate_assignment = True
         # do not include these fields in the generated schema
         # since we don't require the LLM to specify them
-        schema_extra = {"exclude": {"purpose", "id", "model_config"}}
+        schema_extra = {"exclude": {"purpose", "id"}}
 
     @classmethod
     def instructions(cls) -> str:
@@ -123,6 +123,15 @@ class ToolMessage(ABC, BaseModel):
     def dict_example(self) -> Dict[str, Any]:
         return self.dict(exclude=self.Config.schema_extra["exclude"])
 
+    def get_value_of_type(self, target_type: Type[Any]) -> Any:
+        """Try to find a value of a desired type in the fields of the ToolMessage."""
+        ignore_fields = self.Config.schema_extra["exclude"].union(["request"])
+        for field_name in set(self.dict().keys()) - ignore_fields:
+            value = getattr(self, field_name)
+            if is_instance_of(value, target_type):
+                return value
+        return None
+
     @classmethod
     def default_value(cls, f: str) -> Any:
         """
@@ -273,40 +282,3 @@ class ToolMessage(ABC, BaseModel):
             exclude=list(cls.Config.schema_extra["exclude"]),
         )
         return schema
-
-
-class FinalResultTool(ToolMessage):
-    """Class to use as a wrapper for sending arbitrary results from an Agent's
-    agent_response or tool handlers, to:
-    (a) trigger completion of the current task as well as all parent tasks, and
-    (b) be returned as the final result of the root task, i.e. this tool would appear
-         in the final ChatDocument's `tool_messages` list.
-    See test_tool_handlers_and_results in test_tool_messages.py, and
-    examples/basic/tool-extract-short-example.py.
-
-    Note:
-        - when defining a tool handler or agent_response, you can directly return
-            FinalResultTool(field1 = val1, ...),
-            where the values can be aribitrary data structures, including nested
-            Pydantic objs, or you can define a subclass of FinalResultTool with the
-            fields you want to return.
-        - This is a special ToolMessage that is NOT meant to be used or handled
-            by an agent.
-    """
-
-    request: str = ""
-    purpose: str = "Ignored; Wrapper for a structured message"
-    id: str = ""  # placeholder for OpenAI-API tool_call_id
-
-    _handle_only: bool = False  # only allow handling, but not use (LLM-generation)?
-
-    class Config:
-        extra = Extra.allow
-        # only HANDLING allowed, NOT "use" (i.e LLM generation)
-        handle_only: bool = False
-        arbitrary_types_allowed = False
-        validate_all = True
-        validate_assignment = True
-        # do not include these fields in the generated schema
-        # since we don't require the LLM to specify them
-        schema_extra = {"exclude": {"purpose", "id"}}

langroid/agent/tools/__init__.py

@@ -13,6 +13,8 @@ from .orchestration import (
     SendTool,
     AgentSendTool,
     DonePassTool,
+    ResultTool,
+    FinalResultTool,
 )
 
 __all__ = [
@@ -31,4 +33,6 @@ __all__ = [
     "PassTool",
     "SendTool",
     "AgentSendTool",
+    "ResultTool",
+    "FinalResultTool",
 ]

langroid/agent/tools/orchestration.py

@@ -3,12 +3,14 @@ Various tools to for agents to be able to control flow of Task, e.g.
 termination, routing to another agent, etc.
 """
 
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
 from langroid.agent.chat_agent import ChatAgent
 from langroid.agent.chat_document import ChatDocument
 from langroid.agent.tool_message import ToolMessage
 from langroid.mytypes import Entity
+from langroid.pydantic_v1 import Extra
+from langroid.utils.types import to_string
 
 
 class AgentDoneTool(ToolMessage):
@@ -17,16 +19,20 @@ class AgentDoneTool(ToolMessage):
 
     purpose: str = """
     To signal the current task is done, along with an optional message <content>
-    (default empty string) and an optional list of <tools> (default empty list).
+    of arbitrary type (default None) and an 
+    optional list of <tools> (default empty list).
     """
     request: str = "agent_done_tool"
-    content: str = ""
+    content: Any = None
     tools: List[ToolMessage] = []
-    _handle_only: bool = True
+    # only meant for agent_response or tool-handlers, not for LLM generation:
+    _allow_llm_use: bool = False
 
     def response(self, agent: ChatAgent) -> ChatDocument:
+        content_str = "" if self.content is None else to_string(self.content)
         return agent.create_agent_response(
-            self.content,
+            content=content_str,
+            content_any=self.content,
             tool_messages=[self] + self.tools,
         )
 
@@ -37,14 +43,15 @@ class DoneTool(ToolMessage):
 
     purpose = """
     To signal the current task is done, along with an optional message <content>
-    (default empty string).
+    of arbitrary type (default None).
     """
     request = "done_tool"
     content: str = ""
 
     def response(self, agent: ChatAgent) -> ChatDocument:
         return agent.create_agent_response(
-            self.content,
+            content=self.content,
+            content_any=self.content,
             tool_messages=[self],
         )
 
@@ -58,6 +65,78 @@ class DoneTool(ToolMessage):
         """
 
 
+class ResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task (similar to (Agent)DoneTool), and
+    (b) be returned as the result of the current task, i.e. this tool would appear
+         in the resulting ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/tool-extract-short-example.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            ResultTool(field1 = val1, ...),
+            where the values can be aribitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of ResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used or handled
+            by an agent.
+        - AgentDoneTool is more restrictive in that you can only send a `content`
+            or `tools` in the result.
+    """
+
+    request: str = "result_tool"
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+
+    class Config:
+        extra = Extra.allow
+        arbitrary_types_allowed = False
+        validate_all = True
+        validate_assignment = True
+        # do not include these fields in the generated schema
+        # since we don't require the LLM to specify them
+        schema_extra = {"exclude": {"purpose", "id"}}
+
+    def handle(self) -> AgentDoneTool:
+        return AgentDoneTool(tools=[self])
+
+
+class FinalResultTool(ToolMessage):
+    """Class to use as a wrapper for sending arbitrary results from an Agent's
+    agent_response or tool handlers, to:
+    (a) trigger completion of the current task as well as all parent tasks, and
+    (b) be returned as the final result of the root task, i.e. this tool would appear
+         in the final ChatDocument's `tool_messages` list.
+    See test_tool_handlers_and_results in test_tool_messages.py, and
+    examples/basic/tool-extract-short-example.py.
+
+    Note:
+        - when defining a tool handler or agent_response, you can directly return
+            FinalResultTool(field1 = val1, ...),
+            where the values can be aribitrary data structures, including nested
+            Pydantic objs, or you can define a subclass of FinalResultTool with the
+            fields you want to return.
+        - This is a special ToolMessage that is NOT meant to be used or handled
+            by an agent.
+    """
+
+    request: str = ""
+    purpose: str = "Ignored; Wrapper for a structured message"
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
+    _allow_llm_use: bool = False
+
+    class Config:
+        extra = Extra.allow
+        arbitrary_types_allowed = False
+        validate_all = True
+        validate_assignment = True
+        # do not include these fields in the generated schema
+        # since we don't require the LLM to specify them
+        schema_extra = {"exclude": {"purpose", "id"}}
+
+
 class PassTool(ToolMessage):
     """Tool for "passing" on the received msg (ChatDocument),
     so that an as-yet-unspecified agent can handle it.
@@ -206,7 +285,7 @@ class AgentSendTool(ToolMessage):
     to: str
     content: str = ""
     tools: List[ToolMessage] = []
-    _handle_only: bool = True
+    _allow_llm_use: bool = False
 
     def response(self, agent: ChatAgent) -> ChatDocument:
         return agent.create_agent_response(

langroid/language_models/mock_lm.py

@@ -10,6 +10,7 @@ from langroid.language_models.base import (
     OpenAIToolSpec,
     ToolChoiceTypes,
 )
+from langroid.utils.types import to_string
 
 
 def none_fn(x: str) -> None | str:
@@ -43,11 +44,11 @@ class MockLM(LanguageModel):
         # - response_dict
         # - response_fn
         # - default_response
+        mapped_response = self.config.response_dict.get(
+            msg, self.config.response_fn(msg) or self.config.default_response
+        )
         return lm.LLMResponse(
-            message=self.config.response_dict.get(
-                msg,
-                self.config.response_fn(msg) or self.config.default_response,
-            ),
+            message=to_string(mapped_response),
             cached=False,
         )
 

langroid/parsing/web_search.py

@@ -48,10 +48,13 @@ class WebSearchResult:
         return self.full_content[: self.max_summary_length]
 
     def get_full_content(self) -> str:
-        response: Response = requests.get(self.link)
-        soup: BeautifulSoup = BeautifulSoup(response.text, "lxml")
-        text = " ".join(soup.stripped_strings)
-        return text[: self.max_content_length]
+        try:
+            response: Response = requests.get(self.link)
+            soup: BeautifulSoup = BeautifulSoup(response.text, "lxml")
+            text = " ".join(soup.stripped_strings)
+            return text[: self.max_content_length]
+        except Exception as e:
+            return f"Error fetching content from {self.link}: {e}"
 
     def __str__(self) -> str:
         return f"Title: {self.title}\nLink: {self.link}\nSummary: {self.summary}"