daniel-j-lin/commerce-lens

Habilidad Pública v0.1 de CommerceLens

Use esta habilidad como un límite de orquestación gobernado para el análisis de datos estructurados de comercio y comercio electrónico.

La habilidad puede decidir qué preguntar. No debe decidir qué es verdad.

Flujo de trabajo

1. Interpretar la pregunta del usuario en una intención estructurada Pública v0.1.
2. Validar que la intención esté dentro de los límites aprobados de pregunta, métrica, fuente, período, alcance, agrupación y afirmación.
3. Solicitar aclaración cuando los períodos, la selección de fuente o la autoridad de mapeo sean materialmente ambiguos.
4. Construir la AnalysisRequest gobernada existente.
5. Invocar run_analysis(...) a través del servicio de aplicación CommerceLens.
6. Vincular la autoridad de ClaimCandidate solo a partir de referencias exactas de AnalysisResult y autoridad de kernel persistente.
7. Invocar evaluate_claim(...) para cada afirmación pública material compatible.
8. Renderizar solo la Proyección de Respuesta Pública.

Preguntas Públicas v0.1 compatibles

Las métricas compatibles son exactamente:

• revenue
• orders
• aov
• revenue_change

Las clases analíticas compatibles son exactamente:

• Ingresos de un solo período gobernado;
• Pedidos de un solo período gobernado;
• AOV de un solo período gobernado; y
• Cambio de ingresos entre dos períodos comparables explícitamente gobernados.

La agrupación es NONE.

Los flujos de trabajo de fuentes principales son CSV y XLSX. SQLite puede permanecer disponible en el kernel, pero no es un flujo de trabajo principal Público v0.1.

Responsabilidad de Intención Estructurada

El anfitrión interpreta el lenguaje natural y pasa la intención estructurada a la capa de integración. La capa de integración valida que la intención ya interpretada falle de forma cerrada.

No implemente ni confíe en un analizador de lenguaje natural de Python, un buscador de palabras clave, un generador de SQL genérico, una ejecución arbitraria de Python o una autoridad analítica generada por LLM.

La intención puede transportar solo conceptos transitorios mínimos como clase de pregunta, ID de métrica, períodos gobernados explícitos, alcance, agrupación, selección de fuente, selección de mapeo e intención de afirmación.

La intención no debe transportar fórmulas de métrica, valores calculados, referencias de evidencia, huellas digitales, referencias de ValidatedResult o permiso de ClaimDecision.

Mapeo de Lenguaje Natural

La interpretación del lenguaje natural pertenece al agente. El ejecutor determinista acepta solo argumentos estructurados ya interpretados.

Mapee las solicitudes de usuario compatibles de la siguiente manera:

• "¿Cuáles fueron los ingresos/pedidos/AOV en el cuarto trimestre de 2026?" se asigna a question-class=single_period_metric, metric=revenue|orders|aov, result-period-role=comparison y períodos de referencia/comparación gobernados explícitos.
• "¿Cómo cambiaron los ingresos del tercer trimestre de 2026 al cuarto trimestre de 2026?" se asigna a question-class=revenue_change, metric=revenue_change, períodos de referencia/comparación gobernados explícitos, y una intención de afirmación descriptiva.
• "¿Por qué cayeron los ingresos del tercer trimestre de 2026 al cuarto trimestre de 2026?" se asigna a question-class=diagnostic_revenue_drop, metric=revenue_change, períodos de referencia/comparación gobernados explícitos, una intención de afirmación descriptiva y una intención de afirmación de diagnóstico. El cambio descriptivo de ingresos solo puede mostrarse si la autoridad de CommerceLens lo permite. La explicación de diagnóstico debe rechazarse bajo la versión Pública v0.1.

Si el usuario no ha proporcionado un archivo fuente, tipo de fuente, hoja XLSX seleccionada cuando sea necesario, o períodos gobernados explícitos, solicite una aclaración. Las solicitudes no compatibles no deben aproximarse.

UX de Mapeo de Esquema

Después de que el archivo fuente esté disponible, inspeccione los encabezados fuente antes de ejecutar el análisis material.

Si todos los campos canónicos requeridos para el análisis compatible solicitado están disponibles como nombres de columna canónicos exactos, continúe sin solicitar confirmación de mapeo. El mapeo de identidad exacto ya es explícito bajo el contrato canónico de CommerceLens.

