daniel-j-lin/commerce-lens

CommerceLens Public v0.1 スキル

このスキルは、限定されたコマースおよびeコマースの構造化データ分析における、ガバナンスされたオーケストレーション境界として使用します。

スキルは何を尋ねるかを決定できます。何が真実かを決定してはなりません。

ワークフロー

1. ユーザーの質問を構造化されたPublic v0.1インテントに解釈します。
2. インテントが承認された質問、メトリック、ソース、期間、スコープ、グループ化、およびクレームの境界内にあることを検証します。
3. 期間、ソース選択、またはマッピング権限が実質的に曖昧な場合、明確化を要求します。
4. 既存のガバナンスされた AnalysisRequest を構築します。
5. CommerceLensアプリケーションサービスを介して run_analysis(...) を呼び出します。
6. ClaimCandidate 権限を、正確な AnalysisResult 参照と永続化されたカーネル権限からのみバインドします。
7. サポートされているすべての実質的な公開クレームに対して evaluate_claim(...) を呼び出します。
8. 公開レスポンスプロジェクションのみをレンダリングします。

サポートされるPublic v0.1質問

サポートされるメトリックは正確に次のとおりです：

• revenue
• orders
• aov
• revenue_change

サポートされる分析クラスは正確に次のとおりです：

• 単一ガバナンス期間の収益；
• 単一ガバナンス期間の注文数；
• 単一ガバナンス期間のAOV；および
• 明示的にガバナンスされた2つの比較可能な期間間の収益変化。

グループ化は NONE です。

主要なソースワークフローはCSVおよびXLSXです。SQLiteはカーネル内で利用可能な場合がありますが、主要なPublic v0.1ワークフローではありません。

構造化インテントの責任

ホストは自然言語を解釈し、構造化されたインテントを統合レイヤーに渡します。統合レイヤーは、既に解釈されたインテントがフェイルクローズドであることを検証します。

Pythonの自然言語パーサー、キーワードマッチャー、汎用SQLジェネレーター、任意のPython実行、またはLLM生成の分析権限を実装または依存してはなりません。

インテントは、質問クラス、メトリックID、明示的なガバナンス期間、スコープ、グループ化、ソース選択、マッピング選択、クレームインテントなどの最小限の一時的な概念のみを保持できます。

インテントは、メトリック計算式、計算値、証拠参照、フィンガープリント、ValidatedResult参照、またはClaimDecision権限を保持してはなりません。

自然言語マッピング

自然言語解釈はエージェントに属します。決定論的ランナーは、既に解釈された構造化引数のみを受け入れます。

サポートされるユーザーリクエストを次のようにマッピングします：

• 「Q4 2026の収益/注文数/AOVはいくらですか？」は、question-class=single_period_metric、metric=revenue|orders|aov、result-period-role=comparison、および明示的なガバナンスベースライン/比較期間にマッピングします。
• 「Q3 2026からQ4 2026への収益の変化はどうでしたか？」は、question-class=revenue_change、metric=revenue_change、明示的なガバナンスベースライン/比較期間、および説明的なクレームインテントにマッピングします。
• 「なぜQ3 2026からQ4 2026にかけて収益が減少したのですか？」は、question-class=diagnostic_revenue_drop、metric=revenue_change、明示的なガバナンスベースライン/比較期間、1つの説明的なクレームインテント、および1つの診断的なクレームインテントにマッピングします。説明的な収益変化は、CommerceLens権限によって許可されている場合にのみ表示できます。診断的な説明は、Public v0.1では拒否されなければなりません。

ユーザーがソースファイル、ソースタイプ、必要な場合の選択済みXLSXシート、または明示的なガバナンス期間を提供していない場合は、明確化を求めます。サポートされていないリクエストを近似してはなりません。

スキーママッピングUX

ソースファイルが利用可能になった後、実際の分析を実行する前にソースヘッダーを検査します。

リクエストされたサポート分析に必要なすべての正規フィールドが正確な正規の列名として利用可能な場合、マッピング確認を求めずに続行します。CommerceLensの正規契約の下では、同一性マッピングはすでに明示的です。

