langroid 0.31.2__py3-none-any.whl → 0.33.3__py3-none-any.whl

langroid/agent/tool_message.py

@@ -1,393 +0,0 @@
-"""
-Structured messages to an agent, typically from an LLM, to be handled by
-an agent. The messages could represent, for example:
-- information or data given to the agent
-- request for information or data from the agent
-- request to run a method of the agent
-"""
-
-import copy
-import json
-import textwrap
-from abc import ABC
-from random import choice
-from typing import Any, Dict, List, Optional, Tuple, Type, TypeVar
-
-from docstring_parser import parse
-
-from langroid.language_models.base import LLMFunctionSpec
-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
-
-K = TypeVar("K")
-
-
-def remove_if_exists(k: K, d: dict[K, Any]) -> None:
-    """Removes key `k` from `d` if present."""
-    if k in d:
-        d.pop(k)
-
-
-def format_schema_for_strict(schema: Any) -> None:
-    """
-    Recursively set additionalProperties to False and replace
-    oneOf and allOf with anyOf, required for OpenAI structured outputs.
-    Additionally, remove all defaults and set all fields to required.
-    This may not be equivalent to the original schema.
-    """
-    if isinstance(schema, dict):
-        if "type" in schema and schema["type"] == "object":
-            schema["additionalProperties"] = False
-
-            if "properties" in schema:
-                properties = schema["properties"]
-                all_properties = list(properties.keys())
-                for k, v in properties.items():
-                    if "default" in v:
-                        if k == "request":
-                            v["enum"] = [v["default"]]
-
-                        v.pop("default")
-                schema["required"] = all_properties
-            else:
-                schema["properties"] = {}
-                schema["required"] = []
-
-        anyOf = (
-            schema.get("oneOf", []) + schema.get("allOf", []) + schema.get("anyOf", [])
-        )
-        if "allOf" in schema or "oneOf" in schema or "anyOf" in schema:
-            schema["anyOf"] = anyOf
-
-        remove_if_exists("allOf", schema)
-        remove_if_exists("oneOf", schema)
-
-        for v in schema.values():
-            format_schema_for_strict(v)
-    elif isinstance(schema, list):
-        for v in schema:
-            format_schema_for_strict(v)
-
-
-class ToolMessage(ABC, BaseModel):
-    """
-    Abstract Class for a class that defines the structure of a "Tool" message from an
-    LLM. Depending on context, "tools" are also referred to as "plugins",
-    or "function calls" (in the context of OpenAI LLMs).
-    Essentially, they are a way for the LLM to express its intent to run a special
-    function or method. Currently these "tools" are handled by methods of the
-    agent.
-
-    Attributes:
-        request (str): name of agent method to map to.
-        purpose (str): purpose of agent method, expressed in general terms.
-            (This is used when auto-generating the tool instruction to the LLM)
-    """
-
-    request: str
-    purpose: str
-    id: str = ""  # placeholder for OpenAI-API tool_call_id
-
-    # If enabled, forces strict adherence to schema.
-    # Currently only supported by OpenAI LLMs. When unset, enables if supported.
-    _strict: Optional[bool] = None
-    _allow_llm_use: bool = True  # allow an LLM to use (i.e. generate) this tool?
-
-    # Optional param to limit number of result tokens to retain in msg history.
-    # Some tools can have large results that we may not want to fully retain,
-    # e.g. result of a db query, which the LLM later reduces to a summary, so
-    # in subsequent dialog we may only want to retain the summary,
-    # and replace this raw result truncated to _max_result_tokens.
-    # Important to note: unlike _max_result_tokens, this param is used
-    # NOT used to immediately truncate the result;
-    # it is only used to truncate what is retained in msg history AFTER the
-    # response to this result.
-    _max_retained_tokens: int | None = None
-
-    # Optional param to limit number of tokens in the result of the tool.
-    _max_result_tokens: int | None = None
-
-    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"}}
-
-    @classmethod
-    def name(cls) -> str:
-        return str(cls.default_value("request"))  # redundant str() to appease mypy
-
-    @classmethod
-    def instructions(cls) -> str:
-        """
-        Instructions on tool usage.
-        """
-        return ""
-
-    @classmethod
-    def langroid_tools_instructions(cls) -> str:
-        """
-        Instructions on tool usage when `use_tools == True`, i.e.
-        when using langroid built-in tools
-        (as opposed to OpenAI-like function calls/tools).
-        """
-        return """
-        IMPORTANT: When using this or any other tool/function, you MUST include a 
-        `request` field and set it equal to the FUNCTION/TOOL NAME you intend to use.
-        """
-
-    @classmethod
-    def require_recipient(cls) -> Type["ToolMessage"]:
-        class ToolMessageWithRecipient(cls):  # type: ignore
-            recipient: str  # no default, so it is required
-
-        return ToolMessageWithRecipient
-
-    @classmethod
-    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
-        """
-        Examples to use in few-shot demos with formatting instructions.
-        Each example can be either:
-        - just a ToolMessage instance, e.g. MyTool(param1=1, param2="hello"), or
-        - a tuple (description, ToolMessage instance), where the description is
-            a natural language "thought" that leads to the tool usage,
-            e.g. ("I want to find the square of 5",  SquareTool(num=5))
-            In some scenarios, including such a description can significantly
-            enhance reliability of tool use.
-        Returns:
-        """
-        return []
-
-    @classmethod
-    def usage_examples(cls, random: bool = False) -> str:
-        """
-        Instruction to the LLM showing examples of how to use the tool-message.
-
-        Args:
-            random (bool): whether to pick a random example from the list of examples.
-                Set to `true` when using this to illustrate a dialog between LLM and
-                user.
-                (if false, use ALL examples)
-        Returns:
-            str: examples of how to use the tool/function-call
-        """
-        # pick a random example of the fields
-        if len(cls.examples()) == 0:
-            return ""
-        if random:
-            examples = [choice(cls.examples())]
-        else:
-            examples = cls.examples()
-        formatted_examples = [
-            (
-                f"EXAMPLE {i}: (THOUGHT: {ex[0]}) => \n{ex[1].format_example()}"
-                if isinstance(ex, tuple)
-                else f"EXAMPLE {i}:\n {ex.format_example()}"
-            )
-            for i, ex in enumerate(examples, 1)
-        ]
-        return "\n\n".join(formatted_examples)
-
-    def to_json(self) -> str:
-        return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
-
-    def format_example(self) -> str:
-        return self.json(indent=4, exclude=self.Config.schema_extra["exclude"])
-
-    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:
-        """
-        Returns the default value of the given field, for the message-class
-        Args:
-            f (str): field name
-
-        Returns:
-            Any: default value of the field, or None if not set or if the
-                field does not exist.
-        """
-        schema = cls.schema()
-        properties = schema["properties"]
-        return properties.get(f, {}).get("default", None)
-
-    @classmethod
-    def format_instructions(cls, tool: bool = False) -> str:
-        """
-        Default Instructions to the LLM showing how to use the tool/function-call.
-        Works for GPT4 but override this for weaker LLMs if needed.
-
-        Args:
-            tool: instructions for Langroid-native tool use? (e.g. for non-OpenAI LLM)
-                (or else it would be for OpenAI Function calls).
-                Ignored in the default implementation, but can be used in subclasses.
-        Returns:
-            str: instructions on how to use the message
-        """
-        # TODO: when we attempt to use a "simpler schema"
-        # (i.e. all nested fields explicit without definitions),
-        # we seem to get worse results, so we turn it off for now
-        param_dict = (
-            # cls.simple_schema() if tool else
-            cls.llm_function_schema(request=True).parameters
-        )
-        examples_str = ""
-        if cls.examples():
-            examples_str = "EXAMPLES:\n" + cls.usage_examples()
-        return textwrap.dedent(
-            f"""
-            TOOL: {cls.default_value("request")}
-            PURPOSE: {cls.default_value("purpose")} 
-            JSON FORMAT: {
-                json.dumps(param_dict, indent=4)
-            }
-            {examples_str}
-            """.lstrip()
-        )
-
-    @staticmethod
-    def group_format_instructions() -> str:
-        """Template for instructions for a group of tools.
-        Works with GPT4 but override this for weaker LLMs if needed.
-        """
-        return textwrap.dedent(
-            """
-            === ALL AVAILABLE TOOLS and THEIR FORMAT INSTRUCTIONS ===
-            You have access to the following TOOLS to accomplish your task:
-
-            {format_instructions}
-            
-            When one of the above TOOLs is applicable, you must express your 
-            request as "TOOL:" followed by the request in the above format.
-            """
-        )
-
-    @classmethod
-    def llm_function_schema(
-        cls,
-        request: bool = False,
-        defaults: bool = True,
-    ) -> LLMFunctionSpec:
-        """
-        Clean up the schema of the Pydantic class (which can recursively contain
-        other Pydantic classes), to create a version compatible with OpenAI
-        Function-call API.
-
-        Adapted from this excellent library:
-        https://github.com/jxnl/instructor/blob/main/instructor/function_calls.py
-
-        Args:
-            request: whether to include the "request" field in the schema.
-                (we set this to True when using Langroid-native TOOLs as opposed to
-                OpenAI Function calls)
-            defaults: whether to include fields with default values in the schema,
-                    in the "properties" section.
-
-        Returns:
-            LLMFunctionSpec: the schema as an LLMFunctionSpec
-
-        """
-        schema = copy.deepcopy(cls.schema())
-        docstring = parse(cls.__doc__ or "")
-        parameters = {
-            k: v for k, v in schema.items() if k not in ("title", "description")
-        }
-        for param in docstring.params:
-            if (name := param.arg_name) in parameters["properties"] and (
-                description := param.description
-            ):
-                if "description" not in parameters["properties"][name]:
-                    parameters["properties"][name]["description"] = description
-
-        excludes = cls.Config.schema_extra["exclude"]
-        if not request:
-            excludes = excludes.union({"request"})
-        # exclude 'excludes' from parameters["properties"]:
-        parameters["properties"] = {
-            field: details
-            for field, details in parameters["properties"].items()
-            if field not in excludes and (defaults or details.get("default") is None)
-        }
-        parameters["required"] = sorted(
-            k
-            for k, v in parameters["properties"].items()
-            if ("default" not in v and k not in excludes)
-        )
-        if request:
-            parameters["required"].append("request")
-
-            # If request is present it must match the default value
-            # Similar to defining request as a literal type
-            parameters["request"] = {
-                "enum": [cls.default_value("request")],
-                "type": "string",
-            }
-
-        if "description" not in schema:
-            if docstring.short_description:
-                schema["description"] = docstring.short_description
-            else:
-                schema["description"] = (
-                    f"Correctly extracted `{cls.__name__}` with all "
-                    f"the required parameters with correct types"
-                )
-
-        # Handle nested ToolMessage fields
-        if "definitions" in parameters:
-            for v in parameters["definitions"].values():
-                if "exclude" in v:
-                    v.pop("exclude")
-
-                    remove_if_exists("purpose", v["properties"])
-                    remove_if_exists("id", v["properties"])
-                    if (
-                        "request" in v["properties"]
-                        and "default" in v["properties"]["request"]
-                    ):
-                        if "required" not in v:
-                            v["required"] = []
-                        v["required"].append("request")
-                        v["properties"]["request"] = {
-                            "type": "string",
-                            "enum": [v["properties"]["request"]["default"]],
-                        }
-
-        parameters.pop("exclude")
-        _recursive_purge_dict_key(parameters, "title")
-        _recursive_purge_dict_key(parameters, "additionalProperties")
-        return LLMFunctionSpec(
-            name=cls.default_value("request"),
-            description=cls.default_value("purpose"),
-            parameters=parameters,
-        )
-
-    @classmethod
-    def simple_schema(cls) -> Dict[str, Any]:
-        """
-        Return a simplified schema for the message, with only the request and
-        required fields.
-        Returns:
-            Dict[str, Any]: simplified schema
-        """
-        schema = generate_simple_schema(
-            cls,
-            exclude=list(cls.Config.schema_extra["exclude"]),
-        )
-        return schema

