KOSPI·KOSDAQ 종목 자동 스크리닝 + AI/ML 분석 + 텔레그램 리포트 플랫폼

These details have not been verified by PyPI

Project links

Project description

📈 Korean Stocks AI/ML Analysis System

version python license

KOSPI · KOSDAQ 종목을 AI와 머신러닝으로 분석하는 자동화 투자 보조 플랫폼

🚀 프로젝트 소개

Korean Stocks AI/ML Analysis System은 기술적 지표 분석, 머신러닝 예측, 뉴스 감성 분석을 통합하여 한국 주식 시장의 유망 종목을 자동으로 발굴하고 리포트를 생성하는 플랫폼입니다.

매일 장 마감 후 자동으로 실행되어 KOSPI·KOSDAQ 전 종목 중 거래량 상위 · 상승 모멘텀 · 반등 후보 버킷으로 분류된 종목을 스크리닝하고, 심층 분석 후 텔레그램으로 결과를 전송합니다.

단기 AI 추천 외에, DART 공시 기반 펀더멘털과 Piotroski F-Score를 활용한 가치주 스크리닝(중기 3-6개월), ROE·영업이익률·재무건전성 기반의 우량주 스크리닝(장기 6개월+)도 지원합니다.

✨ 주요 기능

기능	설명
AI 종목 추천	기술적 지표·ML·뉴스를 종합한 복합 점수로 유망 종목 선정
버킷 기반 선정	거래량 상위·상승 모멘텀·반등 후보 3개 버킷 쿼터 보장 (배지 UI 표시)
날짜별 히스토리	과거 30일 분석 결과를 날짜 선택으로 조회
추천 지속성 히트맵	연속 추천(🔥)·비연속 반복 추천(🔄/📌) 배지로 신호 신뢰도 시각화
DB 우선 조회 & 캐시	당일 저장된 DB 결과 우선 표시, 메뉴 이탈 후 재진입 시 세션 캐시 유지
DB 자동 동기화	GitHub Actions 완료 후 DB를 저장소에 자동 커밋·푸시 → `koreanstocks sync` 한 번으로 최신 결과 반영
텔레그램 알림	종합점수 바·당일 등락률·RSI·뉴스 헤드라인·AI 강점 포함 구조화 리포트 발송
전략 백테스팅	RSI · MACD · COMPOSITE 전략 시뮬레이션 (단순보유 비교, 초보자 해석 가이드 포함)
관심 종목 관리	Watchlist 등록 및 분석 이력 타임라인 제공
추천 성과 추적	5·10·20거래일 후 실제 수익률 자동 검증, 승률·목표가 달성률 통계 제공
가치주 스크리닝	PER·PBR·ROE·부채비율·Piotroski F-Score 필터 + value_score 정렬, 당일 인메모리 캐시
우량주 스크리닝	ROE·영업이익률·YoY성장·부채비율·PBR 필터 + quality_score 정렬, ROE 2개년 평균으로 지속성 확인
모델 신뢰도 대시보드	ML 모델 AUC·과적합 갭·드리프트 등급·피처 중요도·재학습 권장 여부 확인

🛠 기술 스택

UI          FastAPI + Reveal.js (일일 브리핑) + Vanilla JS (인터랙티브 대시보드 8탭)
CLI         Typer (10개 명령어: serve / recommend / analyze / train / outcomes / value / quality / init / sync / home)
AI/LLM      OpenAI GPT-4o-mini (뉴스 감성 분석, AI 종합 의견)
ML          Scikit-learn (Random Forest, Gradient Boosting) + XGBoost Ranker + LightGBM + CatBoost
            + PyTorch TCN (선택적, pip install koreanstocks[dl])
            → 6-모델 앙상블 (분류기+TCN 75% + 랜커 25%, AUC 기반 Softmax 가중치)
기술 지표    ta (RSI, MACD, BB, SMA, OBV, ADX, VWAP, CMF, MFI, Stochastic, CCI, ATR, Donchian)
             + finta (SQZMI, VZO, Fisher Transform, Williams Fractal)
ML 피처     20개 (변동성·추세강도·시장 상대강도·모멘텀·finta·거래량·거시경제·극값감지)
데이터       FinanceDataReader, KIND API (KRX 전종목), Naver News API, DART Open API (선택)
             Yahoo Finance (VIX · S&P500 거시지표)
DB          SQLite (data/storage/stock_analysis.db)
자동화       GitHub Actions (평일 16:30 KST), Telegram Bot API
시각화       Plotly, Matplotlib, Chart.js (백테스트 차트)
언어         Python 3.11 - 3.13

🏗 시스템 아키텍처

세 가지 독립적인 분석 파이프라인: 단기 AI 추천 · 중기 가치주 스크리닝 · 장기 우량주 스크리닝

[사용자 브라우저]           [CLI]
       │                     │
       │          serve / recommend / analyze
       │          train / outcomes / value
       │          quality / init / sync / home
       │                     │
       └──────────┬──────────┘
                  ▼
        [FastAPI 서버 (koreanstocks.api)]
         ├─ AI 추천 · 분석 · Watchlist · 백테스트 · 시장 · 모델
         └─ 가치주 · 우량주 스크리닝
                  │
       ┌──────────┼──────────────────────────┐
       ▼                                     ▼
[단기 AI 추천 파이프라인]       [펀더멘털 스크리닝 파이프라인]
 indicators.py  → tech_score    value_screener.py  → F-Score + value_score
 prediction_model.py → ml_score  quality_screener.py → quality_score
 news_agent.py  → sentiment      ▲ FinanceDataReader · KIND API
 analysis_agent.py → 4단계 분석  ▲ DART Open API (ROE · 부채비율 등)
 recommendation_agent.py
   → 버킷 기반 선정 → DB 저장
   → 텔레그램 리포트 발송

