koreanstocks 0.4.1

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

📈 Korean Stocks AI/ML Analysis System

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

---

목차

1. 프로젝트 소개
2. 주요 기능
3. 기술 스택
4. 시스템 아키텍처
5. 분석 파이프라인
   • AI 추천 파이프라인 (단기)
   • 가치주 스크리닝 파이프라인 (중기)
6. 점수 체계 해석
7. 실전 투자 활용 가이드
8. 설치 및 실행
   • 방법 A — PyPI 설치
   • 방법 B — 저장소 클론
   • API 키 설정
9. 자동화 설정
10. 면책 조항

---

🚀 프로젝트 소개

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

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

단기 AI 추천 외에, DART 공시 기반 펀더멘털(PER·PBR·ROE·부채비율)과 Piotroski F-Score를 활용한 가치주 스크리닝(중기 3~6개월), 그리고 ROE·영업이익률·재무건전성 기반의 우량주 스크리닝(장기 6개월+)도 지원합니다. 각 스크리너는 대시보드에서 직접 필터링하고 value_score / quality_score 순으로 조회할 수 있습니다.

---

✨ 주요 기능

기능	설명
AI 종목 추천	기술적 지표·ML·뉴스를 종합한 복합 점수로 유망 종목 선정
버킷 기반 선정	거래량 상위·상승 모멘텀·반등 후보 3개 버킷 쿼터 보장 (배지 UI 표시)
날짜별 히스토리	과거 30일 분석 결과를 날짜 선택으로 조회
추천 지속성 히트맵	종목별 연속 추천 일수를 히트맵으로 시각화 (연속 2일+ 시 🔥 배지)
DB 우선 조회 & 세션 캐시	'새로 분석 실행' 클릭 시 당일 저장된 DB 결과 우선 표시 (불필요한 재분석 방지), 메뉴 이탈 후 재진입해도 결과 유지
DB 자동 동기화	GitHub Actions 완료 후 분석 DB를 저장소에 자동 커밋·푸시 → git clone 환경은 git pull, PyPI 설치 환경은 koreanstocks sync 한 번으로 최신 추천 결과 반영
텔레그램 알림	종합점수 바·당일 등락률·RSI·뉴스 헤드라인·AI 강점 포함 구조화 리포트 발송
전략 백테스팅	RSI · MACD · COMPOSITE 전략 시뮬레이션 (단순보유 비교, 원금선 차트, 초보자 해석 가이드 포함)
관심 종목 관리	Watchlist 등록 및 분석 이력 타임라인 제공
테마 필터링	AI · 반도체 · 이차전지 · 바이오 등 테마별 종목 발굴
뉴스 기사 링크	감성 분석에 활용된 뉴스 기사 원문 링크 제공
추천 성과 추적	5·10·20거래일 후 실제 수익률 자동 검증, 승률·목표가 달성률 통계 제공 (Web UI + CLI + 텔레그램)
가치주 스크리닝	PER·PBR·ROE·부채비율·Piotroski F-Score 필터 + value_score 정렬, DART 기반 펀더멘털 자동 수집, 당일 인메모리 캐시
우량주 스크리닝	ROE·영업이익률·YoY성장·부채비율·PBR 필터 + quality_score 정렬, ROE 2개년 평균으로 지속성 확인, 장기(6개월+) 수익성 우량 기업 발굴

---

🛠 기술 스택

UI          FastAPI + Reveal.js (일일 브리핑) + Vanilla JS (인터랙티브 대시보드)
CLI         Typer (koreanstocks serve / recommend / analyze / train / init / sync / home / outcomes / value / quality)
AI/LLM      OpenAI GPT-4o-mini
ML          Scikit-learn (Random Forest, Gradient Boosting), XGBoost Ranker, LightGBM, CatBoost
기술 지표    ta (RSI, MACD, BB, SMA, OBV, ADX, VWAP, CMF, MFI, Stochastic, CCI, ATR, Donchian)
             + finta (SQZMI, VZO, Fisher Transform, Williams Fractal)
데이터       FinanceDataReader, Naver News API, DART Open API (선택)
DB          SQLite
자동화       GitHub Actions (평일 16:30 KST), Telegram Bot API
시각화       Plotly, Matplotlib, Chart.js (백테스트 차트)
언어         Python 3.11 ~ 3.13

---

🏗 시스템 아키텍처

두 개의 독립적인 분석 파이프라인으로 구성됩니다: 단기 AI 추천 (기술·ML·뉴스)과 중기 가치주 스크리닝 (DART 펀더멘털·F-Score).

