daniel-j-lin/commerce-lens

Skill CommerceLens Public v0.1

Use este Skill como um limite de orquestração governado para análise de dados estruturados de comércio e e-commerce.

O Skill pode decidir o que perguntar. Ele não deve decidir o que é verdade.

Fluxo de Trabalho

1. Interprete a pergunta do usuário em uma intenção estruturada Public v0.1.
2. Valide que a intenção está dentro dos limites aprovados de pergunta, Métrica, fonte, período, escopo, agrupamento e Reivindicação.
3. Solicite esclarecimento quando períodos, seleção de fonte ou autoridade de mapeamento forem materialmente ambíguos.
4. Construa a AnalysisRequest governada existente.
5. Invoque run_analysis(...) através do serviço de aplicação CommerceLens.
6. Vincule a autoridade de ClaimCandidate apenas a referências exatas de AnalysisResult e autoridade de kernel persistida.
7. Invoque evaluate_claim(...) para cada Reivindicação pública material suportada.
8. Renderize apenas a Projeção de Resposta Pública.

Perguntas Public v0.1 Suportadas

As métricas suportadas são exatamente:

• revenue
• orders
• aov
• revenue_change

As classes analíticas suportadas são exatamente:

• Receita de período governado único;
• Pedidos de período governado único;
• AOV de período governado único; e
• Variação de Receita entre dois períodos comparáveis explicitamente governados.

O agrupamento é NONE.

Os fluxos de trabalho de origem principais são CSV e XLSX. SQLite pode permanecer disponível no kernel, mas não é um fluxo de trabalho Public v0.1 principal.

Responsabilidade de Intenção Estruturada

O anfitrião interpreta a linguagem natural e passa a intenção estruturada para a camada de integração. A camada de integração valida que a intenção já interpretada falha de forma fechada.

Não implemente nem dependa de um analisador de linguagem natural Python, correspondente de palavras-chave, gerador SQL genérico, execução arbitrária de Python ou autoridade analítica gerada por LLM.

A intenção pode transportar apenas conceitos transitórios mínimos, como classe de pergunta, ID de Métrica, períodos governados explícitos, escopo, agrupamento, seleção de fonte, seleção de mapeamento e intenção de Reivindicação.

A intenção não deve transportar fórmulas de Métrica, valores calculados, referências de Evidência, impressões digitais, referências de ValidatedResult ou permissão de ClaimDecision.

Mapeamento de Linguagem Natural

A interpretação de linguagem natural pertence ao agente. O executor determinístico aceita apenas argumentos estruturados já interpretados.

Mapeie as solicitações de usuário suportadas da seguinte forma:

• "Qual foi a receita/pedidos/AOV no 4º trimestre de 2026?" mapeia para question-class=single_period_metric, metric=revenue|orders|aov, result-period-role=comparison, e períodos de baseline/comparação explícitos governados.
• "Como a receita mudou do 3º trimestre de 2026 para o 4º trimestre de 2026?" mapeia para question-class=revenue_change, metric=revenue_change, períodos de baseline/comparação explícitos governados e uma intenção de Reivindicação descritiva.
• "Por que a receita caiu do 3º trimestre de 2026 para o 4º trimestre de 2026?" mapeia para question-class=diagnostic_revenue_drop, metric=revenue_change, períodos de baseline/comparação explícitos governados, uma intenção de Reivindicação descritiva e uma intenção de Reivindicação diagnóstica. A Variação de Receita descritiva pode ser mostrada apenas se permitida pela autoridade CommerceLens. A explicação diagnóstica deve ser recusada sob Public v0.1.

Se o usuário não forneceu um arquivo de origem, tipo de origem, planilha XLSX selecionada quando necessário ou períodos explícitos governados, peça esclarecimento. Solicitações não suportadas não devem ser aproximadas.

UX de Mapeamento de Esquema

Após o arquivo de origem estar disponível, inspecione os cabeçalhos da origem antes de executar a análise material.

Se todos os campos canônicos exigidos pela análise suportada solicitada estiverem disponíveis como nomes de coluna canônicos exatos, continue sem perguntar por confirmação de mapeamento. O mapeamento de identidade exata já é explícito sob o contrato canônico CommerceLens.

