trigsight

Un asistente de IA que no puede hacer una afirmación sobre mi trabajo que no pueda probar.

Cada afirmación factual que produce está vinculada en tiempo de compilación a la frase exacta que la respalda. Al hacer clic en una cita, se desplaza la página de origen hasta esa frase y la resalta. Si un pasaje citado no existe en su documento de origen, la compilación falla — una afirmación no verificable no es publicable.

Por qué existe esto

Los chatbots de portafolio hacen afirmaciones sobre la competencia de su autor. El lector no tiene forma de verificarlas, y tiene buenas razones para no intentarlo: las tasas de error de citas medidas para la búsqueda general con IA superan el 60%, y solo el 51,5% de las frases generadas están completamente respaldadas por sus fuentes citadas. Así que las afirmaciones se descuentan y la función es decoración.

La solución habitual es basar el modelo en un corpus y esperar. Eso ayuda con la alucinación, pero no con la verificación — el lector sigue recibiendo un enlace a una página completa y tiene que buscar la frase que respalda la afirmación específica.

Esto invierte el modelo de confianza. El modelo nunca escribe un enlace. Nombra un pasaje; la compilación lo resuelve contra un índice de lo que los documentos realmente dicen, o se niega a publicar.

Related MCP server: CiteGuard

Resultados medidos

2,8× menos JavaScript con una escena 3D en ejecución. Ambas cifras son transferencia brotli real en el cable desde los sitios desplegados, medidas con el mismo arnés (bench/baseline/measure-payload.sh), tres ejecuciones cada una — ver docs/05-results.md para saber por qué medir los dos lados de maneras diferentes sobrestimó esto como 3,4×.

Recuperación, 30 consultas doradas escritas a mano con k=5:

Los embeddings reales son text-embedding-3-small con 1536 dimensiones, coseno, a través de Upstash Vector. Tres ejecuciones idénticas. Observa lo que cambió: el recall no mejoró, el ranking sí. Con este tamaño de corpus, los embeddings reales no encuentran más fragmentos relevantes, sino que clasifican más alto los que encuentran — que es la métrica que importa, ya que solo los seis primeros llegan al modelo.

Cómo funciona la garantía

flowchart TB
  subgraph build["BUILD"]
    MDX["content/*.mdx"] --> N["normalise: collapse whitespace, casefold"]
    N --> IDX["passage index"]
    IDX --> VER{"every cited passage present exactly once?"}
    VER -->|no| FAIL["EXIT 1 — build fails"]
    VER -->|yes| OK["allowlist.json"]
  end
  subgraph run["REQUEST"]
    Q["question"] --> R["hybrid retrieve: BM25 + vector, RRF"]
    R --> M["model"]
    M -->|emits a cite token| RES{"in allowlist?"}
    OK --> RES
    RES -->|yes| CHIP["chip with text-fragment deep link"]
    RES -->|no| DROP["dropped"]
  end

El modelo no tiene mecanismo para producir una URL, por lo que no puede producir una incorrecta. Las instrucciones del prompt son una solicitud; una capacidad ausente es un invariante.

La parte que fue más difícil de lo que parece

Un navegador que coincide con #:~:text= compara contra el texto renderizado, y cada parte de la directiva debe estar dentro de un solo elemento. Dos consecuencias que costaron una depuración real:

• Comparar contra el código fuente falla en 3 de 7 pasajes que un navegador coincide bien — pasajes que cruzan una nueva línea, contienen espacios en blanco colapsados o difieren en mayúsculas. Un verificador que produce fallos falsos te entrena para desactivarlo.

• Un pasaje que abarca marcado en línea se renderiza como nodos DOM separados y no se puede coincidir en absoluto, aunque el texto aplanado lo contenga. Dos de 34 citas estaban en este estado: reportadas como vinculadas, pero imposibles de coincidir en la práctica. Solo se detectaron al obtener cada página construida y buscar su texto.

Ambos ahora están aplicados, con pruebas de regresión. El verificador también requiere que cada pasaje aparezca exactamente una vez, desambiguando con un prefijo cuando no es así — de lo contrario el navegador se desplaza silenciosamente a la ocurrencia incorrecta, un error de corrección que parece un éxito.

