langroid 0.1.85__py3-none-any.whl → 0.1.219__py3-none-any.whl

langroid/agent/tool_message.py

@@ -6,6 +6,8 @@ an agent. The messages could represent, for example:
 - request to run a method of the agent
 """
 
+import json
+import textwrap
 from abc import ABC
 from random import choice
 from typing import Any, Dict, List, Type
@@ -14,16 +16,10 @@ from docstring_parser import parse
 from pydantic import BaseModel
 
 from langroid.language_models.base import LLMFunctionSpec
-
-
-def _recursive_purge_dict_key(d: Dict[str, Any], k: str) -> None:
-    """Remove a key from a dictionary recursively"""
-    if isinstance(d, dict):
-        for key in list(d.keys()):
-            if key == k and "type" in d.keys():
-                del d[key]
-            else:
-                _recursive_purge_dict_key(d[key], k)
+from langroid.utils.pydantic_utils import (
+    _recursive_purge_dict_key,
+    generate_simple_schema,
+)
 
 
 class ToolMessage(ABC, BaseModel):
@@ -45,7 +41,6 @@ class ToolMessage(ABC, BaseModel):
     request: str
     purpose: str
     result: str = ""
-    recipient: str = ""  # default is empty string, so it is optional
 
     class Config:
         arbitrary_types_allowed = False
@@ -87,6 +82,9 @@ class ToolMessage(ABC, BaseModel):
         ex = choice(cls.examples())
         return ex.json_example()
 
+    def to_json(self) -> str:
+        return self.json(indent=4, exclude={"result", "purpose"})
+
     def json_example(self) -> str:
         return self.json(indent=4, exclude={"result", "purpose"})
 
@@ -109,7 +107,58 @@ class ToolMessage(ABC, BaseModel):
         return properties.get(f, {}).get("default", None)
 
     @classmethod
-    def llm_function_schema(cls, request: bool = False) -> LLMFunctionSpec:
+    def json_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)
+        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
+        )
+        return textwrap.dedent(
+            f"""
+            TOOL: {cls.default_value("request")}
+            PURPOSE: {cls.default_value("purpose")} 
+            JSON FORMAT: {
+                json.dumps(param_dict, indent=4)
+            }
+            {"EXAMPLE: " + cls.usage_example() if cls.examples() else ""}
+            """.lstrip()
+        )
+
+    @staticmethod
+    def json_group_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 JSON FORMAT INSTRUCTIONS ===
+            You have access to the following TOOLS to accomplish your task:
+
+            {json_instructions}
+            
+            When one of the above TOOLs is applicable, you must express your 
+            request as "TOOL:" followed by the request in the above JSON 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
@@ -122,6 +171,8 @@ class ToolMessage(ABC, BaseModel):
             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
@@ -146,7 +197,7 @@ class ToolMessage(ABC, BaseModel):
         parameters["properties"] = {
             field: details
             for field, details in parameters["properties"].items()
-            if field not in excludes
+            if field not in excludes and (defaults or details.get("default") is None)
         }
         parameters["required"] = sorted(
             k
@@ -173,3 +224,14 @@ class ToolMessage(ABC, BaseModel):
             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=["result", "purpose"])
+        return schema

langroid/agent/tools/__init__.py

@@ -0,0 +1,13 @@
+from .google_search_tool import GoogleSearchTool
+from .recipient_tool import AddRecipientTool, RecipientTool
+
+from . import google_search_tool
+from . import recipient_tool
+
+__all__ = [
+    "GoogleSearchTool",
+    "AddRecipientTool",
+    "RecipientTool",
+    "google_search_tool",
+    "recipient_tool",
+]

langroid/agent/tools/duckduckgo_search_tool.py

@@ -0,0 +1,66 @@
+"""
+A tool to trigger a Metaphor search for a given query,
+(https://docs.exa.ai/reference/getting-started)
+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(MetaphorSearchTool)`
+
+NOTE: To use this tool, you need to:
+
+* set the METAPHOR_API_KEY environment variables in
+your `.env` file, e.g. `METAPHOR_API_KEY=your_api_key_here`
+(Note as of 28 Jan 2023, Metaphor renamed to Exa, so you can also use
+`EXA_API_KEY=your_api_key_here`)
+
+* install langroid with the `metaphor` extra, e.g.
+`pip install langroid[metaphor]` or `poetry add langroid[metaphor]`
+(it installs the `metaphor-python` package from pypi).
+
+For more information, please refer to the official docs:
+https://metaphor.systems/
+"""
+
+from typing import List
+
+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 the metaphor API based on the provided query
+        and number of results by triggering a metaphor_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"]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+                num_results=3,
+            ),
+        ]

langroid/agent/tools/google_search_tool.py

@@ -9,6 +9,8 @@ environment variables in your `.env` file, as explained in the
 [README](https://github.com/langroid/langroid#gear-installation-and-setup).
 """
 
+from typing import List
+
 from langroid.agent.tool_message import ToolMessage
 from langroid.parsing.web_search import google_search
 
@@ -26,3 +28,12 @@ class GoogleSearchTool(ToolMessage):
         search_results = google_search(self.query, self.num_results)
         # return Title, Link, Summary of each result, separated by two newlines
         return "\n\n".join(str(result) for result in search_results)
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage"]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+                num_results=3,
+            ),
+        ]

langroid/agent/tools/metaphor_search_tool.py

@@ -0,0 +1,67 @@
+"""
+A tool to trigger a Metaphor search for a given query,
+(https://docs.exa.ai/reference/getting-started)
+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(MetaphorSearchTool)`
+
+NOTE: To use this tool, you need to:
+
+* set the METAPHOR_API_KEY environment variables in
+your `.env` file, e.g. `METAPHOR_API_KEY=your_api_key_here`
+(Note as of 28 Jan 2023, Metaphor renamed to Exa, so you can also use
+`EXA_API_KEY=your_api_key_here`)
+
+* install langroid with the `metaphor` extra, e.g.
+`pip install langroid[metaphor]` or `poetry add langroid[metaphor]`
+(it installs the `metaphor-python` package from pypi).
+
+For more information, please refer to the official docs:
+https://metaphor.systems/
+"""
+
+from typing import List
+
+from langroid.agent.tool_message import ToolMessage
+from langroid.parsing.web_search import metaphor_search
+
+
+class MetaphorSearchTool(ToolMessage):
+    request: str = "metaphor_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 the metaphor API based on the provided query
+        and number of results by triggering a metaphor_search.
+
+        Returns:
+            str: A formatted string containing the titles, links, and
+                summaries of each search result, separated by two newlines.
+        """
+
+        search_results = metaphor_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"]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+                num_results=3,
+            ),
+        ]

