# 🧠 README - NPC 소셜 네트워크 AI 시뮬레이션

본 문서는 본 프로젝트를 **제로 베이스에서 완전 재현**할 수 있도록 설계되었습니다.
지금까지의 구조, 설계 철학, 구현 단계, 각 파일 기능을 **단 하나의 문서로 완전하게 정리**한 공식 문서입니다.

---

## 📌 프로젝트 개요 (Overview)

이 프로젝트는 감정, 기억, 성격, 관계, 행동을 기반으로 한 **인간 유사 NPC 시뮬레이션**입니다.
단순히 정해진 대사를 반복하는 게임 NPC를 넘어, 자체적인 감정, 기억, 성격, 관계를 가지고 다른 NPC나 플레이어와 상호작용하며 스스로 판단하고 성장하는 가상 인간(AI Agent)을 구현하는 것을 목표로 하는 AI 시뮬레이션입니다.
모든 NPC의 내면 상태와 관계 변화는 웹 기반의 **'월드 관찰자 대시보드'**를 통해 실시간으로 시각화되고 분석됩니다.

핵심 기술: Python, Flask, LLM (Google Gemini), Sentence-Transformers, FAISS

주요 기능:
 - 자체 설계된 4계층 감정 모델에 따른 동적인 감정 변화
 - 의미 기반 검색(Vector Search)을 활용한 장/단기 기억 시스템
 - 상호작용에 따라 변화하는 사회적 관계망
 - 경험을 통해 점진적으로 변화하는 다차원 성격 모델
 - LLM을 이용한 자율적인 목표 설정 및 대화 생성

---

## 📁 폴더 구조

```
portfolio/
├── templates/
│   └── main.html               # 포트폴리오 메인 페이지
│
├── app.py                         # Flask 진입점
├── requirements.txt
├── test.ipynb
└── npc_social_network/
    │
    ├── __init__.py
    ├── simulation_core.py      # ✅ 시뮬레이션의 '심장'. 상태 관리 및 시간 흐름(tick) 담당
    ├── README.txt
    │
    ├── data/
    │   ├── saves/
    │   │   └── simulation_state.pkl  # NPC 월드의 상태가 저장되는 파일
    │   └── vectorstores/
    │       └── 영문 캐릭터명           # 각각의 캐릭터에 대한 정보가 저장되는 파일
    │
    ├── routes/
    │   └── npc_route.py              # ✅ '월드 관찰자' 대시보드의 모든 웹 API 정의
    │
    ├── manager/
    │   ├── conversation_manager.py     # 대화의 시작, 진행, 종료를 총괄하는 역할
    │   └── simulation_manager.py       # 시뮬레이션 상태를 저장/로드하는 기능
    │
    ├── scenarios/
    │   └── scenario_setup.py         # 시뮬레이션 초기 월드(NPC, 관계) 설정
    │
    ├── npc/                          # NPC의 '두뇌'를 구성하는 핵심 로직
    │   ├── npc_base.py               # NPC 본체 (감정/기억/관계 포함)
    │   ├── npc_manager.py            # NPC 리스트 관리
    │   ├── npc_emotion.py            # EmotionManager
    │   ├── npc_memory.py             # Memory / MemoryStore
    │   ├── npc_behavior.py           # 감정 → 행동 매핑
    │   ├── npc_relationship.py       # 관계 점수 관리
    │   ├── npc_memory_embedder.py    # 기억 임베딩 + FAISS 검색
    │   ├── emotion_config.py         # 감정 구조 정의
    │   ├── personality_config.py     # 성격 및 나이 프로필
    │   └── npc_planner.py            # 목표와 관련된 구조
    │
    ├── models/                       # LLM 및 임베딩 모델 관련
    │   ├── gemini_setup.py           # Gemini API 설정
    │   └── llm_helper.py             # 감정 추론, 응답 생성
    │
    ├── templates/
    │   └── dashboard.html            # '월드 관찰자' 대시보드 HTML/CSS/JS
    │
    └── static/
        ├── css/style.css
        ├── js/npc_chat.js
        └── images/
    │       └── npc/              # NPC 이미지 파일 (예: npc_elin.png)

```

