# 🚀 Q-Table 협상 전략 데모 시작 가이드

## 빠른 시작

### 1. 환경 설정

#### Poetry 사용 (권장)
```bash
# Poetry 설치 (미설치시)
curl -sSL https://install.python-poetry.org | python3 -

# 의존성 설치
poetry install

# 가상환경 활성화
poetry shell
```

#### pip 사용
```bash
# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate  # Windows

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

### 2. 환경 변수 설정
```bash
# .env 파일 생성
cp .env.example .env

# 필요에 따라 .env 파일 수정
nano .env
```

### 3. 시스템 실행

#### 방법 1: 전체 시스템 동시 실행
```bash
python run_both.py
```

#### 방법 2: 개별 실행
```bash
# 터미널 1 - API 서버
python run_api.py

# 터미널 2 - 프론트엔드
python run_frontend.py
```

#### 방법 3: Make 사용
```bash
make run-both
```

### 4. 접속
- **프론트엔드**: http://localhost:8501
- **API 문서**: http://localhost:8000/docs

## 주요 기능 사용법

### 1. 콜드 스타트 확인
- 프론트엔드의 "콜드 스타트" 탭에서 초기 Q-Table 상태 확인
- 모든 Q값이 0인 상태에서 시작

### 2. 데이터 수집
- "데이터 수집" 탭에서 에피소드 생성
- 탐험율과 에피소드 수를 조정하여 경험 데이터 수집

### 3. Q-Learning 학습
- "Q-Learning" 탭에서 수집된 데이터로 Q-Table 업데이트
- 학습률, 할인율 등 하이퍼파라미터 조정 가능

### 4. FQI+CQL 학습
- "FQI+CQL" 탭에서 오프라인 학습 수행
- 보수적 Q-Learning으로 안전한 정책 학습

### 5. 정책 비교
- "학습된 정책" 탭에서 Q-Learning과 FQI+CQL 정책 비교
- 실제 협상 시나리오에서 행동 추천 받기

## Docker 사용

### Docker Compose로 실행
```bash
# 이미지 빌드
docker-compose build

# 시스템 실행
docker-compose up

# 백그라운드 실행
docker-compose up -d

# 중지
docker-compose down
```

## 개발 환경 설정

### 코드 품질 도구
```bash
# 코드 포맷팅
make format

# 린팅
make lint

# 테스트
make test
```

### 개발 서버 실행
```bash
# API 서버 (Hot Reload)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 프론트엔드 (Hot Reload)
streamlit run frontend/app.py --server.port 8501
```

## 문제 해결

### 포트 충돌
- 8000번 포트나 8501번 포트가 사용 중인 경우 .env 파일에서 포트 변경

### 의존성 오류
```bash
# 의존성 재설치
pip install --force-reinstall -r requirements.txt

# 또는 Poetry 사용시
poetry install --no-cache
```

### API 연결 오류
- API 서버가 실행 중인지 확인
- http://localhost:8000/api/v1/health 에서 상태 확인

## 추가 정보

### 프로젝트 구조
```
qtable_negotiation_demo/
├── app/                 # FastAPI 백엔드
│   ├── api/            # API 엔드포인트
│   ├── core/           # 설정 및 유틸리티
│   ├── models/         # 데이터 모델
│   └── services/       # 비즈니스 로직
├── frontend/           # Streamlit 프론트엔드
├── tests/              # 테스트 코드
├── run_*.py           # 실행 스크립트
└── docker-compose.yml  # Docker 설정
```

### 핵심 개념
- **보상함수**: R(s,a) = W × (A/P) + (1-W) × End
- **상태공간**: (카드, 시나리오, 가격구간) 조합
- **Q-Learning**: 온라인 강화학습
- **FQI+CQL**: 오프라인 보수적 강화학습

### 지원 및 문의
- 이슈 발생시 API 문서 참조: http://localhost:8000/docs
- 로그 파일 확인: app.log