commonspecs/commonspecs-skill

commonspecs

commonspecs est une base de données orientée API de fiches techniques de qualité ingénieur avec un score de confiance par champ. Elle ne devine pas : chaque valeur est sourcée et porte une confiance calibrée. Votre travail consiste à récupérer ces faits et à les présenter honnêtement — y compris leur degré de fiabilité.

Configuration

La configuration provient de variables d'environnement (ou de ~/.commonspecs/config.json) :

Variable	Requise	Défaut	Signification
COMMONSPECS_API_TOKEN	oui	—	Jeton API, forme cs_live_…. Envoyé comme Authorization: Bearer.
COMMONSPECS_API_URL	non	https://api.commonspecs.com	URL de base de l'API.
COMMONSPECS_DEFAULT_COUNTRY	non	—	ISO 3166-1 alpha-2 (ex. PL) pour les lectures limitées à un pays.

Si COMMONSPECS_API_TOKEN n'est pas défini, dites à l'utilisateur de le définir et arrêtez-vous — n'appelez pas l'API.

Outils

Tous les appels envoient Authorization: Bearer $COMMONSPECS_API_TOKEN. Les exemples supposent API="$COMMONSPECS_API_URL" (repliez-vous sur la valeur par défaut ci-dessus).

lookup_product — récupérer les fiches d'un produit

Résoudre un produit par exactement un 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"} sont les deux autres formes. Optionnel : exclude_low_confidence: true pour supprimer le groupe des champs de faible confiance.

Si l'utilisateur colle un nombre brut de 8 à 14 chiffres (EAN-8, UPC-A, EAN-13 ou GTIN-14), traitez-le comme un ean et effectuez la recherche avant d'essayer de l'interpréter comme un modèle.

Statut de la réponse :

• hit — un produit. Corps : product, quality_score (0–100 ou null), fields, low_confidence_fields, enrichment_opportunities (voir ci-dessous).
• candidates — plusieurs variantes correspondent (candidates: [...]) ; demandez à l'utilisateur laquelle, ou cherchez par url/ean.
• miss — rien trouvé. Proposez de contribuer aux fiches (submit_contribution).

search_products — rechercher des produits, les mieux notés en premier

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"}'

Correspond sur le nom de la marque et le modèle. Filtre optionnel par category (slug) et limit (≤20). Renvoie results classés par quality_score décroissant (meilleures fiches en premier ; les produits avec peu de données en dernier), chacun avec le même champ quality_score qu'une recherche simple. Utilisez cette fonction lorsque l'utilisateur demande « que devrais-je acheter dans <catégorie> » plutôt que de nommer un produit.

compare_products — comparaison côte à côte sur les caractéristiques techniques

À utiliser lorsque l'utilisateur nomme deux produits spécifiques ou plus pour choisir.

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

Jusqu'à 5 identifiants. Renvoie products (chacun avec quality_score), une matrice comparison ([{field, cells: {<product_id>: {value, confidence} | null}}]), et overall_winner (le product_id avec le total_score le plus élevé). Présentez les faits côte à côte, nommez le overall_winner, puis expliquez vous-même le compromis à partir des faits et des scores — l'API ne renvoie délibérément pas de gagnants par dimension ni de justification ; le jugement valeur-coût et adéquation à l'usage vous appartient à partir des données.

get_rankings — meilleurs produits d'une catégorie

À utiliser lorsque l'utilisateur demande « quels sont les meilleurs X » sans nommer de produit.

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

Renvoie results classés par quality_score (chacun avec un rank). ranking_scope est global pour l'instant — les classements localisés par pays nécessitent des données de prix/disponibilité qui ne sont pas encore en ligne, donc un country_code est renvoyé mais le classement correspond à l'ordre global du score. Préférez cette fonction à de multiples recherches individuelles lorsque l'utilisateur navigue dans une catégorie.

get_product — récupérer par identifiant

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

get_quality_score — qualité globale (0–100)

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

Renvoie total_score (0–100, ou null si la catégorie n'est pas encore notée) et missing_fields — les champs de fiche dont l'absence freine le score. Un score faible signifie souvent peu de données, pas un mauvais produit ; utilisez missing_fields pour décider quoi contribuer. Le score est un nombre unique à dessein — la pondération par champ derrière n'est pas exposée ; raisonnez sur les compromis à partir des faits eux-mêmes.

submit_contribution — ajouter des fiches que vous avez vérifiées

Une soumission contient un tableau fields. Identifiez le produit par exactement un de url / ean / brand+model (brand+model crée le produit s'il est nouveau). Chaque champ doit comporter source_url et un snippet textuel dont vous avez lu la valeur — c'est cette preuve qui génère la confiance. source est web (par défaut, une page web) ou label (une étiquette physique — voir ci-dessous).

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"}
    ]
  }'

Monde physique : si l'utilisateur montre une photo d'étiquette/produit, lisez les valeurs et l'EAN vous-même et n'envoyez que les valeurs extraites — la photo ne quitte jamais la machine de l'utilisateur. Cherchez d'abord le produit par ean, puis contribuez les fields manquants avec "source": "label".

Lecture d'une réponse

quality_score (0–100, ou null) est la qualité globale des fiches du produit ; associez-le à missing_fields de get_quality_score lorsque l'utilisateur demande « est-ce que c'est bon ? ». Chaque champ dans fields / low_confidence_fields a value, confidence (0–1), disputed, needs_corroboration, et (en cas de litige) alternate_claims.

• fields[] — confiance ≥ 0,4. Suffisamment fiable pour être énoncé. Affichez quand même le nombre ; « 13,5 oz (confiance 0,88) » est mieux qu'un simple « 13,5 oz ».
• low_confidence_fields[] — confiance 0,1–0,4. Une piste, pas un fait. Présentez uniquement avec une réserve explicite (« une source suggère… »). Omettez si l'utilisateur ne veut que des données solides.
• needs_corroboration: true — une seule source indépendante jusqu'à présent. Mentionnez-le.
• disputed: true — les sources divergent ; montrez le gagnant et alternate_claims. Un désaccord est en soi un signal d'achat, pas un bruit à cacher.
• enrichment_opportunities — champs qui bénéficieraient d'une autre source. Si l'utilisateur est engagé, proposez d'en récupérer une et de faire submit_contribution.

N'inventez jamais une valeur qui n'est pas dans la réponse, et ne supprimez jamais le score de confiance lorsque vous rapportez un fait.

Erreurs

• 401 jeton invalide/manquant → dites à l'utilisateur de vérifier COMMONSPECS_API_TOKEN ; ne réessayez pas.
• 403 accès interdit → le jeton n'a pas les droits ; ne réessayez pas.
• 429 limite de débit dépassée → patientez et réessayez avec un délai exponentiel (ex. 1s, 2s, 4s, max 3).
• 5x / réseau → réessayez une ou deux fois avec backoff, puis signalez l'échec simplement.

Pas encore disponible

offers/tarification et flag_stale ne sont pas encore exposés par l'API. N'inventez pas d'appels vers eux — dites que la fonctionnalité n'est pas en ligne.