README.md

---
title: 물魂(물건의 혼) - 사물 페르소나 생성기
emoji: 🧸
colorFrom: indigo
colorTo: blue
sdk: gradio
sdk_version: 5.30.0
app_file: app.py
pinned: false
---



# 물魂 (물건의 혼) - 사물 페르소나 생성기

사물에 인격을 부여하여 대화할 수 있는 페르소나 생성 및 테스트 도구입니다.

## 프로젝트 개요

물魂(물건의 혼) 프로젝트는 일상 사물에 독특한 성격과 개성을 부여하여 사용자와 대화할 수 있는 페르소나를 생성하는 연구 도구입니다. 이 도구는 사물의 물리적 특성에서 성격적 특성을 도출하고, 매력적인 페르소나를 구축하여 대화 상호작용을 탐구하는 데 중점을 둡니다.

## 주요 기능

- **이미지 기반 분석**: 사물 이미지를 분석하여 물리적 특성에서 성격 특성을 추론
- **직관적인 페르소나 생성**: 슬라이더, 선택 버튼 등 다양한 UI 요소를 통한 손쉬운 페르소나 설계
- **LLM 기반 페르소나 강화**: Google Gemini API를 활용한 페르소나 특성 강화 및 세부화
- **대화 시뮬레이션**: 생성된 페르소나와 대화 테스트 및 상호작용
- **페르소나 라이브러리**: 생성된 페르소나 저장 및 관리
- **대화 기록 및 분석**: 대화 내용 저장, 통계 분석, JSON 형식 내보내기

## 사용 기술

- **Gradio**: 직관적인 웹 UI 구현
- **Google Gemini API**: LLM 기반 페르소나 생성 및 대화 응답 생성
- **PIL/Pillow**: 이미지 처리 및 분석
- **Python**: 백엔드 로직 구현

## 설치 방법

### 1. 필수 조건

- Python 3.9 이상
- Google AI Studio API 키 (Gemini Pro 모델 접근 권한)

### 2. 설치 과정

1. 저장소 클론:
```bash
git clone https://github.com/your-username/memory_tag_mvp.git
cd memory_tag_mvp/연구/persona_creator
```

2. 가상 환경 생성 및 활성화:
```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows
```

3. 의존성 패키지 설치:
```bash
pip install -r requirements.txt
```

4. 환경 변수 설정:
`.env` 파일을 프로젝트 루트 디렉토리에 생성하고 다음 내용 추가:
```
GEMINI_API_KEY=your_api_key_here
```

또는 시스템 환경 변수로 설정:
```bash
# Linux/Mac
export GEMINI_API_KEY=your_api_key_here

# Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key_here"

# Windows (Command Prompt)
set GEMINI_API_KEY=your_api_key_here
```

