# 사물 페르소나 생성기 (物魂 Creator)

## 1. 프로젝트 개요

사물 페르소나 생성기는 일상 사물에 고유한 성격과 개성을 부여하고 테스트할 수 있는 실험적 도구입니다. 본 도구는 "일상 사물 인격화를 통한 관계형성 AI 시스템 연구"를 뒷받침하기 위한 페르소나 생성, 테스트 및 데이터 수집을 목적으로 합니다. 사물의 물리적 특성으로부터 성격을 추론하고, 이를 다양한 설정을 통해 조정하며, 생성된 페르소나와의 대화를 통해 관계 발전 양상을 연구합니다.

## 2. 코드 구현 및 기능 모듈

### 2.1 이미지 기반 성격 추론 모듈 (`image_analyzer.py`)
- **이미지 분석 시스템**
  - PIL/Pillow 라이브러리 활용 이미지 로드 및 처리
  - 물리적 특성(형태, 색상, 재질) 추출 함수 구현
  - 특성별 성격 매핑 로직: `analyze_image()` 함수로 구현

- **물리적 특성-성격 매핑 엔진**
  - JSON 기반 매핑 데이터 관리: `load_trait_mappings()` 함수
  - 형태 매핑: 곡선형/직선형/대칭형/비대칭형/단순형/복잡형
  - 색상 매핑: 밝은/어두운/따뜻한/차가운/화려한/단색
  - 재질 매핑: 나무/금속/유리/가죽/플라스틱/천/종이
  - 매핑 데이터 자동 생성 및 로드 기능

### 2.2 질문 생성 및 페르소나 강화 모듈 (`question_generator.py`, `persona_generator.py`)
- **AI 기반 맞춤형 질문 생성기**
  - 사물 유형별 특화 질문 템플릿 (8개 카테고리)
  - 성격 특성별 맞춤형 질문 생성 로직
  - Google Gemini API 활용 동적 질문 생성: `generate_llm_questions()` 함수

- **페르소나 강화 시스템**
  - `generate_persona()`: 전체 페르소나 생성 파이프라인 함수
  - `get_persona_enhancement()`: Google Gemini API 호출로 페르소나 풍부화
  - 성격 특성 요약 자동 생성: `get_trait_summary()` 함수
  - 배경 이야기, 경험 자동 생성: `generate_experiences()` 함수

### 2.3 대화 처리 모듈 (`chat_engine.py`, `gemini_handler.py`)
- **실시간 채팅 시스템**
  - 대화 초기화: `start_conversation()` 함수
  - 메시지 처리: `process_message()` 함수
  - 대화 내용 관리 및 통계 트래킹 구현

- **응답 생성 엔진**
  - Google Gemini API 연동: `generate_response()` 함수
  - 프롬프트 엔지니어링: 페르소나 특성에 맞는 응답 유도
  - 초기 인사말 생성: `generate_initial_greeting()` 함수

### 2.4 데이터 관리 모듈 (`data_manager.py`)
- **파일 시스템 기반 데이터 관리**
  - 페르소나 저장: `save_persona()` 함수
  - 페르소나 로드: `load_persona()` 함수
  - 대화 기록 저장: `save_conversation()` 함수
  - 페르소나 및 대화 목록화: `list_personas()`, `list_conversations()` 함수

- **데이터 분석 기능**
  - 페르소나 특성 분포 분석: `analyze_persona_trait_distribution()` 함수
  - 대화 통계 분석: `get_conversation_statistics()` 함수

### 2.5 프롬프트 관리 시스템 (`prompt_templates.py`)
- **템플릿 기반 프롬프트 관리**
  - 페르소나 강화용 프롬프트: `PERSONA_ENHANCEMENT_TEMPLATE`
  - 이미지 분석용 프롬프트: `IMAGE_ANALYSIS_TEMPLATE`
  - 대화 응답용 프롬프트: `CONVERSATION_RESPONSE_TEMPLATE`
  - 질문 생성용 프롬프트: `QUESTION_GENERATION_TEMPLATE`

- **프롬프트 포맷 함수**
  - `format_persona_enhancement_prompt()`: 페르소나 강화 프롬프트 포맷
  - `format_conversation_prompt()`: 대화 응답 프롬프트 포맷
  - `format_question_generation_prompt()`: 질문 생성 프롬프트 포맷

