{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "8ab7f3c7",
   "metadata": {},
   "source": [
    "# 03 · LangChain y LlamaIndex\n",
    "\n",
    "Los módulos 01 y 02 construyeron la recuperación a mano, que es la mejor manera de entenderla. En la práctica\n",
    "la mayoría de los equipos recurren a un **framework** que empaqueta las piezas habituales (objetos documento,\n",
    "divisores de texto, almacenes vectoriales, recuperadores, cadenas). Dos dominan: **LangChain**, un conjunto de\n",
    "herramientas general para componer aplicaciones con LLM, y **LlamaIndex**, centrado en indexar y consultar tus\n",
    "propios datos. Este módulo pasa el *mismo* corpus, el *mismo* modelo de embeddings y las *mismas* preguntas por\n",
    "los dos, junto a nuestras pocas líneas de NumPy, y mide qué ganas y qué pagas realmente.\n",
    "\n",
    "En proyectos reales de este portafolio, un agente de analítica de parques eólicos usó **LangChain con FAISS** sobre\n",
    "registros de incidencias en texto libre y **LlamaIndex** sobre especificaciones estructuradas de aerogeneradores,\n",
    "como dos pilas de recuperación independientes detrás de un único agente. La comparación de abajo explica por qué\n",
    "es una elección razonable y también por qué no es la única.\n",
    "\n",
    "**Aprenderás**\n",
    "1. El vocabulario que comparten ambos frameworks: documento, nodo/trozo, embedding, almacén vectorial, recuperador, cadena\n",
    "2. Un pipeline de LangChain: `Document`, divisor, almacén FAISS, recuperador y una cadena LCEL\n",
    "3. Un pipeline de LlamaIndex: `Document`, analizador de nodos, `VectorStoreIndex`, recuperador y motor de consultas\n",
    "4. Una comparación justa: líneas de código, calidad de recuperación, tiempo de importación y tamaño de instalación, todo medido\n",
    "5. Qué abstrae cada framework y cuándo prescindir de ambos"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "450a5e23",
   "metadata": {},
   "source": [
    "## 1. Los mismos ingredientes para los tres\n",
    "\n",
    "Para comparar frameworks con justicia, todo lo que no sea el framework debe ser idéntico. Usamos el manual de\n",
    "Harbourview, las preguntas del módulo 02 (14 originales y 10 paráfrasis, definidas aquí mismo) y el **mismo\n",
    "modelo de embeddings**, `all-MiniLM-L6-v2`, envuelto una vez para cada framework. Si los resultados de recuperación\n",
    "difieren, la diferencia viene del framework y no del modelo."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a6ac1ca",
   "metadata": {},
   "source": [
    "### Imagen: los mismos cinco ingredientes en tres envoltorios\n",
    "\n",
    "Toda canalización de recuperación necesita las mismas piezas. Las columnas son las piezas y las filas, quién las\n",
    "aporta. El vocabulario cambia de una fila a otra; la idea no, y por eso las tres dan la misma recuperación cuando\n",
    "el modelo de embeddings se mantiene fijo."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "ed214d71",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:38.643736Z",
     "iopub.status.busy": "2026-11-17T21:30:38.643388Z",
     "iopub.status.idle": "2026-11-17T21:30:38.713497Z",
     "shell.execute_reply": "2026-11-17T21:30:38.711425Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 800 336\" width=\"100%\" font-family=\"Helvetica, Arial, sans-serif\"><defs><marker id=\"ah\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" markerWidth=\"7\" markerHeight=\"7\" orient=\"auto-start-reverse\"><path d=\"M0,0 L10,5 L0,10 z\" fill=\"#555\"/></marker></defs><rect width=\"800\" height=\"336\" rx=\"12\" fill=\"#fbfbf8\" stroke=\"#d8d8cf\"/><text x=\"400.0\" y=\"26\" text-anchor=\"middle\" font-size=\"15\" font-weight=\"700\" fill=\"#222\">Los mismos ingredientes, tres vocabularios</text><rect x=\"146\" y=\"44\" width=\"128\" height=\"34\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"210.0\" y=\"65.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">Documento</text><rect x=\"280\" y=\"44\" width=\"128\" height=\"34\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"344.0\" y=\"65.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">Trozos</text><rect x=\"414\" y=\"44\" width=\"128\" height=\"34\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"478.0\" y=\"65.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">Embedding</text><rect x=\"548\" y=\"44\" width=\"128\" height=\"34\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"612.0\" y=\"65.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">Almacén vectorial</text><rect x=\"682\" y=\"44\" width=\"100\" height=\"34\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"732.0\" y=\"65.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">Recuperar</text><rect x=\"18\" y=\"92\" width=\"122\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"79.0\" y=\"127.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">LangChain</text><rect x=\"146\" y=\"92\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"210.0\" y=\"110.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Document</text><text x=\"210.0\" y=\"127.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">page_content +</text><text x=\"210.0\" y=\"144.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">metadata</text><rect x=\"280\" y=\"92\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"344.0\" y=\"119.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Divisor de texto</text><text x=\"344.0\" y=\"136.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">(recursivo)</text><rect x=\"414\" y=\"92\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"478.0\" y=\"110.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Embeddings</text><text x=\"478.0\" y=\"127.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">embed_documents</text><text x=\"478.0\" y=\"144.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">embed_query</text><rect x=\"548\" y=\"92\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"612.0\" y=\"119.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">FAISS</text><text x=\"612.0\" y=\"136.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">VectorStore</text><rect x=\"682\" y=\"92\" width=\"100\" height=\"62\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"732.0\" y=\"119.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">as_retriever</text><text x=\"732.0\" y=\"136.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">cadena LCEL</text><rect x=\"18\" y=\"164\" width=\"122\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"79.0\" y=\"199.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">LlamaIndex</text><rect x=\"146\" y=\"164\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"210.0\" y=\"191.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Document</text><text x=\"210.0\" y=\"208.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">texto + metadatos</text><rect x=\"280\" y=\"164\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"344.0\" y=\"182.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Node parser</text><text x=\"344.0\" y=\"199.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">los nodos enlazan</text><text x=\"344.0\" y=\"216.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">con su fuente</text><rect x=\"414\" y=\"164\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"478.0\" y=\"191.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">BaseEmbedding</text><text x=\"478.0\" y=\"208.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">el mismo MiniLM</text><rect x=\"548\" y=\"164\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"612.0\" y=\"191.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">VectorStoreIndex</text><text x=\"612.0\" y=\"208.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">en memoria</text><rect x=\"682\" y=\"164\" width=\"100\" height=\"62\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"732.0\" y=\"191.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">retriever</text><text x=\"732.0\" y=\"208.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">query engine</text><rect x=\"18\" y=\"236\" width=\"122\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"79.0\" y=\"271.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">NumPy propio</text><rect x=\"146\" y=\"236\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"210.0\" y=\"254.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">lista de</text><text x=\"210.0\" y=\"271.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">pasajes</text><text x=\"210.0\" y=\"288.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">ids + textos</text><rect x=\"280\" y=\"236\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"344.0\" y=\"263.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">un pasaje</text><text x=\"344.0\" y=\"280.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">es un trozo</text><rect x=\"414\" y=\"236\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"478.0\" y=\"254.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">matriz E</text><text x=\"478.0\" y=\"271.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">una fila MiniLM</text><text x=\"478.0\" y=\"288.5\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">por pasaje</text><rect x=\"548\" y=\"236\" width=\"128\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"612.0\" y=\"263.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">producto escalar</text><text x=\"612.0\" y=\"280.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">E @ pregunta</text><rect x=\"682\" y=\"236\" width=\"100\" height=\"62\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"732.0\" y=\"263.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">argsort</text><text x=\"732.0\" y=\"280.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">puntuaciones</text><text x=\"400\" y=\"322\" text-anchor=\"middle\" font-size=\"12\" fill=\"#333\">Mismos 22 pasajes, mismo modelo de embeddings, mismas preguntas: cualquier diferencia viene del framework.</text></svg>"
      ],
      "text/plain": [
       "<IPython.core.display.SVG object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from IPython.display import SVG, display\n",
    "import html as _h\n",
    "\n",
    "_COL = {  # fill, stroke  (light cards with dark text: readable in light and dark themes)\n",
    "    \"gold\": (\"#fff4c2\", \"#b89d28\"), \"blue\": (\"#dbeafe\", \"#3b82f6\"), \"green\": (\"#dcfce7\", \"#16a34a\"),\n",
    "    \"red\": (\"#fee2e2\", \"#dc2626\"), \"grey\": (\"#f1f1f4\", \"#8a8aa0\"), \"violet\": (\"#ede9fe\", \"#7c3aed\"),\n",
    "}\n",
    "\n",
    "def diagram(width, height, items, title=None):\n",
    "    # items: (\"box\", x, y, w, h, \"text\\nmore text\", colour) | (\"arrow\", x1, y1, x2, y2, \"label\") |\n",
    "    #        (\"text\", x, y, \"text\", size, \"start|middle|end\") | (\"note\", x, y, w, h, \"text\")\n",
    "    out = [f'<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 {width} {height}\" width=\"100%\" '\n",
    "           f'font-family=\"Helvetica, Arial, sans-serif\">',\n",
    "           '<defs><marker id=\"ah\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" markerWidth=\"7\" markerHeight=\"7\" '\n",
    "           'orient=\"auto-start-reverse\"><path d=\"M0,0 L10,5 L0,10 z\" fill=\"#555\"/></marker></defs>',\n",
    "           f'<rect width=\"{width}\" height=\"{height}\" rx=\"12\" fill=\"#fbfbf8\" stroke=\"#d8d8cf\"/>']\n",
    "    if title:\n",
    "        out.append(f'<text x=\"{width / 2}\" y=\"26\" text-anchor=\"middle\" font-size=\"15\" font-weight=\"700\" fill=\"#222\">{_h.escape(title)}</text>')\n",
    "    for it in items:\n",
    "        kind = it[0]\n",
    "        if kind == \"box\":\n",
    "            _, x, y, w, h, text, col = it\n",
    "            fill, stroke = _COL[col]\n",
    "            out.append(f'<rect x=\"{x}\" y=\"{y}\" width=\"{w}\" height=\"{h}\" rx=\"9\" fill=\"{fill}\" stroke=\"{stroke}\" stroke-width=\"1.6\"/>')\n",
    "            lines = text.split(\"\\n\")\n",
    "            y0 = y + h / 2 - (len(lines) - 1) * 8.5 + 4.5\n",
    "            for k, ln in enumerate(lines):\n",
    "                bold = ' font-weight=\"700\"' if k == 0 and len(lines) > 1 else \"\"\n",
    "                out.append(f'<text x=\"{x + w / 2}\" y=\"{y0 + k * 17}\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\"{bold}>{_h.escape(ln)}</text>')\n",
    "        elif kind == \"arrow\":\n",
    "            _, x1, y1, x2, y2, label = it\n",
    "            out.append(f'<line x1=\"{x1}\" y1=\"{y1}\" x2=\"{x2}\" y2=\"{y2}\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/>')\n",
    "            if label:\n",
    "                out.append(f'<text x=\"{(x1 + x2) / 2}\" y=\"{(y1 + y2) / 2 - 6}\" text-anchor=\"middle\" font-size=\"11.5\" fill=\"#555\">{_h.escape(label)}</text>')\n",
    "        elif kind == \"text\":\n",
    "            _, x, y, text, size, anchor = it\n",
    "            for k, ln in enumerate(text.split(\"\\n\")):\n",
    "                out.append(f'<text x=\"{x}\" y=\"{y + k * (size + 4)}\" text-anchor=\"{anchor}\" font-size=\"{size}\" fill=\"#333\">{_h.escape(ln)}</text>')\n",
    "        elif kind == \"note\":\n",
    "            _, x, y, w, h, text = it\n",
    "            out.append(f'<rect x=\"{x}\" y=\"{y}\" width=\"{w}\" height=\"{h}\" rx=\"6\" fill=\"none\" stroke=\"#b89d28\" stroke-dasharray=\"5 4\"/>')\n",
    "            for k, ln in enumerate(text.split(\"\\n\")):\n",
    "                out.append(f'<text x=\"{x + 10}\" y=\"{y + 20 + k * 16}\" font-size=\"12\" fill=\"#444\">{_h.escape(ln)}</text>')\n",
    "    out.append(\"</svg>\")\n",
    "    display(SVG(\"\".join(out)))\n",
    "\n",
    "\n",
    "diagram(800, 336, [\n",
    "    (\"box\", 146, 44, 128, 34, \"Documento\", \"grey\"),\n",
    "    (\"box\", 280, 44, 128, 34, \"Trozos\", \"grey\"),\n",
    "    (\"box\", 414, 44, 128, 34, \"Embedding\", \"grey\"),\n",
    "    (\"box\", 548, 44, 128, 34, \"Almacén vectorial\", \"grey\"),\n",
    "    (\"box\", 682, 44, 100, 34, \"Recuperar\", \"grey\"),\n",
    "    (\"box\", 18, 92, 122, 62, \"LangChain\", \"blue\"),\n",
    "    (\"box\", 146, 92, 128, 62, \"Document\\npage_content +\\nmetadata\", \"blue\"),\n",
    "    (\"box\", 280, 92, 128, 62, \"Divisor de texto\\n(recursivo)\", \"blue\"),\n",
    "    (\"box\", 414, 92, 128, 62, \"Embeddings\\nembed_documents\\nembed_query\", \"blue\"),\n",
    "    (\"box\", 548, 92, 128, 62, \"FAISS\\nVectorStore\", \"blue\"),\n",
    "    (\"box\", 682, 92, 100, 62, \"as_retriever\\ncadena LCEL\", \"blue\"),\n",
    "    (\"box\", 18, 164, 122, 62, \"LlamaIndex\", \"green\"),\n",
    "    (\"box\", 146, 164, 128, 62, \"Document\\ntexto + metadatos\", \"green\"),\n",
    "    (\"box\", 280, 164, 128, 62, \"Node parser\\nlos nodos enlazan\\ncon su fuente\", \"green\"),\n",
    "    (\"box\", 414, 164, 128, 62, \"BaseEmbedding\\nel mismo MiniLM\", \"green\"),\n",
    "    (\"box\", 548, 164, 128, 62, \"VectorStoreIndex\\nen memoria\", \"green\"),\n",
    "    (\"box\", 682, 164, 100, 62, \"retriever\\nquery engine\", \"green\"),\n",
    "    (\"box\", 18, 236, 122, 62, \"NumPy propio\", \"gold\"),\n",
    "    (\"box\", 146, 236, 128, 62, \"lista de\\npasajes\\nids + textos\", \"gold\"),\n",
    "    (\"box\", 280, 236, 128, 62, \"un pasaje\\nes un trozo\", \"gold\"),\n",
    "    (\"box\", 414, 236, 128, 62, \"matriz E\\nuna fila MiniLM\\npor pasaje\", \"gold\"),\n",
    "    (\"box\", 548, 236, 128, 62, \"producto escalar\\nE @ pregunta\", \"gold\"),\n",
    "    (\"box\", 682, 236, 100, 62, \"argsort\\npuntuaciones\", \"gold\"),\n",
    "    (\"text\", 400, 322, \"Mismos 22 pasajes, mismo modelo de embeddings, mismas preguntas: cualquier diferencia viene del framework.\", 12, \"middle\"),\n",
    "], \"Los mismos ingredientes, tres vocabularios\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "8ea8f616",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:38.718135Z",
     "iopub.status.busy": "2026-11-17T21:30:38.717816Z",
     "iopub.status.idle": "2026-11-17T21:30:38.731716Z",
     "shell.execute_reply": "2026-11-17T21:30:38.729682Z"
    }
   },
   "outputs": [],
   "source": [
    "# El manual de Harbourview: 22 pasajes, ficticios, escritos para este curso\n",
    "PASSAGES = [\n",
    "    [\"p01\", \"Safety / Access\", \"Technicians must hold a valid GWO Basic Safety Training certificate before boarding a crew transfer vessel. Certificates are checked at the harbour gate and expire after two years.\"],\n",
    "    [\"p02\", \"Safety / Weather limits\", \"Crew transfer vessels do not sail when the significant wave height exceeds 1.5 m or the wind speed at the harbour exceeds 20 m/s. The duty coordinator decides at 06:00 and may cancel later.\"],\n",
    "    [\"p03\", \"Safety / Lone working\", \"Lone working inside a nacelle is forbidden. Every task inside a turbine needs at least two people, and both must carry a personal locator beacon.\"],\n",
    "    [\"p04\", \"Turbines / Specification\", \"Each of the 40 turbines is rated at 8.0 MW with a rotor diameter of 164 m. Cut-in wind speed is 3 m/s, rated speed is 12.5 m/s and cut-out speed is 25 m/s.\"],\n",
    "    [\"p05\", \"Turbines / Naming\", \"Turbines are named HV01 to HV40, numbered from the western edge of the array. The offshore substation is OSS1, in the centre.\"],\n",
    "    [\"p06\", \"Maintenance / Schedule\", \"Every turbine gets a planned service once a year between April and September. The service takes two technicians about two days, plus weather delays.\"],\n",
    "    [\"p07\", \"Maintenance / Gearbox oil\", \"Gearbox oil is sampled every six months. If the particle count exceeds ISO 4406 code 18/16/13, a filter change is scheduled within 14 days.\"],\n",
    "    [\"p08\", \"Maintenance / Blade inspection\", \"Blades are inspected by drone every 12 months and after any lightning alarm. Leading-edge erosion above grade 3 is repaired in the next planned service.\"],\n",
    "    [\"p09\", \"Faults / Alarm levels\", \"Alarms have three levels. Level 1 is informational. Level 2 needs a remote check within 4 hours. Level 3 stops the turbine and needs a site visit within 24 hours when the weather allows.\"],\n",
    "    [\"p10\", \"Faults / Pitch system\", \"A pitch system fault (code PF-203) usually means a low accumulator pressure. Reset it remotely once. If it returns within 48 hours, send a crew to replace the hydraulic accumulator.\"],\n",
    "    [\"p11\", \"Faults / Yaw misalignment\", \"A yaw error above 8 degrees for more than 10 minutes raises alarm YW-110. Persistent errors point to a faulty wind vane: the vane is recalibrated, then replaced if the error remains.\"],\n",
    "    [\"p12\", \"Faults / Grid loss\", \"On loss of grid connection the turbines stop and the converters isolate. Restart is allowed only when the grid operator confirms voltage within 5% of nominal for 10 minutes.\"],\n",
    "    [\"p13\", \"Environment / Marine mammals\", \"Piling and heavy cable work pause when a marine mammal is sighted within 500 m. Work resumes after 30 minutes without a sighting.\"],\n",
    "    [\"p14\", \"Environment / Bird collision\", \"Between October and March, turbines HV01 to HV08 are curtailed at night during the peak migration periods announced by the ornithology team.\"],\n",
    "    [\"p15\", \"Environment / Waste\", \"Used oil, filters and composite offcuts are brought ashore and logged in the waste register. Nothing is discharged at sea.\"],\n",
    "    [\"p16\", \"Logistics / Spare parts\", \"The harbour warehouse keeps the critical spares: two pitch accumulators, four wind vanes and a spare converter module. Reorder when stock falls below one unit.\"],\n",
    "    [\"p17\", \"Logistics / Helicopter\", \"A helicopter is used only for medical evacuation and for urgent Level 3 visits when vessels cannot sail. Booking goes through the duty coordinator.\"],\n",
    "    [\"p18\", \"Contacts / Duty coordinator\", \"The duty coordinator is reachable 24 hours a day on the control room line. Out-of-hours safety incidents are reported there first.\"],\n",
    "    [\"p19\", \"Reporting / Incidents\", \"Any injury or near miss is reported within one hour and a written report is filed within 24 hours. Environmental incidents follow the same deadlines.\"],\n",
    "    [\"p20\", \"Reporting / Performance\", \"Availability is reported monthly. The target is 97% time-based availability, counting weather downtime as available.\"],\n",
    "    [\"p21\", \"Grid / Export\", \"Power is exported at 66 kV through two cables to the onshore substation. The export limit agreed with the grid operator is 300 MW.\"],\n",
    "    [\"p22\", \"Training / Induction\", \"New staff complete a two-day induction covering the handbook, emergency drills and the sea survival course before their first transfer.\"],\n",
    "]\n",
    "\n",
    "# (id, pregunta, pasaje correcto, dato que debe contener la respuesta); None = el manual no lo dice\n",
    "QUESTIONS = [\n",
    "    [\"q01\", \"What wave height stops the crew boats from sailing?\", \"p02\", \"1.5 m\"],\n",
    "    [\"q02\", \"How often is the gearbox oil sampled?\", \"p07\", \"six months\"],\n",
    "    [\"q03\", \"Who may work alone inside a nacelle?\", \"p03\", \"forbidden\"],\n",
    "    [\"q04\", \"What is the rotor diameter of a turbine?\", \"p04\", \"164 m\"],\n",
    "    [\"q05\", \"What do I do if the pitch fault comes back after a reset?\", \"p10\", \"replace the hydraulic accumulator\"],\n",
    "    [\"q06\", \"When must a Level 3 alarm be attended on site?\", \"p09\", \"24 hours\"],\n",
    "    [\"q07\", \"How soon must an injury be reported?\", \"p19\", \"one hour\"],\n",
    "    [\"q08\", \"What is the largest amount of power the farm is allowed to send ashore?\", \"p21\", \"300 MW\"],\n",
    "    [\"q09\", \"Which turbines are switched off at night in the autumn to protect birds?\", \"p14\", \"HV01 to HV08\"],\n",
    "    [\"q10\", \"How many spare wind vanes are kept in stock?\", \"p16\", \"four wind vanes\"],\n",
    "    [\"q11\", \"What qualification do I need before getting on the boat?\", \"p01\", \"GWO Basic Safety Training\"],\n",
    "    [\"q12\", \"When can the turbines restart after a blackout?\", \"p12\", \"10 minutes\"],\n",
    "    [\"q13\", \"When can a helicopter be used?\", \"p17\", \"medical evacuation\"],\n",
    "    [\"q14\", \"What happens when a dolphin is seen near the piling work?\", \"p13\", \"pause\"],\n",
    "    [\"q15\", \"What is the price of electricity per MWh?\", None, None],\n",
    "    [\"q16\", \"Who is the chief executive of the operating company?\", None, None],\n",
    "]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f4261cf1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:38.735755Z",
     "iopub.status.busy": "2026-11-17T21:30:38.735472Z",
     "iopub.status.idle": "2026-11-17T21:30:51.472365Z",
     "shell.execute_reply": "2026-11-17T21:30:51.470236Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "22 passages, 24 questions with a known gold passage\n"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\r",
      "Loading weights:   0%|          | 0/103 [00:00<?, ?it/s]"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\r",
      "Loading weights: 100%|██████████| 103/103 [00:00<00:00, 3353.46it/s]"
     ]
    },
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "\n"
     ]
    }
   ],
   "source": [
    "import re, time, math, inspect, subprocess, sys, warnings\n",
    "import numpy as np\n",
    "warnings.filterwarnings(\"ignore\")\n",
    "\n",
    "PARAPHRASES = [\n",
    "    (\"r01\", \"Are boats cancelled when the sea is too rough?\", \"p02\"),\n",
    "    (\"r02\", \"Can I go up the tower alone to fix something?\", \"p03\"),\n",
    "    (\"r03\", \"How big are the blades?\", \"p04\"),\n",
    "    (\"r04\", \"Who do I call in the middle of the night about an accident?\", \"p18\"),\n",
    "    (\"r05\", \"What if the oil in the gearbox gets dirty?\", \"p07\"),\n",
    "    (\"r06\", \"Do you stop work when whales or seals swim close?\", \"p13\"),\n",
    "    (\"r07\", \"How much spare equipment is kept on shore?\", \"p16\"),\n",
    "    (\"r08\", \"Is the farm allowed to produce at full output?\", \"p21\"),\n",
    "    (\"r09\", \"What should new colleagues do before their first trip?\", \"p22\"),\n",
    "    (\"r10\", \"How should rubbish and old oil be handled?\", \"p15\"),\n",
    "]\n",
    "BATTERY = [(q[0], q[1], q[2]) for q in QUESTIONS if q[2]] + PARAPHRASES      # 24 preguntas, todas con respuesta\n",
    "ids = [p[0] for p in PASSAGES]\n",
    "texts = [f\"{section}. {text}\" for _, section, text in PASSAGES]\n",
    "print(len(PASSAGES), \"passages,\", len(BATTERY), \"questions with a known gold passage\")\n",
    "\n",
    "from sentence_transformers import SentenceTransformer\n",
    "minilm = SentenceTransformer(\"sentence-transformers/all-MiniLM-L6-v2\", device=\"cpu\")\n",
    "\n",
    "def evaluate(search):\n",
    "    # search(pregunta) -> lista de ids de pasaje, el mejor primero. Devuelve hit@1, hit@3 y MRR sobre la batería\n",
    "    ranks = []\n",
    "    for _, question, gold in BATTERY:\n",
    "        order = search(question)\n",
    "        ranks.append(order.index(gold) + 1 if gold in order else len(ids) + 1)\n",
    "    r = np.array(ranks)\n",
    "    return dict(hit1=float((r == 1).mean()), hit3=float((r <= 3).mean()), mrr=float((1 / r).mean()))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "569ed973",
   "metadata": {},
   "source": [
    "## 2. Nuestro propio recuperador (la referencia a superar)\n",
    "\n",
    "El módulo 02 en una docena de líneas: calcula los embeddings de los pasajes una vez, el de la pregunta, y ordena\n",
    "por producto escalar. Cualquier framework tiene que justificarse frente a esto."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0eb168f4",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:51.476431Z",
     "iopub.status.busy": "2026-11-17T21:30:51.475885Z",
     "iopub.status.idle": "2026-11-17T21:30:52.038372Z",
     "shell.execute_reply": "2026-11-17T21:30:52.036207Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "construido en 0.53 s\n",
      "['p02', 'p13', 'p15']\n"
     ]
    }
   ],
   "source": [
    "def build_own():\n",
    "    E = minilm.encode(texts, normalize_embeddings=True)\n",
    "    def search(question, k=len(ids)):\n",
    "        scores = E @ minilm.encode(question, normalize_embeddings=True)\n",
    "        return [ids[i] for i in np.argsort(-scores)[:k]]\n",
    "    return search\n",
    "\n",
    "t0 = time.perf_counter(); own = build_own(); t_own = time.perf_counter() - t0\n",
    "print(f\"construido en {t_own:.2f} s\")\n",
    "print(own(\"What wave height stops the crew boats from sailing?\", k=3))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "05bc5ce1",
   "metadata": {},
   "source": [
    "## 3. LangChain\n",
    "\n",
    "La idea central de LangChain es un conjunto de interfaces pequeñas (`Document`, `Embeddings`, `VectorStore`,\n",
    "`Retriever`, `Runnable`) para que los componentes sean intercambiables: cambias una línea y FAISS pasa a ser\n",
    "pgvector, o un modelo local pasa a ser uno alojado. El pipeline de abajo usa:\n",
    "\n",
    "* **`Document`**: texto más un diccionario `metadata` (aquí el id del pasaje y la sección), que viaja con cada trozo\n",
    "  y vuelve con cada resultado, de modo que la cita sale gratis.\n",
    "* **Un divisor de texto**: `RecursiveCharacterTextSplitter` corta por límites de párrafo, luego de frase y luego de\n",
    "  palabra. Nuestros pasajes ya son cortos, así que debería dejarlos intactos; lo comprobamos.\n",
    "* **`Embeddings`**: una interfaz con `embed_documents` y `embed_query`. Envolvemos una vez nuestro modelo MiniLM.\n",
    "* **FAISS** (Facebook AI Similarity Search): el índice vectorial del módulo 02, detrás de la interfaz\n",
    "  `VectorStore` de LangChain.\n",
    "* **Un recuperador**: `vectorstore.as_retriever()`, que devuelve `Document`s para una pregunta."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "9a7b72fb",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:52.042146Z",
     "iopub.status.busy": "2026-11-17T21:30:52.041806Z",
     "iopub.status.idle": "2026-11-17T21:30:53.821627Z",
     "shell.execute_reply": "2026-11-17T21:30:53.819171Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "built in 0.68 s; 22 documents -> 22 chunks (the splitter left every passage whole: True)\n",
      "top hit: {'id': 'p02', 'section': 'Safety / Weather limits'} | Safety / Weather limits. Crew transfer vessels do not sail when the si ...\n"
     ]
    }
   ],
   "source": [
    "from langchain_core.documents import Document\n",
    "from langchain_core.embeddings import Embeddings\n",
    "from langchain_text_splitters import RecursiveCharacterTextSplitter\n",
    "from langchain_community.vectorstores import FAISS\n",
    "\n",
    "class MiniLMEmbeddings(Embeddings):\n",
    "    def embed_documents(self, texts):\n",
    "        return minilm.encode(texts, normalize_embeddings=True).tolist()\n",
    "    def embed_query(self, text):\n",
    "        return minilm.encode(text, normalize_embeddings=True).tolist()\n",
    "\n",
    "def build_langchain(k=len(ids)):\n",
    "    docs = [Document(page_content=t, metadata={\"id\": i, \"section\": s}) for (i, s, _), t in zip(PASSAGES, texts)]\n",
    "    chunks = RecursiveCharacterTextSplitter(chunk_size=400, chunk_overlap=0).split_documents(docs)\n",
    "    store = FAISS.from_documents(chunks, MiniLMEmbeddings())\n",
    "    retriever = store.as_retriever(search_kwargs={\"k\": k})\n",
    "    return (lambda question: [d.metadata[\"id\"] for d in retriever.invoke(question)]), docs, chunks, retriever\n",
    "\n",
    "t0 = time.perf_counter(); lc_search, lc_docs, lc_chunks, lc_retriever = build_langchain(); t_lc = time.perf_counter() - t0\n",
    "print(f\"built in {t_lc:.2f} s; {len(lc_docs)} documents -> {len(lc_chunks)} chunks (the splitter left every passage whole: {len(lc_docs) == len(lc_chunks)})\")\n",
    "hit = lc_retriever.invoke(\"What wave height stops the crew boats from sailing?\")[0]\n",
    "print(\"top hit:\", hit.metadata, \"|\", hit.page_content[:70], \"...\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0336aea3",
   "metadata": {},
   "source": [
    "### Una cadena con el operador de tubería (LCEL)\n",
    "\n",
    "El lenguaje de expresiones de LangChain compone pasos con `|`: recuperar, formatear un prompt, llamar a un\n",
    "modelo, interpretar la salida. Aquí el \"modelo\" es un sustituto local y determinista (el generador extractivo del\n",
    "módulo 01), envuelto en `RunnableLambda` para que encaje en la cadena. Cámbialo por un modelo de chat alojado\n",
    "(módulo 04) y nada más cambia; ese es el sentido de la interfaz."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "6284a08c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:53.825545Z",
     "iopub.status.busy": "2026-11-17T21:30:53.825219Z",
     "iopub.status.idle": "2026-11-17T21:30:53.907612Z",
     "shell.execute_reply": "2026-11-17T21:30:53.906171Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Crew transfer vessels do not sail when the significant wave height exceeds 1.5 m or the wind speed at the harbour exceeds 20 m/s. [1] (source: Safety / Weather limits)\n",
      "Any injury or near miss is reported within one hour and a written report is filed within 24 hours. [1] (source: Reporting / Incidents)\n",
      "\n",
      "the chain is a RunnableSequence with 2 steps: ['RunnableParallel', 'RunnableLambda']\n"
     ]
    }
   ],
   "source": [
    "from langchain_core.runnables import RunnableLambda, RunnablePassthrough\n",
    "\n",
    "STOP = set(\"a an and are as at be by can do does for from how i if in is it of on or that the this to what when which who with you\".split())\n",
    "def toks(s): return {w for w in re.findall(r\"[a-z0-9]+\", s.lower()) if w not in STOP}\n",
    "\n",
    "def format_context(docs):\n",
    "    return \"\\n\".join(f\"[{n}] ({d.metadata['id']}) {d.page_content}\" for n, d in enumerate(docs, start=1))\n",
    "\n",
    "def standin_generator(inputs):\n",
    "    # elige la frase del mejor pasaje que comparte más palabras con la pregunta, y la cita como [1]\n",
    "    question, docs = inputs[\"question\"], inputs[\"docs\"]\n",
    "    body = docs[0].page_content.split(\". \", 1)[1]\n",
    "    best = max(re.split(r\"(?<=[.!?])\\s+\", body), key=lambda s: len(toks(question) & toks(s)))\n",
    "    return f\"{best} [1] (source: {docs[0].metadata['section']})\"\n",
    "\n",
    "# el recuperador de arriba devuelve todos los pasajes; la cadena se queda con los 3 primeros\n",
    "chain = (\n",
    "    {\"question\": RunnablePassthrough(), \"docs\": lc_retriever | RunnableLambda(lambda ds: ds[:3])}\n",
    "    | RunnableLambda(standin_generator)\n",
    ")\n",
    "print(chain.invoke(\"What qualification do I need before getting on the boat?\"))\n",
    "print(chain.invoke(\"How soon must an injury be reported?\"))\n",
    "print(\"\\nthe chain is a\", type(chain).__name__, \"with\", len(chain.steps), \"steps:\", [type(x).__name__ for x in chain.steps])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8813c56c",
   "metadata": {},
   "source": [
    "Fíjate en la primera respuesta: la pregunta era sobre la *cualificación* necesaria para embarcar y la cadena\n",
    "respondió con los límites meteorológicos. Es una de las dos preguntas de la batería en las que el primer pasaje\n",
    "recuperado no es el correcto (mira el hit@1 de más abajo), y la cadena responde fielmente con lo que recibió. Un\n",
    "framework une los pasos entre sí; no convierte en fuerte una recuperación débil."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85e66534",
   "metadata": {},
   "source": [
    "## 4. LlamaIndex\n",
    "\n",
    "LlamaIndex parte de los datos y no de la cadena. Le entregas documentos y construye un **índice** (aquí un\n",
    "`VectorStoreIndex`) que después consultas. Su vocabulario:\n",
    "\n",
    "* **`Document`** se convierte en **nodos** (los trozos) mediante un *analizador de nodos*; los nodos conservan un\n",
    "  enlace a su origen.\n",
    "* **`VectorStoreIndex`** calcula los embeddings de los nodos y guarda los vectores (en memoria por defecto).\n",
    "* **Un recuperador** devuelve nodos *con puntuación*, y un **motor de consultas** añade el paso de síntesis de la\n",
    "  respuesta (recuperar, construir un prompt, llamar al LLM). Le damos un `MockLLM` para que nada salga de la\n",
    "  máquina, y leemos los nodos recuperados, que es donde vive la calidad de la recuperación."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "cb458690",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:53.911816Z",
     "iopub.status.busy": "2026-11-17T21:30:53.911467Z",
     "iopub.status.idle": "2026-11-17T21:30:57.427707Z",
     "shell.execute_reply": "2026-11-17T21:30:57.425812Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "built in 1.35 s; 22 nodes in the index\n",
      "top hit: score 0.62 {'id': 'p02', 'section': 'Safety / Weather limits'} | Safety / Weather limits. Crew transfer vessels do not sail w ...\n",
      "\n",
      "query engine sources: [('p19', 0.52), ('p08', 0.31), ('p18', 0.26)]\n",
      "response object: Response (the text is the MockLLM's placeholder, by design)\n"
     ]
    }
   ],
   "source": [
    "from llama_index.core import VectorStoreIndex, Document as LIDocument\n",
    "from llama_index.core.embeddings import BaseEmbedding\n",
    "from llama_index.core.llms import MockLLM\n",
    "from llama_index.core.node_parser import SentenceSplitter\n",
    "\n",
    "class MiniLMLlama(BaseEmbedding):\n",
    "    def _get_query_embedding(self, query): return minilm.encode(query, normalize_embeddings=True).tolist()\n",
    "    def _get_text_embedding(self, text): return minilm.encode(text, normalize_embeddings=True).tolist()\n",
    "    async def _aget_query_embedding(self, query): return self._get_query_embedding(query)\n",
    "    async def _aget_text_embedding(self, text): return self._get_text_embedding(text)\n",
    "\n",
    "def build_llamaindex(k=len(ids)):\n",
    "    docs = [LIDocument(text=t, metadata={\"id\": i, \"section\": s}) for (i, s, _), t in zip(PASSAGES, texts)]\n",
    "    index = VectorStoreIndex.from_documents(docs, embed_model=MiniLMLlama(model_name=\"minilm\"),\n",
    "                                            transformations=[SentenceSplitter(chunk_size=512, chunk_overlap=0)], show_progress=False)\n",
    "    retriever = index.as_retriever(similarity_top_k=k)\n",
    "    return (lambda question: [n.node.metadata[\"id\"] for n in retriever.retrieve(question)]), index, retriever\n",
    "\n",
    "t0 = time.perf_counter(); li_search, li_index, li_retriever = build_llamaindex(); t_li = time.perf_counter() - t0\n",
    "print(f\"built in {t_li:.2f} s; {len(li_index.docstore.docs)} nodes in the index\")\n",
    "hit = li_retriever.retrieve(\"What wave height stops the crew boats from sailing?\")[0]\n",
    "print(f\"top hit: score {hit.score:.2f}\", hit.node.metadata, \"|\", hit.node.get_content()[:60], \"...\")\n",
    "\n",
    "engine = li_index.as_query_engine(llm=MockLLM(), embed_model=MiniLMLlama(model_name=\"minilm\"), similarity_top_k=3)\n",
    "response = engine.query(\"How soon must an injury be reported?\")\n",
    "print(\"\\nquery engine sources:\", [(n.node.metadata[\"id\"], round(n.score, 2)) for n in response.source_nodes])\n",
    "print(\"response object:\", type(response).__name__, \"(the text is the MockLLM's placeholder, by design)\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b01b0464",
   "metadata": {},
   "source": [
    "## 5. Comparación honesta\n",
    "\n",
    "Tres mediciones: si la recuperación difiere, cuánto código necesita cada pipeline y cuánto cuesta cargar cada uno.\n",
    "Primero la recuperación, sobre la batería de 24 preguntas."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a141917e",
   "metadata": {},
   "source": [
    "### Imagen: qué fluye por las tres canalizaciones\n",
    "\n",
    "Las mismas entradas pasan por cada canalización y a cada una se le hacen las mismas 24 preguntas de la batería. Las\n",
    "cajas de la derecha son los resultados medidos que imprime la celda siguiente. La nota explica el único punto en\n",
    "que difieren."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "5cbaeaf6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:57.431293Z",
     "iopub.status.busy": "2026-11-17T21:30:57.430967Z",
     "iopub.status.idle": "2026-11-17T21:30:57.445367Z",
     "shell.execute_reply": "2026-11-17T21:30:57.443546Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/svg+xml": [
       "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 800 350\" width=\"100%\" font-family=\"Helvetica, Arial, sans-serif\"><defs><marker id=\"ah\" viewBox=\"0 0 10 10\" refX=\"9\" refY=\"5\" markerWidth=\"7\" markerHeight=\"7\" orient=\"auto-start-reverse\"><path d=\"M0,0 L10,5 L0,10 z\" fill=\"#555\"/></marker></defs><rect width=\"800\" height=\"350\" rx=\"12\" fill=\"#fbfbf8\" stroke=\"#d8d8cf\"/><text x=\"400.0\" y=\"26\" text-anchor=\"middle\" font-size=\"15\" font-weight=\"700\" fill=\"#222\">Flujo de datos: un corpus, tres canalizaciones</text><rect x=\"20\" y=\"100\" width=\"200\" height=\"90\" rx=\"9\" fill=\"#f1f1f4\" stroke=\"#8a8aa0\" stroke-width=\"1.6\"/><text x=\"120.0\" y=\"124.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Mismas entradas</text><text x=\"120.0\" y=\"141.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">22 pasajes (id, sección)</text><text x=\"120.0\" y=\"158.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">24 preguntas de la batería</text><text x=\"120.0\" y=\"175.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">mismos embeddings MiniLM</text><line x1=\"220\" y1=\"125\" x2=\"262\" y2=\"76\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><line x1=\"220\" y1=\"145\" x2=\"262\" y2=\"156\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><line x1=\"220\" y1=\"165\" x2=\"262\" y2=\"236\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><rect x=\"262\" y=\"44\" width=\"250\" height=\"64\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"387.0\" y=\"72.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">Recuperador NumPy propio</text><text x=\"387.0\" y=\"89.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">matriz E, producto escalar</text><rect x=\"262\" y=\"124\" width=\"250\" height=\"64\" rx=\"9\" fill=\"#dbeafe\" stroke=\"#3b82f6\" stroke-width=\"1.6\"/><text x=\"387.0\" y=\"152.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">LangChain + FAISS</text><text x=\"387.0\" y=\"169.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">el divisor deja 22 trozos</text><rect x=\"262\" y=\"204\" width=\"250\" height=\"64\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"387.0\" y=\"232.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">LlamaIndex VectorStoreIndex</text><text x=\"387.0\" y=\"249.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">22 nodos, también con metadatos</text><line x1=\"512\" y1=\"76\" x2=\"554\" y2=\"76\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><line x1=\"512\" y1=\"156\" x2=\"554\" y2=\"156\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><line x1=\"512\" y1=\"236\" x2=\"554\" y2=\"236\" stroke=\"#555\" stroke-width=\"1.8\" marker-end=\"url(#ah)\"/><rect x=\"554\" y=\"44\" width=\"226\" height=\"64\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"667.0\" y=\"72.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">hit@1 0.92, hit@3 1.00</text><text x=\"667.0\" y=\"89.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">MRR 0.958</text><rect x=\"554\" y=\"124\" width=\"226\" height=\"64\" rx=\"9\" fill=\"#dcfce7\" stroke=\"#16a34a\" stroke-width=\"1.6\"/><text x=\"667.0\" y=\"152.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">hit@1 0.92, hit@3 1.00</text><text x=\"667.0\" y=\"169.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">top-3 igual al propio: 24/24</text><rect x=\"554\" y=\"204\" width=\"226\" height=\"64\" rx=\"9\" fill=\"#fff4c2\" stroke=\"#b89d28\" stroke-width=\"1.6\"/><text x=\"667.0\" y=\"232.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\" font-weight=\"700\">hit@1 0.92, hit@3 1.00</text><text x=\"667.0\" y=\"249.0\" text-anchor=\"middle\" font-size=\"13\" fill=\"#222\">top-3 igual al propio: 16/24</text><rect x=\"20\" y=\"284\" width=\"760\" height=\"52\" rx=\"6\" fill=\"none\" stroke=\"#b89d28\" stroke-dasharray=\"5 4\"/><text x=\"30\" y=\"304\" font-size=\"12\" fill=\"#444\">Ejemplo: What wave height stops the crew boats from sailing? da p02 en primer lugar en las tres.</text><text x=\"30\" y=\"320\" font-size=\"12\" fill=\"#444\">LlamaIndex también incrusta el texto de los metadatos (id, sección), lo que reordena parte del top 3.</text></svg>"
      ],
      "text/plain": [
       "<IPython.core.display.SVG object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "diagram(800, 350, [\n",
    "    (\"box\", 20, 100, 200, 90, \"Mismas entradas\\n22 pasajes (id, sección)\\n24 preguntas de la batería\\nmismos embeddings MiniLM\", \"grey\"),\n",
    "    (\"arrow\", 220, 125, 262, 76, \"\"),\n",
    "    (\"arrow\", 220, 145, 262, 156, \"\"),\n",
    "    (\"arrow\", 220, 165, 262, 236, \"\"),\n",
    "    (\"box\", 262, 44, 250, 64, \"Recuperador NumPy propio\\nmatriz E, producto escalar\", \"gold\"),\n",
    "    (\"box\", 262, 124, 250, 64, \"LangChain + FAISS\\nel divisor deja 22 trozos\", \"blue\"),\n",
    "    (\"box\", 262, 204, 250, 64, \"LlamaIndex VectorStoreIndex\\n22 nodos, también con metadatos\", \"green\"),\n",
    "    (\"arrow\", 512, 76, 554, 76, \"\"),\n",
    "    (\"arrow\", 512, 156, 554, 156, \"\"),\n",
    "    (\"arrow\", 512, 236, 554, 236, \"\"),\n",
    "    (\"box\", 554, 44, 226, 64, \"hit@1 0.92, hit@3 1.00\\nMRR 0.958\", \"green\"),\n",
    "    (\"box\", 554, 124, 226, 64, \"hit@1 0.92, hit@3 1.00\\ntop-3 igual al propio: 24/24\", \"green\"),\n",
    "    (\"box\", 554, 204, 226, 64, \"hit@1 0.92, hit@3 1.00\\ntop-3 igual al propio: 16/24\", \"gold\"),\n",
    "    (\"note\", 20, 284, 760, 52, \"Ejemplo: What wave height stops the crew boats from sailing? da p02 en primer lugar en las tres.\\nLlamaIndex también incrusta el texto de los metadatos (id, sección), lo que reordena parte del top 3.\"),\n",
    "], \"Flujo de datos: un corpus, tres canalizaciones\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "e5e745ec",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:30:57.449460Z",
     "iopub.status.busy": "2026-11-17T21:30:57.449106Z",
     "iopub.status.idle": "2026-11-17T21:31:03.604042Z",
     "shell.execute_reply": "2026-11-17T21:31:03.602115Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "own NumPy retriever                hit@1 0.92   hit@3 1.00   MRR 0.958\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "LangChain + FAISS                  hit@1 0.92   hit@3 1.00   MRR 0.958\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "LlamaIndex VectorStoreIndex        hit@1 0.92   hit@3 1.00   MRR 0.958\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "same top-1 on 24/24 questions (own vs LangChain) and 24/24 (own vs LlamaIndex)\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "same ordered top-3: own vs LangChain 24/24, own vs LlamaIndex 16/24\n",
      "\n",
      "text LlamaIndex embeds for one node by default:\n",
      "   'id: p01\\nsection: Safety / Access\\n\\nSafety / Access. Technicians must hold a valid GWO Basic Safety Training cer'\n"
     ]
    }
   ],
   "source": [
    "def row(name, search):\n",
    "    m = evaluate(search)\n",
    "    print(f\"{name:34s} hit@1 {m['hit1']:.2f}   hit@3 {m['hit3']:.2f}   MRR {m['mrr']:.3f}\")\n",
    "    return m\n",
    "\n",
    "m_own = row(\"own NumPy retriever\", own)\n",
    "m_lc = row(\"LangChain + FAISS\", lc_search)\n",
    "m_li = row(\"LlamaIndex VectorStoreIndex\", li_search)\n",
    "qs = [q for _, q, _ in BATTERY]\n",
    "agree = lambda a, b, k: sum(a(q)[:k] == b(q)[:k] for q in qs)\n",
    "print(f\"\\nsame top-1 on {agree(own, lc_search, 1)}/{len(qs)} questions (own vs LangChain) and {agree(own, li_search, 1)}/{len(qs)} (own vs LlamaIndex)\")\n",
    "print(f\"same ordered top-3: own vs LangChain {agree(own, lc_search, 3)}/{len(qs)}, own vs LlamaIndex {agree(own, li_search, 3)}/{len(qs)}\")\n",
    "from llama_index.core.schema import MetadataMode\n",
    "node = next(iter(li_index.docstore.docs.values()))\n",
    "print(\"\\ntext LlamaIndex embeds for one node by default:\\n  \", repr(node.get_content(metadata_mode=MetadataMode.EMBED)[:110]))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "55a887e5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-11-17T21:31:03.607967Z",
     "iopub.status.busy": "2026-11-17T21:31:03.607591Z",
     "iopub.status.idle": "2026-11-17T21:31:14.213114Z",
     "shell.execute_reply": "2026-11-17T21:31:14.211172Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "non-blank, non-comment lines of the build function (+ the embedding adapter each framework needs):\n",
      "  own NumPy retriever      6  + adapter   0\n",
      "  LangChain + FAISS        6  + adapter   5\n",
      "  LlamaIndex               6  + adapter   5\n",
      "\n",
      "import time in a fresh interpreter (best of 2) and size of the framework's own packages:\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  numpy only            0.16 s import       65 MB installed\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  LangChain + FAISS     1.48 s import       94 MB installed\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "  LlamaIndex            2.56 s import       27 MB installed\n"
     ]
    }
   ],
   "source": [
    "loc = {name: len([l for l in inspect.getsource(fn).splitlines() if l.strip() and not l.strip().startswith(\"#\")])\n",
    "       for name, fn in [(\"own NumPy retriever\", build_own), (\"LangChain + FAISS\", build_langchain), (\"LlamaIndex\", build_llamaindex)]}\n",
    "def class_source(name):\n",
    "    # las clases definidas en un notebook no tienen archivo fuente: se leen del historial de celdas\n",
    "    cell = next(c for c in get_ipython().user_ns[\"_ih\"] if f\"class {name}(\" in c)\n",
    "    start = cell.index(f\"class {name}(\")\n",
    "    block = cell[start:].split(\"\\n\")\n",
    "    out = [block[0]]\n",
    "    for line in block[1:]:\n",
    "        if line.strip() and not line.startswith(\" \"):\n",
    "            break\n",
    "        out.append(line)\n",
    "    return \"\\n\".join(out)\n",
    "\n",
    "extra = {\"LangChain + FAISS\": class_source(\"MiniLMEmbeddings\"), \"LlamaIndex\": class_source(\"MiniLMLlama\")}\n",
    "print(\"non-blank, non-comment lines of the build function (+ the embedding adapter each framework needs):\")\n",
    "for name, n in loc.items():\n",
    "    adapter = len([l for l in extra.get(name, \"\").splitlines() if l.strip()])\n",
    "    print(f\"  {name:22s}{n:4d}  + adapter {adapter:3d}\")\n",
    "\n",
    "def fresh_import_seconds(stmt):\n",
    "    code_ = f\"import time; t = time.perf_counter(); {stmt}; print(time.perf_counter() - t)\"\n",
    "    out = [float(subprocess.run([sys.executable, \"-c\", code_], capture_output=True, text=True).stdout.strip().splitlines()[-1]) for _ in range(2)]\n",
    "    return min(out)\n",
    "\n",
    "import importlib.metadata as md_\n",
    "def installed_mb(*dists):\n",
    "    total, seen = 0, set()\n",
    "    for d in dists:\n",
    "        try:\n",
    "            for f in md_.files(d) or []:\n",
    "                p = f.locate()\n",
    "                if str(p) not in seen and p.exists():\n",
    "                    seen.add(str(p)); total += p.stat().st_size\n",
    "        except md_.PackageNotFoundError:\n",
    "            pass\n",
    "    return total / 1e6\n",
    "\n",
    "print(\"\\nimport time in a fresh interpreter (best of 2) and size of the framework's own packages:\")\n",
    "for label, stmt, dists in [\n",
    "    (\"numpy only\", \"import numpy\", [\"numpy\"]),\n",
    "    (\"LangChain + FAISS\", \"from langchain_core.documents import Document; from langchain_community.vectorstores import FAISS; from langchain_text_splitters import RecursiveCharacterTextSplitter\", [\"langchain-core\", \"langchain-community\", \"langchain-text-splitters\", \"faiss-cpu\"]),\n",
    "    (\"LlamaIndex\", \"from llama_index.core import VectorStoreIndex\", [\"llama-index-core\"]),\n",
    "]:\n",
    "    print(f\"  {label:20s}{fresh_import_seconds(stmt):6.2f} s import   {installed_mb(*dists):6.0f} MB installed\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aee3de01",
   "metadata": {},
   "source": [
    "Lee los tres resultados juntos:\n",
    "\n",
    "* **La calidad de la recuperación es una propiedad del modelo de embeddings y del troceado, no del framework.** Los\n",
    "  tres recuperadores obtienen exactamente el mismo hit@1, hit@3 y MRR. Nuestro recuperador NumPy y LangChain+FAISS\n",
    "  devuelven el mismo top tres ordenado en todas las preguntas. LlamaIndex coincide en el primer resultado en todas,\n",
    "  pero ordena de otro modo el 2.º y el 3.º en algunas preguntas, y la última línea impresa muestra por qué: **por\n",
    "  defecto calcula el embedding de los metadatos del nodo (`id`, `section`) junto con el texto**, así que el vector que\n",
    "  busca no es el vector que tú construiste. Es un valor por defecto del framework que cambia en silencio tu\n",
    "  recuperación, y solo lo notas porque comparaste con una referencia. (El ejercicio 3 alinea los dos.) Elegir un\n",
    "  framework u otro no hará que las respuestas sean mejores ni peores; el módulo 07 muestra qué sí lo hace.\n",
    "* **A esta escala los frameworks cuestan peso y un adaptador, no líneas.** Las funciones de construcción tienen la\n",
    "  misma longitud (unas seis líneas cada una) y cada framework necesita además un adaptador de cinco líneas para\n",
    "  usar nuestro modelo local, que es donde normalmente se conectaría un modelo alojado. El precio real es el tiempo de\n",
    "  importación y el tamaño instalado, medidos arriba: muy por encima de los de NumPy. En un servidor siempre activo y\n",
    "  con poca memoria eso importa (un punto al que vuelve el módulo de producción).\n",
    "* **Lo que compras es intercambiabilidad y ecosistema**: cien almacenes vectoriales, cargadores de PDF y bases de\n",
    "  datos, callbacks de trazado (módulo 09), agentes y grafos (módulo 05). Si los necesitas, el coste compensa; si\n",
    "  necesitas un solo recuperador sobre un solo corpus, no."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "84b45fca",
   "metadata": {},
   "source": [
    "## 6. Qué abstrae cada framework y cuándo prescindir de ambos\n",
    "\n",
    "| Aspecto | Nuestro código | LangChain | LlamaIndex |\n",
    "|---|---|---|---|\n",
    "| Unidad de texto | una cadena y un id | `Document` con `metadata` | `Document`, dividido en `Node`s que conservan su origen |\n",
    "| Embedding | llamar al modelo | interfaz `Embeddings` | interfaz `BaseEmbedding` |\n",
    "| Índice | una matriz NumPy | cualquier `VectorStore` (FAISS, pgvector, ...) | `VectorStoreIndex` sobre un almacén intercambiable |\n",
    "| Recuperación | `argsort` | `retriever.invoke` | `index.as_retriever`, con nodos puntuados |\n",
    "| Composición | funciones simples | cadenas unidas con el operador pipe (LCEL), después LangGraph | motores de consulta, enrutadores, agentes |\n",
    "| Síntesis de la respuesta | tu propio prompt | una cadena que ensamblas | integrada en el motor de consultas |\n",
    "| Más fuerte en | claridad, huella mínima | integraciones amplias, componer pasos | indexar datos estructurados y mixtos, patrones de consulta incluidos |\n",
    "\n",
    "**Cuándo prescindir de ambos.** Un corpus, un recuperador, unos pocos miles de trozos, un servicio que debe seguir\n",
    "siendo pequeño: la docena de líneas de NumPy de la sección 2 es más fácil de leer, probar y mantener correcta, y se\n",
    "importa al instante. El componente de recuperación de un pequeño endpoint de búsqueda de este portafolio es BM25 puro\n",
    "exactamente por eso. Recurre a un framework cuando necesites lo que aporta (almacenes intercambiables, muchos\n",
    "cargadores, ganchos de trazado, grafos de pasos), no por defecto; y no mezcles dos frameworks sin un motivo. El agente\n",
    "de parques eólicos mantuvo dos pilas porque los dos corpus tenían formas distintas (narrativas de incidencias en texto\n",
    "libre frente a especificaciones estructuradas) y cada framework encajaba mejor con uno, y porque el agente solo ve\n",
    "ambos a través de una única función `search`, de modo que la elección queda local.\n",
    "\n",
    "## Ejercicios\n",
    "\n",
    "1. Cambia el divisor a `chunk_size=80` y reconstruye el almacén de LangChain. ¿Cuántos trozos obtienes y qué ocurre\n",
    "   con el hit@1 y con la legibilidad de un trozo citado?\n",
    "2. Añade un recuperador con `k=2` a la cadena LCEL e imprime qué pasajes ve el generador sustituto en las preguntas\n",
    "   parafraseadas. ¿Dónde falla, y la culpa es de la recuperación o del generador?\n",
    "3. Haz que LlamaIndex calcule el embedding solo del texto: fija `excluded_embed_metadata_keys=[\"id\", \"section\"]` en\n",
    "   cada `Document` y reconstruye. ¿Coincide ahora su top tres ordenado con el de los otros dos en todas las preguntas?\n",
    "4. Escribe un cuarto recuperador: el BM25 del módulo 01 detrás de la misma función `search(question)`, y evalúalo con\n",
    "   el mismo `evaluate`. ¿Cuál de los cuatro llevarías a producción para este corpus, y por qué?"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
