Mismo input, distintos outputs

La prueba

Hasta acá fue análisis estructural — filosofía, código, trade-offs. Ahora corremos la misma pregunta en los 4 frameworks y leemos lo que produjo cada uno. Las diferencias visibles revelan personalidades que el análisis estructural no muestra.

La pregunta:

“¿Cuál es la diferencia entre Hexagonal y Clean Architecture?”

Multi-doc (los dos temas tienen archivos separados en el corpus), conceptual, ambigua (no pide nada técnico específico). Buena para mostrar diferencias entre retrievers y generadores.

Los comandos:

pnpm vercel:query "¿Cuál es la diferencia entre Hexagonal y Clean Architecture?"
pnpm langchain:query "¿Cuál es la diferencia entre Hexagonal y Clean Architecture?"
pnpm llamaindex:query "¿Cuál es la diferencia entre Hexagonal y Clean Architecture?"
pnpm mastra:query "¿Cuál es la diferencia entre Hexagonal y Clean Architecture?"

Lo que sigue son los outputs reales capturados en una corrida del 2026-05 sobre el corpus del repo. Tu corrida puede diferir un poco — llama3.2:3b no es determinista al 100% sin temperature=0, y los frameworks evolucionan.

Vercel AI SDK

=== Answer ===
La respuesta correcta no se puede determinar a partir del contexto
proporcionado, ya que la pregunta parece estar buscando una referencia
directa o una explicación detallada sobre la diferencia entre estas
dos arquitecturas. No hay suficiente información en el texto
proporcionado para brindar una respuesta clara y concisa.

En resumen, aunque tanto Hexagonal (Ports and Adapters) como Clean
Architecture buscan aislar la lógica de negocio del mundo exterior y
mejorar la modularidad y la maintainabilidad de las aplicaciones, no
hay suficiente información en el contexto dado para distinguir entre
estas dos arquitecturas y explicar con claridad su diferencia.

=== Sources ===
  - clean-architecture.md (score: 0.6737)
  - screaming-architecture.md (score: 0.6529)
  - screaming-architecture.md (score: 0.6516)
  - hexagonal-architecture.md (score: 0.6471)

Lectura:

Top-1 es Clean Architecture (0.6737): el retriever identificó correctamente uno de los dos temas.
Posiciones 2 y 3 son Screaming Architecture: contaminación. El embedding de “diferencia entre arquitecturas” matcheó chunks que comparan/contrastan arquitecturas en general, no específicamente Hexagonal.
Hexagonal aparece en posición 4 (0.6471): está, pero relegado.
La respuesta del LLM es ambivalente: dice “no se puede determinar” pero después da una respuesta razonable. Comportamiento típico de llama3.2:3b con prompts anti-alucinación: prefiere admitir “no sé” antes de inventar, pero después intenta de todos modos.

LangChain.js

--- Answer ---

[5] (file: architecture-comparison.md, score: 0.6381)
# Comparación de arquitecturas

Hexagonal Architecture (Ports and Adapters) y Clean Architecture son dos
enfoques arquitectónicos diferentes que comparten el objetivo de aislar
la lógica de negocio del mundo exterior.

La principal diferencia entre las dos es cómo se aborda la dependencia
entre capas.

- **Clean Architecture** se centra en crear una estructura concéntrica
  con reglas de dependencia estricta...
- **Hexagonal Architecture** se centra en aislar el núcleo de la
  aplicación (dominio) de los detalles externos...

En resumen, Clean Architecture se enfoca en crear un código fuerte y
modular, mientras que Hexagonal Architecture se enfoca en crear un
sistema flexible y adaptable a diferentes tecnologías.

--- Sources ---

  clean-architecture.md  (score: 0.6737)
  screaming-architecture.md  (score: 0.6529)
  screaming-architecture.md  (score: 0.6516)
  hexagonal-architecture.md  (score: 0.6471)

Lectura:

