ai-trade/CLAUDE.md

web-ai — Workspace 가이드

Windows AI 머신 (AMD 9800X3D + RTX 5070 Ti 16GB) 의 두 신호 파이프라인. Confidence Signal Pipeline V2 의 Windows-side 구현체 (NAS stock 백엔드와 HTTP 연동).

상위 워크스페이스 컨텍스트는 ../CLAUDE.md 참조.

---

디렉토리 구조

경로	역할	포트	상태
signal_v1/	레거시 자동매매 시스템 (LSTM 7-features + Gemini Flash + Telegram Bot + KIS 자동주문)	:8000	운영 중. V2 Phase 6 에서 deprecation 예정
signal_v2/	Confidence Signal Pipeline V2 (Chronos-bolt + 분봉 모멘텀 + KIS WebSocket + 신호 생성)	:8001	Phase 4 완료 (2026-05-17), Phase 5 대기
.env	V1 + V2 환경변수 공유	—	KIS_REAL_*, TELEGRAM_*, STOCK_API_URL, WEBAI_API_KEY, LOG_LEVEL
start.bat	V1 진입점	—	signal_v1/main_server.py 실행
signal_v2/start.bat	V2 진입점	—	signal_v2/main.py uvicorn 실행
requirements.txt	공용 의존성	—	torch, chronos-forecasting, fastapi, httpx, websockets 등

.venv 는 구조적으로 깨짐: pyvenv.cfg 가 한글 사용자 경로(C:\Users\박재오\...) 를 포함하여 콘솔 코드페이지가 roundtrip 못함. 테스트는 시스템 Python 으로 실행: C:\Users\jaeoh\AppData\Local\Programs\Python\Python312\python.exe -m pytest signal_v2/tests -q.

---

서버 시작 방식

V1 단독 (운영 기본)

cd C:\Users\jaeoh\Desktop\workspace\web-ai
.\start.bat

기대 로그: [Bot] Cycle Start ..., [AI] 005930: NN epochs ..., [Ensemble] tech=... news=... lstm=..., Score: 0.xx [HOLD]

V2 단독 (smoke/검증)

cd C:\Users\jaeoh\Desktop\workspace\web-ai\signal_v2
.\start.bat

기대 로그: Uvicorn running on http://0.0.0.0:8001, poll_loop started, [KIS] minute bars ... OK, [Chronos] predicted N tickers, signal emit XXXXXX buy conf=0.xxx.

휴장일/장 외 시간엔 poll_loop 만 idle. Application startup complete 만 보이면 정상.

V1 + V2 동시 실행 — 권장 안 함

KIS app_key 초당 2회 한도 (EGW00201) 충돌. V1 cycle + V2 분봉 cron 이 같은 KIS app_key 로 동시 호출하면 rate limit. 채택 해결책: V2 임시 종료 (Phase 3a 결정), Phase 6 V1 deprecation 시 자연 해소. 별도 app_key 발급은 옵션 B.

---

Phase 진행 상태 (Confidence Signal Pipeline V2)

Phase	내용	상태
0	Architecture & contract spec	✅ Chronos-2 + Qwen3 14B 채택
1	stock 백엔드 WebAI API 보강 (NAS)	✅ 102/102 tests, 운영 배포
1.5	V1 → signal_v1/ rename	✅ V1 정상 기동
2	signal_v2 pull worker + signal API client + scheduler	✅ 19/19 tests, :8001 기동
3a	KIS REST 분봉 + WebSocket 호가 + NXT 스케줄	✅ 33/33 tests
3b	Chronos-bolt-base 추론 + 5분봉 모멘텀 분류기	✅ 45/45 tests, 실 KIS+Chronos chain 검증
4	Signal Generator (매수/매도 룰) + pull_worker 통합 + 로깅	✅ 2026-05-17 완료, 56/56 tests, push 완료
5	agent-office /signal + Ollama Qwen3 14B + 이중 텔레그램	⏳ 2주 예상
6	signal_v1 deprecation	⏳ 1주
7	운영 모니터링 + 4주 IC 검증	⏳ 1주 + 4주

상세 spec/plan: ../web-ui/docs/superpowers/specs/ 및 ../web-ui/docs/superpowers/plans/ (web-ui repo 안에 보관됨 — V2 자체 코드와 분리 보관).

---

signal_v2 디렉토리 내부

