# Q-Table 협상 전략 강화학습 데모

기업 간 협상 시뮬레이션을 위한 강화학습 에이전트의 Q-Table 기반 전략 학습 데모입니다.

## 주요 기능

- ✅ Q-Table 기반 협상 전략 시뮬레이션
- ✅ 보상함수 R(s,a) = W × (A/P) + (1-W) × End 정확한 구현
- ✅ FQI (Fitted Q-Iteration) + CQL (Conservative Q-Learning) 시뮬레이션
- ✅ 실시간 경험 데이터 수집 및 축적
- ✅ Q-Table 학습 과정 시각화
- ✅ 콜드 스타트 문제부터 학습된 정책까지 전체 여정 관찰

## 시스템 구성

### 백엔드 (FastAPI)
- RESTful API 서버
- Q-Table 학습 엔진
- 협상 환경 시뮬레이터
- 경험 데이터 관리

### 프론트엔드 (Streamlit)
- 대화형 웹 인터페이스
- 실시간 시각화
- 단계별 학습 과정 관찰

## 설치 및 실행

### 1. 의존성 설치
```bash
# Poetry를 사용한 설치
poetry install

# 또는 pip 사용
pip install -r requirements.txt
```

### 2. 환경 설정
```bash
# .env 파일 복사 및 수정
cp .env.example .env
```

### 3. 백엔드 서버 실행
```bash
# Poetry 사용
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 또는 직접 실행
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

### 4. 프론트엔드 실행
```bash
# Poetry 사용
poetry run streamlit run frontend/app.py --server.port 8501

# 또는 직접 실행
streamlit run frontend/app.py --server.port 8501
```

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

## 핵심 개념

### 상태 공간 (State Space)
상태는 (현재 카드, 시나리오, 가격 구간)의 조합으로 구성됩니다:
- **카드**: C1, C2, C3, C4 (협상 전략 카드)
- **시나리오**: A, B, C, D (협상 상황별 가중치)
- **가격 구간**: PZ1, PZ2, PZ3 (목표가 대비 제안가 구간)

### 보상함수 (Reward Function)
```
R(s,a) = W × (A/P) + (1-W) × End
```
- **A**: 앵커링 목표가 (구매자 목표 가격)
- **P**: 상대방 제안가 (판매자 제시 가격)
- **End**: 협상 종료 여부 (0 또는 1)
- **W**: 가중치 = (S_n + PZ_n) / 2

### 가중치 시스템
- **시나리오별 가중치**: S_1=A, S_2=D, S_3=C, S_4=B
- **가격 구간별 가중치**: 목표가와 제안가 차이에 따른 영향도

## 학습 알고리즘

### 1. Q-Learning
전통적인 온라인 강화학습 알고리즘으로 실시간 Q-Table 업데이트

### 2. FQI (Fitted Q-Iteration)
배치 기반 오프라인 강화학습으로 수집된 경험 데이터 활용

### 3. CQL (Conservative Q-Learning)
분포 이동 문제를 해결하기 위한 보수적 Q-Learning

## 데모 흐름

1. **콜드 스타트**: 초기 Q-Table 상태 (모든 값 0)
2. **데이터 수집**: 무작위 탐험을 통한 경험 데이터 축적
3. **Q-Learning**: 수집된 데이터로 Q-Table 실시간 업데이트
4. **FQI+CQL**: 오프라인 배치 학습 시뮬레이션
5. **학습된 정책**: 최적화된 협상 전략 활용

## 기술 스택

- **Backend**: FastAPI, Uvicorn
- **Frontend**: Streamlit
- **Data**: Pandas, NumPy
- **Visualization**: Matplotlib, Seaborn, Plotly
- **Environment**: Poetry, python-dotenv
- **Testing**: Pytest

## 프로젝트 구조

```
qtable_negotiation_demo/
├── app/                    # FastAPI 백엔드
│   ├── api/               # API 라우터
│   ├── core/              # 핵심 설정
│   ├── models/            # 데이터 모델
│   └── services/          # 비즈니스 로직
├── frontend/              # Streamlit 프론트엔드
├── tests/                 # 테스트 코드
├── data/                  # 데이터 파일
├── pyproject.toml         # Poetry 설정
├── .env                   # 환경 변수
└── README.md              # 이 파일
```

## 라이선스

이 프로젝트는 교육 및 데모 목적으로 제작되었습니다.