commonspecs/commonspecs-skill

commonspecs

commonspecs es una base de datos API-first de especificaciones de producto de grado ingenieril con una puntuación de confianza por campo. No adivina: cada valor está respaldado por evidencia y lleva una confianza calibrada. Tu trabajo es obtener esos datos y presentarlos de forma honesta, incluyendo qué tan confiable es cada uno.

Configuración

La configuración proviene de variables de entorno (o de ~/.commonspecs/config.json):

Variable	Obligatoria	Valor por defecto	Significado
COMMONSPECS_API_TOKEN	sí	—	Token de API, con forma cs_live_…. Se envía como Authorization: Bearer.
COMMONSPECS_API_URL	no	https://api.commonspecs.com	URL base de la API.
COMMONSPECS_DEFAULT_COUNTRY	no	—	ISO 3166-1 alpha-2 (ej. PL) para lecturas con ámbito de país.

Si COMMONSPECS_API_TOKEN no está definido, dile al usuario que lo configure y detente — no llames a la API.

Herramientas

Todas las llamadas envían Authorization: Bearer $COMMONSPECS_API_TOKEN. Los ejemplos asumen API="$COMMONSPECS_API_URL" (usa el valor por defecto anterior si no está definido).

lookup_product — obtener especificaciones de un producto

Resuelve un producto usando exactamente uno de: url, ean, o brand + model.

curl -sS -X POST "$API/v1/lookup" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"brand":"Nudie","model":"Gritty Jackson"}'

{"url":"https://…"} o {"ean":"7340028912345"} son las otras dos formas. Opcional: exclude_low_confidence: true para omitir el grupo de baja confianza.

Si el usuario pega un número desnudo de 8 a 14 dígitos (EAN-8, UPC-A, EAN-13 o GTIN-14), trátalo como un ean y búscalo así antes de intentar parsearlo como modelo.

Estado de la respuesta (status):

• hit — un producto. Cuerpo: product, quality_score (0–100 o null), fields, low_confidence_fields, enrichment_opportunities (ver más abajo).
• candidates — varias variantes coincidentes (candidates: [...]); pregúntale al usuario cuál, o busca por url/ean.
• miss — no se encontró nada. Ofrece contribuir con especificaciones (submit_contribution).

search_products — buscar productos, ordenados por mejor puntuación primero

curl -sS -X POST "$API/v1/search" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"denim crudo","category":"jeans-denim"}'

Coincide con nombres de marca y modelo. Filtro opcional de category (slug) y limit (≤20). Devuelve results ordenados por quality_score descendente (mejores especificaciones primero; productos con datos escasos al final), cada uno con el mismo campo quality_score que en lookup. Úsalo cuando el usuario pregunte "qué debería comprar en <categoría>" en lugar de nombrar un producto concreto.

compare_products — comparación lado a lado de especificaciones duras

Úsalo cuando el usuario nombre dos o más productos específicos entre los que elegir.

curl -sS -X POST "$API/v1/compare" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"product_ids":["<id1>","<id2>"]}'

Hasta 5 ids. Devuelve products (cada uno con quality_score), una matriz comparison ([{field, cells: {<product_id>: {value, confidence} | null}}]) y overall_winner (el product_id con la total_score más alta). Presenta los datos lado a lado, nombra el overall_winner y luego explica tú mismo el equilibrio a partir de los datos y las puntuaciones — la API deliberadamente no devuelve ganadores por dimensión ni justificación; el juicio de valor vs. coste e idoneidad es tuyo a partir de los datos.

get_rankings — mejores productos en una categoría

Úsalo cuando el usuario pregunte "cuáles son los mejores X" sin nombrar un producto.

curl -sS "$API/v1/categories/jeans-denim/rankings?country=PL&limit=20" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

Devuelve results ordenados por quality_score (cada uno con un rank). ranking_scope es global por ahora — los rankings localizados por país necesitan precios/disponibilidad que no están operativos, así que se devuelve un country_code pero el ranking es el orden global de puntuaciones. Prefiere esto sobre muchas búsquedas individuales cuando el usuario está explorando una categoría.

get_product — obtener producto por id

curl -sS "$API/v1/products/$PRODUCT_ID" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

get_quality_score — calidad general (0–100)

curl -sS "$API/v1/products/$PRODUCT_ID/quality-score" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN"

Devuelve total_score (0–100, o null si la categoría aún no está puntuada) y missing_fields — los campos de especificación cuya ausencia está frenando la puntuación. Una puntuación baja suele significar datos escasos, no un mal producto; usa missing_fields para decidir qué contribuir. La puntuación es un único número a propósito — la ponderación por campo subyacente no se expone; razona sobre las compensaciones a partir de los propios datos.

submit_contribution — añadir especificaciones que hayas verificado

Un envío lleva un array fields. Identifica el producto usando exactamente uno de url / ean / brand+model (marca+modelo crea el producto si es nuevo). Cada campo debe incluir source_url y un snippet textual del que hayas leído el valor — esa evidencia es lo que genera confianza. source es web (por defecto, una página web) o label (una etiqueta física — ver más abajo).

curl -sS -X POST "$API/v1/contributions" \
  -H "Authorization: Bearer $COMMONSPECS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "Nudie Jeans", "model": "Gritty Jackson", "source": "web",
    "fields": [
      {"field_name": "fabric_weight", "value": "13.5 oz",
       "source_url": "https://www.nudiejeans.com/product/gritty-jackson",
       "snippet": "13.5 oz organic dry denim"}
    ]
  }'

Mundo físico: si el usuario muestra una foto de una etiqueta/producto, lee tú mismo los valores y el EAN y envía solo los valores extraídos — la foto nunca sale de la máquina del usuario. Busca el producto por ean primero, luego contribuye los campos faltantes con "source": "label".

Lectura de una respuesta

quality_score (0–100, o null) es la calidad general de especificaciones del producto; combínalo con missing_fields de get_quality_score cuando el usuario pregunte "¿es bueno?". Cada campo en fields / low_confidence_fields tiene value, confidence (0–1), disputed, needs_corroboration y (cuando está disputado) alternate_claims.

• fields[] — confianza ≥ 0.4. Suficientemente confiable para afirmarlo. Aun así, muestra el número; "13.5 oz (confianza 0.88)" es mejor que un simple "13.5 oz".
• low_confidence_fields[] — confianza 0.1–0.4. Una pista, no un hecho. Preséntalo solo con una reserva explícita ("una fuente sugiere…"). Omítelo si el usuario quiere solo datos sólidos.
• needs_corroboration: true — solo una fuente independiente hasta ahora. Dilo.
• disputed: true — las fuentes discrepan; muestra el ganador y alternate_claims. Un desacuerdo es en sí mismo una señal de compra, no ruido que ocultar.
• enrichment_opportunities — campos que se beneficiarían de otra fuente. Si el usuario está interesado, ofrécete a obtener una y hacer submit_contribution.

Nunca inventes un valor que no esté en la respuesta, y nunca omitas la confianza cuando reportes un hecho.

Errores

• 401 token inválido/faltante → dile al usuario que revise COMMONSPECS_API_TOKEN; no reintentes.
• 403 prohibido → el token no tiene acceso; no reintentes.
• 429 límite de tasa superado → espera y reintenta con retardo exponencial (ej. 1s, 2s, 4s, máx. 3).
• 5x / red → reintenta una o dos veces con retardo, luego informa la falla claramente.

Aún no disponible

offers/precios y flag_stale no están expuestos por la API todavía. No inventes llamadas a ellos — di que la funcionalidad no está operativa.