Entendiendo los Quality Scores

Planes: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓

Lee esto antes de mostrar los scores a un cliente

Los Quality Scores en cada producto (Durability, Quality Perception, Value for Money, Price Positioning, Typical Competitors) están 100% generados por el LLM a partir del texto del producto. No están respaldados por reviews, devoluciones, datos de ventas, certificaciones ni ninguna evidencia externa — aún.

Qué usa el LLM

Al puntuar un producto, Clione pasa al LLM:

• Title
• Description
• Price + currency
• Vendor
• Categories
• Cualquier respuesta que aportaste en el Enrichment Wizard (target audience, materials, key benefits, etc.)

Qué NO usa el LLM

• Reviews reales de clientes (Google / Trustpilot / interno)
• Tasa de devoluciones
• Datos de ventas / conversión
• Comparativos de catálogo externo
• Certificaciones del fabricante (ISO, CE, GOTS, OEKO-TEX, etc.)
• Resultados de tests de ciclo de vida
• Bases de datos de sostenibilidad

Qué significa esto para ti

1. Los scores son opinión sintética, no hechos verificados.
2. Un mismo producto puede producir scores distintos entre ejecuciones si la temperatura del modelo es distinta de cero.
3. Útiles relativamente, no absolutamente — el LLM tiene sentido común (Hermès → luxury, Primark → budget). Los scores te ayudan a diferenciar productos dentro de tu propio catálogo; no te comparan contra competidores.
4. typical_competitors tiene la misma limitación — son inferencias plausibles, no datos verificados de mercado.

Cómo saber qué scores están grounded

Cada producto muestra un badge junto a los Quality Scores:

• 🟢 Data-grounded — evidencia externa respalda el score (futuro: reviews, devoluciones, certificaciones)
• 🔵 AI + owner hints — rellenaste el Enrichment Wizard para este producto
• 🟡 AI-inferred — opinión LLM pura basada en title/description/vendor (por defecto)

Cómo lo estamos arreglando

Ya entregado (abril 2026)

Enrichment Wizard — preguntas de evidencia. El Wizard ahora tiene una sección dedicada Evidence tras las preguntas de contexto originales. Cinco nuevos campos, todos opcionales:

• Warranty — None / 6m / 1y / 2y / 3y / 5y / 10y / Lifetime
• Certifications — lista separada por comas (ISO 9001, CE, GOTS, OEKO-TEX, MIL-STD-810, B-Corp, Fair Trade, etc.)
• Returns rate — brackets de <2% a >20%, más un opt-out Don't know
• Customer reviews — rating agregado + recuento desde cualquier fuente (Google, Trustpilot, interno, marketplaces)
• Manufacturing origin — país + nombre del fabricante

Rellenar 3+ de estos sube el badge de tu producto de ámbar (AI-inferred) a verde (Data-grounded). Rellenar 1-2 sube a cyan (AI + owner hints). El wizard te avisa cuando llegas a la sección de evidencia y qué hace rellenarla.

Typical Competitors verificados por el owner. La pestaña Edit en un producto ahora tiene una sección Typical Competitors donde puedes listar los productos competidores reales (brand + model + precio de referencia opcional + notas). Cuando al menos una entrada está guardada, Clione marca la lista como verificada por el owner y deja de permitir al LLM regenerarla en el re-enriquecimiento. Es el mismo patrón de grounding que el wizard de evidencia — tu input gana sobre la conjetura del LLM.

Si no rellenas nada, los competidores inferidos por el LLM siguen apareciendo con una etiqueta AI-INFERRED para que siempre sepas lo que estás mirando.

Roadmap (próximamente)

1. Conectores de datos externos — tasa de conversión de Google Analytics, APIs de reviews de Judge.me y Yotpo, API de Refunds de Shopify / webhook de Returns de BigCommerce
2. Procedencia por score — cada score individual lleva su propio source (owner / reviews / returns / llm_synthetic / composite) con rastro de evidencia, y la UI muestra por qué este score bajo demanda
3. Scoring compuesto — cuando varias fuentes no coinciden, el dashboard explica el resultado ponderado en lugar de elegir uno y ocultar los demás

Consulta el roadmap completo de grounding para detalle técnico.

Hasta que aterricen los conectores externos, trata los scores como la lectura del LLM sobre el texto de tu catálogo, afilada por la evidencia + competidores que le aportes vía el Wizard y la pestaña Edit.

