@@ -0,0 +1,400 @@
# Confidence Signal Pipeline V2 — Phase 4: Signal Generator Design
**작성일 ** : 2026-05-17
**작성자 ** : gahusb
**상태 ** : Approved for implementation
**선행 spec ** :
- Phase 0 architecture (`2026-05-15-confidence-signal-pipeline-v2-architecture.md` )
- Phase 1 stock WebAI API (`2026-05-15-signal-v2-phase1-webai-api.md` )
- Phase 2 web-ai pull worker (`2026-05-16-signal-v2-phase2-web-ai-pull-worker.md` )
- Phase 3a KIS data collection (`2026-05-16-signal-v2-phase3a-kis-data-collection.md` )
- Phase 3b Chronos-2 + momentum (`2026-05-16-signal-v2-phase3b-chronos-momentum.md` )
**브레인스토밍 결정 6개 ** :
- scope = A (신호 생성만, Phase 5 가 발송)
- trigger = A (매 분봉 cycle 후 일괄 평가)
- minute_score = A (Linear 5-level 1.0/0.7/0.5/0.3/0.0)
- 임계값 = A+ (6 env 외부화)
- state.signals schema = A (Phase 0 spec §5.2 그대로)
- 테스트 = A (9 단위 + 1 integration = 10 신규)
---
## 1. 목표
Phase 2/3a/3b 의 모든 산출을 종합해 Phase 0 spec §6.1/§6.2/§6.3 의 매수/매도/dedup 룰 적용. 임계값 통과한 신호를 `state.signals` 에 저장 + `SignalDedup` 으로 24h 중복 차단.
**Why ** : Phase 5 (agent-office) 의 입력 계약 완성. signal_v2 가 자체적으로 매수/매도 신호 생성 → Phase 5 가 발송.
---
## 2. 범위
### 포함 (6 항목)
- ① `signal_generator.py` 신규 — `generate_signals(state, dedup, settings) -> None` (state mutating)
- ② `config.py` 확장 — 6 env (`STOP_LOSS_PCT` , `TAKE_PROFIT_PCT` , `CHRONOS_SPREAD_THRESHOLD` , `ASKING_BID_RATIO_THRESHOLD` , `CONFIDENCE_THRESHOLD` , `MIN_MOMENTUM_FOR_BUY` )
- ③ `state.py` 확장 — `signals: dict[str, dict]` (Phase 5 input)
- ④ `pull_worker.py` 확장 — 매 cycle 후 `generate_signals` 호출 + signature 확장 (dedup + settings)
- ⑤ `main.py` 의 lifespan poll_task 호출 시 dedup/settings 전달
- ⑥ 테스트 9 단위 + 1 integration = **10 신규 ** (45 → 55)
### Phase 4 산출 (Phase 5 input)
`state.signals[ticker]` — Phase 0 spec §5.2 schema:
``` python
{
" ticker " : str , " name " : str ,
" action " : " buy " | " sell " ,
" confidence_webai " : float ,
" current_price " : int ,
" avg_price " : int | None , # sell 시만
" pnl_pct " : float | None ,
" context " : {
" chronos_pred_1d " : float ( median ) ,
" chronos_pred_conf " : float ,
" chronos_q10 " : float , " chronos_q90 " : float ,
" screener_rank " : int | None ,
" screener_scores " : dict | None ,
" minute_momentum " : str ,
" asking_bid_ratio " : float ,
" news_sentiment " : float | None ,
" news_reason " : str | None ,
} ,
" as_of " : str ( ISO ) ,
}
```
### 범위 외 (NOT)
- agent-office `/signal` HTTP POST (Phase 5)
- Qwen3 검증 + 이중 텔레그램 (Phase 5)
- 호가 변경 시 즉시 매도 trigger (Phase 7 backlog)
- 자동 매매 (Phase 8 backlog)
- ML 기반 룰 변종 (Phase 7 백테스트 후)
- `kospi_change` , `news_top` 컨텍스트 (Phase 7 backlog)
- 외부 API 호출 — Phase 4 는 state 만 사용 (pure function)
---
## 3. 파일 구조 + 변경 매트릭스
| 파일 | 작업 | 라인 |
|------|------|------|
| `signal_v2/signal_generator.py` | 신규 (generate_signals + 5 helpers) | ~250 |
| `signal_v2/config.py` | Settings 6 field 추가 | +15 |
| `signal_v2/state.py` | PollState `signals` 필드 | +2 |
| `signal_v2/pull_worker.py` | poll_loop signature + 매 cycle 호출 | +10 |
| `signal_v2/main.py` | lifespan poll_task 인자 추가 | +3 |
| `signal_v2/tests/test_signal_generator.py` | 9 단위 신규 | ~350 |
| `signal_v2/tests/test_pull_worker.py` | 1 integration 추가 | +50 |
**합계 ** : 7 파일 변경, 10 신규 테스트.
### 외부 의존성 신규
**없음 ** . signal_generator 는 순수 함수, 외부 라이브러리 0.
### 6 신규 env
| env | 기본값 | 의미 |
|-----|--------|------|
| `STOP_LOSS_PCT` | `-0.07` | 손절선 비율. `pnl_pct < 이 값` → 즉시 매도 |
| `TAKE_PROFIT_PCT` | `0.15` | 익절선 비율. `pnl_pct > 이 값` → 검토 알림 |
| `CHRONOS_SPREAD_THRESHOLD` | `0.6` | `(q90-q10)/max(|median|, 0.001) < 이 값` → 매수 통과 |
| `ASKING_BID_RATIO_THRESHOLD` | `0.6` | `bid_ratio >= 이 값` → 매수 통과 |
| `CONFIDENCE_THRESHOLD` | `0.7` | `confidence_webai > 이 값` → 신호 발생 |
| `MIN_MOMENTUM_FOR_BUY` | `strong_up` | 분봉 모멘텀 카테고리 |
---
## 4. 매수 룰 + Confidence
### 4.1 매수 룰 대상
- screener Top-N (`state.screener_preview.items` )
- portfolio 보유 종목 (추가 매수 검토, dedup 으로 중복 차단)
### 4.2 Hard gate (모든 조건 충족)
1. `state.chronos_predictions[ticker].median > 0` (다음날 상승)
2. `(q90 - q10) / max(|median|, 0.001) < settings.chronos_spread_threshold`
3. `state.minute_momentum[ticker] == settings.min_momentum_for_buy` (기본 strong_up)
4. `state.asking_price[ticker].bid_ratio >= settings.asking_bid_ratio_threshold`
### 4.3 Soft confidence (Phase 0 spec §6.1)
``` python
chronos_conf = state . chronos_predictions [ ticker ] [ " conf " ]
minute_score = MOMENTUM_SCORES [ state . minute_momentum [ ticker ] ]
# MOMENTUM_SCORES = {"strong_up": 1.0, "weak_up": 0.7, "neutral": 0.5,
# "weak_down": 0.3, "strong_down": 0.0}
screener_norm = 1 - ( rank - 1 ) / 20 if rank is not None else 0.0
confidence_webai = chronos_conf * 0.5 + minute_score * 0.3 + screener_norm * 0.2
```
### 4.4 임계값
`confidence_webai > settings.confidence_threshold` (기본 0.7) → 신호 발생.
### 4.5 누락 처리
- portfolio (Top-N 외) 매수: `screener_rank = None` → `screener_norm = 0` (보수적)
- `chronos_predictions[ticker]` 누락 → silent (Hard gate 위반)
- `asking_price[ticker]` 누락 → silent
---
## 5. 매도 룰 + Dedup
### 5.1 매도 대상
portfolio holdings 만 (`state.portfolio.holdings` ).
### 5.2 매도 룰 (Phase 0 spec §6.2)
* * (a) 손절선 (즉시 trigger)**:
- `pnl_pct < settings.stop_loss_pct` (기본 -0.07)
- 다른 룰 무관 — 즉시 매도
- `confidence_webai = 1.0`
* * (b) 익절선 (검토 알림)**:
- `pnl_pct > settings.take_profit_pct` (기본 0.15)
- "검토 권고" — 강제 매도 X
- `confidence_webai = 0.6`
* * (c) 이상 신호**:
- `chronos_predictions[ticker].median < -0.01`
- `minute_momentum[ticker] == "strong_down"`
- `asking_price[ticker].bid_ratio < (1 - settings.asking_bid_ratio_threshold)` (매도세 ≥ 60%)
- confidence_webai = chronos_conf × 0.5 + inverted_minute × 0.3 + 1.0 × 0.2
- 임계값 > `settings.confidence_threshold`
### 5.3 우선순위 (같은 ticker 다중 trigger 시)
1. **손절 ** (Phase 0 spec §6.2 "즉시") — 다른 룰 우회
2. **이상 신호 **
3. **익절선 **
상위 trigger 시 하위 skip (한 종목당 한 cycle 1 매도 신호).
### 5.4 Dedup (Phase 0 spec §6.3 + Phase 2 SignalDedup)
``` python
if dedup . is_recent ( ticker , action , within_hours = 24 ) :
continue # silent
# 신호 dict 생성
state . signals [ ticker ] = { . . . }
dedup . record ( ticker , action , confidence = confidence_webai )
```
Dedup 키 `(ticker, action)` — 같은 종목의 매수/매도 별도 추적, 충돌 없음.
손절선도 dedup 적용 (Phase 0 spec §6.3 "1일 1회 max").
---
## 6. State 통합 + pull_worker
### 6.1 PollState 확장
``` python
signals : dict [ str , dict ] = field ( default_factory = dict )
```
매 cycle 마다 **덮어쓰기 X ** — 같은 ticker key 재발생 시 갱신, 그 외 유지. dedup 으로 중복 차단되므로 누적 안전. Phase 5 consumer 가 처리 후 본인 측 dedup.
### 6.2 pull_worker 흐름
``` python
async def poll_loop ( client , state , shutdown ,
kis_client = None , chronos = None ,
dedup = None , settings = None ) - > None :
while not shutdown . is_set ( ) :
now = datetime . now ( KST )
if _is_market_day ( now ) and _is_polling_window ( now ) :
# 1. stock + KIS 분봉/호가 (Phase 2 + 3a)
await _run_polling_cycle ( client , state , kis_client = kis_client )
# 2. 분봉 모멘텀 (Phase 3b)
update_minute_momentum_for_all ( state )
# 3. 종가 트리거 시 Chronos (Phase 3b)
if _is_post_close_trigger ( now ) and chronos and kis_client :
await _run_post_close_cycle ( kis_client , chronos , state )
# 4. (신규 Phase 4) 신호 생성
if dedup is not None and settings is not None :
try :
generate_signals ( state , dedup , settings )
except Exception :
logger . exception ( " generate_signals failed " )
. . .
```
### 6.3 main.py lifespan
``` python
_ctx . poll_task = asyncio . create_task (
poll_loop (
_ctx . client , state_mod . state , _ctx . shutdown ,
kis_client = _ctx . kis_client ,
chronos = _ctx . chronos ,
dedup = _ctx . dedup ,
settings = settings ,
)
)
```
---
## 7. signal_generator.py 구조
``` python
def generate_signals ( state : PollState , dedup : SignalDedup , settings : Settings ) - > None :
""" Phase 4 entry point — state mutating. """
_evaluate_buy_signals ( state , dedup , settings )
_evaluate_sell_signals ( state , dedup , settings )
def _evaluate_buy_signals ( state , dedup , settings ) - > None :
""" screener Top-N + portfolio 매수 후보 평가. """
candidates = _buy_candidates ( state ) # screener Top-N + portfolio holdings
for ticker , rank in candidates :
if not _check_buy_hard_gate ( state , ticker , settings ) :
continue
confidence = _compute_buy_confidence ( state , ticker , rank )
if confidence < = settings . confidence_threshold :
continue
if dedup . is_recent ( ticker , " buy " , within_hours = 24 ) :
continue
state . signals [ ticker ] = _build_buy_signal ( state , ticker , rank , confidence )
dedup . record ( ticker , " buy " , confidence = confidence )
def _evaluate_sell_signals ( state , dedup , settings ) - > None :
""" portfolio 보유 종목 매도 평가 — 손절 > 이상 > 익절 우선순위. """
if state . portfolio is None :
return
for holding in state . portfolio . get ( " holdings " , [ ] ) :
ticker = holding [ " ticker " ]
# 우선순위 1: 손절선
sell = _try_stop_loss ( state , holding , settings )
# 우선순위 2: 이상 신호
if sell is None :
sell = _try_anomaly ( state , holding , settings )
# 우선순위 3: 익절선
if sell is None :
sell = _try_take_profit ( state , holding , settings )
if sell is None :
continue
if dedup . is_recent ( ticker , " sell " , within_hours = 24 ) :
continue
state . signals [ ticker ] = sell
dedup . record ( ticker , " sell " , confidence = sell [ " confidence_webai " ] )
```
Helper 함수:
- `_buy_candidates(state) -> list[tuple[ticker, rank | None]]`
- `_check_buy_hard_gate(state, ticker, settings) -> bool`
- `_compute_buy_confidence(state, ticker, rank | None) -> float`
- `_build_buy_signal(state, ticker, rank, confidence) -> dict`
- `_try_stop_loss(state, holding, settings) -> dict | None`
- `_try_anomaly(state, holding, settings) -> dict | None`
- `_try_take_profit(state, holding, settings) -> dict | None`
- `_build_context(state, ticker, rank, ...) -> dict`
---
## 8. 테스트 (10 신규)
### 8.1 `test_signal_generator.py` (9 단위)
| # | 이름 | Setup | 검증 |
|---|------|-------|------|
| 1 | `test_buy_signal_when_all_conditions_pass_and_confidence_high` | chronos +2%, narrow, strong_up, bid_ratio 0.7, rank 1 | state.signals[ticker]["action"]=="buy", confidence > 0.7, dedup.record 호출 |
| 2 | `test_silent_when_chronos_median_negative` | median -1% | state.signals empty |
| 3 | `test_silent_when_distribution_spread_too_wide` | spread 1.0 | empty |
| 4 | `test_silent_when_momentum_not_strong_up` | weak_up | empty |
| 5 | `test_silent_when_bid_ratio_below_threshold` | 0.5 | empty |
| 6 | `test_silent_when_confidence_below_threshold` | rank 20 + median +0.5% (chronos_conf 낮음) → confidence < 0.7 | empty |
| 7 | `test_sell_signal_when_stop_loss_triggered` | pnl_pct -0.08 | "sell" + confidence 1.0 |
| 8 | `test_sell_signal_when_take_profit_triggered` | pnl_pct 0.16 | "sell" + confidence 0.6 |
| 9 | `test_silent_when_dedup_recently_sent` | dedup.is_recent True | empty |
### 8.2 `test_pull_worker.py` (1 integration)
| # | 이름 | 검증 |
|---|------|------|
| 10 | `test_poll_loop_calls_generate_signals_after_cycle` | mock state setup + mock dedup → poll_loop 1 cycle → state.signals 갱신 |
**합계 ** : 9 + 1 = **10 신규 ** . 45 → 55 total.
---
## 9. 위험 / 운영 / DoD
### 9.1 위험 매트릭스
| 위험 | 완화 |
|------|------|
| Phase 0 spec 의 confidence 공식이 실 운영과 안 맞음 | 6 env 외부화 → Phase 7 IC 검증 후 .env 조정 |
| Chronos 누락 (장 시작 첫 cycle) | Hard gate 위반 → silent. 종가 cron 후 매수 신호 가능 |
| Dedup DB 손상 | WAL + busy_timeout. 운영자 manual 복구 (signal_v2.db 삭제) |
| 동시 cycle 에서 같은 종목 buy + sell trigger | dedup PK `(ticker, action)` 별도 추적 — 충돌 없음 |
| portfolio 매수 → screener_norm=0 → 신호 발생 어려움 | 보수적. 다른 component 높아야 신호. 의도된 동작 |
| 손절선 trigger 후 24h 추가 손실 → 다음 알림 차단 | 운영적 허용 (Phase 0 spec §6.3 1일 1회 max) |
| 신호 빈도 너무 적음 | 4주 IC 검증 + 임계값 완화 |
| 신호 빈도 너무 많음 (false positive) | dedup + 임계값 강화. Phase 7 |
| 매도 우선순위 잘못 (손절 > 이상 > 익절) | 테스트 케이스로 검증 + 코드 명시 |
| signals dict 누적 (cycle 사이 stale entry) | dedup 으로 중복 차단되므로 안전. Phase 5 consumer 가 처리 후 본인 측 marker |
### 9.2 운영 영향
| 항목 | 영향 |
|------|------|
| 다운타임 | signal_v2 재기동 ~5초 |
| 사용자 영향 | 없음 (Phase 5 까지 발송 없음) |
| `.env` 갱신 | optional 0-6개 (기본값 충분) |
| V1 영향 | 0 |
| KIS API 부하 | 0 (Phase 4 는 외부 호출 없음) |
### 9.3 Phase 4 완료 조건 (DoD)
- [ ] `signal_v2/signal_generator.py` 신규 (generate_signals + 8 helpers)
- [ ] `signal_v2/config.py` Settings 에 6 field 추가 (default 있음)
- [ ] `signal_v2/state.py` PollState `signals` field
- [ ] `signal_v2/pull_worker.py` poll_loop signature + 매 cycle 호출
- [ ] `signal_v2/main.py` lifespan 의 poll_task 인자 (dedup, settings) 추가
- [ ] 9 단위 + 1 integration 테스트 PASS (총 55)
- [ ] 운영 smoke: signal_v2 시작 → 1 cycle 후 state.signals 빈 dict (운영 시간대 신호 발생 가능 종목 없을 시 정상) 또는 ≥ 1 신호 생성
- [ ] V1 무영향
- [ ] git push
---
## 10. Phase 5 와의 관계
본 Phase 4 완료 후 즉시 **Phase 5 (agent-office /signal + Qwen3 + 이중 텔레그램) ** brainstorming. 의존성:
```
[Phase 4 spec/plan/실행] → [Phase 5 spec/plan/실행]
3-5일 2주
```
Phase 5 의 입력 = 본 spec 의 `state.signals[ticker]` (state polling 또는 HTTP push). Phase 5 작업:
- agent-office `/signal` endpoint 신설 (Phase 0 spec §5.2 schema 수신)
- web-ai → agent-office HTTP client 추가 (signal_v2 측)
- web-ai 의 Ollama Qwen3 14B Q4 설치 + agent-office 의 LLM 검증 호출
- 이중 텔레그램 (본인 풀 / 아내 lite)
---
## 11. Backlog (본 spec NOT)
- 호가 변경 시 즉시 매도 trigger — Phase 7 운영 후 검토
- `kospi_change` 컨텍스트 (KIS 지수 fetch) — Phase 7
- `news_top` 컨텍스트 (news_sentiment.reason 다중 추출) — Phase 7
- 매수/매도 ML 룰 — Phase 7 백테스트 후
- portfolio 매수의 screener_norm fallback (다른 default 값) — IC 검증 후
- 신호 hit-rate 대시보드 — Phase 7
- 분할 매수/매도 전략 — Phase 7 이후
- 자동 매매 (실주문) — Phase 8
- 손절선 dedup 면제 (즉시성 위해) — Phase 7 운영 검증 후