Skip to main content
Glama

QoH MCP · Evaluación de un agente de inventario con LLMs locales

Servidor MCP que expone una herramienta de stock por almacén (QoH, quantity on hand) a un LLM local vía Ollama, y la suite de evaluación con la que se llevó de 71 % a 100 % en el set de desarrollo y a 75 % en bruto / 88 % corregido en un held-out nunca usado para iterar, analizando errores y cambiando una sola cosa por experimento.

Los datos son sintéticos: un snapshot de 16 filas inspirado en un catálogo de gestión de cables. No contiene datos reales de ninguna empresa.

Resultados

Configuración final: qwen2.5:7b · prompt v3 · num_ctx 8192 · --ground-check. Métricas puntuadas con los graders actuales (g5); entre paréntesis, el resultado bruto que dio la ejecución con los graders de su momento.

Conjunto

Preguntas

Acierto

Tools correctas

Groundedness

Latencia media

Desarrollo (usado para iterar), 2 ejecuciones

17

100 % · 100 %

94 %

100 %

34,6 s · 32,2 s

Held-out (nunca usado para iterar)

8

88 % (75 % bruto)

100 %

100 %

45,8 s

La cifra que vale es la del held-out: el set de desarrollo está inflado por definición, porque el sistema se ajustó mirando sus fallos. La diferencia entre el 75 % bruto y el 88 % es un falso negativo del evaluador en H06 que se corrigió de forma general (ver abajo); se publican las dos.

Cómo se llegó ahí

#

Cambio (uno por experimento)

Acierto dev bruto

Repuntuado g5

Qué se aprendió

1

Baseline: prompt v1

71 %

76 %

5 fallos: 1 grader, 1 límite del modelo (aritmética), 1 prompt, 2 diseño/descripción de tools

2

Arreglos de tools + prompt v2

76 %

76 %

El prompt v2 arregló un caso límite y rompió dos casos normales

3

Solo num_ctx 8192

76 %

76 %

Sin efecto: hipótesis de contexto truncado rechazada con datos

4

Solo prompt v3

82 %

94 %

Las 2 "regresiones" (Q12, Q15) eran falsos negativos del grader

5

Solo --ground-check (reflexión)

100 %

100 %

Elimina la cifra inventada de la pregunta de varios pasos; groundedness 94 % → 100 % por +32 % de latencia

Comparación de modelos (mismo prompt v3 y mismo eval, g5): qwen2.5:7b 94 % / 26 s frente a llama3.1:8b 71 % / 54 s. El modelo más pequeño gana.

Validación del LLM juez contra etiquetas humanas

53 trazas distintas etiquetadas a mano (38 PASS / 15 FAIL) con trace_viewer.py, repartidas de forma fija en DEV (24) y TEST (29). Positivo = PASS; el TNR mide si el juez caza los fallos.

Juez (qwen2.5:7b)

TPR TEST

TNR TEST

Kappa TEST

¿Fiable (≥ 90 %)?

j1 zero-shot

71 %

75 %

0,40

No

j1 + few-shot con críticas de DEV

86 %

50 %

0,37

No

j2 (rúbrica corregida + argumentos de las tools)

pendiente

pendiente

pendiente

—

Lo que mostró el análisis de los desacuerdos:

  • Con 4 FAIL, el few-shot parecía una gran mejora (kappa 0,07 → 0,43); con 15 FAIL no lo es. Con pocos negativos, el TNR solo puede valer 0 %, 50 % o 100 %: las muestras pequeñas engañan.

  • Los fallos del juez eran sobre todo de diseño, no de capacidad: la rúbrica se contradecía ("responde a lo que se pregunta" suspendía rechazos correctos, 5 casos), el juez no veía los argumentos de las tools (no podía detectar warehouse="total") y no tenía regla para la pregunta ambigua. j2 corrige las tres.

  • Lo que el juez no sabe hacer (verificar cálculos o el sentido de una comparación) ya lo hacen los graders deterministas. El juez solo se usa donde el código no llega.

  • El juez también destapó un error de etiquetado humano (Q14 de llama: omite un SKU bajo mínimos y lo etiqueté como PASS), pendiente de revisar.

  • Por eso las cifras de este README salen de graders deterministas; el juez solo decide en las 2 preguntas abiertas, y con su validación documentada.

Held-out: fallos y cómo se trataron

Regla: el sistema (prompt, tools, modelo) no se tocó tras ver el held-out. Solo se corrigió el evaluador cuando el fallo era de medición, con un arreglo general y un test de regresión.

  • H04 — fallo real del modelo. Debía listar los SKUs con más stock virtual que físico; listó todas las discrepancias e invirtió el sentido. Trabajo futuro: que la tool devuelva la discrepancia con signo.

  • H06 — falso negativo del evaluador. Rechazo correcto ("se centran en el inventario, no en el plazo de entrega"), que el detector de rechazos por frases no reconocía (4.º caso). Ahora basta una negación explícita, y lo que protege es la comprobación de que no se filtran SKUs ni cifras inventadas.

  • H02 — falso positivo de groundedness. "$9.10" se interpretaba también como 910 (punto de miles) y se marcaba como cifra inventada, lo que disparó una reflexión innecesaria (latencia extra). Ahora un número está respaldado si alguna de sus interpretaciones aparece en los datos. Mismo bug en Q07 del set de desarrollo ("$6,599.68").

  • Trabajo futuro: normalizar el SKU en la tool (cbl1042 → CBL-1042); hoy lo resuelve el modelo.

