daniel-j-lin/commerce-lens

CommerceLens Public v0.1 Fertigkeit

Verwenden Sie diese Fertigkeit als gesteuerte Orchestrierungsgrenze für begrenzte Handels- und E-Commerce-Strukturdatenanalysen.

Die Fertigkeit kann entscheiden, was sie fragen soll. Sie darf nicht entscheiden, was wahr ist.

Arbeitsablauf

1. Interpretieren Sie die Benutzerfrage in eine strukturierte Public v0.1 Absicht.
2. Validieren Sie, dass die Absicht innerhalb der genehmigten Frage, Metrik, Quelle, Zeitraum, Umfang, Gruppierung und Behauptungsgrenzen liegt.
3. Fordern Sie Klarstellung an, wenn Zeiträume, Quellenauswahl oder Zuordnungsautorität wesentlich mehrdeutig sind.
4. Erstellen Sie die vorhandene gesteuerte AnalysisRequest.
5. Rufen Sie run_analysis(...) über den CommerceLens-Anwendungsdienst auf.
6. Binden Sie die ClaimCandidate-Autorität nur an genaue AnalysisResult-Referenzen und beibehaltene Kernel-Autorität.
7. Rufen Sie evaluate_claim(...) für jede materiale unterstützte öffentliche Behauptung auf.
8. Rendern Sie nur die Public Response Projection.

Unterstützte Public v0.1 Fragen

Unterstützte Metriken sind genau:

• revenue
• orders
• aov
• revenue_change

Unterstützte Analysekategorien sind genau:

• einzelner gesteuerter Zeitraum Umsatz;
• einzelner gesteuerter Zeitraum Bestellungen;
• einzelner gesteuerter Zeitraum AOV; und
• Umsatzveränderung zwischen zwei explizit gesteuerten vergleichbaren Zeiträumen.

Gruppierung ist NONE.

Hauptquellen-Workflows sind CSV und XLSX. SQLite kann im Kernel verfügbar bleiben, ist aber kein Hauptquellen-Public v0.1 Workflow.

Verantwortung für strukturierte Absichten

Der Host interpretiert natürliche Sprache und übergibt strukturierte Absichten an die Integrationsschicht. Die Integrationsschicht validiert, dass bereits interpretierte Absichten fehlschließen.

Implementieren oder verlassen Sie sich nicht auf einen Python-Natural-Language-Parser, Keyword-Matcher, generischen SQL-Generator, beliebige Python-Ausführung oder LLM-generierte Analyseautorität.

Absichten dürfen nur minimale transiente Konzepte wie Frageklasse, Metrik-ID, explizite gesteuerte Zeiträume, Umfang, Gruppierung, Quellenauswahl, Zuordnungsauswahl und Behauptungsabsicht enthalten.

Absichten dürfen keine Metrikformeln, berechnete Werte, Evidenzreferenzen, Fingerabdrücke, ValidatedResult-Referenzen oder ClaimDecision-Berechtigung enthalten.

Natural-Language-Zuordnung

Die Interpretation natürlicher Sprache gehört dem Agenten. Der deterministische Runner akzeptiert nur bereits interpretierte strukturierte Argumente.

Ordnen Sie unterstützte Benutzeranfragen wie folgt zu:

• „Was war der Umsatz/die Bestellungen/der AOV im Q4 2026?“ wird zugeordnet zu question-class=single_period_metric, metric=revenue|orders|aov, result-period-role=comparison und expliziten gesteuerten Basis-/Vergleichszeiträumen.
• „Wie hat sich der Umsatz von Q3 2026 zu Q4 2026 verändert?“ wird zugeordnet zu question-class=revenue_change, metric=revenue_change, explizite gesteuerte Basis-/Vergleichszeiträume und eine beschreibende Behauptungsabsicht.
• „Warum ist der Umsatz von Q3 2026 zu Q4 2026 gefallen?“ wird zugeordnet zu question-class=diagnostic_revenue_drop, metric=revenue_change, explizite gesteuerte Basis-/Vergleichszeiträume, eine beschreibende Behauptungsabsicht und eine diagnostische Behauptungsabsicht. Die beschreibende Umsatzveränderung darf nur angezeigt werden, wenn die CommerceLens-Autorität dies erlaubt. Die diagnostische Erklärung muss unter Public v0.1 verweigert werden.

Wenn der Benutzer keine Quelldatei, keinen Quelltyp, bei Bedarf kein ausgewähltes XLSX-Blatt oder explizite gesteuerte Zeiträume angegeben hat, fragen Sie nach Klarstellung. Nicht unterstützte Anfragen dürfen nicht angenähert werden.

Schema-Zuordnungs-UX

Nachdem die Quelldatei verfügbar ist, überprüfen Sie die Quellkopfzeilen, bevor Sie materiale Analysen ausführen.

Wenn alle kanonischen Felder, die für die angeforderte unterstützte Analyse erforderlich sind, als genaue kanonische Spaltennamen verfügbar sind, fahren Sie fort, ohne nach Bestätigung der Zuordnung zu fragen. Die exakte Identitätszuordnung ist unter dem CommerceLens-kanonischen Vertrag bereits explizit.

Wenn genaue kanonische Felder fehlen, aber semantisch kompatible Quellkopfzeilen verfügbar erscheinen, schlagen Sie eine Quell-zu-kanonische Zuordnung vor und bitten Sie den Benutzer, diese zu bestätigen oder zu korrigieren. Der Vorschlag ist keine Autorität. Führen Sie keine materialen Analysen durch, bis der Benutzer die Zuordnung explizit bestätigt oder bereitstellt.

