### SightRay 핵심 디렉토리 구조 설명 (MVP 기준)

---

## 프로젝트 루트 구조 예시

```
sightray/
├── data_collection_engine/       # 데이터 수집 및 CDS 생성 담당
│   ├── engine.py                 # 수집 + 정제 + 저장 실행 흐름
│   └── modules/
│       ├── fetchers/
│       │   └── polygon.py        # Polygon API 연동
│       └── preprocessors.py      # CDS 정제 및 전처리
│
└── data_analysis_engine/        # CDS를 기반으로 주가 예측 담당
│   ├── dataset_builder.py       # CDS → 학습용 데이터로 변환
│   ├── models/
│   │   └── xgboost_model.py      # XGBoost 모델 정의, 학습, 예측
│   ├── analyzer.py              # 여러 종목 예측, 상위 선정
│   ├── predict.py               # 전체 분석 흐름 실행 CLI
│
├── risk_manage_engine/     # 예측된 종목의 리스크를 정량적으로 평가
│   ├── calculators/               # 리스크 지표 계산 모듈 집합
│   │   ├── var.py                 # Value at Risk 계산
│   │   ├── svar.py                # Stressed Value at Risk 계산
│   │   ├── monte_carlo.py         # Monte Carlo 시뮬레이션
│   │   └── atr.py                 # ATR 지표 계산
│   ├── risk_calculator.py         # 모든 지표를 불러와 계산하는 통합 인터페이스
│   ├── risk_scorer.py             # risk_score 산출 (0~100)
│   ├── filter.py                  # 투자 적격 종목 필터링
│   └── evaluate.py                # 전체 리스크 평가 흐름 실행
│
├── strategy_engine/              # 리스크 필터링된 종목을 기반으로 실제 투자 전략 수립
│   ├── templates/                # 다양한 전략 유형 정의 (기본, 리스크 기반 등)
│   │   ├── basic_strategy.py         # TP/SL 기준의 기본 전략
│   │   ├── risk_adjusted_strategy.py # 리스크 점수 기반 투자 강도 조절 전략
│   ├── selector.py               # tradable 종목 중 전략 조건 부합 종목만 선택
│   ├── position_manager.py       # 진입/청산 시점 판단, 자금 배분 전략 실행
│   └── run_strategy.py           # 전략 엔진 실행 진입점

```

---

## 데이터 수집 엔진 (data_collection_engine)

### engine.py
- CDS 생성을 위한 메인 클래스 (`DataCollectionEngine`) 구현
- fetcher와 preprocessor를 조합하여 데이터 수집 → 정제 → CSV 저장

### modules/fetchers/polygon.py
- Polygon API에서 주식의 OHLCV 데이터를 요청하고 받아오는 로직 구현
- API 키는 `.env` 파일을 통해 안전하게 불러옴

### modules/preprocessors.py
- API로 받은 원본 데이터를 CDS 형식으로 정제
- 결측치 제거, 중복 제거, 컬럼명 정리, 정렬, 인덱스 리셋 등 포함

---

## 데이터 분석 엔진 (data_analysis_engine)

### dataset_builder.py
"""
파일 설명:
CDS (OHLCV) 데이터를 머신러닝 학습용 구조로 변환
- 입력: CDS CSV 파일 (DataFrame)
- 출력: XGBoost 학습용 피처 + 타깃 컬럼 포함 DataFrame
- 타깃: 다음날 종가가 오르면 1, 내리면 0
"""

### models/xgboost_model.py
"""
파일 설명:
XGBoost 모델 학습, 저장, 예측을 포함한 클래스 정의
- fit(): 학습
- predict(): 예측 결과 및 상위 종목 정렬 반환
- save_model(), load_model(): 모델 파일 저장 및 로드
"""

### analyzer.py
"""
파일 설명:
각 종목의 CDS를 불러와 XGBoost 예측 실행
- ROI, 상승 확률 등을 기반으로 상위 종목 필터링
"""

### predict.py
"""
파일 설명:
전체 분석 흐름을 실행하는 엔트리 포인트
- CLI 또는 스크립트로 사용
- analyzer.py를 통해 결과 생성 후 저장
"""

---

## 리스크 관리 엔진 (risk_manage_engine)

### calculators/
- var.py: Value at Risk 계산 로직
- svar.py: Stressed Value at Risk 계산 로직
- monte_carlo.py: Monte Carlo Simulation을 통한 리스크 추정
- atr.py: Average True Range 계산을 통한 변동성 측정

### risk_calculator.py
- 위의 리스크 지표 계산 모듈들을 통합 호출
- 분석 결과와 CDS를 입력받아 리스크 요소 계산

### risk_scorer.py
- 여러 리스크 지표를 통합하여 종합 risk_score(0~100)를 산출
- 사용자 정의 가중치를 적용한 리스크 평가 기준 가능

### filter.py
- risk_score 기반으로 투자 적격 종목을 필터링
- 기준치 이하 종목은 제외

### evaluate.py
- 분석 엔진에서 넘어온 종목에 대해 전체 리스크 평가 파이프라인 실행
- 결과를 CSV로 저장하거나 전략 엔진에 전달


---

## 전략 엔진 (strategy_engine)

### templates/
- basic_strategy.py: TP/SL 기준의 기본 전략 로직 정의
- risk_adjusted_strategy.py: 리스크 점수 기반으로 자금 배분 전략 설정

### selector.py
- tradable 종목 중 전략 조건에 부합하는 종목만 선별

### position_manager.py
- 각 종목에 대해 실제 매수 시점, 목표 수익률(TP), 손절 기준(SL) 설정
- 자산 배분 로직 포함

### run_strategy.py
- 전략 템플릿을 실행하고 결과를 저장하는 전략 엔진 실행 진입점