langroid/agent/tools/recipient_tool.py

@@ -6,25 +6,8 @@ the method `_get_tool_list()`).
 
 See usage examples in `tests/main/test_multi_agent_complex.py` and
 `tests/main/test_recipient_tool.py`.
-
-Previously we were using RecipientValidatorAgent to enforce proper
-recipient specifiction, but the preferred method is to use the
-`RecipientTool` class.  This has numerous advantages:
-- it uses the tool/function-call mechanism to specify a recipient in a JSON-structured
-    string, which is more consistent with the rest of the system, and does not require
-    inventing a new syntax like `TO:<recipient>` (which the RecipientValidatorAgent
-    uses).
-- it removes the need for any special parsing of the message content, since we leverage
-    the built-in JSON tool-matching in `Agent.handle_message()` and downstream code.
-- it does not require setting the `parent_responder` field in the `ChatDocument`
-    metadata, which is somewhat hacky.
-- it appears to be less brittle than requiring the LLM to use TO:<recipient> syntax:
-  The LLM almost never forgets to use the RecipientTool as instructed.
-- The RecipientTool class acts as a specification of the required syntax, and also
-  contains mechanisms to enforce this syntax.
-- For a developer who needs to enforce recipient specification for an agent, they only
-  need to do `agent.enable_message(RecipientTool)`, and the rest is taken care of.
 """
+
 from typing import List, Type
 
 from rich import print
@@ -62,20 +45,22 @@ class AddRecipientTool(ToolMessage):
             (ChatDocument): with content set to self.content and
                 metadata.recipient set to self.recipient.
         """
-        print(f"[red]RecipientTool: Added recipient {self.recipient} to message.")
+        print(
+            "[red]RecipientTool: "
+            f"Added recipient {self.intended_recipient} to message."
+        )
         if self.__class__.saved_content == "":
             recipient_request_name = RecipientTool.default_value("request")