正確な正規フィールドが欠落しているが、意味的に互換性のあるソースヘッダーが利用可能と思われる場合は、ソースから正規へのマッピングを提案し、ユーザーに確認または修正を求めます。提案は権限ではありません。ユーザーが明示的に確認またはマッピングを提供するまで、実際の分析を実行しないでください。

ユーザーは提案されたすべてのマッピングを確認したり、1つ以上のマッピングを修正したり、マッピングを拒否したり、欠落しているマッピングを提供したりできます。曖昧さが残る場合は、どのソース列が line_revenue を表すかなど、的を絞った明確化を求めます。沈黙から確認を推測しないでください。

確認されたら、ソースヘッダーをキー、正規フィールドを値とする構造化されたソースから正規へのマッピングをランナーに渡します。ランナーはこれを既存の CanonicalMapping 契約に変換し、CommerceLensの決定論的権限が分析前に validate_mapping(...) でそれを検証します。

必要なマッピング権限が未解決、拒否、曖昧、または決定論的検証によって拒否された場合は、フェイルクローズドします。LLM計算、サイレントな名前変更、推測されたマッピング、または汎用データフレーム分析にフォールバックしてはなりません。

決定論的ランナー

最初の実行コマンドサーフェスとして skills/commerce-lens/scripts/run_public_analysis.py を使用します。これは構造化引数を次のものに変換します：

• PublicAnalysisIntent
• PublicSourceSelection
• run_public_analysis(...)

ランナーは、何も指定されていない場合、自動的に一時的な ArtifactStore および MetadataStore の場所を作成します。これらは実装の詳細であり、ユーザーがそれらを構築する必要はありません。

例：

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?"

確認された非正規マッピングの例：

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

初回使用時は、Python >=3.11を確認してください。CommerceLensをインポートできない場合は、分離された環境を作成し、ローカルパッケージをインストールして、その環境からランナーを呼び出します：

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

ブートストラップの失敗を隠してはいけません。Python >=3.11またはパッケージの依存関係をインストールできない場合は、インストール/ランタイムの失敗を報告してください。LLMがそれ自体で重要なメトリクスを計算することによって応答してはなりません。

証拠とクレーム権限

決定論的なCommerceLensエンジンからのトレーサブルな証拠なしに、実質的なクレームを提示してはなりません。

実質的なメトリック値は決定論的ランナーから取得する必要があります。スキルは収益、注文数、AOV、収益変化、または派生的な値を計算してはなりません。

診断的、因果的、予測的、および規範的なクレームは、Public v0.1ではフェイルクローズドのままです。サポートされていないリクエストを近似してはなりません。

「なぜQ3 2026からQ4 2026にかけて収益が減少したのですか？」などの質問については、サポートされている説明的な収益変化の命題と、サポートされていない診断的な命題を分離してください。説明的な部分は run_analysis(...) および evaluate_claim(...) を通じて進めることができます。診断的な部分は、サポートされていないクレームインテントとしてのみ送信され、ClaimDecisionが許容できない場合は拒否されたものとしてレンダリングされなければなりません。

該当する場合は、次の正確な限定拒否を使用します：

収益が減少した理由を結論付けるための十分な証拠がありません。

推測的な原因を列挙しないでください。

応答レンダリング

権限のある ClaimDecision が許可する場合にのみ、サポートされている実質的なクレームをレンダリングします。

メトリック状態、クレーム状態、および公開サポートの配置を明確に区別します。注文数がゼロのAOVは、MetricState UNDEFINED、値 None、および undefined_reason orders_equals_zero です。これは数値のゼロではありません。

公開応答には、サポートされているクレーム/回答、証拠概要、メトリック状態、クレームステータス、制限事項、サポートされていない結論、追加の証拠が必要、明確化が必要、ブロック済み/不十分な証拠を含めることができます。

応答に新しいメトリック値、計算式、証拠、検証結果、調査結果、代替説明、または推奨事項を作成してはいけません。