> ⚠️ **중요**: Google AI Studio에서 Gemini API 키를 발급받아야 합니다. 발급 방법은 [Google AI Studio](https://ai.google.dev/) 웹사이트를 참조하세요.

5. 아이콘 파일 준비:
```
assets/icons/persona_avatar.png
```
경로에 페르소나 아바타 이미지 파일(PNG 형식)을 추가하세요. 아이콘 이미지는 원형이나 정사각형 형태의 512x512 픽셀 크기를 권장합니다.

아이콘 파일이 없는 경우 다음 명령어로 임시 아이콘을 생성할 수 있습니다:
```python
from PIL import Image, ImageDraw
import os

# 디렉토리 확인
if not os.path.exists("assets/icons"):
    os.makedirs("assets/icons", exist_ok=True)

# 기본 아이콘 생성
img = Image.new('RGBA', (512, 512), (79, 70, 229, 255))  # 인디고 배경
draw = ImageDraw.Draw(img)
draw.ellipse((100, 100, 412, 412), fill=(255, 255, 255, 255))  # 흰색 원
img.save('assets/icons/persona_avatar.png')
```

### 3. 실행 방법

```bash
python app.py
```

웹 브라우저에서 `http://localhost:7860`으로 접속

## 사용 방법

### 페르소나 생성

1. **사물 정보 입력**: 이름, 유형, 나이/사용 기간, 설명을 입력합니다.
2. **이미지 분석(선택사항)**: 사물 이미지를 업로드하여 물리적 특성 기반의 성격 특성을 자동으로 추출합니다.
3. **성격 특성 조정**: 슬라이더를 사용하여 온기, 능력, 신뢰성 등의 성격 특성을 조정합니다.
4. **소통 방식 설정**: 대화 스타일, 유머 유형, 말투 패턴을 설정합니다.
5. **관계 성향 설정**: 애착 스타일, 관계 깊이 선호도, 초기 태도를 선택합니다.
6. **페르소나 생성**: "페르소나 생성하기" 버튼을 클릭하여 LLM을 통해 페르소나를 강화하고 생성합니다.

### 대화 테스트

1. **대화 시작**: 생성된 페르소나를 선택하고 "대화 시작하기" 버튼을 클릭합니다.
2. **메시지 입력**: 텍스트 입력창에 메시지를 입력하고 전송합니다.
3. **대화 내용 저장**: 대화가 끝나면 "대화 내용 저장" 버튼으로 대화를 JSON 형식으로 저장합니다.

### 페르소나 라이브러리

1. **저장된 페르소나 탐색**: 생성한 모든 페르소나를 확인하고 관리합니다.
2. **페르소나 불러오기**: 저장된 페르소나를 에디터로 불러와 수정하거나 대화 테스트로 불러와 대화할 수 있습니다.

## 프로젝트 구조

```
persona_creator/
├── app.py                     # 메인 그라디오 애플리케이션
├── requirements.txt           # 파이썬 패키지 의존성
├── packages.txt               # 시스템 패키지 (HF Spaces용)
├── 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 # 재질-성격 매핑 규칙
│   ├── personality_templates/ # 카테고리별 기본 성격 템플릿
│   ├── conversation_logs/     # 대화 기록 저장소
│   └── user_personas/         # 사용자 생성 페르소나
├── styles/
│   └── custom.css             # UI 커스텀 스타일
└── assets/
    ├── examples/              # 예시 이미지
    └── icons/                 # UI 아이콘
        └── persona_avatar.png # 페르소나 아바타 이미지
```

## 허깅페이스 스페이스 배포

이 프로젝트는 허깅페이스 스페이스에 쉽게 배포할 수 있습니다:

1. 허깅페이스 계정 생성 및 로그인
2. 새 스페이스 생성 (Gradio App 선택)
3. 저장소 URL 연결 또는 파일 업로드
4. 환경 변수에 `GEMINI_API_KEY` 설정
5. 스페이스 설정에서 Python 패키지와 시스템 패키지가 올바르게 설치되는지 확인

## 연구 용도

이 프로젝트는 다음과 같은 연구 목적으로 활용됩니다:

1. **사물 인격화의 심리적 영향**: 사물에 인격을 부여했을 때 사용자의 인식과 상호작용 패턴 연구
2. **매력적 캐릭터 요소 분석**: 어떤 성격 특성 조합이 가장 매력적이고 상호작용하기 쉬운지 탐구
3. **관계 형성 패턴**: 페르소나와의 지속적 상호작용에서 형성되는 관계의 특성 연구
4. **물리적-성격적 특성 매핑**: 사물의 물리적 특성이 어떻게 성격적 특성으로 인지되는지 분석

## 제한사항

- 현재 버전은 연구 및 개발 목적으로 제공됩니다.
- Gemini API 키가 필요하며, API 사용량 제한에 따라 기능이 제한될 수 있습니다.
- 이미지 분석 기능은 현재 더미 분석을 제공하며, 향후 더 정교한 컴퓨터 비전 모델로 대체될 예정입니다.

## 라이센스

이 프로젝트는 MIT 라이센스 하에 배포됩니다.