-            raise ValueError(
-                f"""
+            content = f"""
                 Recipient specified but content is empty!
                 This could be because the `{self.request}` tool/function was used 
                 before using `{recipient_request_name}` tool/function.
                 Resend the message using `{recipient_request_name}` tool/function.
                 """
-            )
-        content = self.__class__.saved_content  # use class-level attrib value
-        # erase content since we just used it.
-        self.__class__.saved_content = ""
+        else:
+            content = self.__class__.saved_content  # use class-level attrib value
+            # erase content since we just used it.
+            self.__class__.saved_content = ""
         return ChatDocument(
             content=content,
             metadata=ChatDocMetaData(
@@ -91,9 +76,10 @@ class RecipientTool(ToolMessage):
     Used by LLM to send a message to a specific recipient.
 
     Useful in cases where an LLM is talking to 2 or more
-    agents, and needs to specify which agent (task) its message is intended for.
-    The recipient name should be the name of a task (which is normally the name of
-    the agent that the task wraps, although the task can have its own name).
+    agents (or an Agent and human user), and needs to specify which agent (task)
+    its message is intended for. The recipient name should be the name of a task
+    (which is normally the name of the agent that the task wraps, although the task
+    can have its own name).
 
     To use this tool/function-call, LLM must generate a JSON structure
     with these fields:
@@ -102,6 +88,7 @@ class RecipientTool(ToolMessage):
         "intended_recipient": <name_of_recipient_task_or_entity>,
         "content": <content>
     }
+    The effect of this is that `content` will be sent to the `intended_recipient` task.
     """
 
     request: str = "recipient_message"
@@ -181,7 +168,7 @@ class RecipientTool(ToolMessage):
             content=self.content,
             metadata=ChatDocMetaData(
                 recipient=self.intended_recipient,
-                # we are constructing this so it looks as it msg is from LLM
+                # we are constructing this so it looks as if msg is from LLM
                 sender=Entity.LLM,
             ),
         )

langroid/agent/tools/run_python_code.py

@@ -0,0 +1,60 @@
+import io
+import sys
+from typing import List
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class RunPythonCodeTool(ToolMessage):
+    """
+    Tool/function to run code generated by the LLM.
+    The code is assumed to be self-contained, i.e. it contains all necessary imports
+    and does not depend on any external variables.
+    """
+
+    request: str = "run_python_code"
+    purpose: str = """
+            To run python <code> and return the results to answer a question.
+            """
+    code: str
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage"]:
+        return [
+            cls(code="import numpy as np\nnp.square(9)"),
+        ]
+
+    def handle(self) -> str:
+        """
+        Handle a RunPythonCodeTool message by running the code and returning the result.
+        Returns:
+            str: The result of running the code along with any print output.
+        """
+        code = self.code
+
+        # Create a string-based I/O stream
+        code_out = io.StringIO()
+
+        # Temporarily redirect standard output to our string-based I/O stream
+        sys.stdout = code_out
+
+        try:
+            eval_result = eval(code, {})
+        except Exception as e:
+            eval_result = f"ERROR: {type(e)}: {e}"
+
+        if eval_result is None:
+            eval_result = ""
+
+        # Always restore the original standard output
+        sys.stdout = sys.__stdout__
+
+        # Get the resulting string from the I/O stream
+        print_result = code_out.getvalue() or ""
+        sep = "\n" if print_result else ""
+        # Combine the print and eval results
+        result = f"{print_result}{sep}{eval_result}"
+        if result == "":
+            result = "No result"
+        # Return the result
+        return result

langroid/agent/tools/sciphi_search_rag_tool.py

@@ -0,0 +1,79 @@
+"""
+A tool which returns a Search RAG response from the SciPhi API.
+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(SciPhiSearchRAGTool)`
+
+Example return output appears as follows below:
+
+<-- Query -->
+```
+Find 3 results on the internet about the LK-99 superconducting material.
+``
+
+<-- Response (compressed for this example)-->
+```
+[ result1 ]
+
+[ result2 ]
+
+[ result3 ]
+
+```
+
+NOTE: Using this tool requires getting an API key from sciphi.ai.
+Setup is as simple as shown below
+# Get a free API key at https://www.sciphi.ai/account
+# export SCIPHI_API_KEY=$MY_SCIPHI_API_KEY before running the agent
+# OR add SCIPHI_API_KEY=$MY_SCIPHI_API_KEY to your .env file
+
+This tool requires installing langroid with the `sciphi` extra, e.g.
+`pip install langroid[sciphi]` or `poetry add langroid[sciphi]`
+(it installs the `agent-search` package from pypi).
+
+For more information, please refer to the official docs:
+https://agent-search.readthedocs.io/en/latest/
+"""
+
+from typing import List
+
+try:
+    from agent_search import SciPhi
+except ImportError:
+    raise ImportError(
+        "You are attempting to use the `agent-search` library;"
+        "To use it, please install langroid with the `sciphi` extra, e.g. "
+        "`pip install langroid[sciphi]` or `poetry add langroid[sciphi]` "
+        "(it installs the `agent-search` package from pypi)."
+    )
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class SciPhiSearchRAGTool(ToolMessage):
+    request: str = "web_search_rag"
+    purpose: str = """
+            To search the web with provider <search_provider> and 
+            return a response summary with llm model <llm_model> the given <query>. 
+            """
+    query: str
+
+    def handle(self) -> str:
+        rag_response = SciPhi().get_search_rag_response(
+            query=self.query, search_provider="bing", llm_model="SciPhi/Sensei-7B-V1"
+        )
+        result = rag_response["response"]
+        result = (
+            f"### RAG Response:\n{result}\n\n"
+            + "### Related Queries:\n"
+            + "\n".join(rag_response["related_queries"])
+        )
+        return result  # type: ignore
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage"]:
+        return [
+            cls(
+                query="When was the Llama2 Large Language Model (LLM) released?",
+            ),
+        ]

