daniel-j-lin/commerce-lens

Compétence CommerceLens Public v0.1

Utilisez cette compétence comme une frontière d'orchestration gouvernée pour l'analyse de données structurées de commerce et de commerce électronique.

La compétence peut décider quoi demander. Elle ne doit pas décider ce qui est vrai.

Workflow

1. Interprétez la question de l'utilisateur en une intention structurée Public v0.1.
2. Validez que l'intention se trouve dans les limites approuvées de question, métrique, source, période, périmètre, regroupement et affirmation.
3. Demandez des clarifications lorsque les périodes, la sélection de source ou l'autorité de mappage sont matériellement ambiguës.
4. Construisez la AnalysisRequest gouvernée existante.
5. Invoquez run_analysis(...) via le service applicatif CommerceLens.
6. Liez l'autorité ClaimCandidate uniquement à partir de références exactes AnalysisResult et de l'autorité persistante du noyau.
7. Invoquez evaluate_claim(...) pour chaque affirmation publique matérielle supportée.
8. Rendez uniquement la Projection de Réponse Publique.

Questions Public v0.1 Supportées

Les métriques supportées sont exactement :

• revenue
• orders
• aov
• revenue_change

Les classes analytiques supportées sont exactement :

• Revenu sur une seule période gouvernée ;
• Commandes sur une seule période gouvernée ;
• Panier moyen (AOV) sur une seule période gouvernée ; et
• Variation de revenu entre deux périodes comparables explicitement gouvernées.

Le regroupement est AUCUN.

Les workflows principaux sources sont CSV et XLSX. SQLite peut rester disponible dans le noyau mais n'est pas un workflow Public v0.1 principal.

Responsabilité de l'Intention Structurée

L'hôte interprète le langage naturel et transmet l'intention structurée à la couche d'intégration. La couche d'intégration valide que l'intention déjà interprétée échoue de manière fermée.

N'implémentez pas et ne vous fiez pas à un analyseur de langage naturel Python, un matcheur de mots-clés, un générateur SQL générique, une exécution Python arbitraire, ou une autorité analytique générée par LLM.

L'intention peut porter uniquement des concepts transitoires minimaux tels que la classe de question, l'ID de métrique, les périodes gouvernées explicites, le périmètre, le regroupement, la sélection de source, la sélection de mappage, et l'intention d'affirmation.

L'intention ne doit pas porter de formules de métriques, de valeurs calculées, de références de preuves, d'empreintes, de références ValidatedResult, ou de permission ClaimDecision.

Mappage Langage Naturel

L'interprétation du langage naturel appartient à l'agent. Le moteur déterministe accepte uniquement des arguments structurés déjà interprétés.

Mappez les requêtes utilisateur supportées comme suit :

• "Quel était le revenu/commandes/panier moyen au T4 2026 ?" correspond à question-class=single_period_metric, metric=revenue|orders|aov, result-period-role=comparison, et des périodes de référence/comparaison explicites gouvernées.
• "Comment le revenu a-t-il changé du T3 2026 au T4 2026 ?" correspond à question-class=revenue_change, metric=revenue_change, des périodes de référence/comparaison explicites gouvernées, et une intention d'affirmation descriptive.
• "Pourquoi le revenu a-t-il chuté du T3 2026 au T4 2026 ?" correspond à question-class=diagnostic_revenue_drop, metric=revenue_change, des périodes de référence/comparaison explicites gouvernées, une intention d'affirmation descriptive et une intention d'affirmation diagnostique. La Variation de Revenu descriptive ne peut être affichée que si elle est autorisée par l'autorité CommerceLens. L'explication diagnostique doit être refusée sous Public v0.1.

Si l'utilisateur n'a pas fourni de fichier source, de type de source, de feuille XLSX sélectionnée lorsque nécessaire, ou de périodes explicites gouvernées, demandez une clarification. Les requêtes non supportées ne doivent pas être approximées.

Expérience Utilisateur de Mappage de Schéma

Après que le fichier source soit disponible, inspectez les en-têtes source avant d'exécuter l'analyse matérielle.

Si tous les champs canoniques requis par l'analyse supportée demandée sont disponibles sous forme de noms de colonnes canoniques exacts, continuez sans demander de confirmation de mappage. Le mappage d'identité exacte est déjà explicite sous le contrat canonique CommerceLens.

Si les champs canoniques exacts sont manquants mais que des en-têtes source sémantiquement compatibles semblent disponibles, proposez un mappage source-à-canonique et demandez à l'utilisateur de le confirmer ou de le corriger. La proposition n'est pas une autorité. N'exécutez pas d'analyse matérielle jusqu'à ce que l'utilisateur confirme explicitement ou fournisse le mappage.

