commonspecs/commonspecs-skill

commonspecs

commonspecs é um banco de dados API-first de especificações de produtos em nível de engenharia com uma pontuação de confiança por campo. Ele não faz suposições: cada valor é respaldado por evidências e carrega uma confiança calibrada. Seu trabalho é buscar esses fatos e apresentá-los honestamente — incluindo o quão confiável cada um é.

Configuração

A configuração vem de variáveis de ambiente (ou ~/.commonspecs/config.json):

Variável	Obrigatório	Padrão	Significado
COMMONSPECS_API_TOKEN	sim	—	Token da API, formato cs_live_…. Enviado como Authorization: Bearer.
COMMONSPECS_API_URL	não	https://api.commonspecs.com	URL base da API.
COMMONSPECS_DEFAULT_COUNTRY	não	—	ISO 3166-1 alpha-2 (ex.: PL) para leituras com escopo de país.

Se COMMONSPECS_API_TOKEN não estiver definido, informe ao usuário para defini-lo e pare — não chame a API.

Ferramentas

Todas as chamadas enviam Authorization: Bearer $COMMONSPECS_API_TOKEN. Os exemplos assumem API="$COMMONSPECS_API_URL" (use o padrão acima como fallback).

lookup_product — busca as especificações de um produto

Resolva um produto por exatamente um de: url, ean ou 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://…"} ou {"ean":"7340028912345"} são as outras duas formas. Opcional: exclude_low_confidence: true para remover o conjunto de baixa confiança.

Se o usuário colar um número númerico de 8 a 14 dígitos (EAN-8, UPC-A, EAN-13 ou GTIN-14), trate-o como um ean e faça a busca dessa forma antes de tentar interpretá-lo como modelo.

status da resposta:

• hit — um produto. Corpo: product, quality_score (0–100 ou null), fields, low_confidence_fields, enrichment_opportunities (veja abaixo).
• candidates — várias variantes correspondentes (candidates: [...]); pergunte ao usuário qual, ou busque por url/ean.
• miss — nada encontrado. Ofereça-se para contribuir com especificações (submit_contribution).

search_products — encontra produtos, ordenados pelo melhor escore primeiro

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

Corresponde ao nome da marca e modelo. category (slug) opcional como filtro e limit (≤20). Retorna results classificados por quality_score decrescente (melhores especificações primeiro; produtos com dados escassos no final), cada um com o mesmo campo quality_score da busca. Use esta ferramenta quando o usuário perguntar "o que devo comprar em " em vez de nomear um produto específico.

compare_products — comparação lado a lado de especificações técnicas

Use quando o usuário nomear dois ou mais produtos específicos para escolher entre eles.

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

Até 5 IDs. Retorna products (cada um com quality_score), uma matriz comparison ([{field, cells: {<product_id>: {value, confidence} | null}}]) e overall_winner (o product_id com a maior total_score). Apresente os fatos lado a lado, nomeie o overall_winner, e então explique você mesmo o trade-off a partir dos fatos + pontuações — a API deliberadamente não retorna vencedores por dimensão ou uma justificativa; o julgamento de valor-vs-custo e adequação ao propósito é seu a partir dos dados.

get_rankings — principais produtos em uma categoria

Use quando o usuário perguntar "quais são os melhores X" sem nomear um produto.

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

Retorna results classificados por quality_score (cada um com um rank). ranking_scope é global por enquanto — rankings localizados por país precisam de preços/disponibilidade que ainda não estão ativos, portanto um country_code é ecoado, mas a classificação é a ordem global da pontuação. Prefira esta ferramenta em vez de várias buscas individuais quando o usuário estiver navegando em uma categoria.

get_product — busca por ID

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

get_quality_score — qualidade geral (0–100)

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

Retorna total_score (0–100, ou null se a categoria ainda não foi pontuada) e missing_fields — os campos de especificação cuja ausência está segurando a pontuação. Uma pontuação baixa geralmente significa dados escassos, não um produto ruim; use missing_fields para decidir o que contribuir. A pontuação é um único número propositalmente — a ponderação por campo por trás dela não é exposta; raciocine sobre os trade-offs a partir dos próprios fatos.

submit_contribution — adiciona especificações que você verificou

Um envio carrega um array fields. Identifique o produto por exatamente um de url / ean / brand+model (brand+model cria o produto se for novo). Cada campo deve carregar o source_url e um snippet literal do qual você leu o valor — essa evidência é o que gera confiança. source é web (padrão, uma página web) ou label (uma etiqueta física — veja abaixo).

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: se o usuário mostrar uma foto de uma etiqueta/produto, leia os valores e o EAN você mesmo e envie apenas os valores extraídos — a foto nunca sai da máquina do usuário. Primeiro busque o produto por ean e depois contribua com os campos missing com "source": "label".

Lendo uma resposta

quality_score (0–100, ou null) é a qualidade geral das especificações do produto; combine-o com missing_fields de get_quality_score quando o usuário perguntar "isso é bom?". Cada campo em fields / low_confidence_fields tem value, confidence (0–1), disputed, needs_corroboration e (quando em disputa) alternate_claims.

• fields[] — confiança ≥ 0,4. Confiável o suficiente para ser declarado. Ainda assim, exiba o número; "13,5 oz (confiança 0,88)" é melhor que um simples "13,5 oz".
• low_confidence_fields[] — confiança 0,1–0,4. Uma pista, não um fato. Apresente apenas com uma ressalva explícita ("uma fonte sugere…"). Omita se o usuário quiser apenas dados sólidos.
• needs_corroboration: true — apenas uma fonte independente até agora. Informe isso.
• disputed: true — fontes discordam; mostre o vencedor e alternate_claims. Uma discordância é por si só um sinal de compra, não ruído a esconder.
• enrichment_opportunities — campos que se beneficiariam de outra fonte. Se o usuário estiver engajado, ofereça-se para buscar uma e fazer submit_contribution.

Nunca invente um valor que não esteja na resposta, e nunca omita a confiança ao relatar um fato.

Erros

• 401 token inválido/ausente → informe ao usuário para verificar COMMONSPECS_API_TOKEN; não tente novamente.
• 403 proibido → token sem acesso; não tente novamente.
• 429 limite de taxa excedido → aguarde e tente novamente com atraso exponencial (ex.: 1s, 2s, 4s, máx. 3).
• 5x / rede → tente novamente uma ou duas vezes com backoff e, em seguida, relate a falha diretamente.

Ainda não disponível

offers/precificação e flag_stale não são expostos pela API ainda. Não invente chamadas para eles — diga que a funcionalidade não está ativa.