gahusb
ebdfcd758b
확신의 신호 파이프라인 V2. 4 서비스 분담: - stock-lab: 가치 발굴 (8 노드 + ATR) - web-ai (Windows GPU): 시점 분석 (LSTM + KIS 분봉/NXT + 분봉 모멘텀) - agent-office: Claude 2차 검증 + 이중 텔레그램 (본인 풀 / 아내 간소화) - web-ui: 캔버스 settings 편집 6 핵심 결정: pull 채널, KIS 직접, Claude context augmentation, 매수+매도, 양쪽 메시지 단일 콜 생성, 시간대별 폴링. Phase 1-7 분해 (총 10-12주), backlog, 위험 매트릭스, NOT 범위 명시. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
389 lines
16 KiB
Markdown
389 lines
16 KiB
Markdown
# Confidence Signal Pipeline V2 — Architecture & Contract (Phase 0)
|
||
|
||
**작성일**: 2026-05-15
|
||
**작성자**: gahusb
|
||
**상태**: Approved for implementation (Phase 0 = architecture decisions, 코드 변경 없음)
|
||
**선행 컨텍스트**:
|
||
- adversarial review (2026-05-13) — 신호 검증 인프라 필요성
|
||
- Stock Screener V1 (post-close 16:30 Top-N) — 가치 발굴 완성
|
||
- AI News Phase 1 (`articles` source, weight=0 검증 대기) — sentiment 신호
|
||
- web-ai (Windows GPU, RTX 5070 Ti) — LSTM + KIS API + Telegram Bot 기존 자산
|
||
|
||
---
|
||
|
||
## 1. 비전
|
||
|
||
**"주식을 쉽게 잘하기"** — 다층 신뢰도 시스템으로 사용자 + 아내 모두에게 확신 있는 매매 신호 전달.
|
||
|
||
V1 screener는 종가 기반 일별 Top-N 만 산출. V2는:
|
||
- **가치 발굴 (stock-lab 종가 기반)** ×
|
||
- **시점 분석 (web-ai 장중 LSTM + 분봉)** ×
|
||
- **2차 검증 (agent-office Claude)** ×
|
||
- **이중 텔레그램 (본인 = 기술 풀 / 아내 = 간소화)**
|
||
= **확신의 신호**
|
||
|
||
---
|
||
|
||
## 2. Phase 0 산출물
|
||
|
||
**본 spec 1 문서**. 코드 변경 0. 후속 Phase 1-7 의 모든 구현이 본 spec 의 결정을 따른다.
|
||
|
||
핵심 결정 6개:
|
||
1. 데이터 채널 — `web-ai pull from stock-lab` (web-ai 가 polling)
|
||
2. 데이터 소스 — KIS API 직접 (web-ai) + stock-lab API (settings/screener/portfolio)
|
||
3. Claude 2차 검증 — context augmentation (메시지 직접 작성 + 양방향 게이트)
|
||
4. 트리거 — 매수 (screener Top-20) + 매도 (portfolio 보유). 관심종목은 백로그
|
||
5. 이중 텔레그램 — 본인 풀버전 + 아내 간소화. Claude 가 단일 콜에서 양쪽 생성
|
||
6. 운영 — 시간대별 폴링 주기 (장전 5분 / 장중 1분 / 장후 5분 / 야간 1회)
|
||
|
||
---
|
||
|
||
## 3. 시스템 아키텍처
|
||
|
||
```
|
||
┌─────────────────────────────────────┐ ┌──────────────────────────────────┐
|
||
│ NAS (Synology Docker) │ │ Windows PC (RTX 5070 Ti) │
|
||
│ │ │ │
|
||
│ ┌────────────────────────────────┐ │ │ ┌─────────────────────────────┐ │
|
||
│ │ stock-lab :18500 │ │ │ │ web-ai :8001 │ │
|
||
│ │ • /screener/settings │◄─┼──────┼─►│ ① Pull Worker │ │
|
||
│ │ • /screener/run │ │ HTTP │ │ (시간대별 폴링) │ │
|
||
│ │ • /portfolio │ │ pull │ │ │ │
|
||
│ │ • /news-sentiment (옵션) │ │ │ │ ② KIS Client │ │
|
||
│ └────────────────────────────────┘ │ │ │ (WebSocket 분봉/호가) │ │
|
||
│ │ │ │ │ │
|
||
│ ┌────────────────────────────────┐ │ │ │ ③ LSTM Predictor │ │
|
||
│ │ agent-office :18900 │◄─┼──────┼──┤ (GPU, 60일 → 1일 예측) │ │
|
||
│ │ • /signal (Claude 2차 검증) │ │ HTTP │ │ │ │
|
||
│ │ • Telegram dispatcher (이중) │ │ push │ │ ④ Timing Analyzer │ │
|
||
│ └─────────┬──────────────────────┘ │ trig │ │ (분봉 모멘텀) │ │
|
||
│ │ │ │ │ │ │
|
||
└────────────┼──────────────────────────┘ │ │ ⑤ Signal Generator │ │
|
||
│ │ │ (매수/매도 룰) │ │
|
||
▼ │ │ │ │
|
||
┌─────────────────┐ │ │ ⑥ Rate Limiter │ │
|
||
│ Telegram │ │ │ (24h 중복 차단) │ │
|
||
│ - 본인 (full) │ │ └─────────────┬───────────────┘ │
|
||
│ - 아내 (lite) │ │ │
|
||
└─────────────────┘ └───────────────────────────────────┘
|
||
```
|
||
|
||
**책임 분리**:
|
||
- **stock-lab**: 가치 발굴 (8 노드 + 위생 게이트 + ATR), 사용자 설정 저장, portfolio 단일 진실원
|
||
- **web-ai**: 시점 분석 (LSTM + 분봉), 시그널 생성, rate limit
|
||
- **agent-office**: 신호 2차 검증, 메시지 작성, 텔레그램 라우팅
|
||
- **web-ui**: stock-lab settings 편집 (캔버스 UI). 신호 수신/표시는 V2 NOT.
|
||
|
||
---
|
||
|
||
## 4. 데이터 소스 분담
|
||
|
||
| 데이터 | 출처 | 갱신 주기 | 저장소 |
|
||
|--------|------|----------|-------|
|
||
| KRX 일봉 60일 (LSTM 학습) | KIS API (web-ai 직접) | 시작 시 + 종가 후 갱신 | web-ai 로컬 |
|
||
| 정규장 분봉/실시간 호가 | KIS API WebSocket (web-ai 직접) | 실시간 | web-ai 메모리 |
|
||
| NXT 가격 스냅샷 (장전/장후) | KIS API + 네이버 모바일 백업 | 30초~1분 폴링 | web-ai 로컬 |
|
||
| screener settings (가중치) | stock-lab API (web-ai pull) | 1-5분 | NAS `stock.db` |
|
||
| screener 점수 (Top-20) | stock-lab `/run` 호출 결과 | 1-5분 | NAS (preview 모드, 미저장) |
|
||
| portfolio (보유 종목 + 평단) | stock-lab API (web-ai pull) | 1-5분 | NAS `stock.db` |
|
||
| 외인/기관 수급 | stock-lab (네이버 frgn) | 종가 후 16:30 | NAS `stock.db` |
|
||
| AI 뉴스 sentiment | stock-lab (articles 기반 Claude) | 평일 08:00 | NAS `stock.db` |
|
||
| 사용자 텔레그램 chat IDs | agent-office 환경변수 | 정적 | docker-compose env |
|
||
|
||
**원칙**:
|
||
- web-ai는 NAS DB 직접 접근 안 함 — 모든 데이터는 stock-lab API 경유
|
||
- KIS API 데이터는 web-ai 로컬에만 — NAS push 안 함 (실시간성 + 용량)
|
||
- 본인+아내 chat ID 는 agent-office 단독 보관 — web-ai 는 ticker/action 만 push
|
||
|
||
---
|
||
|
||
## 5. API 계약
|
||
|
||
### 5.1 stock-lab → web-ai (pull 응답)
|
||
|
||
**기존 endpoint (변경 없음)**:
|
||
- `GET /api/stock/screener/settings` — 현재 가중치/임계값
|
||
- `POST /api/stock/screener/run {mode:"preview"}` — 8 노드 점수 + Top-N (DB 미저장)
|
||
- `GET /api/portfolio` — 보유 종목 리스트
|
||
|
||
**신규 endpoint (Phase 1)**:
|
||
- `GET /api/stock/screener/news-sentiment?days=1` — 종목별 sentiment 점수 (옵션, Phase 1 에 추가)
|
||
|
||
### 5.2 web-ai → agent-office (push)
|
||
|
||
**신규 endpoint** (Phase 5):
|
||
```
|
||
POST /api/agent-office/signal
|
||
Content-Type: application/json
|
||
```
|
||
|
||
Request body:
|
||
```json
|
||
{
|
||
"ticker": "005930",
|
||
"name": "삼성전자",
|
||
"action": "buy" | "sell",
|
||
"confidence_webai": 0.82,
|
||
"current_price": 78500,
|
||
"avg_price": 75000, // sell 시에만
|
||
"pnl_pct": 0.047, // sell 시에만
|
||
"context": {
|
||
"lstm_pred_1d": 0.023,
|
||
"lstm_pred_conf": 0.82,
|
||
"screener_rank": 3,
|
||
"screener_scores": {"foreign_buy": 88, "volume_surge": 75, "momentum": 60, ...},
|
||
"minute_momentum": "strong_up" | "weak_up" | "neutral" | "weak_down" | "strong_down",
|
||
"kospi_change": 0.004,
|
||
"news_sentiment": 6.2,
|
||
"news_top": ["HBM 양산 가시화", "1분기 어닝 서프라이즈"]
|
||
}
|
||
}
|
||
```
|
||
|
||
Response (agent-office → web-ai):
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"decision": "send" | "hold",
|
||
"final_confidence": 0.745,
|
||
"telegram_self_sent": true,
|
||
"telegram_wife_sent": true
|
||
}
|
||
```
|
||
|
||
### 5.3 Claude 응답 (agent-office 내부)
|
||
|
||
agent-office 가 Claude 에게 보내는 prompt 의 응답 schema:
|
||
```json
|
||
{
|
||
"decision": "send" | "hold",
|
||
"confidence_claude": 0.91,
|
||
"reason": "외인+거래량+호재 일관성 강함",
|
||
"warnings": ["KOSPI 약세 가능성"],
|
||
"message_self": "🔔 매수 신호: 삼성전자 (005930)\n💡 신뢰도 ...",
|
||
"message_wife": "📈 추천: 삼성전자 매수 검토\n사유: ..."
|
||
}
|
||
```
|
||
|
||
`final_confidence = confidence_webai × confidence_claude`. 임계값 (default 0.7) 미만 또는 `decision="hold"` 면 silent (텔레그램 발송 안 함).
|
||
|
||
---
|
||
|
||
## 6. 시그널 룰
|
||
|
||
### 6.1 매수 신호 (screener Top-20 종목 대상)
|
||
|
||
조건 (전부 충족):
|
||
1. LSTM 1-day 예측 > 0% 그리고 LSTM conf > 0.7
|
||
2. 분봉 모멘텀 = `strong_up`:
|
||
- 5분봉 5개 연속 양봉
|
||
- 거래량 > 평균 1.5배
|
||
3. KIS 호가 매수세 ≥ 60%
|
||
|
||
종합 confidence:
|
||
```
|
||
confidence_webai = LSTM_conf × 0.5 + minute_score × 0.3 + screener_norm × 0.2
|
||
```
|
||
- `LSTM_conf` ∈ [0, 1]
|
||
- `minute_score` ∈ [0, 1] (5분봉 강도 + 거래량 multiplier 정규화)
|
||
- `screener_norm` = 1 - (rank - 1) / 20 (rank 1 = 1.0, rank 20 = 0.05)
|
||
|
||
**임계값**: `confidence_webai > 0.7` → agent-office 전송. 아니면 silent.
|
||
|
||
### 6.2 매도 신호 (portfolio 보유 종목 대상)
|
||
|
||
**손절선** (사용자 조정 가능, default -7%):
|
||
- `pnl_pct < -0.07` 시 즉시 매도 시그널 (LSTM/분봉 무관)
|
||
- 메시지: "손절선 도달, 매도 검토"
|
||
|
||
**익절선** (default +15%):
|
||
- `pnl_pct > 0.15` 시 검토 알림 (강제 매도 아님)
|
||
- 메시지: "익절선 도달, 부분 매도 또는 추세 추종 검토"
|
||
|
||
**이상 신호** (보유 중 급격한 약세):
|
||
- LSTM 1-day 예측 < -1% + LSTM conf > 0.7
|
||
- 분봉 모멘텀 = `strong_down`
|
||
- KIS 호가 매도세 ≥ 60%
|
||
- `confidence_webai > 0.7` 동일 임계값으로 전송
|
||
|
||
### 6.3 Rate limit
|
||
|
||
- **같은 종목 + 같은 action**: 24h 내 재알림 금지
|
||
- **장 마감 후 재실행**: 손절선/익절선 알림은 1일 1회 maximum
|
||
- Rate limit state: web-ai 로컬 SQLite 또는 메모리 dict (재기동 시 reset = 운영상 허용)
|
||
|
||
---
|
||
|
||
## 7. 텔레그램 메시지 형식
|
||
|
||
### 7.1 본인 (기술 풀)
|
||
|
||
```
|
||
🔔 매수 신호: 삼성전자 (005930)
|
||
💡 신뢰도 87/100 (web-ai 82 × Claude 91)
|
||
|
||
📊 분석 근거:
|
||
• LSTM 예측: 다음날 +2.3% (conf 0.82)
|
||
• Screener Top-3: 외인+거래량 강세
|
||
• AI 뉴스: +6.2 (HBM 양산 가시화)
|
||
• 분봉 모멘텀: 강세 (5분봉 5연속 양봉)
|
||
• KOSPI: +0.4% (약강세)
|
||
|
||
⚠️ 주의:
|
||
• 코스피 약세 구간 진입 가능성
|
||
• 분할 매수 권고
|
||
|
||
현재가: 78,500원
|
||
```
|
||
|
||
### 7.2 아내 (간소화)
|
||
|
||
```
|
||
📈 추천: 삼성전자 매수 검토
|
||
사유: 외국인 매수 강세 + 호재 뉴스
|
||
추천 강도: ★★★★☆ (높음)
|
||
현재가: 78,500원
|
||
```
|
||
|
||
추천 강도 표시: `final_confidence` 기준
|
||
- ★★★★★ (0.85+)
|
||
- ★★★★☆ (0.7-0.85)
|
||
- ★★★☆☆ (0.55-0.7) — 텔레그램 발송은 0.7 임계값이라 도달 안 함
|
||
|
||
### 7.3 매도 메시지 (본인/아내 양쪽)
|
||
|
||
본인:
|
||
```
|
||
🚨 매도 신호: SK하이닉스 (000660)
|
||
💡 신뢰도 78/100
|
||
|
||
📊 사유:
|
||
• 평단 대비 -7.2% (손절선 도달)
|
||
• LSTM 다음날 -1.5% 예측 (conf 0.75)
|
||
• 분봉 강한 매도세
|
||
|
||
매도 검토 권고. 평단 152,000원 → 현재 141,100원
|
||
```
|
||
|
||
아내:
|
||
```
|
||
⚠️ 매도 검토: SK하이닉스
|
||
사유: 손절선 도달, 약세 신호
|
||
손익: -7.2%
|
||
```
|
||
|
||
---
|
||
|
||
## 8. 운영 모드
|
||
|
||
| 시간대 | web-ai 동작 | 폴링 주기 | LLM 비용 (예상) |
|
||
|--------|------------|----------|----------------|
|
||
| **장전 (07:00-09:00)** | settings + screener pull + NXT 가격 + sentiment | 5분 | 0 (LLM 안 호출) |
|
||
| **장중 (09:00-15:30)** | KIS 분봉 + 호가 + LSTM 추론 + 시그널 생성 | 1분 | 신호 발생 시만 |
|
||
| **장후 (15:30-20:00)** | NXT 가격 + 보유 종목 PnL 추적 + 손절/익절 알림 | 5분 | 신호 발생 시만 |
|
||
| **야간 (20:00-07:00)** | LSTM 모델 일별 재학습 (1회 GPU full pass) | 1회 | 0 |
|
||
|
||
**예상 일 LLM 비용** (agent-office Claude 2차 검증):
|
||
- 일 신호 발생 ~10건 가정 × ₩150/콜 = **~₩1,500/일**, 월 ~₩45,000
|
||
- LSTM 추론은 GPU 로컬, 비용 0
|
||
|
||
---
|
||
|
||
## 9. Phase 1-7 분해
|
||
|
||
```
|
||
Phase 1: stock-lab API 보강 (1주)
|
||
- /api/portfolio 외부 노출 (현재 web-ui 내부용)
|
||
- /api/stock/screener/news-sentiment endpoint 추가
|
||
- /api/stock/screener/run preview 옵션 검증
|
||
|
||
Phase 2: web-ai Pull Worker + Signal API Client (2주)
|
||
- 기존 main_server.py + bot.py 분리
|
||
- stock-lab API client (httpx + retry + cache)
|
||
- 시간대별 폴링 스케줄러
|
||
- rate limit DB
|
||
|
||
Phase 3: KIS WebSocket + 분봉 + LSTM 인프라 (3주)
|
||
- KIS WebSocket client (정규장 분봉 + 호가)
|
||
- NXT 폴링 client (스냅샷 + 네이버 백업)
|
||
- LSTM 학습 파이프라인 야간 재학습
|
||
- 분봉 모멘텀 분류기
|
||
|
||
Phase 4: Signal Generator (1주)
|
||
- 매수 룰 (LSTM + 분봉 + 호가 + screener)
|
||
- 매도 룰 (손절/익절/이상)
|
||
- confidence 계산 + 임계값
|
||
|
||
Phase 5: agent-office /signal endpoint + Claude 검증 + 이중 텔레그램 (1-2주)
|
||
- POST /signal 라우터
|
||
- Claude prompt (system + user + assistant prefill JSON)
|
||
- 본인/아내 dispatcher
|
||
|
||
Phase 6: web-ai 기존 trading bot 정리 (1주)
|
||
- 자체 watchlist_manager 삭제
|
||
- 자체 뉴스 크롤링 (Ollama) 삭제
|
||
- 기존 자동 매매 (KIS 실주문) 비활성화 또는 별도 모드 분리
|
||
|
||
Phase 7: 운영 모니터링 + 4주 IC 검증 (1주 + 4주)
|
||
- 신호 hit-rate 추적 (forward return correlation)
|
||
- false positive rate
|
||
- 임계값 점진 조정
|
||
- Phase 8 (자동 매매) 검토
|
||
```
|
||
|
||
총 10-12주 (개인 페이스). 각 Phase 마다 자체 spec + plan + 검증 사이클.
|
||
|
||
---
|
||
|
||
## 10. Backlog (V2 본 spec NOT)
|
||
|
||
미래 슬라이스로 분리:
|
||
- **관심종목 (watchlist) 모니터링** — Top-N + portfolio 외, 사용자 관심종목의 변동성 spike / 거래량 급증 알람
|
||
- **자동 매매 (KIS 실주문)** — Phase 8 검토. 4주 신호 hit-rate ≥ 60% 후 단계적
|
||
- **DART 공시 통합** — Claude 검증 컨텍스트에 공시 추가
|
||
- **백테스트 화면** — 과거 신호 정확도 시각화
|
||
- **신호 hit-rate 대시보드** — web-ui 신규 페이지
|
||
- **분할 매수/매도 전략 추천** — Phase 7 이후
|
||
- **옵션/선물/해외 주식** — V3 검토
|
||
|
||
---
|
||
|
||
## 11. 위험 및 완화
|
||
|
||
| 위험 | 완화 |
|
||
|------|------|
|
||
| Windows PC 다운 시 신호 zero | stock-lab은 정상. web-ai down 시 헬스체크 → 텔레그램 운영자 알림 |
|
||
| KIS API 장애 | NXT는 네이버 모바일 API 폴백. 분봉은 단기 재시도 + 일정 시간 후 alert |
|
||
| Claude 비용 폭증 | rate limit + 일일 spend cap (예: ₩5,000). 임계값 미만 silent block |
|
||
| False positive 다수 | 4주 IC + Phase 7 모니터링. 임계값 점진 상향 |
|
||
| LSTM drift | 야간 재학습 + 주간 ablation 비교 (이전 1주 모델 vs 신규) |
|
||
| 메시지 본인-아내 drift | Claude 단일 콜에서 양쪽 동시 생성 (drift 회피, 같은 reasoning) |
|
||
| 매도 신호 지연 | 분봉 1분 폴링. 손절선은 보유 종목 단순 비교 (LSTM 무관 즉시 트리거) |
|
||
| stock-lab API 응답 지연 | web-ai 측 timeout 10s + 캐시 (마지막 성공 응답 ttl 5분) |
|
||
| 종목 갱신 race condition | screener Top-20 변동 시 rate limit 키 = (ticker, action, date) |
|
||
|
||
---
|
||
|
||
## 12. 명시적 NOT 범위 (Phase 0)
|
||
|
||
- **자동 매매 (실주문)**: V2 는 신호만. 사용자가 수동 매매. Phase 8 별도 검토
|
||
- **종목 매수 가격/수량 추천**: 사용자 결정. 신호는 "검토 권고" 수준
|
||
- **분할 매수/매도 전략**: Phase 7 이후 별도 슬라이스
|
||
- **옵션/선물/해외 주식**: KRX 정규장 + NXT 한정
|
||
- **관심종목 모니터링**: 백로그 (§10)
|
||
- **신호 hit-rate 시각화 UI**: 백로그
|
||
|
||
---
|
||
|
||
## 13. 완료 조건 (Phase 0 DoD)
|
||
|
||
본 spec 완료 = 다음 조건 모두 충족:
|
||
- [ ] 사용자가 spec 검토 + 승인
|
||
- [ ] git commit (`docs/superpowers/specs/2026-05-15-confidence-signal-pipeline-v2-architecture.md`)
|
||
- [ ] 6 핵심 결정 모두 명시적 (데이터 채널, 데이터 소스, Claude 검증, 트리거, 텔레그램, 운영)
|
||
- [ ] 4개 API 계약 (3 stock-lab pull + 1 agent-office push) 모두 schema 정의
|
||
- [ ] Phase 1-7 분해 + 각 Phase 추정 기간
|
||
- [ ] backlog + 위험/완화 매트릭스 + NOT 범위
|
||
|
||
Phase 0 자체에는 코드 변경 0. 본 spec 승인 후 Phase 1 brainstorming 으로 자연스럽게 이어진다.
|