Wave 4 ML API

Status: Default OFF (rollout_pct 0 영속) / Owner: AI-Engine / Last Updated: 2026-05-05 (세션 103)

Overview

Wave 4 ML 거래 분류기 (J) + 판매량 예측기 (K). ADR-0123 Default OFF 영속, User 명시 rollout 시에만 활성.

Architecture

[키워드 검색] → [J 분류기 (sklearn)] → [거래 분류 prob] ─┐
                                                           ├→ [최종 verdict]
[키워드 검색] → [K 회귀기 (sklearn)] → [판매량 추정]    ─┘

Endpoints

POST /api/agents/analyze

기존 AI 에이전트 분석 (Phase 1~3 orchestrator). Wave 4 ML inference 통합:

• enable_ml_inference_classifier flag ON 시 → models/classifier_v*.skops 추론
• enable_ml_inference_sales flag ON 시 → models/sales_v*.skops 추론
• OFF 시 → _classify_with_gemini 또는 SalesEstimator.estimate 폴백 (A04 STRENGTHENED)

Pre-condition (Default OFF 해제 전 필수)

1. D+7 데이터 누적 (keyword_rank_history >= 1000 rows)
2. APScheduler 03:30 KST daily_rank_tracking 자동 cron
3. ML cron 학습 진입 (host crontab ml_trainer_cron.sh)
4. metric gate 충족: J val_f1 >= 0.70, K val_MAPE <= 0.30
5. apps/api/models/manifest.json status="active" 확증
6. 사후 검증: bash scripts/wave4/d7_postcheck.sh
7. User explicit rollout 결정 (scripts/wave4/rollout_step.sh --flag enable_ml_inference_classifier --pct 10)

Rollout 단계

단계	rollout_pct	검증
1	10%	A/B 분포 검증
2	50%	metric drift 모니터
3	100%	전체 활성
Rollback	0%	--rollback 옵션 즉시 회귀

Related

• ADR-0119 (threshold gate)
• ADR-0123 (Default OFF)
• ADR-0129 amend (host venv → docker compose exec, M-101-E1 RESOLVED)
• scripts/wave4/d7_postcheck.sh
• scripts/wave4/rollout_step.sh