experiment(intent): 수정 전 라벨 baseline과 A.X 테스트 추가

fowoco-knowledge/data/experiments/intent/provisional-char-ngram-nb-v1/report.yaml

@@ -0,0 +1,116 @@
+experiment_id: FOWOCO-INTENT-PROVISIONAL-CHAR-NGRAM-NB-V1
+version: 0.1.0
+status: provisional_pre_consensus
+purpose: 수정 전 라벨로 모델링·평가 파이프라인과 오류 유형을 검증하는 하한선
+source:
+  dataset_id: FOWOCO-HR-INTENT-CANDIDATES
+  version: 1.1.0
+  status: recheck_required
+  path: data/intent/hr_intent_dataset.jsonl
+  record_count: 1340
+  sha256: 4f4ebfdd4170a78def33e31edbed8315921c0b67934f5ff8612595dcd479bed2
+  manifest_path: data/intent/manifest.yaml
+split:
+  manifest_path: data/intent/splits/provisional-v1/manifest.yaml
+  manifest_sha256: 3118f4aa8e4c4859efefed1cbde04ad7773ae0e77323ad9022b3fee9e0b2364b
+  status: provisional_pending_consensus
+  train:
+    path: data/intent/splits/provisional-v1/train_ids.txt
+    record_count: 1072
+    sha256: 264011422e233e28ab7ab4b93579f634a6e53c00730d254b7ca2749d71575cb6
+  validation:
+    path: data/intent/splits/provisional-v1/validation_ids.txt
+    record_count: 268
+    sha256: 96da74e15519f9610ef316bc3e7499d06832c36564180607a3565b851bc8ba85
+  validation_used_for_training_or_thresholds: false
+model:
+  family: multilabel_multinomial_naive_bayes
+  features: character_ngrams
+  ngram_min: 2
+  ngram_max: 5
+  alpha: 1.0
+  threshold_calibration: train_in_sample_f1_only
+  thresholds:
+    WORK_INSTRUCTION: 6.096038744112
+    DOCUMENT_REQUEST: 37.285624039926
+    PAYROLL_EXPLANATION: 20.199619612251
+    WORKER_ONBOARDING: 35.842590492089
+    EMPLOYMENT_CHANGE: 18.694991220673
+    EXPIRY_RENEWAL: 25.444998825749
+    OUT_OF_SCOPE: 40.111322163511
+  evidence_strategy: highest_positive_weight_contiguous_token_span
+  evidence_max_tokens: 6
+  external_dependencies: []
+metrics:
+  record_count: 268
+  intent_exact_match: 0.854478
+  macro_f1: 0.938066
+  micro_f1: 0.940361
+  per_intent:
+    WORK_INSTRUCTION:
+      precision: 0.876712
+      recall: 0.914286
+      f1: 0.895105
+      support: 70
+    DOCUMENT_REQUEST:
+      precision: 1.0
+      recall: 0.971429
+      f1: 0.985507
+      support: 70
+    PAYROLL_EXPLANATION:
+      precision: 0.942308
+      recall: 0.875
+      f1: 0.907407
+      support: 56
+    WORKER_ONBOARDING:
+      precision: 1.0
+      recall: 0.923077
+      f1: 0.96
+      support: 39
+    EMPLOYMENT_CHANGE:
+      precision: 0.947368
+      recall: 0.964286
+      f1: 0.955752
+      support: 56
+    EXPIRY_RENEWAL:
+      precision: 0.959184
+      recall: 0.979167
+      f1: 0.969072
+      support: 48
+    OUT_OF_SCOPE:
+      precision: 1.0
+      recall: 0.807692
+      f1: 0.893617
+      support: 26
+  evidence_gold_exact_match: 0.286136
+  evidence_gold_item_count: 339
+  structural_gate_rates:
+    JSON_SCHEMA_VALID: 1.0
+    EVIDENCE_EXACT_SUBSTRING: 1.0
+    INTENT_ORDER: 1.0
+    OUT_OF_SCOPE_EXCLUSIVE: 1.0
+  error_case_counts:
+    EVIDENCE_TOO_BROAD: 114
+    EXTRA_INTENT: 17
+    MISSING_INTENT: 24
+artifacts:
+  predictions:
+    path: data/experiments/intent/provisional-char-ngram-nb-v1/predictions.jsonl
+    record_count: 268
+    sha256: 2b138faee3c91ab7fcae5e7fa7ed0fcc613138b07fc05fe1d65f0ecae063c108
+claims_not_allowed:
+- 최종 모델 성능
+- Gold Test 성능
+- 운영 배포 가능
+- A/B consensus가 반영된 라벨 성능
+rerun_required_when:
+- A/B consensus가 원본 라벨을 변경
+- source 또는 split checksum이 변경
+- Intent 규칙 또는 모델 설정이 변경
+limitations:
+- Reviewer B와 A/B consensus 전 수정 전 라벨을 사용함
+- Train 내부 점수로 threshold를 정해 운영 threshold로 사용할 수 없음
+- 문자 n-gram Naive Bayes는 A.X 또는 Transformer 모델 후보를 대체하지 않음
+- evidence 추출은 규칙 기반 하한선이며 자연스러움이나 최소 완결 구간을 보장하지 않음
+- Validation은 baseline 개발용이며 독립 Gold Test가 아님
+- 모델 학습·추론 코드는 최종적으로 fowoco/ai 저장소로 이전해야 함

fowoco-knowledge/docs/INTENT_AX_TESTING.md

@@ -0,0 +1,161 @@
+# A.X Intent 분류 테스트 가이드
+
+## 1. 목적
+
+Intent 규칙 v1.1 프롬프트를 A.X에 보내 `Intent + evidence` 출력과 오류 유형을
+확인한다. 현재 원본 라벨과 Validation은 `recheck_required` 상태이므로 결과를 최종
+모델 또는 Gold Test 성능으로 주장하지 않는다.
+
+공식 자료:
+
+- [skt/A.X-4.0-Light 모델 카드](https://huggingface.co/skt/A.X-4.0-Light)
+- [SKT A.X 4.0 API 문서](https://github.com/SKT-AI/A.X-4.0/blob/main/apis/README.md)
+
+공식 모델 카드는 A.X 4.0 Light가 7B 모델이며 Transformers와 vLLM 실행 방법을
+제공한다. 무료 guest API 문서는 모델명을 `ax4`로만 안내하므로, 해당 API 결과를
+A.X 4.0 Light 결과라고 단정하지 않는다.
+
+## 2. 현재 공식 guest API 상태
+
+2026-07-27 확인 결과, 공식 API 문서에 기재된
+`https://guest-api.sktax.chat/v1`은 HTTP 연결에는 성공하지만 다음 종료 안내만
+반환한다.
+
+```text
+Guest 용 API Endpoint 서비스는 종료되었습니다.
+```
+
+따라서 문서에 적힌 공개 key와 guest endpoint로는 현재 모델 추론을 시험할 수 없다.
+테스트하려면 팀에서 사용할 수 있는 A.X API endpoint와 key를 받거나, 아래 5절처럼
+공식 Light 모델을 로컬에서 실행해야 한다. 이 저장소는 종료된 guest 주소를 작동하는
+기본값으로 사용하지 않는다.
+
+## 3. 팀 A.X API 설정
+
+API key는 코드, `.env.example`, 명령행 인자 또는 결과 파일에 기록하지 않는다.
+사용하는 A.X 제공자에서 OpenAI 호환 endpoint와 key를 확인해 환경변수로만 설정한다.
+
+```bash
+export AX_API_KEY="팀에서 발급받은 키"
+export AX_BASE_URL="팀에서 전달받은 OpenAI 호환 base URL"
+export AX_MODEL="팀에서 전달받은 모델명"
+```
+
+`ADOTX_API_KEY`도 호환한다. `.env` 파일은 Git에서 제외되지만 셸이 자동으로 읽지는
+않으므로 직접 `source .env` 하거나 환경변수를 내보내야 한다.
+
+## 4. API로 한 문장 테스트
+
+실제 개인정보 대신 `WRK-001` 같은 더미 식별자를 사용한다.
+
+```bash
+python -m fowoco_knowledge test-intent-ax \
+  "WRK-001 체류기간 만료가 다가오니 여권 사본 받아줘" \
+  --confirm-external
+```
+
+출력에서 다음 항목을 확인한다.
+
+- `requested_model`, `returned_model`: 요청·응답 모델명
+- `raw_content`: A.X 원문 응답
+- `parsed_output`: 추출된 JSON
+- `parse_strategy`: 직접 JSON, 코드 펜스, 부가설명 속 JSON 여부
+- `issues`: Schema, evidence substring, 순서, 중복, OUT_OF_SCOPE 오류
+
+구조 오류가 있으면 명령은 종료 코드 1을 반환한다. 모델 응답을 정답처럼 자동
+수정하지 않는다.
+
+## 5. API로 소량 Smoke Evaluation
+
+Validation 앞부분 5건:
+
+```bash
+python -m fowoco_knowledge run-intent-ax-evaluation \
+  --limit 5 \
+  --delay-seconds 1 \
+  --confirm-external
+```
+
+특정 원본 ID:
+
+```bash
+python -m fowoco_knowledge run-intent-ax-evaluation \
+  --ids 20,74,198,653,1206 \
+  --delay-seconds 1 \
+  --confirm-external
+```
+
+전체 Validation 268건은 제공자의 호출 제한과 비용을 확인한 뒤에만 실행한다.
+
+```bash
+python -m fowoco_knowledge run-intent-ax-evaluation \
+  --all-validation \
+  --delay-seconds 1 \
+  --confirm-external
+```
+
+결과는 기본적으로 Git에서 제외되는 다음 로컬 경로에 저장된다.
+
+```text
+local-data/experiments/intent/ax-zero-shot-v1/
+├── predictions.jsonl
+└── report.yaml
+```
+
+Report는 Intent Exact Match, Macro/Micro F1, evidence 정답 완전일치, 구조 Gate,
+오류 건수와 token usage를 분리해 기록한다.
+
+## 6. 공식 A.X 4.0 Light를 로컬에서 직접 테스트
+
+최초 1회 로컬 실행 의존성을 설치한다.
+
+```bash
+pip install -e ".[ax-local]"
+```
+
+Apple Silicon Mac에서는 다음처럼 한 문장을 테스트한다.
+
+```bash
+python -m fowoco_knowledge test-intent-ax-local \
+  "WRK-001 체류기간 만료가 다가오니 여권 사본 받아줘" \
+  --device mps \
+  --confirm-model-download
+```
+
+`--confirm-model-download`는 공식 `skt/A.X-4.0-Light` 모델을 Hugging Face에서
+처음 내려받고 메모리에 올리는 작업을 명시적으로 허용한다. 7B BF16 원본 가중치는
+대용량이며, 24GB Mac에서도 다른 앱의 메모리 사용량에 따라 로딩에 실패할 수 있다.
+CI에서는 이 명령을 실행하지 않는다.
+
+로컬 명령도 API 명령과 동일한 `raw_content`, `parsed_output`, `issues` 구조를
+출력하므로 Intent와 evidence 결과를 그대로 비교할 수 있다.
+
+## 7. GPU 서버의 A.X 4.0 Light에 연결
+
+공식 모델 카드의 vLLM 예시처럼 GPU 서버에서 Light 모델을 OpenAI 호환 endpoint로
+실행한 경우 다음처럼 연결한다.
+
+```bash
+vllm serve skt/A.X-4.0-Light
+
+export AX_BASE_URL="http://localhost:8000/v1"
+export AX_MODEL="skt/A.X-4.0-Light"
+export AX_API_KEY="local"
+
+python -m fowoco_knowledge test-intent-ax \
+  "WRK-001 체류기간 연장 준비해줘" \
+  --confirm-external
+```
+
+현재 개발 Mac은 Apple Silicon이므로 CUDA 기반 vLLM 서버를 직접 실행하는 환경과는
+다르다. Mac에서 quantized 모델을 별도로 구동할 경우에도 OpenAI 호환 endpoint만
+제공하면 같은 테스트 명령을 사용할 수 있다.
+
+## 8. 개인정보와 해석 제한
+
+- 실제 외국인등록번호, 여권번호, 전화번호, 계좌번호를 전송하지 않는다.
+- 코드의 기본 개인정보 패턴 검사는 보조 장치이며 사람 이름과 모든 식별자를 완전히
+  탐지하지 못한다.
+- 종료된 guest API 연결 성공을 모델 추론 성공으로 표현하지 않는다.
+- API의 `ax4` 결과를 `A.X-4.0-Light` 결과로 바꿔 표현하지 않는다.
+- 수정 전 라벨로 얻은 점수는 consensus 반영 후 같은 prompt로 다시 측정한다.

fowoco-knowledge/docs/INTENT_MODELING_HANDOFF.md

@@ -13,6 +13,8 @@ knowledge 저장소는 다음 자료를 제공한다.
 | 분할 manifest | `data/intent/splits/provisional-v1/manifest.yaml` | consensus 대기 |
 | 평가 정책 | `knowledge/intent_evaluation_policy.yaml` | baseline 전 임시 목표 |
 | Gold 계획 | `docs/INTENT_GOLD_TEST_PLAN.md` | 작성 전 |
+| 임시 baseline 가이드 | `docs/INTENT_PROVISIONAL_BASELINE.md` | 수정 전 라벨 실험 |
+| A.X 테스트 가이드 | `docs/INTENT_AX_TESTING.md` | zero-shot smoke 준비 |
 
 AI 저장소는 프롬프트, 모델 어댑터, 추론·평가 코드와 실험 결과를 관리한다.
 

fowoco-knowledge/docs/INTENT_PROVISIONAL_BASELINE.md

@@ -0,0 +1,69 @@
+# Intent 수정 전 라벨 Provisional Baseline
+
+## 목적
+
+이 baseline은 A/B consensus 전 원본 1,340건으로 모델링 파이프라인이 정상적으로
+작동하는지 확인하는 하한선이다. 최종 모델 또는 Gold Test 성능을 주장하지 않는다.
+
+## 데이터
+
+- Source: `data/intent/hr_intent_dataset.jsonl`
+- 상태: `recheck_required`
+- Train: 1,072건
+- Validation: 268건
+- Split: `data/intent/splits/provisional-v1/manifest.yaml`
+- Reviewer A 제안: 원본에 미반영
+- Reviewer B·Consensus: 대기
+
+Validation ID는 모델 학습과 threshold 산정에 사용하지 않는다.
+
+## 모델
+
+외부 라이브러리와 API 없이 실행되는 문자 n-gram 다중라벨 Naive Bayes다. 각
+Intent를 one-vs-rest 방식으로 학습하고 Train 내부 점수만으로 임시 threshold를
+정한다. evidence는 해당 Intent에 양의 가중치를 갖는 연속 토큰 구간을 선택한다.
+
+이 모델은 데이터·평가 파이프라인 검증용이며 A.X, BERT 또는 Transformer 후보를
+대체하지 않는다.
+
+실제 A.X zero-shot 테스트는
+[`INTENT_AX_TESTING.md`](INTENT_AX_TESTING.md)를 따른다.
+
+## 저장소 경계
+
+AI 저장소의 작업 충돌을 피하기 위해 현재는 knowledge 저장소의 `model` 브랜치에서
+임시로 실행한다. 이 브랜치의 모델 학습·추론 코드는 knowledge `main` 병합 대상이
+아니며, 실험 구조가 확인되면 `fowoco/ai` 저장소로 이전한다. knowledge 저장소에는
+최종적으로 데이터 계약, split, 평가 정책과 검증 리포트만 남긴다.
+
+## 실행
+
+```bash
+python -m fowoco_knowledge run-intent-provisional-baseline
+```
+
+생성 파일:
+
+- `data/experiments/intent/provisional-char-ngram-nb-v1/report.yaml`
+- `data/experiments/intent/provisional-char-ngram-nb-v1/predictions.jsonl`
+
+Report에는 source·split checksum, 모델 설정, Intent 지표, evidence 일치율, 구조적
+Gate, 오류 유형과 금지 주장을 기록한다. 생성 시각은 넣지 않아 같은 입력과 코드에서
+동일한 결과를 재생성할 수 있다.
+
+## 결과 해석
+
+- `intent_exact_match`, `macro_f1`, `micro_f1`: 수정 전 라벨과의 일치 정도
+- `evidence_gold_exact_match`: 기존 evidence와 완전히 같은 구간을 예측한 비율
+- `structural_gate_rates`: JSON Schema, exact substring, 순서, OUT_OF_SCOPE 단독성
+- `error_case_counts`: Intent 누락·추가와 evidence 과다 범위 등의 오류 건수
+
+Validation은 개발 중 확인용이므로 모델 선택을 반복하면 Validation에도 과적합될 수
+있다. 최종 비교는 별도로 잠근 Gold Test 240건이 확보된 뒤 수행한다.
+
+## Consensus 반영 후
+
+1. 원본 JSONL과 `data/intent/manifest.yaml` version·checksum을 갱신한다.
+2. PR #33의 split 생성기를 같은 seed로 다시 실행한다.
+3. 이 baseline을 다시 실행한다.
+4. 수정 전·후 결과를 다른 데이터 version으로 보관하고 직접 혼합하지 않는다.