README.md

---
title: Nurse Handover Simulator
emoji: 🏥
colorFrom: purple
colorTo: pink
sdk: docker
pinned: false
short_description: AI 기반 간호사 SBAR 인수인계 훈련 플랫폼 - EMR 데이터로 실전 연습
---

# 🏥 간호 인수인계 교육 플랫폼

Clinical Handover Training Chatbot utilizing SBAR/ISBAR, EMR data, and immersive technology (Metaverse/VR) for standardized, high-fidelity nursing handover practice.

## 📋 개요

간호사 SBAR 형식 인수인계 훈련을 위한 AI 기반 교육 플랫폼입니다. Gradio 기반 웹 인터페이스를 통해 실제 EMR 데이터를 활용한 인수인계 연습을 제공합니다.

## 🚀 시작하기

### 1. 저장소 클론

```bash
git clone https://github.com/your-username/nurse-handover-simulator.git
cd nurse-handover-simulator
```

### 2. 환경 변수 설정

#### Supabase 사용 (권장)

1. `ENV_EXAMPLE` 파일을 `.env`로 복사합니다:
```bash
cp ENV_EXAMPLE .env
```

2. Supabase 프로젝트 설정에서 필요한 정보를 복사합니다:
   - Project URL: `https://project_id.supabase.co`
   - API Key (anon key)
   - Database URL (Connection String)

3. `.env` 파일에 Supabase 정보를 입력합니다:
```env
SUPABASE_URL=https://[project_id].supabase.co
SUPABASE_ANON_KEY=your_anon_key_here
SUPABASE_DB_URL=postgresql://postgres:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
GOOGLE_API_KEY=your_google_api_key_here
```

#### 로컬 PostgreSQL 사용 (개발 환경)

환경 변수에 `SUPABASE_DB_URL`을 설정하지 않으면 자동으로 로컬 PostgreSQL을 사용합니다.

### 3. 의존성 설치

```bash
# uv를 사용하는 경우
uv sync

# 또는 일반 pip 사용
pip install -e .
```

### 4. Google Gemini API 키 발급

1. [Google AI Studio](https://makersuite.google.com/app/apikey)에서 API 키 발급
2. `.env` 파일에 `GOOGLE_API_KEY` 추가

### 5. 애플리케이션 실행

```bash
# start.sh 사용 (권장)
bash start.sh

# 또는 직접 실행
uv run app.py
```

## 🐳 Docker 배포

### 로컬 Docker 실행

```bash
# Docker 이미지 빌드
docker build -t nurse-handover-simulator .

# Docker 컨테이너 실행 (환경 변수 포함)
docker run -p 7860:7860 \
  -e SUPABASE_URL="https://your-project.supabase.co" \
  -e SUPABASE_ANON_KEY="your_key" \
  -e SUPABASE_DB_URL="postgresql://..." \
  -e GOOGLE_API_KEY="your_key" \
  nurse-handover-simulator

# 또는 .env 파일 사용
docker run -p 7860:7860 --env-file .env nurse-handover-simulator
```

### Hugging Face Spaces 배포

1. Hugging Face Spaces에 새 Space 생성 (Docker 타입 선택)
2. Repository Secrets에 다음 환경 변수 등록:
   - `SUPABASE_URL`
   - `SUPABASE_ANON_KEY`
   - `SUPABASE_DB_URL`
   - `GOOGLE_API_KEY`
3. Dockerfile과 코드 푸시
4. 자동 빌드 및 배포 완료

## 📁 프로젝트 구조

```
nurse-handover-simulator/
├── app.py                    # Gradio 메인 애플리케이션
├── config/
│   └── database.py          # 데이터베이스 연결 설정
├── models/
│   ├── patient_data.py      # 환자 및 시나리오 모델
│   ├── handoff_record.py    # 인수인계 기록 모델
│   └── chat_history.py      # 채팅 히스토리 모델
├── services/
│   ├── db_service.py        # 데이터베이스 CRUD 서비스
│   └── gemini_service.py   # Google Gemini AI 서비스
├── data/
│   └── scenarios.json      # 시나리오 데이터
├── Dockerfile               # Docker 배포 설정
├── docker-compose.yml       # 로컬 PostgreSQL 설정
├── ENV_EXAMPLE              # 환경 변수 템플릿
├── start.sh                 # 시작 스크립트
└── init_db.py              # 데이터베이스 초기화 스크립트
```

## 🔑 환경 변수 설명

| 변수 | 설명 | 필수 여부 |
|------|------|---------|
| `SUPABASE_URL` | Supabase 프로젝트 URL | Supabase 사용 시 |
| `SUPABASE_ANON_KEY` | Supabase Anon API Key | Supabase 사용 시 |
| `SUPABASE_DB_URL` | Supabase 데이터베이스 연결 URL | Supabase 사용 시 |
| `GOOGLE_API_KEY` | Google Gemini API 키 | 필수 |
| `DB_HOST` | 로컬 PostgreSQL 호스트 | 로컬 PostgreSQL 사용 시 |
| `DB_PORT` | 로컬 PostgreSQL 포트 | 로컬 PostgreSQL 사용 시 |

## 🔒 보안 가이드

### 환경 변수 관리

1. **절대 `.env` 파일을 Git에 커밋하지 마세요**
   - `.gitignore`에 `.env`가 이미 포함되어 있습니다

2. **Supabase Keys**
   - `SUPABASE_ANON_KEY`: 클라이언트 노출 가능 (RLS로 보호됨)
   - `SUPABASE_DB_URL`: 서버에서만 사용, 노출 금지

3. **Google API Key**
   - 서버에서만 사용, 노출 금지

4. **Hugging Face Spaces**
   - Repository Secrets를 사용하여 환경 변수를 안전하게 관리

## 📊 주요 기능

- 📋 **EMR 정보 조회**: 실제 병원 EMR과 유사한 인터페이스
- 💬 **AI 피드백**: Google Gemini AI를 활용한 실시간 피드백
- 📝 **SBAR 형식 인수인계**: 표준 인수인계 형식 연습
- 📊 **평가 시스템**: 완전성, 정확성, 명료성, 우선순위 평가
- 📚 **학생 이력 조회**: 학생별 학습 이력 및 통계

## 🛠️ 기술 스택

- **Backend**: Python 3.12
- **UI**: Gradio
- **Database**: Supabase (PostgreSQL) / 로컬 PostgreSQL
- **AI**: Google Gemini 2.0 Flash
- **ORM**: SQLAlchemy

## 📝 라이선스

MIT License

## 🤝 기여하기

Pull Request는 언제든 환영합니다!