graph TD
    CLI["🖥 CLI<br/>serve · recommend · analyze · train<br/>outcomes · sync · init · home · value · quality"]
    USER["👤 사용자<br/>브라우저"]

    subgraph API["⚡ FastAPI  (koreanstocks.api)"]
        RA["recommendations<br/>analysis · watchlist<br/>backtest · market · models"]
        RV["value · quality<br/>GET /api/value_stocks<br/>GET /api/quality_stocks"]
    end

    subgraph FRONTEND["🌐 Frontend (dashboard.html — 8탭)"]
        F_AI["AI 추천 탭<br/>Watchlist · Dashboard<br/>백테스트 · 모델신뢰도 · 설정"]
        F_VAL["가치주 추천 탭<br/>PER·PBR·ROE·F-Score 필터<br/>value_score 정렬"]
        F_QUAL["우량주 추천 탭<br/>ROE·영업이익률·YoY·부채비율 필터<br/>quality_score 정렬"]
    end

    subgraph PIPELINE_AI["🤖 단기 AI 추천 파이프라인"]
        E1["indicators.py<br/>기술적 지표 → tech_score"]
        E2["prediction_model.py<br/>ML 앙상블 → ml_score<br/>RF · GB · LGB · CB · XGBRanker"]
        E3["news_agent.py<br/>뉴스 감성 → sentiment_score<br/>GPT-4o-mini"]
        E4["analysis_agent.py<br/>4단계 심층 분석<br/>GPT 종합 의견"]
        E5["recommendation_agent.py<br/>버킷 기반 종목 선정<br/>composite score 산출"]
        E6["scheduler.py<br/>자동화 워크플로우"]
        E7["trainer.py<br/>ML 모델 재학습"]
    end

    subgraph PIPELINE_FUND["💰 펀더멘털 스크리닝 파이프라인"]
        V1["value_screener.py<br/>Piotroski F-Score<br/>value_score 산출<br/>인메모리 캐시"]
        Q1["quality_screener.py<br/>ROE 2개년 평균<br/>quality_score 산출<br/>인메모리 캐시"]
    end

    subgraph DATA["📊 Data Layer"]
        D1["provider.py<br/>FinanceDataReader · KIND API<br/>주가 OHLCV · 종목 목록<br/>가치주 후보군(시가총액 기준)"]
        D2["fundamental_provider.py<br/>DART Open API<br/>PER · PBR · ROE · 부채비율<br/>영업이익YoY · 연도 폴백"]
        D3["database.py<br/>SQLite CRUD<br/>추천 결과 · 분석 이력<br/>워치리스트 · 뉴스 캐시"]
    end

    subgraph EXT["🌐 외부 데이터 소스"]
        X1["FinanceDataReader<br/>OHLCV · 시장지수"]
        X2["KIND API<br/>KRX 전종목 (2,657개)"]
        X3["Naver News API<br/>종목 뉴스"]
        X4["DART Open API<br/>재무제표 공시"]
        X5["OpenAI GPT-4o-mini<br/>감성 분석 · AI 의견"]
        X6["Yahoo Finance<br/>VIX · S&P500 (거시지표)"]
    end

    subgraph STORAGE["💾 저장소"]
        S1[("stock_analysis.db")]
        S2["models/saved/*.pkl<br/>학습된 ML 모델"]
    end

    subgraph UTILS["🛠 Utils"]
        U1["backtester.py"]
        U2["notifier.py<br/>텔레그램"]
        U3["outcome_tracker.py<br/>성과 추적"]
    end

    CLI -->|서버 기동| API
    CLI -->|직접 실행| PIPELINE_AI
    CLI -->|koreanstocks value/quality| PIPELINE_FUND

    USER --> FRONTEND
    FRONTEND -->|REST| API
    API --> RA --> PIPELINE_AI
    API --> RV --> PIPELINE_FUND

    PIPELINE_AI --> E1 & E2 & E3
    E1 & E2 & E3 --> E4 --> E5
    E5 --> D3
    E6 --> PIPELINE_AI
    E7 --> S2
    E2 --> S2

    PIPELINE_FUND --> V1 & Q1
    V1 --> D1 & D2
    Q1 --> D1 & D2

    D1 --> X1 & X2
    D2 --> X4
    E3 --> X3 & X5
    E4 --> X5
    E1 & E2 --> X6

    D3 --> S1
    U3 --> D3
    U2 --> X5
    E5 --> U2

KoreanStocks/
├── pyproject.toml                       # pip 빌드 설정 (koreanstocks CLI 진입점)
├── requirements.txt                     # 개발/테스트 전용 (pytest 등)
├── src/
│   └── koreanstocks/
│       ├── __init__.py                  # VERSION = "0.4.1"
│       ├── cli.py                       # Typer CLI (serve/recommend/analyze/train/init/sync/home/outcomes/value/quality)
│       ├── api/
│       │   ├── app.py                   # FastAPI 앱 팩토리, StaticFiles 마운트
│       │   ├── dependencies.py          # 공통 의존성
│       │   └── routers/
│       │       ├── recommendations.py   # GET/POST /api/recommendations
│       │       ├── analysis.py          # GET/POST /api/analysis/{code}
│       │       ├── watchlist.py         # CRUD /api/watchlist
│       │       ├── backtest.py          # GET /api/backtest
│       │       ├── market.py            # GET /api/market
│       │       ├── models.py            # GET /api/model_health
│       │       ├── value.py             # GET /api/value_stocks (가치주 스크리닝)
│       │       └── quality.py           # GET /api/quality_stocks (우량주 스크리닝)
│       ├── static/
│       │   ├── index.html               # Reveal.js 일일 브리핑 슬라이드
│       │   ├── dashboard.html           # 인터랙티브 대시보드 (8탭)
│       │   ├── js/
│       │   │   ├── slides.js            # 슬라이드 동적 생성
│       │   │   └── dashboard.js         # 대시보드 인터랙션
│       │   └── css/
│       │       └── theme.css            # 공통 스타일
│       └── core/
│           ├── config.py                # 환경변수 및 설정 관리 (VERSION 포함)
│           ├── data/
│           │   ├── provider.py              # 주가 데이터 수집 (FinanceDataReader + KIND API)
│           │   ├── fundamental_provider.py  # DART 기반 펀더멘털 수집 (ROE·부채비율·PER·PBR)
│           │   └── database.py              # SQLite 관리 (분석 결과, 워치리스트)
│           ├── engine/
│           │   ├── indicators.py            # 기술적 지표 계산 (RSI, MACD, BB, SMA, OBV)
│           │   ├── features.py              # 공유 피처 추출 (trainer·prediction_model 공용, 20개)
│           │   ├── strategy.py              # 전략별 시그널 생성 (TechnicalStrategy)
│           │   ├── prediction_model.py      # ML 앙상블 예측 (RF · GB · LGB · CB · XGBRanker 앙상블)
│           │   ├── news_agent.py            # 뉴스 수집 + 감성 분석 (GPT-4o-mini)
│           │   ├── analysis_agent.py        # 종목 심층 분석 오케스트레이터
│           │   ├── recommendation_agent.py  # 버킷 기반 종목 선정 + 추천 생성
│           │   ├── value_screener.py        # 가치주 스크리닝 엔진 (Piotroski F-Score + value_score)
│           │   ├── quality_screener.py      # 우량주 스크리닝 엔진 (quality_score + ROE 2개년 평균)
│           │   ├── trainer.py               # ML 모델 학습 워크플로우
│           │   └── scheduler.py             # 자동화 워크플로우
│           └── utils/
│               ├── backtester.py        # 전략 성과 검증 엔진
│               ├── notifier.py          # 텔레그램 리포트 발송
│               └── outcome_tracker.py   # 추천 결과 검증 (5·10·20거래일 후 성과 기록)
├── models/saved/                        # 학습된 ML 모델 및 파라미터
├── data/storage/                        # SQLite 데이터베이스 파일
├── train_models.py                      # ML 모델 재학습 스크립트 (진입점)
├── tests/
│   ├── test_backtester.py               # 백테스터 단위 테스트 (pytest)
│   └── compat_check.py                  # Python 3.11~3.13 호환성 검증
└── .github/workflows/
    └── daily_analysis.yml               # GitHub Actions 자동화 스케줄러