---

## 💡 감정 구조 (고차원 감정 모델)

> ✅ **GoEmotions에서 영감을 받아 직접 재설계한 4계층 감정 모델 (ComplexEmotions)**

| 계층 (Layer) | 감정 예시 |
|--------------|------------|
| `core`       | joy, sadness, anger, fear, disgust, surprise, neutral |
| `social`     | gratitude, shame, empathy, pride, jealousy, compassion, love, admiration, awe, attachment, comfort |
| `cognitive`  | anticipation, curiosity, confusion, interest, engagement, boredom, relief, anxiety, calm, skepticism |
| `complex`    | nostalgia, bittersweet, schadenfreude, resentment, anticipatory_joy, regret, rumination, hope, groundedness |

- 감정은 개성(`sensitive`, `stoic`, `*_bias`)에 따라 감정 반응 및 decay 속도가 달라집니다.
- 감정은 행동, 기억 생성, 관계 변화, 성격 변화에 직접 반영됩니다.

---

## 🧠 핵심 시스템 설명

### ✅ 감정 시스템
- `EmotionManager`: 감정 버퍼 관리, decay, 감정 업데이트
- 감정은 최대 100.0까지 누적되며, decay는 personality와 연계됨
- 감정은 행동 생성, 기억 저장 강도, 관계 영향, 성격 변화의 기반이 됨

### ✅ 기억 시스템
- `Memory`: content, timestamp, importance, emotion, type 보유
- `MemoryStore`: 단기/장기 기억 분리, decay, 승격, 검색 기능 포함
- decay는 memory_type별로 다르게 적용됨

### ✅ 성격 시스템
- `PERSONALITY_PROFILE`: stable/emotional/logical
- `AGE_PROFILE`: 인생 단계별 변화율 (예: 어린이는 빠름)
- 기억에 기반해 personality gradually drift (ex: 감정적이거나 이성적 성향 강화)

### ✅ 관계 시스템
- `RelationshipManager`: -100 ~ +100 범위의 관계 점수 관리
- 감정 표현 및 기억이 관계에 영향을 줌 (`reflect_memory_on_relationship`)

### ✅ 행동 시스템
- 감정 → 행동 시퀀스로 변환 (`BehaviorManager`)
- 행동은 기억에 기록되고, 다시 감정에 영향을 줌 (역매핑)

### ✅ LLM 시스템
- `query_llm_for_emotion`: 감정 추론용 LLM 호출
- `query_llm_with_prompt`: 대사 생성용 LLM 호출
- `build_npc_prompt`: 감정/기억 기반 프롬프트 생성
- `summarize_memories`: 장기 기억 요약

### ✅ 임베딩 시스템
- `npc_memory_embedder.py`:
    - `embed_npc_memories`: FAISS 저장
    - `search_similar_memories`: 질의 유사도 검색
    - 모델: `all-MiniLM-L6-v2` 사용 중

---

주요 흐름 (generate_dialogue 함수 기준):
 1. 사건 발생: 플레이어나 다른 NPC로부터 대화(user_input)가 시작됩니다.
 2. 기억 탐색: 입력된 대화 내용과 의미적으로 가장 유사한 과거의 기억들을 벡터 검색(FAISS)을 통해 즉시 찾아냅니다. (npc_memory_embedder.py)
 3. 상황 판단: 현재 NPC의 감정 상태, 성격, 상대방과의 관계, 방금 찾아낸 관련 기억 등 모든 정보를 종합하여 LLM에게 전달할 상세한 '상황 보고서(Prompt)'를 작성합니다. (llm_prompt_builder.py)
 4. 의사 결정 (대화 생성): LLM은 이 상황 보고서를 바탕으로, 현재 상황에 가장 적절한 대사를 생성합니다. (llm_helper.py)
 5. 내면의 변화:
    - 생성된 대사에 담긴 감정을 스스로 추론하여 자신의 감정 상태를 업데이트합니다. (npc_emotion.py)
    - 이 상호작용을 하나의 새로운 기억으로 저장합니다. (npc_memory.py)
    - 발생한 감정의 종류와 강도에 따라 상대방과의 관계 점수를 조절합니다. (npc_relationship.py)
    - 이 중요한 경험은 NPC의 성격에 아주 미세한 영향을 미치며, 장기적으로 NPC를 변화시킵니다. (npc_base.py의 update_personality)

