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

langroid/agent/chat_agent.py

@@ -161,6 +161,7 @@ class ChatAgent(Agent):
                 DoneTool,
                 ForwardTool,
                 PassTool,
+                ResultTool,
                 SendTool,
             )
 
@@ -171,6 +172,7 @@ class ChatAgent(Agent):
             self.enable_message(DonePassTool, use=False, handle=True)
             self.enable_message(SendTool, use=False, handle=True)
             self.enable_message(AgentSendTool, use=False, handle=True)
+            self.enable_message(ResultTool, use=False, handle=True)
 
     def init_state(self) -> None:
         """
@@ -312,8 +314,7 @@ class ChatAgent(Agent):
         usable_tool_classes: List[Type[ToolMessage]] = [
             t
             for t in list(self.llm_tools_map.values())
-            if not t._handle_only
-            and t.default_value("request") in self.llm_tools_usable
+            if t.default_value("request") in self.llm_tools_usable
         ]
 
         if len(usable_tool_classes) == 0:
@@ -522,6 +523,13 @@ class ChatAgent(Agent):
         tools = self._get_tool_list(message_class)
         if message_class is not None:
             request = message_class.default_value("request")
+            if request == "":
+                raise ValueError(
+                    f"""
+                    ToolMessage class {message_class} must have a non-empty 
+                    'request' field if it is to be enabled as a tool.
+                    """
+                )
             llm_function = message_class.llm_function_schema(defaults=include_defaults)
             self.llm_functions_map[request] = llm_function
             if force:
@@ -540,8 +548,21 @@ class ChatAgent(Agent):
                 self.llm_functions_handled.discard(t)
 
             if use:
-                self.llm_tools_usable.add(t)
-                self.llm_functions_usable.add(t)
+                tool_class = self.llm_tools_map[t]
+                if tool_class._allow_llm_use:
+                    self.llm_tools_usable.add(t)
+                    self.llm_functions_usable.add(t)
+                else:
+                    logger.warning(
+                        f"""
+                        ToolMessage class {tool_class} does not allow LLM use,
+                        because `_allow_llm_use=False` either in the Tool or a 
+                        parent class of this tool;
+                        so not enabling LLM use for this tool!
+                        If you intended an LLM to use this tool, 
+                        set `_allow_llm_use=True` when you define the tool.
+                        """
+                    )
             else:
                 self.llm_tools_usable.discard(t)
                 self.llm_functions_usable.discard(t)

langroid/agent/chat_document.py

@@ -22,6 +22,7 @@ from langroid.parsing.parse_json import extract_top_level_json, top_level_json_f
 from langroid.pydantic_v1 import BaseModel, Extra
 from langroid.utils.object_registry import ObjectRegistry
 from langroid.utils.output.printing import shorten_text
+from langroid.utils.types import to_string
 
 
 class ChatDocAttachment(BaseModel):
@@ -115,6 +116,7 @@ class ChatDocument(Document):
         attachment (None | ChatDocAttachment): Any additional data attached.
     """
 
+    content_any: Any = None  # to hold arbitrary data returned by responders
     oai_tool_calls: Optional[List[OpenAIToolCall]] = None
     oai_tool_id2result: Optional[OrderedDict[str, str]] = None
     oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto"
@@ -281,6 +283,7 @@ class ChatDocument(Document):
                 ChatDocument._clean_fn_call(oai_tc.function)
         return ChatDocument(
             content=message,
+            content_any=message,
             oai_tool_calls=response.oai_tool_calls,
             function_call=response.function_call,
             metadata=ChatDocMetaData(
@@ -303,6 +306,7 @@ class ChatDocument(Document):
             message = msg  # retain the whole msg in this case
         return ChatDocument(
             content=message,
+            content_any=message,
             metadata=ChatDocMetaData(
                 source=Entity.USER,
                 sender=Entity.USER,
@@ -335,7 +339,7 @@ class ChatDocument(Document):
         tool_id = ""  # for OpenAI Assistant
         chat_document_id: str = ""
         if isinstance(message, ChatDocument):
-            content = message.content
+            content = message.content or to_string(message.content_any) or ""
             fun_call = message.function_call
             oai_tool_calls = message.oai_tool_calls
             if message.metadata.sender == Entity.USER and fun_call is not None:

langroid/agent/special/doc_chat_agent.py

@@ -1253,12 +1253,12 @@ class DocChatAgent(ChatAgent):
             interactive=False,
         )
 
-        extracts = run_batch_tasks(
+        extracts: list[str] = run_batch_tasks(
             task,
             passages,
             input_map=lambda msg: msg.content,
             output_map=lambda ans: ans.content if ans is not None else NO_ANSWER,
-        )
+        )  # type: ignore
 
         # Caution: Retain ALL other fields in the Documents (which could be
         # other than just `content` and `metadata`), while simply replacing

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(
@@ -910,9 +1000,10 @@ class Task:
             and not self.human_tried
             and not self.agent.has_tool_message_attempt(self.pending_message)
         ):
-            # When in interactive mode,
             # Give human first chance if they haven't been tried in last step,
             # and the msg is not a tool-call attempt;
+            # (When `interactive=False`, human is only allowed to respond only if
+            #  if explicitly addressed)
             # This ensures human gets a chance to respond,
             #   other than to a LLM tool-call.
             # When there's a tool msg attempt we want the
@@ -1246,7 +1337,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 +1461,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 +1489,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 +1502,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 +1526,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 +1885,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",
 ]