Initial commit
This commit is contained in:
jsahn
@@ -0,0 +1,94 @@
|
||||
# US2KR — 미국 마감 → 한국 개장 전 브리핑 봇
|
||||
|
||||
미국 정규장이 끝난 뒤(16:00 ET), 한국 장이 열리기 전(09:00 KST) 하루 한 번
|
||||
미국 시장 데이터를 수집하고 MiniMax LLM으로 한국어 브리핑을 만들어 발송하는 상주 프로그램입니다.
|
||||
설계 문서는 [PLAN.md](PLAN.md)를 참고하세요.
|
||||
|
||||
```
|
||||
수집(yfinance · RSS · FRED) → SQLite 저장 → MiniMax-M3 요약(JSON 스키마) → Markdown 렌더 → Telegram / 파일
|
||||
```
|
||||
|
||||
## 실행 시각
|
||||
|
||||
| | ET | KST |
|
||||
|---|---|---|
|
||||
| 미국 정규장 마감 | 16:00 | 05:00 (3~11월 EDT) / 06:00 (11~3월 EST) |
|
||||
| **브리핑 발송** (마감 +75분, 기본) | 17:15 | **06:15 / 07:15** |
|
||||
| 한국 개장 | — | 09:00 |
|
||||
|
||||
- 시각은 하드코딩이 아니라 `exchange_calendars`(XNYS/XKRX)로 계산 → 미국 휴장·조기폐장·서머타임 자동 대응
|
||||
- 미국 휴장일은 스킵, 한국 휴장일은 리포트에 "오늘 한국 휴장" 표기. `US2KR_SKIP_WHEN_KRX_CLOSED=true`면
|
||||
한국 휴장 연휴 중 **다음 미국 세션이 먼저 마감되어 무의미해지는 브리핑만** 스킵 — 금요일 세션(토요일 도착)은
|
||||
월요일 개장용으로 항상 발송
|
||||
|
||||
## 설치
|
||||
|
||||
```bash
|
||||
# Python 3.12 + uv
|
||||
uv venv --python 3.12 .venv
|
||||
uv pip install --python .venv/bin/python -e ".[dev]"
|
||||
|
||||
cp .env.example .env # MINIMAX_API_KEY 필수, TELEGRAM_* 선택
|
||||
```
|
||||
|
||||
## 사용
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m us2kr.cli show-config # 설정 확인(시크릿 마스킹)
|
||||
.venv/bin/python -m us2kr.cli next-run # 다음 브리핑 세션/시각
|
||||
.venv/bin/python -m us2kr.cli run-once --dry-run # 지금 즉시 생성해서 터미널에 출력(발송 X)
|
||||
.venv/bin/python -m us2kr.cli run-once --dry-run --no-llm # LLM 없이 숫자표만(축소 모드)
|
||||
.venv/bin/python -m us2kr.cli run-once --date 2026-08-24 # 특정 미국 세션 기준 생성·발송(마감된 세션만)
|
||||
.venv/bin/python -m us2kr.cli run-once --force # 이미 발송된 날이어도 다시(재발송)
|
||||
.venv/bin/python -m us2kr.cli test-notify # 발송 채널 점검
|
||||
.venv/bin/python -m us2kr.cli daemon # 상주 실행(스케줄러)
|
||||
```
|
||||
|
||||
종료 코드: `0` 성공 · `1` 오류(발송 채널 실패 포함) · `2` 스킵(이미 발송 / 한국 휴장)
|
||||
|
||||
아직 마감되지 않은 세션을 `--date`로 지정하면 `--dry-run`이 아닌 한 거부합니다(장중 데이터가 저장되면
|
||||
데몬의 정규 브리핑이 "이미 발송"으로 건너뛰기 때문). 발송 테스트는 `--date <직전 세션> --force`로 하세요.
|
||||
|
||||
## 상주 실행(배포)
|
||||
|
||||
프로세스 생존은 OS에 맡기고, 프로그램은 "다음 실행 시각 계산 → 대기 → 실행"만 반복합니다.
|
||||
재시작 후 마감 3시간(`US2KR_CATCHUP_WINDOW_HOURS`) 이내면 놓친 브리핑을 즉시 따라잡고, SQLite 기록으로 중복 발송을 막습니다.
|
||||
|
||||
| 환경 | 방법 |
|
||||
|---|---|
|
||||
| macOS | `bash deploy/install-launchd.sh` (launchd, KeepAlive) |
|
||||
| Linux | `deploy/us2kr.service` → `systemctl enable --now us2kr` |
|
||||
| Docker | `docker compose -f deploy/compose.yaml up -d --build` |
|
||||
|
||||
> macOS 노트북은 **잠자기 중에는 실행되지 않습니다.** 06~07시에 깨어 있도록
|
||||
> `sudo pmset repeat wakeorpoweron MTWRFS 06:00:00` 로 예약 기동을 걸거나, 항상 켜진 머신/서버에서 돌리세요.
|
||||
|
||||
## 설정(.env)
|
||||
|
||||
| 변수 | 기본값 | 설명 |
|
||||
|---|---|---|
|
||||
| `MINIMAX_API_KEY` | — | 필수. 글로벌 엔드포인트(`api.minimax.io`) 키 |
|
||||
| `MINIMAX_MODEL` | `MiniMax-M3` | 기본 모델 |
|
||||
| `MINIMAX_FALLBACK_MODELS` | `MiniMax-M2.7,MiniMax-M2.5` | 실패 시 순차 폴백 |
|
||||
| `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` | — | 둘 다 있으면 Telegram 발송 |
|
||||
| `FRED_API_KEY` | — | 있으면 경제지표 발표 일정 포함 |
|
||||
| `US2KR_RUN_OFFSET_MINUTES` | `75` | 미국 마감 후 몇 분 뒤 실행 |
|
||||
| `US2KR_CATCHUP_WINDOW_HOURS` | `3` | 재시작 시 따라잡기 허용 창 |
|
||||
| `US2KR_SKIP_WHEN_KRX_CLOSED` | `false` | 한국 휴장일에 다음 미국 세션이 먼저 마감되어 브리핑이 무의미해질 때만 스킵(금요일 세션은 항상 발송) |
|
||||
| `US2KR_NEWS_LOOKBACK_HOURS` / `US2KR_NEWS_MAX_ITEMS` | `18` / `40` | 뉴스 수집 범위 |
|
||||
| `US2KR_KRX_EXTRA_HOLIDAYS` | — | 캘린더에 없는 한국 임시휴장일 CSV (예: `2026-06-03`) |
|
||||
|
||||
## 산출물
|
||||
|
||||
- `reports/YYYY-MM-DD.md`, `.json` — 한국 거래일 기준 아카이브
|
||||
- `data/us2kr.sqlite3` — 시세 스냅샷·리포트·발송 기록(전일 대비 비교, 중복 방지)
|
||||
- `logs/us2kr.log` — 일자별 회전, API 키 마스킹
|
||||
|
||||
## 개발
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m pytest -q
|
||||
.venv/bin/ruff check us2kr tests
|
||||
```
|
||||
|
||||
LLM은 `us2kr/llm/base.py`의 `LLMProvider` 인터페이스 뒤에 있으므로, 다른 모델로 바꾸려면 구현체만 추가하면 됩니다.
|
||||
Reference in New Issue
Block a user