Related MCP server: HomeStock

Lecciones

  1. Analiza los errores antes de tocar el prompt. En el primer análisis, solo 1 de 5 fallos se arreglaba con el prompt; el resto eran del grader, de las tools o un límite del modelo.

  2. El evaluador también se evalúa. 6 de los 14 fallos investigados (43 %) eran bugs de los graders, no del modelo. Cada salida real que destapa un bug se convierte en un test de regresión (73 tests).

  3. No pidas cálculos al LLM. Los totales y valores se calculan en la tool.

  4. Groundedness ≠ acierto. Una respuesta puede contener la cifra correcta y además otra inventada.

  5. Un cambio por experimento y graders versionados; si cambia el grader, repuntúa lo antiguo.

Estructura

Archivo

Qué hace

qoh_mcp_server.py

Servidor MCP con 4 tools: get_stock, list_stock_discrepancies, list_price_discrepancies, list_low_stock

data/qoh_snapshot_2026-10-22.csv

Snapshot congelado: la única fuente de verdad del eval

eval_set_qoh.yaml

Set de desarrollo: 17 preguntas (consulta, agregación, comparación, casos límite, fuera de alcance, varios pasos, abierta)

eval_holdout_qoh.yaml

Held-out: 8 preguntas nuevas, ejecutadas una sola vez con la configuración congelada

graders.py

Puntuación determinista: exact match, tolerancia numérica, booleano, precision/recall, rechazo, aclaración, groundedness

run_evals.py

Bucle de agente (Ollama + MCP), reintentos ante caídas, LLM juez para preguntas abiertas, informe JSON

compare_runs.py

Compara dos ejecuciones pregunta a pregunta (arreglos y regresiones)

regrade.py

Repuntúa una ejecución guardada con los graders actuales, sin volver a llamar al modelo

trace_viewer.py

Visor de trazas en Streamlit con anotación humana (PASS/FAIL, crítica, modo de fallo) y conteo de modos de fallo

validate_judge.py

Valida el LLM juez contra las etiquetas humanas: TPR, TNR y kappa en DEV y TEST

labels/human_labels.json

53 etiquetas humanas del experto (PASS/FAIL, crítica, modo de fallo)

tests/

Tests del evaluador (respuesta buena pasa, mala falla) y end-to-end sin LLM

results/published/

Informes JSON brutos de las ejecuciones citadas; regraded/ = repuntuados con g5

Uso

pip install -r requirements.txt
ollama pull qwen2.5:7b

python -m pytest tests -q                                   # 1) el evaluador funciona
python run_evals.py --prompt v3 --num-ctx 8192 --ground-check   # 2) eval de desarrollo
python run_evals.py --eval eval_holdout_qoh.yaml --prompt v3 --num-ctx 8192 --ground-check
python compare_runs.py                                      # compara las dos últimas ejecuciones

streamlit run trace_viewer.py                               # revisar y etiquetar trazas
python validate_judge.py                                    # ¿coincide el juez con el experto?
python validate_judge.py --fewshot                          # juez con las críticas de DEV como ejemplos

Opciones: --model, --judge-model, --only Q01,Q11, --cpu, --prompt v2|v3, --num-ctx, --ground-check.

Decisiones de diseño

  • Determinista primero: todas las preguntas salvo la abierta se puntúan con código; el juez se contrasta con un recall de SKUs de referencia porque un juez sin validar no decide solo.

  • Dos métricas separadas: acierto de la respuesta y acierto de las tools (nombre, orden y argumentos válidos), para distinguir "razonó mal" de "eligió mal la herramienta".

  • Tests de alucinación: SKU inexistente, búsqueda imposible, pregunta ambigua y fuera de alcance.

  • Errores de infraestructura aparte: una caída de Ollama se reintenta y, si persiste, no cuenta como fallo del modelo.

  • Prompts y graders versionados (--prompt, GRADER_VERSION), registrados en cada informe.

  • Groundedness: toda cifra de la respuesta debe aparecer en la salida de alguna tool. Con --ground-check, si el modelo inventa una cifra se le pide que corrija una vez (reflexión).

Limitaciones

  • Eval pequeño (17 + 8 preguntas) y una ejecución por configuración: el modelo no es del todo determinista, así que las diferencias de una pregunta (≈6 puntos) no son significativas.

  • El groundedness es una heurística numérica: puede marcar datos derivados (porcentajes) como no respaldados.

  • El juez es el mismo modelo de 7B que se evalúa y no supera el umbral de fiabilidad (ver «Validación del LLM juez»). La partición TEST ya se ha mirado para diseñar j2: una validación limpia de j2 necesita etiquetas nuevas.

Licencia

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables document retrieval, OCR, web search, and calculator tools via a RAG pipeline and LangGraph agent, all running locally with Ollama.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage a local-first household inventory, recording receipt emails and maintaining a probabilistic estimate of stock levels. Provides tools to query stock, identify items to reorder, and correct ingestion errors, all without any cloud dependency.
      19
      1
      Functional Source , Version 1.1, MIT Future
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables an AI agent to query a warehouse management system for orders, stock, stalled orders, and audit logs, and to make narrowly scoped writes by changing order status with a required reason or appending notes, with all writes recorded in a full audit trail.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage inventory conversationally: list and look up products, check current stock levels, record inbound and outbound movements idempotently, review movement history, and surface items below their minimum threshold. Every figure is grounded in tool calls rather than model estimation, and invalid operations return explicit error codes the agent can reason about.
      5
      MIT