langroid 0.1.139__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):
@@ -86,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"})
 
@@ -107,6 +106,53 @@ class ToolMessage(ABC, BaseModel):
         properties = schema["properties"]
         return properties.get(f, {}).get("default", None)
 
+    @classmethod
+    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,
@@ -178,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

@@ -3,3 +3,11 @@ 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
@@ -68,17 +51,16 @@ class AddRecipientTool(ToolMessage):
         )
         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(

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/cachedb/__init__.py

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

langroid/embedding_models/__init__.py

@@ -1,6 +1,11 @@
 from . import base
 from . import models
+from . import remote_embeds
 
+from .base import (
+    EmbeddingModel,
+    EmbeddingModelsConfig,
+)
 from .models import (
     OpenAIEmbeddings,
     OpenAIEmbeddingsConfig,
@@ -8,3 +13,22 @@ from .models import (
     SentenceTransformerEmbeddings,
     embedding_model,
 )
+from .remote_embeds import (
+    RemoteEmbeddingsConfig,
+    RemoteEmbeddings,
+)
+
+__all__ = [
+    "base",
+    "models",
+    "remote_embeds",
+    "EmbeddingModel",
+    "EmbeddingModelsConfig",
+    "OpenAIEmbeddings",
+    "OpenAIEmbeddingsConfig",
+    "SentenceTransformerEmbeddingsConfig",
+    "SentenceTransformerEmbeddings",
+    "embedding_model",
+    "RemoteEmbeddingsConfig",
+    "RemoteEmbeddings",
+]

langroid/embedding_models/base.py

@@ -12,6 +12,8 @@ logging.getLogger("openai").setLevel(logging.ERROR)
 class EmbeddingModelsConfig(BaseSettings):
     model_type: str = "openai"
     dims: int = 0
+    context_length: int = 512
+    batch_size: int = 512
 
 
 class EmbeddingModel(ABC):
@@ -27,8 +29,14 @@ class EmbeddingModel(ABC):
             SentenceTransformerEmbeddings,
             SentenceTransformerEmbeddingsConfig,
         )
+        from langroid.embedding_models.remote_embeds import (
+            RemoteEmbeddings,
+            RemoteEmbeddingsConfig,
+        )
 
-        if isinstance(config, OpenAIEmbeddingsConfig):
+        if isinstance(config, RemoteEmbeddingsConfig):
+            return RemoteEmbeddings(config)
+        elif isinstance(config, OpenAIEmbeddingsConfig):
             return OpenAIEmbeddings(config)
         elif isinstance(config, SentenceTransformerEmbeddingsConfig):
             return SentenceTransformerEmbeddings(config)

langroid/embedding_models/models.py

@@ -1,29 +1,93 @@
+import atexit
 import os
-from typing import Callable, List
+from typing import Callable, List, Optional
 
+import tiktoken
 from dotenv import load_dotenv
 from openai import OpenAI
 
 from langroid.embedding_models.base import EmbeddingModel, EmbeddingModelsConfig
-from langroid.language_models.utils import retry_with_exponential_backoff
 from langroid.mytypes import Embeddings
+from langroid.parsing.utils import batched
 
 
 class OpenAIEmbeddingsConfig(EmbeddingModelsConfig):
     model_type: str = "openai"
     model_name: str = "text-embedding-ada-002"
     api_key: str = ""
+    api_base: Optional[str] = None
     organization: str = ""
     dims: int = 1536
+    context_length: int = 8192
 
 
 class SentenceTransformerEmbeddingsConfig(EmbeddingModelsConfig):
     model_type: str = "sentence-transformer"
     model_name: str = "BAAI/bge-large-en-v1.5"
+    context_length: int = 512
+    data_parallel: bool = False
+    # Select device (e.g. "cuda", "cpu") when data parallel is disabled
+    device: Optional[str] = None
+    # Select devices when data parallel is enabled
+    devices: Optional[list[str]] = None
+
+
+class EmbeddingFunctionCallable:
+    """
+    A callable class designed to generate embeddings for a list of texts using
+    the OpenAI API, with automatic retries on failure.
+
+    Attributes:
+        model (OpenAIEmbeddings): An instance of OpenAIEmbeddings that provides
+                                configuration and utilities for generating embeddings.
+
+    Methods:
+        __call__(input: List[str]) -> Embeddings: Generate embeddings for
+                                a list of input texts.
+    """
+
+    def __init__(self, model: "OpenAIEmbeddings", batch_size: int = 512):
+        """
+        Initialize the EmbeddingFunctionCallable with a specific model.
+
+        Args:
+            model (OpenAIEmbeddings): An instance of OpenAIEmbeddings to use for
+            generating embeddings.
+            batch_size (int): Batch size
+        """
+        self.model = model
+        self.batch_size = batch_size
+
+    def __call__(self, input: List[str]) -> Embeddings:
+        """
+        Generate embeddings for a given list of input texts using the OpenAI API,
+        with retries on failure.
+
+        This method:
+        - Truncates each text in the input list to the model's maximum context length.
+        - Processes the texts in batches to generate embeddings efficiently.
+        - Automatically retries the embedding generation process with exponential
+        backoff in case of failures.
+
+        Args:
+            input (List[str]): A list of input texts to generate embeddings for.
+
+        Returns:
+            Embeddings: A list of embedding vectors corresponding to the input texts.
+        """
+        tokenized_texts = self.model.truncate_texts(input)
+        embeds = []
+        for batch in batched(tokenized_texts, self.batch_size):
+            result = self.model.client.embeddings.create(
+                input=batch, model=self.model.config.model_name
+            )
+            batch_embeds = [d.embedding for d in result.data]
+            embeds.extend(batch_embeds)
+        return embeds
 
 
 class OpenAIEmbeddings(EmbeddingModel):
-    def __init__(self, config: OpenAIEmbeddingsConfig):
+    def __init__(self, config: OpenAIEmbeddingsConfig = OpenAIEmbeddingsConfig()):
         super().__init__()
         self.config = config
         load_dotenv()
@@ -36,28 +100,38 @@ class OpenAIEmbeddings(EmbeddingModel):
                 in your .env file.
                 """
             )
-        self.client = OpenAI(api_key=self.config.api_key)
+        self.client = OpenAI(base_url=self.config.api_base, api_key=self.config.api_key)
+        self.tokenizer = tiktoken.encoding_for_model(self.config.model_name)
+
+    def truncate_texts(self, texts: List[str]) -> List[List[int]]:
+        """
+        Truncate texts to the embedding model's context length.
+        TODO: Maybe we should show warning, and consider doing T5 summarization?
+        """
+        return [
+            self.tokenizer.encode(text, disallowed_special=())[
+                : self.config.context_length
+            ]
+            for text in texts
+        ]
 
     def embedding_fn(self) -> Callable[[List[str]], Embeddings]:
-        @retry_with_exponential_backoff
-        def fn(texts: List[str]) -> Embeddings:
-            result = self.client.embeddings.create(
-                input=texts, model=self.config.model_name
-            )
-            return [d.embedding for d in result.data]
-
-        return fn
+        return EmbeddingFunctionCallable(self, self.config.batch_size)
 
     @property
     def embedding_dims(self) -> int:
         return self.config.dims
 
 
+STEC = SentenceTransformerEmbeddingsConfig
+
+
 class SentenceTransformerEmbeddings(EmbeddingModel):
-    def __init__(self, config: SentenceTransformerEmbeddingsConfig):
+    def __init__(self, config: STEC = STEC()):
         # this is an "extra" optional dependency, so we import it here
         try:
             from sentence_transformers import SentenceTransformer
+            from transformers import AutoTokenizer
         except ImportError:
             raise ImportError(
                 """
@@ -69,13 +143,39 @@ class SentenceTransformerEmbeddings(EmbeddingModel):
 
         super().__init__()
         self.config = config
-        self.model = SentenceTransformer(self.config.model_name)
+
+        self.model = SentenceTransformer(
+            self.config.model_name,
+            device=self.config.device,
+        )
+        if self.config.data_parallel:
+            self.pool = self.model.start_multi_process_pool(
+                self.config.devices  # type: ignore
+            )
+            atexit.register(
+                lambda: SentenceTransformer.stop_multi_process_pool(self.pool)
+            )
+
+        self.tokenizer = AutoTokenizer.from_pretrained(self.config.model_name)
+        self.config.context_length = self.tokenizer.model_max_length
 
     def embedding_fn(self) -> Callable[[List[str]], Embeddings]:
         def fn(texts: List[str]) -> Embeddings:
-            return self.model.encode(  # type: ignore
-                texts, convert_to_numpy=True
-            ).tolist()
+            if self.config.data_parallel:
+                embeds: Embeddings = self.model.encode_multi_process(
+                    texts,
+                    self.pool,
+                    batch_size=self.config.batch_size,
+                ).tolist()
+            else:
+                embeds = []
+                for batch in batched(texts, self.config.batch_size):
+                    batch_embeds = self.model.encode(
+                        batch, convert_to_numpy=True
+                    ).tolist()  # type: ignore
+                    embeds.extend(batch_embeds)
+
+            return embeds
 
         return fn
 

langroid/embedding_models/protoc/embeddings.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+service Embedding {
+    rpc Embed (EmbeddingRequest) returns (BatchEmbeds) {};
+}
+
+message EmbeddingRequest {
+    string model_name = 1;
+    int32 batch_size = 2;
+    repeated string strings = 3;
+}
+
+message BatchEmbeds {
+    repeated Embed embeds = 1;
+}
+
+message Embed {
+    repeated float embed = 1;
+}