diff --git a/docs/superpowers/specs/2026-05-22-lotto-weight-evolver-design.md b/docs/superpowers/specs/2026-05-22-lotto-weight-evolver-design.md new file mode 100644 index 0000000..e3174d2 --- /dev/null +++ b/docs/superpowers/specs/2026-05-22-lotto-weight-evolver-design.md @@ -0,0 +1,419 @@ +# Lotto Weight Evolver — 자율 학습 루프 설계 (v2) + +- **상태**: Draft (사용자 리뷰 대기) +- **작성일**: 2026-05-22 +- **대상 컨테이너**: lotto (lotto-lab) + agent-office (텔레그램 보고) +- **선행 작업**: v1 LottoAgent 능동성 확장 (2026-05-20 배포) +- **목표**: 5종 시뮬 점수 가중치를 매주 6가지로 변형 시도 → 토요일 회고 → winner 가중치를 다음 주 base로 적용 → 무한 반복 자가 학습 루프 + +--- + +## 1. 문제 정의 + +현재 `analyzer.score_combination()`은 5종 점수(`score_frequency`, `score_fingerprint`, `score_gap`, `score_cooccur`, `score_diversity`)를 **균등 합산**으로 `score_total`을 계산한다. 어떤 메트릭이 실제 추첨 결과와 더 잘 상관되는지에 대한 학습 없이 가중치가 고정. + +또한 `purchase_history` 기반 `strategy_evolver`는 **사용자가 실제 구매한 번호만** 학습 시그널로 사용. 사람이 안 사면 학습 안 됨. + +사용자 요구: 에이전트가 사람 없이도 **매일 다른 가중치로 시뮬레이션 → 번호 시도 → 토요일 추첨 후 best 가중치 식별 → 다음주 base 갱신**의 무한 학습 루프. + +## 2. 의사결정 요약 + +| 결정 사항 | 선택 | 비고 | +|---|---|---| +| 학습 대상 | 시뮬 점수 5종 가중치 (`W = [w_freq, w_finger, w_gap, w_cooccur, w_diversity]`) | 메타 전략 가중치는 strategy_evolver가 별도 학습 (v2에서 손대지 않음) | +| 탐험 전략 | 현재 base 주변 4개 perturbation + Dirichlet 무작위 2개 | 매주 월요일 6개 후보 | +| 일일 시도량 | N = 5 세트/일 × 6일 = 30 세트/주 | 통계적 의미 + 비용 균형 | +| 평가 시그널 | strategy_evolver의 `RANK_BONUS` + `correct/6` | 기존 패턴 재사용으로 일관성 | +| Base 적용 강도 | Hybrid — winner_max_correct ≥ 4면 교체, =3이면 EMA blend (0.3), ≤2면 유지 | 노이즈에 base가 헤매지 않도록 보호 | +| v1과의 결합 | W가 `analyzer.score_combination`에 반영 → best_picks 점수 자동 영향 → v1 시그널 자동 cascade | 별도 통합 코드 없음 | +| strategy_evolver와의 상호작용 | strategy_evolver는 `score_total`을 그대로 입력으로 사용 → W 변경 시 입력 분포가 함께 변함. **의도된 간접 영향** | v3에서 메타 가중치도 함께 학습할 때 명시적으로 분리 검토 | +| 자동 구매 | v2 비포함 | 사람 결정 영역 — purchase_history는 사람이 등록 | + +## 3. 아키텍처 + +### 3.1 컴포넌트 다이어그램 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ lotto-lab (자율 학습 루프 추가) │ +│ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ weight_evolver.py (신규) │ │ +│ │ • generate_weekly_candidates() ← 월 09:00 │ │ +│ │ • apply_today_weight() ← 매일 09:00 │ │ +│ │ • evaluate_weekly() ← 토 22:00 │ │ +│ │ • update_base() ← evaluate 안에서 │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ analyzer.score_combination(numbers, cache, │ │ +│ │ weights=None) 확장 │ │ +│ │ • weights=None → 균등 합산 (기존 호환) │ │ +│ │ • weights=[..] → 가중 합산 │ │ +│ └─────────────────────────────────────────────────────┘ │ +│ ↓ │ +│ lotto.db 신규 테이블 3개 │ +│ • weight_trials (주별 6일치 후보 가중치) │ +│ • auto_picks (매일 N=5 시도 번호 + 채점 결과) │ +│ • weight_base_history (base 변경 이력) │ +│ │ +│ 기존 시뮬 cron (00/04/08/12/16/20:05) — 변경 없음. │ +│ 단 best_picks 재계산 시 활성 W를 읽어 적용. │ +└─────────────────────────────────────────────────────────────┘ + ↓ (HTTP) +┌─────────────────────────────────────────────────────────────┐ +│ agent-office │ +│ │ +│ cron 신규 1종: lotto_evolution_weekly (토 22:15) │ +│ LottoAgent.run_weekly_evolution_report() (신규) │ +│ notifiers/telegram_lotto.send_evolution_report() (신규) │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 3.2 책임 경계 + +- **lotto-lab**: 가중치 생성·적용·평가·base 갱신 + DB CRUD + API. 시그널/알림 책임 없음. +- **agent-office**: 토요일 22:15 lotto-lab API 폴링 → 텔레그램 보고 1통. +- **v1 (signals layer)**: 변경 없음. W 변경의 효과는 best_picks 분포 변화로 자동 흡수. +- **strategy_evolver (메타 가중치 5종)**: 그대로 둠. + +## 4. 가중치 진화 알고리즘 + +### 4.1 Weight Vector + +``` +W = [w_freq, w_finger, w_gap, w_cooccur, w_diversity] +제약: w_i ≥ 0.05, sum(W) = 1.0 +``` + +(MIN_WEIGHT=0.05는 한 메트릭이 죽지 않도록 보호. strategy_evolver의 MIN_WEIGHT 패턴.) + +### 4.2 주간 6개 후보 생성 + +`generate_weekly_candidates()` — 매주 월요일 09:00 KST. + +```python +W_base = get_current_base() # weight_base_history 최신 row, 없으면 [0.2]*5 + +# 4개 Local Perturbation +for i in range(4): + noise = np.random.normal(0, 0.05, size=5) + W_i = W_base + noise + W_i = clamp(W_i, min=0.05) + W_i = W_i / W_i.sum() + save_trial(week_start, day=i, W_i, source='perturb', base=W_base) + +# 2개 Dirichlet 탐험 +for i in range(4, 6): + W_i = np.random.dirichlet([2.0]*5) + W_i = clamp(W_i, min=0.05) + W_i = W_i / W_i.sum() + save_trial(week_start, day=i, W_i, source='dirichlet', base=W_base) +``` + +- `σ=0.05` 정규분포: 각 메트릭 ±10%p 안쪽 변동 +- `α=2.0` Dirichlet: 균등 분포에 약간 치우치게, 극단 가중치도 포함 + +### 4.3 일일 W 적용 + +`apply_today_weight()` — 매일 09:00 KST. + +```python +W_today = get_trial(week_start, day_of_week=today) +set_active_weight(W_today) # 메모리 캐시 or DB row (W_active 테이블 또는 file) +generate_n_picks(N=5, weight=W_today) # auto_picks에 5세트 저장 +``` + +같은 W로 그날 기존 시뮬 cron (4시간마다 6회) best_picks 재계산. + +### 4.4 토요일 회고 + +`evaluate_weekly()` — 매주 토요일 22:00 KST (추첨 20:35 KST + sync 21:10 → 22:00 안전). + +```python +winning_numbers = get_latest_draw().numbers # 1224, 1225, ... +trials = get_trials(week_start) # 6 trials + +scores_per_day = [] +for trial in trials: + picks = get_auto_picks(trial.id) # N=5 + day_score = mean( + calc_pick_score(p.numbers, winning_numbers) for p in picks + ) + max_correct = max( + count_match(p.numbers, winning_numbers) for p in picks + ) + update_pick_grades(picks, winning_numbers) # auto_picks 채점 결과 저장 + scores_per_day.append({ + "trial_id": trial.id, + "day": trial.day_of_week, + "weight": trial.weight, + "score": day_score, + "max_correct": max_correct, + }) + +winner = max(scores_per_day, key=lambda s: s.score) +update_base(winner) +``` + +**점수 함수** (strategy_evolver `calc_draw_score` 패턴, 단순화): + +v2에서는 보너스 번호를 평가에 포함하지 않음 → 5개 일치를 2등/3등으로 구분 불가. 따라서 보너스 무시한 단순 매핑: + +```python +# correct → rank 매핑 (보너스 제외) +RANK_BY_CORRECT = { + 6: 1, # 1등 + 5: 3, # 3등 (보너스 평가 안 함 → 2등 표시 X) + 4: 4, + 3: 5, +} +RANK_BONUS = {1: 1.0, 2: 0.8, 3: 0.6, 4: 0.3, 5: 0.1} + +def calc_pick_score(pick_numbers, winning_numbers): + correct = count_match(pick_numbers, winning_numbers[:6]) + base = correct / 6.0 + rank = RANK_BY_CORRECT.get(correct) + bonus = RANK_BONUS.get(rank, 0) + return base + bonus +``` + +(rank=2의 보너스 0.8은 매핑되지 않으므로 v2 점수에 등장하지 않음. v3에서 보너스 번호 평가 도입 시 활성화.) + +### 4.5 Base 갱신 규칙 (Hybrid) + +```python +if winner.max_correct >= 4: + W_base_next = winner.weight + reason = "winner_4plus" +elif winner.max_correct == 3: + W_base_next = 0.3 * winner.weight + 0.7 * W_base_current + reason = "ema_blend" +else: + W_base_next = W_base_current + reason = "unchanged" + +save_to_weight_base_history(W_base_next, reason, winner) +``` + +성과가 약할 때 base를 그대로 두는 게 핵심 — base가 노이즈에 따라 헤매지 않음. + +### 4.6 Cold start (첫 주) + +`weight_base_history`가 비어있으면 `W_base = [0.2]*5` (균등) 가정. 첫 주는 4 perturbation이 모두 균등 주변, 2 Dirichlet 탐험. + +## 5. 데이터 모델 + +### 5.1 weight_trials + +```sql +CREATE TABLE IF NOT EXISTS weight_trials ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + week_start TEXT NOT NULL, -- 'YYYY-MM-DD' (해당 주 월요일) + day_of_week INTEGER NOT NULL, -- 0=월 .. 5=토 + weight_json TEXT NOT NULL, -- '[0.18, 0.22, ...]' + source TEXT NOT NULL, -- 'perturb' | 'dirichlet' + base_at_gen TEXT, -- 생성 시점 W_base (참조용) + created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')), + UNIQUE(week_start, day_of_week) +); +CREATE INDEX idx_wt_week ON weight_trials(week_start, day_of_week); +``` + +### 5.2 auto_picks + +```sql +CREATE TABLE IF NOT EXISTS auto_picks ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + trial_id INTEGER NOT NULL REFERENCES weight_trials(id) ON DELETE CASCADE, + pick_no INTEGER NOT NULL, -- 1..5 + numbers TEXT NOT NULL, -- JSON 정렬 6개 + meta_score REAL, -- 활성 W로 계산한 score_total + correct INTEGER, -- 채점 후 채워짐 + rank INTEGER, -- 1..5 또는 NULL + graded_at TEXT, + created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')), + UNIQUE(trial_id, pick_no) +); +CREATE INDEX idx_ap_trial ON auto_picks(trial_id); +CREATE INDEX idx_ap_graded ON auto_picks(graded_at); +``` + +### 5.3 weight_base_history + +```sql +CREATE TABLE IF NOT EXISTS weight_base_history ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + effective_from TEXT NOT NULL, -- 'YYYY-MM-DD' (적용 시작 월요일) + weight_json TEXT NOT NULL, + source_trial_id INTEGER REFERENCES weight_trials(id), -- NULL=cold start + update_reason TEXT, -- 'winner_4plus' | 'ema_blend' | 'unchanged' | 'cold_start' + winner_score REAL, + winner_max_correct INTEGER, + created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now')) +); +``` + +마이그레이션: `lotto/app/db.py`의 `init_db()`에 `CREATE TABLE IF NOT EXISTS` 추가만으로 idempotent. 기존 테이블 영향 없음. + +## 6. analyzer.score_combination 시그니처 확장 + +```python +# 기존 +def score_combination(numbers, cache) -> Dict[str, float]: + ... + return { + "score_frequency": ..., + "score_fingerprint": ..., + "score_gap": ..., + "score_cooccur": ..., + "score_diversity": ..., + "score_total": sum(5 scores) # 균등 합산 + } + +# 변경 +def score_combination(numbers, cache, weights: Optional[List[float]] = None) -> Dict[str, float]: + ... + scores = [s_freq, s_finger, s_gap, s_cooccur, s_diversity] + if weights is None: + total = sum(scores) + else: + total = sum(s * w for s, w in zip(scores, weights)) + return { + "score_frequency": ..., + ... + "score_total": total + } +``` + +- 기본값 None → 기존 호출 호환 (변경 없는 효과) +- 시뮬 cron / smart_recommendation 등은 `get_active_weight()` 결과 전달 +- 활성 W가 없으면 (cold start 이전) None 그대로 → 균등 합산 폴백 + +### 6.1 활성 W 조회 (`get_active_weight()`) + +별도 캐시 테이블 없이 `weight_trials`에서 오늘 요일 row 직접 조회: + +```python +def get_active_weight() -> Optional[List[float]]: + today = datetime.now(KST).date() + week_start = today - timedelta(days=today.weekday()) # 이번주 월요일 + day_of_week = today.weekday() # 0=월, 6=일 + if day_of_week == 6: # 일요일은 trial 없음 → 직전 토요일 W 유지 + day_of_week = 5 + row = db.get_weight_trial(week_start.isoformat(), day_of_week) + return json.loads(row["weight_json"]) if row else None +``` + +- 컨테이너 재시작·timezone 변화에 영향 없음 (DB 진실 기준) +- 일요일(6)은 토요일 W를 그대로 사용 (회고 cron 22:00 전까지) +- 첫 주 월요일 generate가 안 끝났을 때만 None 반환 → 균등 폴백 + +## 7. API 추가 (lotto-lab) + +| 메서드 | 경로 | 설명 | +|---|---|---| +| GET | `/api/lotto/evolver/status` | 현재 base + 이번주 6 trials + 진행 상황 | +| GET | `/api/lotto/evolver/history?weeks=12` | 주별 winner + base 변경 이력 | +| GET | `/api/lotto/evolver/trials/{week_start}` | 특정 주 trials + 채점 결과 | +| POST | `/api/lotto/evolver/generate-now` | 수동 트리거 (다음 월요일 후보 생성) | +| POST | `/api/lotto/evolver/evaluate-now` | 수동 채점 (디버그) | + +## 8. 스케줄러 cron (lotto-lab) + +```python +scheduler.add_job(generate_weekly_candidates, "cron", day_of_week="mon", hour=9, minute=0, id="weight_evolver_weekly") +scheduler.add_job(apply_today_weight, "cron", hour=9, minute=0, id="weight_evolver_daily") +scheduler.add_job(evaluate_weekly, "cron", day_of_week="sat", hour=22, minute=0, id="weight_evolver_eval") +``` + +순서 보장: 월요일 09:00에 generate가 먼저 row 저장 후 commit, 그 다음 같은 시각 apply가 그 row 읽음. APScheduler가 동일 시간 job 직렬 실행 보장하지 않으므로 **월요일에 generate 함수 마지막에 inline으로 apply_today_weight 호출** — race 제거. + +## 9. agent-office 통합 (텔레그램 주간 보고) + +### 9.1 cron 추가 + +```python +scheduler.add_job(_run_lotto_weekly_evolution_report, "cron", day_of_week="sat", hour=22, minute=15, id="lotto_evolution_weekly") +``` + +### 9.2 LottoAgent.run_weekly_evolution_report (신규) + +```python +async def run_weekly_evolution_report(self) -> dict: + from ..service_proxy import lotto_evolver_status + from ..notifiers.telegram_lotto import send_evolution_report + status = await lotto_evolver_status() + await send_evolution_report(status) + return {"ok": True, **status} +``` + +### 9.3 텔레그램 메시지 폼 + +``` +🧬 로또 학습 주간 리포트 (1225회차) + +이번주 시도: 6일 × 5세트 = 30번 + +🏆 Winner: 목요일 (W_4) + W = [freq 0.18, finger 0.32, gap 0.20, cooccur 0.22, divers 0.08] + 최고 적중: 4개 일치 (1세트) + 평균 점수: 0.42 (vs 다른 요일 0.18~0.30) + +📊 다음주 base 변경: + freq 0.20 → 0.18 (-) + finger 0.20 → 0.32 (+) + gap 0.20 → 0.20 (=) + cooccur 0.20 → 0.22 (+) + divers 0.20 → 0.08 (--) + reason: winner_4plus (4개 이상 일치 → base 교체) + +[웹에서 차트 보기] (/lotto/evolver) +``` + +## 10. v1 시그널과의 연동 (자동 cascade) + +별도 코드 추가 없음. 활성 W가 `analyzer.score_combination`에 반영되면: +1. 매 4시간 시뮬 cron이 새 W로 best_picks 갱신 +2. score 분포 자체가 변하므로 v1의 `sim_consensus_score`가 자동으로 새 분포 평가 +3. W 변경 직후 outlier 패턴이 나오면 자연스럽게 sim_signal urgent fire + +→ 사용자는 두 종류 텔레그램 받음: +- **🧬 토 22:15 weekly evolution report** (정해진 리듬) +- **🚨 평시 v1 urgent / 📊 v1 digest** (시그널 기반) + +## 11. 구현 Phase + +| Phase | 범위 | 검증 | +|---|---|---| +| 1 | DB 마이그레이션 + `weight_evolver.py` (순수 함수: generate/evaluate + 점수 함수) + 단위 테스트 | pytest로 perturbation·Dirichlet·점수·base 갱신 룰 검증 | +| 2 | analyzer.score_combination 시그니처 확장 + active weight 캐시 | 기존 시뮬 cron이 새 시그니처로 정상 동작 (regression X) | +| 3 | cron 3종 등록 + API 5종 | 수동 트리거로 generate→apply→evaluate 전체 흐름 확인 | +| 4 | agent-office 통합 (cron + 텔레그램 폼 + 테스트) | 토요일 22:15 자동 발송 확인 | + +각 Phase 끝 commit + 자동 배포. + +## 12. 비기능 요구 + +- **백워드 호환**: `analyzer.score_combination` 기본값 None → 기존 호출 그대로 작동 +- **장애 격리**: 가중치 적용 실패 시 균등 합산 폴백, evaluate 실패해도 다음 주 base는 직전 값 유지 +- **테스트**: + - `weight_evolver` 순수 함수 (clamp, normalize, perturbation, base update rule) — 단위 테스트 + - `analyzer.score_combination(weights=...)` — 가중 합산 정확성 테스트 + - `evaluate_weekly` mock 추첨번호 시나리오 — base 갱신 분기 3가지 (winner_4plus / ema_blend / unchanged) +- **관측**: `weight_base_history` 테이블로 모든 base 변경 추적 가능 (rollback도 가능) + +## 13. 비목표 (Out of scope) + +- 메타 전략(combined/simulation/heatmap/manual/custom) 가중치 학습 — strategy_evolver 영역, v3 후속 +- 6일 trials의 day-transition에서 이전 W로 계산된 best_picks를 새 W로 재계산하는 처리 — 다음 시뮬 cron에서 자동 덮어씀 +- Multi-objective 학습 (적중 + 분포 균등 등 복합 점수) +- 자동 구매 (purchase_history 자동 채움) +- 프론트 `/lotto/evolver` UI — v2 백엔드 완성 후 별도 PR (web-ui repo) + +## 14. v3 후속 검토 + +- Multi-armed bandit (UCB1) — 탐험·활용 균형 더 정교 +- 메타 전략 가중치도 함께 학습 (2-layer Bayesian Optimization) +- 가중치 공간을 RL agent로 학습 (policy gradient) +- 자동 구매 후보 픽 (winner W로 1주 N장 자동 발주, 사람 승인 후)