[외부 데이터 소스]
 FinanceDataReader / KIND API    OHLCV · 종목목록 (2,600종목+)
 Naver News API                  종목 관련 뉴스 검색
 DART Open API                   재무제표 공시 (PER · PBR · ROE 등)
 OpenAI GPT-4o-mini              감성 분석 · AI 종합 의견
 Yahoo Finance                   VIX · S&P500 거시지표

[저장소]
 data/storage/stock_analysis.db  추천결과 · 분석이력 · 뉴스캐시 · Watchlist
 models/saved/*.pkl              학습된 ML 모델 (RF · GB · LGB · CB · XGBRanker)

🔬 분석 파이프라인

단기 AI 추천 파이프라인 (1-2주)

버킷 기반 후보군 선정

FinanceDataReader + KIND API (KOSPI · KOSDAQ 전체 종목)
  → 시장 필터 (KOSPI / KOSDAQ / ALL)
     ├─ 🟦 거래량 상위    40% 쿼터
     ├─ 🟩 상승 모멘텀    +2%-+15%,  35% 쿼터
     └─ 🟥 반등 후보      거래량 상위 중 하락,  25% 쿼터
  → 분석 풀 구성: min(limit × 8, 80)개
    ※ 기본 limit=9 → 최대 72종목

종목별 심층 분석 (4단계 병렬)

분석 풀 (최대 80종목)
  → 병렬 분석 (max_workers=5 · timeout=60s)

  1단계  기술적 지표   → tech_score  (0-100)
         추세(40pt) + 모멘텀(30pt) + BB/CMF/거래량(30pt)

  2단계  ML 앙상블    → ml_score   (0-100)
         RF · GB · LGB · CB (분류기 75%)
         + XGBRanker (랜커 25%)
         → 101분위수 캘리브레이션 → 0-100 균등 스케일

  3단계  뉴스 감성    → sentiment_score (-100-100)
         GPT-4o-mini · 지수감쇠 시간가중치

  4단계  GPT AI 의견  → BUY / HOLD / SELL · 목표가 · 강점·약점

  → 종합 점수 산출
  → 버킷 쿼터 기반 최종 N종목 선정 (섹터 다양성 고려)
  → SQLite DB 저장 + 텔레그램 리포트 발송

종합 점수 공식

ML 모델 활성 시:
  종합 점수 = Tech × 0.40 + ML × 0.35 + sentiment_norm × 0.25

ML 모델 없을 시 (폴백):
  종합 점수 = Tech × 0.65 + sentiment_norm × 0.35

  ※ sentiment_norm = (sentiment_score + 100) / 2  →  0-100 정규화

2단계 — ML 앙상블 (ml_score, 0-100)

입력 피처 (20개)

카테고리	피처
변동성·추세강도	`atr_ratio` (rolling 60일 percentile) · `adx` · `bb_width` · `bb_position`
시장 상대강도	`rs_vs_mkt_3m`
모멘텀·추세	`high_52w_ratio` · `mom_accel` · `macd_diff` · `macd_slope_5d` · `price_sma_5_ratio`
finta 지표	`fisher` · `bullish_fractal_5d`
거래량·강도	`mfi` · `vzo` · `obv_trend` · `low_52w_ratio`
극값감지·반전	`rsi` · `cci_pct`
거시경제	`vix_level` · `sp500_1m`

6-모델 앙상블 구조

20개 피처 입력
  ├─ Random Forest     (분류기) ─┐
  ├─ Gradient Boosting (분류기)  │
  ├─ LightGBM          (분류기)  ├─► AUC 기반 Softmax 가중치 집계 (75%)
  ├─ CatBoost          (분류기)  │
  ├─ TCN               (딥러닝, 선택적: pip install koreanstocks[dl]) ─┘
  └─ XGBoost Ranker    (rank:ndcg) ─────────────────────────────► (25%)
                                        │
                                        ▼
                              101분위수 캘리브레이션 → ml_score (0-100 균등)

ML 학습 설정:

타깃: 10거래일 후 수익률 상위 25% = 1 / 하위 25% = 0 (중간 50% neutral zone 제외)
Walk-Forward CV: VAL_STEP=10 거래일, 약 48 fold, Purging 20 거래일
품질 게이트: test_AUC ≥ 0.52 통과 시에만 저장 (미통과 시 tech_score 폴백)

가치주 스크리닝 파이프라인 (중기 3-6개월)

1. Naver 시가총액 순위 페이지 병렬 스크래핑
   (탐색 범위: 100 / 200 / 300종목)

2. 사전 필터: PER > 0 · ROE > 0 · 시가총액 500억 이상

3. DART Open API — 펀더멘털 수집
   PER · PBR · ROE · 부채비율 · 영업이익YoY
   ※ 연도 폴백: 전년사업보고서 → 반기 → 전전년

4. 6단계 필터
   PER ≤ 25 · PBR ≤ 3 · ROE ≥ 8% · 부채비율 ≤ 150%
   영업이익YoY ≥ -15% · F-Score ≥ 4

5. Piotroski F-Score 산출 (9점 만점)
   수익성(P1-P3) + 안전성(L1-L3) + 성장성(E1-E3)

6. value_score 산출 (0-100점)
   PER(25) + PBR(15) + ROE(20) + 부채비율(15) + 영업이익YoY(30) + 배당(10)

7. 복합 정렬: value_score × 0.7 + F-Score_normalized × 0.3
   → 당일 인메모리 캐시 (동일 조건 재실행 → 즉시 반환)

Piotroski F-Score 구성 (9점)

구분	항목	기준
수익성 (P1-P3)	P1 ROA	당기순이익 / 총자산 > 0
	P2 영업현금흐름	영업이익 > 0
	P3 ROA 개선	전년 대비 ROA 증가
안전성 (L1-L3)	L1 부채비율 감소	전년 대비 부채비율 하락
	L2 유동비율 개선	부채비율 하락 (대리지표)
	L3 무상증자 없음	PBR 정상 범위
성장성 (E1-E3)	E1 영업이익률 개선	전년 대비 영업이익률 상승
	E2 자산회전율 개선	전년 대비 매출/총자산 증가
	E3 OCF > 순이익	영업이익YoY > 5% (대리지표)

우량주 스크리닝 파이프라인 (장기 6개월+)

1. Naver 시가총액 순위 페이지 스크래핑
   (탐색 범위: 100 / 200 / 300종목)

2. 사전 필터: ROE > 0 · 시가총액 500억 이상

3. DART Open API — 펀더멘털 수집
   ROE 2개년 평균 · 영업이익률 · 영업이익YoY
   부채비율 · 배당수익률
   ※ 연도 폴백: 전년사업보고서 → 반기

4. 5단계 필터
   ROE ≥ roe_min · 영업이익률 ≥ op_margin_min
   영업이익YoY ≥ yoy_min · 부채비율 ≤ debt_max · PBR ≤ pbr_max

5. quality_score 산출 (0-100점)
   ROE(30) + 영업이익률(25) + 영업이익YoY(20) + 부채비율(15) + 배당(10)

6. ROE 2개년 평균 — 일시적 고ROE 필터링, 지속 성장 기업 확인

7. quality_score 내림차순 정렬
   → 당일 인메모리 캐시

📊 점수 체계 해석

Tech Score (기술적 지표 종합, 0-100)

점수	해석
80–100	매우 강세
60–79	강세
40–59	중립
0–39	약세

세부 구성 (합계 100점)

구성	최대	주요 지표
① 추세	40점	SMA5/20/60, MACD 골든크로스, ADX DI+/DI−
② 모멘텀	30점	RSI × MACD 방향 맥락 보정, BB 폭 보정
③ 위치·자금흐름	30점	BB 위치(20), CMF(5), 거래량 확인(5)

MACD 방향에 따라 RSI 최적 구간이 반전됩니다 (상승추세: 55-75 최적 / 하락추세: 35-50 최적).

ML Score (머신러닝 예측, 0-100)

10거래일 후 수익률 상위 25% 진입 확률의 캘리브레이션 점수.

점수	해석
70–100	강한 상승 기대 (상위 25% 고확률)
50–69	중간 이상 — 양호
30–49	중립-약세
0–29	하위권 예상

News Sentiment Score (뉴스 감성, -100-100)

점수	해석
51–100	Very Bullish (매우 긍정)
1–50	Bullish (긍정)
0	Neutral
-49--1	Bearish (부정)
-100--50	Very Bearish (매우 부정)

Value Score (가치주, 0-100)

항목	배점	최고점 기준
PER	25pt	업종 중앙값 기준 상대 평가
PBR	15pt	낮을수록 최고 / 3.0 이상 0pt
ROE	20pt	≥ 30% 최고 (2개년 평균)
부채비율	15pt	낮을수록 최고 / 150% 이상 0pt
영업이익YoY	30pt	≥ +30% 최고 / -30% 이하 0pt
배당수익률	10pt	≥ 3% 최고 (데이터 없으면 제외)

복합 정렬: value_score × 0.7 + (F-Score / 9 × 100) × 0.3

value_score	해석
70–100	우수한 저평가 종목 — 중기 매수 검토 대상
50–69	양호 — 추가 검증 후 판단
30–49	보통 — 일부 지표 취약
0–29	미달

Quality Score (우량주, 0-100)

항목	배점	최고점 기준
ROE	30pt	≥ 20% 최고 (2개년 평균)
영업이익률	25pt	≥ 20% 최고
영업이익YoY	20pt	≥ 30% 최고
부채비율	15pt	낮을수록 최고 / 100% 이상 0pt
배당수익률	10pt	≥ 3% 최고

quality_score	해석
70–100	최우량 — 장기 핵심 보유 후보
50–69	양호 — 장기 투자 검토 대상
30–49	보통 — 추가 검증 필요
0–29	미달

🖥 대시보드 메뉴 구성 (8탭)

권장 브라우저: Chrome / Firefox (최신 버전)

대시보드 URL: http://localhost:8000/dashboard

탭	주요 기능	투자 관점
① Dashboard	시장지수, AI 추천, 추천 지속성 히트맵 🔥🔄📌	당일 현황 파악
② Watchlist	관심종목 등록·삭제, 실시간 심층 분석, 분석 이력 타임라인	지속 모니터링
③ AI 추천	테마·시장별 추천 생성, 날짜 선택 히스토리, 5·10·20거래일 성과 추적	단기 1-2주
④ 가치주 추천	PER·PBR·ROE·부채비율·F-Score 필터, value_score 복합 정렬, 탐색 범위 선택	중기 3-6개월
⑤ 우량주 추천	ROE·영업이익률·YoY·부채비율 필터, quality_score 정렬, ROE 2개년 지속성	장기 6개월+
⑥ 백테스트	RSI / MACD / COMPOSITE 전략 시뮬레이션, 단순보유 비교 차트	전략 검증
⑦ 모델 신뢰도	5모델 AUC · 과적합 갭 · 드리프트 등급 · 피처 중요도 · 재학습 권장	신호 신뢰성 판단
⑧ 설정	수동 일일 업데이트 실행, 텔레그램·데이터소스 상태 확인	운영 관리

💡 실전 투자 활용 가이드

⚠️ 본 시스템은 투자 보조 도구입니다. 최종 투자 결정은 반드시 본인이 직접 판단하세요.

투자 시계 (Investment Horizon) 선택

투자 기간	추천 탭	핵심 기준
단기 (1-2주)	AI 추천 탭	종합 점수 65+ · BUY 신호 · tech+ml 동시 강세
중기 (3-6개월)	가치주 추천 탭	value_score 60+ · F-Score 6+ · PER ≤ 15 · ROE ≥ 10%
장기 (6개월+)	우량주 추천 탭	quality_score 70+ · ROE 2개년 ≥ 15% · 영업이익률 ≥ 15%

두 신호 이상 일치 시 최우선 검토 대상 (예: 단기 BUY + 가치주 상위권 동시 진입)

단기 AI 추천 활용 단계별 가이드

Step 1 — 스크리닝 (매일 자동)
  → 텔레그램 알림으로 오늘의 추천 9종목 확인
  → 종합 점수 상위 2-3종목을 후보로 선정

Step 2 — 지속성 확인 (신뢰도 검증)
  → 추천 지속성 히트맵에서 연속 추천 일수 확인
  → 🔥 (연속 2일+) 배지 종목은 신호 신뢰도 높음

Step 3 — 성과 데이터 확인
  → AI 추천 탭 → "추천 성과 추적" 섹션
  → 과거 추천의 5·10·20거래일 승률 · 목표가 달성률 확인

Step 4 — 심층 검증 (수동)
  → Dashboard 또는 AI 추천 탭 상세 리포트 확인
  → 강점/약점, 뉴스 원문 링크, 목표가 근거 직접 검토
  → 백테스트 탭에서 해당 전략의 과거 성과 확인

Step 5 — 최종 판단 기준
  아래 조건 중 2개 이상 충족 시 매수 검토 ✅
  ✓ 최근 5일 거래량 ≥ 20일 평균의 150%
  ✓ 52주 저점 대비 -20% 이내
  ✓ 뉴스 감성 Bullish 이상 (score > 20)
  ✓ 추천 지속성 히트맵 🔥 배지 (연속 2일+)
  ✓ ML Score ≥ 60 + Tech Score ≥ 65

강력 매수 후보 판단 기준

강력 매수 후보 (모든 조건 충족 시)
  ✅ Tech Score ≥ 65
  ✅ ML Score ≥ 60
  ✅ News Score > 20
  ✅ AI action = BUY
  ✅ RSI: 35-50 구간 (과매도 탈출 또는 중립 하단)
  ✅ MACD: 골든크로스 발생 또는 유지

관망 권고
  ✗ Tech < 50 이고 MACD 데드크로스 상태
  ✗ News Score < -30 (강한 악재 뉴스)
  ✗ RSI > 75 (과열 구간)

매도 검토
  ✗ AI action = SELL + Tech Score < 40
  ✗ RSI > 75 + MACD 데드크로스 동시 발생

리스크 관리 원칙

원칙	설명
분산 투자	동일 섹터에 몰리지 않도록 1-2종목만 선택
손절 기준	매수가 대비 7-8% 하락 시 손절 고려
비중 관리	단일 종목에 총 자산의 10% 이상 집중 지양
재검증	매수 후 3-5일 내 재분석으로 의견 변화 모니터링

⚙️ 설치 및 실행

방법 A — PyPI 설치 (권장: 분석 결과 조회 전용)

분석 실행 없이 GitHub Actions가 생성한 추천 결과를 대시보드로 조회할 때 사용합니다.

# 시스템 라이브러리 (XGBoost / LightGBM 구동에 필요)
sudo apt-get install -y libomp-dev   # Ubuntu / Debian
# brew install libomp               # macOS

pip install koreanstocks

koreanstocks init    # API 키 대화형 설정
koreanstocks sync    # GitHub Actions 생성 DB 다운로드
koreanstocks serve   # http://localhost:8000/dashboard 자동 열림

.env·DB·ML 모델은 ~/.koreanstocks/에 저장됩니다.

pipx로 설치 (CLI 격리 권장)

pip install pipx && pipx ensurepath
pipx install koreanstocks          # 기본 설치 (TCN 비활성화)

TCN 딥러닝 앙상블을 활성화하려면 (선택적, ~700MB):

# 방법 A: 처음부터 dl extra 포함 설치
pipx install "koreanstocks[dl]"

# 방법 B: 이미 설치한 경우 inject
pipx inject koreanstocks torch

주의: pipx는 격리 venv를 사용하므로 pip install koreanstocks[dl]로는 TCN을 활성화할 수 없습니다. 반드시 위 pipx 방식을 사용하세요.

방법 B — 저장소 클론 (개발 / 자체 분석 실행)

git clone https://github.com/bullpeng72/KoreanStock.git
cd KoreanStock

conda create -n stocks_env python=3.11
conda activate stocks_env

sudo apt-get install -y libomp-dev   # Ubuntu/Debian
pip install -e .                     # editable 설치

API 키 설정 — `koreanstocks init`

koreanstocks init                   # 대화형 입력 (권장)
koreanstocks init --non-interactive  # 빈 템플릿 생성 (CI용)

환경 변수 목록

# ── 필수 ──────────────────────────────────────────────────────
OPENAI_API_KEY=sk-proj-...         # GPT-4o-mini 뉴스 감성·AI 의견
NAVER_CLIENT_ID=abc123             # Naver News API
NAVER_CLIENT_SECRET=xyz789
TELEGRAM_BOT_TOKEN=123456:ABC-...  # 추천 리포트 발송
TELEGRAM_CHAT_ID=-1001234567890

# ── 선택 ──────────────────────────────────────────────────────
DART_API_KEY=                      # 미설정 시 뉴스만으로 감성 분석

# ── 시스템 (기본값 사용 권장) ──────────────────────────────────
DB_PATH=data/storage/stock_analysis.db
# KOREANSTOCKS_BASE_DIR=           # 데이터 루트 경로 강제 지정
# KOREANSTOCKS_GITHUB_DB_URL=      # fork 시 sync URL 재정의

변수	발급처	필수
`OPENAI_API_KEY`	platform.openai.com/api-keys	✅
`NAVER_CLIENT_ID/SECRET`	developers.naver.com — 검색 API	✅
`TELEGRAM_BOT_TOKEN`	텔레그램 @BotFather → `/newbot`	✅
`TELEGRAM_CHAT_ID`	`api.telegram.org/bot<TOKEN>/getUpdates`	✅
`DART_API_KEY`	opendart.fss.or.kr (무료)	☑️

주요 CLI 명령어

# 웹 대시보드
koreanstocks serve                     # http://localhost:8000/dashboard
koreanstocks serve --port 8080         # 포트 변경
koreanstocks serve --no-browser        # 브라우저 자동 실행 비활성화

# 일일 추천 분석 (GitHub Actions용)
koreanstocks recommend
koreanstocks recommend --market KOSPI --limit 10

# 단일 종목 심층 분석
koreanstocks analyze 005930

# ML 모델 재학습
koreanstocks train
koreanstocks train --period 2y --future-days 10

# DB 동기화 (PyPI 설치 환경)
koreanstocks sync              # 최초 수신 또는 날짜 갱신
koreanstocks sync --force      # 강제 덮어쓰기

# 추천 성과 추적
koreanstocks outcomes                  # 미검증 결과 업데이트 + 통계 출력
koreanstocks outcomes --days 180       # 최근 180일 조회
koreanstocks outcomes --no-record      # DB 업데이트 없이 통계만

# 가치주 스크리닝 (중기 3-6개월)
koreanstocks value                     # 기본 필터 (상위 20종목)
koreanstocks value --per-max 15 --roe-min 10
koreanstocks value --f-score-min 6 --candidate-limit 300

# 우량주 스크리닝 (장기 6개월+)
koreanstocks quality                   # 기본 필터 (상위 20종목)
koreanstocks quality --roe-min 15 --margin-min 15
koreanstocks quality --market KOSPI --candidate-limit 200

# 데이터 홈 디렉토리
koreanstocks home                      # 경로 출력
koreanstocks home --open               # 파일 탐색기로 열기
koreanstocks home --setup              # 셸 alias 스니펫 출력

# 테스트
pytest tests/
python tests/compat_check.py          # Python 3.11-3.13 호환성 검증

📡 API 엔드포인트

서버 실행 후 /docs에서 Swagger UI로 전체 API 문서를 확인할 수 있습니다.

라우터	엔드포인트	메서드	설명
market	`/api/market`	GET	시장 지수 (KS11/KQ11)
	`/api/market/trading-day`	GET	거래일 여부 확인
	`/api/market/ranking`	GET	시장 등락 순위
recommendations	`/api/recommendations`	GET	날짜별 추천 목록
	`/api/recommendations/run`	POST	추천 분석 실행
	`/api/recommendations/history`	GET	30일 히스토리
	`/api/recommendations/outcomes`	GET	성과 추적 통계
analysis	`/api/analysis/{code}`	GET/POST	종목 심층 분석
	`/api/analysis/{code}/history`	GET	분석 이력 타임라인
watchlist	`/api/watchlist`	GET/POST	관심 종목 조회/등록
	`/api/watchlist/{code}`	DELETE	관심 종목 삭제
backtest	`/api/backtest`	GET	전략 백테스팅
value	`/api/value_stocks`	GET	가치주 스크리닝 결과
	`/api/value_stocks/filters`	GET	필터 기본값
quality	`/api/quality_stocks`	GET	우량주 스크리닝 결과
	`/api/quality_stocks/filters`	GET	필터 기본값
models	`/api/model_health`	GET	ML 모델 헬스체크
	`/api/model_params/{name}`	GET	학습 파라미터 + 오버라이드 조회
	`/api/model_params/{name}`	POST	파라미터 오버라이드 저장
	`/api/model_params/{name}/override`	DELETE	오버라이드 초기화
	`/api/macro_context`	GET	거시경제 레짐·감성·요약
version	`/api/version`	GET	API 버전 정보

🤖 자동화 설정 (GitHub Actions)

실행 시점: 평일 오후 16:30 KST (UTC 07:30) — 장 마감 후 자동 실행

⏰ 16:30 KST 평일 자동 실행 (또는 수동 workflow_dispatch)
  │
  ├─ 한국 증시 휴장일 → 텔레그램 휴장일 알림 후 종료
  │
  └─ 거래일 진행:
      1. 지난 추천 성과 기록 (5·10·20거래일 후 수익률 집계)
         └─ 텔레그램 성과 리포트 발송
      2. KOSPI + KOSDAQ 전체 종목 갱신
      3. 버킷 기반 후보군 선정
         (거래량 상위 / 상승 모멘텀 / 반등 후보)
      4. 심층 분석 병렬 실행
         (기술적 지표 + ML 앙상블 + 뉴스 감성 + GPT)
      5. 종합 점수 상위 9종목 선정
         (버킷 쿼터 + 섹터 다양성)
      6. SQLite DB 저장
         ├─ GitHub Artifact 백업 (90일 보존)
         └─ 저장소에 DB 커밋·푸시
              ├─ git clone 환경 → git pull 로 반영
              └─ PyPI 설치 환경 → koreanstocks sync 로 반영
      7. 텔레그램 추천 리포트 발송

GitHub Secrets 등록 (Settings > Secrets and variables > Actions):

OPENAI_API_KEY
TELEGRAM_BOT_TOKEN
TELEGRAM_CHAT_ID
NAVER_CLIENT_ID
NAVER_CLIENT_SECRET
DART_API_KEY          (선택)

📁 프로젝트 구조

KoreanStocks/
├── pyproject.toml                       # pip 빌드 설정 (koreanstocks CLI 진입점)
├── requirements.txt                     # 개발/테스트 전용 (pytest 등)
├── train_models.py                      # ML 모델 재학습 스크립트
├── src/
│   └── koreanstocks/
│       ├── __init__.py                  # VERSION = "0.5.3"
│       ├── cli.py                       # Typer CLI (10개 명령어)
│       ├── api/
│       │   ├── app.py                   # FastAPI 앱 팩토리
│       │   ├── dependencies.py          # 공통 의존성
│       │   └── routers/
│       │       ├── recommendations.py   # AI 추천 · 성과 추적
│       │       ├── analysis.py          # 종목 심층 분석
│       │       ├── watchlist.py         # 관심 종목 CRUD
│       │       ├── backtest.py          # 전략 백테스팅
│       │       ├── market.py            # 시장 지수 · 거래일
│       │       ├── models.py            # ML 모델 헬스체크
│       │       ├── value.py             # 가치주 스크리닝
│       │       └── quality.py           # 우량주 스크리닝
│       ├── static/
│       │   ├── index.html               # Reveal.js 일일 브리핑 슬라이드
│       │   ├── dashboard.html           # 인터랙티브 대시보드 (8탭)
│       │   ├── js/
│       │   │   ├── slides.js
│       │   │   └── dashboard.js
│       │   └── css/theme.css
│       └── core/
│           ├── config.py                # 환경변수 및 설정 (dotenv)
│           ├── constants.py             # 버킷 상수 등 공유 상수
│           ├── data/
│           │   ├── provider.py              # 주가 · 종목목록 수집
│           │   ├── fundamental_provider.py  # DART 펀더멘털 수집
│           │   └── database.py              # SQLite CRUD
│           ├── engine/
│           │   ├── indicators.py            # 기술적 지표 계산
│           │   ├── features.py              # ML 피처 추출 (20개, 공유)
│           │   ├── strategy.py              # 전략별 시그널 생성
│           │   ├── prediction_model.py      # 6-모델 앙상블 추론 (트리 5 + TCN)
│           │   ├── news_agent.py            # 뉴스 수집 + GPT 감성
│           │   ├── analysis_agent.py        # 종목 심층 분석 오케스트레이터
│           │   ├── recommendation_agent.py  # 버킷 기반 추천 생성
│           │   ├── value_screener.py        # 가치주 스크리닝 (F-Score + value_score)
│           │   ├── quality_screener.py      # 우량주 스크리닝 (quality_score)
│           │   ├── trainer.py               # ML 모델 재학습 워크플로우
│           │   └── scheduler.py             # 자동화 워크플로우
│           └── utils/
│               ├── backtester.py        # 전략 성과 검증
│               ├── notifier.py          # 텔레그램 리포트
│               └── outcome_tracker.py   # 추천 결과 성과 추적
├── models/saved/                        # 학습된 ML 모델 (.pkl) · 파라미터 (.json)
├── data/storage/                        # SQLite DB 파일
├── docs/
│   ├── ML_ANALYSIS.md                   # ML 앙상블 시스템 기술 문서
│   ├── TECHNICAL_ANALYSIS.md            # 기술적 분석 시스템 기술 문서
│   ├── NEWS_ANALYSIS.md                 # 뉴스 감성 분석 시스템 기술 문서
│   ├── VALUE_SCREENING.md               # 가치주 스크리닝 기술 문서
│   └── QUALITY_SCREENING.md             # 우량주 스크리닝 기술 문서
├── tests/
│   ├── test_backtester.py               # 백테스터 단위 테스트
│   └── compat_check.py                  # Python 3.11-3.13 호환성 검증
└── .github/workflows/
    └── daily_analysis.yml               # GitHub Actions 스케줄러

📝 변경 이력

v0.5.3 (2026-03-16) — 모델 파라미터 조정 UI 프론트 구현 완성

✨ 신뢰도 향상 방안 대상 모델에만 ⚙ 파라미터 조정 버튼 표시 (overfit_gap > 0.10 또는 cv_auc_std > 0.05)
✨ 슬라이더 2행 레이아웃 — 파라미터명 + 기존: N + 조정값 표기, 카드 내 오버플로 수정
✨ 💾 저장 / 🔄 초기화 즉시 반영 (POST/DELETE /api/model_params/{name})

v0.5.2 (2026-03-16) — 기술 부채 해소 · 상수 중앙화 · trainer 분해 · 단위 테스트 추가

🔧 constants.py: 레짐 임계값·앙상블 가중치·Softmax 온도·max_workers 상수 추출 (매직넘버 중앙화)
🔧 provider.py: fetch_macro_df() / fetch_market_df() 공유 함수 추출 + _HEADERS 모듈 상수화
🔧 trainer.py: train_and_save() 255줄 → 3개 헬퍼 함수 + ~80줄 오케스트레이터로 분해
🔧 quality_screener.py: O(n²) 종목 룩업 → set_index O(1) + calc_roe_avg() 공유 함수 추출
🔧 value.py / quality.py 라우터: Depends() 패턴 통일 (테스트 인젝션 가능)
🐛 backtester.py: Sharpe 계산 시 NaN sync-back 제거 — 표준편차 왜곡 버그 수정
🐛 features.py / prediction_model.py: market_df·macro_df 중복 인덱스 방어 코드 추가
🐛 sync CLI URL 오타 수정 (KoreanStock → KoreanStocks)
✨ tests/test_core.py 신규: 단위 테스트 29개 추가

v0.5.1 (2026-03-16) — 모델 파라미터 UI · 신뢰도 권장 파라미터 정확화

✨ models.py / dashboard.js: 모델 파라미터 조회·조정 UI — 학습 파라미터 토글, 오버라이드 저장 (*_overrides.json), 재학습 시 자동 병합
✨ GET/POST/DELETE /api/model_params/{name} 엔드포인트 — 파라미터 오버라이드 CRUD, 서버 측 범위 검증
🔧 신뢰도 향상 방안 카드 — 모델별 실제 파라미터명으로 조치 텍스트 정확화 (XGBoost: min_child_weight, LightGBM: min_child_samples, CatBoost: min_data_in_leaf)
🐛 dashboard.js: innerHTML += 반복 시 DOM 재직렬화 버그 → createElement + addEventListener 방식으로 교체
🐛 trainer.py: 학습 루프에 *_overrides.json 자동 merge 로직 추가

v0.5.0 (2026-03-13) — 거시경제 통합 · MacroNewsAgent · 대시보드 거시 UI · ML 28피처

✨ macro_news_agent.py 신규: 거시 뉴스 감성 분석 + 레짐 감지 (risk_on / uncertain / risk_off)
✨ ML 피처 20개 → 28개 (vix_change_5d, tnx_level, tnx_change_1m, yield_spread, nasdaq_1m, gold_1m, oil_1m, csi300_1m)
✨ GET /api/macro_context 신설 — 레짐·감성·요약 반환
✨ 대시보드 거시경제 UI — 레짐 배너 (Dashboard·AI추천 탭), 레짐 배지, 거시감성 모달 섹션
🔧 종합 점수 3-케이스 확장 (with_ml_macro: tech×0.35 + ml×0.35 + 종목감성×0.20 + 거시감성×0.10)
🐛 trainer._fetch_macro_data(): 2심볼 → 8심볼 전체 수집 (7개 피처 중요도 0% 버그 해결)

v0.4.x (2026-03-06 ~ 2026-03-12) — 가치·우량주 스크리너 · TCN 딥러닝 앙상블 · 히트맵 · 안정성 강화

✨ 가치주 추천 탭 — PER·PBR·ROE·F-Score 필터 + koreanstocks value CLI + GET /api/value_stocks
✨ 우량주 추천 탭 — ROE·영업이익률·YoY성장 필터 + koreanstocks quality CLI + GET /api/quality_stocks
✨ tcn_model.py 신규: Dilated Causal Conv1D TCN — 6-모델 앙상블 완성 (RF · GB · LGB · CB · XGBRanker · TCN)
✨ 추천 지속성 히트맵 — 7등급 체계(SS/S/A/B/Cp/C/D), 연속 추천 배지, 5단계 정렬 tiebreaker
✨ 추천 성과 Collapse UI, 성과 탭 자동 재시도, target_hit 소급 집계
🔧 ML 피처 17→20개 (obv_trend, rsi, cci_pct), Walk-Forward CV 강화, TCN 과적합 억제
🔧 FDR DataReader read timeout 전역 패치 — 학습 수집 hang 해결
🔧 pipx 환경 감지 → pipx inject koreanstocks torch 안내 자동 출력
🐛 pandas·yfinance FutureWarning 전면 제거, SettingWithCopyWarning 수정
🐛 fundamental_provider.py DART 재작성 — ROE·부채비율 대차대조표 직접 계산

v0.3.x (2026-02-28 - 2026-03-05) — 추천 성과 추적 · 5-모델 앙상블 · pykrx 제거

✨ 추천 성과 추적 (5·10·20거래일 후 실적 검증, outcomes CLI 및 Web UI)
✨ 버킷 배지 UI (거래량 상위/상승 모멘텀/반등 후보) — 대시보드·슬라이드 동시 반영
✨ LightGBM · CatBoost 추가 → 5-모델 앙상블
✨ XGBoost 이진 분류 → XGBRanker (rank:ndcg) 교체
✨ /api/version 엔드포인트 신설
🔧 pykrx 완전 제거 → FinanceDataReader + KIND API

⚠️ 면책 조항

본 소프트웨어는 교육 및 정보 제공 목적으로만 제작되었습니다.

본 시스템의 분석 결과는 투자 권유 또는 금융 조언이 아닙니다.
AI 및 ML 모델의 예측은 미래 수익을 보장하지 않습니다.
주식 투자에는 원금 손실의 위험이 있습니다.
최종 투자 결정과 그에 따른 손익은 전적으로 투자자 본인에게 있습니다.

📄 라이선스

이 프로젝트는 MIT License를 따릅니다.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.5.5

Apr 3, 2026

0.5.4

Mar 17, 2026

This version

0.5.3

Mar 16, 2026

0.5.2

Mar 16, 2026

0.5.0

Mar 13, 2026

0.4.6

Mar 12, 2026

0.4.5

Mar 12, 2026

0.4.4

Mar 11, 2026

0.4.3

Mar 11, 2026

0.4.2

Mar 10, 2026

0.4.1

Mar 10, 2026

0.4.0

Mar 6, 2026

0.3.8

Mar 5, 2026

0.3.7

Mar 5, 2026

0.3.6

Mar 4, 2026

0.3.5

Mar 3, 2026

0.3.4

Mar 2, 2026

0.3.3

Mar 2, 2026

0.3.2

Mar 2, 2026

0.3.1

Mar 1, 2026

0.3.0

Feb 28, 2026

0.2.9

Feb 28, 2026

0.2.8

Feb 28, 2026

0.2.7

Feb 28, 2026

0.2.6

Feb 28, 2026

0.2.5

Feb 28, 2026

0.2.4

Feb 28, 2026

0.2.3

Feb 27, 2026

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

koreanstocks-0.5.3.tar.gz (240.2 kB view details)

Uploaded Mar 16, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

koreanstocks-0.5.3-py3-none-any.whl (215.2 kB view details)

Uploaded Mar 16, 2026 Python 3

File details

Details for the file koreanstocks-0.5.3.tar.gz.

File metadata

Download URL: koreanstocks-0.5.3.tar.gz
Upload date: Mar 16, 2026
Size: 240.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.14

File hashes

Hashes for koreanstocks-0.5.3.tar.gz
Algorithm	Hash digest
SHA256	`4cc9ffb5f8dba3e7596f35f718f0ea907bf1bdb946f9ab7708f157a38bc0fa9f`
MD5	`2697867e60d8048b0cbf990d521e8987`
BLAKE2b-256	`c32ed46cefd97d115216a0827cdb5c95ae1180c64eca27762a16874cc2d99bd4`

See more details on using hashes here.

File details

Details for the file koreanstocks-0.5.3-py3-none-any.whl.

File metadata

Download URL: koreanstocks-0.5.3-py3-none-any.whl
Upload date: Mar 16, 2026
Size: 215.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.11.14

File hashes

Hashes for koreanstocks-0.5.3-py3-none-any.whl
Algorithm	Hash digest
SHA256	`ddad223207d93ec63fdda635516e10d419d15d6f830e1484bcfb25682b2f47b9`
MD5	`f2f714fddc3a3776eb27ffb11cb9983c`
BLAKE2b-256	`b47ea1e1bbae3e7198b6b77293cedc84285db8f48951b9f08c912309649a3df6`

See more details on using hashes here.

koreanstocks 0.5.3

Navigation

Verified details

Maintainers

Meta

Unverified details

Project links

Meta

Classifiers

Project description

📈 Korean Stocks AI/ML Analysis System

목차

🚀 프로젝트 소개

✨ 주요 기능

🛠 기술 스택

🏗 시스템 아키텍처

🔬 분석 파이프라인

단기 AI 추천 파이프라인 (1-2주)

버킷 기반 후보군 선정

종목별 심층 분석 (4단계 병렬)

종합 점수 공식

2단계 — ML 앙상블 (ml_score, 0-100)

입력 피처 (20개)

6-모델 앙상블 구조

가치주 스크리닝 파이프라인 (중기 3-6개월)

Piotroski F-Score 구성 (9점)

우량주 스크리닝 파이프라인 (장기 6개월+)

📊 점수 체계 해석

Tech Score (기술적 지표 종합, 0-100)

ML Score (머신러닝 예측, 0-100)

News Sentiment Score (뉴스 감성, -100-100)

Value Score (가치주, 0-100)

Quality Score (우량주, 0-100)

🖥 대시보드 메뉴 구성 (8탭)

💡 실전 투자 활용 가이드

투자 시계 (Investment Horizon) 선택

단기 AI 추천 활용 단계별 가이드

강력 매수 후보 판단 기준

리스크 관리 원칙

⚙️ 설치 및 실행

방법 A — PyPI 설치 (권장: 분석 결과 조회 전용)

pipx로 설치 (CLI 격리 권장)

방법 B — 저장소 클론 (개발 / 자체 분석 실행)

API 키 설정 — koreanstocks init

환경 변수 목록

주요 CLI 명령어

📡 API 엔드포인트

🤖 자동화 설정 (GitHub Actions)

📁 프로젝트 구조

📝 변경 이력

v0.5.3 (2026-03-16) — 모델 파라미터 조정 UI 프론트 구현 완성

v0.5.2 (2026-03-16) — 기술 부채 해소 · 상수 중앙화 · trainer 분해 · 단위 테스트 추가

v0.5.1 (2026-03-16) — 모델 파라미터 UI · 신뢰도 권장 파라미터 정확화

v0.5.0 (2026-03-13) — 거시경제 통합 · MacroNewsAgent · 대시보드 거시 UI · ML 28피처

v0.4.x (2026-03-06 ~ 2026-03-12) — 가치·우량주 스크리너 · TCN 딥러닝 앙상블 · 히트맵 · 안정성 강화

v0.3.x (2026-02-28 - 2026-03-05) — 추천 성과 추적 · 5-모델 앙상블 · pykrx 제거

⚠️ 면책 조항

📄 라이선스

Project details

Verified details

Maintainers

Meta

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

API 키 설정 — `koreanstocks init`