lightgbm

.gemini/checkpoint-final.md

@@ -1,21 +1,20 @@
-# fumen-analyze 최종 진행 리포트 (Final)
+# fumen-analyze 프로젝트 상태 보고 (Current)
 
-## 1. 모델 성능 요약
-- **최종 MAE**: **0.1758**
-- **모델 유형**: `GradientBoostingRegressor` (Warm Start + Precision Tuning)
-- **최종 Estimators**: 1,600개
-- **성과**: 30개 이상의 피처를 기반으로 채보의 미세한 난이도 차이를 성공적으로 학습. 이상치(에러 > 1.0)를 배제한 정밀 튜닝으로 안정성 확보.
+## 1. 모델 아키텍처 전환
+- **이전**: `GradientBoostingRegressor` (scikit-learn)
+- **현재**: `XGBRegressor` (XGBoost)
+- **변경 사유**: 대규모 데이터셋에 대한 학습 속도 향상 및 하이퍼파라미터 튜닝의 유연성 확보.
 
-## 2. 핵심 피처 가중치 (추정)
-- **밀도**: Global NPS, Peak NPS (1s/2s)
-- **리듬**: 엇박 비율(Triplets), 리듬 표준편차, 가속도
-- **패턴**: 손 배치 전환(Hand-switching), 3노트 단위 패턴 복잡도
-- **기믹**: SV/BPM 변화 빈도 및 변동성
+## 2. 성능 지표 (목표치)
+- **목표 MAE**: **0.15 이하** (현재 약 0.17~0.18 추정)
+- **허용 오차 범위**: ±0.1 (상수 단위 기준)
+- **성과**: 리듬 복잡도 및 순간 밀도 피처를 도입하여 10성급 고난이도 채보 간의 미세한 서열(상수 11.0~12.0)을 유의미하게 구분 중.
 
-## 3. 사용 안내
-- **학습 업데이트**: `./run_pipeline.sh` (현재 정밀 튜닝 모드 설정됨)
-- **상수 예측**: `./run_predict.sh <TJA_Path> [diff]`
-- **문서 참조**: `GUIDE.md`
+## 3. 핵심 업데이트 사항
+- **BPM/Scroll 변화 감지**: `#BPMCHANGE` 뿐만 아니라 `#SCROLL` 변화를 결합한 시각적 속도 변화 피처 추가.
+- **색상 복잡도 가중치**: 노트 간 간격이 좁을수록 더 높은 난이도 가중치를 부여하는 $1/\Delta t^2$ 로직 적용.
+- **지속 학습 지원**: `CONTINUE_TRAINING` 옵션을 통해 기존 모델에 추가 데이터를 점진적으로 학습 가능.
 
-## 4. 최종 결론
-현재 모델은 10성급 고난이도 곡들 사이의 미세한 '상수' 서열을 0.1~0.2 오차 범위 내에서 예측할 수 있는 수준에 도달했습니다. 추가 데이터 확보 시 0.1 미만으로의 진입이 충분히 가능합니다.
+## 4. 향후 과제
+- `rhythm_complexity` 로직의 정교화 (비정형 박자 감지 강화).
+- `measure.csv` 데이터셋 확충을 통한 과적합 방지 및 일반화 성능 향상.

.gemini/difficulty-factors.md

@@ -1,28 +1,23 @@
-# TJA 난이도 산정 핵심 요소 (Technical Factors)
+# TJA 난이도 산정 피처 (Features)
 
-학습 모델(DifficultyNet)에 입력되는 8가지 핵심 지표입니다. (spec.md 업데이트 반영)
+`preprocess/featurize.ts`에서 추출되는 8가지 핵심 피처입니다.
 
-## 1. 물리적 밀도
-- **density_avg**: 평균 노트 밀도 (총 노트 수 / 곡 길이)
-- **density_peak**: 1초당 최대 밀도 (가장 촘촘한 구간의 노트 수)
+## 1. 양적 지표
+- **note_count**: 총 노트 수. 곡의 길이에 따른 절대적인 노트 양.
 
-## 2. BPM 및 속도 변화
-- **bpm_avg**: 곡의 평균 BPM
-- **bpm_var**: BPM 변화율 (BPM 변속의 다양성)
+## 2. 밀도 지표
+- **density_avg**: 평균 NPS. `(총 노트 수 / 곡의 총 소요 시간) * 1000`.
+- **density_peak**: 순간 최대 밀도. 임의의 노트를 기준으로 1초 이내에 포함된 최대 노트 수.
 
-## 3. 구조적 특징
-- **note_count**: 총 노트 수
-- **long_note_duration**: 전체 대비 긴 노트(지속형) 점유율
+## 3. 속도 변화 지표
+- **bpm_avg**: 노트별 BPM의 단순 산술 평균.
+- **bpm_change**: BPM 변동 횟수. 인접한 두 노트 간 BPM 차이가 1.5 이상일 때 카운트.
+- **scroll_change**: 시각적 속도(`BPM * Scroll`) 변동 횟수. 차이가 1.5 이상일 때 카운트.
 
-## 4. 패턴 및 연타
-- **complex_ratio**: 복합 패턴(큰 북/작은 북 혼합) 비율
-- **roll_count**: 연타(Roll) 노트의 총 개수
+## 4. 구조적 복잡도
+- **rhythm_complexity**: 리듬의 정규성. 인접한 노트 간 시간 간격의 비율이 2의 거듭제곱(1, 0.5, 2 등)에 가까운 횟수를 카운트.
+    - *참고: 현재 코드는 정규 리듬일 때 증가하며, 문서와 실제 로직의 방향성이 반대일 수 있음.*
+- **color_complexity**: 색상 배치 복잡도. 인접 노트의 색상(Don/Ka)이 바뀔 때, 그 간격의 제곱의 역수($1/\Delta t^2$)를 누적. 간격이 좁을수록 수치가 급격히 상승.
 
-## 계산 로직
-- **밀도 계열**: 노트 간 시간 간격(`delta`)의 역수(`1/delta`)로 순시 밀도를 계산하여 `avg`/`peak` 도출.
-- **BPM 계열**: `#BPM` 및 `#STOP` 명령을 기반으로 시간 축 전개 후 평균 및 표준편차(`var`) 계산.
-- **패턴 계열**: 슬라이딩 윈도우(4~8개 노트)에서 노트 타입 변화(`d↔k`) 횟수를 측정하여 비율 산정.
-- **연타 계열**: `#ROLL` 명령 및 입력 밀집 구간 카운트.
-
-## 중요 주의사항
-- 모든 Factor는 모델 학습 전 `StandardScaler` 또는 `RobustScaler`를 통해 반드시 이상치를 처리해야 합니다.
+## 주의사항
+- `color_complexity`는 수치의 범위가 매우 클 수 있으므로 학습 시 `StandardScaler`를 통한 정규화가 필수적입니다.

.gemini/notes.md

@@ -2,16 +2,20 @@
 
 ## Technical Stack
 - **Runtime**: [Bun](https://bun.sh/)
-- **Language**: TypeScript
-- **Library**: [tja](https://www.npmjs.com/package/tja) (TJA parser)
+- **Language**: TypeScript (Preprocessing), Python (Machine Learning)
+- **ML Library**: [XGBoost](https://xgboost.readthedocs.io/), [scikit-learn](https://scikit-learn.org/)
+- **TJA Parser**: [tja-parser](https://www.npmjs.com/package/tja-parser)
 
-## Key Documents
-- `.gemini/tja-spec.md`: Rigorous TJA format specification.
-- `tja-format.mediawiki`: Original source document.
-- `measure.csv`: Dataset with columns `상수`, `songno`, `diff`.
+## Key Directories
+- `preprocess/`: TJA 파싱 및 피처 추출 로직 (TypeScript)
+- `script/`: 전처리, 학습 제어 스크립트
+- `train/`: XGBoost 학습 엔진 (Python)
+- `predict/`: 추론 엔진 (Python)
+- `datas/tja/`: 원본 TJA 데이터셋
+- `datas/measure.csv`: 정답지 (상수 데이터)
+- `test/`: 학습 결과물 (model.pkl, scaler.pkl, features.json)
 
-## Models (model/)
-- `constant_predictor.py`: DNN 기반 상수 예측 모델.
-
-## Library Usage (tja)
-...
+## Data Flow
+1. `datas/tja/*.tja` → `script/preprocess.ts` → `test/features.json`
+2. `test/features.json` + `datas/measure.csv` → `train/train_xgboost.py` → `test/model.pkl`
+3. `test/model.pkl` + `test/features.json` → `predict/predict_xgboost.py` → Result

.gemini/pipeline-design.md

@@ -1,13 +1,35 @@
-# 파이프라인 실행 규칙
+# 파이프라인 실행 가이드
 
-모든 경로는 실행 시점에 인자로 지정하여 관리합니다.
+모든 실행은 프로젝트 루트 디렉토리에서 수행합니다.
 
-## 1. 학습 파이프라인 (`run_train.sh`)
-- **인자 1 (TJA_DIR)**: 학습용 TJA 채보가 저장된 폴더 (예: `sample/training`)
-- **인자 2 (MODEL_PATH)**: 모델이 저장될 경로 (예: `output/model/v2_constant`)
-- **인자 3 (DATASET_DIR)**: 데이터셋이 저장될 폴더 (예: `output/dataset`)
+## 1. 전처리 (Feature Extraction)
+TJA 파일들로부터 피처를 추출하여 `features.json`을 생성합니다.
+```bash
+bun run script/preprocess.ts --workingDir ./test --dataDir ./datas
+```
+- **--workingDir**: 결과물(`features.json`)이 저장될 폴더.
+- **--dataDir**: 원본 데이터(`tja/` 폴더)가 위치한 폴더.
 
-## 2. 예측 파이프라인 (`run_predict.sh`)
-- **인자 1 (MODEL_PATH)**: 추론에 사용할 모델 경로
-- **인자 2 (TJA_DIR)**: 예측할 TJA 채보가 모여있는 폴더
-- **인자 3 (OUTPUT_DIR)**: 결과가 저장될 폴더
+## 2. 모델 학습 (Training)
+추출된 피처와 상수 데이터를 사용하여 XGBoost 모델을 학습시킵니다.
+```bash
+python3 train/train_xgboost.py \
+  --workingDir ./test \
+  --dataDir ./datas \
+  --trainSize 1000 \
+  --validSize 200
+```
+- **--trainSize / --validSize**: 학습 및 검증에 사용할 데이터 수.
+
+## 3. 난이도 예측 (Inference)
+특정 곡 번호(`songno`)에 대한 난이도 상수를 예측합니다.
+```bash
+python3 predict/predict_xgboost.py --workingDir ./test --songno 1000
+```
+- **--songno**: 예측할 곡의 번호 (파일명 기준).
+
+## 주요 산출물 (in `workingDir`)
+- `features.json`: 추출된 피처 데이터셋.
+- `model.pkl`: 학습된 XGBoost 모델 파일.
+- `scaler.pkl`: 피처 정규화를 위한 Scaler 객체.
+- `features.txt`: 학습에 사용된 피처 이름 목록.