langchain/docs/docs/expression_language/get_started.ipynb

{
 "cells": [
  {
   "cell_type": "raw",
   "id": "366a0e68-fd67-4fe5-a292-5c33733339ea",
   "metadata": {},
   "source": [
    "---\n",
    "sidebar_position: 0\n",
    "title: Get started\n",
    "keywords: [chain.invoke]\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "befa7fd1",
   "metadata": {},
   "source": [
    "LCEL makes it easy to build complex chains from basic components, and supports out of the box functionality such as streaming, parallelism, and logging."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a9acd2e",
   "metadata": {},
   "source": [
    "## Basic example: prompt + model + output parser\n",
    "\n",
    "The most basic and common use case is chaining a prompt template and a model together. To see how this works, let's create a chain that takes a topic and generates a joke:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "278b0027",
   "metadata": {},
   "outputs": [],
   "source": [
    "%pip install --upgrade --quiet  langchain-core langchain-community langchain-openai"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3d54f72",
   "metadata": {},
   "source": [
    "```{=mdx}\n",
    "import ChatModelTabs from \"@theme/ChatModelTabs\";\n",
    "\n",
    "<ChatModelTabs openaiParams={`model=\"gpt-4\"`} />\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f9eed8e8",
   "metadata": {},
   "outputs": [],
   "source": [
    "# | output: false\n",
    "# | echo: false\n",
    "\n",
    "from langchain_openai import ChatOpenAI\n",
    "\n",
    "model = ChatOpenAI(model=\"gpt-4\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "466b65b3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"Why don't ice creams ever get invited to parties?\\n\\nBecause they always drip when things heat up!\""
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from langchain_core.output_parsers import StrOutputParser\n",
    "from langchain_core.prompts import ChatPromptTemplate\n",
    "\n",
    "prompt = ChatPromptTemplate.from_template(\"tell me a short joke about {topic}\")\n",
    "output_parser = StrOutputParser()\n",
    "\n",
    "chain = prompt | model | output_parser\n",
    "\n",
    "chain.invoke({\"topic\": \"ice cream\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81c502c5-85ee-4f36-aaf4-d6e350b7792f",
   "metadata": {},
   "source": [
    "Notice this line of the code, where we piece together these different components into a single chain using LCEL:\n",
    "\n",
    "```\n",
    "chain = prompt | model | output_parser\n",
    "```\n",
    "\n",
    "The `|` symbol is similar to a [unix pipe operator](https://en.wikipedia.org/wiki/Pipeline_(Unix)), which chains together the different components, feeding the output from one component as input into the next component. \n",
    "\n",
    "In this chain the user input is passed to the prompt template, then the prompt template output is passed to the model, then the model output is passed to the output parser. Let's take a look at each component individually to really understand what's going on."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aa1b77fa",
   "metadata": {},
   "source": [
    "### 1. Prompt\n",
    "\n",
    "`prompt` is a `BasePromptTemplate`, which means it takes in a dictionary of template variables and produces a `PromptValue`. A `PromptValue` is a wrapper around a completed prompt that can be passed to either an `LLM` (which takes a string as input) or `ChatModel` (which takes a sequence of messages as input). It can work with either language model type because it defines logic both for producing `BaseMessage`s and for producing a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "b8656990",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "ChatPromptValue(messages=[HumanMessage(content='tell me a short joke about ice cream')])"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prompt_value = prompt.invoke({\"topic\": \"ice cream\"})\n",
    "prompt_value"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e6034488",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[HumanMessage(content='tell me a short joke about ice cream')]"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prompt_value.to_messages()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "60565463",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'Human: tell me a short joke about ice cream'"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "prompt_value.to_string()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "577f0f76",
   "metadata": {},
   "source": [
    "### 2. Model\n",
    "\n",
    "The `PromptValue` is then passed to `model`. In this case our `model` is a `ChatModel`, meaning it will output a `BaseMessage`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "33cf5f72",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "AIMessage(content=\"Why don't ice creams ever get invited to parties?\\n\\nBecause they always bring a melt down!\")"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "message = model.invoke(prompt_value)\n",
    "message"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "327e7db8",
   "metadata": {},
   "source": [
    "If our `model` was an `LLM`, it would output a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "8feb05da",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'\\n\\nRobot: Why did the ice cream truck break down? Because it had a meltdown!'"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from langchain_openai import OpenAI\n",
    "\n",
    "llm = OpenAI(model=\"gpt-3.5-turbo-instruct\")\n",
    "llm.invoke(prompt_value)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91847478",
   "metadata": {},
   "source": [
    "### 3. Output parser\n",
    "\n",
    "And lastly we pass our `model` output to the `output_parser`, which is a `BaseOutputParser` meaning it takes either a string or a \n",
    "`BaseMessage` as input. The specific `StrOutputParser` simply converts any input into a string."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "533e59a8",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "\"Why did the ice cream go to therapy? \\n\\nBecause it had too many toppings and couldn't find its cone-fidence!\""
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "output_parser.invoke(message)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9851e842",
   "metadata": {},
   "source": [
    "### 4. Entire Pipeline\n",
    "\n",
    "To follow the steps along:\n",
    "\n",
    "1. We pass in user input on the desired topic as `{\"topic\": \"ice cream\"}`\n",
    "2. The `prompt` component takes the user input, which is then used to construct a PromptValue after using the `topic` to construct the prompt. \n",
    "3. The `model` component takes the generated prompt, and passes into the OpenAI LLM model for evaluation. The generated output from the model is a `ChatMessage` object. \n",
    "4. Finally, the `output_parser` component takes in a `ChatMessage`, and transforms this into a Python string, which is returned from the invoke method. \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c4873109",
   "metadata": {},
   "source": [
    "```mermaid\n",
    "graph LR\n",
    "    A(Input: topic=ice cream) --> |Dict| B(PromptTemplate)\n",
    "    B -->|PromptValue| C(ChatModel)    \n",
    "    C -->|ChatMessage| D(StrOutputParser)\n",
    "    D --> |String| F(Result)\n",
    "```\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fe63534d",
   "metadata": {},
   "source": [
    ":::info\n",
    "\n",
    "Note that if you’re curious about the output of any components, you can always test out a smaller version of the chain such as `prompt` or `prompt | model` to see the intermediate results:\n",
    "\n",
    ":::"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11089b6f-23f8-474f-97ec-8cae8d0ca6d4",
   "metadata": {},
   "outputs": [],
   "source": [
    "input = {\"topic\": \"ice cream\"}\n",
    "\n",
    "prompt.invoke(input)\n",
    "# > ChatPromptValue(messages=[HumanMessage(content='tell me a short joke about ice cream')])\n",
    "\n",
    "(prompt | model).invoke(input)\n",
    "# > AIMessage(content=\"Why did the ice cream go to therapy?\\nBecause it had too many toppings and couldn't cone-trol itself!\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc7d3b9d-e400-4c9b-9188-f29dac73e6bb",
   "metadata": {},
   "source": [
    "## RAG Search Example\n",
    "\n",
    "For our next example, we want to run a retrieval-augmented generation chain to add some context when responding to questions."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b8fe8eb4",
   "metadata": {},
   "source": [
    "```{=mdx}\n",
    "<ChatModelTabs />\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "662426e8-4316-41dc-8312-9b58edc7e0c9",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Requires:\n",
    "# pip install langchain docarray tiktoken\n",
    "\n",
    "from langchain_community.vectorstores import DocArrayInMemorySearch\n",
    "from langchain_core.output_parsers import StrOutputParser\n",
    "from langchain_core.prompts import ChatPromptTemplate\n",
    "from langchain_core.runnables import RunnableParallel, RunnablePassthrough\n",
    "from langchain_openai import OpenAIEmbeddings\n",
    "\n",
    "vectorstore = DocArrayInMemorySearch.from_texts(\n",
    "    [\"harrison worked at kensho\", \"bears like to eat honey\"],\n",
    "    embedding=OpenAIEmbeddings(),\n",
    ")\n",
    "retriever = vectorstore.as_retriever()\n",
    "\n",
    "template = \"\"\"Answer the question based only on the following context:\n",
    "{context}\n",
    "\n",
    "Question: {question}\n",
    "\"\"\"\n",
    "prompt = ChatPromptTemplate.from_template(template)\n",
    "output_parser = StrOutputParser()\n",
    "\n",
    "setup_and_retrieval = RunnableParallel(\n",
    "    {\"context\": retriever, \"question\": RunnablePassthrough()}\n",
    ")\n",
    "chain = setup_and_retrieval | prompt | model | output_parser\n",
    "\n",
    "chain.invoke(\"where did harrison work?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f0999140-6001-423b-970b-adf1dfdb4dec",
   "metadata": {},
   "source": [
    "In this case, the composed chain is: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5b88e9bb-f04a-4a56-87ec-19a0e6350763",
   "metadata": {},
   "outputs": [],
   "source": [
    "chain = setup_and_retrieval | prompt | model | output_parser"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e929e15-40a5-4569-8969-384f636cab87",
   "metadata": {},
   "source": [
    "To explain this, we first can see that the prompt template above takes in `context` and `question` as values to be substituted in the prompt. Before building the prompt template, we want to retrieve relevant documents to the search and include them as part of the context. \n",
    "\n",
    "As a preliminary step, we’ve setup the retriever using an in memory store, which can retrieve documents based on a query. This is a runnable component as well that can be chained together with other components, but you can also try to run it separately:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a7319ef6-613b-4638-ad7d-4a2183702c1d",
   "metadata": {},
   "outputs": [],
   "source": [
    "retriever.invoke(\"where did harrison work?\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6833844-f1c4-444c-a3d2-31b3c6b31d46",
   "metadata": {},
   "source": [
    "We then use the `RunnableParallel` to prepare the expected inputs into the prompt by using the entries for the retrieved documents as well as the original user question, using the retriever for document search, and RunnablePassthrough to pass the user’s question:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dcbca26b-d6b9-4c24-806c-1ec8fdaab4ed",
   "metadata": {},
   "outputs": [],
   "source": [
    "setup_and_retrieval = RunnableParallel(\n",
    "    {\"context\": retriever, \"question\": RunnablePassthrough()}\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68c721c1-048b-4a64-9d78-df54fe465992",
   "metadata": {},
   "source": [
    "To review, the complete chain is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1d5115a7-7b8e-458b-b936-26cc87ee81c4",
   "metadata": {},
   "outputs": [],
   "source": [
    "setup_and_retrieval = RunnableParallel(\n",
    "    {\"context\": retriever, \"question\": RunnablePassthrough()}\n",
    ")\n",
    "chain = setup_and_retrieval | prompt | model | output_parser"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c6f5f74-b387-48a0-bedd-1fae202cd10a",
   "metadata": {},
   "source": [
    "With the flow being:\n",
    "\n",
    "1. The first steps create a `RunnableParallel` object with two entries.  The first entry, `context` will include the document results fetched by the retriever. The second entry, `question` will contain the user’s original question. To pass on the question, we use `RunnablePassthrough` to copy this entry. \n",
    "2. Feed the dictionary from the step above to the `prompt` component. It then takes the user input which is `question` as well as the retrieved document which is `context` to construct a prompt and output a PromptValue. \n",
    "3. The `model` component takes the generated prompt, and passes into the OpenAI LLM model for evaluation. The generated output from the model is a `ChatMessage` object. \n",
    "4. Finally, the `output_parser` component takes in a `ChatMessage`, and transforms this into a Python string, which is returned from the invoke method.\n",
    "\n",
    "```mermaid\n",
    "graph LR\n",
    "    A(Question) --> B(RunnableParallel)\n",
    "    B -->|Question| C(Retriever)\n",
    "    B -->|Question| D(RunnablePassThrough)\n",
    "    C -->|context=retrieved docs| E(PromptTemplate)\n",
    "    D -->|question=Question| E\n",
    "    E -->|PromptValue| F(ChatModel)    \n",
    "    F -->|ChatMessage| G(StrOutputParser)\n",
    "    G --> |String| H(Result)\n",
    "```\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c2438df-164e-4bbe-b5f4-461695e45b0f",
   "metadata": {},
   "source": [
    "## Next steps\n",
    "\n",
    "We recommend reading our [Advantages of LCEL](/docs/expression_language/why) section next to see a side-by-side comparison of the code needed to produce common functionality with and without LCEL."
   ]
  }
 ],
 "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.11.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}