US2KR/README.md

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 (311월 EDT) / 06:00 (113월 EST)
브리핑 발송 (마감 +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)
macOS (Apple container)	bash deploy/install-apple-container.sh — 데몬+대시보드 빌드·기동. --boot를 붙이면 로그인 시 자동 기동(LaunchAgent) 등록
Linux	deploy/us2kr.service → systemctl enable --now us2kr
Docker	docker compose -f deploy/compose.yaml up -d --build

Apple container(brew install container)는 restart 정책이 없어 재부팅 후 자동 기동은 --boot의 LaunchAgent(container system start + container start us2kr)가 담당합니다. data/ reports/ logs/는 호스트 디렉터리를 그대로 마운트하므로 launchd 방식과 산출물 위치가 같습니다.

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	뉴스 수집 범위
SEARXNG_BASE_URL	—	있으면 RSS 외에 SearXNG 뉴스 검색 결과도 병합 (인스턴스에 json 포맷 활성화 필요)
US2KR_SEARXNG_QUERIES	기본 검색어 3개	SearXNG 검색어 CSV (기본: us2kr/collectors/searx.py의 DEFAULT_QUERIES)
US2KR_KRX_EXTRA_HOLIDAYS	—	캘린더에 없는 한국 임시휴장일 CSV (예: 2026-06-03)

산출물

• reports/YYYY-MM-DD.md, .json — 한국 거래일 기준 아카이브
• data/us2kr.sqlite3 — 시세 스냅샷·리포트·발송 기록(전일 대비 비교, 중복 방지)
• logs/us2kr.log — 일자별 회전, API 키 마스킹

대시보드 (dashboard/)

쌓인 브리핑을 보는 웹 대시보드(TypeScript, 런타임 의존성 없는 Node 24 서버 + 번들 클라이언트). reports/*.json만 읽는 읽기 전용 뷰라 데몬의 SQLite(WAL)와 절대 경합하지 않습니다.

• 최신 세션 요약 타일(S&P·나스닥·SOX·VIX·달러/원·10년물), 종목별 종가 추이 차트(표 전환 가능)
• 브리핑 목록/본문(Markdown 렌더, sanitize), 데이터 결측·오류 로그 표시
• Apple container 배포 시 함께 기동: http://localhost:8090 (포트: US2KR_DASHBOARD_PORT)

cd dashboard
npm install
npm run build        # tsc 타입체크 + esbuild 번들
US2KR_REPORTS_DIR=../reports npm start   # http://localhost:8090

개발

.venv/bin/python -m pytest -q
.venv/bin/ruff check us2kr tests

LLM은 us2kr/llm/base.py의 LLMProvider 인터페이스 뒤에 있으므로, 다른 모델로 바꾸려면 구현체만 추가하면 됩니다.