# Phase 02: API Engine — PLAN

## 목표
Machine A의 추론 서버를 단일 포트(8000)로 통합하는 FastAPI 기반 리버스 프록시 + 핫스왑 엔진을 구축한다.

## 아키텍처

```
Machine B (VS Code / Discord)
│
│  OpenAI-compatible API
│  (always port 8000)
▼
Variet Engine (FastAPI, Port 8000)
├── /v1/*            → llama-server 투명 중계
├── /engine/status   → 현재 모델/상태 조회
├── /engine/models   → 사용 가능 모델 목록
├── /engine/switch   → 모델 핫스왑 요청
└── /engine/health   → 헬스체크
│
│  localhost only
▼
llama-server (Port 8080, 외부 노출 X)
```

## 완료 태스크

### Task 1: 설정 파일 (`config/engine_models.json`) ✅
- 5개 모델의 CLI 인수를 정확한 배열 형태로 저장
- Single Source of Truth: Python/TypeScript/Bash 어디서든 파싱 가능
- llama-server의 대시 규칙(-ngl vs --prio)을 직접 명시하여 추측 로직 제거

### Task 2: 엔진 코어 (`engine/variet_engine.py`) ✅
- FastAPI + lifespan 이벤트 (deprecated on_event 사용 안 함)
- subprocess.Popen으로 llama-server 생명주기 관리
- httpx 스트리밍 프록시 (SSE 포함)
- 교체 중 503 + Retry-After 응답으로 클라이언트 보호
- 프로세스 사망 감지, 포트 해제 대기, 에러 핸들링

### Task 3: 런처 (`start_variet_engine.bat`) ✅
- 원클릭 엔진 시작 스크립트
- 기존 4개 개별 .bat 파일 → `_archive/`로 이동

### Task 4: 파일 정리 ✅
- `scripts/` 85개 파일 → 9개 + `_archive/` 정리
- 루트 deprecated .bat 4개 → `_archive/`

## 기술적 결정사항

| 결정 | 이유 |
|------|------|
| args를 dict → list로 변경 | llama-server의 축약 플래그(-ngl)와 정식 플래그(--prio) 규칙이 불규칙하여 코드 추측이 실패 |
| 내부 포트 8080 | 외부(8000)와 분리하여 보안 강화 |
| BackgroundTasks로 핫스왑 | switch API가 즉시 응답 → 백그라운드에서 교체 진행 |
| 스트리밍 프록시 | SSE 스트리밍 응답을 chunk 단위로 전달하여 지연 최소화 |

## 산출물
- `engine/variet_engine.py` — FastAPI 프록시 + 프로세스 관리자 (398줄)
- `engine/__init__.py` — 패키지 초기화
- `config/engine_models.json` — 5개 모델 설정
- `start_variet_engine.bat` — 원클릭 런처
- `scripts/test_hotswap.py` — 핫스왑 검증 스크립트