# Modern ML Pipeline

YAML 설정 기반의 머신러닝 파이프라인 CLI 도구입니다.

코드를 수정하지 않고 **YAML 설정 파일**만으로 모델 학습부터 API 서빙까지 처리합니다.

---

## 주요 특징

- **설정 기반 (Config-driven)**: YAML만으로 실험을 정의
- **자동 실험 추적**: MLflow와 연동되어 모든 실험 결과와 모델이 자동 저장
- **Data Leakage 방지**: Train/Validation/Test/Calibration 4단계 분할 자동 처리
- **즉시 서빙**: 학습 완료 후 명령어 한 줄로 REST API 서버 기동

---

## 빠른 시작

### 1. 설치

```bash
# pipx 설치 (독립 환경으로 의존성 충돌 방지)
pipx install modern-ml-pipeline

# extras 포함 설치
pipx install "modern-ml-pipeline[all]"           # 전체 기능
```

> pipx가 없다면: `brew install pipx && pipx ensurepath` (macOS) 또는 `pip install pipx && pipx ensurepath`

상세 설치 옵션은 [환경 설정 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/ENVIRONMENT_SETUP.md)를 참고하세요.

### 2. 프로젝트 생성

```bash
mmp init {{ project_name }}
```

생성되는 디렉토리 구조:
```
{{ project_name }}/
├── data/           # 학습/추론 데이터 파일
├── configs/        # 환경 설정 파일 (dev.yaml, prod.yaml 등)
├── recipes/        # 실험 레시피 파일
├── sql/            # SQL 쿼리 파일
├── docker-compose.yml
├── Dockerfile
├── pyproject.toml
├── README.md
└── .gitignore
```

### 3. 데이터 준비

학습에 사용할 데이터를 준비합니다. CSV 파일 또는 SQL 쿼리 파일을 사용할 수 있습니다.

**데이터 형식 요구사항**
- 각 행은 하나의 샘플을 나타냄
- entity_columns: 행을 식별하는 ID 컬럼 (학습에서 자동 제외)
- target_column: 예측 대상 컬럼
- 나머지 컬럼: 피처로 사용

Task별 상세 데이터 형식은 [Task 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/TASK_GUIDE.md)를 참고하세요.

### 4. 설정 파일 생성

#### Config 파일 (인프라 설정)

```bash
mmp get-config
```

MLflow, 스토리지, DB 연결 등 인프라 설정을 정의합니다.
상세 옵션은 [환경 설정 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/ENVIRONMENT_SETUP.md)를 참고하세요.

#### Recipe 파일 (실험 설정)

```bash
mmp get-recipe
```

Task, 모델, 전처리 등 실험 설정을 정의합니다. 생성된 Recipe 파일은 **반드시 직접 수정**이 필요합니다:

```yaml
# recipes/my-recipe.yaml
task_choice: classification

data:
  data_interface:
    entity_columns: [user_id]      # 사용자가 직접 지정
    target_column: is_fraud        # 사용자가 직접 지정
    feature_columns: null          # null이면 자동 선택

model:
  class_path: xgboost.XGBClassifier

preprocessing:
  numeric:
    strategy: standard             # 전처리 옵션 지정
  missing:
    strategy: mean
```

**필수 설정 항목**
- `entity_columns`: 데이터의 ID 컬럼명
- `target_column`: 예측 대상 컬럼명
- `model.class_path`: 사용할 모델

**참고 문서**
- [Task 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/TASK_GUIDE.md): Task별 data_interface 설정, 지원 모델
- [전처리 레퍼런스](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/PREPROCESSOR_REFERENCE.md): 전처리 옵션 (스케일링, 결측치 처리 등)
- [설정 스키마](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/SETTINGS_SCHEMA.md): Config/Recipe YAML 전체 스키마

### 5. 학습 실행

```bash
# CSV 파일로 학습
mmp train --config configs/dev.yaml --recipe recipes/my-recipe.yaml --data data/train.csv

# SQL 파일로 학습 (DB에서 직접 데이터 로드)
mmp train --config configs/dev.yaml --recipe recipes/my-recipe.yaml --data queries/train_data.sql
```

SQL 파일 사용 시 Jinja2 템플릿을 지원합니다:
```sql
-- queries/train_data.sql.j2
SELECT user_id, feature_1, feature_2, target
FROM my_table
WHERE created_at BETWEEN '{% raw %}{{ data_interval_start }}{% endraw %}' AND '{% raw %}{{ data_interval_end }}{% endraw %}'
```

```bash
# 템플릿 파라미터 전달
mmp train -c configs/dev.yaml -r recipes/model.yaml -d queries/train_data.sql.j2 \
  --params '{"data_interval_start": "2025-01-01", "data_interval_end": "2025-01-31"}'
```

**로그 파일**

학습 실행 시 상세 로그가 `logs/` 디렉토리에 자동 저장됩니다:
```
logs/dev_my-recipe_20250107_123456.log
```
- 파일명 형식: `{환경}_{레시피명}_{타임스탬프}.log`
- 30일 이상 된 로그는 자동 삭제됩니다