파일	역할
main.py	FastAPI app + lifespan (StockClient + KISClient + KISWebSocket + ChronosPredictor + SignalDedup 초기화). poll_loop task 생성
config.py	Settings dataclass — 환경변수 로드. Phase 4 추가 6 필드: stop_loss_pct, take_profit_pct, chronos_spread_threshold, asking_bid_ratio_threshold, confidence_threshold, min_momentum_for_buy
state.py	PollState (process-wide singleton) — portfolio, screener_preview, news_sentiment, chronos_predictions, minute_bars, asking_price, signals (Phase 4)
stock_client.py	NAS stock 백엔드 pull (X-WebAI-Key + 메모리 cache 60s/300s/60s + retry)
kis_client.py	KIS REST 분봉/호가 — V1 토큰 read-only 공유 (mtime cache) + 초당 2회 throttle + 지수 backoff
kis_websocket.py	KIS WebSocket H0STASP0 호가 + approval_key + 재연결 (1→2→4→max 30s)
chronos_predictor.py	amazon/chronos-bolt-base zero-shot quantile (FP32 강제 — FP16 overflow 회피)
minute_momentum.py	5분봉 → strong_up/weak_up/neutral/weak_down/strong_down 5단계 분류
signal_generator.py	Phase 4 — 매수/매도 룰 엔진. generate_signals(state, dedup, settings) 진입. sell-first → buy 순서. 신호 emit/skip INFO/DEBUG 로그
pull_worker.py	asyncio cron — 장전 5분 / 장중 1분 / 장후 5분 / NXT / dead zone skip. cycle 끝에 generate_signals 호출
scheduler.py	polling window 판정 (KST 캘린더 + 휴장일)
rate_limit.py	초당 N회 token bucket
dedup.py	SignalDedup SQLite WAL — (ticker, action) PK 24h
tests/	56 tests (pytest + respx HTTP mock + monkeypatch)
data/	dedup.db (SQLite WAL) + holidays.json (NAS stock 에서 manual copy)
start.bat	V2 진입

---

신호 룰 요약 (Phase 4)

매수 (screener Top-N + portfolio, sell 신호 받은 종목은 skip)

모두 충족:

1. chronos.median > 0
2. chronos.q90 - chronos.q10 < 0.6 (absolute spread — 2026-05-17 spec amend, 기존 relative formula 가 zero-shot median≈0 빈번에서 모든 신호 거부)
3. minute_momentum == strong_up (env 로 조정 가능)
4. asking_price.bid_ratio >= 0.6

종합 confidence = chronos_conf * 0.5 + minute_score * 0.3 + screener_norm * 0.2. > 0.7 시 emit.

매도 (portfolio only, 우선순위 stop_loss → anomaly → take_profit)

• stop_loss: pnl_pct < -7% 즉시 (confidence=1.0)
• anomaly: chronos.median < -1% + strong_down + bid_ratio < 0.4 + 종합 conf > 0.7
• take_profit: pnl_pct > 15% 검토 (confidence=0.6)

---

알려진 함정 / Phase 7 백로그

1. KIS rate limit (EGW00201) — V1+V2 동시 실행 시 충돌. Phase 6 자연 해소
2. .venv 한글 경로 깨짐 — 시스템 Python 사용
3. Chronos FP16 overflow — 한국 주가 5만+ 시 inf. FP32 강제 (chronos_predictor.py:39-41)
4. predict_quantiles positional inputs — ChronosBolt API 새 변경. try/except TypeError fallback 처리됨
5. state.signals consumer-drain protocol 미정의 — Phase 5 prereq. dict 무한 누적 위험 (실제로는 bounded by unique ticker count)
6. integration test 가 poll_loop 실제 호출 안 함 — test_pull_worker.py:test_poll_loop_calls_generate_signals_after_cycle 가 generate_signals 직접 호출. Phase 7 hardening 시 mock-iteration 으로 강화
7. KIS WebSocket URL ws://ops.koreainvestment.com:21000/31000 — 첫 운영 시 실제 KIS API docs 와 대조 필요
8. _parse_asking_price 필드 인덱스 — 마지막 2 필드 가정. 실 운영 raw 메시지 캡처 후 매핑 검증 필요
9. holidays.json 자동 동기화 부재 — NAS stock 의 holidays.json 을 수동 copy
10. schema rename — Phase 0 §5.2 의 lstm_pred_*, news_top[] 는 chronos_pred_*, news_reason(string) 으로 변경됨. Phase 5 prompt 작성 시 반영
11. 6개 env 필드가 .env 에 미기재 — 기본값으로 동작 가능하나 discoverability 위해 .env.example 또는 commented block 추가 권장

---

다음 단계 (Phase 5 진입 시 brainstorming 주제)

• state.signals consumer 패턴: pop vs leave + Phase 5 자체 dedup
• agent-office 의 /signal endpoint 설계 — POST 페이로드 schema
• Ollama Qwen3 14B Q4 로컬 호출 — 타임아웃, retry, VRAM 공존 (Chronos + Qwen3 동시 메모리 9.3GB / 15.5GB 가용)
• 이중 텔레그램 (본인 풀 / 아내 lite) — context augmentation 단일 호출에서 양쪽 메시지 생성
• LLM 비용: ₩0 목표 유지 (로컬)

---

양쪽 디렉토리 (web-ui ↔ web-ai) 작업 시 주의

• 코드: signal_v2 는 web-ai/, spec/plan/메모리는 web-ui/
• 커밋: web-ai 와 web-ui 는 별도 Gitea 저장소. 각각 경로에서만 git add/commit/push
• 메모리: Claude Code 의 auto-memory 는 디렉토리별 격리. 핵심 reference 는 양쪽에 미러됨 (./memory-mirror/ 또는 ~/.claude/projects/C--Users-jaeoh-Desktop-workspace-web-ai/memory/)
• spec amendment 발생 시: 코드는 web-ai 에 commit, spec 갱신은 web-ui/docs/superpowers/specs/ 에 commit (Phase 4 spread formula 변경 사례 = web-ui commit 534ded5)

자세한 V1 가이드는 signal_v1/CLAUDE.md 참조 (있다면).