web-page/docs/superpowers/specs/2026-05-17-signal-v2-phase4-signal-generator.md

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:

{
    "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(
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) < settings.chronos_spread_threshold (absolute spread — Phase 3b 실 운영 데이터 기반 변경)
3. state.minute_momentum[ticker] == settings.min_momentum_for_buy (기본 strong_up)
4. state.asking_price[ticker].bid_ratio >= settings.asking_bid_ratio_threshold

Spread formula 결정 노트 (2026-05-17 implementer 변경 채택):

• Phase 0 spec §6.1 의 한국어 "(90-10 분위수) / 50 분위수 < 0.6" 은 relative spread 로 명시되었으나, Phase 3b 실 운영 결과 (Chronos zero-shot prediction 의 median 이 종종 0 가까이) 에서 relative formula 가 거의 모든 신호 거부 → useless.
• 변경: absolute spread (q90 - q10) < 0.6 사용. 0.6 = 60% 변동 예측 — 한국 주식 1-day 변동성 (1-2%) 대비 매우 넓음 (모델 자신 없음 신호).
• 결과: Phase 3b smoke 005930 (median=-0.59%, q10=-8.9%, q90=6.4%, spread=15.3%) → spread 0.153 < 0.6 → hard gate 통과 가능 (다른 조건 충족 시).
• Phase 7 IC 검증 시 임계값 재조정 가능 (env CHRONOS_SPREAD_THRESHOLD).

4.3 Soft confidence (Phase 0 spec §6.1)

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)

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 확장

signals: dict[str, dict] = field(default_factory=dict)

매 cycle 마다 덮어쓰기 X — 같은 ticker key 재발생 시 갱신, 그 외 유지. dedup 으로 중복 차단되므로 누적 안전. Phase 5 consumer 가 처리 후 본인 측 dedup.

6.2 pull_worker 흐름

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

_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 구조

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 운영 검증 후