El harness en 30 minutos

1Qué vas a montar — y qué NO es

Vienes a este apéndice porque necesitas medir a Magallanes y no hiciste el curso de evals. Este recetario te da el instrumento mínimo y nada más.

Prerequisitos:

• Magallanes corriendo (el esqueleto de L1).
• Python 3.
• Node ^20.20 o ≥22.22 instalado.
• Un encargo de prueba con su corpus de documentos del lab.

Vas a montar tres piezas:

• promptfoo — el runner de evals: toma prompts, los pasa a tu agente, aplica comprobaciones (assertions) y emite una tabla de resultados.
• un provider Python — el adaptador que conecta promptfoo con Magallanes; promptfoo le pasa el prompt, él invoca al agente y devuelve la salida.
• tres comprobaciones — cobertura de subtemas, citas a documentos reales y coherencia del informe.

Lo que NO es esto: un sistema de evaluación serio. No hay error analysis (mirar fallos uno a uno y agruparlos por causa). No hay juez validado contra humanos (un llm-rubric que sabes que concuerda con tu criterio). Sin esas dos cosas, los números absolutos no son fiables.

El instrumento serio lo construye el curso Evals y Observabilidad de sistemas LLM. Cuando necesites decisiones que dependan del score exacto, ese es tu sitio. Aquí buscamos otra cosa: comparar longitudes entre sí en el sweep, y para eso el mínimo alcanza (sección 7).

2Instalar promptfoo

promptfoo se distribuye por npm. La serie verificada para este curso es v0.121.x, que exige Node ^20.20 o ≥22.22.

1npm install -g promptfoo@0.121.15
2promptfoo --version

Si la versión no aparece, revisa tu Node con node --version antes de seguir. Una versión de Node por debajo del rango rompe la instalación sin un mensaje claro.

3El provider Python: my_provider.py

El provider es el puente entre promptfoo y tu agente. promptfoo no sabe qué es Magallanes; sabe llamar a una función con una firma fija y leer lo que devuelve.

Esa firma es exacta. No la cambies:

1# my_provider.py
2def call_api(prompt: str, options: dict, context: dict) -> dict:
3    return {"output": "...", "tokenUsage": {"total": 0}}   # output requerido

Lee la firma entera antes de la explicación. Tres parámetros entran, un diccionario sale.

• prompt — el texto que promptfoo construyó desde tu plantilla (el encargo para Magallanes).
• options y context — metadatos que promptfoo pasa; los recibes aunque no los uses.
• El retorno es un diccionario. La clave output es requerida: es el texto sobre el que correrán las comprobaciones. tokenUsage.total reporta tokens consumidos.

Dentro de call_api, invocas a Magallanes con el prompt como encargo y devuelves el informe que produce como output. La forma de invocar a tu grafo la tienes en L1; aquí solo la envuelves:

Reemplaza el cuerpo del esqueleto anterior por la invocación real — es el mismo archivo, no uno nuevo:

1# my_provider.py — el provider invoca a Magallanes
2from magallanes import graph   # tu grafo de L1
3
4def call_api(prompt: str, options: dict, context: dict) -> dict:
5    result = graph.invoke({"messages": [{"role": "user", "content": prompt}]})
6    informe = result["messages"][-1].content   # el informe que escribió Magallanes
7    return {"output": informe, "tokenUsage": {"total": 0}}

Es común olvidar la clave output o llamarla result. Si lo haces, promptfoo no encuentra qué evaluar y la comprobación falla sin medir nada. La clave se llama output, en minúsculas.

4El promptfooconfig.yaml mínimo

El config conecta las tres piezas: qué provider usar, qué prompts enviar y qué comprobar en la salida.

Si nunca usaste promptfoo, el YAML puede parecer circular. Léelo de fuera hacia dentro: primero providers (quién responde), luego prompts (qué se le pide), luego tests (cómo se juzga).

1# promptfooconfig.yaml mínimo con provider Python
2providers:
3  - id: 'file://my_provider.py'
4prompts:
5  - 'Investiga: {{query}}'
6tests:
7  - vars: { query: "..." }
8    assert:
9      - { type: contains, value: "..." }
10      - { type: llm-rubric, value: "..." }