---

🔬 분석 파이프라인

버킷 기반 후보군 선정

flowchart TD
    A["FinanceDataReader<br/>KIND API<br/>전체 종목 수집"] --> B["시장 필터<br/>KOSPI / KOSDAQ / ALL"]
    B --> V["거래량 상위<br/>40% 버킷"]
    B --> M["상승 모멘텀<br/>+2%~+15%<br/>35% 버킷"]
    B --> R["반등 후보<br/>거래량 상위 중 하락<br/>25% 버킷"]

    V & M & R --> POOL["분석 풀 구성<br/>min(limit × 8, 80)개<br/>limit=9 → 72종목"]

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

flowchart TD
    POOL["분석 풀<br/>최대 80종목"] --> PAR["병렬 분석<br/>max_workers=5<br/>timeout=60s"]

    PAR --> T["1단계<br/>기술적 지표<br/>tech_score 0~100"]
    PAR --> ML["2단계<br/>ML 앙상블<br/>ml_score 0~100"]
    PAR --> N["3단계<br/>뉴스 감성 분석<br/>sentiment -100~100"]

    T & ML & N --> GPT["4단계<br/>GPT-4o-mini<br/>AI 종합 의견"]
    GPT --> C["종합 점수 산출<br/>tech×0.40 + ml×0.35<br/>+ sentiment_norm×0.25"]
    C --> Q["버킷 쿼터 기반<br/>최종 N종목 선정<br/>섹터 다양성 고려"]
    Q --> DB[("SQLite DB<br/>날짜별 저장")]
    Q --> TG["텔레그램<br/>리포트 발송"]

1단계 — 기술적 지표 (tech_score, 0–100)

지표: SMA 5/20/60/120, MACD, RSI(14), Bollinger Bands, OBV, Stochastic, CCI, ATR
      + ADX (DI+/DI−), CMF, VZO, Fisher Transform, Williams Fractal (finta)

구성: ① 추세   (최대 40점) — SMA, MACD 골든크로스, ADX 방향
      ② 모멘텀 (최대 30점) — RSI × MACD 방향 맥락 보정
      ③ 위치   (최대 30점) — BB 위치 + CMF 자금흐름 + 거래량 확인

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

모델: RF · GB · LGB · CB (AUC 기반 가중 앙상블, 이진 분류) + XGBRanker (rank:ndcg, 크로스섹셔널 직접 최적화)
피처: 20개 (순수 기술지표 + 거시경제, pykrx 의존성 없음)
  · 변동성·추세강도 (4): ATR 비율(rolling 60일 percentile), ADX, BB 너비, BB 위치
  · 시장 상대강도 (1): 3개월 시장 초과수익 (vs KS11/KQ11)
  · 모멘텀·추세 (5): 52주 고점 비율, 모멘텀 가속도, MACD diff, MACD diff 5일 기울기, 가격/SMA5 비율
  · finta 지표 (2): Fisher Transform, Williams Fractal (5일)
  · 거래량·강도 (4): MFI, VZO, 52주 저가 대비 반등 위치, OBV 추세
  · 거시경제 (2): VIX 레벨, S&P500 1개월 수익률
  · 극값감지·반전 (2): RSI, CCI percentile
타깃: 10거래일 후 수익률 상위 25% = 1 / 하위 25% = 0 (중간 50% 제외, neutral zone)
출력: 이진 분류 확률(RF·GB·LGB·CB) + Ranker 점수(XGBRanker) → 101분위수 캘리브레이션 → 0~100 균등 스케일
폴백: 모델 없을 경우 tech_score로 대체

3단계 — 뉴스 감성 분석 (sentiment_score, -100–100)

소스: Naver News API (display=50, 중복 제거 후 고유 기사 확보)
    + DART 공시 API (최근 30일, 유상증자·합병·수주 등 공식 공시, 선택)
가중치: 지수 감쇠 시간 가중치 (오늘=1.00 / 7일 전=0.09)
분석: GPT-4o-mini (temperature=0.1, 퀀트 애널리스트 시스템 프롬프트)
캐시: L1 메모리 + L2 SQLite 당일 캐시 (API 비용 절감)

4단계 — AI 종합 의견

입력: 전 단계 데이터 + 점수 기준표
출력: action (BUY/HOLD/SELL), 요약, 강점, 약점, 추천 사유, 목표가
보정: action과 목표가 일관성 자동 검증

종합 점수 공식

flowchart LR
    T["Tech Score<br/>0~100"] -->|"× 0.40"| SUM["종합 점수<br/>0~100"]
    ML["ML Score<br/>0~100"] -->|"× 0.35"| SUM
    N["News Score<br/>-100~100<br/>→ 정규화 0~100"] -->|"× 0.25"| SUM

    SUM --> FB["※ ML 모델 없을 때<br/>tech×0.65 + sentiment_norm×0.35"]

    style FB fill:#f9f,stroke:#999,stroke-dasharray:5 5

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

가치주 스크리닝 파이프라인

AI 추천과 독립적으로 실행되는 중기(3~6개월) 저평가 종목 발굴 파이프라인입니다.

flowchart TD
    A["Naver 시가총액 순위 페이지<br/>병렬 스크래핑<br/>(100/200/300종목 선택)"] --> B["사전 필터<br/>PER > 0 · ROE > 0<br/>시가총액 500억 이상"]
    B --> C["DART Open API<br/>펀더멘털 수집<br/>PER · PBR · ROE<br/>부채비율 · 영업이익YoY"]
    C --> D["6단계 필터<br/>PER ≤ 25 · PBR ≤ 3<br/>ROE ≥ 5% · 부채비율 ≤ 200%<br/>영업이익YoY ≥ -20%<br/>F-Score ≥ 4"]
    D --> E["Piotroski F-Score<br/>9점 만점<br/>수익성(P1~P3)<br/>안전성(L1~L3)<br/>성장성(E1~E3)"]
    D --> F["value_score<br/>0~100점<br/>PER·PBR·ROE<br/>부채비율·영업이익YoY"]
    E & F --> G["복합 정렬<br/>value_score × 0.7<br/>+ F-Score × 0.3"]
    G --> H["결과 반환<br/>당일 인메모리 캐시<br/>(동일 조건 재실행 0초)"]

DART 연도 폴백 순서

1순위: (year-1) 사업보고서 (11011)   — 전년도 확정 실적
2순위: (year-1) 반기보고서 (11012)   — 전년도 상반기 잠정
3순위: (year-2) 사업보고서 (11011)   — 전전년도 (최후 수단)

Piotroski F-Score 구성 (9점)

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

DART에서 전년도 대비 데이터를 확보하지 못한 항목은 0점 처리 (보수적 평가).

---

📊 점수 체계 해석

Tech Score (기술적 지표 종합)

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

세부 구성 (합계 100점)

① 추세 (최대 40점)

조건	SMA60 계산 가능 시	SMA60 미계산 시
종가 > SMA20	+10	+10
SMA5 > SMA20	+10	+10
MACD > Signal (골든크로스)	+15	+20
종가 > SMA60 (중기 추세 확인)	+5	—
ADX DI+ > DI− (추세 방향 확인)	+3 (최대 40 캡)	+3 (최대 40 캡)

SMA60 미계산 시 MACD에 가중치를 흡수하여 기본 합계 40점 유지. ADX 보너스는 40점 초과 불가.

② 모멘텀 (최대 30점) — MACD 방향별 RSI 구간

MACD > Signal(상승 추세)이면 강한 RSI가 긍정 신호, 하락/중립이면 과매도 반등 구간이 최적.

상승 추세 (MACD > Signal):

RSI 구간	점수	해석
55–75	+30	핵심 상승 구간 (최적)
75 초과	+24	강한 과매수 — 모멘텀 강함
45–55	+20	추세 초입
35–45	+12	추세 약화 경고
35 미만	+6	신뢰 저하

하락/중립 추세 (MACD ≤ Signal):

RSI 구간	점수	해석
35–50	+30	과매도 탈출, 반등 준비 (최적)
30–35	+24	깊은 과매도, 반등 기대
30 미만	+18	심한 과매도, 단기 반등 가능
50–65	+14	중립~완만한 상승
65–75	+8	하락 추세인데 RSI 높음
75 초과	+4	과열 경고

BB 폭 보정: 밴드가 매우 좁으면(bb_width < 3%) −3pt, 확장되면(bb_width > 12%) +2pt (최대 30pt 캡).

③ BB 위치 + CMF + 거래량 (최대 30점)

BB 위치 (최대 20점) — MACD 방향에 따라 최적 구간 이동:

BB 위치	상승추세 (MACD↑)	하락/중립 (MACD↓)
0.4–0.75	+20 (추세 추종 최적)	+11
0.2–0.5	+11	+20 (반등 매수 최적)
0.75–0.9	+14	+6
0.5–0.7	—	+14
0.1–0.2	—	+10
0.9 초과	+6	+2 (밴드 이탈)
0.2 미만	+2 (하단 이탈)	—
0.1 미만	—	+2 (밴드 이탈)

CMF 자금흐름 (최대 5점): CMF > 0.05 → +5pt / CMF > 0 → +3pt

거래량 확인 (최대 5점): 당일 거래량 ≥ 20일 평균의 1.5배 → +5pt

ML Score (머신러닝 예측)

10거래일 후 수익률 상위 25% 확률의 캘리브레이션 점수 (0~100). 이진 분류(top 25% = 1 / bottom 25% = 0)의 예측 확률을 test_proba 분포 기준 백분위로 균등화.

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

News Sentiment Score (뉴스 감성)

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

Value Score (가치주 스크리닝)

value_score (0~100) — 펀더멘털 항목별 가중 점수 합산:

항목	배점	최고점 기준
PER	25pt	PER ≤ 5 → 25점, ≤ 10 → 20점, ≤ 15 → 15점, ≤ 25 → 10점
PBR	20pt	PBR ≤ 0.5 → 20점, ≤ 1 → 16점, ≤ 2 → 10점, ≤ 3 → 5점
ROE	20pt	ROE ≥ 20% → 20점, ≥ 15% → 16점, ≥ 10% → 12점, ≥ 5% → 6점
부채비율	20pt	≤ 30% → 20점, ≤ 70% → 16점, ≤ 100% → 12점, ≤ 150% → 8점, ≤ 200% → 4점
영업이익YoY	15pt	≥ 30% → 15점, ≥ 15% → 12점, ≥ 0% → 9점, ≥ -20% → 4점