L'utilisateur peut confirmer tous les mappages proposés, corriger un ou plusieurs mappages, refuser le mappage, ou fournir un mappage manquant. Si l'ambiguïté persiste, posez une question ciblée comme "Quelle colonne source représente line_revenue ?". N'inférez pas la confirmation à partir du silence.

Une fois confirmé, transmettez au moteur d'exécution un mappage source-à-canonique structuré avec les en-têtes source comme clés et les champs canoniques comme valeurs. Le moteur d'exécution convertit cela en contrat CanonicalMapping existant, et l'autorité déterministe CommerceLens le valide avec validate_mapping(...) avant analyse.

Échouez de manière fermée lorsque l'autorité de mappage requise est non résolue, rejetée, ambiguë, ou rejetée par validation déterministe. Ne recourez jamais à un calcul LLM, un renommage silencieux, un mappage deviné, ou une analyse générique de dataframe.

Moteur d'Exécution Déterministe

Utilisez skills/commerce-lens/scripts/run_public_analysis.py comme surface de commande de première exécution. Il traduit les arguments structurés en :

• PublicAnalysisIntent
• PublicSourceSelection
• run_public_analysis(...)

Le moteur d'exécution crée automatiquement des emplacements temporaires ArtifactStore et MetadataStore lorsqu'aucun n'est fourni. Ce sont des détails d'implémentation ; l'utilisateur n'a pas besoin de les construire.

Exemple :

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 "T3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "T4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --original-question "Comment le revenu a-t-il changé du T3 2026 au T4 2026 ?"

Exemple de mappage non canonique confirmé :

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 "T3 2026" \
  --baseline-start 2026-07-01 \
  --baseline-end 2026-09-30 \
  --comparison-label "T4 2026" \
  --comparison-start 2026-10-01 \
  --comparison-end 2026-12-31 \
  --mapping-json '{"ID Commande":"order_id","ID Ligne Commande":"order_line_id","Date Commande":"order_date","ID Produit":"product_id","Quantité":"quantity","Revenu":"line_revenue","Devise":"currency","Statut Commande":"eligibility_status"}'

Pour la première utilisation, vérifiez Python >=3.11. Si CommerceLens ne peut pas être importé, créez un environnement isolé, installez le paquet local et invoquez le moteur d'exécution depuis cet environnement :

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 ...

Ne cachez pas les échecs de démarrage. Si Python >=3.11 ou les dépendances du paquet ne peuvent pas être installés, signalez l'échec d'installation/exécution. Ne répondez jamais en faisant calculer les métriques matérielles par le LLM lui-même.

Preuve et Autorité d'Affirmation

Aucune affirmation matérielle ne peut être présentée sans preuve traçable provenant du moteur déterministe CommerceLens.

Les valeurs de métriques matérielles doivent provenir du moteur d'exécution déterministe. La compétence ne doit pas calculer le Revenu, les Commandes, le Panier Moyen, la Variation de Revenu, ou toute valeur dérivée.

Les affirmations diagnostiques, causales, prédictives et prescriptives restent en échec fermé sous Public v0.1. Les requêtes non supportées ne doivent pas être approximées.

Pour des questions telles que "Pourquoi le revenu a-t-il chuté du T3 2026 au T4 2026 ?", gardez la proposition de Variation de Revenu descriptive supportée séparée de la proposition diagnostique non supportée. La partie descriptive peut procéder via run_analysis(...) et evaluate_claim(...). La partie diagnostique doit être soumise uniquement comme une intention d'affirmation non supportée et rendue comme refusée si la ClaimDecision est inadmissible.

Utilisez ce refus borné exact lorsque applicable :

Preuves insuffisantes pour conclure pourquoi le Revenu a diminué.

N'énumérez pas de causes spéculatives.

Rendu de la Réponse

Rendez les affirmations matérielles supportées uniquement lorsqu'une ClaimDecision faisant autorité les autorise.

Gardez l'État de la Métrique, l'État de l'Affirmation, et la disposition de support public distincts. Le Panier Moyen avec des Commandes égales à zéro est MetricState UNDEFINED, valeur None, et undefined_reason orders_equals_zero ; ce n'est pas un zéro numérique.

La réponse publique peut inclure Affirmations Supportées / Réponse, Résumé des Preuves, État de la Métrique, Statut de l'Affirmation, Limitations, Conclusions Non Supportées, Preuves Supplémentaires Nécessaires, Clarification Requise, et Bloqué / Preuves Insuffisantes.

Ne créez pas de nouvelles valeurs de métriques, formules, preuves, résultats de validation, conclusions, explications alternatives ou recommandations dans la réponse.