Apéndice L — Widget de IA: «Pregúntale al libro»

L.3.1 Chunking del corpus

El script chunker.py recorre los veintidós archivos .qmd listados en _quarto.yml (trece capítulos más diez anexos, incluido el index.qmd del prefacio) y produce una lista de fragmentos semánticos. El procedimiento es:

1. Se lee el archivo y se separa el frontmatter YAML del cuerpo; del frontmatter se extrae el título del capítulo.
2. Se recorre el cuerpo línea a línea. Cada vez que se encuentra un encabezado de nivel H2, H3 o H4 se cierra el chunk anterior y se abre uno nuevo. Los bloques de código delimitados por ``` se preservan como parte del chunk en el que aparecen pero no disparan cortes.
3. Cada encabezado se escanea en busca del patrón {#sec-xxx}. Si existe, ese es el ancla canónica del chunk. Si no, el chunk hereda la última ancla vista en el documento.
4. Para cada chunk se construye un heading_path jerárquico del tipo “Contexto territorial > Caracterización > Clima”, reconstruyendo la pila de encabezados activos en ese punto del archivo.
5. Antes de guardar el chunk se limpian las imágenes (preservando el texto de la caption como [Figura: ...] para que el contenido visual quede representado textualmente), los comentarios HTML y los bloques de código.
6. Los chunks con menos de ochenta caracteres de texto útil se descartan (encabezados sueltos, separadores).

Cada chunk resultante es un objeto con los campos id, file, chapter_title, heading_path, anchor, level y text. El conjunto completo se persiste como chunks.json. Para el libro FONDOCYT el proceso produce 321 chunks, con una extensión total aproximada de 618,000 caracteres distribuidos razonablemente entre todos los capítulos.

L.3.2 Índice vectorial

El script index.py toma los chunks del paso anterior y genera una representación vectorial densa. Para cada chunk construye un texto de entrada de la forma “título del capítulo. jerarquía de encabezados. cuerpo del chunk”, truncado a cuatro mil caracteres para respetar el contexto del modelo de embeddings, y lo envía al modelo seleccionado por lotes de 64. El vector de salida se normaliza a norma uno, lo que permite reemplazar el cálculo de similitud coseno por un simple producto escalar.

La matriz resultante, de tamaño (n_chunks, d) donde d es 1536 para text-embedding-3-small o 768 para nomic-embed-text, se persiste en index.npz mediante numpy.savez_compressed. Los metadatos del índice, incluidos los chunks completos, se guardan aparte en index.meta.json para que el servidor pueda cargar rápidamente tanto los vectores como el texto de referencia en una sola lectura.

Para un corpus de 321 chunks no es necesario usar una base de datos vectorial especializada (Chroma, Qdrant, Weaviate, pgvector). El producto escalar de NumPy en memoria sobre una matriz de \(321 \times 1536\) se resuelve en menos de un milisegundo, lo que simplifica el stack y elimina dependencias.

L.3.3 Pipeline de una consulta

Cuando el widget envía una pregunta al endpoint /ask, el servidor ejecuta el siguiente flujo:

1. Validación: se rechazan queries vacías o de más de quinientos caracteres para evitar abusos triviales.
2. Embedding de la consulta: se envía la pregunta al modelo de embeddings activo, se obtiene un vector de la misma dimensión que los del índice y se normaliza.
3. Recuperación: se calcula el producto escalar de ese vector contra toda la matriz index.npz y se seleccionan los top_k chunks con mayor similitud. Por defecto top_k = 7, valor configurable en .env mediante la variable IA_TOP_K.
4. Construcción del prompt de usuario: para cada chunk recuperado se anota el número, el título del capítulo, la jerarquía de encabezados y el ancla en el formato [#sec-xxx]. Los cuerpos se truncan a 1,800 caracteres por chunk para no exceder el límite de contexto del modelo generativo y mantener el coste controlado.
5. Llamada al LLM: se invoca al modelo con temperatura 0.2 (favorece reproducibilidad sobre creatividad), pasando el system prompt fijo y el user prompt construido.
6. Generación del reporte: la respuesta del modelo se pasa a render_report.py, que produce los tres artefactos persistentes (HTML, Markdown, PDF) y agrega una entrada al índice de la galería.
7. Respuesta al widget: el servidor devuelve un objeto JSON con la respuesta en Markdown, la lista de fuentes consultadas, las rutas de descarga y el identificador del reporte.

L.3.4 System prompt del modelo generativo

El prompt de sistema es la pieza crítica para controlar el comportamiento del LLM. Se mantiene deliberadamente corto y explícito, en español, y establece seis reglas:

Eres un asistente de investigación del libro FONDOCYT sobre Bajos
de Haina. Respondes preguntas usando ÚNICAMENTE los fragmentos del
libro que te pasa el usuario. Reglas:

1. Nunca inventes información. Si la respuesta no está en los
   fragmentos, responde textualmente: "No encontrado en el libro".
2. Responde en español, registro académico claro, párrafos de 4
   a 6 oraciones.
3. PROHIBIDO usar el guion largo. Usa coma, punto y coma, dos
   puntos o paréntesis.
4. Cada afirmación fáctica relevante debe terminar con una
   referencia al ancla de la sección del libro de donde proviene,
   en el formato [#sec-xxx]. Usa los anclajes que aparecen en los
   metadatos de los fragmentos.
5. Estructura: 2 a 4 párrafos (200 a 400 palabras). Sin listas
   ni bullets en el cuerpo.
6. No menciones que estás usando fragmentos, ni digas "según los
   fragmentos". Habla como si citaras directamente el libro.

La combinación de la primera regla (prohibido inventar), la cuarta (cada afirmación con su ancla) y la decisión de pasar solo los chunks recuperados al contexto del modelo produce una cadena de verificación sencilla: si una afirmación no aparece en los chunks, el modelo está instruido para responder “No encontrado en el libro”; si el modelo rompe la regla e inventa, la ausencia del ancla correspondiente delata la invención al lector.

L.3.5 Endpoints del servidor

El servidor FastAPI expone los siguientes endpoints:

El servidor habilita CORS con allow_origins=["*"] para facilitar el desarrollo local. En producción se recomienda restringirlo al dominio desde el que se sirve el libro HTML.

L.3.6 Generación del PDF

Cada respuesta del sistema se convierte en un PDF descargable. La primera versión del prototipo usaba WeasyPrint para evitar dependencias externas, pero su instalación en Windows requiere las bibliotecas GTK, Cairo y Pango, lo que añade fricción innecesaria. Se adoptó en su lugar el mismo motor que ya utiliza Quarto para el libro: pandoc más xelatex sobre TinyTeX.

El procedimiento en render_report.py::_build_pdf_with_pandoc() es:

1. Se detecta dinámicamente la ruta de instalación de TinyTeX (candidatas: C:\ProgramData\TinyTeX\bin\windows, ~\AppData\Roaming\TinyTeX\bin\windows, ~\AppData\Local\TinyTeX\bin\windows).
2. Se inyecta la ruta encontrada al PATH del subproceso que ejecutará pandoc, sin modificar el PATH global del sistema. Esto es necesario porque Quarto instala TinyTeX pero no expone su bin al shell padre.
3. Se intenta la conversión en cascada: primero con quarto pandoc (que ya trae pandoc bundleado), luego con pandoc del sistema si está instalado, probando los motores xelatex, lualatex y pdflatex en ese orden.
4. Si algún intento tiene éxito, el PDF queda en reports/<id>/report.pdf. Si todos fallan, se escribe un pdf.error.log en la carpeta del reporte y el sistema degrada graciosamente: el widget oculta el botón “Descargar PDF” pero el reporte HTML y el Markdown siguen disponibles.

El PDF resultante respeta los parámetros geometry:margin=2.2cm, fontsize=11pt, lang=es y colorlinks=true, lo que produce un documento consistente con el estilo del libro aunque no idéntico.

L.3.7 Reescritura de anclas en la respuesta

El LLM devuelve una respuesta en Markdown con anclas del tipo [#sec-xxx] incrustadas al final de cada afirmación. Antes de entregar la respuesta al lector, render_report.py::rewrite_anchor_links() las transforma en enlaces Markdown reales: cada [#sec-xxx] pasa a ser [§](<ruta>/capitulo.html#sec-xxx), donde la ruta relativa se calcula en función de la ubicación del reporte (../.. desde reports/<id>/report.html hasta la raíz del libro). Esta reescritura se ejecuta tanto para el HTML del reporte (donde el símbolo § se convierte en un enlace clicable al libro) como para el Markdown descargable (donde queda como referencia textual de la sección).

L.3.8 Integración con Quarto

La única modificación necesaria en el proyecto Quarto del libro es una línea en libro/_quarto.yml, dentro del bloque format.html:

format:
  html:
    include-in-header:
      - _ia/widget-include.html

El archivo _ia/widget-include.html es un fragmento de HTML mínimo que declara la variable global window.IA_API_URL, carga el CSS del widget y el script widget.js desde el servidor FastAPI local. La directiva include-in-header de Quarto solo afecta a la salida HTML, de forma que el PDF del libro no se ve modificado en absoluto. Los demás archivos del libro (.qmd, references.bib, custom.scss) no requieren ninguna modificación.