데이터 미수신 항목은 전체 가용 점수 기준으로 비율 정규화 (데이터가 적을수록 불리하지 않도록).

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

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

Quality Score (우량주 스크리닝)

quality_score (0~100) — 수익성·성장성·재무건전성 항목별 가중 점수 합산:

항목	배점	최고점 기준
ROE	30pt	ROE ≥ 25% → 30점, ≥ 20% → 25점, ≥ 15% → 18점, ≥ 12% → 12점
영업이익률	25pt	≥ 25% → 25점, ≥ 20% → 20점, ≥ 15% → 14점, ≥ 10% → 8점
영업이익YoY	20pt	≥ 20% → 20점, ≥ 10% → 16점, ≥ 0% → 10점, ≥ -10% → 4점
부채비율	15pt	≤ 30% → 15점, ≤ 50% → 12점, ≤ 70% → 8점, ≤ 100% → 4점
배당수익률	10pt	≥ 3% → 10점, ≥ 2% → 7점, ≥ 1% → 4점, ≥ 0% → 2점

ROE 지속성 확인: 2개년 평균 ROE를 계산해 일시적 고ROE를 걸러냅니다.

quality_score	해석
70–100	최우량 — 장기 핵심 보유 후보
50–69	양호 — 장기 투자 검토 대상
30–49	보통 — 일부 지표 취약, 추가 검증 필요
0–29	미달 — 필터 기준 재검토 권장

---

💡 실전 투자 활용 가이드

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

0. 투자 시계 (Investment Horizon) — 단기, 1~2주

본 시스템의 모든 컴포넌트는 단기(5~15거래일) 트레이딩 관점에 최적화되어 있습니다.

컴포넌트	시간 지평	근거
ML 모델 (ml_score)	10거래일 (≈ 2주)	타깃 = 10거래일 후 수익률 상위 25%
기술적 지표 (tech_score)	5~60일	SMA5·20·MACD(12/26)·RSI(14)·BB(20) 중심
후보군 선정 (버킷)	당일	당일 거래량 상위·등락률 기준 분류
뉴스 감성 (sentiment)	당일~수일	최신순 뉴스, 7일 전 가중치 0.09로 급감
가치주 스크리닝	3~6개월	DART 연간 재무제표 기반 펀더멘털 (PER·PBR·ROE·부채비율) + F-Score
우량주 스크리닝	6개월+	DART 기반 ROE 2개년·영업이익률·YoY성장·부채비율 — 장기 수익성 우량 기업

1~3개월 이상 보유 시 AI 추천(단기) 신호는 의미를 잃습니다. 중기 보유 목적이라면 AI 추천 대신 가치주 스크리닝(가치주 추천 탭) 을 활용하세요. 추천 후 1~2주 내 진입·관찰·청산 사이클을 전제로 설계되었습니다. SMA120(6개월) 같은 장기 지표는 계산되지만 점수·ML 피처에 미반영됩니다.

1. 신호 해석 기준

강력 매수 후보 (모든 조건 충족 시)
  ✅ 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 데드크로스 동시 발생

2. 단계별 활용 방법

Step 1 — 스크리닝 (매일 자동)

• 텔레그램 알림으로 오늘의 추천 9종목 확인
• 종합 점수 상위 2–3종목을 후보로 선정

Step 2 — 지속성 확인

• AI Recommendations → 📅 추천 지속성 히트맵에서 연속 추천 일수 확인
• 2일+ 연속 추천 종목(🔥 배지)은 신호 신뢰도가 높음

Step 3 — 심층 검증 (수동)

• Dashboard 또는 AI Recommendations에서 상세 리포트 확인
• 강점/약점, 뉴스 근거 및 원문 링크, 목표가 근거 직접 검토
• Backtest Viewer에서 해당 종목의 전략별 과거 성과 확인

[중기 보유 목적] Step 2.5 — 가치주 스크리닝 활용

• 가치주 추천 탭에서 PER·PBR·ROE·부채비율 필터를 조정해 후보군 설정
• value_score + F-Score 복합 정렬 결과 상위 종목을 중기 매수 후보로 검토
• F-Score 6점 이상 + value_score 60 이상 종목은 펀더멘털 안정성이 높음
• 가치주 신호는 단기 AI 추천과 독립적 — 두 신호가 일치하는 종목 우선 검토

[장기 보유 목적] Step 2.6 — 우량주 스크리닝 활용

• 우량주 추천 탭에서 ROE·영업이익률·부채비율 필터를 조정해 후보군 설정
• quality_score 상위 종목은 ROE 2개년 평균·영업이익률·YoY성장·재무건전성이 복합적으로 우수
• ROE ≥ 15% + 영업이익률 ≥ 15% + quality_score 70+ 종목은 장기 핵심 보유 후보
• 우량주 신호는 가치주·단기 AI 추천과 독립적 — 모든 신호가 겹치는 종목을 최우선 검토

Step 4 — 최종 판단 기준

AI 추천만으로 매수 ❌
AI 추천 + 아래 조건 중 2개 이상 충족 시 매수 검토 ✅
  - 최근 5일 거래량이 20일 평균 대비 150% 이상
  - 52주 저점 대비 -20% 이내 (저점 매수 구간)
  - 섹터 전반적 상승 분위기
  - 뉴스 감성 Bullish 이상
  - 추천 지속성 히트맵에서 2일+ 연속 추천

3. 리스크 관리

원칙	설명
분산 투자	추천 9종목 중 동일 섹터에 몰리지 않도록 1–2종목만 선택
손절 기준	매수가 대비 7–8% 하락 시 손절 고려 (시스템은 손절선 미제공)
목표가 활용	목표가는 단기 참고값이며 보장 수치가 아님. 실현 후 일부 익절 전략 권장
비중 관리	단일 종목에 총 자산의 10% 이상 집중 투자 지양
재검증	매수 후 3–5일 내 시스템 재분석으로 의견 변화 모니터링