langroid/agent/tools/segment_extract_tool.py

@@ -0,0 +1,36 @@
+"""
+A tool to extract segment numbers from the last user message,
+containing numbered segments.
+
+The idea is that when an LLM wants to (or is asked to) simply extract
+portions of a message verbatim, it should use this tool/function to
+SPECIFY what should be extracted, rather than actually extracting it.
+The output will be in the form of a list of segment numbers or ranges.
+This will usually be much cheaper and faster than actually writing out the extracted
+text. The handler of this tool/function will then extract the text and send it back.
+"""
+
+from typing import List
+
+from langroid.agent.tool_message import ToolMessage
+
+
+class SegmentExtractTool(ToolMessage):
+    request: str = "extract_segments"
+    purpose: str = """
+            To extract segments from a body of text containing numbered 
+            segments, in the form of a <segment_list> which is a list of segment 
+            numbers or ranges, like "10,12,14-17".
+            """
+    segment_list: str
+
+    @classmethod
+    def examples(cls) -> List["ToolMessage"]:
+        return [cls(segment_list="1,3,5-7")]
+
+    @classmethod
+    def instructions(cls) -> str:
+        return """
+        Use this tool/function to indicate certain segments from 
+        a body of text containing numbered segments.
+        """

langroid/cachedb/__init__.py

@@ -0,0 +1,9 @@
+from . import base
+from . import momento_cachedb
+from . import redis_cachedb
+
+__all__ = [
+    "base",
+    "momento_cachedb",
+    "redis_cachedb",
+]

langroid/cachedb/base.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List
 
 
 class CacheDB(ABC):
@@ -17,7 +17,7 @@ class CacheDB(ABC):
         pass
 
     @abstractmethod
-    def retrieve(self, key: str) -> Optional[Dict[str, Any]]:
+    def retrieve(self, key: str) -> Dict[str, Any] | str | None:
         """
         Abstract method to retrieve the value associated with a key.
 
@@ -28,3 +28,23 @@ class CacheDB(ABC):
             dict: The value associated with the key.
         """
         pass
+
+    @abstractmethod
+    def delete_keys(self, keys: List[str]) -> None:
+        """
+        Delete the keys from the cache.
+
+        Args:
+            keys (List[str]): The keys to delete.
+        """
+        pass
+
+    @abstractmethod
+    def delete_keys_pattern(self, pattern: str) -> None:
+        """
+        Delete all keys with the given pattern
+
+        Args:
+            prefix (str): The pattern to match.
+        """
+        pass

langroid/cachedb/momento_cachedb.py

@@ -2,7 +2,7 @@ import json
 import logging
 import os
 from datetime import timedelta
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List
 
 import momento
 from dotenv import load_dotenv
@@ -61,7 +61,7 @@ class MomentoCache(CacheDB):
         """
         self.client.set(self.config.cachename, key, json.dumps(value))
 
-    def retrieve(self, key: str) -> Optional[Dict[str, Any]]:
+    def retrieve(self, key: str) -> Dict[str, Any] | str | None:
         """
         Retrieve the value associated with a key.
 
@@ -76,3 +76,27 @@ class MomentoCache(CacheDB):
             return json.loads(value.value_string)  # type: ignore
         else:
             return None
+
+    def delete_keys(self, keys: List[str]) -> None:
+        """
+        Delete the keys from the cache.
+
+        Args:
+            keys (List[str]): The keys to delete.
+        """
+        for key in keys:
+            self.client.delete(self.config.cachename, key)
+
+    def delete_keys_pattern(self, pattern: str) -> None:
+        """
+        Delete the keys from the cache with the given pattern.
+
+        Args:
+            prefix (str): The pattern to match.
+        """
+        raise NotImplementedError(
+            """
+            MomentoCache does not support delete_keys_pattern.
+            Please use RedisCache instead.
+            """
+        )