Mismos chunks que Vercel (mismos filenames, mismos scores). LangChain y Vercel usan distintos clientes para Qdrant pero los retrievers convergen en este caso.
La respuesta empieza con [5] (file: architecture-comparison.md, score: 0.6381): ¡el LLM inventó una fuente! No existe architecture-comparison.md en el corpus. Mirá los Sources reales — son 4 chunks, numerados [1] a [4]. El [5] es alucinación.

El system prompt del repo le pedía al LLM “for each piece of information you use, cite the source filename in brackets”. El context que arma query.ts numera los chunks con [1], [2], etc. El modelo aprendió el patrón y lo extrapoló: cuando quiso citar una afirmación que NO está en ningún chunk, generó un [5] con un filename plausible.

Esto NO es bug de LangChain. Es bug del prompt template. La citation explícita del Nivel 3 / cap 05 (el patrón con validación de unmatched marks) hubiera detectado este [5] como out-of-range.

Update post-curso: el prompt fue corregido — la instrucción de “cite the source filename” se removió en packages/02-langchain/src/query.ts. La salida actual del comando ya no produce el [5] alucinado. La captura de arriba se mantiene como snapshot histórico porque la lección sigue intacta: pequeños detalles del prompt template producen diferencias visibles en la salida, y esos detalles importan más que la elección del framework.

El cuerpo de la respuesta es razonable: el LLM sí distingue Clean de Hexagonal y arma un resumen útil, a pesar de que los chunks #2 y #3 (Screaming) eran ruido. Mérito del modelo, no del retriever.

LlamaIndex.TS

Question: ¿Cuál es la diferencia entre Hexagonal y Clean Architecture?

--- Answer ---

Basado en el contexto proporcionado, la diferencia entre Hexagonal y
Clean Architecture se centra en su enfoque y principios.

**Clean Architecture** (Arquitectura Limpia) se centra en organizar el
código en capas concéntricas con una regla de dependencia estricta:
**las dependencias del código fuente solo pueden apuntar hacia adentro**.
Su objetivo es aislar la lógica de negocio (dominio) del mundo exterior...

**Hexagonal Architecture** (Arquitectura Hexagonal), por otro lado, se
centra en crear interfaces chicas y específicas entre los módulos de
alto nivel y los módulos de bajo nivel. Cada cliente debe depender
solo de lo que necesita, sin importar la implementación concreta...

--- Sources ---

  screaming-architecture.md  (score: 0.6045)
  screaming-architecture.md  (score: 0.5961)
  clean-architecture.md  (score: 0.5908)
  solid-principles.md  (score: 0.5907)

Lectura:

Los chunks recuperados son DISTINTOS a Vercel/LangChain. El top-1 es Screaming Architecture (0.6045) en vez de Clean (0.6737). Hexagonal no aparece en el top-4.
Scores son menores en absoluto (0.59-0.60 vs 0.65-0.67 de los otros). LlamaIndex normaliza embeddings ligeramente distinto vía QdrantVectorStore — la asimetría que documentamos en cap 05 visible en la práctica.
La respuesta es la mejor de los 4: distingue Clean de Hexagonal con detalles específicos (“regla de dependencia estricta”, “puertos”, “interfaces chicas”). Incluso menciona el principio de inversión de dependencias (que viene del chunk de SOLID).

¿Cómo da una respuesta tan buena con chunks supuestamente “peores”? Tres razones:

El chunk de Clean Architecture aparece en posición 3 (no 1), pero sigue dentro del top-K que va al prompt.
El chunk de SOLID (“solid-principles.md”) tiene contenido sobre dependencias que el LLM combinó bien con Clean.
El response synthesizer de LlamaIndex (asQueryEngine) tiene su propio prompt template, distinto al de los otros 3. Los detalles del prompt template afectan más que los chunks marginales.

Mastra (modo Naive)

=== Answer ===
La principal diferencia entre Hexagonal Architecture y Clean
Architecture es que Clean Architecture se centra en separar lógica
de negocio de detalles externos, mientras que Hexagonal Architecture
se enfoca en aislar el núcleo de la aplicación (la lógica de
negocio) de los detalles externos a través de interfaces llamadas
**puertos**.