### 2.6 웹 인터페이스 (`app.py`)
- **Gradio 기반 UI 구현**
  - 3개 탭 구성: 페르소나 생성, 대화 테스트, 페르소나 라이브러리
  - 이벤트 핸들러 연결: 버튼 클릭, 입력 제출 등
  - 상태 관리: gr.State()를 활용한 페르소나 및 대화 상태 관리

- **요소별 UI 컴포넌트**
  - 이미지 업로드 및 분석: gr.Image, image_analysis_btn
  - 성격 특성 슬라이더: gr.Slider 컴포넌트 6개 활용
  - 채팅 인터페이스: gr.Chatbot, gr.Textbox 조합

## 3. 기술 스택 및 의존성

### 3.1 핵심 라이브러리
- **Gradio**: 웹 인터페이스 구현 (v3.50.2 이상)
- **Python-dotenv**: 환경 변수 관리
- **Requests**: API 통신
- **Pillow**: 이미지 처리
- **NumPy**: 수치 연산
- **Matplotlib**: 데이터 시각화 (향후 구현 예정)

### 3.2 API 통합
- **Google Gemini API**: LLM 기반 텍스트 생성
  - `gemini_query()`: API 요청 함수
  - JSON 파싱: `extract_json()` 함수

### 3.3 파일 시스템 구조
```
persona_creator/
├── app.py                     # 메인 그라디오 애플리케이션
├── requirements.txt           # 의존성 패키지
├── packages.txt               # 시스템 패키지
├── README.md                  # 사용 설명서
├── modules/
│   ├── image_analyzer.py      # 이미지 분석 및 특성 추출
│   ├── question_generator.py  # 동적 질문 생성 엔진
│   ├── persona_generator.py   # 페르소나 생성 엔진
│   ├── chat_engine.py         # 대화 처리 및 기록
│   ├── gemini_handler.py      # 제미나이 API 연동
│   ├── prompt_templates.py    # LLM 프롬프트 템플릿
│   └── data_manager.py        # 데이터 저장 및 분석
├── data/
│   ├── trait_mappings/        # 물리적-성격 특성 매핑 데이터
│   │   ├── shape_traits.json  # 형태-성격 매핑 규칙
│   │   ├── color_traits.json  # 색상-성격 매핑 규칙
│   │   └── material_traits.json # 재질-성격 매핑 규칙
│   ├── user_personas/         # 사용자 생성 페르소나
│   └── conversation_logs/     # 대화 기록 저장소
├── styles/
│   └── custom.css             # UI 커스텀 스타일
└── assets/
    ├── examples/              # 예시 이미지
    └── icons/                 # UI 아이콘
```

## 4. 데이터 구조 및 스키마

### 4.1 페르소나 JSON 스키마
```json
{
  "기본정보": {
    "이름": "String",
    "유형": "String",
    "나이": "String",
    "설명": "String",
    "생성일시": "String (YYYY-MM-DD HH:MM:SS)"
  },
  "성격특성": {
    "온기": "Integer (0-100)",
    "능력": "Integer (0-100)",
    "신뢰성": "Integer (0-100)",
    "친화성": "Integer (0-100)",
    "창의성": "Integer (0-100)",
    "유머감각": "Integer (0-100)"
  },
  "성격요약": "String",
  "매력적결함": ["String", "String"],
  "소통방식": "String",
  "유머스타일": "String",
  "말투패턴": "String",
  "관심사": ["String", "String", "String", ...],
  "배경이야기": "String",
  "경험": ["String", "String", "String", ...],
  "관계성향": {
    "애착스타일": "String",
    "관계깊이선호도": "String",
    "초기태도": "String"
  },
  "filepath": "String (저장 경로)"
}
```

### 4.2 대화 기록 JSON 스키마
```json
{
  "persona_name": "String",
  "persona_type": "String",
  "start_time": "String (YYYY-MM-DD HH:MM:SS)",
  "current_time": "String (YYYY-MM-DD HH:MM:SS)",
  "duration_seconds": "Integer",
  "messages": [
    {
      "role": "String (system|user|assistant)",
      "content": "String",
      "timestamp": "String (YYYY-MM-DD HH:MM:SS)"
    },
    ...
  ]
}
```

### 4.3 매핑 데이터 스키마
```json
{
  "특성유형": {
    "특성값": {
      "성격특성": [최소값, 최대값]
    }
  }
}
```

