# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

mBART Translation API - FastAPI 기반의 다국어 번역 REST API 서비스. Facebook의 mBART-50 모델을 사용하여 18개 이상의 언어 간 번역을 제공합니다.

## Commands

### Docker (권장)

```bash
# Docker Compose로 시작 (가장 쉬움)
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 서비스 중지
docker-compose down

# Docker 직접 사용
docker build -t mbart-translation-api .
docker run -d -p 8000:8000 --name mbart-api mbart-translation-api

# GPU 지원
docker run -d --gpus all -p 8000:8000 -e DEVICE=cuda --name mbart-api-gpu mbart-translation-api
```

### Local Development

```bash
# 개발 서버 실행 (자동 리로드)
python main.py

# 프로덕션 서버 실행
uvicorn main:app --host 0.0.0.0 --port 8000

# GPU 사용하여 실행
DEVICE=cuda python main.py
```

### Installation

```bash
# 의존성 설치
pip install -r requirements.txt

# 가상 환경 사용 권장
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows
pip install -r requirements.txt
```

### Testing API

```bash
# 헬스 체크
curl http://localhost:8000/health

# 번역 테스트 (한국어 -> 영어)
curl -X POST "http://localhost:8000/translate" \
  -H "Content-Type: application/json" \
  -d '{"text": "안녕하세요", "source_lang": "ko", "target_lang": "en"}'

# 지원 언어 목록 조회
curl http://localhost:8000/languages
```

## Architecture

### Core Components

1. **main.py** - FastAPI 애플리케이션
   - `/translate` POST: 번역 요청 처리
   - `/health` GET: 서비스 상태 확인
   - `/languages` GET: 지원 언어 목록
   - `lifespan`: 애플리케이션 시작 시 모델 로드

2. **translator.py** - MBartTranslator 클래스
   - `load_model()`: mBART 모델과 토크나이저 초기화
   - `translate()`: 실제 번역 수행
   - GPU/CPU 자동 감지 및 할당
   - 모델: facebook/mbart-large-50-many-to-many-mmt

3. **models.py** - Pydantic 데이터 모델
   - TranslationRequest: 번역 요청 스키마
   - TranslationResponse: 번역 응답 스키마
   - HealthResponse, LanguagesResponse

4. **config.py** - 설정 관리
   - 환경 변수 기반 설정
   - SUPPORTED_LANGUAGES: 언어 코드 매핑 (예: "ko" -> "ko_KR")

### Request Flow

```
Client Request → FastAPI Endpoint → Validation (Pydantic)
                                         ↓
Response ← Translated Text ← MBartTranslator.translate()
```

### Model Loading

- 애플리케이션 시작 시 `lifespan` 이벤트에서 모델 로드
- 첫 실행 시 HuggingFace에서 모델 다운로드 (약 2.4GB)
- 이후 실행에서는 캐시된 모델 사용 (~/.cache/huggingface/)

### Language Code Mapping

mBART는 특정 언어 코드 형식을 사용합니다:
- 일반 코드 (ko, en) → mBART 코드 (ko_KR, en_XX)
- config.py의 SUPPORTED_LANGUAGES에 정의
- 새 언어 추가 시 이 딕셔너리에 추가 필요

## Key Implementation Details

- **Device Selection**: CUDA 사용 가능 시 자동으로 GPU 사용, 아니면 CPU
- **Token Length**: MAX_LENGTH(기본 512)로 입력 길이 제한
- **Error Handling**: 언어 코드 검증, 모델 로드 상태 확인
- **CORS**: 모든 origin 허용 (프로덕션에서는 제한 필요)

## Configuration

환경 변수로 설정 변경:
- `HOST`, `PORT`: 서버 바인딩 설정
- `MODEL_NAME`: 사용할 mBART 모델 (다른 변형 가능)
- `MAX_LENGTH`: 최대 토큰 길이
- `DEVICE`: "cuda" 또는 "cpu"

## Docker Details

### Image Structure
- Base: python:3.11-slim
- Non-root user (appuser) for security
- Health check endpoint: /health
- Model cache volume: /home/appuser/.cache/huggingface

### Volume Management
모델은 약 2.4GB로, 컨테이너 재시작 시 재다운로드 방지를 위해 볼륨 마운트 필수:
```bash
-v mbart-cache:/home/appuser/.cache/huggingface
```

### Resource Requirements
- CPU: 최소 8GB RAM (16GB 권장)
- GPU: 최소 8GB VRAM
- Disk: 모델 캐시용 약 5GB 여유 공간