4. 점수별 권장 포지션 크기

종합 점수 75 이상 + BUY → 일반 비중 (예: 5–7%)
종합 점수 65–74 + BUY   → 소규모 진입 (예: 3–5%)
종합 점수 55–64 + BUY   → 관망 또는 최소 비중 (예: 1–2%)
종합 점수 55 미만        → 매수 보류

5. 활용 시 주의사항

• 단기(1~2주) 신호 — ML 타깃이 10거래일이므로 수개월 보유 목적의 종목 선택에는 부적합
• 뉴스 감성은 당일 헤드라인 기반 — 호재성 기사 뒤 실적 부진 가능
• ML 모델 미탑재 시 tech_score 대체 — 로그 메시지로 확인 가능
• ML 점수는 절대 수익률이 아닌 상대강도 순위 — 시장 전체가 하락장이면 점수 높아도 손실 가능
• 자동화는 평일 16:30 KST 실행 — 당일 주가 반영, 다음날 매매 판단에 활용
• 빠른 시장 변동 반영 불가 — 급등락 당일은 직접 현재 가격 확인 필수

---

⚙️ 설치 및 실행

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

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

사전 요구 사항 — 시스템 라이브러리

# Ubuntu / Debian
sudo apt-get install -y libomp-dev

# macOS
brew install libomp

# Windows — 별도 설치 불필요

pip로 설치

pip install koreanstocks

가상 환경(venv, conda) 내에서 설치할 것을 권장합니다. 시스템 Python에 직접 설치하면 다른 패키지와 의존성이 충돌할 수 있습니다.

pipx로 설치 (CLI 툴 격리 권장)

pipx는 CLI 도구를 독립된 가상 환경에 설치하여 시스템 Python을 오염시키지 않습니다.

# pipx 설치 (미설치 시)
pip install pipx
pipx ensurepath          # PATH 자동 등록 (셸 재시작 필요)

# koreanstocks 설치
pipx install koreanstocks

항목	pip	pipx
설치 환경	현재 활성 Python 환경	자동 생성된 독립 venv
시스템 Python 오염	가능	없음
CLI 자동 PATH 등록	환경에 따라 다름	항상 자동 등록
패키지 업그레이드	pip install -U koreanstocks	pipx upgrade koreanstocks
패키지 제거	pip uninstall koreanstocks	pipx uninstall koreanstocks

설치 후 빠른 시작

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

.env·DB·ML 모델은 ~/.koreanstocks/에 저장됩니다. 매일 장 마감 후 koreanstocks sync --force로 최신 추천 결과를 받아오세요.

---

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

GitHub Actions 없이 로컬에서 직접 분석을 실행하거나 코드를 수정할 때 사용합니다.

1. 저장소 클론

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

2. Python 환경 설정 (Python 3.11 ~ 3.13)

conda create -n stocks_env python=3.11   # 또는 3.12, 3.13
conda activate stocks_env

3. 패키지 설치

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

pip install -e .    # editable 설치 — 코드 수정이 즉시 반영됨

---

API 키 설정 — koreanstocks init

방법 A·B 공통. 설치 후 반드시 실행해야 합니다.

대화형 설정 (권장)

koreanstocks init

실행 시 아래와 같이 단계별로 입력을 요청합니다 (Enter = 나중에 입력):

생성 위치: ~/.koreanstocks/.env