## 5. 사용자 플로우 시퀀스

### 5.1 페르소나 생성 시퀀스
1. 이미지 업로드 → `image_analyzer.py` → 특성 추출
2. 성격 특성 조정 → 슬라이더 UI → 특성 값 설정
3. 매력적 결함, 소통 방식 선택 → 선택형 UI
4. 생성 버튼 클릭 → `persona_generator.py` → 페르소나 생성
5. Google Gemini API 호출 → 페르소나 강화 → JSON 결과 표시
6. 자동 저장 → `data_manager.py` → 파일시스템 저장

### 5.2 대화 테스트 시퀀스
1. 페르소나 선택 → `load_persona()` → 메모리에 로드
2. 대화 시작 → `start_conversation()` → 인사말 생성
3. 사용자 입력 → `process_message()` → 메시지 기록
4. Gemini API 호출 → `generate_response()` → 응답 생성
5. 응답 표시 → Chatbot UI 업데이트 → 통계 업데이트
6. 대화 저장 → `save_conversation()` → JSON 저장

## 6. 프롬프트 시스템 상세

### 6.1 페르소나 강화 프롬프트 구성
- **기본 정보 섹션**: 이름, 유형, 설명
- **성격 특성 섹션**: 6개 주요 특성 및 값
- **소통 방식 섹션**: 대화/유머 스타일, 말투 패턴
- **관계 성향 섹션**: 애착 스타일, 관계 깊이, 초기 태도
- **강화 지시사항**: 배경 확장, 관심사 추가, 말투 구체화, 성격 특성 독특화

### 6.2 대화 응답 프롬프트 구성
- **페르소나 정보 섹션**: 기본 정보, 성격 특성, 배경 이야기
- **표현 방식 섹션**: 소통 방식, 유머 스타일, 매력적 결함
- **대화 맥락 섹션**: 최근 대화 기록 포함
- **응답 지시사항**: 페르소나 역할 유지, 성격 특성 반영, 한국어 응답

## 7. 핵심 함수 및 로직

### 7.1 이미지 분석 파이프라인
```python
# 이미지 업로드 → 분석 → 특성 매핑 → UI 업데이트
image_analysis_btn.click(
    fn=analyze_image,
    inputs=[object_image],
    outputs=[image_analysis_result, warmth, competence, trustworthiness, 
             friendliness, creativity, humor, object_type, object_description]
)
```

### 7.2 페르소나 생성 파이프라인
```python
# 모든 입력 데이터 → 페르소나 생성 → JSON 결과
create_btn.click(
    fn=generate_persona,
    inputs=[
        object_name, object_type, object_age, object_description,
        warmth, competence, trustworthiness, friendliness, creativity, humor,
        flaws, communication_style, humor_style, speech_pattern, interests,
        attachment_style, relationship_depth, initial_attitude, backstory,
        image_analysis_result
    ],
    outputs=[generated_persona, current_persona]
)
```

### 7.3 대화 처리 파이프라인
```python
# 사용자 메시지 → 대화 처리 → 응답 생성 → UI 업데이트
send_btn.click(
    fn=process_message,
    inputs=[user_message, conversation_history, current_persona, session_start_time],
    outputs=[chat_display, conversation_history, user_message, chat_stats]
)
```

## 8. 향후 개발 계획

### 8.1 이미지 분석 고도화
- **컴퓨터 비전 API 통합**
  - Google Cloud Vision API 또는 Azure Computer Vision API 연동
  - image_analyzer.py 확장: 실제 객체 인식 및 속성 추출 구현
  - 이미지 감정 분석 알고리즘 추가

- **물리적-성격 매핑 확장**
  - 머신러닝 기반 매핑 시스템: 사용자 피드백으로 학습
  - 더 세분화된 물리적 특성 카테고리 추가
  - 동적 매핑 규칙 업데이트 메커니즘

### 8.2 페르소나 시스템 확장
- **모순적 특성 구현**
  - persona_generator.py 확장: 모순 특성 정의 및 처리 모듈
  - 상황 인식 모순 표현 로직: 특정 대화 맥락에서 발현
  - 심층 성격 모델 도입: 5요인 모델 또는 MBTI 기반

- **관계 발전 단계 시스템**
  - 새로운 모듈 추가: relationship_tracker.py
  - 6단계 관계 발전 모델: 친숙도, 신뢰도, 친밀도 지표
  - 대화 분석 기반 관계 단계 자동 진단