이 모든 과정이 단 한 번의 대화 속에서 일어나며, NPC를 시간이 지남에 따라 성장하고 변화하는 입체적인 존재로 만듭니다.

---

## 📦 실행 방법

```bash
conda activate portfolio

# Flask 웹 서버 실행
python portfolio/app.py
# → http://127.0.0.1:5000/npc_social_network/

```

---

🗺️ 프로젝트 로드맵 (Roadmap)
본 프로젝트는 여러 단계를 거쳐 발전해왔으며, 현재는 '내면 세계'와 '웹 기반 관찰 시스템'의 핵심 기능 구현을 완료하고, 더 깊이 있는 사회적 상호작용 구현을 앞두고 있습니다.

Phase 1: 내면 세계의 완성 (Core Engine & Intelligence) - ✅ 완료
NPC가 독립적인 개체로서 생각하고 느낄 수 있는 핵심 두뇌를 구현했습니다.
4계층 감정 모델: Core, Social, Cognitive, Complex로 구성된 자체 감정 모델을 구현하여, NPC가 상황에 따라 다채로운 감정을 느끼도록 설계했습니다.
RAG 기반 기억 시스템: Sentence-Transformers와 FAISS를 이용, 대화의 맥락과 의미적으로 가장 관련 깊은 과거 기억을 찾아내어 대화에 활용하는 검색-증강 생성(RAG) 시스템을 구축했습니다.
동적 관계/성격 시스템: 모든 상호작용은 관계 점수에 영향을 미치며, 누적된 경험은 NPC의 성격을 점진적으로 변화시킵니다.
자율 에이전트(Planner): LLM을 활용하여 NPC가 스스로 자신의 상태를 진단하고, 장기적인 목표와 그것을 달성하기 위한 구체적인 계획을 수립하는 기능을 구현했습니다.

Phase 2: 월드 관찰자 대시보드 구축 (Web-based Visualization) - ✅ 완료
NPC의 복잡한 내면과 관계 변화를 직관적으로 관찰하고, 시뮬레이션에 개입할 수 있는 웹 기반 대시보드를 완성했습니다.
실시간 관계 네트워크: vis-network 라이브러리를 사용하여 NPC 간의 관계(친구, 적 등)와 그 강도를 시각적인 그래프로 구현했습니다.
NPC 상세 정보 패널: 특정 NPC를 클릭하면, 해당 NPC의 현재 감정, 목표, 최근 기억 등 모든 내면 상태를 실시간으로 확인할 수 있습니다.
시뮬레이션 시간 제어: Play/Pause, Next Tick 버튼을 통해 시뮬레이션의 시간 흐름을 제어하여, 특정 순간의 변화를 면밀히 관찰할 수 있습니다.
실시간 이벤트 로거: NPC 간의 상호작용, 목표 변경 등 월드에서 발생하는 모든 주요 이벤트를 실시간 로그로 확인할 수 있습니다.

'플레이어'의 요약된 기억 개입 도구: 특정 NPC 또는 모든 NPC에게 인위적인 이벤트를 과거의 기억으로 주입하여, 특별한 상황에 대한 NPC의 반응을 테스트할 수 있는 기능을 구현합니다.