En Clean Architecture, las capas son más rígidas y estrictas, con
una regla de dependencia que establece que las dependencias del
código fuente sólo pueden apuntar hacia adentro. Las capas son más
abstractas y generales, lo que permite una mayor flexibilidad y
reutilización de código.

En Hexagonal Architecture, los puertos (interfaz) se utilizan para
conectar el dominio con el mundo exterior, y los adaptadores se
encargan de implementar estas interfaces con tecnologías específicas.

=== Sources ===
  - clean-architecture.md (score: 0.6737)
  - screaming-architecture.md (score: 0.6529)
  - screaming-architecture.md (score: 0.6516)
  - hexagonal-architecture.md (score: 0.6471)

latency: 7362 ms

Lectura:

Chunks idénticos a Vercel/LangChain (mismos filenames, mismos scores). Mastra Naive y Vercel usan misma estrategia de retrieve.
La respuesta es directa y útil, sin la duda inicial que tuvo Vercel ni la alucinación de fuente que tuvo LangChain.
Latencia 7362 ms — la más alta de los 4. Mastra tiene overhead de bookkeeping del agent runtime aunque el modo Naive no lo use directamente.
El modo Agent (modo B) falló por la incompatibilidad de versiones que documentamos en cap 06. Solo capturamos Naive.

¿Por qué la misma pregunta da respuestas distintas?

Mismos chunks (en 3 de 4 frameworks). Mismo modelo (llama3.2:3b). Mismo Qdrant. Mismo corpus. ¿Qué explica las diferencias?

El prompt template

Cada framework arma el prompt con un formato sutilmente distinto:

Framework	Cómo presenta el contexto al LLM
Vercel	`Context:\n[filename1]\ncontent1\n\n---\n\n[filename2]\ncontent2...`
LangChain	`Context:\n[1] (file: name1, score: 0.6737)\ncontent1\n\n---\n\n[2] ...`
LlamaIndex	El response synthesizer interno (no expuesto, depende de la versión)
Mastra	`Context:\n[1] (name1, score=0.6737)\ncontent1\n\n[2] ...`

Con la misma información de fondo, los detalles de presentación afectan cómo el LLM la procesa. Los [N] numbered prefixes en LangChain probablemente lo empujan a citar — y así apareció el [5] alucinado.

Las instrucciones del system prompt

Vercel y Mastra usan: “answer using ONLY the context. If not enough info, say so”.

LangChain agrega: “for each piece of information you use, cite the source filename in brackets”.

LlamaIndex usa el prompt interno de su response synthesizer (no es directamente comparable).

La instrucción de citar en LangChain es la causa directa del [5] inventado. Sin ella, probablemente la salida sería más parecida a la de Vercel.

Las versiones del client a Qdrant

LlamaIndex usa @llamaindex/qdrant. Los otros 3 usan @qdrant/js-client-rest directamente (Vercel) o vía wrappers más finos (LangChain, Mastra). Los wrappers aplican normalizaciones distintas a los embeddings — eso explica por qué LlamaIndex retrieve chunks distintos con la misma pregunta.

La conclusión pedagógica

Tres lecciones de este experimento:

El framework cambia menos de lo que parece. 3 de 4 retrieve los mismos chunks. La mayoría de las diferencias visibles vienen del prompt template, no del framework.
Pequeños detalles del prompt importan mucho. La instrucción de “cite the source” en LangChain produjo una alucinación que ningún otro framework tuvo. Antes de blame al framework, revisá tu prompt.
La métrica retrieval@k puede mentir entre frameworks. LlamaIndex retrieveó chunks “peores” según scores absolutos pero produjo la respuesta más útil. Las métricas absolutas son orientativas — la calidad final depende de cómo el LLM use el contexto.

Lo que viene

Vimos diferencias cualitativas. Ahora las medimos cuantitativamente con el harness corriendo los 4 frameworks side-by-side sobre las 12 preguntas del golden set.