README.md

metadata

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

git clone https://github.com/your-username/memory_tag_mvp.git
cd memory_tag_mvp/연구/persona_creator

2. 가상 환경 생성 및 활성화:

python -m venv venv
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

3. 의존성 패키지 설치:

pip install -r requirements.txt

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

GEMINI_API_KEY=your_api_key_here

또는 시스템 환경 변수로 설정:

# 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 웹사이트를 참조하세요.

5. 아이콘 파일 준비:

assets/icons/persona_avatar.png

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

아이콘 파일이 없는 경우 다음 명령어로 임시 아이콘을 생성할 수 있습니다:

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. 실행 방법

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 라이센스 하에 배포됩니다.