langroid 0.6.7__py3-none-any.whl → 0.8.0__py3-none-any.whl

langroid/agent/chat_document.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import copy
 import json
 from enum import Enum
-from typing import Any, List, Optional, Union, cast
+from typing import Any, Dict, List, Optional, Union, cast
 
 from langroid.agent.tool_message import ToolMessage
 from langroid.language_models.base import (
@@ -11,7 +11,9 @@ from langroid.language_models.base import (
     LLMMessage,
     LLMResponse,
     LLMTokenUsage,
+    OpenAIToolCall,
     Role,
+    ToolChoiceTypes,
 )
 from langroid.mytypes import DocMetaData, Document, Entity
 from langroid.parsing.agent_chats import parse_message
@@ -51,6 +53,8 @@ class ChatDocMetaData(DocMetaData):
     agent_id: str = ""  # ChatAgent that generated this message
     msg_idx: int = -1  # index of this message in the agent `message_history`
     sender: Entity  # sender of the message
+    # tool_id corresponding to single tool result in ChatDocument.content
+    oai_tool_id: str | None = None
     tool_ids: List[str] = []  # stack of tool_ids; used by OpenAIAssistant
     block: None | Entity = None
     sender_name: str = ""
@@ -86,6 +90,31 @@ class ChatDocLoggerFields(BaseModel):
 
 
 class ChatDocument(Document):
+    """
+    Represents a message in a conversation among agents. All responders of an agent
+    have signature ChatDocument -> ChatDocument (modulo None, str, etc),
+    and so does the Task.run() method.
+
+    Attributes:
+        oai_tool_calls (List[OpenAIToolCall]): Tool-calls from an OpenAI-compatible API
+        oai_tool_id2results (Dict[str, str]): Results of tool-calls from OpenAI
+            (dict is a map of tool_id -> result)
+        oai_tool_choice: ToolChoiceTypes | Dict[str, str]: Param controlling how the
+            LLM should choose tool-use in its response
+            (auto, none, required, or a specific tool)
+        function_call (LLMFunctionCall): Function-call from an OpenAI-compatible API
+                (deprecated; use oai_tool_calls instead)
+        tool_messages (List[ToolMessage]): Langroid ToolMessages extracted from
+            - `content` field (via JSON parsing),
+            - `oai_tool_calls`, or
+            - `function_call`
+        metadata (ChatDocMetaData): Metadata for the message, e.g. sender, recipient.
+        attachment (None | ChatDocAttachment): Any additional data attached.
+    """
+
+    oai_tool_calls: Optional[List[OpenAIToolCall]] = None
+    oai_tool_id2result: Optional[Dict[str, str]] = None
+    oai_tool_choice: ToolChoiceTypes | Dict[str, Dict[str, str] | str] = "auto"
     function_call: Optional[LLMFunctionCall] = None
     tool_messages: List[ToolMessage] = []
     metadata: ChatDocMetaData
@@ -198,6 +227,24 @@ class ChatDocument(Document):
         if len(self.metadata.tool_ids) > 0:
             self.metadata.tool_ids.pop()
 
+    @staticmethod
+    def _clean_fn_call(fc: LLMFunctionCall | None) -> None:
+        # Sometimes an OpenAI LLM (esp gpt-4o) may generate a function-call
+        # with odditities:
+        # (a) the `name` is set, as well as `arguments.request` is set,
+        #  and in langroid we use the `request` value as the `name`.
+        #  In this case we override the `name` with the `request` value.
+        # (b) the `name` looks like "functions blah" or just "functions"
+        #   In this case we strip the "functions" part.
+        if fc is None:
+            return
+        fc.name = fc.name.replace("functions", "").strip()
+        if fc.arguments is not None:
+            request = fc.arguments.get("request")
+            if request is not None and request != "":
+                fc.name = request
+                fc.arguments.pop("request")
+
     @staticmethod
     def from_LLMResponse(
         response: LLMResponse,
@@ -216,22 +263,14 @@ class ChatDocument(Document):
         if message in ["''", '""']:
             message = ""
         if response.function_call is not None:
-            # Sometimes an OpenAI LLM (esp gpt-4o) may generate a function-call
-            # with odditities:
-            # (a) the `name` is set, as well as `arugments.request` is set,
-            #  and in langroid we use the `request` value as the `name`.
-            #  In this case we override the `name` with the `request` value.
-            # (b) the `name` looks like "functions blah" or just "functions"
-            #   In this case we strip the "functions" part.
-            fc = response.function_call
-            fc.name = fc.name.replace("functions", "").strip()
-            if fc.arguments is not None:
-                request = fc.arguments.get("request")
-                if request is not None and request != "":
-                    fc.name = request
-                    fc.arguments.pop("request")
+            ChatDocument._clean_fn_call(response.function_call)
+        if response.oai_tool_calls is not None:
+            # there must be at least one if it's not None
+            for oai_tc in response.oai_tool_calls:
+                ChatDocument._clean_fn_call(oai_tc.function)
         return ChatDocument(
             content=message,
+            oai_tool_calls=response.oai_tool_calls,
             function_call=response.function_call,
             metadata=ChatDocMetaData(
                 source=Entity.LLM,
@@ -261,24 +300,33 @@ class ChatDocument(Document):
         )
 
     @staticmethod
-    def to_LLMMessage(message: Union[str, "ChatDocument"]) -> LLMMessage:
+    def to_LLMMessage(
+        message: Union[str, "ChatDocument"],
+        oai_tools: Optional[List[OpenAIToolCall]] = None,
+    ) -> List[LLMMessage]:
         """
-        Convert to LLMMessage for use with LLM.
+        Convert to list of LLMMessage, to incorporate into msg-history sent to LLM API.
+        Usually there will be just a single LLMMessage, but when the ChatDocument
+        contains results from multiple OpenAI tool-calls, we would have a sequence
+        LLMMessages, one per tool-call result.
 
         Args:
             message (str|ChatDocument): Message to convert.
+            oai_tools (Optional[List[OpenAIToolCall]]): Tool-calls currently awaiting
+                response, from the ChatAgent's latest message.
         Returns:
-            LLMMessage: LLMMessage representation of this str or ChatDocument.
-
+            List[LLMMessage]: list of LLMMessages corresponding to this ChatDocument.
         """
         sender_name = None
         sender_role = Role.USER
         fun_call = None
-        tool_id = ""
+        oai_tool_calls = None
+        tool_id = ""  # for OpenAI Assistant
         chat_document_id: str = ""
         if isinstance(message, ChatDocument):
             content = message.content
             fun_call = message.function_call
+            oai_tool_calls = message.oai_tool_calls
             if message.metadata.sender == Entity.USER and fun_call is not None:
                 # This may happen when a (parent agent's) LLM generates a
                 # a Function-call, and it ends up being sent to the current task's
@@ -289,6 +337,10 @@ class ChatDocument(Document):
                 # in the content of the message.
                 content += " " + str(fun_call)
                 fun_call = None
+            if message.metadata.sender == Entity.USER and oai_tool_calls is not None:
+                # same reasoning as for function-call above
+                content += " " + "\n\n".join(str(tc) for tc in oai_tool_calls)
+                oai_tool_calls = None
             sender_name = message.metadata.sender_name
             tool_ids = message.metadata.tool_ids
             tool_id = tool_ids[-1] if len(tool_ids) > 0 else ""
@@ -299,22 +351,74 @@ class ChatDocument(Document):
                 message.metadata.parent is not None
                 and message.metadata.parent.function_call is not None
             ):
+                # This is a response to a function call, so set the role to FUNCTION.
                 sender_role = Role.FUNCTION
                 sender_name = message.metadata.parent.function_call.name
+            elif oai_tools is not None and len(oai_tools) > 0:
+                pending_tool_ids = [tc.id for tc in oai_tools]
+                # The ChatAgent has pending OpenAI tool-call(s),
+                # so the current ChatDocument contains
+                # results for some/all/none of them.
+
+                if len(oai_tools) == 1:
+                    # Case 1:
+                    # There was exactly 1 pending tool-call, and in this case
+                    # the result would be a plain string in `content`
+                    return [
+                        LLMMessage(
+                            role=Role.TOOL,
+                            tool_call_id=oai_tools[0].id,
+                            content=content,
+                            chat_document_id=chat_document_id,
+                        )
+                    ]
+
+                elif (
+                    message.metadata.oai_tool_id is not None
+                    and message.metadata.oai_tool_id in pending_tool_ids
+                ):
+                    # Case 2:
+                    # ChatDocument.content has result of a single tool-call
+                    return [
+                        LLMMessage(
+                            role=Role.TOOL,
+                            tool_call_id=message.metadata.oai_tool_id,
+                            content=content,
+                            chat_document_id=chat_document_id,
+                        )
+                    ]
+                elif message.oai_tool_id2result is not None:
+                    # Case 2:
+                    # There were > 1 tool-calls awaiting response,
+                    assert (
+                        len(message.oai_tool_id2result) > 1
+                    ), "oai_tool_id2result must have more than 1 item."
+                    return [
+                        LLMMessage(
+                            role=Role.TOOL,
+                            tool_call_id=tool_id,
+                            content=result,
+                            chat_document_id=chat_document_id,
+                        )
+                        for tool_id, result in message.oai_tool_id2result.items()
+                    ]
             elif message.metadata.sender == Entity.LLM:
                 sender_role = Role.ASSISTANT
         else:
             # LLM can only respond to text content, so extract it
             content = message
 
-        return LLMMessage(
-            role=sender_role,
-            tool_id=tool_id,
-            content=content,
-            function_call=fun_call,
-            name=sender_name,
-            chat_document_id=chat_document_id,
-        )
+        return [
+            LLMMessage(
+                role=sender_role,
+                tool_id=tool_id,  # for OpenAI Assistant
+                content=content,
+                function_call=fun_call,
+                tool_calls=oai_tool_calls,
+                name=sender_name,
+                chat_document_id=chat_document_id,
+            )
+        ]
 
 
 LLMMessage.update_forward_refs()

langroid/agent/openai_assistant.py

@@ -79,7 +79,7 @@ class OpenAIAssistantConfig(ChatAgentConfig):
     # set to True once we can add Assistant msgs in threads
     cache_responses: bool = True
     timeout: int = 30  # can be different from llm.timeout
-    llm = OpenAIGPTConfig(chat_model=OpenAIChatModel.GPT4_TURBO)
+    llm = OpenAIGPTConfig(chat_model=OpenAIChatModel.GPT4o)
     tools: List[AssistantTool] = []
     files: List[str] = []
 
@@ -192,7 +192,7 @@ class OpenAIAssistant(ChatAgent):
             self.set_system_message(sys_msg.content)
         if not self.config.use_functions_api:
             return
-        functions, _ = self._function_args()
+        functions, _, _, _ = self._function_args()
         if functions is None:
             return
         # add the functions to the assistant:
@@ -720,7 +720,12 @@ class OpenAIAssistant(ChatAgent):
         """
         is_tool_output = False
         if message is not None:
-            llm_msg = ChatDocument.to_LLMMessage(message)
+            # note: to_LLMMessage returns a list of LLMMessage,
+            # which is allowed to have len > 1, in case the msg
+            # represents results of multiple (non-assistant) tool-calls.
+            # But for OAI Assistant, we only assume exactly one tool-call at a time.
+            # TODO look into multi-tools
+            llm_msg = ChatDocument.to_LLMMessage(message)[0]
             tool_id = llm_msg.tool_id
             if tool_id in self.pending_tool_ids:
                 if isinstance(message, ChatDocument):

langroid/agent/special/sql/sql_chat_agent.py

@@ -14,11 +14,12 @@ from rich import print
 from rich.console import Console
 
 from langroid.exceptions import LangroidImportError
+from langroid.utils.constants import DONE
 
 try:
     from sqlalchemy import MetaData, Row, create_engine, inspect, text
     from sqlalchemy.engine import Engine
-    from sqlalchemy.exc import SQLAlchemyError
+    from sqlalchemy.exc import ResourceClosedError, SQLAlchemyError
     from sqlalchemy.orm import Session, sessionmaker
 except ImportError as e:
     raise LangroidImportError(extra="sql", error=str(e))
@@ -49,8 +50,8 @@ logger = logging.getLogger(__name__)
 
 console = Console()
 
-DEFAULT_SQL_CHAT_SYSTEM_MESSAGE = """
-{mode}
+DEFAULT_SQL_CHAT_SYSTEM_MESSAGE = f"""
+{{mode}}
 
 You do not need to attempt answering a question with just one query. 
 You could make a sequence of SQL queries to help you write the final query.
@@ -64,16 +65,19 @@ are "Male" and "Female".
 
 Start by asking what I would like to know about the data.
 
+When you have FINISHED the given query or database update task, 
+say {DONE} and show your answer.
+
 """
 
-ADDRESSING_INSTRUCTION = """
+ADDRESSING_INSTRUCTION = f"""
 IMPORTANT - Whenever you are NOT writing a SQL query, make sure you address the user
-using {prefix}User. You MUST use the EXACT syntax {prefix} !!!
+using {{prefix}}User. You MUST use the EXACT syntax {{prefix}} !!!
 
 In other words, you ALWAYS write EITHER:
  - a SQL query using the `run_query` tool, 
- - OR address the user using {prefix}User.
-
+ - OR address the user using {{prefix}}User, and include {DONE} to indicate your 
+     task is FINISHED. 
 """
 
 
@@ -135,6 +139,9 @@ class SQLChatAgent(ChatAgent):
     Agent for chatting with a SQL database
     """
 
+    used_run_query: bool = False
+    llm_responded: bool = False
+
     def __init__(self, config: "SQLChatAgentConfig") -> None:
         """Initialize the SQLChatAgent.
 
@@ -246,7 +253,49 @@ class SQLChatAgent(ChatAgent):
         self.enable_message(GetTableSchemaTool)
         self.enable_message(GetColumnDescriptionsTool)
 
-    def agent_response(
+    def llm_response(
+        self, message: Optional[str | ChatDocument] = None
+    ) -> Optional[ChatDocument]:
+        self.llm_responded = True
+        return super().llm_response(message)
+
+    def user_response(
+        self,
+        msg: Optional[str | ChatDocument] = None,
+    ) -> Optional[ChatDocument]:
+        self.llm_responded = False
+        self.used_run_query = False
+        return super().user_response(msg)
+
+    def handle_message_fallback(
+        self, msg: str | ChatDocument
+    ) -> str | ChatDocument | None:
+
+        if not self.llm_responded:
+            return None
+        if self.used_run_query:
+            prefix = (
+                self.config.addressing_prefix + "User"
+                if self.config.addressing_prefix
+                else ""
+            )
+            return (
+                DONE + prefix + (msg.content if isinstance(msg, ChatDocument) else msg)
+            )
+
+        else:
+            reminder = """
+            You may have forgotten to use the `run_query` tool to execute an SQL query
+            for the user's question/request            
+            """
+            if self.config.addressing_prefix != "":
+                reminder += f"""
+                OR you may have forgotten to address the user using the prefix
+                {self.config.addressing_prefix} 
+                """
+            return reminder
+
+    def _agent_response(
         self,
         msg: Optional[str | ChatDocument] = None,
     ) -> Optional[ChatDocument]:
@@ -326,16 +375,23 @@ class SQLChatAgent(ChatAgent):
         """
         query = msg.query
         session = self.Session
-        response_message = ""
-
+        self.used_run_query = True
         try:
             logger.info(f"Executing SQL query: {query}")
 
             query_result = session.execute(text(query))
             session.commit()
-
-            rows = query_result.fetchall()
-            response_message = self._format_rows(rows)
+            try:
+                # attempt to fetch results: should work for normal SELECT queries
+                rows = query_result.fetchall()
+                response_message = self._format_rows(rows)
+            except ResourceClosedError:
+                # If we get here, it's a non-SELECT query (UPDATE, INSERT, DELETE)
+                affected_rows = query_result.rowcount  # type: ignore
+                response_message = f"""
+                    Non-SELECT query executed successfully. 
+                    Rows affected: {affected_rows}
+                    """
 
         except SQLAlchemyError as e:
             session.rollback()

langroid/agent/task.py

@@ -923,7 +923,6 @@ class Task:
                 # create dummy msg for logging
                 log_doc = ChatDocument(
                     content="[CANNOT RESPOND]",
-                    function_call=None,
                     metadata=ChatDocMetaData(
                         sender=r if isinstance(r, Entity) else Entity.USER,
                         sender_name=str(r),
@@ -1027,7 +1026,6 @@ class Task:
                 # create dummy msg for logging
                 log_doc = ChatDocument(
                     content="[CANNOT RESPOND]",
-                    function_call=None,
                     metadata=ChatDocMetaData(
                         sender=r if isinstance(r, Entity) else Entity.USER,
                         sender_name=str(r),
@@ -1111,7 +1109,7 @@ class Task:
                 self.pending_sender = r
             self.pending_message = result
         # set the parent/child links ONLY if not already set by agent internally,
-        # which may happen when using the RewindTool
+        # which may happen when using the RewindTool, or in other scenarios.
         if parent is not None and not result.metadata.parent_id:
             result.metadata.parent_id = parent.id()
         if parent is not None and not parent.metadata.child_id:
@@ -1185,8 +1183,24 @@ class Task:
                 max_cost=self.max_cost,
                 max_tokens=self.max_tokens,
             )
+            if result is not None:
+                content, id2result, oai_tool_id = self.agent._process_tool_results(
+                    result.content,
+                    result.oai_tool_id2result,
+                    (
+                        self.pending_message.oai_tool_calls
+                        if isinstance(self.pending_message, ChatDocument)
+                        else None
+                    ),
+                )
+                result.content = content
+                result.oai_tool_id2result = id2result
+                result.metadata.oai_tool_id = oai_tool_id
+
             result_str = (  # only used by callback to display content and possible tool
-                "NONE" if result is None else str(ChatDocument.to_LLMMessage(result))
+                "NONE"
+                if result is None
+                else "\n\n".join(str(m) for m in ChatDocument.to_LLMMessage(result))
             )
             maybe_tool = len(extract_top_level_json(result_str)) > 0
             self.callbacks.show_subtask_response(
@@ -1266,7 +1280,11 @@ class Task:
                 max_cost=self.max_cost,
                 max_tokens=self.max_tokens,
             )
-            result_str = str(ChatDocument.to_LLMMessage(result))
+            result_str = (  # only used by callback to display content and possible tool
+                "NONE"
+                if result is None
+                else "\n\n".join(str(m) for m in ChatDocument.to_LLMMessage(result))
+            )
             maybe_tool = len(extract_top_level_json(result_str)) > 0
             self.callbacks.show_subtask_response(
                 task=e,
@@ -1301,6 +1319,8 @@ class Task:
         if DONE in content:
             # assuming it is of the form "DONE: <content>"
             content = content.replace(DONE, "").strip()
+        oai_tool_calls = result_msg.oai_tool_calls if result_msg else None
+        oai_tool_id2result = result_msg.oai_tool_id2result if result_msg else None
         fun_call = result_msg.function_call if result_msg else None
         tool_messages = result_msg.tool_messages if result_msg else []
         block = result_msg.metadata.block if result_msg else None
@@ -1312,6 +1332,8 @@ class Task:
         # since to the "parent" task, this result is equivalent to a response from USER
         result_doc = ChatDocument(
             content=content,
+            oai_tool_calls=oai_tool_calls,
+            oai_tool_id2result=oai_tool_id2result,
             function_call=fun_call,
             tool_messages=tool_messages,
             metadata=ChatDocMetaData(
@@ -1346,6 +1368,8 @@ class Task:
                 isinstance(msg, ChatDocument)
                 and msg.content.strip() in [PASS, ""]
                 and msg.function_call is None
+                and msg.oai_tool_calls is None
+                and msg.oai_tool_id2result is None
                 and msg.tool_messages == []
             )
         )
@@ -1474,8 +1498,8 @@ class Task:
             and (result.content in USER_QUIT_STRINGS or DONE in result.content)
             and result.metadata.sender == Entity.USER
         )
-        if self._level == 0 and self.interactive and self.only_user_quits_root:
-            # for top-level task, in interactive mode, only user can quit out
+        if self._level == 0 and self._user_can_respond() and self.only_user_quits_root:
+            # for top-level task, only user can quit out
             return (user_quit, StatusCode.USER_QUIT if user_quit else StatusCode.OK)
 
         if self.is_done:
@@ -1630,14 +1654,17 @@ class Task:
             and recipient != self.name  # case sensitive
         )
 
-    def _can_respond(self, e: Responder) -> bool:
-        user_can_respond = self.interactive or (
+    def _user_can_respond(self) -> bool:
+        return self.interactive or (
             # regardless of self.interactive, if a msg is explicitly addressed to
             # user, then wait for user response
             self.pending_message is not None
             and self.pending_message.metadata.recipient == Entity.USER
         )
 
+    def _can_respond(self, e: Responder) -> bool:
+        user_can_respond = self._user_can_respond()
+
         if self.pending_sender == e or (e == Entity.USER and not user_can_respond):
             # sender is same as e (an entity cannot respond to its own msg),
             # or user cannot respond

langroid/agent/tool_message.py

@@ -39,6 +39,7 @@ class ToolMessage(ABC, BaseModel):
 
     request: str
     purpose: str
+    id: str = ""  # placeholder for OpenAI-API tool_call_id
 
     class Config:
         arbitrary_types_allowed = False
@@ -46,7 +47,7 @@ class ToolMessage(ABC, BaseModel):
         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"}}
+        schema_extra = {"exclude": {"purpose", "id"}}
 
     @classmethod
     def instructions(cls) -> str:
@@ -108,13 +109,13 @@ class ToolMessage(ABC, BaseModel):
         return "\n\n".join(examples_jsons)
 
     def to_json(self) -> str:
-        return self.json(indent=4, exclude={"purpose"})
+        return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
 
     def json_example(self) -> str:
-        return self.json(indent=4, exclude={"purpose"})
+        return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
 
     def dict_example(self) -> Dict[str, Any]:
-        return self.dict(exclude={"purpose"})
+        return self.dict(exclude=self.Config.schema_extra["exclude"])
 
     @classmethod
     def default_value(cls, f: str) -> Any:
@@ -218,7 +219,9 @@ class ToolMessage(ABC, BaseModel):
                 if "description" not in parameters["properties"][name]:
                     parameters["properties"][name]["description"] = description
 
-        excludes = ["purpose"] if request else ["request", "purpose"]
+        excludes = cls.Config.schema_extra["exclude"]
+        if not request:
+            excludes = excludes.union({"request"})
         # exclude 'excludes' from parameters["properties"]:
         parameters["properties"] = {
             field: details

langroid/agent/tools/rewind_tool.py

@@ -127,7 +127,7 @@ class RewindTool(ToolMessage):
         result_doc.metadata.msg_idx = idx
 
         # replace the message at idx with this new message
-        agent.message_history.append(ChatDocument.to_LLMMessage(result_doc))
+        agent.message_history.extend(ChatDocument.to_LLMMessage(result_doc))
 
         # set the replaced doc's parent's child to this result_doc
         if parent is not None: