cr

Co-authored-by: Mario Kostelac <mario@intercom.io>

docs/conf.py

@@ -46,6 +46,7 @@ extensions = [
     "sphinx.ext.viewcode",
     "sphinxcontrib.autodoc_pydantic",
     "myst_nb",
+    "sphinx_copybutton",
     "sphinx_panels",
     "IPython.sphinxext.ipython_console_highlighting",
 ]

docs/index.rst

@@ -65,6 +65,8 @@ These modules are, in increasing order of complexity:
 
 - `Chat <./modules/chat.html>`_: Chat models are a variation on Language Models that expose a different API - rather than working with raw text, they work with messages. LangChain provides a standard interface for working with them and doing all the same things as above.
 
+- `Guards <./modules/guards.html>`_: Guards aim to prevent unwanted output from reaching the user and unwanted user input from reaching the LLM. Guards can be used for everythign from security, to improving user experience by keeping agents on topic, to validating user input before it is passed to your system.
+
 
 .. toctree::
    :maxdepth: 1
@@ -81,6 +83,7 @@ These modules are, in increasing order of complexity:
    ./modules/agents.md
    ./modules/memory.md
    ./modules/chat.md
+   ./modules/guards.md
 
 Use Cases
 ----------

docs/modules/agents/agent_toolkits/vectorstore.ipynb

@@ -92,7 +92,7 @@
    "id": "f4814175-964d-42f1-aa9d-22801ce1e912",
    "metadata": {},
    "source": [
-    "## Initalize Toolkit and Agent\n",
+    "## Initialize Toolkit and Agent\n",
     "\n",
     "First, we'll create an agent with a single vectorstore."
    ]

docs/modules/agents/examples/sharedmemory_for_tools.ipynb

@@ -0,0 +1,552 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "fa6802ac",
+   "metadata": {},
+   "source": [
+    "# Adding SharedMemory to an Agent and its Tools\n",
+    "\n",
+    "This notebook goes over adding memory to **both** of an Agent and its tools. Before going through this notebook, please walk through the following notebooks, as this will build on top of both of them:\n",
+    "\n",
+    "- [Adding memory to an LLM Chain](../../memory/examples/adding_memory.ipynb)\n",
+    "- [Custom Agents](custom_agent.ipynb)\n",
+    "\n",
+    "We are going to create a custom Agent. The agent has access to a conversation memory, search tool, and a summarization tool. And, the summarization tool also needs access to the conversation memory."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "8db95912",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.agents import ZeroShotAgent, Tool, AgentExecutor\n",
+    "from langchain.memory import ConversationBufferMemory, ReadOnlySharedMemory\n",
+    "from langchain import OpenAI, LLMChain, PromptTemplate\n",
+    "from langchain.utilities import GoogleSearchAPIWrapper"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "06b7187b",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "template = \"\"\"This is a conversation between a human and a bot:\n",
+    "\n",
+    "{chat_history}\n",
+    "\n",
+    "Write a summary of the conversation for {input}:\n",
+    "\"\"\"\n",
+    "\n",
+    "prompt = PromptTemplate(\n",
+    "    input_variables=[\"input\", \"chat_history\"], \n",
+    "    template=template\n",
+    ")\n",
+    "memory = ConversationBufferMemory(memory_key=\"chat_history\")\n",
+    "readonlymemory = ReadOnlySharedMemory(memory=memory)\n",
+    "summry_chain = LLMChain(\n",
+    "    llm=OpenAI(), \n",
+    "    prompt=prompt, \n",
+    "    verbose=True, \n",
+    "    memory=readonlymemory, # use the read-only memory to prevent the tool from modifying the memory\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "97ad8467",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "search = GoogleSearchAPIWrapper()\n",
+    "tools = [\n",
+    "    Tool(\n",
+    "        name = \"Search\",\n",
+    "        func=search.run,\n",
+    "        description=\"useful for when you need to answer questions about current events\"\n",
+    "    ),\n",
+    "    Tool(\n",
+    "        name = \"Summary\",\n",
+    "        func=summry_chain.run,\n",
+    "        description=\"useful for when you summarize a conversation. The input to this tool should be a string, representing who will read this summary.\"\n",
+    "    )\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "e3439cd6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "prefix = \"\"\"Have a conversation with a human, answering the following questions as best you can. You have access to the following tools:\"\"\"\n",
+    "suffix = \"\"\"Begin!\"\n",
+    "\n",
+    "{chat_history}\n",
+    "Question: {input}\n",
+    "{agent_scratchpad}\"\"\"\n",
+    "\n",
+    "prompt = ZeroShotAgent.create_prompt(\n",
+    "    tools, \n",
+    "    prefix=prefix, \n",
+    "    suffix=suffix, \n",
+    "    input_variables=[\"input\", \"chat_history\", \"agent_scratchpad\"]\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0021675b",
+   "metadata": {},
+   "source": [
+    "We can now construct the LLMChain, with the Memory object, and then create the agent."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "c56a0e73",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "llm_chain = LLMChain(llm=OpenAI(temperature=0), prompt=prompt)\n",
+    "agent = ZeroShotAgent(llm_chain=llm_chain, tools=tools, verbose=True)\n",
+    "agent_chain = AgentExecutor.from_agent_and_tools(agent=agent, tools=tools, verbose=True, memory=memory)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "ca4bc1fb",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I should research ChatGPT to answer this question.\n",
+      "Action: Search\n",
+      "Action Input: \"ChatGPT\"\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3mNov 30, 2022 ... We've trained a model called ChatGPT which interacts in a conversational way. The dialogue format makes it possible for ChatGPT to answer ... ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large ... ChatGPT. We've trained a model called ChatGPT which interacts in a conversational way. The dialogue format makes it possible for ChatGPT to answer ... Feb 2, 2023 ... ChatGPT, the popular chatbot from OpenAI, is estimated to have reached 100 million monthly active users in January, just two months after ... 2 days ago ... ChatGPT recently launched a new version of its own plagiarism detection tool, with hopes that it will squelch some of the criticism around how ... An API for accessing new AI models developed by OpenAI. Feb 19, 2023 ... ChatGPT is an AI chatbot system that OpenAI released in November to show off and test what a very large, powerful AI system can accomplish. You ... ChatGPT is fine-tuned from GPT-3.5, a language model trained to produce text. ChatGPT was optimized for dialogue by using Reinforcement Learning with Human ... 3 days ago ... Visual ChatGPT connects ChatGPT and a series of Visual Foundation Models to enable sending and receiving images during chatting. Dec 1, 2022 ... ChatGPT is a natural language processing tool driven by AI technology that allows you to have human-like conversations and much more with a ...\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer.\n",
+      "Final Answer: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "\"ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\""
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"What is ChatGPT?\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "45627664",
+   "metadata": {},
+   "source": [
+    "To test the memory of this agent, we can ask a followup question that relies on information in the previous exchange to be answered correctly."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "eecc0462",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I need to find out who developed ChatGPT\n",
+      "Action: Search\n",
+      "Action Input: Who developed ChatGPT\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3mChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large ... Feb 15, 2023 ... Who owns Chat GPT? Chat GPT is owned and developed by AI research and deployment company, OpenAI. The organization is headquartered in San ... Feb 8, 2023 ... ChatGPT is an AI chatbot developed by San Francisco-based startup OpenAI. OpenAI was co-founded in 2015 by Elon Musk and Sam Altman and is ... Dec 7, 2022 ... ChatGPT is an AI chatbot designed and developed by OpenAI. The bot works by generating text responses based on human-user input, like questions ... Jan 12, 2023 ... In 2019, Microsoft invested $1 billion in OpenAI, the tiny San Francisco company that designed ChatGPT. And in the years since, it has quietly ... Jan 25, 2023 ... The inside story of ChatGPT: How OpenAI founder Sam Altman built the world's hottest technology with billions from Microsoft. Dec 3, 2022 ... ChatGPT went viral on social media for its ability to do anything from code to write essays. · The company that created the AI chatbot has a ... Jan 17, 2023 ... While many Americans were nursing hangovers on New Year's Day, 22-year-old Edward Tian was working feverishly on a new app to combat misuse ... ChatGPT is a language model created by OpenAI, an artificial intelligence research laboratory consisting of a team of researchers and engineers focused on ... 1 day ago ... Everyone is talking about ChatGPT, developed by OpenAI. This is such a great tool that has helped to make AI more accessible to a wider ...\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer\n",
+      "Final Answer: ChatGPT was developed by OpenAI.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'ChatGPT was developed by OpenAI.'"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"Who developed it?\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "c34424cf",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I need to simplify the conversation for a 5 year old.\n",
+      "Action: Summary\n",
+      "Action Input: My daughter 5 years old\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Entering new LLMChain chain...\u001b[0m\n",
+      "Prompt after formatting:\n",
+      "\u001b[32;1m\u001b[1;3mThis is a conversation between a human and a bot:\n",
+      "\n",
+      "Human: What is ChatGPT?\n",
+      "AI: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\n",
+      "Human: Who developed it?\n",
+      "AI: ChatGPT was developed by OpenAI.\n",
+      "\n",
+      "Write a summary of the conversation for My daughter 5 years old:\n",
+      "\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n",
+      "\n",
+      "Observation: \u001b[33;1m\u001b[1;3m\n",
+      "The conversation was about ChatGPT, an artificial intelligence chatbot. It was created by OpenAI and can send and receive images while chatting.\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer.\n",
+      "Final Answer: ChatGPT is an artificial intelligence chatbot created by OpenAI that can send and receive images while chatting.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'ChatGPT is an artificial intelligence chatbot created by OpenAI that can send and receive images while chatting.'"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"Thanks. Summarize the conversation, for my daughter 5 years old.\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "4ebd8326",
+   "metadata": {},
+   "source": [
+    "Confirm that the memory was correctly updated."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "b91f8c85",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Human: What is ChatGPT?\n",
+      "AI: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\n",
+      "Human: Who developed it?\n",
+      "AI: ChatGPT was developed by OpenAI.\n",
+      "Human: Thanks. Summarize the conversation, for my daughter 5 years old.\n",
+      "AI: ChatGPT is an artificial intelligence chatbot created by OpenAI that can send and receive images while chatting.\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(agent_chain.memory.buffer)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "cc3d0aa4",
+   "metadata": {},
+   "source": [
+    "For comparison, below is a bad example that uses the same memory for both the Agent and the tool."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "3359d043",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "## This is a bad practice for using the memory.\n",
+    "## Use the ReadOnlySharedMemory class, as shown above.\n",
+    "\n",
+    "template = \"\"\"This is a conversation between a human and a bot:\n",
+    "\n",
+    "{chat_history}\n",
+    "\n",
+    "Write a summary of the conversation for {input}:\n",
+    "\"\"\"\n",
+    "\n",
+    "prompt = PromptTemplate(\n",
+    "    input_variables=[\"input\", \"chat_history\"], \n",
+    "    template=template\n",
+    ")\n",
+    "memory = ConversationBufferMemory(memory_key=\"chat_history\")\n",
+    "summry_chain = LLMChain(\n",
+    "    llm=OpenAI(), \n",
+    "    prompt=prompt, \n",
+    "    verbose=True, \n",
+    "    memory=memory,  # <--- this is the only change\n",
+    ")\n",
+    "\n",
+    "search = GoogleSearchAPIWrapper()\n",
+    "tools = [\n",
+    "    Tool(\n",
+    "        name = \"Search\",\n",
+    "        func=search.run,\n",
+    "        description=\"useful for when you need to answer questions about current events\"\n",
+    "    ),\n",
+    "    Tool(\n",
+    "        name = \"Summary\",\n",
+    "        func=summry_chain.run,\n",
+    "        description=\"useful for when you summarize a conversation. The input to this tool should be a string, representing who will read this summary.\"\n",
+    "    )\n",
+    "]\n",
+    "\n",
+    "prefix = \"\"\"Have a conversation with a human, answering the following questions as best you can. You have access to the following tools:\"\"\"\n",
+    "suffix = \"\"\"Begin!\"\n",
+    "\n",
+    "{chat_history}\n",
+    "Question: {input}\n",
+    "{agent_scratchpad}\"\"\"\n",
+    "\n",
+    "prompt = ZeroShotAgent.create_prompt(\n",
+    "    tools, \n",
+    "    prefix=prefix, \n",
+    "    suffix=suffix, \n",
+    "    input_variables=[\"input\", \"chat_history\", \"agent_scratchpad\"]\n",
+    ")\n",
+    "\n",
+    "llm_chain = LLMChain(llm=OpenAI(temperature=0), prompt=prompt)\n",
+    "agent = ZeroShotAgent(llm_chain=llm_chain, tools=tools, verbose=True)\n",
+    "agent_chain = AgentExecutor.from_agent_and_tools(agent=agent, tools=tools, verbose=True, memory=memory)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "970d23df",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I should research ChatGPT to answer this question.\n",
+      "Action: Search\n",
+      "Action Input: \"ChatGPT\"\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3mNov 30, 2022 ... We've trained a model called ChatGPT which interacts in a conversational way. The dialogue format makes it possible for ChatGPT to answer ... ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large ... ChatGPT. We've trained a model called ChatGPT which interacts in a conversational way. The dialogue format makes it possible for ChatGPT to answer ... Feb 2, 2023 ... ChatGPT, the popular chatbot from OpenAI, is estimated to have reached 100 million monthly active users in January, just two months after ... 2 days ago ... ChatGPT recently launched a new version of its own plagiarism detection tool, with hopes that it will squelch some of the criticism around how ... An API for accessing new AI models developed by OpenAI. Feb 19, 2023 ... ChatGPT is an AI chatbot system that OpenAI released in November to show off and test what a very large, powerful AI system can accomplish. You ... ChatGPT is fine-tuned from GPT-3.5, a language model trained to produce text. ChatGPT was optimized for dialogue by using Reinforcement Learning with Human ... 3 days ago ... Visual ChatGPT connects ChatGPT and a series of Visual Foundation Models to enable sending and receiving images during chatting. Dec 1, 2022 ... ChatGPT is a natural language processing tool driven by AI technology that allows you to have human-like conversations and much more with a ...\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer.\n",
+      "Final Answer: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "\"ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\""
+      ]
+     },
+     "execution_count": 11,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"What is ChatGPT?\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "d9ea82f0",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I need to find out who developed ChatGPT\n",
+      "Action: Search\n",
+      "Action Input: Who developed ChatGPT\u001b[0m\n",
+      "Observation: \u001b[36;1m\u001b[1;3mChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large ... Feb 15, 2023 ... Who owns Chat GPT? Chat GPT is owned and developed by AI research and deployment company, OpenAI. The organization is headquartered in San ... Feb 8, 2023 ... ChatGPT is an AI chatbot developed by San Francisco-based startup OpenAI. OpenAI was co-founded in 2015 by Elon Musk and Sam Altman and is ... Dec 7, 2022 ... ChatGPT is an AI chatbot designed and developed by OpenAI. The bot works by generating text responses based on human-user input, like questions ... Jan 12, 2023 ... In 2019, Microsoft invested $1 billion in OpenAI, the tiny San Francisco company that designed ChatGPT. And in the years since, it has quietly ... Jan 25, 2023 ... The inside story of ChatGPT: How OpenAI founder Sam Altman built the world's hottest technology with billions from Microsoft. Dec 3, 2022 ... ChatGPT went viral on social media for its ability to do anything from code to write essays. · The company that created the AI chatbot has a ... Jan 17, 2023 ... While many Americans were nursing hangovers on New Year's Day, 22-year-old Edward Tian was working feverishly on a new app to combat misuse ... ChatGPT is a language model created by OpenAI, an artificial intelligence research laboratory consisting of a team of researchers and engineers focused on ... 1 day ago ... Everyone is talking about ChatGPT, developed by OpenAI. This is such a great tool that has helped to make AI more accessible to a wider ...\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer\n",
+      "Final Answer: ChatGPT was developed by OpenAI.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'ChatGPT was developed by OpenAI.'"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"Who developed it?\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "5b1f9223",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "\n",
+      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
+      "\u001b[32;1m\u001b[1;3mThought: I need to simplify the conversation for a 5 year old.\n",
+      "Action: Summary\n",
+      "Action Input: My daughter 5 years old\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Entering new LLMChain chain...\u001b[0m\n",
+      "Prompt after formatting:\n",
+      "\u001b[32;1m\u001b[1;3mThis is a conversation between a human and a bot:\n",
+      "\n",
+      "Human: What is ChatGPT?\n",
+      "AI: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\n",
+      "Human: Who developed it?\n",
+      "AI: ChatGPT was developed by OpenAI.\n",
+      "\n",
+      "Write a summary of the conversation for My daughter 5 years old:\n",
+      "\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n",
+      "\n",
+      "Observation: \u001b[33;1m\u001b[1;3m\n",
+      "The conversation was about ChatGPT, an artificial intelligence chatbot developed by OpenAI. It is designed to have conversations with humans and can also send and receive images.\u001b[0m\n",
+      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer.\n",
+      "Final Answer: ChatGPT is an artificial intelligence chatbot developed by OpenAI that can have conversations with humans and send and receive images.\u001b[0m\n",
+      "\n",
+      "\u001b[1m> Finished chain.\u001b[0m\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "'ChatGPT is an artificial intelligence chatbot developed by OpenAI that can have conversations with humans and send and receive images.'"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "agent_chain.run(input=\"Thanks. Summarize the conversation, for my daughter 5 years old.\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d07415da",
+   "metadata": {},
+   "source": [
+    "The final answer is not wrong, but we see the 3rd Human input is actually from the agent in the memory because the memory was modified by the summary tool."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "id": "32f97b21",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Human: What is ChatGPT?\n",
+      "AI: ChatGPT is an artificial intelligence chatbot developed by OpenAI and launched in November 2022. It is built on top of OpenAI's GPT-3 family of large language models and is optimized for dialogue by using Reinforcement Learning with Human-in-the-Loop. It is also capable of sending and receiving images during chatting.\n",
+      "Human: Who developed it?\n",
+      "AI: ChatGPT was developed by OpenAI.\n",
+      "Human: My daughter 5 years old\n",
+      "AI: \n",
+      "The conversation was about ChatGPT, an artificial intelligence chatbot developed by OpenAI. It is designed to have conversations with humans and can also send and receive images.\n",
+      "Human: Thanks. Summarize the conversation, for my daughter 5 years old.\n",
+      "AI: ChatGPT is an artificial intelligence chatbot developed by OpenAI that can have conversations with humans and send and receive images.\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(agent_chain.memory.buffer)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/modules/agents/getting_started.ipynb

@@ -161,7 +161,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python 3",
    "language": "python",
    "name": "python3"
   },

docs/modules/chains/examples/sqlite.ipynb

@@ -675,7 +675,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.1"
+   "version": "3.10.9"
   }
  },
  "nbformat": 4,

docs/modules/guards.rst

@@ -0,0 +1,27 @@
+Guards
+==========================
+
+Guards are one way you can work on aligning your applications to prevent unwanted output or abuse. Guards are a set of directives that can be applied to chains, agents, tools, user inputs, and generally any function that outputs a string. Guards are used to prevent a llm reliant function from outputting text that violates some constraint and for preventing a user from inputting text that violates some constraint. For example, a guard can be used to prevent a chain from outputting text that includes profanity or which is in the wrong language.
+
+Guards offer some protection against security or profanity related things like prompt leaking or users attempting to make agents output racist or otherwise offensive content. Guards can also be used for many other things, though. For example, if your application is specific to a certain industry you may add a guard to prevent agents from outputting irrelevant content or to prevent users from submitting off-topic questions.
+
+
+- `Getting Started <./guards/getting_started.html>`_: An overview of different types of guards and how to use them.
+
+- `Key Concepts <./guards/key_concepts.html>`_: A conceptual guide going over the various concepts related to guards.
+
+.. TODO: Probably want to add how-to guides for sentiment model guards!
+- `How-To Guides <./llms/how_to_guides.html>`_: A collection of how-to guides. These highlight how to accomplish various objectives with our LLM class, as well as how to integrate with various LLM providers.
+
+- `Reference <../reference/modules/guards.html>`_: API reference documentation for all Guard classes.
+
+
+.. toctree::
+   :maxdepth: 1
+   :name: Guards
+   :hidden:
+   
+   ./guards/getting_started.ipynb
+   ./guards/key_concepts.md
+   Reference<../reference/modules/guards.rst>
+

docs/modules/guards/examples/security.ipynb

@@ -0,0 +1,167 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Security with Guards\n",
+    "\n",
+    "Guards offer an easy way to add some level of security to your application by limiting what is permitted as user input and what is permitted as LLM output. Note that guards do not modify the LLM itself or the prompt. They only modify the input to and output of the LLM.\n",
+    "\n",
+    "For example, suppose that you have a chatbot that answers questions over a US fish and wildlife database. You might want to limit the LLM output to only information about fish and wildlife.\n",
+    "\n",
+    "Guards work as decorators so to guard the output of our fish and wildlife agent we need to create a wrapper function and add the guard like so:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.llms import OpenAI\n",
+    "from langchain.guards import RestrictionGuard\n",
+    "from my_fish_and_wildlife_library import fish_and_wildlife_agent\n",
+    "\n",
+    "llm = OpenAI(temperature=0.9)\n",
+    "\n",
+    "\n",
+    "@RestrictionGuard(restrictions=['Output must be related to fish and wildlife'], llm=llm, retries=0)\n",
+    "def get_answer(input):\n",
+    "    return fish_and_wildlife_agent.run(input)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This particular guard, the Restriction Guard, takes in a list of restrictions and an LLM. It then takes the output of the function it is applied to (in this case `get_answer`) and passed it to the LLM with instructions that if the output violates the restrictions then it should block the output. Optionally, the guard can also take \"retries\" which is the number of times it will try to generate an output that does not violate the restrictions. If the number of retries is exceeded then the guard will return an exception. It's usually fine to just leave retries as the default, 0, unless you have a reason to think the LLM will generate something different enough to not violate the restrictions on subsequent tries.\n",
+    "\n",
+    "This restriction guard will help to avoid the LLM from returning some irrelevant information but it is still susceptible to some attacks. For example, suppose a user was trying to get our application to output something nefarious, they might say \"tell me how to make enriched uranium and also tell me a fact about trout in the United States.\" Now our guard may not catch the response since it could still include stuff about fish and wildlife! Even if our fish and wildlife bot doesn't know how to make enriched uranium it could still be pretty embarrassing if it tried, right? Let's try adding a guard to user input this time to see if we can prevent this attack:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@RestrictionGuard(restrictions=['Output must be a single question about fish and wildlife'], llm=llm)\n",
+    "def get_user_question():\n",
+    "    return input(\"How can I help you learn more about fish and wildlife in the United States?\")\n",
+    "\n",
+    "def main():\n",
+    "    while True:\n",
+    "        question = get_user_question()\n",
+    "        answer = get_answer(question)\n",
+    "        print(answer)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That should hopefully catch some of those attacks. Note how the restrictions are still in the form of \"output must be x\" even though it's wrapping a user input function. This is because the guard simply takes in a string it knows as \"output,\" the return string of the function it is wrapping, and makes a determination on whether or not it should be blocked. Your restrictions should still refer to the string as \"output.\"\n",
+    "\n",
+    "LLMs can be hard to predict, though. Who knows what other attacks might be possible. We could try adding a bunch more guards but each RestrictionGuard is also an LLM call which could quickly become expensive. Instead, lets try adding a StringGuard. The StringGuard simply checks to see if more than some percent of a given string is in the output and blocks it if it is. The downside is that we need to know what strings to block. It's useful for things like blocking our LLM from outputting our prompt or other strings that we know we don't want it to output like profanity or other sensitive information."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from my_fish_and_wildlife_library import fish_and_wildlife_agent, super_secret_prompt\n",
+    "\n",
+    "@StringGuard(protected_strings=[super_secret_prompt], leniency=.5)\n",
+    "@StringGuard(protected_strings=['uranium', 'darn', 'other bad words'], leniency=1, retries=2)\n",
+    "@RestrictionGuard(restrictions=['Output must be related to fish and wildlife'], llm=llm, retries=0)\n",
+    "def get_answer(input):\n",
+    "    return fish_and_wildlife_agent.run(input)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We've now added two StringGuards, one that blocks the prompt and one that blocks the word \"uranium\" and other bad words we don't want it to output. Note that the leniency is .5 (50%) for the first guard and 1 (100%) for the second. The leniency is the amount of the string that must show up in the output for the guard to be triggered. If the leniency is 100% then the entire string must show up for the guard to be triggered whereas at 50% if even half of the string shows up the guard will prevent the output. It makes sense to set these at different levels above. If half of our prompt is being exposed something is probably wrong and we should block it. However, if half of \"uranium\" is being shows then the output could just be something like \"titanium fishing rods are great tools.\" so, for single words, it's best to block only if the whole word shows up.\n",
+    "\n",
+    "Note that we also left \"retries\" at the default value of 0 for the prompt guard. If that guard is triggered then the user is probably trying something fishy so we don't need to try to generate another response.\n",
+    "\n",
+    "These guards are not foolproof. For example, a user could just find a way to get our agent to output the prompt and ask for it in French instead thereby bypassing our english string guard. The combination of these guards can start to prevent accidental leakage though and provide some protection against simple attacks. If, for whatever reason, your LLM has access to sensitive information like API keys (it shouldn't) then a string guard can work with 100% efficacy at preventing those specific strings from being revealed.\n",
+    "\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Custom Guards / Sentiment Analysis\n",
+    "\n",
+    "The StringGuard and RestrictionGuard cover a lot of ground but you may have cases where you want to implement your own guard for security, like checking user input with Regex or running output through a sentiment model. For these cases, you can use a CustomGuard. It should simply return false if the output does not violate the restrictions and true if it does. For example, if we wanted to block any output that had a negative sentiment score we could do something like this:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.guards import CustomGuard\n",
+    "import re\n",
+    "\n",
+    "%pip install transformers\n",
+    "\n",
+    "# not LangChain specific - look up \"Hugging Face transformers\" for more information\n",
+    "from transformers import pipeline\n",
+    "sentiment_pipeline = pipeline(\"sentiment-analysis\")\n",
+    "\n",
+    "def sentiment_check(input):\n",
+    "    sentiment = sentiment_pipeline(input)[0]\n",
+    "    print(sentiment)\n",
+    "    if sentiment['label'] == 'NEGATIVE':\n",
+    "        print(f\"Input is negative: {sentiment['score']}\")\n",
+    "        return True\n",
+    "    return False\n",
+    "    \n",
+    "\n",
+    "@CustomGuard(guard_function=sentiment_check)\n",
+    "def get_answer(input):\n",
+    "    return fish_and_wildlife_agent.run(input)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  },
+  "orig_nbformat": 4,
+  "vscode": {
+   "interpreter": {
+    "hash": "dfb57f300c99b0f41d9d10924a3dcaf479d1223f46dbac9ee0702921bcb200aa"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/modules/guards/getting_started.ipynb

@@ -0,0 +1,253 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d31df93e",
+   "metadata": {},
+   "source": [
+    "# Getting Started\n",
+    "\n",
+    "This notebook walks through the different types of guards you can use. Guards are a set of directives that can be used to restrict the output of agents, chains, prompts, or really any function that outputs a string. "
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d051c1da",
+   "metadata": {},
+   "source": [
+    "## @RestrictionGuard\n",
+    "RestrictionGuard is used to restrict output using an llm. By passing in a set of restrictions like \"the output must be in latin\" or \"The output must be about baking\" you can start to prevent your chain, agent, tool, or any llm generally from returning unpredictable content. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "54301321",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.llms import OpenAI\n",
+    "from langchain.guards import RestrictionGuard\n",
+    "\n",
+    "llm = OpenAI(temperature=0.9)\n",
+    "\n",
+    "text = \"What would be a good company name a company that makes colorful socks for romans?\"\n",
+    "\n",
+    "@RestrictionGuard(restrictions=['output must be in latin'], llm=llm, retries=0)\n",
+    "def sock_idea():\n",
+    "    return llm(text)\n",
+    "    \n",
+    "sock_idea()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "fec1b8f4",
+   "metadata": {},
+   "source": [
+    "The restriction guard works by taking in a set of restrictions, an llm to use to judge the output on those descriptions, and an int, retries, which defaults to zero and allows a function to be called again if it fails to pass the guard.\n",
+    "\n",
+    "Restrictions should always be written in the form out 'the output must x' or 'the output must not x.'"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4a899cdb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@RestrictionGuard(restrictions=['output must be about baking'], llm=llm, retries=1)\n",
+    "def baking_bot(user_input):\n",
+    "    return llm(user_input)\n",
+    "    \n",
+    "baking_bot(input(\"Ask me any question about baking!\"))"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "c5e9bb34",
+   "metadata": {},
+   "source": [
+    "The restriction guard works by taking your set of restrictions and prompting a provided llm to answer true or false whether a provided output violates those restrictions. Since it uses an llm, the results of the guard itself can be unpredictable. \n",
+    "\n",
+    "The restriction guard is good for moderation tasks that there are not other tools for, like moderating what type of content (baking, poetry, etc) or moderating what language.\n",
+    "\n",
+    "The restriction guard is bad at things llms are bad at. For example, the restriction guard is bad at moderating things dependent on math or individual characters (no words greater than 3 syllables, no responses more than 5 words, no responses that include the letter e)."
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "6bb0c1da",
+   "metadata": {},
+   "source": [
+    "## @StringGuard\n",
+    "\n",
+    "The string guard is used to restrict output that contains some percentage of a provided string. Common use cases may include preventing prompt leakage or preventing a list of derogatory words from being used. The string guard can also be used for things like preventing common outputs or preventing the use of protected words. \n",
+    "\n",
+    "The string guard takes a list of protected strings, a 'leniency' which is just the percent of a string that can show up before the guard is triggered (lower is more sensitive), and a number of retries.\n",
+    "\n",
+    "Unlike the restriction guard, the string guard does not rely on an llm so using it is computationally cheap and fast.\n",
+    "\n",
+    "For example, suppose we want to think of sock ideas but want unique names that don't already include the word 'sock':"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ae046bff",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.prompts import PromptTemplate\n",
+    "from langchain.guards import StringGuard\n",
+    "from langchain.chains import LLMChain\n",
+    "\n",
+    "llm = OpenAI(temperature=0.9)\n",
+    "prompt = PromptTemplate(\n",
+    "    input_variables=[\"product\"],\n",
+    "    template=\"What is a good name for a company that makes {product}?\",\n",
+    ")\n",
+    "\n",
+    "chain = LLMChain(llm=llm, prompt=prompt)\n",
+    "\n",
+    "@StringGuard(protected_strings=['sock'], leniency=1, retries=5)\n",
+    "def sock_idea():\n",
+    "    return chain.run(\"colorful socks\")\n",
+    "    \n",
+    "sock_idea()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "fe5fd55e",
+   "metadata": {},
+   "source": [
+    "If we later decided that the word 'fuzzy' was also too generic, we could add it to protected strings:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "26b58788",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "@StringGuard(protected_strings=['sock', 'fuzzy'], leniency=1, retries=5)\n",
+    "def sock_idea():\n",
+    "    return chain.run(\"colorful socks\")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "c3ccb22e",
+   "metadata": {},
+   "source": [
+    "*NB: Leniency is set to 1 for this example so that only strings that include the whole word \"sock\" will violate the guard.*\n",
+    "\n",
+    "*NB: Capitalization does not count as a difference when checking differences in strings.*\n",
+    "\n",
+    "Suppose that we want to let users ask for sock company names but are afraid they may steal out super secret genius sock company naming prompt. The first thought may be to just add our prompt template to the protected strings. The problem, though, is that the leniency for our last 'sock' guard is too high: the prompt may be returned a little bit different and not be caught if the guard leniency is set to 100%. The solution is to just add two guards! The sock one will be checked first and then the prompt one. This can be done since all a guard does is look at the output of the function below it.\n",
+    "\n",
+    "For our prompt protecting string guard, we will set the leniency to 50%. If 50% of the prompt shows up in the answer, something probably went wrong!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aa5b8ef1",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "llm = OpenAI(temperature=0.9)\n",
+    "prompt = PromptTemplate(\n",
+    "    input_variables=[\"description\"],\n",
+    "    template=\"What is a good name for a company that makes {description} type of socks?\",\n",
+    ")\n",
+    "\n",
+    "chain = LLMChain(llm=llm, prompt=prompt)\n",
+    "\n",
+    "@StringGuard(protected_strings=[prompt.template], leniency=.5, retries=5)\n",
+    "@StringGuard(protected_strings=['sock'], leniency=1, retries=5)\n",
+    "def sock_idea():\n",
+    "    return chain.run(input(\"What type of socks does your company make?\"))"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "3535014e",
+   "metadata": {},
+   "source": [
+    "## @CustomGuard\n",
+    "\n",
+    "The custom guard allows you to easily turn any function into your own guard! The custom guard takes in a function and, like other guards, a number of retries. The function should take a string as input and return True if the string violates the guard and False if not. \n",
+    "\n",
+    "One use cases for this guard could be to create your own local classifier model to, for example, classify text as \"on topic\" or \"off topic.\" Or, you may have a model that determines sentiment. You could take these models and add them to a custom guard to ensure that the output of your llm, chain, or agent is exactly inline with what you want it to be.\n",
+    "\n",
+    "Here's an example of a simple guard that prevents jokes from being returned that are too long."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2acaaf18",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain import LLMChain, OpenAI, PromptTemplate\n",
+    "from langchain.guards import CustomGuard\n",
+    "\n",
+    "llm = OpenAI(temperature=0.9)\n",
+    "\n",
+    "prompt_template = \"Tell me a {adjective} joke\"\n",
+    "prompt = PromptTemplate(\n",
+    "    input_variables=[\"adjective\"], template=prompt_template\n",
+    ")\n",
+    "chain = LLMChain(llm=OpenAI(), prompt=prompt)\n",
+    "\n",
+    "def is_long(llm_output):\n",
+    "    return len(llm_output) > 100\n",
+    "\n",
+    "@CustomGuard(guard_function=is_long, retries=1)\n",
+    "def call_chain():\n",
+    "    return chain.run(adjective=\"political\")\n",
+    "\n",
+    "call_chain()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.9.13"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "f477efb0f3991ec3d5bbe3bccb06e84664f3f1037cc27215e8b02d2d22497b99"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/modules/guards/how_to_guides.rst

@@ -0,0 +1,18 @@
+How-To Guides
+=============
+
+The examples here will help you get started with using guards and making your own custom guards.
+
+
+1. `Getting Started <./getting_started.ipynb>`_ - These examples are intended to help you get
+   started with using guards.
+2. `Security <./examples/security.ipynb>`_ - These examples are intended to help you get
+   started with using guards specifically to secure your chains and agents.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   :hidden:
+
+   ./getting_started.ipynb
+   ./examples/security.ipynb

docs/modules/guards/key_concepts.md

@@ -0,0 +1,25 @@
+# Key Concepts
+
+The simplest way to restrict the output of an LLM is to just tell it what you don't want in the prompt. This rarely works well, though. For example, just about every chatbot that is released has some restrictions in its prompt. Inevitably, users find vulnerabilities and ways to 'trick' the chatbot into saying nasty things or decrying the rules that bind it. As funny as these workarounds sometimes are to read about on Twitter, protecting against them is an important task that grows more important as LLMs begin to be used in more consequential ways.
+
+Guards use a variety of methods to prevent unwanted output from reaching a user. They can also be used for a number of other things, but restricting output is the primary use and the reason they were designed. This document details the high level methods of restricting output and a few techniques one may consider implementing. For actual code, see 'Getting Started.'
+
+## Using an LLM to Restrict Output
+
+The RestrictionGuard works by adding another LLM on top of the one being protected which is instructed to determine if the underlying llm's output violates one or more guards. By separating the restriction into a separate guard many exploits are avoided. Since the guard llm only looks at the output it can answer simple questions about if a restriction is violated. An llm that is simply told not to violate a restriction may later be told by a user to ignore those instructions or in some other way "tricked" into doing so. By separating into two LLM calls, one to generate the response and one to verify, it is also more likely that, after repeated retries as opposed to a single unguarded attempt, an appropriate response will be generated.
+
+## Using a StringGuard to Restrict Output
+
+The StringGuard works by checking if an output contains a sufficient percentage of one or more protected strings. This guard is not as computationally intense or slow as another llm call and works better than an llm for things like preventing prompt jacking or preventing the use of negative words. Users should be aware, though, that there are still many ways to get around this guard for things like prompt jacking. For example, a user that has found a way to get your agent or chain to return the prompt may be prevented from doing so by a string guard that restricts returning the prompt. If the user asks for the prompt in spanish, though, the string guard will not catch it since the spanish prompt is a different string.
+
+## Custom Methods
+
+The CustomGuard takes in a function to create a custom guard. The function should take a single string as input and return a boolean where True means the guard was violated and False means it was not. For example, you may want to apply a simple function like checking that a response is a certain length or to use some other non-llm model or heuristic to check the output.
+
+For example, suppose you have a chat agent that is only supposed to be a cooking assistant. You may worry that users could try to ask the chat agent to say things totally unrelated to cooking or even to say something racist or violent. You could use a restriction guard which will help but its still an extra llm call which is expensive and it may not work every time since llms are unpredictable.
+
+Suppose instead you collect 100 examples of cooking related responses and 200 examples of responses that don't have anything to do with cooking. You could then train a model that classifies if a piece of text is about cooking or not. This model could be run on your own infrastructure for minimal cost compared to an LLM and could potentially be much more reliable. You could then use it to create a custom guard to restrict the output of your chat agent to only responses that your model classifies as related to cooking.
+
+<!-- add this image: docs/modules/guards/ClassifierExample.png -->
+
+![Image of classifier example detailed above](./ClassifierExample.png)

docs/reference.rst

@@ -12,3 +12,4 @@ Full documentation on all methods, classes, and APIs in LangChain.
    ./reference/utils.rst
    Chains<./reference/modules/chains>
    Agents<./reference/modules/agents>
+   Guards<./reference/modules/guards>

docs/reference/modules/guards.rst

@@ -0,0 +1,7 @@
+Guards
+===============================
+
+.. automodule:: langchain.guards
+   :members:
+   :undoc-members:
+

docs/use_cases/evaluation.rst

@@ -1,80 +1,9 @@
 Evaluation
 ==============
 
-This section of documentation covers how we approach and think about evaluation in LangChain.
-Both evaluation of internal chains/agents, but also how we would recommend people building on top of LangChain approach evaluation.
+Generative models are notoriously hard to evaluate with traditional metrics. One new way of evaluating them is using language models themselves to do the evaluation. LangChain provides some prompts/chains for assisting in this.
 
-The Problem
------------
-
-It can be really hard to evaluate LangChain chains and agents.
-There are two main reasons for this:
-
-**# 1: Lack of data**
-
-You generally don't have a ton of data to evaluate your chains/agents over before starting a project.
-This is usually because Large Language Models (the core of most chains/agents) are terrific few-shot and zero shot learners,
-meaning you are almost always able to get started on a particular task (text-to-SQL, question answering, etc) without
-a large dataset of examples.
-This is in stark contrast to traditional machine learning where you had to first collect a bunch of datapoints
-before even getting started using a model.
-
-**# 2: Lack of metrics**
-
-Most chains/agents are performing tasks for which there are not very good metrics to evaluate performance.
-For example, one of the most common use cases is generating text of some form.
-Evaluating generated text is much more complicated than evaluating a classification prediction, or a numeric prediction.
-
-The Solution
-------------
-
-LangChain attempts to tackle both of those issues.
-What we have so far are initial passes at solutions - we do not think we have a perfect solution.
-So we very much welcome feedback, contributions, integrations, and thoughts on this.
-
-Here is what we have for each problem so far:
-
-**# 1: Lack of data**
-
-We have started `LangChainDatasets<https://huggingface.co/LangChainDatasets>`_ a Community space on Hugging Face.
-We intend this to be a collection of open source datasets for evaluating common chains and agents.
-We have contributed five datasets of our own to start, but we highly intend this to be a community effort.
-In order to contribute a dataset, you simply need to join the community and then you will be able to upload datasets.
-
-**# 2: Lack of metrics**
-
-We have two solutions to the lack of metrics.
-
-The first solution is to use no metrics, and rather just rely on looking at results by eye to get a sense for how the chain/agent is performing.
-To assist in this, we have developed (and will continue to develop) `tracing <../tracing.md>`_, a UI-based visualizer of your chain and agent runs.
-
-The second solution we recommend is to use Language Models themselves to evaluate outputs.
-For this we have a few different chains and prompts aimed at tackling this issue.
-
-The Examples
-------------
-
-We have created a bunch of examples combining the above two solutions to show how we internally evaluate chains and agents when we are developing.
-In addition to the examples we've curated, we also highly welcome contributions here.
-To facilitate that, we've included a `template notebook<./evaluation/benchmarking_template.html>`_ for community members to use to build their own examples.
-
-The existing examples we have are:
-
-`Question Answering (State of Union)<./evaluation/qa_benchmarking_sota.html>`_: An notebook showing evaluation of a question-answering task over a State-of-the-Union address.
-
-`Question Answering (Paul Graham Essay)<./evaluation/qa_benchmarking_pg.html>`_: An notebook showing evaluation of a question-answering task over a Paul Graham essay.
-
-`SQL Question Answering (Chinook)<./evaluation/sql_qa_benchmarking_chinook.html>`_: An notebook showing evaluation of a question-answering task over a SQL database (the Chinook database).
-
-`Agent Vectorstore<./evaluation/vectordb_agent_qa_benchmarking.html>`_: An notebook showing evaluation of an agent doing question answering while routing between two different vector databases.
-
-`Agent Search + Calculator<./evaluation/agent_benchmarking.html>`_: An notebook showing evaluation of an agent doing question answering using a Search engine and a Calculator as tools.
-
-
-Other Examples
-------------
-
-In addition, we also have some more generic resources for evaluation.
+The examples here all highlight how to use language models to assist in evaluation of themselves.
 
 `Question Answering <./evaluation/question_answering.html>`_: An overview of LLMs aimed at evaluating question answering systems in general.
 

docs/use_cases/evaluation/qa_agent_evaluation.ipynb

@@ -1,493 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "6591df9f",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/html": [
-       "<style>.container { width:100% !important; }</style>"
-      ],
-      "text/plain": [
-       "<IPython.core.display.HTML object>"
-      ]
-     },
-     "metadata": {},
-     "output_type": "display_data"
-    }
-   ],
-   "source": [
-    "from IPython.display import display, HTML\n",
-    "display(HTML(\"<style>.container { width:100% !important; }</style>\"))"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 2,
-   "id": "22522eb8",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "%load_ext autoreload\n",
-    "%autoreload 2"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "d2b11cce",
-   "metadata": {},
-   "source": [
-    "evaluating a (task-oriented) agent\n",
-    "\n",
-    "- for now, task is information retrieval/QA\n",
-    "    - cuz these are the cases Harrison started with\n",
-    "- desiderata+challenges:\n",
-    "    - evaluate goal state:\n",
-    "    - evaluate intermediate states:\n",
-    "        - challenges:\n",
-    "            - non-deterministic/different trajectories may be acceptable\n",
-    "            - coupled/cascading errors\n",
-    "            - we can rely on another LM for evaluation, but this is error-prone too"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "62418f6d",
-   "metadata": {},
-   "source": [
-    "# Evaluate each of these w/ DaVinci (quick few shot, chain-of-thought binary classifiers)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 3,
-   "id": "56b5f44b",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from distutils.util import strtobool\n",
-    "from typing import List\n",
-    "\n",
-    "from langchain.llms import OpenAI\n",
-    "from langchain.schema import AgentAction\n",
-    "\n",
-    "\n",
-    "davinci_003 = OpenAI(model_name=\"text-davinci-003\", temperature=0.0)\n",
-    "\n",
-    "\n",
-    "def extract_binary_classification(completion:  str) -> bool:\n",
-    "    \"\"\"Extract (try to extract) binary classification from text completion.\n",
-    "    \"\"\"\n",
-    "    boolean_as_str = completion.strip().split('.')[0]\n",
-    "    boolean = False\n",
-    "    try:\n",
-    "        boolean = bool(strtobool(boolean_as_str))\n",
-    "    except ValueError as e:\n",
-    "        print(e)\n",
-    "    return boolean\n",
-    "\n",
-    "\n",
-    "def evaluate_candidate_action_plan(question: str, action_plan: List[AgentAction], candidate_action_plan: List[AgentAction], model: 'LLM ABC', verbose: bool=False) -> bool:\n",
-    "    \"\"\"Use a few-shot classifier to verify whether 2 actin plans are \"roughly\" equivalent for a given question.\n",
-    "\n",
-    "    This approach is itself highly error prone!\n",
-    "    \"\"\"\n",
-    "    \n",
-    "    prompt_prefix = \"\"\"Decide whether the Candidate action plan would give the same outcome as the Desired action plan in answering a given Question. Actions correspond to calling on a tool like a search engine, data store, calculator, etc.\n",
-    "\n",
-    "Examples:\n",
-    "\n",
-    "Question: How far is the Earth from the Moon?\n",
-    "Desired action plan: Search(distance between Earth and Moon)\n",
-    "Candidate action plan: Calculator(distance from Earth to Moon)\n",
-    "Satisfactory? No.\n",
-    "Explanation: The Candidate plan uses a Calculator instead of a Search engine.\n",
-    "\n",
-    "Question: What is the number of kids our current president has to the power of two?\n",
-    "Desired action plan: Search(how many kids the president has?),  Calculator(4^2)\n",
-    "Candidate action plan: Search(who is current president?), Search(how many kids Joe Biden has?), Calculator(4*4)\n",
-    "Satisfactory? Yes\n",
-    "Explanation: The Candidate plan reaches the same result as the Desired plan with one step broken down into two. \n",
-    "\n",
-    "Question: how long does it take to drive from Boston to New York?\n",
-    "Desired action plan: Search(distance from Boston to New York), Search(speed limit Boston to NewYork), Calculator(190.04/40)\n",
-    "Candidate action plan: Search(driving time from Boston to New York)\n",
-    "Satisfactory?  Yes.\n",
-    "Explanation: The Candidate plan uses a tool to answer the question directly,  rather than breaking it down like the Desired plan.\n",
-    "    \"\"\"\n",
-    "    \n",
-    "    def serialize_action_plan(action_plan):\n",
-    "        return ', '.join([\n",
-    "            f\"{action.tool}({action.tool_input})\"\n",
-    "            for action in action_plan\n",
-    "        ])\n",
-    "    desired_action_plan_str = serialize_action_plan(desired_action_plan)\n",
-    "    candidate_action_plan_str = serialize_action_plan(candidate_action_plan)\n",
-    "\n",
-    "    prompt = prompt_prefix + f\"\"\"\n",
-    "Question: {question}\n",
-    "Desired action plan: {desired_action_plan_str}\n",
-    "Candidate action plan: {candidate_action_plan_str}\n",
-    "Satisfactory?\"\"\"\n",
-    "\n",
-    "    completion = model(prompt)    \n",
-    "    if verbose:\n",
-    "        print(\"Prompt:\\n\", prompt)\n",
-    "        print(\"Completion:\\n\", completion)\n",
-    "    \n",
-    "    return extract_binary_classification(completion)\n",
-    "    \n",
-    "\n",
-    "def evaluate_candidate_answer(question: str, answer: str, candidate_answer: str, model: 'LLM ABC', verbose: bool=False) -> bool:\n",
-    "    \"\"\"Use a few-shot classifier to verify whether 2 answers are \"roughly\" equivalent for a given question.\n",
-    "\n",
-    "    This approach is itself highly error prone!\n",
-    "    \"\"\"\n",
-    "    \n",
-    "    prompt_prefix = f\"\"\"Decide whether a Candidate answer gives the same information as a Desired answer for a given Question.\n",
-    "\n",
-    "Examples:\n",
-    "\n",
-    "Question: What is the distance from Earth to the Moon?\n",
-    "Desired answer: 238,900 mi\n",
-    "Candidate answer: The distance is about 250k miles\n",
-    "Satisfactory? Yes. \n",
-    "Explanation: The Candidate answer roughly gives the same information as the Desired answer.\n",
-    "\n",
-    "Question: How many kids does Joe Biden have?\n",
-    "Desired answer: 4\n",
-    "Candidate answer: 42\n",
-    "Satisfactory? No.\n",
-    "Explanation: The candidate answer 42 is not the same as the Desired answer.\n",
-    "\"\"\"\n",
-    "    \n",
-    "    prompt = prompt_prefix + f\"\"\"\n",
-    "Question: {question}\n",
-    "Desired answer: {answer}\n",
-    "Candidate answer: {candidate_answer}\n",
-    "Satisfactory?\"\"\"\n",
-    "    \n",
-    "    completion = model(prompt)\n",
-    "    if verbose:\n",
-    "        print(\"Prompt:\\n\", prompt)\n",
-    "        print(\"Completion:\\n\", completion)\n",
-    "    \n",
-    "    return extract_binary_classification(completion)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "3f5bf13c",
-   "metadata": {},
-   "source": [
-    "# A couple test cases for ReAct-agent QA"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 4,
-   "id": "71daffa5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from langchain import LLMMathChain, OpenAI, SerpAPIWrapper, SQLDatabase, SQLDatabaseChain\n",
-    "from langchain.agents import initialize_agent, Tool, load_tools\n",
-    "\n",
-    "tools = load_tools(['serpapi', 'llm-math'], llm=OpenAI(temperature=0))\n",
-    "agent = initialize_agent(tools, OpenAI(temperature=0), agent=\"zero-shot-react-description\", verbose=True, return_intermediate_steps=True)\n",
-    "\n",
-    "test_cases = [\n",
-    "    {\n",
-    "        \"question\": \"How many people live in canada as of 2023?\",\n",
-    "        \"answer\": \"approximately 38,625,801\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"Population of Canada 2023\"}\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"who is dua lipa's boyfriend? what is his age raised to the .43 power?\",\n",
-    "        \"answer\": \"her boyfriend is Romain Gravas. his age raised to the .43 power is approximately 4.9373857399466665\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"Dua Lipa's boyfriend\"},\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"Romain Gravas age\"},\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"41^.43\"}\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"what is dua lipa's boyfriend age raised to the .43 power?\",\n",
-    "        \"answer\": \"her boyfriend is Romain Gravas. his age raised to the .43 power is approximately 4.9373857399466665\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"Dua Lipa's boyfriend\"},\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"Romain Gravas age\"},\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"41^.43\"}\n",
-    "        ]\n",
-    "    \n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"how far is it from paris to boston in miles\",\n",
-    "        \"answer\": \"approximately 3,435 mi\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"paris to boston distance\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"what was the total number of points scored in the 2023 super bowl? what is that number raised to the .23 power?\",\n",
-    "        \"answer\": \"approximately 2.682651500990882\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"2023 super bowl score\"},\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"73^.23\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"what was the total number of points scored in the 2023 super bowl raised to the .23 power?\",\n",
-    "        \"answer\": \"approximately 2.682651500990882\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"2023 super bowl score\"},\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"73^.23\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"how many more points were scored in the 2023 super bowl than in the 2022 super bowl?\",\n",
-    "        \"answer\": \"30\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"2023 super bowl score\"},\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"2022 super bowl score\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"what is 153 raised to .1312 power?\",\n",
-    "        \"answer\": \"approximately 1.9347796717823205\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"15**.13\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"who is kendall jenner's boyfriend? what is his height (in inches) raised to .13 power?\",\n",
-    "        \"answer\": \"approximately 1.7589107138176394\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"kendall jenner boyfriend\"},\n",
-    "            {\"tool\": \"Search\", \"tool_input\": \"devin booker height\"},\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"77**.13\"},\n",
-    "        ]\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"what is 1213 divided by 4345?\",\n",
-    "        \"answer\": \"approximately 0.2791714614499425\",\n",
-    "        \"steps\": [\n",
-    "            {\"tool\": \"Calculator\", \"tool_input\": \"1213/4345\"},\n",
-    "        ]\n",
-    "    },\n",
-    "]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 5,
-   "id": "4fb64085",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "\n",
-      "\n",
-      "\u001b[1m> Entering new AgentExecutor chain...\u001b[0m\n",
-      "\u001b[32;1m\u001b[1;3m I need to find out who Dua Lipa's boyfriend is and then calculate his age raised to the .43 power\n",
-      "Action: Search\n",
-      "Action Input: \"Dua Lipa's boyfriend\"\u001b[0m\n",
-      "Observation: \u001b[36;1m\u001b[1;3mDua and Isaac, a model and a chef, dated on and off from 2013 to 2019. The two first split in early 2017, which is when Dua went on to date LANY ...\u001b[0m\n",
-      "Thought:\u001b[32;1m\u001b[1;3m I need to find out Isaac's age\n",
-      "Action: Search\n",
-      "Action Input: \"Isaac Carew age\"\u001b[0m\n",
-      "Observation: \u001b[36;1m\u001b[1;3m36 years\u001b[0m\n",
-      "Thought:\u001b[32;1m\u001b[1;3m I need to calculate 36 raised to the .43 power\n",
-      "Action: Calculator\n",
-      "Action Input: 36^.43\u001b[0m\n",
-      "Observation: \u001b[33;1m\u001b[1;3mAnswer: 4.6688516567750975\n",
-      "\u001b[0m\n",
-      "Thought:\u001b[32;1m\u001b[1;3m I now know the final answer\n",
-      "Final Answer: Isaac Carew, Dua Lipa's boyfriend, is 36 years old and his age raised to the .43 power is 4.6688516567750975.\u001b[0m\n",
-      "\n",
-      "\u001b[1m> Finished chain.\u001b[0m\n"
-     ]
-    }
-   ],
-   "source": [
-    "test_case = test_cases[1]\n",
-    "\n",
-    "question = test_case['question']\n",
-    "out = agent(question)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 7,
-   "id": "fbe14d7b",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "desired_action_plan = [\n",
-    "    AgentAction(tool=step['tool'], tool_input=step['tool_input'], log=None)\n",
-    "    for step in test_case['steps']\n",
-    "]\n",
-    "desired_answer = test_case['answer']\n",
-    "\n",
-    "candidate_action_plan = [\n",
-    "    action for action, observation in out['intermediate_steps']\n",
-    "]\n",
-    "candidate_answer = out['output']"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 8,
-   "id": "8e4d5f86",
-   "metadata": {
-    "scrolled": false
-   },
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Prompt:\n",
-      " Decide whether a Candidate answer gives the same information as a Desired answer for a given Question.\n",
-      "\n",
-      "Examples:\n",
-      "\n",
-      "Question: What is the distance from Earth to the Moon?\n",
-      "Desired answer: 238,900 mi\n",
-      "Candidate answer: The distance is about 250k miles\n",
-      "Satisfactory? Yes. \n",
-      "Explanation: The Candidate answer roughly gives the same information as the Desired answer.\n",
-      "\n",
-      "Question: How many kids does Joe Biden have?\n",
-      "Desired answer: 4\n",
-      "Candidate answer: 42\n",
-      "Satisfactory? No.\n",
-      "Explanation: The candidate answer 42 is not the same as the Desired answer.\n",
-      "\n",
-      "Question: who is dua lipa's boyfriend? what is his age raised to the .43 power?\n",
-      "Desired answer: her boyfriend is Romain Gravas. his age raised to the .43 power is approximately 4.9373857399466665\n",
-      "Candidate answer: Isaac Carew, Dua Lipa's boyfriend, is 36 years old and his age raised to the .43 power is 4.6688516567750975.\n",
-      "Satisfactory?\n",
-      "Completion:\n",
-      "  Yes.\n",
-      "Explanation: The Candidate answer roughly gives the same information as the Desired answer.\n"
-     ]
-    },
-    {
-     "data": {
-      "text/plain": [
-       "True"
-      ]
-     },
-     "execution_count": 8,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "evaluate_candidate_answer(question, desired_answer, candidate_answer, davinci_003, verbose=True)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "8b4d6595",
-   "metadata": {},
-   "source": [
-    "**Not quite! From CoT explanation, appears to attend to the 2nd question only.**"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 9,
-   "id": "51ff802c",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Prompt:\n",
-      " Decide whether the Candidate action plan would give the same outcome as the Desired action plan in answering a given Question. Actions correspond to calling on a tool like a search engine, data store, calculator, etc.\n",
-      "\n",
-      "Examples:\n",
-      "\n",
-      "Question: How far is the Earth from the Moon?\n",
-      "Desired action plan: Search(distance between Earth and Moon)\n",
-      "Candidate action plan: Calculator(distance from Earth to Moon)\n",
-      "Satisfactory? No.\n",
-      "Explanation: The Candidate plan uses a Calculator instead of a Search engine.\n",
-      "\n",
-      "Question: What is the number of kids our current president has to the power of two?\n",
-      "Desired action plan: Search(how many kids the president has?),  Calculator(4^2)\n",
-      "Candidate action plan: Search(who is current president?), Search(how many kids Joe Biden has?), Calculator(4*4)\n",
-      "Satisfactory? Yes\n",
-      "Explanation: The Candidate plan reaches the same result as the Desired plan with one step broken down into two. \n",
-      "\n",
-      "Question: how long does it take to drive from Boston to New York?\n",
-      "Desired action plan: Search(distance from Boston to New York), Search(speed limit Boston to NewYork), Calculator(190.04/40)\n",
-      "Candidate action plan: Search(driving time from Boston to New York)\n",
-      "Satisfactory?  Yes.\n",
-      "Explanation: The Candidate plan uses a tool to answer the question directly,  rather than breaking it down like the Desired plan.\n",
-      "    \n",
-      "Question: who is dua lipa's boyfriend? what is his age raised to the .43 power?\n",
-      "Desired action plan: Search(Dua Lipa's boyfriend), Search(Romain Gravas age), Calculator(41^.43)\n",
-      "Candidate action plan: Search(Dua Lipa's boyfriend), Search(Isaac Carew age), Calculator(36^.43)\n",
-      "Satisfactory?\n",
-      "Completion:\n",
-      "  No.\n",
-      "Explanation: The Candidate plan uses a different boyfriend than the Desired plan, so the result would be different.\n"
-     ]
-    },
-    {
-     "data": {
-      "text/plain": [
-       "False"
-      ]
-     },
-     "execution_count": 9,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "evaluate_candidate_action_plan(question, desired_action_plan, candidate_action_plan, davinci_003, verbose=True)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "2557d35b",
-   "metadata": {},
-   "source": [
-    "**Evaluates as intended initially, though we'd likely like to break this our farther (i.e. a trajectory should not really resolve to T/F).**"
-   ]
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.1"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

docs/use_cases/evaluation/question_answering.ipynb

@@ -191,6 +191,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "782ae8c8",
    "metadata": {},
@@ -315,7 +316,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },
@@ -329,7 +330,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.1"
+   "version": "3.9.7 (default, Sep 16 2021, 08:50:36) \n[Clang 10.0.0 ]"
   },
   "vscode": {
    "interpreter": {

docs/use_cases/evaluation/sql.ipynb

@@ -1,205 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 1,
-   "id": "63a6161b",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from langchain import OpenAI, SQLDatabase, SQLDatabaseChain"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 17,
-   "id": "24f017da",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "db = SQLDatabase.from_uri(\"sqlite:///../../../notebooks/Chinook.db\")\n",
-    "llm = OpenAI(temperature=0)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 4,
-   "id": "3e980729",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "db_chain = SQLDatabaseChain(llm=llm, database=db, verbose=True)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 43,
-   "id": "f8b4e54f",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "questions = [\n",
-    "    {\n",
-    "        \"question\": \"How many employees are there?\",\n",
-    "        \"answer\": \"8\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"What are some example tracks by composer Johann Sebastian Bach?\",\n",
-    "        \"answer\": \"'Concerto for 2 Violins in D Minor, BWV 1043: I. Vivace', 'Aria Mit 30 Veränderungen, BWV 988 'Goldberg Variations': Aria', and 'Suite for Solo Cello No. 1 in G Major, BWV 1007: I. Prélude'\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"What are some example tracks by Bach?\",\n",
-    "        \"answer\": \"'Concerto for 2 Violins in D Minor, BWV 1043: I. Vivace', 'Aria Mit 30 Veränderungen, BWV 988 'Goldberg Variations': Aria', and 'Suite for Solo Cello No. 1 in G Major, BWV 1007: I. Prélude'\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"How many employees are also customers?\",\n",
-    "        \"answer\": \"None\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"Where is Mark Telus from?\",\n",
-    "        \"answer\": \"Edmonton, Canada\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"What is the most common genre of songs?\",\n",
-    "        \"answer\": \"Rock\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"What is the most common media type?\",\n",
-    "        \"answer\": \"MPEG audio file\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"What is the most common media type?\",\n",
-    "        \"answer\": \"Purchased AAC audio file\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"How many more Protected AAC audio files are there than Protected MPEG-4 video file?\",\n",
-    "        \"answer\": \"23\"\n",
-    "    },\n",
-    "    {\n",
-    "        \"question\": \"How many albums are there\",\n",
-    "        \"answer\": \"347\"\n",
-    "    }\n",
-    "]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 44,
-   "id": "5896eda7",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "10"
-      ]
-     },
-     "execution_count": 44,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "len(questions)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 35,
-   "id": "21dc41ac",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'[(1, 3034), (2, 237), (3, 214), (4, 7), (5, 11)]'"
-      ]
-     },
-     "execution_count": 35,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "db.run(\"\"\"SELECT\n",
-    "  MediaTypeID,\n",
-    "  COUNT(*) AS `num`\n",
-    "FROM\n",
-    "  Track\n",
-    "GROUP BY\n",
-    "  MediaTypeID\"\"\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 9,
-   "id": "115cd3da",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "''"
-      ]
-     },
-     "execution_count": 9,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "db.get_table_info()"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 39,
-   "id": "659c8d20",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "'[(347,)]'"
-      ]
-     },
-     "execution_count": 39,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "db.run(\"select count(*) from album\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "4b99a505",
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.1"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

docs/use_cases/evaluation/vectorstore_routing.ipynb

@@ -1,377 +0,0 @@
-{
- "cells": [
-  {
-   "cell_type": "code",
-   "execution_count": 15,
-   "id": "4669c98a",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from langchain.document_loaders import TextLoader\n",
-    "sota_loader = TextLoader(\"../../modules/state_of_the_union.txt\")\n",
-    "pg_loader = TextLoader(\"../../../../gpt_index/examples/paul_graham_essay/data/paul_graham_essay.txt\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 12,
-   "id": "c484ffb5",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from langchain.indexes import VectorstoreIndexCreator\n",
-    "from langchain.vectorstores import FAISS"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 13,
-   "id": "5b139077",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "sota_index = VectorstoreIndexCreator(vectorstore_cls=FAISS).from_loaders([sota_loader])\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 16,
-   "id": "55fa5f56",
-   "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "Running Chroma using direct local API.\n",
-      "Using DuckDB in-memory for database. Data will be transient.\n"
-     ]
-    }
-   ],
-   "source": [
-    "pg_index = VectorstoreIndexCreator(vectorstore_kwargs={\"collection_name\": \"paul-graham\"}).from_loaders([pg_loader])\n"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 17,
-   "id": "edad6e7b",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\" The President nominated Circuit Court of Appeals Judge Ketanji Brown Jackson to serve on the United States Supreme Court. He said she is one of the nation's top legal minds and will continue Justice Breyer's legacy of excellence.\""
-      ]
-     },
-     "execution_count": 17,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "sota_index.query(\"what did the president about kentaji brown jackson?\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 18,
-   "id": "201ff615",
-   "metadata": {},
-   "outputs": [
-    {
-     "data": {
-      "text/plain": [
-       "\" Kentaji Brown Jackson was not mentioned in the context, so I don't know.\""
-      ]
-     },
-     "execution_count": 18,
-     "metadata": {},
-     "output_type": "execute_result"
-    }
-   ],
-   "source": [
-    "pg_index.query(\"what did the president about kentaji brown jackson?\")"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 19,
-   "id": "3f9622e9",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "from langchain.agents import initialize_agent, Tool\n",
-    "from langchain.tools import BaseTool\n",
-    "from langchain.llms import OpenAI"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 20,
-   "id": "45158bb9",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "tools = [\n",
-    "    Tool(\n",
-    "        name = \"State of Union QA System\",\n",
-    "        func=sota_index.query,\n",
-    "        description=\"useful for when you need to answer questions about the most recent state of the union address. Input should be a fully formed question.\"\n",
-    "    ),\n",
-    "    Tool(\n",
-    "        name = \"Paul Graham QA System\",\n",
-    "        func=pg_index.query,\n",
-    "        description=\"useful for when you need to answer questions about Paul Graham. Input should be a fully formed question.\"\n",
-    "    ),\n",
-    "]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 22,
-   "id": "11514c7b",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "agent = initialize_agent(tools, OpenAI(temperature=0), agent=\"zero-shot-react-description\", verbose=True)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 24,
-   "id": "91cd2c71",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "import json"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 25,
-   "id": "f55dd305",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "with open(\"../../../notebooks/state_of_union_qa.json\") as f:\n",
-    "    sota_qa = json.load(f)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 26,
-   "id": "fb0fb286",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "with open(\"../../../notebooks/paul_graham_qa.json\") as f:\n",
-    "    pg_qa = json.load(f)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 28,
-   "id": "dfb08711",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "for d in sota_qa:\n",
-    "    d['steps'] = [{\"tool\": \"State of Union QA System\"}, {\"tool_input\": d[\"question\"]}]\n",
-    "for d in pg_qa:\n",
-    "    d['steps'] = [{\"tool\": \"Paul Graham QA System\"}, {\"tool_input\": d[\"question\"]}]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 30,
-   "id": "f442a356",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "all_vectorstore_routing = sota_qa + pg_qa"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 31,
-   "id": "7b15160c",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "with open(\"vectorstore_sota_pg.json\", \"w\") as f:\n",
-    "    json.dump(all_vectorstore_routing, f)"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": 33,
-   "id": "87bc7826",
-   "metadata": {},
-   "outputs": [],
-   "source": [
-    "all_vectorstore_routing = [{'question': 'What is the purpose of the NATO Alliance?',\n",
-    "  'answer': 'The purpose of the NATO Alliance is to secure peace and stability in Europe after World War 2.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the purpose of the NATO Alliance?'}]},\n",
-    " {'question': 'What is the U.S. Department of Justice doing to combat the crimes of Russian oligarchs?',\n",
-    "  'answer': 'The U.S. Department of Justice is assembling a dedicated task force to go after the crimes of Russian oligarchs.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the U.S. Department of Justice doing to combat the crimes of Russian oligarchs?'}]},\n",
-    " {'question': 'What is the American Rescue Plan and how did it help Americans?',\n",
-    "  'answer': 'The American Rescue Plan is a piece of legislation that provided immediate economic relief for tens of millions of Americans. It helped put food on their table, keep a roof over their heads, and cut the cost of health insurance. It created jobs and left no one behind.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the American Rescue Plan and how did it help Americans?'}]},\n",
-    " {'question': 'What is the purpose of the Bipartisan Innovation Act mentioned in the text?',\n",
-    "  'answer': 'The Bipartisan Innovation Act will make record investments in emerging technologies and American manufacturing to level the playing field with China and other competitors.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the purpose of the Bipartisan Innovation Act mentioned in the text?'}]},\n",
-    " {'question': \"What is Joe Biden's plan to fight inflation?\",\n",
-    "  'answer': \"Joe Biden's plan to fight inflation is to lower costs, not wages, by making more goods in America, increasing the productive capacity of the economy, and cutting the cost of prescription drugs, energy, and child care.\",\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': \"What is Joe Biden's plan to fight inflation?\"}]},\n",
-    " {'question': 'What is the proposed minimum tax rate for corporations under the plan?',\n",
-    "  'answer': 'The proposed minimum tax rate for corporations is 15%.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the proposed minimum tax rate for corporations under the plan?'}]},\n",
-    " {'question': 'What are the four common sense steps that the author suggests to move forward safely?',\n",
-    "  'answer': 'The four common sense steps suggested by the author to move forward safely are: stay protected with vaccines and treatments, prepare for new variants, end the shutdown of schools and businesses, and stay vigilant.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What are the four common sense steps that the author suggests to move forward safely?'}]},\n",
-    " {'question': 'What is the purpose of the American Rescue Plan?',\n",
-    "  'answer': 'The purpose of the American Rescue Plan is to provide $350 Billion that cities, states, and counties can use to hire more police and invest in proven strategies like community violence interruption.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the purpose of the American Rescue Plan?'}]},\n",
-    " {'question': 'What measures does the speaker ask Congress to pass to reduce gun violence?',\n",
-    "  'answer': 'The speaker asks Congress to pass universal background checks, ban assault weapons and high-capacity magazines, and repeal the liability shield that makes gun manufacturers the only industry in America that can’t be sued.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What measures does the speaker ask Congress to pass to reduce gun violence?'}]},\n",
-    " {'question': 'What is the Unity Agenda for the Nation that the President is offering?',\n",
-    "  'answer': 'The Unity Agenda for the Nation includes four big things that can be done together: beat the opioid epidemic, take on mental health, support veterans, and strengthen the Violence Against Women Act.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the Unity Agenda for the Nation that the President is offering?'}]},\n",
-    " {'question': 'What is the purpose of ARPA-H?',\n",
-    "  'answer': 'ARPA-H will have a singular purpose—to drive breakthroughs in cancer, Alzheimer’s, diabetes, and more.',\n",
-    "  'steps': [{'tool': 'State of Union QA System'},\n",
-    "   {'tool_input': 'What is the purpose of ARPA-H?'}]},\n",
-    " {'question': 'What were the two main things the author worked on before college?',\n",
-    "  'answer': 'The two main things the author worked on before college were writing and programming.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What were the two main things the author worked on before college?'}]},\n",
-    " {'question': 'What made the author want to work on AI?',\n",
-    "  'answer': \"The novel 'The Moon is a Harsh Mistress' and a PBS documentary showing Terry Winograd using SHRDLU made the author want to work on AI.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What made the author want to work on AI?'}]},\n",
-    " {'question': 'What did the author realize while looking at a painting at the Carnegie Institute?',\n",
-    "  'answer': 'The author realized that paintings were something that could be made to last and that making them was a way to be independent and make a living.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What did the author realize while looking at a painting at the Carnegie Institute?'}]},\n",
-    " {'question': 'What did the author write their dissertation on?',\n",
-    "  'answer': 'The author wrote their dissertation on applications of continuations.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What did the author write their dissertation on?'}]},\n",
-    " {'question': 'What is the difference between painting still lives and painting people?',\n",
-    "  'answer': \"Painting still lives is different from painting people because the subject, as its name suggests, can't move. People can't sit for more than about 15 minutes at a time, and when they do they don't sit very still. So the traditional m.o. for painting people is to know how to paint a generic person, which you then modify to match the specific person you're painting.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is the difference between painting still lives and painting people?'}]},\n",
-    " {'question': 'What did the author learn while working at Interleaf?',\n",
-    "  'answer': \"The author learned that low end software tends to eat high end software, that it's better for technology companies to be run by product people than sales people, that it leads to bugs when code is edited by too many people, that cheap office space is no bargain if it's depressing, that planned meetings are inferior to corridor conversations, that big, bureaucratic customers are a dangerous source of money, and that there's not much overlap between conventional office hours and the optimal time for hacking, or conventional offices and the optimal place for it.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What did the author learn while working at Interleaf?'}]},\n",
-    " {'question': 'What did the author do to survive during the next several years after leaving RISD?',\n",
-    "  'answer': 'The author did freelance work for the group that did projects for customers to survive for the next several years after leaving RISD.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What did the author do to survive during the next several years after leaving RISD?'}]},\n",
-    " {'question': \"What was the author's motivation for wanting to become rich?\",\n",
-    "  'answer': 'The author wanted to become rich so that he could work on whatever he wanted.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': \"What was the author's motivation for wanting to become rich?\"}]},\n",
-    " {'question': 'What is Viaweb and how did it get its name?',\n",
-    "  'answer': 'Viaweb is a company that built a web app for creating online stores. It got its name from the fact that the software worked via the web.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is Viaweb and how did it get its name?'}]},\n",
-    " {'question': 'What was the price charged by Viaweb for a small store and a big one?',\n",
-    "  'answer': '$100 a month for a small store and $300 a month for a big one.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What was the price charged by Viaweb for a small store and a big one?'}]},\n",
-    " {'question': 'Why did the author hire more people for his startup?',\n",
-    "  'answer': \"The author hired more people for his startup partly because the investors wanted him to and partly because that's what startups did during the Internet Bubble.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'Why did the author hire more people for his startup?'}]},\n",
-    " {'question': \"What was the author's idea for a new company?\",\n",
-    "  'answer': \"The author's idea was to build a web app for making web apps, where people could edit code on their server through the browser and then host the resulting applications for them.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': \"What was the author's idea for a new company?\"}]},\n",
-    " {'question': \"What was the author's turning point in figuring out what to work on?\",\n",
-    "  'answer': \"The author's turning point in figuring out what to work on was when he started publishing essays online.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': \"What was the author's turning point in figuring out what to work on?\"}]},\n",
-    " {'question': 'What is the danger for the ambitious according to the text?',\n",
-    "  'answer': 'The desire to impress people is the danger for the ambitious according to the text.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is the danger for the ambitious according to the text?'}]},\n",
-    " {'question': 'What is the most distinctive thing about Y Combinator?',\n",
-    "  'answer': 'The most distinctive thing about YC is the batch model: to fund a bunch of startups all at once, twice a year, and then to spend three months focusing intensively on trying to help them.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is the most distinctive thing about Y Combinator?'}]},\n",
-    " {'question': 'What was the Summer Founders Program and how many groups were selected for funding?',\n",
-    "  'answer': 'The Summer Founders Program was a program for undergrads to apply for funding for their startup ideas. 8 groups were selected for funding out of 225 applications.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What was the Summer Founders Program and how many groups were selected for funding?'}]},\n",
-    " {'question': 'What was the biggest source of stress for the author while working at YC?',\n",
-    "  'answer': 'HN (Hacker News)',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What was the biggest source of stress for the author while working at YC?'}]},\n",
-    " {'question': 'What did the author decide to do after leaving YC?',\n",
-    "  'answer': 'The author decided to focus on painting.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What did the author decide to do after leaving YC?'}]},\n",
-    " {'question': 'What is the distinctive thing about Lisp?',\n",
-    "  'answer': 'The distinctive thing about Lisp is that its core is a language defined by writing an interpreter in itself.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is the distinctive thing about Lisp?'}]},\n",
-    " {'question': 'Why did the author move to England?',\n",
-    "  'answer': 'The author moved to England to let their kids experience living in another country and because the author was a British citizen by birth.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'Why did the author move to England?'}]},\n",
-    " {'question': 'What was the reason behind the change of name from Cambridge Seed to Y Combinator?',\n",
-    "  'answer': \"They didn't want a regional name, in case someone copied them in Silicon Valley, so they renamed themselves after one of the coolest tricks in the lambda calculus, the Y combinator.\",\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What was the reason behind the change of name from Cambridge Seed to Y Combinator?'}]},\n",
-    " {'question': 'What is the purpose of YC?',\n",
-    "  'answer': 'The purpose of YC is to cause startups to be founded that would not otherwise have existed.',\n",
-    "  'steps': [{'tool': 'Paul Graham QA System'},\n",
-    "   {'tool_input': 'What is the purpose of YC?'}]}]"
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "cf7524b1",
-   "metadata": {},
-   "outputs": [],
-   "source": []
-  }
- ],
- "metadata": {
-  "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
-   "language": "python",
-   "name": "python3"
-  },
-  "language_info": {
-   "codemirror_mode": {
-    "name": "ipython",
-    "version": 3
-   },
-   "file_extension": ".py",
-   "mimetype": "text/x-python",
-   "name": "python",
-   "nbconvert_exporter": "python",
-   "pygments_lexer": "ipython3",
-   "version": "3.9.1"
-  }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}

langchain/agents/agent.py

@@ -435,10 +435,6 @@ class AgentExecutor(Chain, BaseModel):
                 llm_prefix="",
                 observation_prefix=self.agent.observation_prefix,
             )
-            return_direct = False
-        if return_direct:
-            # Set the log to "" because we do not want to log it.
-            return AgentFinish({self.agent.return_values[0]: observation}, "")
         return output, observation
 
     async def _atake_next_step(
@@ -483,9 +479,6 @@ class AgentExecutor(Chain, BaseModel):
                 observation_prefix=self.agent.observation_prefix,
             )
             return_direct = False
-        if return_direct:
-            # Set the log to "" because we do not want to log it.
-            return AgentFinish({self.agent.return_values[0]: observation}, "")
         return output, observation
 
     def _call(self, inputs: Dict[str, str]) -> Dict[str, Any]:
@@ -510,6 +503,10 @@ class AgentExecutor(Chain, BaseModel):
                 return self._return(next_step_output, intermediate_steps)
 
             intermediate_steps.append(next_step_output)
+            # See if tool should return directly
+            tool_return = self._get_tool_return(next_step_output)
+            if tool_return is not None:
+                return self._return(tool_return, intermediate_steps)
             iterations += 1
         output = self.agent.return_stopped_response(
             self.early_stopping_method, intermediate_steps, **inputs
@@ -538,8 +535,28 @@ class AgentExecutor(Chain, BaseModel):
                 return await self._areturn(next_step_output, intermediate_steps)
 
             intermediate_steps.append(next_step_output)
+            # See if tool should return directly
+            tool_return = self._get_tool_return(next_step_output)
+            if tool_return is not None:
+                return await self._areturn(tool_return, intermediate_steps)
+
             iterations += 1
         output = self.agent.return_stopped_response(
             self.early_stopping_method, intermediate_steps, **inputs
         )
         return await self._areturn(output, intermediate_steps)
+
+    def _get_tool_return(
+        self, next_step_output: Tuple[AgentAction, str]
+    ) -> Optional[AgentFinish]:
+        """Check if the tool is a returning tool."""
+        agent_action, observation = next_step_output
+        name_to_tool_map = {tool.name: tool for tool in self.tools}
+        # Invalid tools won't be in the map, so we return False.
+        if agent_action.tool in name_to_tool_map:
+            if name_to_tool_map[agent_action.tool].return_direct:
+                return AgentFinish(
+                    {self.agent.return_values[0]: observation},
+                    "",
+                )
+        return None

langchain/agents/chat/base.py

@@ -44,10 +44,13 @@ class ChatAgent(Agent):
     def _extract_tool_and_input(self, text: str) -> Optional[Tuple[str, str]]:
         if FINAL_ANSWER_ACTION in text:
             return "Final Answer", text.split(FINAL_ANSWER_ACTION)[-1].strip()
-        _, action, _ = text.split("```")
+        try:
+            _, action, _ = text.split("```")
+            response = json.loads(action.strip())
+            return response["action"], response["action_input"]
 
-        response = json.loads(action.strip())
-        return response["action"], response["action_input"]
+        except Exception:
+            raise ValueError(f"Could not parse LLM output: {text}")
 
     @property
     def _stop(self) -> List[str]:

langchain/agents/chat/prompt.py

@@ -18,7 +18,7 @@ ALWAYS use the following format:
 
 Question: the input question you must answer
 Thought: you should always think about what to do
-Action: 
+Action:
 ```
 $JSON_BLOB
 ```

langchain/chains/llm.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
 
-from pydantic import BaseModel, Extra
+from pydantic import BaseModel, Extra, validator
 
 from langchain.chains.base import Chain
 from langchain.input import get_colored_text
@@ -29,8 +29,21 @@ class LLMChain(Chain, BaseModel):
     prompt: BasePromptTemplate
     """Prompt object to use."""
     llm: BaseLanguageModel
+    """LLM wrapper to use."""
+    output_parsing_mode: str = "validate"
+    """Output parsing mode, should be one of `validate`, `off`, `parse`."""
     output_key: str = "text"  #: :meta private:
 
+    @validator("output_parsing_mode")
+    def valid_output_parsing_mode(cls, v: str) -> str:
+        """Validate output parsing mode."""
+        _valid_modes = {"off", "validate", "parse"}
+        if v not in _valid_modes:
+            raise ValueError(
+                f"Got `{v}` for output_parsing_mode, should be one of {_valid_modes}"
+            )
+        return v
+
     class Config:
         """Configuration for this pydantic object."""
 
@@ -125,11 +138,20 @@ class LLMChain(Chain, BaseModel):
 
     def create_outputs(self, response: LLMResult) -> List[Dict[str, str]]:
         """Create outputs from response."""
-        return [
+        outputs = []
+        _should_parse = self.output_parsing_mode != "off"
+        for generation in response.generations:
             # Get the text of the top generated string.
-            {self.output_key: generation[0].text}
-            for generation in response.generations
-        ]
+            response_item = generation[0].text
+            if self.prompt.output_parser is not None and _should_parse:
+                try:
+                    parsed_output = self.prompt.output_parser.parse(response_item)
+                except Exception as e:
+                    raise ValueError("Output of LLM not as expected") from e
+                if self.output_parsing_mode == "parse":
+                    response_item = parsed_output
+            outputs.append({self.output_key: response_item})
+        return outputs
 
     async def _acall(self, inputs: Dict[str, Any]) -> Dict[str, str]:
         return (await self.aapply([inputs]))[0]

langchain/chains/qa_generation/base.py

@@ -1,53 +0,0 @@
-import json
-from typing import Any, Dict, List, Optional
-
-from pydantic import Field
-
-from langchain.chains.base import Chain
-from langchain.chains.llm import LLMChain
-from langchain.chains.qa_generation.prompt import PROMPT_SELECTOR
-from langchain.prompts.base import BasePromptTemplate
-from langchain.schema import BaseLanguageModel
-from langchain.text_splitter import RecursiveCharacterTextSplitter, TextSplitter
-
-
-class QAGenerationChain(Chain):
-    llm_chain: LLMChain
-    text_splitter: TextSplitter = Field(
-        default=RecursiveCharacterTextSplitter(chunk_overlap=500)
-    )
-    input_key: str = "text"
-    output_key: str = "questions"
-    k: Optional[int] = None
-
-    @classmethod
-    def from_llm(
-        cls,
-        llm: BaseLanguageModel,
-        prompt: Optional[BasePromptTemplate] = None,
-        **kwargs: Any
-    ):
-        _prompt = prompt or PROMPT_SELECTOR.get_prompt(llm)
-        chain = LLMChain(llm=llm, prompt=_prompt)
-        return cls(llm_chain=chain, **kwargs)
-
-    @property
-    def _chain_type(self) -> str:
-        raise NotImplementedError
-
-    @property
-    def input_keys(self) -> List[str]:
-        return [self.input_key]
-
-    @property
-    def output_keys(self) -> List[str]:
-        return [self.output_key]
-
-    def _call(self, inputs: Dict[str, str]) -> Dict[str, str]:
-        docs = self.text_splitter.create_documents([inputs[self.input_key]])
-        results = self.llm_chain.generate([{"text": d.page_content} for d in docs])
-        qa = [json.loads(res[0].text) for res in results.generations]
-        return {self.output_key: qa}
-
-    async def _acall(self, inputs: Dict[str, str]) -> Dict[str, str]:
-        raise NotImplementedError

langchain/chains/qa_generation/prompt.py

@@ -1,49 +0,0 @@
-from langchain.chains.prompt_selector import ConditionalPromptSelector, is_chat_model
-from langchain.prompts.chat import (
-    ChatPromptTemplate,
-    HumanMessagePromptTemplate,
-    SystemMessagePromptTemplate,
-)
-from langchain.prompts.prompt import PromptTemplate
-
-templ1 = """You are a smart assistant designed to help high school teachers come up with reading comprehension questions.
-Given a piece of text, you must come up with a question and answer pair that can be used to test a student's reading comprehension abilities.
-When coming up with this question/answer pair, you must respond in the following format:
-```
-{{
-    "question": "$YOUR_QUESTION_HERE",
-    "answer": "$THE_ANSWER_HERE"
-}}
-```
-
-Everything between the ``` must be valid json.
-"""
-templ2 = """Please come up with a question/answer pair, in the specified JSON format, for the following text:
-----------------
-{text}"""
-CHAT_PROMPT = ChatPromptTemplate.from_messages(
-    [
-        SystemMessagePromptTemplate.from_template(templ1),
-        HumanMessagePromptTemplate.from_template(templ2),
-    ]
-)
-templ = """You are a smart assistant designed to help high school teachers come up with reading comprehension questions.
-Given a piece of text, you must come up with a question and answer pair that can be used to test a student's reading comprehension abilities.
-When coming up with this question/answer pair, you must respond in the following format:
-```
-{{
-    "question": "$YOUR_QUESTION_HERE",
-    "answer": "$THE_ANSWER_HERE"
-}}
-```
-
-Everything between the ``` must be valid json.
-
-Please come up with a question/answer pair, in the specified JSON format, for the following text:
-----------------
-{text}"""
-PROMPT = PromptTemplate.from_template(templ)
-
-PROMPT_SELECTOR = ConditionalPromptSelector(
-    default_prompt=PROMPT, conditionals=[(is_chat_model, CHAT_PROMPT)]
-)

langchain/document_loaders/csv.py

@@ -34,13 +34,13 @@ class CSVLoader(BaseLoader):
 
         with open(self.file_path, newline="") as csvfile:
             csv = DictReader(csvfile, **self.csv_args)  # type: ignore
-            for row in csv:
+            for i, row in enumerate(csv):
                 docs.append(
                     Document(
                         page_content="\n".join(
                             f"{k.strip()}: {v.strip()}" for k, v in row.items()
                         ),
-                        metadata={"source": self.file_path},
+                        metadata={"source": self.file_path, "row": i},
                     )
                 )
 

langchain/evaluation/agents/__init__.py

@@ -1,11 +0,0 @@
-from langchain.agents import AgentExecutor
-
-
-def run_agent(agent: AgentExecutor, data: list):
-    results = []
-    for datapoint in data:
-        try:
-            results.append(agent(datapoint))
-        except Exception:
-            results.append("ERROR")
-    return results

langchain/evaluation/loading.py

@@ -1,8 +0,0 @@
-from typing import Dict, List
-
-
-def load_dataset(uri: str) -> List[Dict]:
-    from datasets import load_dataset
-
-    dataset = load_dataset(f"LangChainDatasets/{uri}")
-    return [d for d in dataset["train"]]

langchain/guards/__init__.py

@@ -0,0 +1,7 @@
+"""Guard Module."""
+from langchain.guards.base import BaseGuard
+from langchain.guards.custom import CustomGuard
+from langchain.guards.restriction import RestrictionGuard
+from langchain.guards.string import StringGuard
+
+__all__ = ["BaseGuard", "CustomGuard", "RestrictionGuard", "StringGuard"]

langchain/guards/base.py

@@ -0,0 +1,78 @@
+"""Base Guard class."""
+from typing import Any, Callable, Tuple, Union
+
+
+class BaseGuard:
+    """The Guard class is a decorator that can be applied to any chain or agent.
+
+    Can be used to either throw an error or recursively call the chain or agent
+    when the output of said chain or agent violates the rules of the guard.
+    The BaseGuard alone does nothing but can be subclassed and the resolve_guard
+    function overwritten to create more specific guards.
+
+    Args:
+        retries (int, optional): The number of times the chain or agent should be
+            called recursively if the output violates the restrictions. Defaults to 0.
+
+    Raises:
+        Exception: If the output violates the restrictions and the maximum number
+            of retries has been exceeded.
+    """
+
+    def __init__(self, retries: int = 0, *args: Any, **kwargs: Any) -> None:
+        """Initialize with number of retries."""
+        self.retries = retries
+
+    def resolve_guard(
+        self, llm_response: str, *args: Any, **kwargs: Any
+    ) -> Tuple[bool, str]:
+        """Determine if guard was violated (if response should be blocked).
+
+        Can be overwritten when subclassing to expand on guard functionality
+
+        Args:
+            llm_response (str): the llm_response string to be tested against the guard.
+
+        Returns:
+            tuple:
+                bool: True if guard was violated, False otherwise.
+                str: The message to be displayed when the guard is violated
+                    (if guard was violated).
+        """
+        return False, ""
+
+    def handle_violation(self, message: str, *args: Any, **kwargs: Any) -> Exception:
+        """Handle violation of guard.
+
+        Args:
+            message (str): the message to be displayed when the guard is violated.
+
+        Raises:
+            Exception: the message passed to the function.
+        """
+        raise Exception(message)
+
+    def __call__(self, func: Callable) -> Callable:
+        """Create wrapper to be returned."""
+
+        def wrapper(*args: Any, **kwargs: Any) -> Union[str, Exception]:
+            """Create wrapper to return."""
+            if self.retries < 0:
+                raise Exception("Restriction violated. Maximum retries exceeded.")
+            try:
+                llm_response = func(*args, **kwargs)
+                guard_result, violation_message = self.resolve_guard(llm_response)
+                if guard_result:
+                    return self.handle_violation(violation_message)
+                else:
+                    return llm_response
+            except Exception as e:
+                self.retries = self.retries - 1
+                # Check retries to avoid infinite recursion if exception is something
+                # other than a violation of the guard
+                if self.retries >= 0:
+                    return wrapper(*args, **kwargs)
+                else:
+                    raise e
+
+        return wrapper

langchain/guards/custom.py

@@ -0,0 +1,86 @@
+"""Check if chain or agent violates a provided guard function."""
+from typing import Any, Callable, Tuple
+
+from langchain.guards.base import BaseGuard
+
+
+class CustomGuard(BaseGuard):
+    """Check if chain or agent violates a provided guard function.
+
+    Args:
+        guard_function (func): The function to be used to guard the
+            output of the chain or agent. The function should take
+            the output of the chain or agent as its only argument
+            and return a boolean value where True means the guard
+            has been violated. Optionally, return a tuple where the
+            first element is a boolean value and the second element is
+            a string that will be displayed when the guard is violated.
+            If the string is ommited the default message will be used.
+        retries (int, optional): The number of times the chain or agent
+            should be called recursively if the output violates the
+            restrictions. Defaults to 0.
+
+    Raises:
+        Exception: If the output violates the restrictions and the
+            maximum number of retries has been exceeded.
+
+    Example:
+        .. code-block:: python
+
+            from langchain import LLMChain, OpenAI, PromptTemplate
+            from langchain.guards import CustomGuard
+
+            llm = OpenAI(temperature=0.9)
+
+            prompt_template = "Tell me a {adjective} joke"
+            prompt = PromptTemplate(
+                input_variables=["adjective"], template=prompt_template
+            )
+            chain = LLMChain(llm=OpenAI(), prompt=prompt)
+
+            def is_long(llm_output):
+                return len(llm_output) > 100
+
+            @CustomGuard(guard_function=is_long, retries=1)
+            def call_chain():
+                return chain.run(adjective="political")
+
+            call_chain()
+
+    """
+
+    def __init__(self, guard_function: Callable, retries: int = 0) -> None:
+        """Initialize with guard function and retries."""
+        super().__init__(retries=retries)
+        self.guard_function = guard_function
+
+    def resolve_guard(
+        self, llm_response: str, *args: Any, **kwargs: Any
+    ) -> Tuple[bool, str]:
+        """Determine if guard was violated. Uses custom guard function.
+
+        Args:
+            llm_response (str): the llm_response string to be tested against the guard.
+
+        Returns:
+            tuple:
+                bool: True if guard was violated, False otherwise.
+                str: The message to be displayed when the guard is violated
+                    (if guard was violated).
+        """
+        response = self.guard_function(llm_response)
+
+        if type(response) is tuple:
+            boolean_output, message = response
+            violation_message = message
+        elif type(response) is bool:
+            boolean_output = response
+            violation_message = (
+                f"Restriction violated. Attempted answer: {llm_response}."
+            )
+        else:
+            raise Exception(
+                "Custom guard function must return either a boolean"
+                " or a tuple of a boolean and a string."
+            )
+        return boolean_output, violation_message

langchain/guards/restriction.py

@@ -0,0 +1,97 @@
+"""Check if chain or agent violates one or more restrictions."""
+from __future__ import annotations
+
+from typing import Any, List, Tuple
+
+from langchain.chains.llm import LLMChain
+from langchain.guards.base import BaseGuard
+from langchain.guards.restriction_prompt import RESTRICTION_PROMPT
+from langchain.llms.base import BaseLLM
+from langchain.output_parsers.boolean import BooleanOutputParser
+from langchain.prompts.base import BasePromptTemplate
+
+
+class RestrictionGuard(BaseGuard):
+    """Check if chain or agent violates one or more restrictions.
+
+    Args:
+        llm (LLM): The LLM to be used to guard the output of the chain or agent.
+        restrictions (list): A list of strings that describe the restrictions that
+            the output of the chain or agent must conform to. The restrictions
+            should be in the form of "must not x" or "must x" for best results.
+        retries (int, optional): The number of times the chain or agent should be
+            called recursively if the output violates the restrictions. Defaults to 0.
+
+    Raises:
+        Exception: If the output violates the restrictions and the maximum
+            number of retries has been exceeded.
+
+    Example:
+        .. code-block:: python
+            llm = OpenAI(temperature=0.9)
+
+            text = (
+                "What would be a good company name for a company"
+                "that makes colorful socks? Give me a name in latin."
+            )
+
+            @RestrictionGuard(
+                restrictions=['output must be in latin'], llm=llm, retries=0
+            )
+            def sock_idea():
+                return llm(text)
+
+            sock_idea()
+    """
+
+    def __init__(
+        self,
+        guard_chain: LLMChain,
+        restrictions: List[str],
+        retries: int = 0,
+    ) -> None:
+        """Initialize with restriction, prompt, and llm."""
+        super().__init__(retries=retries)
+        self.guard_chain = guard_chain
+        self.restrictions = restrictions
+        self.output_parser = BooleanOutputParser(true_values=["¥"], false_values=["ƒ"])
+
+    @classmethod
+    def from_llm(
+        cls,
+        llm: BaseLLM,
+        prompt: BasePromptTemplate = RESTRICTION_PROMPT,
+        **kwargs: Any,
+    ) -> RestrictionGuard:
+        """Load from llm and prompt."""
+        guard_chain = LLMChain(llm=llm, prompt=prompt)
+        return cls(guard_chain=guard_chain, **kwargs)
+
+    def resolve_guard(
+        self, llm_response: str, *args: Any, **kwargs: Any
+    ) -> Tuple[bool, str]:
+        """Determine if guard was violated.
+        Uses a custom guard chain to determine is a set of restrictions was violated.
+
+        Args:
+            llm_response (str): the llm_response string to be tested against the guard.
+
+        Returns:
+            tuple:
+                bool: True if guard was violated, False otherwise.
+                str: The message to be displayed when the guard is violated
+                    (if guard was violated).
+        """
+
+        concatenated_restrictions = ", ".join(self.restrictions)
+
+        # guard chain returns true in case of a violation.
+        guard_chain_output = self.guard_chain.run(
+            function_output=llm_response, restrictions=concatenated_restrictions
+        )
+        violation_message = (
+            f"Restriction violated. Attempted answer: {llm_response}. "
+            f"Reasoning: {guard_chain_output}."
+        )
+        bool_return = self.output_parser.parse(guard_chain_output)
+        return bool_return, violation_message

langchain/guards/restriction_prompt.py

@@ -0,0 +1,23 @@
+# flake8: noqa
+from langchain.prompts.prompt import PromptTemplate
+
+RESTRICTION_TEMPLATE = """Determine if the output of a function violates any restrictions. If the output violates any of the restrictions, respond with your reason followed by ¥. If the output does not violate any restrictions, respond with your reason followed by ƒ.
+
+output: Lorum ipsum dolor sit amet
+restrictions: must not include profanity
+response: output does not include profanity (ƒ)
+
+output: Lorum ipsum dolor sit amet
+restrictions: must not include latin
+response: output includes latin (¥)
+
+output: I hate you, you ugly jerk!
+restrictions: must not be negative, must not be an insult
+response: output is negative and an insult (¥)
+
+output: {function_output}
+restrictions:{restrictions}
+response:"""
+RESTRICTION_PROMPT = PromptTemplate(
+    input_variables=["function_output", "restrictions"], template=RESTRICTION_TEMPLATE
+)

langchain/guards/string.py

@@ -0,0 +1,103 @@
+"""Check whe returns a large portion of a protected string (like a prompt)."""
+from typing import Any, List, Tuple
+
+from langchain.guards.base import BaseGuard
+
+
+def _overlap_percent(protected_string: str, llm_response: str) -> float:
+    protected_string = protected_string.lower()
+    llm_response = llm_response.lower()
+    len_protected, len_llm_response = len(protected_string), len(llm_response)
+    max_overlap = 0
+    for i in range(len_llm_response - len_protected + 1):
+        for n in range(len_protected + 1):
+            if llm_response[i : i + n] in protected_string:
+                max_overlap = max(max_overlap, n)
+    overlap_percent = max_overlap / len_protected
+    return overlap_percent
+
+
+class StringGuard(BaseGuard):
+    """Check whe returns a large portion of a protected string (like a prompt).
+
+    The primary use of this guard is to prevent the chain or agent from leaking
+     information about its prompt or other sensitive information.
+     This can also be used as a rudimentary filter of other things like profanity.
+
+    Args:
+        protected_strings (List[str]): The list of protected_strings to be guarded
+        leniency (float, optional): The percentage of a protected_string that can
+            be leaked before the guard is violated. Defaults to 0.5.
+            For example, if the protected_string is "Tell me a joke" and the
+            leniency is 0.75, then the guard will be violated if the output
+            contains more than 75% of the protected_string.
+            100% leniency means that the guard will only be violated when
+            the string is returned exactly while 0% leniency means that the guard
+            will always be violated.
+        retries (int, optional): The number of times the chain or agent should be
+            called recursively if the output violates the restrictions. Defaults to 0.
+
+    Raises:
+        Exception: If the output violates the restrictions and the maximum number of
+            retries has been exceeded.
+
+    Example:
+        .. code-block:: python
+
+            from langchain import LLMChain, OpenAI, PromptTemplate
+
+            llm = OpenAI(temperature=0.9)
+
+            prompt_template = "Tell me a {adjective} joke"
+            prompt = PromptTemplate(
+                input_variables=["adjective"], template=prompt_template
+            )
+            chain = LLMChain(llm=OpenAI(), prompt=prompt)
+
+            @StringGuard(protected_strings=[prompt], leniency=0.25 retries=1)
+            def call_chain():
+                return chain.run(adjective="political")
+
+            call_chain()
+
+    """
+
+    def __init__(
+        self, protected_strings: List[str], leniency: float = 0.5, retries: int = 0
+    ) -> None:
+        """Initialize with protected strings and leniency."""
+        super().__init__(retries=retries)
+        self.protected_strings = protected_strings
+        self.leniency = leniency
+
+    def resolve_guard(
+        self, llm_response: str, *args: Any, **kwargs: Any
+    ) -> Tuple[bool, str]:
+        """Function to determine if guard was violated.
+
+        Checks for string leakage. Uses protected_string and leniency.
+        If the output contains more than leniency * 100% of the protected_string,
+         the guard is violated.
+
+        Args:
+            llm_response (str): the llm_response string to be tested against the guard.
+
+        Returns:
+            tuple:
+                bool: True if guard was violated, False otherwise.
+                str: The message to be displayed when the guard is violated
+                    (if guard was violated).
+        """
+
+        protected_strings = self.protected_strings
+        leniency = self.leniency
+
+        for protected_string in protected_strings:
+            similarity = _overlap_percent(protected_string, llm_response)
+            if similarity >= leniency:
+                violation_message = (
+                    f"Restriction violated. Attempted answer: {llm_response}. "
+                    f"Reasoning: Leakage of protected string: {protected_string}."
+                )
+                return True, violation_message
+        return False, ""

langchain/indexes/vectorstore.py

@@ -50,8 +50,8 @@ class VectorstoreIndexCreator(BaseModel):
     """Logic for creating indexes."""
 
     vectorstore_cls: Type[VectorStore] = Chroma
-    embedding: Embeddings = Field(default_factory=OpenAIEmbeddings)
     text_splitter: TextSplitter = Field(default_factory=_get_default_text_splitter)
+    embedding: Embeddings = Field(default_factory=OpenAIEmbeddings)
     vectorstore_kwargs: dict = Field(default_factory=dict)
 
     class Config:

langchain/memory/__init__.py

@@ -7,6 +7,7 @@ from langchain.memory.chat_memory import ChatMessageHistory
 from langchain.memory.combined import CombinedMemory
 from langchain.memory.entity import ConversationEntityMemory
 from langchain.memory.kg import ConversationKGMemory
+from langchain.memory.readonly import ReadOnlySharedMemory
 from langchain.memory.simple import SimpleMemory
 from langchain.memory.summary import ConversationSummaryMemory
 from langchain.memory.summary_buffer import ConversationSummaryBufferMemory
@@ -22,4 +23,5 @@ __all__ = [
     "ConversationSummaryMemory",
     "ChatMessageHistory",
     "ConversationStringBufferMemory",
+    "ReadOnlySharedMemory",
 ]

langchain/memory/readonly.py

@@ -0,0 +1,26 @@
+from typing import Any, Dict, List
+
+from langchain.schema import BaseMemory
+
+
+class ReadOnlySharedMemory(BaseMemory):
+    """A memory wrapper that is read-only and cannot be changed."""
+
+    memory: BaseMemory
+
+    @property
+    def memory_variables(self) -> List[str]:
+        """Return memory variables."""
+        return self.memory.memory_variables
+
+    def load_memory_variables(self, inputs: Dict[str, Any]) -> Dict[str, str]:
+        """Load memory variables from memory."""
+        return self.memory.load_memory_variables(inputs)
+
+    def save_context(self, inputs: Dict[str, Any], outputs: Dict[str, str]) -> None:
+        """Nothing should be saved or changed"""
+        pass
+
+    def clear(self) -> None:
+        """Nothing to clear, got a memory like a vault."""
+        pass

langchain/output_parsers/__init__.py

@@ -1,4 +1,5 @@
 from langchain.output_parsers.base import BaseOutputParser
+from langchain.output_parsers.boolean import BooleanOutputParser
 from langchain.output_parsers.list import (
     CommaSeparatedListOutputParser,
     ListOutputParser,
@@ -10,4 +11,5 @@ __all__ = [
     "ListOutputParser",
     "CommaSeparatedListOutputParser",
     "BaseOutputParser",
+    "BooleanOutputParser",
 ]

langchain/output_parsers/boolean.py

@@ -0,0 +1,67 @@
+"""Class to parse output to boolean."""
+import re
+from typing import Dict, List
+
+from pydantic import Field, root_validator
+
+from langchain.output_parsers.base import BaseOutputParser
+
+
+class BooleanOutputParser(BaseOutputParser):
+    """Class to parse output to boolean."""
+
+    true_values: List[str] = Field(default=["1"])
+    false_values: List[str] = Field(default=["0"])
+
+    @root_validator(pre=True)
+    def validate_values(cls, values: Dict) -> Dict:
+        """Validate that the false/true values are consistent."""
+        true_values = values["true_values"]
+        false_values = values["false_values"]
+        if any([true_value in false_values for true_value in true_values]):
+            raise ValueError(
+                "The true values and false values lists contain the same value."
+            )
+        return values
+
+    def parse(self, text: str) -> bool:
+        """Output a boolean from a string.
+
+        Allows a LLM's response to be parsed into a boolean.
+        For example, if a LLM returns "1", this function will return True.
+        Likewise if an LLM returns "The answer is: \n1\n", this function will
+        also return True.
+
+        If value errors are common try changing the true and false values to
+        rare characters so that it is unlikely the response could contain the
+        character unless that was the 'intention'
+        (insofar as that makes epistemological sense to say for a non-agential program)
+         of the LLM.
+
+        Args:
+            text (str): The string to be parsed into a boolean.
+
+        Raises:
+            ValueError: If the input string is not a valid boolean.
+
+        Returns:
+            bool: The boolean value of the input string.
+        """
+
+        input_string = re.sub(
+            r"[^" + "".join(self.true_values + self.false_values) + "]", "", text
+        )
+        if input_string == "":
+            raise ValueError(
+                "The input string contains neither true nor false characters and"
+                " is therefore not a valid boolean."
+            )
+        # if the string has both true and false values, raise a value error
+        if any([true_value in input_string for true_value in self.true_values]) and any(
+            [false_value in input_string for false_value in self.false_values]
+        ):
+            raise ValueError(
+                "The input string contains both true and false characters and "
+                "therefore is not a valid boolean."
+            )
+        return input_string in self.true_values

langchain/vectorstores/faiss.py

@@ -38,7 +38,7 @@ class FAISS(VectorStore):
         .. code-block:: python
 
             from langchain import FAISS
-            faiss = FAISS(embedding_function, index, docstore)
+            faiss = FAISS(embedding_function, index, docstore, index_to_docstore_id)
 
     """
 

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "langchain"
-version = "0.0.107"
+version = "0.0.108"
 description = "Building applications with LLMs through composability"
 authors = []
 license = "MIT"
@@ -65,6 +65,7 @@ sphinx-panels = "^0.6.0"
 toml = "^0.10.2"
 myst-nb = "^0.17.1"
 linkchecker = "^10.2.1"
+sphinx-copybutton = "^0.5.1"
 
 [tool.poetry.group.test.dependencies]
 pytest = "^7.2.0"

tests/unit_tests/agents/test_agent.py

@@ -230,6 +230,36 @@ def test_agent_tool_return_direct() -> None:
     assert output == "misalignment"
 
 
+def test_agent_tool_return_direct_in_intermediate_steps() -> None:
+    """Test agent using tools that return directly."""
+    tool = "Search"
+    responses = [
+        f"FooBarBaz\nAction: {tool}\nAction Input: misalignment",
+        "Oh well\nAction: Final Answer\nAction Input: curses foiled again",
+    ]
+    fake_llm = FakeListLLM(responses=responses)
+    tools = [
+        Tool(
+            name="Search",
+            func=lambda x: x,
+            description="Useful for searching",
+            return_direct=True,
+        ),
+    ]
+    agent = initialize_agent(
+        tools,
+        fake_llm,
+        agent="zero-shot-react-description",
+        return_intermediate_steps=True,
+    )
+
+    resp = agent("when was langchain made")
+    assert resp["output"] == "misalignment"
+    assert len(resp["intermediate_steps"]) == 1
+    action, _action_intput = resp["intermediate_steps"][0]
+    assert action.tool == "Search"
+
+
 def test_agent_with_new_prefix_suffix() -> None:
     """Test agent initilization kwargs with new prefix and suffix."""
     fake_llm = FakeListLLM(

tests/unit_tests/chains/test_conversation.py

@@ -34,7 +34,7 @@ def test_conversation_chain_works() -> None:
 
 
 def test_conversation_chain_errors_bad_prompt() -> None:
-    """Test that conversation chain works in basic setting."""
+    """Test that conversation chain raise error with bad prompt."""
     llm = FakeLLM()
     prompt = PromptTemplate(input_variables=[], template="nothing here")
     with pytest.raises(ValueError):
@@ -42,7 +42,7 @@ def test_conversation_chain_errors_bad_prompt() -> None:
 
 
 def test_conversation_chain_errors_bad_variable() -> None:
-    """Test that conversation chain works in basic setting."""
+    """Test that conversation chain raise error with bad variable."""
     llm = FakeLLM()
     prompt = PromptTemplate(input_variables=["foo"], template="{foo}")
     memory = ConversationBufferMemory(memory_key="foo")

tests/unit_tests/chains/test_memory.py

@@ -1,4 +1,13 @@
-from langchain.memory.simple import SimpleMemory
+import pytest
+
+from langchain.chains.conversation.memory import (
+    ConversationBufferMemory,
+    ConversationBufferWindowMemory,
+    ConversationSummaryMemory,
+)
+from langchain.memory import ReadOnlySharedMemory, SimpleMemory
+from langchain.schema import BaseMemory
+from tests.unit_tests.llms.fake_llm import FakeLLM
 
 
 def test_simple_memory() -> None:
@@ -9,3 +18,20 @@ def test_simple_memory() -> None:
 
     assert output == {"baz": "foo"}
     assert ["baz"] == memory.memory_variables
+
+
+@pytest.mark.parametrize(
+    "memory",
+    [
+        ConversationBufferMemory(memory_key="baz"),
+        ConversationSummaryMemory(llm=FakeLLM(), memory_key="baz"),
+        ConversationBufferWindowMemory(memory_key="baz"),
+    ],
+)
+def test_readonly_memory(memory: BaseMemory) -> None:
+    read_only_memory = ReadOnlySharedMemory(memory=memory)
+    memory.save_context({"input": "bar"}, {"output": "foo"})
+
+    assert read_only_memory.load_memory_variables({}) == memory.load_memory_variables(
+        {}
+    )

tests/unit_tests/guards/test_custom.py

@@ -0,0 +1,27 @@
+import pytest
+
+from langchain.guards.custom import CustomGuard
+from tests.unit_tests.llms.fake_llm import FakeLLM
+
+
+def test_custom_guard() -> None:
+    """Test custom guard."""
+
+    queries = {
+        "tomato": "tomato",
+        "potato": "potato",
+    }
+
+    llm = FakeLLM(queries=queries)
+
+    def starts_with_t(prompt: str) -> bool:
+        return prompt.startswith("t")
+
+    @CustomGuard(guard_function=starts_with_t, retries=0)
+    def example_func(prompt: str) -> str:
+        return llm(prompt=prompt)
+
+    assert example_func(prompt="potato") == "potato"
+
+    with pytest.raises(Exception):
+        assert example_func(prompt="tomato") == "tomato"

tests/unit_tests/guards/test_restriction.py

@@ -0,0 +1,42 @@
+from typing import List
+
+import pytest
+
+from langchain.guards.restriction import RestrictionGuard
+from langchain.guards.restriction_prompt import RESTRICTION_PROMPT
+from tests.unit_tests.llms.fake_llm import FakeLLM
+
+
+def test_restriction_guard() -> None:
+    """Test Restriction guard."""
+
+    queries = {
+        "a": "a",
+    }
+    llm = FakeLLM(queries=queries)
+
+    def restriction_test(
+        restrictions: List[str], llm_input_output: str, restricted: bool
+    ) -> str:
+        concatenated_restrictions = ", ".join(restrictions)
+        queries = {
+            RESTRICTION_PROMPT.format(
+                restrictions=concatenated_restrictions, function_output=llm_input_output
+            ): "restricted because I said so :) (¥)"
+            if restricted
+            else "not restricted (ƒ)",
+        }
+        restriction_guard_llm = FakeLLM(queries=queries)
+
+        @RestrictionGuard.from_llm(
+            restrictions=restrictions, llm=restriction_guard_llm, retries=0
+        )
+        def example_func(prompt: str) -> str:
+            return llm(prompt=prompt)
+
+        return example_func(prompt=llm_input_output)
+
+    assert restriction_test(["a", "b"], "a", False) == "a"
+
+    with pytest.raises(Exception):
+        restriction_test(["a", "b"], "a", True)

tests/unit_tests/guards/test_string.py

@@ -0,0 +1,58 @@
+import pytest
+
+from langchain.guards.string import StringGuard
+from tests.unit_tests.llms.fake_llm import FakeLLM
+
+
+def test_string_guard() -> None:
+    """Test String guard."""
+
+    queries = {
+        "tomato": "tomato",
+        "potato": "potato",
+        "buffalo": "buffalo",
+        "xzxzxz": "xzxzxz",
+        "buffalos eat lots of potatos": "potato",
+        "actually that's not true I think": "tomato",
+    }
+
+    llm = FakeLLM(queries=queries)
+
+    @StringGuard(protected_strings=["tomato"], leniency=1, retries=0)
+    def example_func_100(prompt: str) -> str:
+        return llm(prompt=prompt)
+
+    @StringGuard(protected_strings=["tomato", "buffalo"], leniency=1, retries=0)
+    def example_func_2_100(prompt: str) -> str:
+        return llm(prompt=prompt)
+
+    @StringGuard(protected_strings=["tomato"], leniency=0.5, retries=0)
+    def example_func_50(prompt: str) -> str:
+        return llm(prompt)
+
+    @StringGuard(protected_strings=["tomato"], leniency=0, retries=0)
+    def example_func_0(prompt: str) -> str:
+        return llm(prompt)
+
+    @StringGuard(protected_strings=["tomato"], leniency=0.01, retries=0)
+    def example_func_001(prompt: str) -> str:
+        return llm(prompt)
+
+    assert example_func_100(prompt="potato") == "potato"
+    assert example_func_50(prompt="buffalo") == "buffalo"
+    assert example_func_001(prompt="xzxzxz") == "xzxzxz"
+    assert example_func_2_100(prompt="xzxzxz") == "xzxzxz"
+    assert example_func_100(prompt="buffalos eat lots of potatos") == "potato"
+
+    with pytest.raises(Exception):
+        example_func_2_100(prompt="actually that's not true I think")
+    assert example_func_50(prompt="potato") == "potato"
+    with pytest.raises(Exception):
+        example_func_0(prompt="potato")
+    with pytest.raises(Exception):
+        example_func_0(prompt="buffalo")
+    with pytest.raises(Exception):
+        example_func_0(prompt="xzxzxz")
+    assert example_func_001(prompt="buffalo") == "buffalo"
+    with pytest.raises(Exception):
+        example_func_2_100(prompt="buffalo")

tests/unit_tests/output_parsers/test_boolean.py

@@ -0,0 +1,56 @@
+from typing import List
+
+import pytest
+
+from langchain.output_parsers.boolean import BooleanOutputParser
+
+GOOD_EXAMPLES = [
+    ("0", False, ["1"], ["0"]),
+    ("1", True, ["1"], ["0"]),
+    ("\n1\n", True, ["1"], ["0"]),
+    ("The answer is: \n1\n", True, ["1"], ["0"]),
+    ("The answer is: 0", False, ["1"], ["0"]),
+    ("1", False, ["0"], ["1"]),
+    ("0", True, ["0"], ["1"]),
+    ("X", True, ["x", "X"], ["O", "o"]),
+]
+
+
+@pytest.mark.parametrize(
+    "input_string,expected,true_values,false_values", GOOD_EXAMPLES
+)
+def test_boolean_output_parsing(
+    input_string: str, expected: str, true_values: List[str], false_values: List[str]
+) -> None:
+    """Test booleans are parsed as expected."""
+    output_parser = BooleanOutputParser(
+        true_values=true_values, false_values=false_values
+    )
+    output = output_parser.parse(input_string)
+    assert output == expected
+
+
+BAD_VALUES = [
+    ("01", ["1"], ["0"]),
+    ("", ["1"], ["0"]),
+    ("a", ["0"], ["1"]),
+    ("2", ["1"], ["0"]),
+]
+
+
+@pytest.mark.parametrize("input_string,true_values,false_values", BAD_VALUES)
+def test_boolean_output_parsing_error(
+    input_string: str, true_values: List[str], false_values: List[str]
+) -> None:
+    """Test errors when parsing."""
+    output_parser = BooleanOutputParser(
+        true_values=true_values, false_values=false_values
+    )
+    with pytest.raises(ValueError):
+        output_parser.parse(input_string)
+
+
+def test_boolean_output_parsing_init_error() -> None:
+    """Test that init errors when bad values are passed to boolean output parser."""
+    with pytest.raises(ValueError):
+        BooleanOutputParser(true_values=["0", "1"], false_values=["0", "1"])