Phase 3: 사회적 상호작용 심화 (Social Interaction Deepening) - ✅ 완료
이제 개별 NPC의 내면을 넘어, NPC들이 서로 영향을 주고받으며 하나의 '사회'를 형성하는 고차원적인 상호작용을 구현합니다.

1단계: 소문 및 평판 시스템 (Gossip & Reputation System):
구현 목표: NPC들 사이에 '소문'이 퍼지는 시스템을 구현합니다. 예를 들어, A와 B의 부정적인 상호작용을 C가 목격했을 때, C는 "A와 B가 다퉜다"는 소문을 다른 NPC에게 퍼뜨릴 수 있습니다.
기대 효과: 이 소문은 다른 NPC들의 A와 B에 대한 '평판'에 영향을 미치며, 이는 새로운 관계 변화의 원인이 됩니다. 플레이어의 개입 없이도 마을 전체의 관계망이 유기적으로 요동치는 모습을 관찰할 수 있습니다.

2단계: 개인 간 상호작용 심화
2-A. 멀티턴(Multi-turn) 대화 시스템: 여러 턴에 걸쳐 깊이 있는 대화를 나누는 기능. (가장 시급하고 효과가 큼)
2-B. 지능적 사회적 행동: '돕기', '선물 주기' 등 대화 외의 상호작용 추가.

3단계: 기능 추가 및 개선 사항 정리
3-A. 사회적 그룹 형성 (Clique Formation) - 나중에 진행
구현 목표: 관계 유형(friend, rival)과 평판을 기반으로 NPC들이 자동으로 그룹이나 파벌을 형성하는 시스템을 구현합니다.
기대 효과: NPC들은 자신이 속한 그룹의 구성원과 더 자주 긍정적인 상호작용을 하고, 경쟁 그룹의 구성원은 피하거나 부정적인 상호작용을 하는 등, 더욱 복잡하고 현실적인 사회적 행동을 보여주게 됩니다.

3-B. 플레이어 개입 및 관계 형성 시스템
구현 목표: 플레이어가 '신'의 관점에서 시뮬레이션에 직접 개입하여 새로운 관계나 사건을 만들어내는 기능을 구현.
주요 기능: '소개' 기능, 관계 강제 설정, 특정 상황 연출 등.

3-C. UI/UX 안정성 개선
구현 목표: 대시보드의 사용 경험을 개선합니다.
주요 기능: 관계도 그래프의 떨림 현상 해결, CSS 레이아웃 정리.

4단계: 고차원적 자아 기능 활성화
- 그룹 활동 등을 통해 얻은 새로운 경험을 바탕으로, NPC가 자신의 관계를 정리하거나 새로운 깨달음을 획득.
    - 1단계: 관계 재정의 (Relationship Redefinition)
        - 구현 목표: NPC가 특정 인물과의 관계를 스스로 되돌아보고, "A는 나에게 이런 존재야" 라고 자신만의 한 줄 요약 정의를 내리도록 합니다.
        - 동작 방식: 시뮬레이션 루프에서 낮은 확률로 이 함수를 호출합니다. 함수가 호출되면, NPC는 특정 대상과의 핵심 기억들을 다시 살펴보고, 그 관계에 대한 새로운 요약(summary)을 생성하여 자신의 내면에 저장합니다.

    - 2단계: 가치관 형성 (Value Formation)
        - 구현 목표: 수많은 경험(기억)을 통해, "정직이 최고의 가치이다" 또는 "가족을 지키는 것이 가장 중요하다"와 같은 **자신만의 신념이나 좌우명(상징 기억)**을 형성하도록 합니다.
        - 동작 방식: NPC가 충분한 경험(예: 기억 30개 이상)을 쌓았을 때, 시뮬레이션 루프에서 극히 낮은 확률로 이 함수를 호출합니다. 함수가 호출되면, NPC는 자신의 전체 기억을 종합하여 가장 핵심적인 깨달음을 하나의 '상징 기억'으로 만들어 저장합니다.

Phase 4: 자아와 윤리의 탐구 (Self & Ethics Exploration) - 🚀 장기 과제
NPC가 단순한 반응을 넘어, 스스로를 이해하고 도덕적인 판단을 내리는 고차원적인 자아를 탐구합니다.

윤리 시스템과 도덕적 딜레마 (Ethics & Moral Dilemmas):
구현 목표: NPC가 가진 '상징 기억'(예: "정직이 최고의 가치이다")을 핵심 가치관으로 활용합니다. 이 가치관에 반하는 도덕적 딜레마 상황(예: "가족을 살리기 위해 거짓말을 해야 하는가?")을 제시하고, NPC가 자신의 가치관과 상황 사이에서 어떤 결정을 내리는지 관찰합니다.

메타인지 및 자아 성찰 (Metacognition & Self-Reflection):
구현 목표: NPC가 "내가 왜 지금 슬픈 감정을 느끼지? 아, 어제 앨리스와 다퉜던 기억 때문이구나"와 같이 자신의 감정이나 생각의 원인을 스스로 추론하고 이해하는 '메타인지' 시스템을 구현합니다.

기대 효과: 이는 NPC가 단순한 감정 표현을 넘어, 자신의 내면 상태를 이해하고 설명할 수 있는 한 단계 더 높은 수준의 '자아'를 갖게 됨을 의미합니다.

Phase 5: 논문/연구 결과 정리 - 최종 과제
구현 목표: 진행한 내용을 토대로 IEEE 학회에 제출할 논문을 작성합니다.

참고 논문: 
[1] J. Park, J. S. Wu, T. N. Hashimoto, and M. S. Bernstein, "Generative Agents: Interactive Simulacra of Human Behavior," arXiv preprint arXiv:2304.03442, 2023.
[2] L. Li et al., "Evolving Agents: Interactive Simulation of Dynamic and Diverse Human Personalities," IEEE Transactions on Games, 2024.
[3] X. Cheng et al., "PsyMem: Fine-grained psychological alignment and Explicit Memory Control for Advanced Role-Playing LLMs," arXiv preprint arXiv:2505.12814, 2025.
[4] B. W. Roberts and D. Mroczek, "Personality Trait Change in Adulthood," Current Directions in Psychological Science, vol. 17, no. 1, pp. 31–35, 2008.
[5] C. J. Soto, "How replicable are links between personality traits and consequential life outcomes? The life outcomes of personality replication project," Psychological Science, vol. 27, no. 7, pp. 949–961, 2016.
[6] T. A. Klimstra, W. K. Luyckx, M. B. Hale III, S. J. Goossens, and W. Meeus, "Personality development in adolescence: Longitudinal analyses and associations with life events," Journal of Research in Personality, vol. 43, no. 3, pp. 345–354, 2009.
[7] J. Specht, B. Egloff, and S. C. Schmukle, "Stability and change of personality across the life course: The impact of age and major life events on mean-level and rank-order stability of the Big Five," Journal of Personality and Social Psychology, vol. 101, no. 4, pp. 862–882, 2011.
[8] W. Bleidorn, C. J. Hopwood, and R. E. Lucas, "Life Events and Personality Trait Change," Annual Review of Psychology, vol. 73, pp. 109–133, 2022.
[9] I. Puerta-Merino and J. Sabater-Mir, "LLM Reasoner and Automated Planner: A New NPC Approach," arXiv preprint arXiv:2501.10106, 2025.
[10] P. Chiang et al., "Collaborative Quest Completion with LLM-driven Non-Player Characters in Minecraft," arXiv preprint arXiv:2403.12329, 2024.
[11] K. Tsuchiya et al., "Leveraging Large Language Models for Active Merchant Non-player Characters," Proceedings of the 2024 CHI Conference on Human Factors in Computing Systems (CHI '24), 2024.

© 2025 NPC Social Network Simulation Project v3