all_rag_techniques/relevant_segment_extraction.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Relevant Segment Extraction (RSE)\n",
    "\n",
    "## Overview\n",
    "\n",
    "Relevant segment extraction (RSE) is a method of reconstructing multi-chunk segments of contiguous text out of retrieved chunks. This step occurs after vector search (and optionally reranking), but before presenting the retrieved context to the LLM. This method ensures that nearby chunks are presented to the LLM in the order they appear in the original document. It also adds in chunks that are not marked as relevant, but are sandwiched between highly relevant chunks, further improving the context provided to the LLM. This method provides a substantial improvement in RAG performance, as shown in the eval results presented at the end of this notebook.\n",
    "\n",
    "## Motivation\n",
    "\n",
    "When chunking documents for RAG, choosing the right chunk size is an exercise in managing tradeoffs. Large chunks provide better context to the LLM than small chunks, but they also make it harder to precisely retrieve specific pieces of information. Some queries (like simple factoid questions) are best handled by small chunks, while other queries (like higher-level questions) require very large chunks. There are some queries that can be answered with a single sentence from the document, while there are other queries that require entire sections or chapters to properly answer. Most real-world RAG use cases face a combination of these types of queries. \n",
    "\n",
    "What we really need is a more dynamic system that can retrieve short chunks when that's all that's needed, but can also retrieve very large chunks when required. How do we do that?\n",
    "\n",
    "Our solution is motivated by one simple insight: **relevant chunks tend to be clustered within their original documents**.\n",
    "\n",
    "## Key Components\n",
    "\n",
    "#### Chunk text key-value store\n",
    "RSE requires being able to retrieve chunk text from a database quickly, using a doc_id and chunk_index as keys. This is because not all chunks that need to be included in a given segment will have been returned in the initial search results. Therefore some sort of key-value store may need to be used in addition to the vector database.\n",
    "\n",
    "## Method Details\n",
    "\n",
    "#### Document chunking\n",
    "Standard document chunking methods can be used. The only special requirement here is that documents are chunked with no overlap. This allows us to reconstruct sections of the document (i.e. segments) by concatenating chunks.\n",
    "\n",
    "#### RSE optimization\n",
    "After the standard chunk retrieval process is completed, which ideally includes a reranking step, the RSE process can begin. The first step is to combine the absolute relevance value (i.e the similarity score) and the relevance rank. This provides a more robust starting point than just using the similarity score on its own or just using the rank on its own. Then we subtract a constant threshold value (let's say 0.2) from each chunk's value, such that irrelevant chunks have a negative value (as low as -0.2), and relevant chunks have a positive value (as high as 0.8). By calculating chunk values this way we can define segment value as just the sum of the chunk values. \n",
    "\n",
    "For example suppose chunks 0-4 in a document have the following chunk values: [-0.2, -0.2, 0.4, 0.8, -0.1]. The segment that includes only chunks 2-3 would have value 0.4+0.8=1.2.\n",
    "\n",
    "Finding the best segments then becomes a constrained version of the maximum sum subarray problem. We use a brute force search with a few heuristics to make it efficient. This generally takes ~5-10ms.\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "\n",
    "![Relevant segment extraction](../images/relevant-segment-extraction.svg)\n"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Setup\n",
    "First, some setup. You'll need a Cohere API key to run some of these cells, as we use their excellent reranker to calculate relevance scores."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import numpy as np\n",
    "from typing import List\n",
    "from scipy.stats import beta\n",
    "import matplotlib.pyplot as plt\n",
    "import cohere\n",
    "from dotenv import load_dotenv\n",
    "\n",
    "# Load environment variables from a .env file\n",
    "load_dotenv()\n",
    "os.environ[\"CO_API_KEY\"] = os.getenv('CO_API_KEY') # Cohere API key"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We define a few helper functions. We'll use the Cohere Rerank API to calculate relevance values for our chunks. Normally, we'd start with a vector and/or keyword search to narrow down the list of candidates, but since we're just dealing with a single document here we can just send all chunks directly to the reranker, keeping things a bit simpler."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "from langchain_text_splitters import RecursiveCharacterTextSplitter\n",
    "\n",
    "def split_into_chunks(text: str, chunk_size: int):\n",
    "    \"\"\"\n",
    "    Split a given text into chunks of specified size using RecursiveCharacterTextSplitter.\n",
    "\n",
    "    Args:\n",
    "        text (str): The input text to be split into chunks.\n",
    "        chunk_size (int, optional): The maximum size of each chunk. Defaults to 800.\n",
    "\n",
    "    Returns:\n",
    "        list[str]: A list of text chunks.\n",
    "\n",
    "    Example:\n",
    "        >>> text = \"This is a sample text to be split into chunks.\"\n",
    "        >>> chunks = split_into_chunks(text, chunk_size=10)\n",
    "        >>> print(chunks)\n",
    "        ['This is a', 'sample', 'text to', 'be split', 'into', 'chunks.']\n",
    "    \"\"\"\n",
    "    text_splitter = RecursiveCharacterTextSplitter(chunk_size=chunk_size, chunk_overlap=0, length_function=len)\n",
    "    texts = text_splitter.create_documents([text])\n",
    "    chunks = [text.page_content for text in texts]\n",
    "    return chunks\n",
    "\n",
    "def transform(x: float):\n",
    "    \"\"\"\n",
    "    Transformation function to map the absolute relevance value to a value that is more uniformly distributed between 0 and 1. The relevance values given by the Cohere reranker tend to be very close to 0 or 1. This beta function used here helps to spread out the values more uniformly.\n",
    "\n",
    "    Args:\n",
    "        x (float): The absolute relevance value returned by the Cohere reranker\n",
    "\n",
    "    Returns:\n",
    "        float: The transformed relevance value\n",
    "    \"\"\"\n",
    "    a, b = 0.4, 0.4  # These can be adjusted to change the distribution shape\n",
    "    return beta.cdf(x, a, b)\n",
    "\n",
    "def rerank_chunks(query: str, chunks: List[str]):\n",
    "    \"\"\"\n",
    "    Use Cohere Rerank API to rerank the search results\n",
    "\n",
    "    Args:\n",
    "        query (str): The search query\n",
    "        chunks (list): List of chunks to be reranked\n",
    "\n",
    "    Returns:\n",
    "        similarity_scores (list): List of similarity scores for each chunk\n",
    "        chunk_values (list): List of relevance values (fusion of rank and similarity) for each chunk\n",
    "    \"\"\"\n",
    "    model = \"rerank-english-v3.0\"\n",
    "    client = cohere.Client(api_key=os.environ[\"CO_API_KEY\"])\n",
    "    decay_rate = 30\n",
    "\n",
    "    reranked_results = client.rerank(model=model, query=query, documents=chunks)\n",
    "    results = reranked_results.results\n",
    "    reranked_indices = [result.index for result in results]\n",
    "    reranked_similarity_scores = [result.relevance_score for result in results] # in order of reranked_indices\n",
    "    \n",
    "    # convert back to order of original documents and calculate the chunk values\n",
    "    similarity_scores = [0] * len(chunks)\n",
    "    chunk_values = [0] * len(chunks)\n",
    "    for i, index in enumerate(reranked_indices):\n",
    "        absolute_relevance_value = transform(reranked_similarity_scores[i])\n",
    "        similarity_scores[index] = absolute_relevance_value\n",
    "        chunk_values[index] = np.exp(-i/decay_rate)*absolute_relevance_value # decay the relevance value based on the rank\n",
    "\n",
    "    return similarity_scores, chunk_values\n",
    "\n",
    "def plot_relevance_scores(chunk_values: List[float], start_index: int = None, end_index: int = None) -> None:\n",
    "    \"\"\"\n",
    "    Visualize the relevance scores of each chunk in the document to the search query\n",
    "\n",
    "    Args:\n",
    "        chunk_values (list): List of relevance values for each chunk\n",
    "        start_index (int): Start index of the chunks to be plotted\n",
    "        end_index (int): End index of the chunks to be plotted\n",
    "\n",
    "    Returns:\n",
    "        None\n",
    "\n",
    "    Plots:\n",
    "        Scatter plot of the relevance scores of each chunk in the document to the search query\n",
    "    \"\"\"\n",
    "    plt.figure(figsize=(12, 5))\n",
    "    plt.title(f\"Similarity of each chunk in the document to the search query\")\n",
    "    plt.ylim(0, 1)\n",
    "    plt.xlabel(\"Chunk index\")\n",
    "    plt.ylabel(\"Query-chunk similarity\")\n",
    "    if start_index is None:\n",
    "        start_index = 0\n",
    "    if end_index is None:\n",
    "        end_index = len(chunk_values)\n",
    "    plt.scatter(range(start_index, end_index), chunk_values[start_index:end_index])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Split the document into 500 chunks\n"
     ]
    }
   ],
   "source": [
    "# File path for the input document\n",
    "FILE_PATH = \"../data/nike_2023_annual_report.txt\"\n",
    "\n",
    "with open(FILE_PATH, 'r') as file:\n",
    "    text = file.read()\n",
    "\n",
    "chunks = split_into_chunks(text, chunk_size=800)\n",
    "\n",
    "print (f\"Split the document into {len(chunks)} chunks\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Visualize chunk relevance distribution across single document"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Example query that requires a longer result than a single chunk\n",
    "query = \"Nike consolidated financial statements\"\n",
    "\n",
    "similarity_scores, chunk_values = rerank_chunks(query, chunks)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAA+kAAAHUCAYAAABGRmklAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjUuMiwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy8qNh9FAAAACXBIWXMAAA9hAAAPYQGoP6dpAAB1J0lEQVR4nO3deXhU1f3H8c9kJyEZCEsSFiEgCpGtgGhAKossLnGprYoiUNQWXFlsK1oNQVsU9w20VbCKIj+roliMREAUhQZZVAx1wSiICZFEkgiEJTm/P9KZZjKTZCaZycxk3q/n4XnInTN3vjO5uXO/93zPORZjjBEAAAAAAPC7MH8HAAAAAAAAqpGkAwAAAAAQIEjSAQAAAAAIECTpAAAAAAAECJJ0AAAAAAACBEk6AAAAAAABgiQdAAAAAIAAQZIOAAAAAECAIEkHAAAAACBAkKQDaLR///vfuuSSS3TSSScpOjpaSUlJSk9P15w5cxzajRw5UiNHjvTqa7vap8Vi0bx587z6Ot9++60sFouee+45+7aPPvpI8+bN08GDB736Wp54/PHHdfLJJysqKkoWi8WvsbjSvXt3XXDBBT59DYvFohtvvNGnr1GXefPmyWKx6MCBAx4/97nnnpPFYtG3337rtXj++te/auXKlXW+1scff+y11/KEL95rS3H48GHNmzdP7733nlvtf/jhB82bN087duzwahz17Xfq1Klq3bq1V1+vpRg5cqT69u3r7zAAtFAk6QAa5V//+peGDRumsrIyLVy4UGvWrNGjjz6q4cOHa8WKFQ5tFy1apEWLFnn19X2xT1dSUlK0adMmnX/++fZtH330kbKysvyWGO/YsUM333yzRo0apXXr1mnTpk2Kj4/3Syzw3Pnnn69NmzYpJSXFa/usK0lH4Dp8+LCysrI8StKzsrJ8kqT7Yr8AgMaL8HcAAILTwoULlZqaqnfeeUcREf87lVxxxRVauHChQ9u0tDSvv74v9llTZWWlTpw4oejoaJ155pk+fS1Pff7555Kk6667TkOHDvVzNPBUhw4d1KFDB3+HAaCWI0eOKCYmRhaLxd+hNLvDhw8rNjbW32EA+C960gE0SnFxsdq3b++QoNuEhTmeWmqXpttKyO+//37dd9996t69u1q1aqWRI0fqyy+/1PHjx3XbbbepU6dOslqtuuSSS1RUVFTvPl358ccfdf311ystLU2tW7dWx44dNXr0aH3wwQcO7WzxLFy4UPfcc49SU1MVHR2t9evXO5W7z5s3T3/4wx8kSampqbJYLLJYLHrvvfd0zTXXKDExUYcPH3aKZfTo0TrttNPqjVeSlixZogEDBigmJkaJiYm65JJLtGvXLof3PWnSJEnSGWecIYvFoqlTp9a7z6+++kpXXnmlOnbsqOjoaPXp00dPPvmkQ5uKigrNmTNHAwcOlNVqVWJiotLT0/XGG2847a+qqkqPP/64Bg4cqFatWqlNmzY688wz9eabbzq1zc7O1qBBg9SqVSv17t1bS5YsafAzkKSjR49q/vz56tOnj2JiYtSuXTuNGjVKH330kVPbF154QX369FFsbKwGDBigt956y+HxqVOnqnv37k7Ps5Ws12QroW9on6785z//UY8ePXTGGWc4Ha81uSoBt5XObtmyRSNGjFBsbKx69Oihe++9V1VVVfW+rsVi0aFDh/SPf/zDfjzW/tsoLy/XjBkz1L59e7Vr106/+tWv9MMPPzjta8WKFUpPT1dcXJxat26t8ePHa/v27Q2+d0navHmzhg8frpiYGHXq1Elz587V8ePHndpVVVVp4cKF6t27t6Kjo9WxY0dNnjxZ33//vVPb7OxsjRkzRlarVbGxserTp48WLFjg8Lm5Og/U/p1745zj7udjKxH/+uuvdd5556l169bq2rWr5syZo6NHj9rjsd2oycrKsv/e6vpbfu+993T66adLkn7729/a29cc3vPmm28qPT1dsbGxio+P19ixY7Vp0yaX+/Nkv5LqfS82x44d0z333GP/vXbo0EG//e1v9eOPP9YbgyR98803uuKKK9SpUyf70KkxY8Y49e678/l//PHHuuKKK+y/4+7du2vixIn67rvvHNrZ/g7XrFmjadOmqUOHDoqNjbW/r5deeknp6elq3bq1WrdurYEDB+rZZ591ir0xf7OSVFZWpuuuu07t2rVT69atNWHCBH355ZdOn78n5y9jjBYtWmQ/N7dt21a//vWv9c033zi0s51v3n//fQ0bNkyxsbGaNm2aV77DAHiJAYBGuPbaa40kc9NNN5nNmzebY8eO1dn27LPPNmeffbb95/z8fCPJdOvWzWRkZJi33nrLLFu2zCQlJZlTTjnFXH311WbatGnm7bffNk899ZRp3bq1ycjIqHefxhgjyWRmZtp//s9//mNmzJhhXn75ZfPee++Zt956y1xzzTUmLCzMrF+/3imezp07m1GjRpl//vOfZs2aNSY/P9/+2NKlS40xxuzdu9fcdNNNRpJ57bXXzKZNm8ymTZtMaWmp+eSTT4wk8/e//90hrs8//9xIMk8++WS9n+lf//pXI8lMnDjR/Otf/zLPP/+86dGjh7FarebLL7+07+vPf/6zPaZNmzaZr7/+us59fv7558ZqtZp+/fqZ559/3qxZs8bMmTPHhIWFmXnz5tnbHTx40EydOtW88MILZt26dSY7O9vceuutJiwszPzjH/9w2OfVV19tLBaLufbaa80bb7xh3n77bfOXv/zFPProo/Y23bp1M126dDFpaWnm+eefN++88475zW9+YySZDRs21Ps5HD9+3IwaNcpERESYW2+91axevdq8+eab5vbbbzfLly+3t5NkunfvboYOHWr+7//+z6xevdqMHDnSREREmN27d9vbTZkyxXTr1s3pdTIzM03tr0F392l77o8//miMMea9994zbdu2NRdddJE5dOhQve9v6dKlRpLJz8+3bzv77LNNu3btTK9evcxTTz1lcnJyzPXXX28kOX3+tW3atMm0atXKnHfeefbj8fPPP3d4rR49epibbrrJvPPOO+aZZ54xbdu2NaNGjXLYz1/+8hdjsVjMtGnTzFtvvWVee+01k56ebuLi4uz7q8vnn39uYmNjTVpamlm+fLl54403zPjx481JJ53k9F5/97vfGUnmxhtvNNnZ2eapp54yHTp0MF27drV/nsYY88wzzxiLxWJGjhxpXnrpJfPuu++aRYsWmeuvv97hc6t9HjDG+XfujXOOu5/PlClTTFRUlOnTp4954IEHzLvvvmvuuusuY7FYTFZWljHGmIqKCpOdnW0kmWuuucb+e6vrb7m0tNT+u/zzn/9sb793715jjDEvvviikWTGjRtnVq5caVasWGEGDx5soqKizAcffFDn762h/brzXowxprKy0kyYMMHExcWZrKwsk5OTY5555hnTuXNnk5aWZg4fPlxnDMYYc+qpp5qTTz7ZvPDCC2bDhg3m1VdfNXPmzHE4T7v7+b/yyivmrrvuMq+//rrZsGGDefnll83ZZ59tOnTo4HB82d53586dze9+9zvz9ttvm3/+85/mxIkT5s477zSSzK9+9SvzyiuvmDVr1piHHnrI3HnnnfbnN+VvtqqqyowaNcpER0ebv/zlL2bNmjUmMzPT9OjRw+l7zJPz13XXXWciIyPNnDlzTHZ2tnnppZdM7969TVJSkiksLHSIPTEx0XTt2tU8/vjjZv369WbDhg1N/g4D4D0k6QAa5cCBA+ass84ykowkExkZaYYNG2YWLFhgysvLHdrWlaQPGDDAVFZW2rc/8sgjRpK58MILHZ4/c+ZMI8mUlpbWuU9jnJP02k6cOGGOHz9uxowZYy655BKneHr27Ol0s6F2km6MMffff79T4lEzroEDBzpsmzFjhklISHD6XGr66aef7IlWTXv27DHR0dHmyiuvtG+zXVxu2bKlzv3ZjB8/3nTp0sXhszPGmBtvvNHExMSYkpISl8+zfVbXXHON+cUvfmHf/v777xtJ5o477qj3dbt162ZiYmLMd999Z9925MgRk5iYaH7/+9/X+9znn3/e5YVibZJMUlKSKSsrs28rLCw0YWFhZsGCBfZtnibp7uyzZpL+wgsvmKioKHPzzTc7HM91qStJl2T+/e9/O7RNS0sz48ePb3CfcXFxZsqUKXW+Vs3E1hhjFi5caCSZgoICY0z1cRYREWFuuukmh3bl5eUmOTnZXHbZZfW+/uWXX25atWrlkAicOHHC9O7d2+G97tq1y2U8//73v40kc/vtt9tfNyEhwZx11lmmqqqqztf1NElv7DnHk89nypQpRpL5v//7P4e25513njn11FPtP//4448NnrNq2rJli9O5yJjqBLlTp06mX79+Du+tvLzcdOzY0QwbNqxR+/XkvSxfvtxIMq+++qrLfS9atKjO1z9w4ICRZB555JE62zTl+Dxx4oT5+eefTVxcnMONRNvfxuTJkx3af/PNNyY8PNxcddVVde7TmKb9zb799ttGkkM8xlTfiGhskr5p0yYjyTz44IMO7fbu3WtatWpl/vjHPzrFvnbtWpfvqzHfYQC8i3J3AI3Srl07ffDBB9qyZYvuvfdeXXTRRfryyy81d+5c9evXz61Zr8877zyH0vg+ffpIksMkbTW379mzx+M4n3rqKQ0aNEgxMTGKiIhQZGSk1q5d61BCbnPhhRcqMjLS49eo6ZZbbtGOHTv04YcfSqouaXzhhRc0ZcqUemdJ3rRpk44cOeJU7tq1a1eNHj1aa9eu9TiWiooKrV27VpdccoliY2N14sQJ+7/zzjtPFRUV2rx5s739K6+8ouHDh6t169b2z+rZZ591+KzefvttSdINN9zQ4OsPHDhQJ510kv3nmJgYnXLKKU5lp7W9/fbbiomJ0bRp0xp8jVGjRjlMmpeUlKSOHTs2+Bre2udf/vIXTZ06Vffee68effRRp6EenkhOTnaaY6B///5Nei82F154odN+Jdn3/c477+jEiROaPHmyw3ESExOjs88+u8HJzdavX68xY8YoKSnJvi08PFyXX365UztJTsf50KFD1adPH/tx/tFHH6msrEzXX3+9V8cHN/ac4+nnY7FYlJGR4bDNW7/L2r744gv98MMPuvrqqx3eW+vWrXXppZdq8+bNLsuX3eXOe3nrrbfUpk0bZWRkOHw+AwcOVHJycr3HT2Jionr27Kn7779fDz30kLZv3+5ULu7J5//zzz/rT3/6k04++WRFREQoIiJCrVu31qFDh1ye9y+99FKHn3NyclRZWenWOa6xf7O2v4OrrrrKYfuVV17Z4GvW5a233pLFYtGkSZMcPqPk5GQNGDDA6XfQtm1bjR492mk/jf0OA+BdJOkAmmTIkCH605/+pFdeeUU//PCDZs2apW+//dZp8jhXEhMTHX6Oioqqd3tFRYVHsT300EOaMWOGzjjjDL366qvavHmztmzZogkTJujIkSNO7b0x2/ZFF12k7t2728d8P/fcczp06FCDF3zFxcV1xtCpUyf7454oLi7WiRMn9PjjjysyMtLh33nnnSdJ9pspr732mi677DJ17txZy5Yt06ZNm7RlyxZNmzbN4XP/8ccfFR4eruTk5AZfv127dk7boqOjXX72Nf3444/q1KmTWwlvY1/DW/tctmyZOnfurCuuuKLRr9eY123qvqOjoyXJvu/9+/dLkk4//XSnY2XFihUN3nQrLi52eUzU3ubucW4bx9ylS5cG35snGnvO8fTziY2NVUxMjMO26Ohoj89h7mjoM62qqtJPP/3U6P27817279+vgwcPKioqyunzKSwsrPf4sVgsWrt2rcaPH6+FCxdq0KBB6tChg26++WaVl5fb9y+59/lfeeWVeuKJJ3TttdfqnXfeUW5urrZs2aIOHTq4dd735Nhr7N9scXGxIiIinJ7vznm1Lvv375cxRklJSU6f0ebNm51+B3V93zX2OwyAdzG7OwCviYyMVGZmph5++GHt3LnT3+Fo2bJlGjlypBYvXuyw3XbhV5s3euzCwsJ0ww036Pbbb9eDDz6oRYsWacyYMTr11FPrfZ7tYq2goMDpsR9++EHt27f3OJa2bdsqPDxcV199dZ0XWKmpqZKqP6vU1FStWLHC4XOoPTlUhw4dVFlZqcLCQq8uIVb7NTZu3Kiqqqom9UzbxMTEOL0PSY1a47y27OxsXX755RoxYoTWrl2rbt26NXmf/mA7vv75z3826j20a9dOhYWFTttrb6t5nNdOgmoe57ZJ1VxNJldTTEyMSktLnbZ743dbU1M/H19q6NwRFhamtm3b+jQG24SE2dnZLh9vaInIbt262Sdl+/LLL/V///d/mjdvno4dO6annnrK7c+/tLRUb731ljIzM3XbbbfZtx89elQlJSUun1P7vF/z2OvatWu9cTdWu3btdOLECRUXFzsk6q7+htw9f7Vv314Wi0UffPCB/SZcTbW31fV919jvMADeRU86gEZxdUEoyV5O2KlTp+YMxyWLxeJ0YfLpp582OONxQ2r3QtZ27bXXKioqSldddZW++OIL3XjjjQ3uMz09Xa1atdKyZcsctn///fdat26dxowZ43GcsbGxGjVqlLZv367+/ftryJAhTv9sF4gWi0VRUVEOF26FhYVOs7ufe+65kuR048Obzj33XFVUVNhn1G+q7t27q6ioyN4bJ1XPRP3OO+80ed/dunWzXxSPGDFCX331VZP32RhN7XEfP368IiIitHv3bpfHyZAhQ+p9/qhRo7R27VqHz7iyslIrVqxwaGcrr619nG/ZskW7du2yH+fDhg2T1WrVU089JWNMna/bvXt3ffnllw5JTHFxsctVAJqiqZ+PKw2dR9xtf+qpp6pz58566aWXHD6rQ4cO6dVXX7XP+O6tOFy54IILVFxcrMrKSpefjScJ3imnnKI///nP6tevn7Zt2ybJ/c/fYrHIGON03n/mmWdUWVnp1uuPGzdO4eHhPj3HjRo1SpL04osvOmx/6aWXnNq6e/664IILZIzRvn37XH4+/fr1czu+xnyHAfAuetIBNMr48ePVpUsXZWRkqHfv3qqqqtKOHTv04IMPqnXr1rrlllv8HaIuuOAC3X333crMzNTZZ5+tL774QvPnz1dqaqpOnDjR6P3aLnYeffRRTZkyRZGRkTr11FPtvUVt2rTR5MmTtXjxYnXr1s1pPKcrbdq00Z133qnbb79dkydP1sSJE1VcXKysrCzFxMQoMzOzUbE++uijOuusszRixAjNmDFD3bt3V3l5ub7++mutWrVK69atk1T9Wb322mu6/vrr9etf/1p79+7V3XffrZSUFIfEc8SIEbr66qt1zz33aP/+/brgggsUHR2t7du3KzY2VjfddFOj4qxp4sSJWrp0qaZPn64vvvhCo0aNUlVVlf7973+rT58+HpeWX3755brrrrt0xRVX6A9/+IMqKir02GOPuX3R3pCUlBRt2LBB48eP1y9/+Uvl5OSob9++Xtm3u/r166f33ntPq1atUkpKiuLj4z1KjLp376758+frjjvu0DfffKMJEyaobdu22r9/v3JzcxUXF6esrKw6n//nP/9Zb775pkaPHq277rpLsbGxevLJJ3Xo0CGHdqeeeqp+97vf6fHHH1dYWJjOPfdcffvtt7rzzjvVtWtXzZo1S1L1eOoHH3xQ1157rc455xxdd911SkpK0tdff61PPvlETzzxhCTp6quv1tNPP61JkybpuuuuU3FxsRYuXKiEhIRGfIq++3xciY+PV7du3fTGG29ozJgxSkxMVPv27V0utyVJPXv2VKtWrfTiiy+qT58+at26tTp16qROnTpp4cKFuuqqq3TBBRfo97//vY4ePar7779fBw8e1L333ltvHPXt111XXHGFXnzxRZ133nm65ZZbNHToUEVGRur777/X+vXrddFFF+mSSy5x+dxPP/1UN954o37zm9+oV69eioqK0rp16/Tpp5/ae8Pd/fwTEhL0y1/+Uvfff7/9s9ywYYOeffZZtWnTxq330r17d91+++26++67deTIEU2cOFFWq1V5eXk6cOCAx79nV8aNG6df/vKX+uMf/6hDhw5pyJAh+vDDD/XCCy84tXX3/DV8+HD97ne/029/+1t9/PHH+uUvf6m4uDgVFBRo48aN6tevn2bMmOFWfI35DgPgZX6dtg5A0FqxYoW58sorTa9evUzr1q1NZGSkOemkk8zVV19t8vLyHNrWNbv7/fff79Bu/fr1RpJ55ZVXHLa7ms3cndndjx49am699VbTuXNnExMTYwYNGmRWrlxZ58zPteOp+VjtmY/nzp1rOnXqZMLCwowkh6WCjKlekkuSuffee532WZ9nnnnG9O/f30RFRRmr1Wouuugip+WvPJnd3fYepk2bZjp37mwiIyNNhw4dzLBhw8w999zj0O7ee+813bt3N9HR0aZPnz7m73//u8sZ0CsrK83DDz9s+vbta48zPT3drFq1yt6mW7du5vzzz3eKpa7ZuGs7cuSIueuuu0yvXr1MVFSUadeunRk9erT56KOP7G0kmRtuuMHpud26dXOa6Xz16tVm4MCBplWrVqZHjx7miSeeqHN2d3f2WXsJNmOql7EbPny4SUxMrPd3U9fs7qeddppT27pmdq5tx44dZvjw4SY2NtZIsn/GdR0rtr+12sftypUrzahRo0xCQoKJjo423bp1M7/+9a/Nu+++22AMH374oTnzzDNNdHS0SU5ONn/4wx/M3/72N6f3WllZae677z5zyimnmMjISNO+fXszadIk+7JfNa1evdqcffbZJi4uzr7E23333efQ5h//+Ifp06ePiYmJMWlpaWbFihVu/417cs5x9/OZMmWKiYuLc3ovro63d9991/ziF78w0dHRRpLLGfprWr58uendu7eJjIx0Ot+tXLnSnHHGGSYmJsbExcWZMWPGmA8//LDe/TW0X0/ey/Hjx80DDzxgBgwYYGJiYkzr1q1N7969ze9//3vz1Vdf1fna+/fvN1OnTjW9e/c2cXFxpnXr1qZ///7m4YcfNidOnHBo687n//3335tLL73UtG3b1sTHx5sJEyaYnTt3Ov0NN3Qeff75583pp59ufy+/+MUvHL4Hmvo3e/DgQTNt2jTTpk0bExsba8aOHWv+85//uJzx393zlzHGLFmyxJxxxhkmLi7OtGrVyvTs2dNMnjzZfPzxxw3GXlNjv8MAeIfFmHrqyAAAjTJnzhwtXrxYe/fudTm5EAAAtVksFmVmZmrevHl+jYPvMMC/KHcHAC/avHmzvvzySy1atEi///3vubgBAAQNvsOAwECSDgBeZJuk6YILLtA999zj73AAAHAb32FAYKDcHQAAAACAAOHXJdjef/99ZWRkqFOnTrJYLFq5cmWDz9mwYYMGDx6smJgY9ejRQ0899ZTvAwUAAAAAoBn4NUk/dOiQBgwYYF9KpSH5+fk677zzNGLECG3fvl233367br75Zr366qs+jhQAAAAAAN8LmHJ3i8Wi119/XRdffHGdbf70pz/pzTff1K5du+zbpk+frk8++USbNm1qhigBAAAAAPCdoJo4btOmTRo3bpzDtvHjx+vZZ5/V8ePHFRkZ6fSco0eP6ujRo/afq6qq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dwAA3MR6uAAQutyd/O3cvilK79muUQm6bdb4N3bs06bdxXyfhCi/J+mLFi1SamqqYmJiNHjwYH3wwQd1tn3ttdc0duxYdejQQQkJCUpPT9c777zTjNECAEIZ6+ECQOgampqoFGuM0xrtNhZVD31q7CRx2TsLdNZ96zTx75t1y8s7NPHvm3XWfeuU7eYyb2g5/Jqkr1ixQjNnztQdd9yh7du3a8SIETr33HO1Z88el+3ff/99jR07VqtXr9bWrVs1atQoZWRkaPv27c0cOQAgFLlb6sh6uADQ8oSHWZSZkSZJTol6UyeJsw2lqn0j2DaUikQ9tFiMMX6roTjjjDM0aNAgLV682L6tT58+uvjii7VgwQK39nHaaafp8ssv11133eVW+7KyMlmtVpWWliohIaFRcQMAQtOm3cWa+PfNDbZbft2ZflkaCADge96ePLSyyuis+9bVWallW8Zt459GM8Y9iHmSh/pt4rhjx45p69atuu222xy2jxs3Th999JFb+6iqqlJ5ebkSE+suKTl69KiOHj1q/7msrKxxAQMAQp6t1LGwtMLluHTWwwWAlm9C3xSNTUv22jKcngyl4gZwaPBbufuBAwdUWVmppKQkh+1JSUkqLCx0ax8PPvigDh06pMsuu6zONgsWLJDVarX/69q1a5PiBgCELl+WOiLwMIETgLqEh1mU3rOdLhrYudGTxNkwlAq1+X0JNovF8YA2xjhtc2X58uWaN2+e3njjDXXs2LHOdnPnztXs2bPtP5eVlZGoAwAabULfFC2eNMip1JH1cFsWb5ezAkBd3J013t12CH5+S9Lbt2+v8PBwp17zoqIip9712lasWKFrrrlGr7zyis4555x620ZHRys6OrrJ8QIAYOPtUkcEFtsETrX7zW0TOC2eNIhEHYDXMJQKtfmt3D0qKkqDBw9WTk6Ow/acnBwNGzaszuctX75cU6dO1UsvvaTzzz/f12ECAOBSY0sdKaEObJVVRlmr8lxeKNu2Za3K4/cGwGsYSoXa/FruPnv2bF199dUaMmSI0tPT9be//U179uzR9OnTJVWXqu/bt0/PP/+8pOoEffLkyXr00Ud15pln2nvhW7VqJavV6rf3AQCAOyihDnxM4ATAHxhKhZr8mqRffvnlKi4u1vz581VQUKC+fftq9erV6tatmySpoKDAYc30p59+WidOnNANN9yg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",
      "text/plain": [
       "<Figure size 1200x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plot_relevance_scores(chunk_values)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to interpret the chunk relevance plot above\n",
    "In the plot above, the x-axis represents the chunk index. The first chunk in the document has index 0, the next chunk has index 1, etc. The y-axis represents the relevance of each chunk to the query. Viewing it this way lets us see how relevant chunks tend to be clustered in one or more sections of a document. \n",
    "\n",
    "Note: the relevance values in this plot are actually a combination of the raw relevance value and the relevance ranks. An exponential decay function is applied to the ranks, and that is then multiplied by the raw relevance value. Using this combination provides a more robust measure of relevance than using just one or the other.\n",
    "\n",
    "### Zooming in\n",
    "Now let's zoom in on that cluster of relevant chunks for a closer look."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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+cYsX77cDBs2zPj4+Jj169c71FOjRg3TuXNn8+mnn5o1a9aYpKQk22vz5s0zxhhz9OhRM3LkSCPJfP7552br1q1m69atJi0tzfz4449Gknn//fft6tq7d6+RZN55552rrtOXXnrJSDL333+/+eqrr8z8+fNN3bp1jdVqNT///LNtXv/6179sNW3dutUcPHiwwHnu3bvXWK1W07RpUzN//nyzZs0aM3bsWOPj42MmTpxo63f69GkzZMgQ8+GHH5p169aZVatWmaefftr4+PiY//znP3bzHDhwoLFYLObhhx82X375pVm5cqV58cUXzZtvvmnrExUVZWrWrGkaNWpk5s+fb1avXm3uu+8+I8ls2LDhquvh4sWLpnPnzsbPz888/fTTZsWKFWbp0qVmwoQJZtGiRbZ+kkydOnVMmzZtzH//+1+zYsUK06lTJ+Pn52d++eUXW7/BgwebqKgoh+XExcWZKzeDhZ1n3rR//PGHMcaYb775xlSqVMncdddd5uzZs1d9f/PmzTOSTFJSkq2tY8eOpnLlyqZ+/fpm1qxZJiEhwTz22GNGksP6v9LWrVtNuXLlTK9evWyfx71799otq27dumbkyJFm9erVZvbs2aZSpUqmc+fOdvN58cUXjcViMUOHDjXLly83n3/+uYmNjTUhISG2+RVk7969Jjg42DRq1MgsWrTIfPnll6ZHjx6mdu3aDu/173//u5FknnjiCbNq1Soza9YsU7VqVVOrVi3b+jTGmNmzZxuLxWI6depkPvroI/P111+bGTNmmMcee8xuvV35O2CM45i74jensOtn8ODBJiAgwMTExJjXXnvNfP311+b55583FovFxMfHG2OMyczMNKtWrTKSzLBhw2zjVtB3OS0tzTaW//rXv2z9jx49aowxZuHChUaS6d69u1myZIlZvHixadWqlQkICDAbN24scNyuNd/CvBdjjMnJyTE9e/Y0ISEhJj4+3iQkJJjZs2ebGjVqmEaNGplz584VWIMxxjRo0MDccMMN5sMPPzQbNmwwn332mRk7dqzd73Rh1/8nn3xinn/+efPFF1+YDRs2mI8//th07NjRVK1a1e7zlfe+a9SoYf7+97+blStXmk8//dRkZ2eb5557zkgy99xzj/nkk0/MmjVrzNSpU81zzz1nm74439nc3FzTuXNnExgYaF588UWzZs0aExcXZ+rWreuwHXPm9+uRRx4x/v7+ZuzYsWbVqlXmo48+Mg0bNjTh4eEmJSXFrvawsDBTq1YtM336dLN+/XqzYcOGYm/DALgOIR1AkZw8edLccsstRpKRZPz9/U27du3M5MmTTUZGhl3fgkJ68+bNTU5Ojq192rRpRpLp06eP3fRPPfWUkWTS0tIKnKcxjiH9StnZ2ebixYuma9eupm/fvg711KtXz+E/G64M6cYY8+qrrzoEj8vratGihV3biBEjTGhoqMN6udyff/5pC1qXO3LkiAkMDDQPPPCArS3vj8vt27cXOL88PXr0MDVr1rRbd8YY88QTT5igoCCTmpqa73R562rYsGHmpptusrV/++23RpJ59tlnr7rcqKgoExQUZH799Vdb2/nz501YWJh59NFHrzrt/Pnz8/1D8UqSTHh4uElPT7e1paSkGB8fHzN58mRbm7MhvTDzvDykf/jhhyYgIMCMGjXK7vNckIJCuiTz3Xff2fVt1KiR6dGjxzXnGRISYgYPHlzgsi4PtsYYM2XKFCPJJCcnG2Mufc78/PzMyJEj7fplZGSY6tWrm379+l11+f379zflypWzCwLZ2dmmYcOGdu91//79+dbz3XffGUlmwoQJtuWGhoaaW265xeTm5ha4XGdDelF/c5xZP4MHDzaSzH//+1+7vr169TINGjSwPf/jjz+u+Zt1ue3btzv8FhlzKSBHRkaapk2b2r23jIwMU61aNdOuXbsizdeZ97Jo0SIjyXz22Wf5znvGjBkFLv/kyZNGkpk2bVqBfYrz+czOzjZnzpwxISEhdv+RmPfdGDRokF3/Q4cOGV9fX/Pggw8WOE9jivedXblypZFkV48xl/4joqghfevWrUaSef311+36HT161JQrV87885//dKh97dq1+b6vomzDALgWh7sDKJLKlStr48aN2r59u15++WXddddd+vnnnzV+/Hg1bdq0UFe97tWrl92h8TExMZJkd5G2y9uPHDnidJ2zZs1Sy5YtFRQUJD8/P/n7+2vt2rV2h5Dn6dOnj/z9/Z1exuWefPJJ7dq1S5s3b5Z06ZDGDz/8UIMHD77qVZK3bt2q8+fPOxzuWqtWLXXp0kVr1651upbMzEytXbtWffv2VXBwsLKzs22PXr16KTMzU9u2bbP1/+STT9S+fXuVL1/etq7mzJljt65WrlwpSXr88cevufwWLVqo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4MGDWrZsmdatWyfp0rr6/PPP9dhjj+mvf/2rjh49qn//+9+KiIiwC54dOnTQwIED9cILL+j48eO68847FRgYqB9++EHBwcEaOXJkkeq83P3336958+Zp+PDh+umnn9S5c2fl5ubqu+++U0xMjNOHlvfv31/PP/+8BgwYoH/84x/KzMzUW2+9Veg/2q8lIiJCGzZsUI8ePXTrrbcqISFBTZo0ccm8C6tp06b65ptvtGzZMkVERKhChQpOBaM6depo0qRJevbZZ3Xo0CH17NlTlSpV0vHjx5WYmKiQkBDFx8cXOP2//vUvLV26VF26dNHzzz+v4OBgvfPOOzp79qxdvwYNGujvf/+7pk+fLh8fH91+++06fPiwnnvuOdWqVUujR4+WdOl86tdff10PP/ywbrvtNj3yyCMKDw/XwYMH9eOPP+rtt9+WJA0cOFDvvvuuHnroIT3yyCM6deqUpkyZotDQ0CKsRfetn/xUqFBBUVFR+vLLL9W1a1eFhYWpSpUq+d5uS5Lq1auncuXKaeHChYqJiVH58uUVGRmpyMhITZkyRQ8++KDuvPNOPfroo8rKytKrr76q06dP6+WXX75qHVebb2ENGDBACxcuVK9evfTkk0+qTZs28vf312+//ab169frrrvuUt++ffOddvfu3XriiSd03333qX79+goICNC6deu0e/du297wwq7/0NBQ3XrrrXr11Vdt63LDhg2aM2eOKlasWKj3UqdOHU2YMEH//ve/df78ed1///2yWq3at2+fTp486fQ456d79+669dZb9c9//lNnz55V69attXnzZn344YcOfQv7+9W+fXv9/e9/19/+9jd9//33uvXWWxUSEqLk5GRt2rRJTZs21YgRIwpVX1G2YQBczKOXrQNQai1evNg88MADpn79+qZ8+fLG39/f1K5d2wwcONDs27fPrm9BV3d/9dVX7fqtX7/eSDKffPKJXXt+VzMvzNXds7KyzNNPP21q1KhhgoKCTMuWLc2SJUsKvPLzlfVc/tqVVz4eP368iYyMND4+PkaS3a2CjLl0Sy5J5uWXX3aY59XMnj3bNGvWzAQEBBir1Wruuusuh9tfOXN197z3MHToUFOjRg3j7+9vqlatatq1a2deeOEFu34vv/yyqVOnjgkMDDQxMTHm/fffz/cK6Dk5OeaNN94wTZo0sdUZGxtrli1bZusTFRVl7rjjDodaCroa95XOnz9vnn/+eVO/fn0TEBBgKleubLp06WK2bNli6yPJPP744w7TRkVFOVzpfMWKFaZFixamXLlypm7duubtt98u8OruhZnnlbdgM+bSbezat29vwsLCrjo2BV3dvXHjxg59C7qy85V27dpl2rdvb4KDg40k2zou6LOS91278nO7ZMkS07lzZxMaGmoCAwNNVFSU+etf/2q+/vrra9awefNmc/PNN5vAwEBTvXp1849//MO89957Du81JyfHvPLKK+bGG280/v7+pkqVKuahhx6y3fbrcitWrDAdO3Y0ISEhtlu8vfLKK3Z9/vOf/5iYmBgTFBRkGjVqZBYvXlzo77gzvzmFXT+DBw82ISEhDu8lv8/b119/bW666SYTGBhoJOV7hf7LLVq0yDRs2ND4+/s7/N4tWbLEtG3b1gQFBZmQkBDTtWtXs3nz5qvO71rzdea9XLx40bz22mumefPmJigoyJQvX940bNjQPProo+bAgQMFLvv48eNmyJAhpmHDhiYkJMSUL1/eNGvWzLzxxhsmOzvbrm9h1v9vv/1m7r33XlOpUiVToUIF07NnT7Nnzx6H7/C1fkfnz59v/vKXv9jey0033WS3HSjud/b06dNm6NChpmLFiiY4ONh069bN/O9//8v3iv+F/f0yxpi5c+eatm3bmpCQEFOuXDlTr149M2jQIPP9999fs/bLFXUbBsA1LMZc5TgyAECRjB07VjNnztTRo0fzvbgQAABXslgsiouL08SJEz1aB9swwLM43B0AXGjbtm36+eefNWPGDD366KP8cQMAKDXYhgHegZAOAC6Ud5GmO++8Uy+88IKnywEAoNDYhgHegcPdAQAAAADwEh69Bdu3336r3r17KzIyUhaLRUuWLLnmNBs2bFCrVq0UFBSkunXratasWe4vFAAAAACAEuDRkH727Fk1b97cdiuVa0lKSlKvXr3UoUMH/fDDD5owYYJGjRqlzz77zM2VAgAAAADgfl5zuLvFYtEXX3yhu+++u8A+zzzzjJYuXar9+/fb2oYPH64ff/xRW7duLYEqAQAAAABwn1J14bitW7eqe/fudm09evTQnDlzdPHiRfn7+ztMk5WVpaysLNvz3NxcpaamqnLlyrJYLG6vGQAAAABQthljlJGRocjISPn4XP2A9lIV0lNSUhQeHm7XFh4eruzs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FDugS1L//v116tQpTZo0ScnJyWrSpIlWrFhhO+89OTlZR44csfUvX768EhISNHLkSLVu3VqVK1dWv3799MILLxS7FgAAAAAAPM3pPen//Oc/FRYW5nDrtNKCPekAAAAAgJLkTA51OqTn5OTozjvv1Pnz59W0aVP5+/vbvT516lTnKy5BhHQAAAAAQEly6+HuL730klavXq0GDRpIksOF4wAAAAAAQNE4HdKnTp2quXPnasiQIW4oBwAAAACAssvpq78FBgaqffv27qgFAAAAAIAyzemQ/uSTT2r69OnuqAUAAAAAgDLN6cPdExMTtW7dOi1fvlyNGzd2uHDc559/7rLiAAAAAAAoS5wO6RUrVtQ999zjjloAAAAAACjTnA7p8+bNc0cdAAAAAACUeU6fkw4AAAAAANyjUHvSW7ZsqbVr16pSpUq66aabrno/9J07d7qsOAAAAAAAypJChfS77rpLgYGBkqS7777bnfUAAAAAAFBmWYwxxtNFlKT09HRZrValpaUpNDTU0+UAAAAAAK5zzuRQp89JP3r0qH777Tfb88TERD311FN67733nK8UAAAAAADYOB3SH3jgAa1fv16SlJKSottuu02JiYmaMGGCJk2a5PICAQAAAAAoK5wO6Xv27FGbNm0kSf/973/VtGlTbdmyRR999JE++OADV9cHAAAAAECZ4XRIv3jxou0icl9//bX69OkjSWrYsKGSk5NdWx0AAAAAAGWI0yG9cePGmjVrljZu3KiEhAT17NlTkvT777+rcuXKLi8QAAAAAICywumQ/sorr+jdd99Vp06ddP/996t58+aSpKVLl9oOgwcAAAAAAM4r0i3YcnJylJ6erkqVKtnaDh8+rODgYFWrVs2lBboat2ADAAAAAJQkZ3KoX1EW4OvraxfQJalOnTpFmRUAAAAAAPh/nD7cHQAAAAAAuAchHQAAAAAAL0FIBwAAAADASzgd0o8ePVrga9u2bStWMQAAAAAAlGVOh/Ru3brp1KlTDu2bN2+23TMdAAAAAAA4z+mQ3qFDB3Xv3l0ZGRm2tm+//Va9evVSXFycS4sDAAAAAKAscTqkv/fee4qOjtYdd9yhzMxMrV+/XnfccYcmTZqk0aNHu6NGAAAAAADKBKdDusVi0aJFixQUFKSuXbuqT58+mjx5sp588kl31AcAAAAAQJlhMcaYa3XavXu3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GGOcmaBZs2bav3+/unfvrkceeUS9e/eWr6+vXZ8//vhD4eHhys3NdWmxrpCeni6r1aq0tDTOTwcAAAAAuJ0zOdTpPen33Xefhg4dqho1ahTYp2rVql4Z0AEAAAAA8GZOnZN+8eJFzZs3r1AXhgMAAAAAAM5xKqT7+/srKysr3/uYAwAAAACA4nH66u4jR47UK6+8ouzsbHfUAwAAAABAmeX0Oenfffed1q5dqzVr1qhp06YOtz77/PPPXVYcAAAAAABlidMhvWLFirr33nvdUQsAAAAAAGWa0yF93rx57qgDAAAAAIAyz+lz0iUpOztbX3/9td59911lZGRIkn7//XedOXPGpcUBAAAAAFCWOL0n/ddff1XPnj115MgRZWVlqVu3bqpQoYKmTJmizMxMzZo1yx11AgAAAABw3XN6T/qTTz6p1q1b688//1S5cuVs7X379tXatWtdWhwAAAAAAGWJ03vSN23apM2bNysgIMCuPSoqSseOHXNZYQAAAAAAlDVO70nPzc1VTk6OQ/tvv/2mChUquKQoAAAAAADKIqdDerdu3TRt2jTbc4vFojNnziguLk69evVyZW0AAAAAAJQpFmOMcWaC33//XZ07d5avr68OHDig1q1b68CBA6pSpYq+/fZbVatWzV21ukR6erqsVqvS0tIUGhrq6XIAAAAAANc5Z3Ko0+ekR0ZGateuXVq0aJF27typ3NxcDRs2TA8++KDdheQAAAAAAIBznN6TXtqxJx0AAAAAUJLcuid9/vz5V3190KBBzs4SAAAAAACoCHvSK1WqZPf84sWLOnfunAICAhQcHKzU1FSXFuhq7EkHAAAAAJQkZ3Ko01d3//PPP+0eZ86c0U8//aRbbrlFixYtKnLRAAAAAACUdU6H9PzUr19fL7/8sp588klXzA4AAAAAgDLJJSFdknx9ffX777+7anYAAAAAAJQ5Tl84bunSpXbPjTFKTk7W22+/rfbt27usMAAAAAAAyhqnQ/rdd99t99xisahq1arq0qWLXn/9dVfVBQAAAABAmeN0SM/NzXVHHQAAAAAAlHlFPif95MmTSk9Pd2UtAAAAAACUaU6F9NOnT+vxxx9XlSpVFB4erkqVKql69eoaP368zp07564aAQAAAAAoEwp9uHtqaqpiY2N17NgxPfjgg4qJiZExRvv379f06dOVkJCgTZs26ccff9R3332nUaNGubNuAAAAAACuO4UO6ZMmTVJAQIB++eUXhYeHO7zWvXt3DRw4UGvWrNFbb73l8kIBAAAAALjeFTqkL1myRO+++65DQJek6tWra8qUKerVq5fi4uI0ePBglxYJAAAAAEBZUOhz0pOTk9W4ceMCX2/SpIl8fHwUFxfnksIAAAAAAChrCh3Sq1SposOHDxf4elJSkqpVq+aKmgAAAAAAKJMKHdJ79uypZ599VhcuXHB4LSsrS88995x69uzp0uIAAAAAAChLLMYYU5iOv/32m1q3bq3AwEA9/vjjatiwoSRp3759mjFjhrKysrR9+3bVrl3brQUXV3p6uqxWq9LS0hQaGurpcgAAAAAA1zlncmihLxxXs2ZNbd26VY899pjGjx+vvGxvsVjUrVs3vf32214f0AEAAAAA8GaFDumSFB0drZUrV+rPP//UgQMHJEk33HCDwsLC3FIcAAAAAABliVMhPU+lSpXUpk0bV9cCAAAAAECZVugLxwEAAAAAAPcipAMAAAAA4CUI6QAAAAAAeAlCOgAAAAAAXoKQDgAAAACAlyCkAwAAAADgJQjpAAAAAAB4CUI6AAAAAABegpAOAAAAAICXIKQDAAAAAOAlCOkAAAAAAHgJQjoAAAAAAF6CkA4AAAAAgJcgpAMAAAAA4CUI6QAAAAAAeAlCOgAAAAAAXoKQDgAAAACAlyCkAwAAAADgJQjpAAAAAAB4CUI6AAAAAABegpAOAAAAAICXIKQDAAAAAOAlCOkAAAAAAHgJQjoAAAAAAF6CkA4AAAAAgJcgpAMAAAAA4CUI6QAAAAAAeAlCOgAAAAAAXoKQDgAAAACAlyCkAwAAAADgJTwe0mfMmKHo6GgFBQWpVatW2rhxY4F9P//8c3Xr1k1Vq1ZVaGioYmNjtXr16hKsFgAAAAAA9/FoSF+8eLGeeuopPfvss/rhhx/UoUMH3X777Tpy5Ei+/b/99lt169ZNK1as0I4dO9S5c2f17t1bP/zwQwlXDgAAAACA61mMMcZTC2/btq1atmypmTNn2tpiYmJ09913a/LkyYWaR+PGjdW/f389//zzheqfnp4uq9WqtLQ0hYaGFqluAAAAAAAKy5kc6rE96RcuXNCOHTvUvXt3u/bu3btry5YthZpHbm6uMjIyFBYWVmCfrKwspaen2z0AAAAAAPBGHgvpJ0+eVE5OjsLDw+3aw8PDlZKSUqh5vP766zp79qz69etXYJ/JkyfLarXaHrVq1SpW3QAAAAAAuIvHLxxnsVjsnhtjHNrys2jRIk2cOFGLFy9WtWrVCuw3fvx4paWl2R5Hjx4tds0AAAAAALiDn6cWXKVKFfn6+jrsNT9x4oTD3vUrLV68WMOGDdMnn3yi22677ap9AwMDFRgYWOx6AQAAAABwN4/tSQ8ICFCrVq2UkJBg156QkKB27doVON2iRYs0ZMgQffTRR7rjjjvcXSYAAAAAACXGY3vSJWnMmDEaOHCgWrdurdjYWL333ns6cuSIhg8fLunSoerHjh3T/PnzJV0K6IMGDdKbb76pm2++2bYXvly5crJarR57HwAAAAAAuIJHQ3r//v116tQpTZo0ScnJyWrSpIlWrFihqKgoSVJycrLdPdPfffddZWdn6/HHH9fjjz9uax88eLA++OCDki4fAAAAAACX8uh90j2B+6QDAAAAAEpSqbhPOgAAAAAAsEdIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8BCEdAAAAAAAvQUgHAAAAAMBLENIBAAAAAPAShHQAAAAAALwEIR0AAAAAAC9BSAcAAAAAwEsQ0gEAAAAA8BKEdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8BCEdAAAAAAAvQUgHAAAAAMBLENIBAAAAAPAShHQAAAAAALwEIR0AAAAAAC9BSAcAAAAAwEsQ0gEAAAAA8BKEdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8BCEdAAAAAAAvQUgHAAAAAMBLENIBAAAAAPAShHQAAAAAALwEIR0AAAAAAC9BSAcAAAAAwEsQ0gEAAAAA8BKEdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8BCEdAAAAAAAvQUgHAAAAAMBLENIBAAAAAPAShHQAAAAAALwEIR0AAAAAAC9BSAcAAAAAwEsQ0gEAAAAA8BKEdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8BCEdAAAAAAAvQUgHAAAAAMBLENIBAAAAAPAShHQAAAAAALwEIR0AAAAAAC9BSAcAAAAAwEsQ0gEAAAAA8BKEdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDSAQAAAADwEoR0AAAAAAC8hJ+nCwAAwJvl5BolJqXqREamqlUIUpvoMPn6WDxdFgAAuE4R0r1UafujsLTVK5XOmoEr8Tl2r1V7khW/bJ+S0zJtbRHWIMX1bqSeTSI8WFnBSuNnojTWXNqUtnVc2uotjVjH7lca13Fpq7m01VtYHg/pM2bM0Kuvvqrk5GQ1btxY06ZNU4cOHQrsv2HDBo0ZM0Z79+5VZGSk/vnPf2r48OElWLH7lbY/CktbvVLprBm4Ep9j91q1J1kjFuyUuaI9JS1TIxbs1MyHWnrdei6Nn4nSWHNpU9rWcWmrtzRiHbtfaVzHpa3m0lavMyzGmCv//igxixcv1sCBAzVjxgy1b99e7777rmbPnq19+/apdu3aDv2TkpLUpEkTPfLII3r00Ue1efNmPfbYY1q0aJHuvffeQi0zPT1dVqtVaWlpCg0NdfVbKraC/ijM+/8gb/ujsLTVK5XOmoEr8Tl2r5xco1teWWe34b+cRVJ1a5A2PdPFa/7HvjR+JkpjzaVNaVvHpa3e0oh17H6lcR2XtppLW72ScznUoxeOmzp1qoYNG6aHH35YMTExmjZtmmrVqqWZM2fm23/WrFmqXbu2pk2bppiYGD388MMaOnSoXnvttRKu3D1yco3il+1z+LBJsrXFL9unnFyP/b+KndJWr1Q6awauxOfY/RKTUgsM6NKl9ZyclqnEpNSSK+oqSuNnojTWXNqUtnVc2uotjVjH7lca13Fpq7m01VsUHjvc/cKFC9qxY4fGjRtn1969e3dt2bIl32m2bt2q7t2727X16NFDc+bM0cWLF+Xv7+8wTVZWlrKysmzP09LSJF36nwxvk3goVcdOXP0PvmMnzmn97l/Vpm5YCVVVsNJWr1Q6awauxOfY/Q4n/6HcrHOF6te4quO2p6SVxs9Eaay5tClt67i01VsasY7drzSu49JWc2mrN09e/izUgezGQ44dO2Ykmc2bN9u1v/jii+bGG2/Md5r69eubF1980a5t8+bNRpL5/fff850mLi7O6NJ/qvDgwYMHDx48ePDgwYMHDx4eexw9evSaWdnjF46zWOzP5TPGOLRdq39+7XnGjx+vMWPG2J7n5uYqNTVVlStXvupyvEF6erpq1aqlo0ePeuX58ygYY1d6MXalF2NXujF+pRdjV3oxdqUXY1f6GGOUkZGhyMjIa/b1WEivUqWKfH19lZKSYtd+4sQJhYeH5ztN9erV8+3v5+enypUr5ztNYGCgAgMD7doqVqxY9MI9IDQ0lC9fKcXYlV6MXenF2JVujF/pxdiVXoxd6cXYlS5Wq7VQ/Tx24biAgAC1atVKCQkJdu0JCQlq165dvtPExsY69F+zZo1at26d7/noAAAAAACUJh69uvuYMWM0e/ZszZ07V/v379fo0aN15MgR233Px48fr0GDBtn6Dx8+XL/++qvGjBmj/fv3a+7cuZozZ46efvppT70FAAAAAABcxqPnpPfv31+nTp3SpEmTlJycrCZNmmjFihWKioqSJCUnJ+vIkSO2/tHR0VqxYoVGjx6td955R5GRkXrrrbcKfY/00iYwMFBxcXEOh+vD+zF2pRdjV3oxdqUb41d6MXalF2NXejF21zeLMYW5BjwAAAAAAHA3jx7uDgAAAAAA/n+EdAAAAAAAvAQhHQAAAAAAL0FIBwAAAADASxDS3WDmzJlq1qyZQkNDFRoaqtjYWK1cuVKSdPHiRT3zzDNq2rSpQkJCFBkZqUGDBun333+3m0dWVpZGjhypKlWqKCQkRH369NFvv/12zWXPmDFD0dHRCgoKUqtWrbRx40a3vMfrVXHHLjU1VSNHjlSDBg0UHBys2rVra9SoUUpLS7vqcidOnCiLxWL3qF69ulvf6/XGFd+7Tp06OYzDgAEDrrlsvnfFV9zxO3z4sMPY5T0++eSTApfLd6/4rjZ20qV13LBhQ4WEhKhSpUq67bbb9N1339nNg22eZxR37NjmeY4rvnds8zynuOPHNq8MMHC5pUuXmq+++sr89NNP5qeffjITJkww/v7+Zs+ePeb06dPmtttuM4sXLzb/+9//zNatW03btm1Nq1at7OYxfPhwU6NGDZOQkGB27txpOnfubJo3b26ys7MLXO7HH39s/P39zfvvv2/27dtnnnzySRMSEmJ+/fVXd7/l60Zxx+7//u//zD333GOWLl1qDh48aNauXWvq169v7r333qsuNy4uzjRu3NgkJyfbHidOnHD3272uuOJ717FjR/PII4/YjcPp06evuly+d65R3PHLzs62G7fk5GQTHx9vQkJCTEZGRoHL5btXfFcbO2OMWbhwoUlISDC//PKL2bNnjxk2bJgJDQ21W89s8zyjuGPHNs9zXPG9Y5vnOcUdP7Z51z9CegmpVKmSmT17dr6vJSYmGkm2H7jTp08bf39/8/HHH9v6HDt2zPj4+JhVq1YVuIw2bdqY4cOH27U1bNjQjBs3zgXvoOxyZuzy89///tcEBASYixcvFtgnLi7ONG/evLil4grOjl3Hjh3Nk08+6dQy+N65T3G/ey1atDBDhw696jL47rnH1cYuLS3NSDJff/21MYZtnrdxZuzywzbPc5wdO7Z53qW43z22edcXDnd3s5ycHH388cc6e/asYmNj8+2TlpYmi8WiihUrSpJ27Nihixcvqnv37rY+kZGRatKkibZs2ZLvPC5cuKAdO3bYTSNJ3bt3L3AaXF1Rxq6gPqGhofLz87vq8g4cOKDIyEhFR0drwIABOnToUHHKL9OKM3YLFy5UlSpV1LhxYz399NPKyMgocDl879zDFd+9HTt2aNeuXRo2bNg1l8d3z3WuNXYXLlzQe++9J6vVqubNm0tim+ctijJ2+WGbV/KKM3Zs8zzPFd89tnnXIU//L8H1avfu3SYkJMT4+voaq9Vqvvrqq3z7nT9/3rRq1co8+OCDtraFCxeagIAAh77dunUzf//73/Odz7Fjx4wks3nzZrv2F1980dx4443FeCdlT3HG7konT540tWvXNs8+++xVl7lixQrz6aefmt27d5uEhATTsWNHEx4ebk6ePFms91LWFHfs3nvvPZOQkGD+7//+zyxatMjUqVPH3HbbbQUuj++da7nyuzdixAgTExNzzWXy3XONa43dsmXLTEhIiLFYLCYyMtIkJibaXmOb51nFGbsrsc0rWcUdO7Z5nuXK7x7bvOsPId1NsrKyzIEDB8z27dvNuHHjTJUqVczevXvt+ly4cMHcdddd5qabbjJpaWm29oL+YLntttvMo48+mu/y8n44t2zZYtf+wgsvmAYNGrjgHZUdxRm7y6WlpZm2bduanj17mgsXLjhVw5kzZ0x4eLh5/fXXi/w+yiJXjV2e77//3kgyO3bsyPd1vneu5arxO3funLFarea1115zuga+e0VzrbE7c+aMOXDggNm6dasZOnSoqVOnjjl+/Lgxhm2epxVn7C7HNq/kuWrs8rDNK1muGj+2edcnQnoJ6dq1q90egQsXLpi7777bNGvWzOF/r9auXWskmdTUVLv2Zs2ameeffz7f+WdlZRlfX1/z+eef27WPGjXK3HrrrS56F2WTM2OXJz093cTGxpquXbua8+fPF2m5t912m8N5X3BOUcbucrm5uQ7nyl6O7517FXX85s+fb/z9/Yt8MRy+e8V35dhd6YYbbjAvvfSSMYZtnrdxZuzysM3zDkUZu8uxzfOsoo4f27zrE+eklxBjjLKysiRdup1Qv379dODAAX399deqXLmyXd9WrVrJ399fCQkJtrbk5GTt2bNH7dq1y3f+AQEBatWqld00kpSQkFDgNCgcZ8ZOktLT09W9e3cFBARo6dKlCgoKcnqZWVlZ2r9/vyIiIopdf1nm7Nhdae/evbp48WKB48D3zr2KOn5z5sxRnz59VLVqVaeXyXfPNS4fu2u9zjbPuzgzdhLbPG/i7NhdiW2eZxV1/NjmXac8838D17fx48ebb7/91iQlJZndu3ebCRMmGB8fH7NmzRpz8eJF06dPH1OzZk2za9cuu1sgZGVl2eYxfPhwU7NmTfP111+bnTt3mi5dujjcjqZLly5m+vTptud5t8WYM2eO2bdvn3nqqadMSEiIOXz4cIm+/9KsuGOXnp5u2rZta5o2bWoOHjxo1+dqYzd27FjzzTffmEOHDplt27aZO++801SoUIGxc0Jxx+7gwYMmPj7ebN++3SQlJZmvvvrKNGzY0Nx0001870qAK343jTHmwIEDxmKxmJUrV+a7HL57rne1sTtz5owZP3682bp1qzl8+LDZsWOHGTZsmAkMDLTdasgYtnmeUtyxY5vnOcUdO7Z5nuWK301j2OZdzwjpbjB06FATFRVlAgICTNWqVU3Xrl3NmjVrjDHGJCUlGUn5PtavX2+bx/nz580TTzxhwsLCTLly5cydd95pjhw5YrecqKgoExcXZ9f2zjvv2JbdsmVLs2HDBne/3etKccdu/fr1BfZJSkqyLefKsevfv7+JiIgw/v7+JjIy0txzzz0O5+Li6oo7dkeOHDG33nqrCQsLMwEBAaZevXpm1KhR5tSpU3bL4XvnHq743TTm0h8+NWvWNDk5Ofkuh++e611t7M6fP2/69u1rIiMjTUBAgImIiDB9+vRxuAAS2zzPKO7Ysc3znOKOHds8z3LF76YxbPOuZxZjjHHvvnoAAAAAAFAYnJMOAAAAAICXIKQDAAAAAOAlCOkAAAAAAHgJQjoAAAAAAF6CkA4AAAAAgJcgpAMAAAAA4CUI6QAAAAAAeAlCOgAAAAAAXoKQDgBAKWKxWLRkyRK3L6dTp0566qmnCt3/m2++kcVi0enTp4u13CFDhujuu+8u1jwAACjNCOkAAHiJlJQUjRw5UnXr1lVgYKBq1aql3r17a+3atZ4u7ZratWun5ORkWa1WT5cCAECp5ufpAgAAgHT48GG1b99eFStW1JQpU9SsWTNdvHhRq1ev1uOPP67//e9/ni7xqgICAlS9enVPlwEAQKnHnnQAALzAY489JovFosTERP31r3/VjTfeqMaNG2vMmDHatm2bXd+TJ0+qb9++Cg4OVv369bV06VLbax988IEqVqxo13/JkiWyWCy25xMnTlSLFi304Ycfqk6dOrJarRowYIAyMjIKrG/VqlWyWq2aP39+vq9febh7Xh2rV69WTEyMypcvr549eyo5Odk2TU5OjsaMGaOKFSuqcuXK+uc//yljjN18jTGaMmWK6tatq3Llyql58+b69NNPba/ddttt6tmzp22606dPq3bt2nr22WcLfC8AAHgzQjoAAB6WmpqqVatW6fHHH1dISIjD61eG7vj4ePXr10+7d+9Wr1699OCDDyo1NdWpZf7yyy9asmSJli9fruXLl2vDhg16+eWX8+378ccfq1+/fpo/f74GDRpU6GWcO3dOr732mj788EN9++23OnLkiJ5++mnb66+//rrmzp2rOXPmaNOmTUpNTdUXX3xhN49//etfmjdvnmbOnKm9e/dq9OjReuihh7RhwwZZLBb95z//UWJiot566y1J0vDhwxUeHq6JEyc6tT4AAPAWHO4OAICHHTx4UMYYNWzYsFD9hwwZovvvv1+S9NJLL2n69OlKTExUz549C73M3NxcffDBB6pQoYIkaeDAgVq7dq1efPFFu34zZszQhAkT9OWXX6pz586Fnr8kXbx4UbNmzVK9evUkSU888YQmTZpke33atGkaP3687r33XknSrFmztHr1atvrZ8+e1dSpU7Vu3TrFxsZKkurWratNmzbp3XffVceOHVWjRg29++67GjhwoI4fP65ly5bphx9+kL+/v1O1AgDgLQjpAAB4WN6h2pcfkn41zZo1s/07JCREFSpU0IkTJ5xaZp06dWwBXZIiIiIc5vHZZ5/p+PHj2rRpk9q0aePU/CUpODjYFtCvXEZaWpqSk5Nt4VuS/Pz81Lp1a9v62LdvnzIzM9WtWze7+V64cEE33XST7fl9992nL774QpMnT9bMmTN14403Ol0rAADegpAOAICH1a9fXxaLRfv37y/U7ceu3EtssViUm5srSfLx8XE4r/vixYtOzSNPixYttHPnTs2bN09/+ctfCv2fCFdbxpW1XU1ePV999ZVq1Khh91pgYKDt3+fOndOOHTvk6+urAwcOOFUjAADehnPSAQDwsLCwMPXo0UPvvPOOzp496/C6M/cer1q1qjIyMuzms2vXriLVVa9ePa1fv15ffvmlRo4cWaR5FMRqtSoiIsLuonjZ2dnasWOH7XmjRo0UGBioI0eO6IYbbrB71KpVy9Zv7Nix8vHx0cqVK/XWW29p3bp1Lq0VAICSxJ50AAC8wIwZM9SuXTu1adNGkyZNUrNmzZSdna2EhATNnDlT+/fvL9R82rZtq+DgYE2YMEEjR45UYmKiPvjggyLXdeONN2r9+vXq1KmT/Pz8NG3atCLP60pPPvmkXn75ZdWvX18xMTGaOnWq3X9IVKhQQU8//bRGjx6t3Nxc3XLLLUpPT9eWLVtUvnx5DR48WF999ZXmzp2rrVu3qmXLlho3bpwGDx6s3bt3q1KlSi6rFQCAksKedAAAvEB0dLR27typzp07a+zYsWrSpIm6deumtWvXaubMmYWeT1hYmBYsWKAVK1aoadOmWrRoUbGvdN6gQQOtW7dOixYt0tixY4s1r8uNHTtWgwYN0pAhQxQbG6sKFSqob9++dn3+/e9/6/nnn9fkyZMVExOjHj16aNmyZYqOjtYff/yhYcOGaeLEiWrZsqUkKS4uTpGRkRo+fLjL6gQAoCRZjDMnhwEAAAAAALdhTzoAAAAAAF6CkA4AAAAAgJcgpAMAAAAA4CUI6QAAAAAAeAlCOgAAAAAAXoKQDgAAAACAlyCkAwAAAADgJQjpAAAAAAB4CUI6AAAAAABegpAOAAAAAICXIKQDAAAAAOAl/j9H1t0w6eKawAAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 1200x500 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "plot_relevance_scores(chunk_values, 320, 340)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "What's interesting to note here is that only 7 of these 20 chunks have been marked as relevant by our reranker. And many of the non-relevant chunks are sandwiched between relevant chunks. Looking at the span of 323-336, exactly half of those chunks are marked as relevant and the other half are marked as not relevant.\n",
    "\n",
    "### Let's see what this part of the document contains"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def print_document_segment(chunks: List[str], start_index: int, end_index: int):\n",
    "    \"\"\"\n",
    "    Print the text content of a segment of the document\n",
    "\n",
    "    Args:\n",
    "        chunks (list): List of text chunks\n",
    "        start_index (int): Start index of the segment\n",
    "        end_index (int): End index of the segment (not inclusive)\n",
    "\n",
    "    Returns:\n",
    "        None\n",
    "\n",
    "    Prints:\n",
    "        The text content of the specified segment of the document\n",
    "    \"\"\"\n",
    "    for i in range(start_index, end_index):\n",
    "        print(f\"\\nChunk {i}\")\n",
    "        print(chunks[i])\n",
    "\n",
    "print_document_segment(chunks, 320, 340)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can see that the Consolidated Statement of Income starts in chunk 323, and everything up to chunk 333 contains consolidated financial statements, which is what we're looking for. So every chunk in that range is indeed relevant and necessary for our query, yet only about half of those chunks were marked as relevant by the reranker. So in addition to providing more complete context to the LLM, by combining these clusters of relevant chunks we actually find important chunks that otherwise would have been ignored."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What can we do with these clusters of relevant chunks?\n",
    "The core idea is that clusters of relevant chunks, in their original contiguous form, provide much better context to the LLM than individual chunks can. Now for the hard part: how do we actually identify these clusters?\n",
    "\n",
    "If we can calculate chunk values in such a way that the value of a segment is just the sum of the values of its constituent chunks, then finding the optimal segment is a version of the maximum subarray problem, for which a solution can be found relatively easily. How do we define chunk values in such a way? We'll start with the idea that highly relevant chunks are good, and irrelevant chunks are bad. We already have a good measure of chunk relevance, on a scale of 0-1, so all we need to do is subtract a constant threshold value from it. This will turn the chunk value of irrelevant chunks to a negative number, while keeping the values of relevant chunks positive. We call this the `irrelevant_chunk_penalty`. A value around 0.2 seems to work well empirically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 37,
   "metadata": {},
   "outputs": [],
   "source": [
    "def get_best_segments(relevance_values: list, max_length: int, overall_max_length: int, minimum_value: float):\n",
    "    \"\"\"\n",
    "    This function takes the chunk relevance values and then runs an optimization algorithm to find the best segments. In more technical terms, it solves a constrained version of the maximum sum subarray problem.\n",
    "\n",
    "    Note: this is a simplified implementation intended for demonstration purposes. A more sophisticated implementation would be needed for production use and is available in the dsRAG library.\n",
    "\n",
    "    Args:\n",
    "        relevance_values (list): a list of relevance values for each chunk of a document\n",
    "        max_length (int): the maximum length of a single segment (measured in number of chunks)\n",
    "        overall_max_length (int): the maximum length of all segments (measured in number of chunks)\n",
    "        minimum_value (float): the minimum value that a segment must have to be considered\n",
    "\n",
    "    Returns:\n",
    "        best_segments (list): a list of tuples (start, end) that represent the indices of the best segments (the end index is non-inclusive) in the document\n",
    "        scores (list): a list of the scores for each of the best segments\n",
    "    \"\"\"\n",
    "    best_segments = []\n",
    "    scores = []\n",
    "    total_length = 0\n",
    "    while total_length < overall_max_length:\n",
    "        # find the best remaining segment\n",
    "        best_segment = None\n",
    "        best_value = -1000\n",
    "        for start in range(len(relevance_values)):\n",
    "            # skip over negative value starting points\n",
    "            if relevance_values[start] < 0:\n",
    "                continue\n",
    "            for end in range(start+1, min(start+max_length+1, len(relevance_values)+1)):\n",
    "                # skip over negative value ending points\n",
    "                if relevance_values[end-1] < 0:\n",
    "                    continue\n",
    "                # check if this segment overlaps with any of the best segments and skip if it does\n",
    "                if any(start < seg_end and end > seg_start for seg_start, seg_end in best_segments):\n",
    "                    continue\n",
    "                # check if this segment would push us over the overall max length and skip if it would\n",
    "                if total_length + end - start > overall_max_length:\n",
    "                    continue\n",
    "                \n",
    "                # define segment value as the sum of the relevance values of its chunks\n",
    "                segment_value = sum(relevance_values[start:end])\n",
    "                if segment_value > best_value:\n",
    "                    best_value = segment_value\n",
    "                    best_segment = (start, end)\n",
    "        \n",
    "        # if we didn't find a valid segment then we're done\n",
    "        if best_segment is None or best_value < minimum_value:\n",
    "            break\n",
    "\n",
    "        # otherwise, add the segment to the list of best segments\n",
    "        best_segments.append(best_segment)\n",
    "        scores.append(best_value)\n",
    "        total_length += best_segment[1] - best_segment[0]\n",
    "    \n",
    "    return best_segments, scores"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Best segment indices\n",
      "[(323, 337), (226, 231), (448, 453), (312, 313)]\n",
      "\n",
      "Best segment scores\n",
      "[2.5559905778741827, 1.6569259433941705, 0.7325434206345869, 0.7318070628222588]\n",
      "\n"
     ]
    }
   ],
   "source": [
    "# define some parameters and constraints for the optimization\n",
    "irrelevant_chunk_penalty = 0.2 # empirically, something around 0.2 works well; lower values bias towards longer segments\n",
    "max_length = 20\n",
    "overall_max_length = 30\n",
    "minimum_value = 0.7\n",
    "\n",
    "# subtract constant threshold value from chunk relevance values\n",
    "relevance_values = [v - irrelevant_chunk_penalty for v in chunk_values] \n",
    "\n",
    "# run the optimization\n",
    "best_segments, scores = get_best_segments(relevance_values, max_length, overall_max_length, minimum_value)\n",
    "\n",
    "# print results\n",
    "print (\"Best segment indices\")\n",
    "print (best_segments) # indices of the best segments, with the end index non-inclusive\n",
    "print ()\n",
    "print (\"Best segment scores\")\n",
    "print (scores)\n",
    "print ()"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The first segment given by the optimization algorithm is chunks 323-336. Looking at the chunks manually, we decided that 323-333 was the ideal segment, so we got a few bonus chunks that we don't really need, but overall this is going to be a great piece of context for the LLM to work with. We also identified some shorter segments from other parts of the document that we could provide to the LLM as well.\n",
    "\n",
    "### What if the answer is contained in a single chunk?\n",
    "In the case where only a single chunk, or a few isolated chunks, are relevant to the query, we don't want to create large segments out of them. We just want to return those specific chunks. RSE can handle that scenario well too. Since there are no clusters of relevant chunks, it basically reduces to standard top-k retrieval in that case. We'll leave it as an exercise to the reader to see what happens to the chunk relevance plot and the resulting best segments for queries like this."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Eval results\n",
    "\n",
    "### KITE\n",
    "We evaluated RSE on an end-to-end RAG benchmark we created, called [KITE](https://github.com/D-Star-AI/KITE) (Knowledge-Intensive Task Evaluation).\n",
    "\n",
    "KITE currently consists of 4 datasets and a total of 50 questions.\n",
    "- **AI Papers** - ~100 academic papers about AI and RAG, downloaded from arXiv in PDF form.\n",
    "- **BVP Cloud 10-Ks** - 10-Ks for all companies in the Bessemer Cloud Index (~70 of them), in PDF form.\n",
    "- **Sourcegraph Company Handbook** - ~800 markdown files, with their original directory structure, downloaded from Sourcegraph's publicly accessible company handbook GitHub [page](https://github.com/sourcegraph/handbook/tree/main/content).\n",
    "- **Supreme Court Opinions** - All Supreme Court opinions from Term Year 2022 (delivered from January '23 to June '23), downloaded from the official Supreme Court [website](https://www.supremecourt.gov/opinions/slipopinion/22) in PDF form.\n",
    "\n",
    "Ground truth answers are included with each sample. Most samples also include grading rubrics. Grading is done on a scale of 0-10 for each question, with a strong LLM doing the grading.\n",
    "\n",
    "We compare RSE with standard Top-k retrieval (k=20). All other parameters remain the same between the two configurations. We use the Cohere 3 reranker, and we use GPT-4o for response generation. The average length of the relevant knowledge string is roughly the same between the two configurations, so cost and latency are similar.\n",
    "\n",
    "|                         | Top-k    | RSE    |\n",
    "|-------------------------|----------|--------|\n",
    "| AI Papers               | 4.5      | 7.9    |\n",
    "| BVP Cloud               | 2.6      | 4.4    |\n",
    "| Sourcegraph             | 5.7      | 6.6    |\n",
    "| Supreme Court Opinions  | 6.1      | 8.0    |\n",
    "| **Average**             | 4.72     | 6.73   |\n",
    "\n",
    "We can see that RSE leads to an improvement in performance on each of the four datasets. The overall average score increases from 4.72 -> 6.73, a 42.6% increase.\n",
    "\n",
    "### FinanceBench\n",
    "We've also evaluated RSE on FinanceBench, where it contributed to a score of 83%, compared to a baseline score of 19%. For that benchmark, we tested contextual chunk headers (CCH) and RSE jointly, so we can't say exactly how much RSE contributed to that result. But the combination of CCH and RSE clearly leads to substantial accuracy improvements on FinanceBench."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "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 (main, Aug 25 2022, 18:29:29) \n[Clang 12.0.0 ]"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "44d0561a9d33f22b2e67e0485c48036e39d1c698628b030a9859974b559ff507"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}