{
 "cells": [
  {
   "attachments": {
    "51f122de-b2ce-4c21-a5a7-c3be70c28a91.png": {
     "image/png": "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LyI+CiAgICAgICAgIDxleGlmOlBpeGVsWURpbWVuc2lvbj41NDI8L2V4aWY6UGl4ZWxZRGltZW5zaW9uPgogICAgICAgICA8ZXhpZjpQaXhlbFhEaW1lbnNpb24+OTA0PC9leGlmOlBpeGVsWERpbWVuc2lvbj4KICAgICAgICAgPGV4aWY6VXNlckNvbW1lbnQ+U2NyZWVuc2hvdDwvZXhpZjpVc2VyQ29tbWVudD4KICAgICAgPC9yZGY6RGVzY3JpcHRpb24+CiAgIDwvcmRmOlJERj4KPC94OnhtcG1ldGE+ClCweXwAAAAcaURPVAAAAAIAAAAAAAABDwAAACgAAAEPAAABDwAARV8dcCWfAABAAElEQVR4AezdB3wURfvA8UcgdAgdqaElNAEVFBSk96agf1REFJSiooAFRXxtiAooShHEBkhRULEjRTpIB0MTCC0JJEBooZcA/5mJt97mLqSQS+4uv30/8XZnd2dnvjcvnzyZ2ZmbrqlN2BBAAAEEEEAAAQQQQAABBDK9wE0EiJm+DQCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIIAAAggggAACCCCAgBEgQKQhIIAAAggggAACCCCAAAIIGAECRBoCAggggAACCCCAAAIIIICAESBApCEggAACCCCAAAIIIIAAAggYAQJEGgICCCCAAAIIIIAAAggggIARIECkISCAAAIIIIAAAggggAACCBgBAkQaAgIIIICARwXOnDkjW7ZssT2jWrVqEhgYaEvjAAEEEEAAAQQyXoAAMeO/A0qAAAII+LVA+/btXQJEXeHy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Ujl++pycOH1eTkSfl7PnzsvFC+cl5qL5MZ8XL56TwsUjpFSZslK2TBkpXz5C8uUQyZczixTKncV82llyggACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAApaKqg4AAAVzSURBVAgggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuCxAgugxOcQgggAACCCCAAAIIIICAVwUIEL36ZqgXAggggAACCCCAAAIIIOCyAAGiy+AUhwACCCCAAAIIIIAAAgh4VYAA0atvhnohgAACCCCAAAIIIIAAAi4LECC6DE5xCCCAAAIIIIAAAggggIBXBQgQvfpmqBcCCCCAAAIIIIAAAggg4LIAAaLL4BSHAAIIIIAAAggggAACCHhVgADRq2+GeiGAAAIIIIAAAggggAACLgsQILoMTnEIIIAAAggggAACCCCAgFcFCBC9+maoFwIIIIAAAggggAACCCDgsgABosvgFIcAAggggAACCCCAAAIIeFWAANGrb4Z6IYAAAggggAACCCCAAAIuC/w/OsDdHSiHP+MAAAAASUVORK5CYII="
    }
   },
   "cell_type": "markdown",
   "id": "710dc4f0-1c88-4386-9e9d-fec3de6bb774",
   "metadata": {},
   "source": [
    "# How to create branches for parallel node execution\n",
    "\n",
    "Parallel execution of nodes is essential to speed up overall graph operation. LangGraph offers native support for parallel execution of nodes, which can significantly enhance the performance of graph-based workflows. This parallelization is achieved through fan-out and fan-in mechanisms, utilizing both standard edges and [conditional_edges](https://langchain-ai.github.io/langgraph/reference/graphs/#langgraph.graph.MessageGraph.add_conditional_edges). Below are some examples showing how to add create branching dataflows that work for you. \n",
    "\n",
    "![Screenshot 2024-07-09 at 2.55.56 PM.png](attachment:51f122de-b2ce-4c21-a5a7-c3be70c28a91.png)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "bb54e2d0",
   "metadata": {},
   "outputs": [],
   "source": [
    "%%capture --no-stderr\n",
    "%pip install -U langgraph"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6c05fc4-ecd8-483f-a9fd-b1a055f922d9",
   "metadata": {},
   "source": [
    "## Parallel node fan-out and fan-in\n",
    "\n",
    "In this example, we fan out from `Node A` to `B and C` and then fan in to `D`. With our state, [we specify the reducer add operation](https://langchain-ai.github.io/langgraph/concepts/low_level/#reducers). This will combine or accumulate values for the specific key in the State, rather than simply overwriting the existing value. For lists, this means concatenating the new list with the existing list. \n",
    "\n",
    "Note that LangGraph uses `Annotated` type to specify reducer functions for specific keys in the State: it maintains the original type (`list`) for type checking, but allows attaching the reducer function (`add`) to the type without changing the type itself."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "09372b8b-edea-4b9d-9ec3-3d93ce1ba819",
   "metadata": {},
   "outputs": [],
   "source": [
    "import operator\n",
    "from typing import Annotated, Any\n",
    "\n",
    "from typing_extensions import TypedDict\n",
    "\n",
    "from langgraph.graph import StateGraph, START, END\n",
    "\n",
    "\n",
    "class State(TypedDict):\n",
    "    # The operator.add reducer fn makes this append-only\n",
    "    aggregate: Annotated[list, operator.add]\n",
    "\n",
    "\n",
    "class ReturnNodeValue:\n",
    "    def __init__(self, node_secret: str):\n",
    "        self._value = node_secret\n",
    "\n",
    "    def __call__(self, state: State) -> Any:\n",
    "        print(f\"Adding {self._value} to {state['aggregate']}\")\n",
    "        return {\"aggregate\": [self._value]}\n",
    "\n",
    "\n",
    "builder = StateGraph(State)\n",
    "builder.add_node(\"a\", ReturnNodeValue(\"I'm A\"))\n",
    "builder.add_edge(START, \"a\")\n",
    "builder.add_node(\"b\", ReturnNodeValue(\"I'm B\"))\n",
    "builder.add_node(\"c\", ReturnNodeValue(\"I'm C\"))\n",
    "builder.add_node(\"d\", ReturnNodeValue(\"I'm D\"))\n",
    "builder.add_edge(\"a\", \"b\")\n",
    "builder.add_edge(\"a\", \"c\")\n",
    "builder.add_edge(\"b\", \"d\")\n",
    "builder.add_edge(\"c\", \"d\")\n",
    "builder.add_edge(\"d\", END)\n",
    "graph = builder.compile()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "66f52a20",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image, display\n",
    "\n",
    "display(Image(graph.get_graph().draw_mermaid_png()))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "74dd577b-0474-44c4-b4bc-9113090e3121",
   "metadata": {},
   "source": [
    "With the reducer, you can see that the values added in each node are accumulated."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "38846b01",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm B to [\"I'm A\"]\n",
      "Adding I'm C to [\"I'm A\"]\n",
      "Adding I'm D to [\"I'm A\", \"I'm B\", \"I'm C\"]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", \"I'm B\", \"I'm C\", \"I'm D\"]}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": []}, {\"configurable\": {\"thread_id\": \"foo\"}})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c392b3d2",
   "metadata": {},
   "source": [
    "<details class=\"note\"> <summary>Exception handling?</summary>\n",
    " <p>LangGraph executes nodes within <a href=\"https://langchain-ai.github.io/langgraph/concepts/#core-design\">\"supersteps\"</a>, meaning that while parallel branches are executed in parallel, the entire superstep is <b>transactional</b>. If any of these branches raises an exception, <b>none</b> of the updates are applied to the state (the entire superstep errors).<br><br>\n",
    " If you have error-prone (perhaps want to handle flakey API calls), LangGraph provides two ways to address this:<br>\n",
    " <ol>\n",
    "  <li>You can write regular python code within your node to catch and handle exceptions.</li>\n",
    "  <li>You can set a <b><a href=\"https://langchain-ai.github.io/langgraph/reference/graphs/#langgraph.graph.graph.CompiledGraph.retry_policy\">retry_policy</a></b> to direct the graph to retry nodes that raise certain types of exceptions. Only failing branches are retried, so you needn't worry about performing redundant work.</li>\n",
    "</ol></p>\n",
    "Together, these let you perform parallel execution and fully control exception handling.\n",
    "</details>"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "08d8162e-1785-4ae1-993f-6d2ed48c22ae",
   "metadata": {},
   "source": [
    "## Parallel node fan-out and fan-in with extra steps\n",
    "\n",
    "The above example showed how to fan-out and fan-in when each path was only one step. But what if one path had more than one step?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "259a7704-5aa0-4e4c-aeef-cca04e8be0ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "import operator\n",
    "from typing import Annotated\n",
    "\n",
    "from typing_extensions import TypedDict\n",
    "\n",
    "from langgraph.graph import StateGraph\n",
    "\n",
    "\n",
    "class State(TypedDict):\n",
    "    # The operator.add reducer fn makes this append-only\n",
    "    aggregate: Annotated[list, operator.add]\n",
    "\n",
    "\n",
    "builder = StateGraph(State)\n",
    "builder.add_node(\"a\", ReturnNodeValue(\"I'm A\"))\n",
    "builder.add_edge(START, \"a\")\n",
    "builder.add_node(\"b\", ReturnNodeValue(\"I'm B\"))\n",
    "builder.add_node(\"b2\", ReturnNodeValue(\"I'm B2\"))\n",
    "builder.add_node(\"c\", ReturnNodeValue(\"I'm C\"))\n",
    "builder.add_node(\"d\", ReturnNodeValue(\"I'm D\"))\n",
    "builder.add_edge(\"a\", \"b\")\n",
    "builder.add_edge(\"a\", \"c\")\n",
    "builder.add_edge(\"b\", \"b2\")\n",
    "builder.add_edge([\"b2\", \"c\"], \"d\")\n",
    "builder.add_edge(\"d\", END)\n",
    "graph = builder.compile()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "83320227-8ab3-44c0-b6cf-064a7a425b9f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image, display\n",
    "\n",
    "display(Image(graph.get_graph().draw_mermaid_png()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "3f971fa3-29e4-466f-a85e-2863bfecf7fe",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm B to [\"I'm A\"]\n",
      "Adding I'm C to [\"I'm A\"]\n",
      "Adding I'm B2 to [\"I'm A\", \"I'm B\", \"I'm C\"]\n",
      "Adding I'm D to [\"I'm A\", \"I'm B\", \"I'm C\", \"I'm B2\"]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", \"I'm B\", \"I'm C\", \"I'm B2\", \"I'm D\"]}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": []})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d45f4477",
   "metadata": {},
   "source": [
    "## Conditional Branching\n",
    "\n",
    "If your fan-out is not deterministic, you can use [add_conditional_edges](https://langchain-ai.github.io/langgraph/reference/graphs/#langgraph.graph.StateGraph.add_conditional_edges) directly.\n",
    "\n",
    "If you have a known \"sink\" node that the conditional branches will route to afterwards, you can provide `then=<final-node-name>` when creating the conditional edges."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "95f5e026",
   "metadata": {},
   "outputs": [],
   "source": [
    "import operator\n",
    "from typing import Annotated, Sequence\n",
    "\n",
    "from typing_extensions import TypedDict\n",
    "\n",
    "from langgraph.graph import END, START, StateGraph\n",
    "\n",
    "\n",
    "class State(TypedDict):\n",
    "    # The operator.add reducer fn makes this append-only\n",
    "    aggregate: Annotated[list, operator.add]\n",
    "    which: str\n",
    "\n",
    "\n",
    "builder = StateGraph(State)\n",
    "builder.add_node(\"a\", ReturnNodeValue(\"I'm A\"))\n",
    "builder.add_edge(START, \"a\")\n",
    "builder.add_node(\"b\", ReturnNodeValue(\"I'm B\"))\n",
    "builder.add_node(\"c\", ReturnNodeValue(\"I'm C\"))\n",
    "builder.add_node(\"d\", ReturnNodeValue(\"I'm D\"))\n",
    "builder.add_node(\"e\", ReturnNodeValue(\"I'm E\"))\n",
    "\n",
    "\n",
    "def route_bc_or_cd(state: State) -> Sequence[str]:\n",
    "    if state[\"which\"] == \"cd\":\n",
    "        return [\"c\", \"d\"]\n",
    "    return [\"b\", \"c\"]\n",
    "\n",
    "\n",
    "intermediates = [\"b\", \"c\", \"d\"]\n",
    "builder.add_conditional_edges(\n",
    "    \"a\",\n",
    "    route_bc_or_cd,\n",
    "    intermediates,\n",
    ")\n",
    "for node in intermediates:\n",
    "    builder.add_edge(node, \"e\")\n",
    "\n",
    "\n",
    "builder.add_edge(\"e\", END)\n",
    "graph = builder.compile()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "1d0e6c56",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image, display\n",
    "\n",
    "display(Image(graph.get_graph().draw_mermaid_png()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "7134f652",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm B to [\"I'm A\"]\n",
      "Adding I'm C to [\"I'm A\"]\n",
      "Adding I'm E to [\"I'm A\", \"I'm B\", \"I'm C\"]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", \"I'm B\", \"I'm C\", \"I'm E\"], 'which': 'bc'}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": [], \"which\": \"bc\"})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "b130e694",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm D to [\"I'm A\"]\n",
      "Adding I'm C to [\"I'm A\"]\n",
      "Adding I'm E to [\"I'm A\", \"I'm C\", \"I'm D\"]\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", \"I'm C\", \"I'm D\", \"I'm E\"], 'which': 'cd'}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": [], \"which\": \"cd\"})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "952cd6f3",
   "metadata": {},
   "source": [
    "## Stable Sorting\n",
    "\n",
    "When fanned out, nodes are run in parallel as a single \"superstep\". The updates from each superstep are all applied to the state in sequence once the superstep has completed. \n",
    "\n",
    "If you need consistent, predetermined ordering of updates from a parallel superstep, you should write the outputs (along with an identifying key) to a separate field in your state, then combine them in the \"sink\" node by adding regular `edge`'s from each of the fanout nodes to the rendezvous point.\n",
    "\n",
    "For instance, suppose I want to order the outputs of the parallel step by \"reliability\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "836bc12d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import operator\n",
    "from typing import Annotated, Sequence\n",
    "\n",
    "from typing_extensions import TypedDict\n",
    "\n",
    "from langgraph.graph import StateGraph\n",
    "\n",
    "\n",
    "def reduce_fanouts(left, right):\n",
    "    if left is None:\n",
    "        left = []\n",
    "    if not right:\n",
    "        # Overwrite\n",
    "        return []\n",
    "    return left + right\n",
    "\n",
    "\n",
    "class State(TypedDict):\n",
    "    # The operator.add reducer fn makes this append-only\n",
    "    aggregate: Annotated[list, operator.add]\n",
    "    fanout_values: Annotated[list, reduce_fanouts]\n",
    "    which: str\n",
    "\n",
    "\n",
    "builder = StateGraph(State)\n",
    "builder.add_node(\"a\", ReturnNodeValue(\"I'm A\"))\n",
    "builder.add_edge(START, \"a\")\n",
    "\n",
    "\n",
    "class ParallelReturnNodeValue:\n",
    "    def __init__(\n",
    "        self,\n",
    "        node_secret: str,\n",
    "        reliability: float,\n",
    "    ):\n",
    "        self._value = node_secret\n",
    "        self._reliability = reliability\n",
    "\n",
    "    def __call__(self, state: State) -> Any:\n",
    "        print(f\"Adding {self._value} to {state['aggregate']} in parallel.\")\n",
    "        return {\n",
    "            \"fanout_values\": [\n",
    "                {\n",
    "                    \"value\": [self._value],\n",
    "                    \"reliability\": self._reliability,\n",
    "                }\n",
    "            ]\n",
    "        }\n",
    "\n",
    "\n",
    "builder.add_node(\"b\", ParallelReturnNodeValue(\"I'm B\", reliability=0.9))\n",
    "\n",
    "builder.add_node(\"c\", ParallelReturnNodeValue(\"I'm C\", reliability=0.1))\n",
    "builder.add_node(\"d\", ParallelReturnNodeValue(\"I'm D\", reliability=0.3))\n",
    "\n",
    "\n",
    "def aggregate_fanout_values(state: State) -> Any:\n",
    "    # Sort by reliability\n",
    "    ranked_values = sorted(\n",
    "        state[\"fanout_values\"], key=lambda x: x[\"reliability\"], reverse=True\n",
    "    )\n",
    "    return {\n",
    "        \"aggregate\": [x[\"value\"] for x in ranked_values] + [\"I'm E\"],\n",
    "        \"fanout_values\": [],\n",
    "    }\n",
    "\n",
    "\n",
    "builder.add_node(\"e\", aggregate_fanout_values)\n",
    "\n",
    "\n",
    "def route_bc_or_cd(state: State) -> Sequence[str]:\n",
    "    if state[\"which\"] == \"cd\":\n",
    "        return [\"c\", \"d\"]\n",
    "    return [\"b\", \"c\"]\n",
    "\n",
    "\n",
    "intermediates = [\"b\", \"c\", \"d\"]\n",
    "builder.add_conditional_edges(\"a\", route_bc_or_cd, intermediates)\n",
    "\n",
    "for node in intermediates:\n",
    "    builder.add_edge(node, \"e\")\n",
    "\n",
    "builder.add_edge(\"e\", END)\n",
    "graph = builder.compile()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "932c497e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/jpeg": "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",
      "text/plain": [
       "<IPython.core.display.Image object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import Image, display\n",
    "\n",
    "display(Image(graph.get_graph().draw_mermaid_png()))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "933b3afd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm B to [\"I'm A\"] in parallel.\n",
      "Adding I'm C to [\"I'm A\"] in parallel.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", [\"I'm B\"], [\"I'm C\"], \"I'm E\"],\n",
       " 'fanout_values': [],\n",
       " 'which': 'bc'}"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": [], \"which\": \"bc\", \"fanout_values\": []})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "e30531bf",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Adding I'm A to []\n",
      "Adding I'm C to [\"I'm A\"] in parallel.\n",
      "Adding I'm D to [\"I'm A\"] in parallel.\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "{'aggregate': [\"I'm A\", [\"I'm D\"], [\"I'm C\"], \"I'm E\"],\n",
       " 'fanout_values': [],\n",
       " 'which': 'cd'}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "graph.invoke({\"aggregate\": [], \"which\": \"cd\"})"
   ]
  }
 ],
 "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}