commonspecs/commonspecs-skill

commonspecs

commonspecs ist eine API-first-Datenbank für technische Produktspezifikationen mit einem Konfidenzwert pro Feld. Sie rät nicht: Jeder Wert ist durch Belege gestützt und trägt einen kalibrierten Konfidenzwert. Ihre Aufgabe ist es, diese Fakten abzurufen und ehrlich darzustellen – einschließlich der Vertrauenswürdigkeit jedes Einzelnen.

Einrichtung

Die Konfiguration erfolgt über Umgebungsvariablen (oder ~/.commonspecs/config.json):

Variable	Erforderlich	Standard	Bedeutung
COMMONSPECS_API_TOKEN	ja	—	API-Token, Form cs_live_…. Wird als Authorization: Bearer gesendet.
COMMONSPECS_API_URL	nein	https://api.commonspecs.com	API-Basis-URL.
COMMONSPECS_DEFAULT_COUNTRY	nein	—	ISO 3166-1 alpha-2 (z. B. DE) für länderspezifische Abfragen.

Wenn COMMONSPECS_API_TOKEN nicht gesetzt ist, teilen Sie dem Benutzer mit, dass er es setzen soll, und brechen Sie ab – rufen Sie die API nicht auf.

Tools

Alle Aufrufe senden Authorization: Bearer $COMMONSPECS_API_TOKEN. Die Beispiele gehen von API="$COMMONSPECS_API_URL" aus (verwenden Sie andernfalls den Standardwert oben).

lookup_product – Spezifikationen eines Produkts abrufen

Ein Produkt anhand genau einer der folgenden Angaben auflösen: url, ean oder 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://…"} oder {"ean":"7340028912345"} sind die anderen beiden Formen. Optional: exclude_low_confidence: true, um die Kategorie mit niedriger Konfidenz auszuschließen.

Wenn der Benutzer eine nackte 8- bis 14-stellige Zahl (EAN-8, UPC-A, EAN-13 oder GTIN-14) einfügt, behandeln Sie diese als ean und suchen Sie sie zuerst auf diese Weise, bevor Sie versuchen, sie als Modell zu parsen.

Antwort status:

• hit – ein Produkt gefunden. Inhalt: product, quality_score (0–100 oder null), fields, low_confidence_fields, enrichment_opportunities (siehe unten).
• candidates – mehrere Varianten stimmten überein (candidates: [...]); fragen Sie den Benutzer, welche er möchte, oder suchen Sie über url/ean.
• miss – nichts gefunden. Bieten Sie an, Spezifikationen beizutragen (submit_contribution).

search_products – Produkte finden, beste zuerst

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

Findet Übereinstimmungen mit Markennamen und Modell. Optionaler category (Slug)-Filter und limit (≤20). Gibt results zurück, sortiert nach quality_score absteigend (beste Spezifikationen zuerst; Produkte mit dünnen Daten zuletzt), jedes mit dem gleichen quality_score-Feld wie bei einer Suche. Verwenden Sie dies, wenn der Benutzer fragt „was soll ich in kaufen“, anstatt ein bestimmtes Produkt zu nennen.

compare_products – Seitenvergleich von technischen Daten

Verwenden Sie dies, wenn der Benutzer zwei oder mehr bestimmte Produkte zur Auswahl nennt.

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

Bis zu 5 IDs. Gibt products (jeweils mit quality_score), eine comparison-Matrix zurück ([{field, cells: {<product_id>: {value, confidence} | null}}]) und overall_winner (die product_id mit der höchsten total_score). Präsentieren Sie die Fakten nebeneinander, nennen Sie den overall_winner und erklären Sie dann selbst den Kompromiss aus den Fakten + Bewertungen – die API liefert bewusst keine dimensionsspezifischen Gewinner oder eine Begründung; das Wert-vs-Kosten- und Eignungsurteil liegt bei Ihnen, das Sie aus den Daten ableiten müssen.

get_rankings – Top-Produkte in einer Kategorie

Verwenden Sie dies, wenn der Benutzer nach „den besten X“ fragt, ohne ein Produkt zu nennen.

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