Notas por plataforma

El modelo de scoring es idéntico entre plataformas. Lo que difiere es la riqueza del input que el sincronizador puede extraer y la superficie que expone los scores.

BigCommerce

• El sincronizador lee meta_keywords, search_keywords, brand, options, custom fields y category path. Cuanto más rico, más afilados los scores.
• Los BC Reviews (built-in) aún no se incorporan al scoring — el conector está en el roadmap. Si tienes reviews activos, vuelca una muestra representativa en la descripción del producto para que el LLM vea el lenguaje.
• Los Channels de BigCommerce con price books distintos no se puntúan por separado — el scoring usa los precios del channel por defecto.

Shopify

• El sincronizador lee productType, vendor, todos los tags, variantes (size/color/material) y pertenencias a collections (manuales + smart).
• Las reviews de Shopify Reviews / Judge.me / Stamped aún no se incorporan al scoring. Mismo workaround que en BC: parafrasea reviews representativas en la descripción.
• Los Markets de Shopify con divisas y precios distintos no se puntúan por separado — el scoring usa el Market principal.

Cómo aparece el score badge en el storefront

Los scores nunca se exponen literalmente en el storefront. Son una señal interna usada para:

• Rankear productos en los listados ordenables de tu propio dashboard.
• Informar el párrafo de razonamiento del LLM (que sí se expone vía la API /llm y el description del JSON-LD).
• Alimentar la franja "Typical Competitors" de la página pública Pulse (si haces opt-in).

Si quieres publicar una señal derivada de score (p. ej. un badge "editor's pick"), usa el módulo Promotions para codificarla como trigger de cupón con clave en un rango de score.

Auditar scores en bulk

El listado de Products tiene un filtro por columna Score — elige un único score (p. ej. Durability) y ordena de alto a bajo para detectar outliers. Si un producto de gama alta muestra un durability bajo, probablemente el LLM no haya visto suficiente texto de descripción para inferirlo; abre la pestaña Edit y añade una frase sobre construcción.

Resolución de problemas

Un producto premium muestra Price Positioning de budget — El LLM pondera el input de precio frente al lenguaje de la descripción. Si vendes una silla de 2000€ y la descripción no menciona craftsmanship, materiales o herencia de marca, el LLM puede anclarse en la categoría (sillas) en lugar de en la marca. Solución: amplía la descripción, o añade la herencia de marca al Wizard.

Mismo producto, scores distintos al re-enriquecer — Comportamiento esperado con temperatura > 0. Bloquea el score rellenando la sección de evidencia del Wizard — una vez 3+ campos de evidencia están rellenos, el LLM se ciñe mucho más y las re-ejecuciones convergen.

El score badge se queda ámbar incluso tras rellenar el wizard — El badge requiere 3+ campos de evidencia más una ejecución de re-enrich. Rellenar el wizard no actualiza retroactivamente los enrichments existentes. Pulsa Enrich en el detalle del producto para regenerar.

Typical Competitors sigue regenerándose pese a entradas verificadas por el owner — Asegúrate de que al menos una fila de competidor está guardada con todos los campos requeridos (brand + model). El flag owner-verified solo se activa cuando hay al menos una fila completa.

Los scores parecen inconsistentes entre categorías de la misma tienda — El LLM puntúa dentro del contexto del catálogo, pero no normaliza entre categorías. Un par de calcetines "high quality" es un listón absoluto distinto a un colchón "high quality". Es por diseño — la idea es usar scores para rankear dentro de una categoría, no entre categorías.

Referencia de campos de score

Cada enriquecimiento de producto produce estos campos de score:

Campo	Tipo	Rango	Significado
durability	float	1.0 – 5.0	Build / longevidad inferida.
quality_perception	float	1.0 – 5.0	Calidad percibida inferida.
value_for_money	float	1.0 – 5.0	Ratio precio-calidad inferida.
price_positioning	enum	budget / mid / premium / luxury	Segmento de mercado inferido.
typical_competitors	array	hasta 5 entradas brand+model	Set competitivo inferido.
confidence	float	0.0 – 1.0	Confianza propia del LLM en los scores (más alta = datos de fuente menos ambiguos).
evidenceSources	array	strings	Qué campos de evidencia usó el LLM: owner_wizard, description, vendor_brand, category_context.