Pieza por pieza:

• providers apunta a tu fichero con file://my_provider.py. promptfoo carga el módulo y llama a call_api.
• prompts es la plantilla. {{query}} es un hueco que promptfoo rellena con la variable query de cada test.
• tests es la lista de casos. Cada uno fija vars (los valores de los huecos) y assert (las comprobaciones sobre el output).
• assert usa dos tipos aquí. contains comprueba que el output incluye un texto literal. llm-rubric pide a un modelo juez que valore el output contra un criterio en prosa.

Cada test produce un veredicto por assertion. La tabla final agrega esos veredictos.

5Las tres métricas del lab

El sweep de L4 mide tres cosas en cada informe de Magallanes. Cada una usa un tipo de comprobación distinto, y cada tipo tiene una fiabilidad distinta.

1. Cobertura de subtemas — contains. El encargo pide N subtemas; el informe debe tocarlos. Una assertion contains por subtema comprueba que su término aparece. Es determinista: el término está o no está. Mide presencia literal, no profundidad.

1assert:
2  - { type: contains, value: "presupuesto de atención" }
3  - { type: contains, value: "longitud efectiva" }

2. Citas a doc_id reales — contains. El corpus del lab tiene documentos con identificadores conocidos. Magallanes debe citar los que leyó. Comprobar que el informe contiene un doc_id real del corpus es determinista: ese identificador existe en tu biblioteca o es inventado. Esta comprobación caza el poisoning en el que el agente cita una fuente que no existe.

1assert:
2  - { type: contains, value: "doc_042" }

3. Coherencia del informe — llm-rubric. Que un informe no se contradiga ni divague no se comprueba con texto literal. Aquí pides a un modelo juez que lo valore contra un criterio:

1assert:
2  - type: llm-rubric
3    value: "El informe es coherente: las secciones no se contradicen entre sí."

Las dos primeras métricas son deterministas y fiables. La tercera depende del juez, y tu juez aquí no está validado. Recuerda esa diferencia al leer los scores (sección 7).

6Correr y leer resultados

Con el config y el provider en su sitio, lanzas la evaluación:

1promptfoo eval

promptfoo rellena cada prompt, llama a call_api y aplica las assertions. Emite una tabla: una fila por test, una columna por assertion, con pasa o falla en cada celda.

Para verlo en el navegador:

1promptfoo view

La tabla muestra una fila por test case y una columna por assertion; cada celda marca pasa/falla (y el score del llm-rubric).

Lee la tabla por columnas, no por filas. Una columna de contains con muchos fallos te dice qué subtema se cae sistemáticamente. La columna de llm-rubric te dice dónde el informe pierde coherencia. Ese mapa es la materia prima de la curva del sweep.

7Los límites del starter kit

Llegaste hasta aquí con un instrumento que mide, pero que no es de fiar en términos absolutos. Conviene saber exactamente dónde está el límite antes de apoyar decisiones en él.

El llm-rubric no está validado: nadie comprobó que su criterio concuerda con el tuyo en una muestra de informes juzgados a mano. Su score de coherencia es orientativo. Un 0,7 hoy y un 0,7 mañana no garantizan la misma calidad real.

Por eso el sweep de L4 compara valores relativos, no absolutos. Corres la misma tarea a cuatro longitudes y miras cómo cae el score de un punto al siguiente. La pregunta no es "¿cuánto vale este informe?" sino "¿cuánto peor es a 50 documentos que a 10?". Para esa comparación, un juez no validado pero consistente alcanza. El sesgo se aplica a todas las longitudes por igual y se cancela en la diferencia.

Esto deja de alcanzar cuando necesitas el número absoluto. Por ejemplo: certificar a un cliente que el agente supera un umbral, o decidir un despliegue por el score sin compararlo con un baseline. Ahí necesitas error analysis y un juez validado contra humanos.

Eso lo construye el curso Evals y Observabilidad de sistemas LLM. Este harness es el andamio para empezar a medir; el otro curso es la herramienta de precisión. Para diagnosticar a Magallanes en N0, el andamio cumple.