명령어 상세 옵션은 [CLI 레퍼런스](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/CLI_REFERENCE.md)를 참고하세요.

### 6. 추론

학습된 모델로 예측을 수행합니다. 배치 추론과 실시간 API 서빙 두 가지 방식을 지원합니다.

#### 배치 추론

대량의 데이터를 한 번에 예측할 때 사용합니다.

```bash
# CSV 파일로 배치 추론
mmp batch-inference --config configs/dev.yaml --run-id <mlflow_run_id> --data data/test.csv

# SQL 파일로 배치 추론
mmp batch-inference --config configs/dev.yaml --run-id <mlflow_run_id> --data queries/inference_data.sql
```

#### 실시간 API 서빙

REST API 서버를 기동하여 실시간 예측 요청을 처리합니다.

```bash
# API 서버 시작
mmp serve-api --config configs/dev.yaml --run-id <mlflow_run_id>
```

```bash
# API 호출 예시
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"feature_1": 0.5, "feature_2": 100}'
```

명령어 상세 옵션은 [CLI 레퍼런스](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/CLI_REFERENCE.md)를, API 상세 사용법은 [API 서빙 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/API_SERVING_GUIDE.md)를 참고하세요.

### 7. Docker 배포

프로젝트에 포함된 Docker 설정으로 컨테이너 배포가 가능합니다.

#### 학습 (로컬 artifact 저장)

```bash
# 로컬에서 학습 (mlruns/에 저장)
MLFLOW_TRACKING_URI=./mlruns mmp train \
  -c configs/dev.yaml -r recipes/model.yaml -d data/train.csv
```

#### Docker 이미지 빌드 및 배포

```bash
# API 서버 이미지 빌드
docker-compose build api

# API 서버 실행 (mlruns/ 볼륨 마운트)
MODEL_RUN_ID=<run_id> docker-compose up api
```

#### Docker Compose 사용법

```bash
# API 서버 실행
docker-compose up api

# 학습 실행 (on-demand)
docker-compose --profile training up training

# 배치 추론 실행 (on-demand)
MODEL_RUN_ID=<run_id> INFERENCE_DATA_PATH=data/test.csv \
  docker-compose --profile inference up inference

# MLflow UI 실행 (선택)
docker-compose --profile mlflow up mlflow
```

---

## 지원 Task

| Task | 설명 | 활용 사례 |
|------|------|----------|
| Classification | 범주형 분류 | 사기 탐지, 이탈 예측 |
| Regression | 연속값 예측 | 집값 예측, 매출 예측 |
| Timeseries | 시계열 예측 | 일별 매출, 트래픽 예측 |
| Clustering | 비지도 군집화 | 고객 세분화 |
| Causal | 인과 추론 | 프로모션 효과 분석 |

각 Task별 데이터 형식과 모델 설정은 [Task 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/TASK_GUIDE.md)를 참고하세요.

---

## 지원 모델

| 라이브러리 | 모델 |
|------------|------|
| Scikit-learn | RandomForest, LogisticRegression, KMeans 등 |
| XGBoost | XGBClassifier, XGBRegressor |
| LightGBM | LGBMClassifier, LGBMRegressor |
| CatBoost | CatBoostClassifier, CatBoostRegressor |
| PyTorch | LSTM, TabNet |
| statsmodels | ARIMA, ExponentialSmoothing |
| CausalML | T-Learner, S-Learner |

```bash
# 사용 가능한 모델 목록 조회
mmp list models

# 사용 가능한 메트릭 목록 조회
mmp list metrics
```

---

## 문서

### 사용자 문서

| 문서 | 설명 |
|------|------|
| [환경 설정 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/ENVIRONMENT_SETUP.md) | 설치, DB 연결, Cloud 설정 |
| [Task 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/TASK_GUIDE.md) | Task별 데이터 형식, 모델, Recipe 설정 |
| [설정 스키마](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/SETTINGS_SCHEMA.md) | Config/Recipe YAML 작성법 |
| [CLI 레퍼런스](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/CLI_REFERENCE.md) | 명령어 상세 옵션 |
| [API 서빙 가이드](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/API_SERVING_GUIDE.md) | REST API 서버 배포 |
| [전처리 레퍼런스](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/PREPROCESSOR_REFERENCE.md) | 전처리 옵션 |
| [로컬 개발 환경](https://github.com/wooshikwon/modern-ml-pipeline/blob/main/docs/user/LOCAL_DEV_ENVIRONMENT.md) | Docker Compose 기반 로컬 개발 환경 |

### 개발자 문서

시스템 확장이나 기여를 원하시면 [개발자 문서](https://github.com/wooshikwon/modern-ml-pipeline/tree/main/docs/developer)를 참고하세요.

---

## 도움말

```bash
# 전체 명령어 도움말
mmp --help

# 특정 명령어 사용법
mmp train --help

# 상세 로그 출력 (디버깅)
mmp train -c configs/dev.yaml -r recipes/model.yaml -d data/train.csv -v
```

---

**Version**: 1.0.0 | **License**: MIT | **Python**: 3.11+