Inicio rápido

npm ci
npm run dev          # http://localhost:3000

No se necesitan credenciales. Sin AI_GATEWAY_API_KEY, el endpoint de chat devuelve el contexto recuperado en lugar de una respuesta, por lo que la recuperación es inspeccionable por sí sola.

Verifica las afirmaciones tú mismo

npm run verify:citations                 # the gate: exits 1 on any unbound claim
npx tsx bench/citations/verify.ts --demo # watch it reject a fabricated passage
npm run eval:retrieval                   # recall@5 and MRR over the golden set
./bench/payload/measure.sh 3990 150      # initial JS against the budget
npm test                                 # 91 tests

Cada número anterior proviene de uno de esos. bench/ está confirmado y nunca en gitignore — un arnés no confirmado convierte un resultado real en una afirmación no verificable.

Servidor MCP

POST /api/mcp — Streamable HTTP sin estado, especificación 2026-07-28. Cuatro herramientas de verificación de solo lectura en lugar de herramientas de descripción:

find_evidence originalmente confirmó "investigación en criptografía cuántica sobre trampas de iones". Una pata vectorial es una búsqueda de vecino más cercano: siempre devuelve sus fragmentos más cercanos, sin importar lo no relacionados que estén. Un agente que consuma eso repetiría una credencial fabricada. Ahora requiere una superposición léxica genuina, calibrada a 8/10 verdaderos positivos y 0/6 falsos positivos contra conjuntos de afirmaciones escritos a mano.

Limitaciones

Expresadas claramente, porque una sección de limitaciones que suena a marketing no vale nada.

• El margen sobre el solo léxico es de una consulta de ancho. Con 34 fragmentos y 30 consultas doradas, una consulta vale 0,033 de recall — así que la brecha de recall de 0,034 entre léxico e híbrido es una sola consulta. No leas la tabla como prueba de que el híbrido es superior en general. Muestra que el híbrido no es peor y clasifica mejor en este corpus.

• Una predicción mía fue incorrecta, y la razón es instructiva. Predije que los embeddings reales arreglarían la consulta que se perdía. No lo hicieron. Al sondear la pata vectorial en aislamiento se mostró que el fragmento correcto nunca entra en su top 5 — porque ese fragmento tiene 1,340 caracteres que cubren cinco temas, y la respuesta es una cláusula de 871 caracteres. Su vector único es un promedio de cinco ideas. Eso es un problema de fragmentación, no de embeddings, y ningún modelo lo arregla. Registrado en lugar de parcheado, porque cambiar el fragmentador ahora invalidaría la comparación que la tabla existe para hacer. Ver bench/retrieval/results/real-embeddings-2026-08-21.md.

• Sin credenciales, la pata vectorial se degrada a un sustituto determinista que no es un modelo semántico. La recuperación aún responde vía BM25, pero la calidad es genuinamente menor — el arnés nombra el backend en cada ejecución para que un número nunca se pueda citar sin él.

• Los fragmentos de texto son frágiles por diseño. Reformular una frase citada rompe su enlace. Ese es el punto de la compuerta de compilación — no puedes publicar la rotura — pero sí significa que editar prosa a veces implica actualizar una cita.

• Las citas deben estar dentro de un elemento de bloque. Una afirmación mejor respaldada por texto que abarca una fila de tabla y un párrafo no se puede citar como un solo pasaje.

• El corpus es pequeño (6 documentos, 34 fragmentos). Los números de recuperación aquí no deberían leerse como predicciones para un corpus grande.

• Sin resolución de citas en streaming. Las chips se renderizan después de que un mensaje se completa, no a mitad de transmisión.

Stack

Next.js 16.3.1 · React 19.2.8 (pinned — R3F 9 peers >=19 <19.3) · TypeScript · Tailwind v4.3.3 · Velite + Zod · three 0.185.1 + R3F 9.7.0 (pinned) · Vercel AI Gateway

Licencia

MIT — ver LICENSE.