US2KR — 미국 마감 → 한국 개장 전 브리핑 봇
미국 정규장이 끝난 뒤(16:00 ET), 한국 장이 열리기 전(09:00 KST) 하루 한 번 미국 시장 데이터를 수집하고 MiniMax LLM으로 한국어 브리핑을 만들어 발송하는 상주 프로그램입니다. 설계 문서는 PLAN.md를 참고하세요.
수집(yfinance · RSS · FRED) → SQLite 저장 → MiniMax-M3 요약(JSON 스키마) → Markdown 렌더 → Telegram / 파일
실행 시각
| ET | KST | |
|---|---|---|
| 미국 정규장 마감 | 16:00 | 05:00 (3 |
| 브리핑 발송 (마감 +75분, 기본) | 17:15 | 06:15 / 07:15 |
| 한국 개장 | — | 09:00 |
- 시각은 하드코딩이 아니라
exchange_calendars(XNYS/XKRX)로 계산 → 미국 휴장·조기폐장·서머타임 자동 대응 - 미국 휴장일은 스킵, 한국 휴장일은 리포트에 "오늘 한국 휴장" 표기.
US2KR_SKIP_WHEN_KRX_CLOSED=true면 한국 휴장 연휴 중 다음 미국 세션이 먼저 마감되어 무의미해지는 브리핑만 스킵 — 금요일 세션(토요일 도착)은 월요일 개장용으로 항상 발송
설치
# 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_* 선택
사용
.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 키 마스킹
개발
.venv/bin/python -m pytest -q
.venv/bin/ruff check us2kr tests
LLM은 us2kr/llm/base.py의 LLMProvider 인터페이스 뒤에 있으므로, 다른 모델로 바꾸려면 구현체만 추가하면 됩니다.