### 8.3 연구 도구 및 분석 기능
- **데이터 분석 도구**
  - 새로운 모듈 추가: analytics_engine.py
  - 통계 분석 라이브러리 통합: pandas, scipy
  - 대시보드 UI 개발: plotly 또는 dash 통합

- **A/B 테스트 시스템**
  - 실험 설계 모듈: experiment_manager.py
  - 동일 사물의 다른 성격 버전 생성 및 비교
  - 사용자 반응 자동 측정 및 분석

## 9. 개발자 참고 사항

### 9.1 API 키 설정
- `.env` 파일에 `GEMINI_API_KEY=your_api_key` 추가
- Google AI Studio에서 API 키 발급 필요
- API 비용 추적: 페르소나 생성당 약 0.0002-0.0005 USD

### 9.2 개발 환경 설정
```bash
# 가상환경 생성
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

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

# 애플리케이션 실행
python app.py
```

### 9.3 Flutter 앱 개발 환경 설정
```bash
# Flutter SDK 설치
flutter doctor

# Flutter 프로젝트 생성
flutter create memory_tag_app
cd memory_tag_app

# 필요한 패키지 추가
flutter pub add google_generative_ai
flutter pub add qr_flutter
flutter pub add qr_code_scanner
flutter pub add speech_to_text
flutter pub add flutter_tts
flutter pub add shared_preferences
flutter pub add camera
flutter pub add path_provider
```

### 9.4 Flutter 애플리케이션 구조
```
memory_tag_app/
├── lib/
│   ├── main.dart                # 앱 진입점
│   ├── screens/
│   │   ├── home_screen.dart     # 홈 화면
│   │   ├── scan_screen.dart     # QR 스캔 화면
│   │   ├── chat_screen.dart     # 대화 화면
│   │   ├── create_screen.dart   # 페르소나 생성 화면
│   │   └── settings_screen.dart # 설정 화면
│   ├── models/
│   │   ├── persona.dart         # 페르소나 모델
│   │   └── message.dart         # 대화 메시지 모델
│   ├── services/
│   │   ├── gemini_service.dart   # Google Gemini API 연동
│   │   ├── storage_service.dart  # 로컬 스토리지 관리
│   │   ├── stt_service.dart      # 음성-텍스트 변환
│   │   └── tts_service.dart      # 텍스트-음성 변환
│   ├── widgets/
│   │   ├── chat_bubble.dart     # 채팅 버블 UI
│   │   ├── voice_input_button.dart # 음성 입력 버튼
│   │   └── persona_card.dart    # 페르소나 카드 UI
│   └── utils/
│       ├── constants.dart       # 상수 정의
│       └── prompt_templates.dart # 프롬프트 템플릿
├── assets/
│   ├── images/                  # 이미지 리소스
│   └── sounds/                  # 사운드 리소스
└── pubspec.yaml                 # 의존성 관리
```

### 9.5 Google Gemini API 활용
- **멀티모달 기능 구현**
  - 카메라로 캡처한 사물 이미지를 Gemini Pro Vision API에 전송
  - 텍스트와 이미지를 동시에 처리하는 멀티모달 프롬프트 설계
  - 이미지 인식 결과를 바탕으로 사물 성격 자동 추론

- **제미나이 모델 활용 전략**
  - Gemini 1.5 Pro: 복잡한 페르소나 생성 및 긴 컨텍스트 대화용
  - Gemini 1.5 Flash: 빠른 응답이 필요한 일상 대화용
  - 적절한 모델 선택을 통한 비용 최적화 구현

- **대화 메모리 관리**
  - 벡터 임베딩을 활용한 대화 메모리 구현
  - 중요 대화를 요약하여 장기 메모리에 저장
  - 상황에 따른 관련 기억 검색 알고리즘 구현

### 9.6 QR 코드 기반 연결 시스템
- **QR 코드 생성 및 관리**
  - 페르소나 ID와 메타데이터를 포함한 QR 코드 생성
  - 위치 정보를 QR 코드에 포함하여 공간 인식 기능 구현
  - 보안을 위한 QR 코드 암호화 옵션 제공

- **스캔 및 상호작용 흐름**
  - 카메라를 통한 QR 코드 인식 → 페르소나 정보 로드
  - 이전 대화 이력 검색 → 대화 컨텍스트 구성
  - 위치 기반 맞춤형 인사말 및 화제 제안