[필수] API 키를 입력하세요 (Enter = 나중에 입력):

  OpenAI API Key [https://platform.openai.com/api-keys]: sk-proj-...
  Naver Client ID [https://developers.naver.com/apps]: abc123
  Naver Client Secret: xyz789
  Telegram Bot Token [@BotFather → /newbot]: 123456:ABC-...
  Telegram Chat ID [getUpdates 로 확인]: -1001234567890

[선택] 미입력 시 건너뜁니다:

  DART API Key (선택) [https://opendart.fss.or.kr]:

.env 파일을 생성했습니다.
  경로: ~/.koreanstocks/.env

다음 단계:
  koreanstocks sync    # 최신 분석 DB 다운로드
  koreanstocks serve   # 웹 대시보드 실행

비대화형 설정 (CI·자동화용)

koreanstocks init --non-interactive   # 빈 템플릿 생성 후 직접 편집

.env 파일 경로 확인 및 편집

koreanstocks home                        # 홈 디렉토리 경로 출력
cd $(koreanstocks home)                  # 홈 디렉토리로 이동
${EDITOR:-nano} $(koreanstocks home)/.env  # .env 직접 편집

koreanstocks home --open                 # 파일 탐색기로 열기
koreanstocks home --setup                # 셸 alias 등록 안내 출력

koreanstocks home --setup 출력 예시 (.bashrc / .zshrc에 추가):

alias kshome='cd "$(koreanstocks home)"'          # 홈 디렉토리로 이동
alias ksenv='${EDITOR:-nano} "$(koreanstocks home)/.env"'  # .env 편집

.env 생성 위치는 설치 방법에 따라 자동 결정됩니다:

설치 방법	.env 저장 경로
pip install koreanstocks / pipx install koreanstocks	~/.koreanstocks/.env
pip install -e . (editable, 방법 B)	(프로젝트 루트)/.env

API 키 발급 가이드

① OpenAI API Key (필수) — GPT-4o-mini 뉴스 감성 분석·AI 의견 생성

1. platform.openai.com 로그인
2. 우측 상단 프로필 → API keys → Create new secret key
3. 키 이름 입력 후 생성 — sk-proj-... 형식의 키를 복사
4. ⚠️ 키는 생성 직후에만 전체 확인 가능하므로 즉시 복사하세요.

② Naver 검색 API (필수) — 종목명 기반 최신 뉴스 수집

1. developers.naver.com/apps 로그인
2. Application 등록 클릭
3. 애플리케이션 이름 입력 (예: KoreanStocks)
4. 사용 API → 검색 선택
5. 등록 후 Client ID와 Client Secret 복사

③ Telegram Bot Token & Chat ID (필수) — 일일 추천 리포트 수신

Bot Token 발급:
1. 텔레그램에서 @BotFather 검색 후 시작
2. /newbot 입력 → 봇 이름 및 사용자명 입력
3. 발급된 토큰 복사 (예: 123456789:ABC-defGHI...)

Chat ID 확인:
1. 발급한 봇에게 임의 메시지 전송
2. 브라우저에서 아래 URL 접속 (TOKEN을 실제 토큰으로 교체):
   https://api.telegram.org/bot<TOKEN>/getUpdates
3. 응답 JSON에서 "chat" → "id" 값 복사
   (그룹 채팅의 경우 음수 값: 예 -1001234567890)

④ DART API Key (선택) — 금융감독원 공시 수집으로 감성 분석 품질 향상

1. opendart.fss.or.kr 회원가입
2. 개발자 센터 → API 신청 (무료, 즉시 발급)
3. 발급된 API 키 복사
4. 미설정 시에도 뉴스만으로 감성 분석이 동작합니다.

환경 변수 전체 목록

# ── 필수 ──────────────────────────────────────────────────────
OPENAI_API_KEY=sk-proj-...
NAVER_CLIENT_ID=abc123
NAVER_CLIENT_SECRET=xyz789
TELEGRAM_BOT_TOKEN=123456789: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 (무료)	☑️
KOREANSTOCKS_GITHUB_DB_URL	저장소 fork 시 koreanstocks sync 대상 URL 재정의	☑️

---

ML 모델 학습 (방법 B / 최초 1회)

koreanstocks train
# 또는
python train_models.py

추천 성과 추적

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

가치주 스크리닝

koreanstocks value                            # 기본 조건으로 가치주 스크리닝 (상위 10종목)
koreanstocks value --limit 20                 # 결과 20종목 출력
koreanstocks value --per-max 15 --roe-min 10  # PER ≤ 15, ROE ≥ 10% 조건 적용
koreanstocks value --f-score-min 6            # Piotroski F-Score 6점 이상만 포함
koreanstocks value --candidate-limit 300      # 탐색 범위 300종목으로 확대 (소요 시간 증가)

DART API Key(DART_API_KEY)가 .env에 설정된 경우 펀더멘털 수집 정확도가 향상됩니다. 당일 동일 조건 재실행 시 인메모리 캐시로 즉시 반환됩니다.

우량주 스크리닝

koreanstocks quality                                  # 기본 조건으로 우량주 스크리닝 (상위 20종목)
koreanstocks quality --limit 30                       # 결과 30종목 출력
koreanstocks quality --roe-min 15 --margin-min 15     # ROE ≥ 15%, 영업이익률 ≥ 15% 조건 적용
koreanstocks quality --debt-max 80                    # 부채비율 ≤ 80% 조건 적용
koreanstocks quality --market KOSPI --candidate-limit 200  # KOSPI 200종목 탐색

우량주는 장기(6개월+) 보유 관점 — 단기 AI 추천과 목적이 다릅니다. 당일 동일 조건 재실행 시 인메모리 캐시로 즉시 반환됩니다.

앱 실행

koreanstocks serve

브라우저가 자동으로 열리며 http://localhost:8000/dashboard 접속

• / — Reveal.js 일일 브리핑 슬라이드
• /dashboard — 인터랙티브 대시보드 (8탭)
• /docs — FastAPI Swagger UI

권장 브라우저: Chrome / Firefox (최신 버전) 대시보드의 모든 기능은 Chrome 및 Firefox 최신 버전에서 정상 동작합니다.

---

🤖 자동화 설정 (GitHub Actions)

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

설정 방법:

1. 저장소를 GitHub에 푸시
2. Settings > Secrets and variables > Actions에서 아래 5개 Secret 등록

OPENAI_API_KEY
TELEGRAM_BOT_TOKEN
TELEGRAM_CHAT_ID
NAVER_CLIENT_ID      (없으면 뉴스 감성 분석 스킵)
NAVER_CLIENT_SECRET

3. Actions 탭에서 워크플로우 활성화 확인
4. 수동 실행: Actions > Daily Stock Analysis > Run workflow

자동화 흐름

flowchart TD
    TRIGGER["⏰ 16:30 KST<br/>평일 자동 실행<br/>(또는 수동 workflow_dispatch)"]
    TRIGGER --> TRADING{"한국 증시<br/>거래일?"}

    TRADING -- 휴장 --> SKIP["📅 텔레그램 휴장일 알림"]

    TRADING -- 거래일 --> OUTCOME["지난 추천 성과 기록<br/>5·10·20거래일 후 수익률 집계<br/>→ 텔레그램 성과 리포트"]
    OUTCOME --> STOCKLIST["KOSPI + KOSDAQ<br/>전체 종목 리스트 갱신"]
    STOCKLIST --> BUCKETS["버킷 기반 후보군 선정<br/>거래량 상위 / 상승 모멘텀 / 반등 후보"]
    BUCKETS --> ANALYSIS["심층 분석 (병렬)<br/>기술 + ML + 뉴스 + GPT"]
    ANALYSIS --> SELECT["종합 점수 상위 9종목 선정<br/>버킷 쿼터 + 섹터 다양성"]
    SELECT --> SAVE[("SQLite DB<br/>날짜별 저장")]
    SAVE --> ARTIFACT["GitHub Artifact 백업<br/>(90일 보존)"]
    SAVE --> COMMIT["저장소에 DB<br/>커밋·푸시"]
    COMMIT --> NOTIFY["📱 텔레그램<br/>추천 리포트 발송"]

    COMMIT --> SYNC1["git clone 환경<br/>git pull"]
    COMMIT --> SYNC2["PyPI 설치 환경<br/>koreanstocks sync --force"]

---

📱 메뉴 구성

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

탭	URL	주요 기능
Dashboard	/dashboard	시장 지수, Portfolio 요약, 날짜별 AI 추천 리포트, 추천 지속성 히트맵
Watchlist	/dashboard#watchlist	관심 종목 등록/삭제, 실시간 심층 분석, 분석 이력 타임라인
AI 추천	/dashboard#recommendations	테마·시장별 추천 생성, 날짜 선택 히스토리, 추천 지속성 히트맵, 📊 추천 성과 추적 (5·10·20거래일 승률·목표가 달성률)
가치주 추천	/dashboard#value	PER·PBR·ROE·부채비율·F-Score 필터 기반 중기(3~6개월) 가치주 스크리닝, 초보자 지표 가이드, 탐색 범위(100/200/300종목) 설정
우량주 추천	/dashboard#quality	ROE·영업이익률·YoY성장·부채비율·PBR 필터 기반 장기(6개월+) 우량주 스크리닝, quality_score 정렬, ROE 2개년 지속성 확인
백테스트	/dashboard#backtest	RSI/MACD/COMPOSITE 전략 시뮬레이션, B&H 비교 차트, 초보자 해석 가이드
모델 신뢰도	/dashboard#model	ML 모델 AUC·과적합 갭·드리프트 등급·피처 중요도·재학습 권장 여부 확인
설정	/dashboard#settings	수동 자동화 실행, 텔레그램 설정 상태 확인
브리핑	/	Reveal.js 일일 슬라이드 (종목별 점수·뉴스·AI 의견)
API 문서	/docs	FastAPI Swagger UI

---

📝 변경 이력

v0.4.1 (2026-03-10) — 우량주 스크리너 추가 · ML 피처 개선 · 대시보드 히트맵 개선

• ✨ 우량주 추천 탭 신설 (대시보드 5번째 탭) — ROE·영업이익률·YoY성장·부채비율·PBR 필터 + 우량점수 정렬
• ✨ koreanstocks quality CLI 명령어 신설 — 우량주 스크리닝 터미널 직접 실행
• ✨ GET /api/quality_stocks 엔드포인트 신설 — quality_score 내림차순 정렬
• ✨ 추천 지속성 히트맵 개선 — 연속 추천(🔥)과 비연속 반복 추천(🔄/📌) 구분 배지
• 🔧 ML 피처 3개 추가: obv_trend, rsi, cci_pct (17→20개), vix_change_5d 제거
• 🔧 ML Walk-Forward CV VAL_STEP 20→10, Purging 10→20거래일 강화
• 🔧 앙상블 Softmax 가중치 정규화, Classifier·Ranker 분리 집계
• 📝 docs/QUALITY_SCREENING.md 신설 — 우량주 스크리닝 시스템 전체 기술 문서

v0.4.0 (2026-03-06) — 가치주 스크리닝 기능 추가

• ✨ 가치주 추천 탭 신설 (대시보드 7번째 탭) — PER·PBR·ROE·부채비율·F-Score 필터 + 가치점수 정렬, 초보자용 지표 가이드
• ✨ koreanstocks value CLI 명령어 신설 — 가치주 스크리닝 터미널 직접 실행
• ✨ GET /api/value_stocks 엔드포인트 신설 — Piotroski F-Score + value_score 복합 정렬
• 🐛 fundamental_provider.py DART 재작성 — ROE·부채비율 대차대조표에서 직접 계산 (wisereport AJAX 불가 해소)
• 🔧 provider.py get_value_candidates() 신설 — 시가총액 기준 PER/ROE 사전 필터 후보군 병렬 수집
• 🔧 value_screener.py 당일 인메모리 캐시 — 동일 조건 재실행 즉시 반환 (1~2분 → 0초)
• 🔧 대시보드 탐색 범위 드롭다운(100/200/300종목) — candidate_limit 직접 노출, 의미 있는 UX
• 📝 docs/VALUE_SCREENING.md 신설 — 가치주 스크리닝 시스템 전체 기술 문서 (후보군·DART·필터·F-Score·value_score·캐시·API·CLI)

v0.3.x (2026-02-28 ~ 2026-03-05) — 추천 성과 추적 · 버킷 UI · pykrx 제거 · 5-모델 앙상블 · 기술 부채 해소

• ✨ 추천 성과 추적 기능 (5·10·20거래일 후 실적 검증, outcomes CLI 및 Web UI)
• ✨ 추천 버킷(거래량 상위/상승 모멘텀/반등 후보) 배지 UI — 대시보드·슬라이드 동시 반영
• ✨ 기본 추천 종목 수 5 → 9개 상향, 분석 설정 종목 수 자동 선택 로직
• ✨ LightGBM · CatBoost 모델 추가 → 5-모델 앙상블 (RF · GB · LGB · CB · XGBRanker)
• ✨ XGBoost 이진 분류 → XGBRanker (rank:ndcg) 교체 — 크로스섹셔널 순위 직접 최적화
• ✨ /api/version 엔드포인트 신설 — 대시보드가 API로 버전 동적 조회
• 🐛 /api/market NaN → JSON 직렬화 오류 수정
• 🐛 prediction_model.py mom_accel 공식 수정 — 학습/추론 불일치 해소
• 🐛 CLI recommend 명령 --limit 인수 누락 버그 수정
• 🔧 pykrx 완전 제거 → FinanceDataReader + KIND API (KRX 정책 변경 대응)
• 🔧 버전 단일 소스 (__init__.py) 구조 확립, 버킷 상수 core/constants.py 통합
• 🔧 atr_ratio → rolling 60일 percentile 변환, 피처 교체 (bb_position·mfi·low_52w_ratio)
• 🔧 뉴스 캐시 TTL 1시간, 감성 분석 퀀트 애널리스트 프롬프트 추가

---

⚠️ 면책 조항

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

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

---

📄 라이선스

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

---

(C) 2026. All rights reserved.