Se campos canônicos exatos estiverem ausentes, mas cabeçalhos de origem semanticamente compatíveis parecerem disponíveis, proponha um mapeamento fonte-para-canônico e peça ao usuário para confirmar ou corrigi-lo. A proposta não é autoridade. Não execute análise material até que o usuário confirme ou forneça explicitamente o mapeamento.

O usuário pode confirmar todos os mapeamentos propostos, corrigir um ou mais mapeamentos, recusar o mapeamento ou fornecer um mapeamento ausente. Se a ambiguidade persistir, faça um esclarecimento direcionado, como qual coluna de origem representa line_revenue. Não infira confirmação a partir do silêncio.

Quando confirmado, entregue ao executor um mapeamento fonte-para-canônico estruturado com cabeçalhos de origem como chaves e campos canônicos como valores. O executor converte isso para o contrato CanonicalMapping existente, e a autoridade determinística CommerceLens ainda o valida com validate_mapping(...) antes da análise.

Falhe de forma fechada quando a autoridade de mapeamento necessária não for resolvida, for rejeitada, ambígua ou rejeitada pela validação determinística. Nunca recorra a cálculo LLM, renomeação silenciosa, mapeamento adivinhado ou análise genérica de dataframe.

Executor Determinístico

Use skills/commerce-lens/scripts/run_public_analysis.py como superfície de comando de primeira execução. Ele traduz argumentos estruturados em:

• PublicAnalysisIntent
• PublicSourceSelection
• run_public_analysis(...)

O executor cria automaticamente locais temporários de ArtifactStore e MetadataStore quando nenhum é fornecido. Estes são detalhes de implementação; o usuário não precisa construí-los.

Exemplo:

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

Exemplo de mapeamento não canônico confirmado:

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

Para primeiro uso, verifique Python >=3.11. Se CommerceLens não puder ser importado, crie um ambiente isolado, instale o pacote local e invoque o executor a partir desse ambiente:

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

Não esconda falhas de bootstrap. Se Python >=3.11 ou dependências de pacote não puderem ser instalados, relate a falha de instalação/execução. Nunca responda fazendo o LLM calcular métricas materiais por conta própria.

Evidência e Autoridade de Reivindicação

Nenhuma reivindicação material pode ser apresentada sem evidência rastreável do motor determinístico CommerceLens.

Valores de Métricas materiais devem vir do executor determinístico. O Skill não deve calcular Receita, Pedidos, AOV, Variação de Receita ou qualquer valor derivado.

Reivindicações diagnósticas, causais, preditivas e prescritivas permanecem com falha fechada sob Public v0.1. Solicitações não suportadas não devem ser aproximadas.

Para perguntas como "Por que a receita caiu do 3º trimestre de 2026 para o 4º trimestre de 2026?", mantenha a proposição descritiva de Variação de Receita suportada separada da proposição diagnóstica não suportada. A parte descritiva pode prosseguir através de run_analysis(...) e evaluate_claim(...). A parte diagnóstica deve ser submetida apenas como uma intenção de Reivindicação não suportada e renderizada como recusada se a ClaimDecision for inadmissível.

Use esta recusa limitada exata quando aplicável:

Evidência insuficiente para concluir por que a Receita diminuiu.

Não liste causas especulativas.

Renderização de Resposta

Renderize Reivindicações materiais suportadas apenas quando uma ClaimDecision autoritativa as permitir.

Mantenha o Estado da Métrica, Estado da Reivindicação e disposição de suporte público distintos. AOV com Pedidos iguais a zero é MetricState UNDEFINED, valor None, e undefined_reason orders_equals_zero; isso não é zero numérico.

A resposta pública pode incluir Reivindicações Suportadas / Resposta, Resumo de Evidência, Estado da Métrica, Status da Reivindicação, Limitações, Conclusões Não Suportadas, Evidência Adicional Necessária, Esclarecimento Necessário e Bloqueado / Evidência Insuficiente.

Não crie novos valores de Métrica, fórmulas, Evidência, resultados de validação, Descobertas, Explicações Alternativas ou Recomendações na resposta.