daniel-j-lin/commerce-lens

CommerceLens Public v0.1 Skill

이 Skill은 경계가 명확한 커머스 및 전자상거래 정형 데이터 분석을 위한 통제된 오케스트레이션 경계로 사용됩니다.

Skill은 무엇을 물을지 결정할 수 있습니다. Skill은 무엇이 사실인지 결정해서는 안 됩니다.

워크플로우

1. 사용자 질문을 구조화된 Public v0.1 의도(Intent)로 해석합니다.
2. 의도가 승인된 질문, 메트릭, 소스, 기간, 범위, 그룹화 및 주장(Claim) 경계 내에 있는지 검증합니다.
3. 기간, 소스 선택 또는 매핑 권한이 실질적으로 모호한 경우 명확화를 요청합니다.
4. 기존의 통제된 AnalysisRequest를 구성합니다.
5. CommerceLens 애플리케이션 서비스를 통해 run_analysis(...)를 호출합니다.
6. 정확한 AnalysisResult 참조와 영속화된 커널 권한에서만 ClaimCandidate 권한을 바인딩합니다.
7. 지원되는 모든 공개 주장에 대해 evaluate_claim(...)을 호출합니다.
8. 공개 응답 투영(Public Response Projection)만 렌더링합니다.

지원되는 Public v0.1 질문

지원되는 메트릭은 정확히 다음과 같습니다:

• revenue
• orders
• aov
• revenue_change

지원되는 분석 클래스는 정확히 다음과 같습니다:

• 단일 통제 기간 수익
• 단일 통제 기간 주문
• 단일 통제 기간 AOV
• 명시적으로 통제된 두 개의 비교 가능한 기간 간 수익 변화

그룹화는 NONE입니다.

주요 소스 워크플로우는 CSV와 XLSX입니다. SQLite는 커널에 계속 사용 가능할 수 있지만 Public v0.1의 주요 워크플로우는 아닙니다.

구조화된 의도 책임

호스트(Agent)는 자연어를 해석하고 구조화된 의도를 통합 레이어에 전달합니다. 통합 레이어는 이미 해석된 의도가 fail-closed 방식으로 검증합니다.

Python 자연어 파서, 키워드 매처, 일반 SQL 생성기, 임의 Python 실행 또는 LLM 생성 분석 권한을 구현하거나 의존하지 마십시오.

의도는 질문 클래스, 메트릭 ID, 명시적 통제 기간, 범위, 그룹화, 소스 선택, 매핑 선택 및 주장 의도와 같은 최소한의 일시적 개념만 전달할 수 있습니다.

의도는 메트릭 공식, 계산된 값, 증거 참조, 지문, ValidatedResult 참조 또는 ClaimDecision 권한을 전달해서는 안 됩니다.

자연어 매핑

자연어 해석은 Agent에 속합니다. 확정적 러너는 이미 해석된 구조화된 인수만 허용합니다.

지원되는 사용자 요청을 다음과 같이 매핑하십시오:

• "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, 명시적 통제 기준/비교 기간, 하나의 설명적 주장 의도, 하나의 진단 주장 의도로 매핑됩니다. 설명적 수익 변화는 CommerceLens 권한이 허용하는 경우에만 표시될 수 있습니다. 진단 설명은 Public v0.1에서 거부되어야 합니다.

사용자가 소스 파일, 소스 유형, 필요한 경우 선택한 XLSX 시트 또는 명시적 통제 기간을 제공하지 않은 경우 명확화를 요청하십시오. 지원되지 않는 요청은 근사화해서는 안 됩니다.

스키마 매핑 UX

소스 파일을 사용할 수 있게 된 후, 실제 분석을 실행하기 전에 소스 헤더를 검사하십시오.

요청된 지원 분석에 필요한 모든 정식 필드가 정확한 정식 열 이름으로 사용 가능한 경우, 매핑 확인을 요청하지 않고 계속 진행하십시오. 정확한 동일성 매핑은 CommerceLens 정식 계약 하에 이미 명시적입니다.

정확한 정식 필드가 누락되었지만 의미적으로 호환되는 소스 헤더가 있는 것으로 보이는 경우, 소스-정식 매핑을 제안하고 사용자에게 확인 또는 수정을 요청하십시오. 제안은 권한이 아닙니다. 사용자가 명시적으로 확인하거나 매핑을 제공할 때까지 실제 분석을 실행하지 마십시오.

사용자는 제안된 모든 매핑을 확인하거나, 하나 이상의 매핑을 수정하거나, 매핑을 거부하거나, 누락된 매핑을 제공할 수 있습니다. 모호성이 남아 있으면 어떤 소스 열이 line_revenue를 나타내는지와 같은 대상화된 명확화를 요청하십시오. 침묵을 확인으로 추정하지 마십시오.

확인되면 소스 헤더를 키로, 정식 필드를 값으로 하는 구조화된 소스-정식 매핑을 러너에 전달하십시오. 러너는 이를 기존 CanonicalMapping 계약으로 변환하며, CommerceLens 확정적 권한은 분석 전에 validate_mapping(...)으로 여전히 이를 검증합니다.

필요한 매핑 권한이 해결되지 않았거나, 거부되었거나, 모호하거나, 확정적 검증에서 거부된 경우 fail-closed 처리하십시오. 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 엔진의 추적 가능한 증거 없이 자료 주장을 제시할 수 없습니다.

자료 메트릭 값은 확정적 러너에서 가져와야 합니다. Skill은 수익, 주문, AOV, 수익 변화 또는 파생 값을 계산해서는 안 됩니다.

진단, 인과, 예측 및 처방 주장은 Public v0.1 하에서 fail-closed 상태를 유지합니다. 지원되지 않는 요청은 근사화해서는 안 됩니다.

"Q3 2026에서 Q4 2026으로 수익이 왜 떨어졌나요?"와 같은 질문의 경우, 지원되는 설명적 수익 변화 명제와 지원되지 않는 진단 명제를 분리하여 유지하십시오. 설명적 부분은 run_analysis(...) 및 evaluate_claim(...)을 통해 진행될 수 있습니다. 진단 부분은 지원되지 않는 주장 의도로만 제출되어야 하며 ClaimDecision이 허용 불가능인 경우 거부된 것으로 렌더링되어야 합니다.

해당되는 경우 다음의 제한된 거부 문구를 사용하십시오:

수익이 감소한 이유를 결론내리기에 충분한 증거가 없습니다.

추측성 원인을 나열하지 마십시오.

응답 렌더링

권위 있는 ClaimDecision이 허용하는 경우에만 지원되는 자료 주장을 렌더링하십시오.

메트릭 상태, 주장 상태 및 공개 지원 상태를 구분하여 유지하십시오. 주문이 0인 AOV는 MetricState UNDEFINED, 값 None, undefined_reason orders_equals_zero입니다. 이는 숫자 0이 아닙니다.

공개 응답에는 지원되는 주장/답변, 증거 요약, 메트릭 상태, 주장 상태, 제한 사항, 지원되지 않는 결론, 추가 증거 필요, 명확화 필요, 차단됨/불충분한 증거가 포함될 수 있습니다.

응답에 새로운 메트릭 값, 공식, 증거, 검증 결과, 소견, 대체 설명 또는 권장 사항을 생성하지 마십시오.