langroid/agent/tools/__init__.py

@@ -1,38 +0,0 @@
-from . import google_search_tool
-from . import recipient_tool
-from . import rewind_tool
-from . import orchestration
-from .google_search_tool import GoogleSearchTool
-from .recipient_tool import AddRecipientTool, RecipientTool
-from .rewind_tool import RewindTool
-from .orchestration import (
-    AgentDoneTool,
-    DoneTool,
-    ForwardTool,
-    PassTool,
-    SendTool,
-    AgentSendTool,
-    DonePassTool,
-    ResultTool,
-    FinalResultTool,
-)
-
-__all__ = [
-    "GoogleSearchTool",
-    "AddRecipientTool",
-    "RecipientTool",
-    "google_search_tool",
-    "recipient_tool",
-    "rewind_tool",
-    "RewindTool",
-    "orchestration",
-    "AgentDoneTool",
-    "DoneTool",
-    "DonePassTool",
-    "ForwardTool",
-    "PassTool",
-    "SendTool",
-    "AgentSendTool",
-    "ResultTool",
-    "FinalResultTool",
-]

langroid/agent/tools/duckduckgo_search_tool.py

@@ -1,50 +0,0 @@
-"""
-A tool to trigger a DuckDuckGo search for a given query, and return the top results with
-their titles, links, summaries. Since the tool is stateless (i.e. does not need
-access to agent state), it can be enabled for any agent, without having to define a
-special method inside the agent: `agent.enable_message(DuckduckgoSearchTool)`
-"""
-
-from typing import List, Tuple
-
-from langroid.agent.tool_message import ToolMessage
-from langroid.parsing.web_search import duckduckgo_search
-
-
-class DuckduckgoSearchTool(ToolMessage):
-    request: str = "duckduckgo_search"
-    purpose: str = """
-            To search the web and return up to <num_results> 
-            links relevant to the given <query>. When using this tool,
-            ONLY show the required JSON, DO NOT SAY ANYTHING ELSE.
-            Wait for the results of the web search, and then use them to
-            compose your response.
-            """
-    query: str
-    num_results: int
-
-    def handle(self) -> str:
-        """
-        Conducts a search using DuckDuckGo based on the provided query
-        and number of results by triggering a duckduckgo_search.
-
-        Returns:
-            str: A formatted string containing the titles, links, and
-                summaries of each search result, separated by two newlines.
-        """
-        search_results = duckduckgo_search(self.query, self.num_results)
-        # return Title, Link, Summary of each result, separated by two newlines
-        results_str = "\n\n".join(str(result) for result in search_results)
-        return f"""
-        BELOW ARE THE RESULTS FROM THE WEB SEARCH. USE THESE TO COMPOSE YOUR RESPONSE:
-        {results_str}
-        """
-
-    @classmethod
-    def examples(cls) -> List["ToolMessage" | Tuple[str, "ToolMessage"]]:
-        return [
-            cls(
-                query="When was the Llama2 Large Language Model (LLM) released?",
-                num_results=3,
-            ),
-        ]