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

langroid/language_models/base.py

@@ -9,6 +9,7 @@ from typing import (
     Callable,
     Dict,
     List,
+    Literal,
     Optional,
     Tuple,
     Type,
@@ -32,6 +33,11 @@ def noop_fn(*args: List[Any], **kwargs: Dict[str, Any]) -> None:
     pass
 
 
+FunctionCallTypes = Literal["none", "auto"]
+ToolChoiceTypes = Literal["none", "auto", "required"]
+ToolTypes = Literal["function"]
+
+
 class LLMConfig(BaseSettings):
     type: str = "openai"
     streamer: Optional[Callable[[Any], None]] = noop_fn
@@ -60,7 +66,7 @@ class LLMConfig(BaseSettings):
 
 class LLMFunctionCall(BaseModel):
     """
-    Structure of LLM response indicate it "wants" to call a function.
+    Structure of LLM response indicating it "wants" to call a function.
     Modeled after OpenAI spec for `function_call` field in ChatCompletion API.
     """
 
@@ -103,6 +109,45 @@ class LLMFunctionSpec(BaseModel):
     parameters: Dict[str, Any]
 
 
+class OpenAIToolCall(BaseModel):
+    """
+    Represents a single tool call in a list of tool calls generated by OpenAI LLM API.
+    See https://platform.openai.com/docs/api-reference/chat/create
+
+    Attributes:
+        id: The id of the tool call.
+        type: The type of the tool call;
+            only "function" is currently possible (7/26/24).
+        function: The function call.
+    """
+
+    id: str | None = None
+    type: ToolTypes = "function"
+    function: LLMFunctionCall | None = None
+
+    @staticmethod
+    def from_dict(message: Dict[str, Any]) -> "OpenAIToolCall":
+        """
+        Initialize from dictionary.
+        Args:
+            d: dictionary containing fields to initialize
+        """
+        id = message["id"]
+        type = message["type"]
+        function = LLMFunctionCall.from_dict(message["function"])
+        return OpenAIToolCall(id=id, type=type, function=function)
+
+    def __str__(self) -> str:
+        if self.function is None:
+            return ""
+        return "OAI-TOOL: " + json.dumps(self.function.dict(), indent=2)
+
+
+class OpenAIToolSpec(BaseModel):
+    type: ToolTypes
+    function: LLMFunctionSpec
+
+
 class LLMTokenUsage(BaseModel):
     prompt_tokens: int = 0
     completion_tokens: int = 0
@@ -132,18 +177,26 @@ class Role(str, Enum):
     SYSTEM = "system"
     ASSISTANT = "assistant"
     FUNCTION = "function"
+    TOOL = "tool"
 
 
 class LLMMessage(BaseModel):
     """
-    Class representing message sent to, or received from, LLM.
+    Class representing an entry in the msg-history sent to the LLM API.
+    It could be one of these:
+    - a user message
+    - an LLM ("Assistant") response
+    - a fn-call or tool-call-list from an OpenAI-compatible LLM API response
+    - a result or results from executing a fn or tool-call(s)
     """
 
     role: Role
     name: Optional[str] = None
+    tool_call_id: Optional[str] = None  # which OpenAI LLM tool this is a response to
     tool_id: str = ""  # used by OpenAIAssistant
     content: str
     function_call: Optional[LLMFunctionCall] = None
+    tool_calls: Optional[List[OpenAIToolCall]] = None
     timestamp: datetime = Field(default_factory=datetime.utcnow)
     # link to corresponding chat document, for provenance/rewind purposes
     chat_document_id: str = ""
@@ -169,6 +222,14 @@ class LLMMessage(BaseModel):
                 dict_no_none["function_call"]["arguments"] = json.dumps(
                     dict_no_none["function_call"]["arguments"]
                 )
+        if "tool_calls" in dict_no_none:
+            # convert tool calls to API format
+            for tc in dict_no_none["tool_calls"]:
+                if "arguments" in tc["function"]:
+                    # arguments must be a string
+                    tc["function"]["arguments"] = json.dumps(
+                        tc["function"]["arguments"]
+                    )
         # IMPORTANT! drop fields that are not expected in API call
         dict_no_none.pop("tool_id", None)
         dict_no_none.pop("timestamp", None)
@@ -190,7 +251,9 @@ class LLMResponse(BaseModel):
     """
 
     message: str
+    # TODO tool_id needs to generalize to multi-tool calls
     tool_id: str = ""  # used by OpenAIAssistant
+    oai_tool_calls: Optional[List[OpenAIToolCall]] = None
     function_call: Optional[LLMFunctionCall] = None
     usage: Optional[LLMTokenUsage] = None
     cached: bool = False
@@ -198,18 +261,28 @@ class LLMResponse(BaseModel):
     def __str__(self) -> str:
         if self.function_call is not None:
             return str(self.function_call)
+        elif self.oai_tool_calls:
+            return "\n".join(str(tc) for tc in self.oai_tool_calls)
         else:
             return self.message
 
     def to_LLMMessage(self) -> LLMMessage:
-        content = self.message
-        role = Role.ASSISTANT if self.function_call is None else Role.FUNCTION
-        name = None if self.function_call is None else self.function_call.name
+        """Convert LLM response to an LLMMessage, to be included in the
+        message-list sent to the API.
+        This is currently NOT used in any significant way in the library, and is only
+        provided as a utility to construct a message list for the API when directly
+        working with an LLM object.
+
+        In a `ChatAgent`, an LLM response is first converted to a ChatDocument,
+        which is in turn converted to an LLMMessage via `ChatDocument.to_LLMMessage()`
+        See `ChatAgent._prep_llm_messages()` and `ChatAgent.llm_response_messages`
+        """
         return LLMMessage(
-            role=role,
-            content=content,
-            name=name,
+            role=Role.ASSISTANT,
+            content=self.message,
+            name=None if self.function_call is None else self.function_call.name,
             function_call=self.function_call,
+            tool_calls=self.oai_tool_calls,
         )
 
     def get_recipient_and_message(
@@ -221,8 +294,9 @@ class LLMResponse(BaseModel):
         of the recipient name if specified.
 
         Two cases:
-        (a) `message` contains "TO: <name> <content>", or
-        (b) `message` is empty and `function_call` with `to: <name>`
+        (a) `message` contains addressing string "TO: <name> <content>", or
+        (b) `message` is empty and function_call/tool_call with explicit `recipient`
+
 
         Returns:
             (str): name of recipient, which may be empty string if no recipient
@@ -240,8 +314,17 @@ class LLMResponse(BaseModel):
             return recipient, msg
         else:
             msg = self.message
-
-        # It's not a function call, so continue looking to see
+            if self.oai_tool_calls is not None:
+                # get the first tool that has a recipient field, if any
+                for tc in self.oai_tool_calls:
+                    if tc.function is not None and tc.function.arguments is not None:
+                        recipient = tc.function.arguments.get(
+                            "recipient"
+                        )  # type: ignore
+                        if recipient is not None and recipient != "":
+                            return recipient, ""
+
+        # It's not a function or tool call, so continue looking to see
         # if a recipient is specified in the message.
 
         # First check if message contains "TO: <recipient> <content>"
@@ -396,9 +479,25 @@ class LanguageModel(ABC):
         self,
         messages: Union[str, List[LLMMessage]],
         max_tokens: int = 200,
+        tools: Optional[List[OpenAIToolSpec]] = None,
+        tool_choice: ToolChoiceTypes | Dict[str, str | Dict[str, str]] = "auto",
         functions: Optional[List[LLMFunctionSpec]] = None,
         function_call: str | Dict[str, str] = "auto",
     ) -> LLMResponse:
+        """
+        Get chat-completion response from LLM.
+
+        Args:
+            messages: message-history to send to the LLM
+            max_tokens: max tokens to generate
+            tools: tools available for the LLM to use in its response
+            tool_choice: tool call mode, one of "none", "auto", "required",
+                or a dict specifying a specific tool.
+            functions: functions available for LLM to call (deprecated)
+            function_call: function calling mode, "auto", "none", or a specific fn
+                    (deprecated)
+        """
+
         pass
 
     @abstractmethod
@@ -406,9 +505,12 @@ class LanguageModel(ABC):
         self,
         messages: Union[str, List[LLMMessage]],
         max_tokens: int = 200,
+        tools: Optional[List[OpenAIToolSpec]] = None,
+        tool_choice: ToolChoiceTypes | Dict[str, str | Dict[str, str]] = "auto",
         functions: Optional[List[LLMFunctionSpec]] = None,
         function_call: str | Dict[str, str] = "auto",
     ) -> LLMResponse:
+        """Async version of `chat`. See `chat` for details."""
         pass
 
     def __call__(self, prompt: str, max_tokens: int) -> LLMResponse:

langroid/language_models/mock_lm.py

@@ -4,7 +4,12 @@ from typing import Callable, Dict, List, Optional, Union
 
 import langroid.language_models as lm
 from langroid.language_models import LLMResponse
-from langroid.language_models.base import LanguageModel, LLMConfig
+from langroid.language_models.base import (
+    LanguageModel,
+    LLMConfig,
+    OpenAIToolSpec,
+    ToolChoiceTypes,
+)
 
 
 def none_fn(x: str) -> None | str:
@@ -50,6 +55,8 @@ class MockLM(LanguageModel):
         self,
         messages: Union[str, List[lm.LLMMessage]],
         max_tokens: int = 200,
+        tools: Optional[List[OpenAIToolSpec]] = None,
+        tool_choice: ToolChoiceTypes | Dict[str, str | Dict[str, str]] = "auto",
         functions: Optional[List[lm.LLMFunctionSpec]] = None,
         function_call: str | Dict[str, str] = "auto",
     ) -> lm.LLMResponse:
@@ -63,6 +70,8 @@ class MockLM(LanguageModel):
         self,
         messages: Union[str, List[lm.LLMMessage]],
         max_tokens: int = 200,
+        tools: Optional[List[OpenAIToolSpec]] = None,
+        tool_choice: ToolChoiceTypes | Dict[str, str | Dict[str, str]] = "auto",
         functions: Optional[List[lm.LLMFunctionSpec]] = None,
         function_call: str | Dict[str, str] = "auto",
     ) -> lm.LLMResponse: