improve documentation on how to pass in custom prompts (#561)

docs/modules/chains/combine_docs_examples/qa_with_sources.ipynb

@@ -31,7 +31,8 @@
     "from langchain.text_splitter import CharacterTextSplitter\n",
     "from langchain.vectorstores.elastic_vector_search import ElasticVectorSearch\n",
     "from langchain.vectorstores.faiss import FAISS\n",
-    "from langchain.docstore.document import Document"
+    "from langchain.docstore.document import Document\n",
+    "from langchain.prompts import PromptTemplate"
    ]
   },
   {
@@ -81,6 +82,46 @@
     "from langchain.llms import OpenAI"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "5b119026",
+   "metadata": {},
+   "source": [
+    "## Quickstart\n",
+    "If you just want to get started as quickly as possible, this is the recommended way to do it:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "id": "3722373b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'output_text': ' The president thanked Justice Breyer for his service.\\nSOURCES: 30-pl'}"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "chain = load_qa_with_sources_chain(OpenAI(temperature=0), chain_type=\"stuff\")\n",
+    "query = \"What did the president say about Justice Breyer\"\n",
+    "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bdaf9268",
+   "metadata": {},
+   "source": [
+    "If you want more control and understanding over what is happening, please see the information below."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "d82f899a",
@@ -123,6 +164,51 @@
     "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e966aea8",
+   "metadata": {},
+   "source": [
+    "**Custom Prompts**\n",
+    "\n",
+    "You can also use your own prompts with this chain. In this example, we will respond in Italian."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "426c570b",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'output_text': '\\nNon so cosa abbia detto il presidente riguardo a Justice Breyer.\\nSOURCES: 30, 31, 33'}"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "template = \"\"\"Given the following extracted parts of a long document and a question, create a final answer with references (\"SOURCES\"). \n",
+    "If you don't know the answer, just say that you don't know. Don't try to make up an answer.\n",
+    "ALWAYS return a \"SOURCES\" part in your answer.\n",
+    "Respond in Italian.\n",
+    "\n",
+    "QUESTION: {question}\n",
+    "=========\n",
+    "{summaries}\n",
+    "=========\n",
+    "FINAL ANSWER IN ITALIAN:\"\"\"\n",
+    "PROMPT = PromptTemplate(template=template, input_variables=[\"summaries\", \"question\"])\n",
+    "\n",
+    "chain = load_qa_with_sources_chain(OpenAI(temperature=0), chain_type=\"stuff\", prompt=PROMPT)\n",
+    "query = \"What did the president say about Justice Breyer\"\n",
+    "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "c5dbb304",
@@ -210,6 +296,66 @@
     "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "d56e101a",
+   "metadata": {},
+   "source": [
+    "**Custom Prompts**\n",
+    "\n",
+    "You can also use your own prompts with this chain. In this example, we will respond in Italian."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "47f0d517",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'intermediate_steps': [\"\\nStasera vorrei onorare qualcuno che ha dedicato la sua vita a servire questo paese: il giustizia Stephen Breyer - un veterano dell'esercito, uno studioso costituzionale e un giustizia in uscita della Corte Suprema degli Stati Uniti. Giustizia Breyer, grazie per il tuo servizio.\",\n",
+       "  ' Non pertinente.',\n",
+       "  ' Non rilevante.',\n",
+       "  \" Non c'è testo pertinente.\"],\n",
+       " 'output_text': ' Non conosco la risposta. SOURCES: 30, 31, 33, 20.'}"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "\n",
+    "question_prompt_template = \"\"\"Use the following portion of a long document to see if any of the text is relevant to answer the question. \n",
+    "Return any relevant text in Italian.\n",
+    "{context}\n",
+    "Question: {question}\n",
+    "Relevant text, if any, in Italian:\"\"\"\n",
+    "QUESTION_PROMPT = PromptTemplate(\n",
+    "    template=question_prompt_template, input_variables=[\"context\", \"question\"]\n",
+    ")\n",
+    "\n",
+    "combine_prompt_template = \"\"\"Given the following extracted parts of a long document and a question, create a final answer with references (\"SOURCES\"). \n",
+    "If you don't know the answer, just say that you don't know. Don't try to make up an answer.\n",
+    "ALWAYS return a \"SOURCES\" part in your answer.\n",
+    "Respond in Italian.\n",
+    "\n",
+    "QUESTION: {question}\n",
+    "=========\n",
+    "{summaries}\n",
+    "=========\n",
+    "FINAL ANSWER IN ITALIAN:\"\"\"\n",
+    "COMBINE_PROMPT = PromptTemplate(\n",
+    "    template=combine_prompt_template, input_variables=[\"summaries\", \"question\"]\n",
+    ")\n",
+    "\n",
+    "chain = load_qa_with_sources_chain(OpenAI(temperature=0), chain_type=\"map_reduce\", return_intermediate_steps=True, question_prompt=QUESTION_PROMPT, combine_prompt=COMBINE_PROMPT)\n",
+    "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "5bf0e1ab",
@@ -297,6 +443,81 @@
     "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "cf08c8a1",
+   "metadata": {},
+   "source": [
+    "**Custom Prompts**\n",
+    "\n",
+    "You can also use your own prompts with this chain. In this example, we will respond in Italian."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "97e33bd9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "refine_template = (\n",
+    "    \"The original question is as follows: {question}\\n\"\n",
+    "    \"We have provided an existing answer, including sources: {existing_answer}\\n\"\n",
+    "    \"We have the opportunity to refine the existing answer\"\n",
+    "    \"(only if needed) with some more context below.\\n\"\n",
+    "    \"------------\\n\"\n",
+    "    \"{context_str}\\n\"\n",
+    "    \"------------\\n\"\n",
+    "    \"Given the new context, refine the original answer to better \"\n",
+    "    \"answer the question (in Italian)\"\n",
+    "    \"If you do update it, please update the sources as well. \"\n",
+    "    \"If the context isn't useful, return the original answer.\"\n",
+    ")\n",
+    "refine_prompt = PromptTemplate(\n",
+    "    input_variables=[\"question\", \"existing_answer\", \"context_str\"],\n",
+    "    template=refine_template,\n",
+    ")\n",
+    "\n",
+    "\n",
+    "question_template = (\n",
+    "    \"Context information is below. \\n\"\n",
+    "    \"---------------------\\n\"\n",
+    "    \"{context_str}\"\n",
+    "    \"\\n---------------------\\n\"\n",
+    "    \"Given the context information and not prior knowledge, \"\n",
+    "    \"answer the question in Italian: {question}\\n\"\n",
+    ")\n",
+    "question_prompt = PromptTemplate(\n",
+    "    input_variables=[\"context_str\", \"question\"], template=question_template\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "41565992",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'intermediate_steps': ['\\nIl presidente ha detto che Justice Breyer ha dedicato la sua vita al servizio di questo paese e ha onorato la sua carriera.',\n",
+       "  \"\\n\\nIl presidente ha detto che Justice Breyer ha dedicato la sua vita al servizio di questo paese, ha onorato la sua carriera e ha contribuito a costruire un consenso. Ha ricevuto un ampio sostegno, dall'Ordine Fraterno della Polizia a ex giudici nominati da democratici e repubblicani. Inoltre, ha sottolineato l'importanza di avanzare la libertà e la giustizia attraverso la sicurezza delle frontiere e la risoluzione del sistema di immigrazione. Ha anche menzionato le nuove tecnologie come scanner all'avanguardia per rilevare meglio il traffico di droga, le pattuglie congiunte con Messico e Guatemala per catturare più trafficanti di esseri umani, l'istituzione di giudici di immigrazione dedicati per far sì che le famiglie che fuggono da per\",\n",
+       "  \"\\n\\nIl presidente ha detto che Justice Breyer ha dedicato la sua vita al servizio di questo paese, ha onorato la sua carriera e ha contribuito a costruire un consenso. Ha ricevuto un ampio sostegno, dall'Ordine Fraterno della Polizia a ex giudici nominati da democratici e repubblicani. Inoltre, ha sottolineato l'importanza di avanzare la libertà e la giustizia attraverso la sicurezza delle frontiere e la risoluzione del sistema di immigrazione. Ha anche menzionato le nuove tecnologie come scanner all'avanguardia per rilevare meglio il traffico di droga, le pattuglie congiunte con Messico e Guatemala per catturare più trafficanti di esseri umani, l'istituzione di giudici di immigrazione dedicati per far sì che le famiglie che fuggono da per\",\n",
+       "  \"\\n\\nIl presidente ha detto che Justice Breyer ha dedicato la sua vita al servizio di questo paese, ha onorato la sua carriera e ha contribuito a costruire un consenso. Ha ricevuto un ampio sostegno, dall'Ordine Fraterno della Polizia a ex giudici nominati da democratici e repubblicani. Inoltre, ha sottolineato l'importanza di avanzare la libertà e la giustizia attraverso la sicurezza delle frontiere e la risoluzione del sistema di immigrazione. Ha anche menzionato le nuove tecnologie come scanner all'avanguardia per rilevare meglio il traffico di droga, le pattuglie congiunte con Messico e Guatemala per catturare più trafficanti di esseri umani, l'istituzione di giudici di immigrazione dedicati per far sì che le famiglie che fuggono da per\"],\n",
+       " 'output_text': \"\\n\\nIl presidente ha detto che Justice Breyer ha dedicato la sua vita al servizio di questo paese, ha onorato la sua carriera e ha contribuito a costruire un consenso. Ha ricevuto un ampio sostegno, dall'Ordine Fraterno della Polizia a ex giudici nominati da democratici e repubblicani. Inoltre, ha sottolineato l'importanza di avanzare la libertà e la giustizia attraverso la sicurezza delle frontiere e la risoluzione del sistema di immigrazione. Ha anche menzionato le nuove tecnologie come scanner all'avanguardia per rilevare meglio il traffico di droga, le pattuglie congiunte con Messico e Guatemala per catturare più trafficanti di esseri umani, l'istituzione di giudici di immigrazione dedicati per far sì che le famiglie che fuggono da per\"}"
+      ]
+     },
+     "execution_count": 10,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "chain = load_qa_with_sources_chain(OpenAI(temperature=0), chain_type=\"refine\", return_intermediate_steps=True, question_prompt=question_prompt, refine_prompt=refine_prompt)\n",
+    "chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "07ff756e",
@@ -374,10 +595,89 @@
     "result[\"intermediate_steps\"]"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "b94bfeb6",
+   "metadata": {},
+   "source": [
+    "**Custom Prompts**\n",
+    "\n",
+    "You can also use your own prompts with this chain. In this example, we will respond in Italian."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "cb46ba3f",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from langchain.prompts.base import RegexParser\n",
+    "\n",
+    "output_parser = RegexParser(\n",
+    "    regex=r\"(.*?)\\nScore: (.*)\",\n",
+    "    output_keys=[\"answer\", \"score\"],\n",
+    ")\n",
+    "\n",
+    "prompt_template = \"\"\"Use the following pieces of context to answer the question at the end. If you don't know the answer, just say that you don't know, don't try to make up an answer.\n",
+    "\n",
+    "In addition to giving an answer, also return a score of how fully it answered the user's question. This should be in the following format:\n",
+    "\n",
+    "Question: [question here]\n",
+    "Helpful Answer In Italian: [answer here]\n",
+    "Score: [score between 0 and 100]\n",
+    "\n",
+    "Begin!\n",
+    "\n",
+    "Context:\n",
+    "---------\n",
+    "{context}\n",
+    "---------\n",
+    "Question: {question}\n",
+    "Helpful Answer In Italian:\"\"\"\n",
+    "PROMPT = PromptTemplate(\n",
+    "    template=prompt_template,\n",
+    "    input_variables=[\"context\", \"question\"],\n",
+    "    output_parser=output_parser,\n",
+    ")\n",
+    "chain = load_qa_with_sources_chain(OpenAI(temperature=0), chain_type=\"map_rerank\", metadata_keys=['source'], return_intermediate_steps=True, prompt=PROMPT)\n",
+    "query = \"What did the president say about Justice Breyer\"\n",
+    "result = chain({\"input_documents\": docs, \"question\": query}, return_only_outputs=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "id": "fee7b055",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'source': 30,\n",
+       " 'intermediate_steps': [{'answer': ' Il presidente ha detto che Justice Breyer ha dedicato la sua vita a servire questo paese e ha onorato la sua carriera.',\n",
+       "   'score': '100'},\n",
+       "  {'answer': ' Il presidente non ha detto nulla sulla Giustizia Breyer.',\n",
+       "   'score': '100'},\n",
+       "  {'answer': ' Non so.', 'score': '0'},\n",
+       "  {'answer': ' Il presidente non ha detto nulla sulla giustizia Breyer.',\n",
+       "   'score': '100'}],\n",
+       " 'output_text': ' Il presidente ha detto che Justice Breyer ha dedicato la sua vita a servire questo paese e ha onorato la sua carriera.'}"
+      ]
+     },
+     "execution_count": 12,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "result"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "e66b8160",
+   "id": "5a51c987",
    "metadata": {},
    "outputs": [],
    "source": []