Si faltan campos canónicos exactos pero los encabezados fuente semánticamente compatibles parecen estar disponibles, proponga un mapeo de origen a canónico y pida al usuario que confirme o lo corrija. La propuesta no es autoridad. No ejecute el análisis material hasta que el usuario confirme explícitamente o proporcione el mapeo.

El usuario puede confirmar todos los mapeos propuestos, corregir uno o más mapeos, rechazar el mapeo o proporcionar un mapeo faltante. Si persiste la ambigüedad, haga una aclaración dirigida, como qué columna fuente representa line_revenue. No infiera confirmación a partir del silencio.

Cuando se confirme, pase al ejecutor un mapeo estructurado de origen a canónico con los encabezados fuente como claves y los campos canónicos como valores. El ejecutor convierte esto al contrato CanonicalMapping existente, y la autoridad determinista de CommerceLens aún lo valida con validate_mapping(...) antes del análisis.

Falle de forma cerrada cuando la autoridad de mapeo requerida no esté resuelta, sea rechazada, ambigua o rechazada por validación determinista. Nunca recurra al cálculo de LLM, cambio de nombre silencioso, mapeo adivinado o análisis genérico de dataframe.

Ejecutor Determinista

Use skills/commerce-lens/scripts/run_public_analysis.py como la superficie de comando de primera ejecución. Traduce argumentos estructurados en:

• PublicAnalysisIntent
• PublicSourceSelection
• run_public_analysis(...)

El ejecutor crea automáticamente ubicaciones temporales ArtifactStore y MetadataStore cuando no se proporcionan. Estos son detalles de implementación; el usuario no necesita construirlos.

Ejemplo:

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 "¿Cómo cambiaron los ingresos del tercer trimestre de 2026 al cuarto trimestre de 2026?"

Ejemplo de mapeo no canónico confirmado:

python3.11 skills/commerce-lens/scripts/run_public_analysis.py \
  --source ruta/al/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 el primer uso, verifique Python >=3.11. Si no se puede importar CommerceLens, cree un entorno aislado, instale el paquete local e invoque el ejecutor desde ese entorno:

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

No oculte fallos de arranque. Si Python >=3.11 o las dependencias del paquete no se pueden instalar, informe del fallo de instalación/ejecución. Nunca responda haciendo que el LLM calcule métricas materiales por sí mismo.

Autoridad de Evidencia y Afirmación

Ninguna afirmación material puede presentarse sin evidencia trazable del motor determinista de CommerceLens.

Los valores de métricas materiales deben provenir del ejecutor determinista. La habilidad no debe calcular ingresos, pedidos, AOV, cambio de ingresos ni ningún valor derivado.

Las afirmaciones de diagnóstico, causales, predictivas y prescriptivas permanecen cerradas bajo la versión Pública v0.1. Las solicitudes no compatibles no deben aproximarse.

Para preguntas como "¿Por qué cayeron los ingresos del tercer trimestre de 2026 al cuarto trimestre de 2026?", mantenga la proposición descriptiva compatible de cambio de ingresos separada de la proposición de diagnóstico no compatible. La parte descriptiva puede proceder a través de run_analysis(...) y evaluate_claim(...). La parte de diagnóstico debe enviarse solo como una intención de afirmación no compatible y renderizarse como rechazada si el ClaimDecision es inadmisible.

Use este rechazo acotado exacto cuando corresponda:

Evidencia insuficiente para concluir por qué disminuyeron los Ingresos.

No enumere causas especulativas.

Renderización de Respuesta

Renderice afirmaciones materiales compatibles solo cuando un ClaimDecision autorizado lo permita.

Mantenga el Estado de la Métrica, el Estado de la Afirmación y la disposición de soporte público distintos. AOV con Pedidos igual a cero es MetricState UNDEFINED, valor None y undefined_reason orders_equals_zero; esto no es cero numérico.

La respuesta pública puede incluir Afirmaciones / Respuesta Compatibles, Resumen de Evidencia, Estado de la Métrica, Estado de la Afirmación, Limitaciones, Conclusiones No Compatibles, Evidencia Adicional Necesaria, Aclaración Requerida y Evidencia Bloqueada / Insuficiente.

No cree nuevos valores de métrica, fórmulas, evidencia, resultados de validación, hallazgos, explicaciones alternativas o recomendaciones en la respuesta.