Categorías, collections y pages no obtienen scores — el modelo de score es específico de producto. Sí obtienen los mismos artefactos identity + reasoning + keywords.

Dónde se exponen los scores vía API

Si quieres consumir scores desde tu propia analítica:

• GET /api/v1/products/:id/enrichment devuelve el payload completo de enriquecimiento incluyendo todos los campos de score y el array evidenceSources.
• GET /api/v1/public/seo-signals/:platform/products/:id expone el meta + JSON-LD orientado a cliente pero no los scores crudos.

Los scores crudos no se exponen deliberadamente en endpoints públicos — son una señal interna, no una afirmación pública.

Cuándo re-enriquecer vs confiar en los scores existentes

Tres triggers justifican un re-enrich:

1. Añadiste evidencia al Wizard — re-enriquece para que el LLM use la nueva evidencia y el badge pase de ámbar a verde.
2. Cambiaste sustancialmente la descripción — el sync trajo el nuevo texto pero el LLM puntuó sobre el texto antiguo hasta que re-enriqueces.
3. Añadiste competidores verificados por el owner — re-enriquece para impedir al LLM regenerar la lista de competidores.

No re-enriquezcas solo porque un score no te guste — el re-enriquecimiento consume un crédito y es poco probable que los scores oscilen mucho a menos que los inputs cambien.

Referencia de colores del score badge

Badge	Color	Significado	Qué lo dispara
Green	Data-grounded	Evidencia externa respalda los scores	3+ campos de evidencia rellenos en el Wizard
Cyan	AI + owner hints	Algún input del owner	1-2 campos de evidencia rellenos
Amber	AI-inferred	Opinión LLM pura	Ningún campo de evidencia relleno
Grey	Not enriched	Aún no ha corrido enrichment	Estado por defecto

Los badges aparecen junto al bloque de scores en cada página de detalle de producto y en los CSV exportados.

Auditar los scores de un único producto

Cuando los scores de un único producto se ven raros, el orden de diagnóstico es:

1. Abre el producto → pestaña Enrichment → mira los valores de score + color del badge.
2. Abre la pestaña Corpus — mira exactamente qué texto se le dio al LLM. Si la descripción es escasa o tiene contenido no relacionado (p. ej. instrucciones de un SKU distinto), arregla primero la descripción.
3. Abre el Wizard — rellena cualquier campo de contexto + evidencia no rellenado.
4. Re-enriquece.
5. Compara contra el enriquecimiento anterior vía la pestaña Versions para ver qué cambió.

Cuando los scores fluctúan en la misma ejecución de enriquecimiento

¿Bulk-enriqueces 100 productos y notas que el producto 50 puntuó distinto que uno similar en posición 5? El LLM trata cada llamada independientemente (no hay contexto compartido entre productos del mismo batch). Una variabilidad run-to-run de ±0.3 sobre una escala 1-5 es normal.

Para minimizar la fluctuación:

• Rellena el Wizard para los SKUs hero (bloquea evidencia).
• Usa la opción Lock scores after first enrich del Enrichment Wizard (Pro/Agency) — una vez activada, el re-enrich preserva los valores de score y solo actualiza los campos de texto.

Decisión: cómo usar los scores en tus dashboards

Trata los scores como señales relativas dentro de la misma categoría. Buenos usos:

• Rankear productos dentro de una categoría para destacar items de alta calidad.
• Filtrar el catálogo para encontrar productos con score bajo que necesitan actualización de descripción.
• A/B testear cambios de descripción — re-enriquece y observa el shift de score.

Malos usos:

• Afirmaciones de marketing ("¡valorado 4.5 por IA!" — consulta "Por qué no fabricamos ratings" en Configuración de reviews).
• Comparaciones entre categorías.
• Decisiones de pricing (el LLM no ve datos reales de demanda).
• Benchmarking de vendors (puntúa lo que hay en el texto, no lo que es cierto).

Estabilidad de score entre los cuatro tipos de entidad

Solo los productos obtienen el bloque completo de quality-score. Los demás tipos de entidad obtienen una vista más simple:

• Categories / Collections — popularity_indicator (inferido por el LLM del mix de productos), audience_clarity (1-5).
• Pages — content_freshness, intent_clarity, target_audience_match.

Estos se guardan en cada entidad y no se propagan al storefront — son señales internas usadas por la propia organización de catálogo de Clione.