README.md

metadata

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. 저장소 클론

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

2. 환경 변수 설정

Supabase 사용 (권장)

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

cp ENV_EXAMPLE .env

2. Supabase 프로젝트 설정에서 필요한 정보를 복사합니다:

   • Project URL: https://project_id.supabase.co
   • API Key (anon key)
   • Database URL (Connection String)

3. .env 파일에 Supabase 정보를 입력합니다:

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. 의존성 설치

# uv를 사용하는 경우
uv sync

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

4. Google Gemini API 키 발급

1. Google AI Studio에서 API 키 발급
2. .env 파일에 GOOGLE_API_KEY 추가

5. 애플리케이션 실행

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

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

🐳 Docker 배포

로컬 Docker 실행

# 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는 언제든 환영합니다!