### 9.7 음성 인터페이스
- **STT(음성-텍스트) 파이프라인**
  - `speech_to_text` 패키지를 활용한 실시간 음성 인식
  - 오디오 스트림 처리 및 잡음 필터링
  - 다국어 지원(한국어, 영어, 일본어)

- **TTS(텍스트-음성) 파이프라인**
  - Google Cloud TTS API 활용한 자연스러운 음성 생성
  - 페르소나별 맞춤 음성(음높이, 속도, 악센트) 설정
  - SSML 태그를 활용한 표현력 있는 음성 구현

### 9.8 성능 최적화 전략
- **오프라인 모드 지원**
  - 핵심 대화 패턴의 로컬 캐싱
  - 네트워크 연결 없이 기본 응답 생성 가능
  - 연결 복구 시 자동 동기화

- **배터리 및 데이터 사용량 최적화**
  - 저전력 모드에서의 동작 방식 조정
  - 요청 배치 처리를 통한 API 호출 최소화
  - 압축 알고리즘을 활용한 데이터 전송량 감소

### 9.9 코드 확장 가이드라인
- 모듈 확장 시 기존 인터페이스 유지
- 새 기능은 별도 모듈로 구현 후 app.py에 통합
- 데이터 스키마 변경 시 하위 호환성 고려
- 로깅 시스템: app.py 내 logging 모듈 설정 추가 필요

### 9.10 알려진 이슈 및 제한사항
- Gemini API 한국어 응답이 때때로 불안정함
- 이미지 분석은 현재 더미 데이터 기반 (실제 분석 미구현)
- 대용량 대화 히스토리(20턴 이상)에서 성능 저하 발생
- 페르소나 간 전환 시 일부 UI 상태 초기화 문제

## 10. 연구 활용 방안

본 도구는 현재 구현된 기능만으로도 다음과 같은 연구에 활용할 수 있습니다:

- **사물 인격화 효과 연구**: 사물에 인격 부여 시 사용자 인식 변화 및 심리적 영향
- **성격 특성 선호도 연구**: 어떤 성격 특성 조합이 더 매력적으로 느껴지는지 분석
- **대화 패턴 연구**: 페르소나 특성에 따른 대화 패턴 차이 및 사용자 참여도 변화
- **물리적-성격적 매핑 연구**: 사물의 물리적 특성이 어떻게 성격 특성으로 인식되는지 분석

향후 개발이 진행됨에 따라 더 다양하고 심층적인 연구가 가능해질 것입니다.

## 11. 모바일 앱 응용 방안

### 11.1 상업적 활용 가능성
- **실물 제품과 연동한 AI 경험**
  - 가전제품, 인테리어 소품 등에 QR 코드 부착하여 제품 브랜딩 강화
  - 상품 사용 가이드와 서포트를 재미있는 대화형으로 제공
  - 브랜드 스토리텔링 및 고객 관계 구축 도구로 활용

- **공간 기반 AI 컴패니언**
  - 공공장소, 전시관, 관광지 등에 사물 페르소나 배치
  - 사용자의 이동 경로에 따른 스토리라인 구성
  - 모바일 AR과 결합한 증강 현실 경험 제공

### 11.2 교육 및 치료적 활용
- **학습 도우미로 활용**
  - 학습 도구와 연결된 AI 튜터 기능
  - 맞춤형 학습 콘텐츠 추천 및 대화형 교육
  - 학습 진도와 이해도 추적 기능

- **감정적 지원 및 치료 보조**
  - 심리 치료 보조 도구로 활용(단, 전문가 감독 하에)
  - 감정 표현 및 사회적 상호작용 연습
  - 일상 루틴 관리 및 정서적 안정 지원

### 11.3 대화형 IoT 통합
- **스마트홈 시스템과 연동**
  - IoT 기기와 연결하여 자연어로 기기 제어
  - 사용자 생활 패턴 학습 및 맞춤형 자동화 제안
  - 재미있는 페르소나를 통한 스마트홈 경험 향상

- **위치 기반 서비스 통합**
  - GPS 및 실내 위치 추적과 결합
  - 장소별 맞춤형 페르소나와 대화 경험 제공
  - 가상 가이드로서 실내 내비게이션 기능