Gibt results zurück, sortiert nach quality_score (jeweils mit einem rank). ranking_scope ist zurzeit global – länderspezifische Rankings benötigen Preis-/Verfügbarkeitsdaten, die noch nicht live sind, sodass ein country_code zurückgespiegelt wird, aber das Ranking der globalen Bewertungsreihenfolge entspricht. Bevorzugen Sie dies gegenüber vielen einzelnen Abfragen, wenn der Benutzer in einer Kategorie stöbert.

get_product – Abrufen nach ID

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

get_quality_score – Gesamtqualität (0–100)

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

Gibt total_score (0–100, oder null, wenn die Kategorie noch nicht bewertet wurde) und missing_fields zurück – die Spezifikationsfelder, deren Fehlen die Bewertung senkt. Ein niedrigerer Wert bedeutet oft dünne Daten, nicht ein schlechtes Produkt; verwenden Sie missing_fields, um zu entscheiden, was Sie beitragen möchten. Der Score ist bewusst eine einzelne Zahl – die gewichtete Bewertung pro Feld dahinter wird nicht preisgegeben; bewerten Sie Kompromisse anhand der Fakten selbst.

submit_contribution – Überprüfte Spezifikationen hinzufügen

Eine Einreichung enthält ein fields-Array. Identifizieren Sie das Produkt über genau eine der Angaben url / ean / brand+model (brand+model erstellt das Produkt, wenn es neu ist). Jedes Feld sollte die source_url und einen wörtlichen snippet enthalten, aus dem Sie den Wert gelesen haben – dieser Beleg schafft Vertrauen. source ist web (Standard, eine Webseite) oder label (ein physisches Etikett – siehe unten).

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

Physische Welt: Wenn der Benutzer ein Foto eines Etiketts/Produkts zeigt, lesen Sie die Werte und die EAN selbst und senden Sie nur die extrahierten Werte – das Foto verlässt niemals den Computer des Benutzers. Suchen Sie das Produkt zuerst über ean und tragen Sie dann die fehlenden fields mit "source": "label" bei.

Lesen einer Antwort

quality_score (0–100 oder null) ist die gesamte Spezifikationsqualität des Produkts; kombinieren Sie es mit missing_fields von get_quality_score, wenn der Benutzer fragt „ist das gut?“. Jedes Feld in fields / low_confidence_fields hat value, confidence (0–1), disputed, needs_corroboration und (wenn bestritten) alternate_claims.

• fields[] – Konfidenz ≥ 0,4. Vertrauenswürdig genug, um es zu nennen. Zeigen Sie dennoch die Zahl an; „13,5 oz (confidence 0.88)“ ist besser als ein nacktes „13,5 oz“.
• low_confidence_fields[] – Konfidenz 0,1–0,4. Ein Hinweis, keine Tatsache. Nur mit einer expliziten Einschränkung präsentieren („eine Quelle deutet an…“). Weglassen, wenn der Benutzer nur solide Daten wünscht.
• needs_corroboration: true – Bisher nur eine unabhängige Quelle. Sagen Sie das.
• disputed: true – Quellen widersprechen sich; zeigen Sie den Gewinner und die alternate_claims. Ein Widerspruch ist selbst ein Kaufsignal, kein Rauschen, das versteckt werden muss.
• enrichment_opportunities – Felder, die von einer weiteren Quelle profitieren würden. Wenn der Benutzer interessiert ist, bieten Sie an, eine zu holen und submit_contribution durchzuführen.

Erfinden Sie niemals einen Wert, der nicht in der Antwort steht, und lassen Sie niemals die Konfidenz weg, wenn Sie eine Tatsache berichten.

Fehler

• 401 ungültiges/fehlendes Token → teilen Sie dem Benutzer mit, dass er COMMONSPECS_API_TOKEN überprüfen soll; versuchen Sie es nicht erneut.
• 403 verboten → Token hat keinen Zugriff; versuchen Sie es nicht erneut.
• 429 Ratenlimit erreicht → pausieren und mit exponentiellem Verzögerung erneut versuchen (z. B. 1s, 2s, 4s, max. 3).
• 5x / Netzwerk → ein- oder zweimal mit exponentiellem Backoff erneut versuchen, dann den Fehler klar melden.

Noch nicht verfügbar

offers/Preisgestaltung und flag_stale werden von der API noch nicht bereitgestellt. Erfinden Sie keine Aufrufe dafür – sagen Sie, dass die Funktion noch nicht live ist.