Social-Lens: A. Social Coach

프로젝트 목적

Social-Lens: A. Social Coach는 사회적 상호작용에 어려움을 겪거나 자신의 감정 전달 상태를 확인하고 싶은 사용자를 위한 실시간 코칭 도우미입니다. 카메라를 통해 사용자의 표정(Vision) 을 분석하고, 입력한 대화 내용(Text) 과의 일치 여부를 판단하여, 상황에 적절한 따뜻한 조언을 제공합니다. 이 프로젝트는 SKT A. (에이닷) 서비스의 "사회 상황 코치" 기능을 가정한 데모로, 프라이버시 보호(On-device cleanup) 와 안정성(Graceful Degradation) 을 핵심 가치로 합니다.

개요

스냅샷 기반 표정 분석과 텍스트 컨텍스트를 결합해 조언을 제공하는 데모 앱입니다. 안정성과 프라이버시를 최우선으로 하는 Streamlit/FastAPI 하이브리드 구조를 채택했습니다.

주요 특징

• Streamlit 스냅샷 플로우: st.camera_input으로 단일 프레임만 전송해 렉 최소화.
• Vision 모듈: OpenCV + DeepFace, enforce_detection=False로 얼굴 미감지 시 안전한 폴백.
• Reasoning 모듈: GPT-4o 호출 + 지수 백오프, OPENAI_API_KEY 없으면 mock 응답으로 데모 가능.
• Web Speech API: 브라우저 내장 합성으로 즉시 재생, gTTS 불필요.
• 프라이버시: 프레임 메모리 삭제, 히스토리 5턴 제한, Reset으로 세션 초기화.
• FastAPI 백엔드: /health, /analyze 엔드포인트로 동일한 reasoning 모듈을 활용.

구조

social-lens/
├── app.py                 # Streamlit 메인 엔트리 (Snapshot & Analyze)
├── api/
│   ├── __init__.py
│   └── main.py            # FastAPI 엔트리 (건강검사, /analyze)
├── core/
│   ├── __init__.py
│   ├── vision.py          # DeepFace/OpenCV
│   ├── reasoning.py       # GPT-4o + mock + 백오프
│   └── web_speech.py      # Web Speech API 버튼 HTML
├── utils/
│   ├── __init__.py
│   ├── validators.py      # 텍스트 검증, 유해어 감지
│   ├── errors.py          # 예외 스텁
│   └── memory.py          # 세션/GC 정리
├── tests/
│   ├── test_e2e.py        # End-to-End 통합 테스트
│   └── test_docker_e2e.py # Docker 실행 테스트
├── scripts/
│   └── download_models.py # 모델 사전 다운로드
├── pyproject.toml         # uv 관리 의존성
├── uv.lock
├── .env.example           # OPENAI_API_KEY 템플릿
└── social-lens-demo-prompt.md

주의

• API 키는 환경변수 OPENAI_API_KEY로 주입.
• DeepFace/TensorFlow, OpenCV는 초기 로드가 무거울 수 있으므로 데모 환경에서 사전 설치 권장.
• UI는 모바일 폭 500px 기준, 버튼 높이 48px 이상으로 접근성을 기본 확보.

테스트 및 검증 방법

1. 로컬 환경 설정 (Setup)

uv 패키지 매니저를 사용하여 의존성을 설치합니다.

uv sync

2. Mock 모드 실행 (Mock Mode)

API 키나 카메라 연결 없이 UI 및 로직 흐름을 테스트하려면 MOCK_MODE를 활성화하세요.

export MOCK_MODE=true
uv run streamlit run app.py

3. E2E 테스트 실행 (Automated Tests)

Vision-Reasoning 파이프라인 및 프라이버시 클린업 로직을 검증합니다.

# pytest 실행 (onnxruntime 등 의존성 포함)
uv run --with pytest python -m pytest tests/test_e2e.py

4. Docker 배포 및 테스트

도커 이미지를 빌드하고 컨테이너 상태를 검증합니다.

# Docker 빌드 및 테스트 자동화 스크립트 실행
uv run python tests/test_docker_e2e.py

# 또는 수동 실행
docker build -t social-lens .
docker run -p 8501:8501 social-lens

5. Streamlit Community Cloud 배포

이 프로젝트는 Streamlit Cloud에 최적화되어 있습니다. 다음 절차를 따르세요.

1. GitHub 저장소에 코드를 푸시합니다.
   • 주의: models/ 폴더 내의 .xml 및 .onnx 파일이 함께 커밋되었는지 확인하세요.
2. Streamlit Cloud에 접속하여 'New app'을 클릭합니다.
3. 저장소와 브랜치를 선택하고, 메인 파일 경로에 app.py를 입력합니다.
4. Advanced settings에서 OPENAI_API_KEY를 Secrets에 추가합니다.

   OPENAI_API_KEY = "sk-..."

5. 'Deploy'를 클릭합니다. (필요한 라이브러리는 requirements.txt를 통해 자동 설치됩니다)