Der Benutzer kann alle vorgeschlagenen Zuordnungen bestätigen, eine oder mehrere Zuordnungen korrigieren, die Zuordnung ablehnen oder eine fehlende Zuordnung bereitstellen. Wenn Mehrdeutigkeit bestehen bleibt, stellen Sie eine gezielte Klarstellungsfrage, z. B. welche Quellspalte line_revenue darstellt. Leiten Sie keine Bestätigung aus Stille ab.

Wenn bestätigt, übergeben Sie dem Runner eine strukturierte Quell-zu-kanonische Zuordnung mit Quellkopfzeilen als Schlüsseln und kanonischen Feldern als Werten. Der Runner konvertiert dies in den vorhandenen CanonicalMapping-Vertrag, und die CommerceLens-deterministische Autorität validiert es dennoch mit validate_mapping(...) vor der Analyse.

Schließen Sie fehl, wenn die erforderliche Zuordnungsautorität ungelöst, abgelehnt, mehrdeutig oder von der deterministischen Validierung abgelehnt wird. Fallen Sie niemals auf LLM-Berechnung, stilles Umbenennen, erratene Zuordnung oder generische DataFrame-Analyse zurück.

Deterministischer Runner

Verwenden Sie skills/commerce-lens/scripts/run_public_analysis.py als erstes Befehlsfläche. Es übersetzt strukturierte Argumente in:

• PublicAnalysisIntent
• PublicSourceSelection
• run_public_analysis(...)

Der Runner erstellt automatisch temporäre ArtifactStore- und MetadataStore-Speicherorte, wenn keine bereitgestellt werden. Dies sind Implementierungsdetails; der Benutzer muss sie nicht konstruieren.

Beispiel:

python3.11 skills/commerce-lens/scripts/run_public_analysis.py \
  --source examples/public_v0_1/orders.csv \
  --source-type csv \
  --question-class revenue_change \
  --metric revenue_change \
  --baseline-label "Q3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "Q4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --original-question "How did revenue change from Q3 2026 to Q4 2026?"

Bestätigtes Beispiel für nicht-kanonische Zuordnung:

python3.11 skills/commerce-lens/scripts/run_public_analysis.py \
  --source path/to/orders.csv \
  --source-type csv \
  --question-class revenue_change \
  --metric revenue_change \
  --baseline-label "Q3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "Q4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --mapping-json '{"Order ID":"order_id","Order Line ID":"order_line_id","Order Date":"order_date","Product ID":"product_id","Quantity":"quantity","Revenue":"line_revenue","Currency":"currency","Order Status":"eligibility_status"}'

Stellen Sie vor der ersten Verwendung sicher, dass Python >=3.11 installiert ist. Wenn CommerceLens nicht importiert werden kann, erstellen Sie eine isolierte Umgebung, installieren Sie das lokale Paket und rufen Sie den Runner aus dieser Umgebung auf:

python3.11 -m venv .venv-commerce-lens-skill
.venv-commerce-lens-skill/bin/python -m pip install --upgrade pip
.venv-commerce-lens-skill/bin/python -m pip install -e "."
.venv-commerce-lens-skill/bin/python skills/commerce-lens/scripts/run_public_analysis.py ...

Verstecken Sie keine Bootstrap-Fehler. Wenn Python >=3.11 oder Paketabhängigkeiten nicht installiert werden können, melden Sie den Installations-/Laufzeitfehler. Antworten Sie niemals, indem das LLM selbst materiale Metriken berechnet.

Evidenz- und Behauptungsautorität

Keine materiale Behauptung darf ohne nachvollziehbare Evidenz aus der deterministischen CommerceLens-Engine präsentiert werden.

Materiale Metrikwerte müssen vom deterministischen Runner stammen. Das Skill darf Umsatz, Bestellungen, AOV, Umsatzveränderung oder andere derivative Werte nicht selbst berechnen.

Diagnostische, kausale, prädiktive und präskriptive Behauptungen bleiben unter Public v0.1 fehlgeschlossen. Nicht unterstützte Anfragen dürfen nicht angenähert werden.

Stellen Sie bei Fragen wie „Warum ist der Umsatz von Q3 2026 zu Q4 2026 gefallen?“ die unterstützte beschreibende Umsatzveränderungsproposition getrennt von der nicht unterstützten diagnostischen Proposition dar. Der beschreibende Teil kann über run_analysis(...) und evaluate_claim(...) fortgesetzt werden. Der diagnostische Teil darf nur als nicht unterstützte Behauptungsabsicht eingereicht und als abgelehnt dargestellt werden, wenn die ClaimDecision unzulässig ist.

Verwenden Sie diese genaue Begrenzung, wo zutreffend:

Nicht genügend Evidenz, um zu schlussfolgern, warum der Umsatz zurückgegangen ist.

Listen Sie keine spekulativen Ursachen auf.

Antwort-Rendering

Rendern Sie unterstützte materiale Behauptungen nur, wenn eine autoritative ClaimDecision sie erlaubt.

Halten Sie Metrikzustand, Behauptungszustand und öffentliche Unterstützungsdisposition getrennt. AOV mit Bestellungen gleich Null ist MetricState UNDEFINED, Wert None und undefined_reason orders_equals_zero; dies ist keine numerische Null.

Die öffentliche Antwort kann unterstützte Behauptungen / Antwort, Evidenzzusammenfassung, Metrikzustand, Behauptungsstatus, Einschränkungen, nicht unterstützte Schlussfolgerungen, zusätzlich benötigte Evidenz, erforderliche Klarstellung und blockierte / unzureichende Evidenz enthalten.

Erstellen Sie keine neuen Metrikwerte, Formeln, Evidenz, Validierungsergebnisse, Befunde, alternative Erklärungen oder Empfehlungen in der Antwort.