README.md

---
title: NPC Social Network AI Simulation
emoji: 🤖
colorFrom: blue
colorTo: indigo
sdk: gradio
python_version: "3.11"
app_file: app.py
pinned: false
---

## 🗂️ Language | 언어 선택
- 🇰🇷 [한국어로 보기](#한국어-설명서)
- 🇺🇸 [Read in English](#english-documentation)
---
## 주요 버전 관리
- 1.0.0v:
> 자율 성장형 AI 에이전트 소셜 시뮬레이션 기본 동작 확인 완료
> Basic functionality verified for autonomous, self-growing AI agent social simulation.
<br>

---
## 한국어 설명서
# 🧠 자율 성장형 AI 에이전트 소셜 시뮬레이션
> 감정, 기억, 가치관을 가진 NPC들과 함께 살아가는 가상 세계

![Python](https://img.shields.io/badge/Python-3.11-blue?logo=python)
![Flask](https://img.shields.io/badge/Flask-Web_Framework-black?logo=flask)
![License](https://img.shields.io/badge/License-Restricted-red)
<br>

## 📝 1. 프로젝트 소개
이 프로젝트는 단순히 정해진 대사를 반복하는 게임 NPC를 넘어, 자체적인 감정, 기억, 성격, 관계를 바탕으로 상호작용하며<br>
<strong>스스로 판단하고 성장하는 가상 인간(AI Agent)</strong>을 구현하는 AI 시뮬레이션입니다.

- **플랫폼**: 웹 기반 (Python + Flask)
- **핵심 기술**: LLM (Gemini), Sentence-TransFormers, FAISS
- **주요 기능**: 자율 행동, 기억 기반 대화, 가치관 형성, 성격/관계 변화, 플레이어 개입 등
<br>

## 🚀 2. 주요 기능 및 시스템
### 🧩 동적 멀티턴 대화 시스템
- 단답형 문답을 넘어, NPC의 감정, 기억, 관계를 활용한 깊이 있는 대화

### 🧠 자율 에이전트 아키텍처
- LLM 기반 Reasoner/Planner가 장기 목표와 행동 계획을 자율적으로 생성

### 🔍 고차원 자아 성찰 기능
- NPC는 관계를 재정의하고 스스로의 가치관을 점진적으로 형성

### 🧭 상황 인지 기반 사회적 행동
- "도움 주기" 등의 사회적 행동이 메모리와 관계에 영향을 줌

### 🧠 RAG 기반 기억 시스템
- FAISS를 통한 의미적 기억 검색 및 활용 (Sentence-Transformers + LLM)

### 🕹️ 플레이어 개입 시스템
- 관계 설정, 이벤트 유도 등으로 NPC 세계에 실시간 개입 가능
<br>

## 🖼️ 3. 시각화: 월드 관찰자 대시보드
> NPC들의 내면 상태와 관계 변화를 실시간으로 시각화하는 웹 기반 대시보드입니다.<br>
![Dashboard Example](/npc_social_network/static/images/assets/dashboard_example.png)
<br>

## 🧰 4. 사용 기술 스택
- **AI/ML**: Google Gemini, Sentence-Transformers, FAISS
- **Frontend**: HTML, CSS
- **Backend**: Python 3.10, Flask
- **Memory Architecture**: RAG
<br>

## ⚙️ 5. 설치 및 실행 방법
```bash
# 1. 클론
git clone http://github.com/Rorshi/autonomous-ai-agent-sim.git
cd autonomous-ai-agent-sim

# 2. 필요 라이브러리 설치
pip install -r requirements.txt

# 3. 실행
python app.py
http://127.0.0.1:5000 접속

# 4. LLM 모델 선택 및 API Key 입력

# 5. 시작 설정(선택 사항)
autonomous-ai-agent-sim\npc_social_network\scenarios\scenario_setup.py 파일 수정
```

## 🤝 6. 기여 / 라이선스
- 이 프로젝트는 **개인 포트폴리오 및 연구 목적**으로 제작되었습니다.
- 외부 사용자의 Issue 및 Pull Request는 검토 후 반영할 수 있습니다.
- 이 프로젝트의 저작권은 <strong>[@Rorshi](https://github.com/Rorshi)</strong>에게 있으며, 무단 사용, 수정, 배포를 금지합니다.
> ✉️ 이용 및 협업 문의: [email protected]

<br>
<br>

---
## English Documentation
# 🧠 Autonomous AI Agent Social Simulation  
> A virtual world where NPCs grow through emotion, memory, and personal values

![Python](https://img.shields.io/badge/Python-3.11-blue?logo=python)
![Flask](https://img.shields.io/badge/Flask-Web_Framework-black?logo=flask)
![License](https://img.shields.io/badge/License-Restricted-red)
<br>

## 📝 1. Project Overview

This project aims to go beyond traditional NPCs with predefined dialogue.  
It simulates **virtual humans (AI Agents)** capable of autonomous interaction, emotion, memory, personality, and growth.

- **Platform**: Web-based (Python + Flask)  
- **Core Technologies**: LLM (Gemini), Sentence-Transformers, FAISS  
- **Key Features**: Autonomous behavior, memory-based dialogue, evolving values and personality, player intervention  
<br>

## 🚀 2. Key Features and Systems

### 🧩 Dynamic Multi-turn Dialogue System  
- NPCs engage in deep, contextual conversations based on emotion, memory, and relationships

### 🧠 Autonomous Agent Architecture  
- Each NPC utilizes LLM-based Reasoners and Planners to formulate long-term goals and actionable plans

### 🔍 Higher-Order Cognitive Reflection  
- NPCs redefine their relationships and gradually form personal values over time

### 🧭 Context-Aware Social Behavior  
- NPCs perform social actions like "helping" and simulate their effects on memory and relationships

### 🧠 RAG-based Memory System  
- Semantic memory retrieval using FAISS + Sentence-Transformers to enhance dialogue relevance

### 🕹️ Player Intervention System  
- Players can modify relationships or trigger events to observe and influence NPC responses in real time  
<br>

## 🖼️ 3. Visualization: World Observer Dashboard  
> A web-based dashboard that visualizes NPCs' internal states and relationship changes in real time  
![Dashboard Example](/npc_social_network/static/images/assets/dashboard_example.png)  
<br>

## 🧰 4. Technology Stack

- **AI/ML**: Google Gemini, Sentence-Transformers, FAISS  
- **Frontend**: HTML, CSS  
- **Backend**: Python 3.10, Flask  
- **Memory Architecture**: RAG (Retrieval-Augmented Generation)  
<br>

## ⚙️ 5. Setup & Run Instructions

```bash
# 1. Clone the repository
git clone http://github.com/Rorshi/autonomous-ai-agent-sim.git
cd autonomous-ai-agent-sim

# 2. Install required packages
pip install -r requirements.txt

# 3. Run the app
python app.py
# Access the app at:
http://127.0.0.1:5000

# 4. Choose LLM model and enter your API key

# 5. (Optional) Configure initial setup
Edit the file:
autonomous-ai-agent-sim\npc_social_network\scenarios\scenario_setup.py
```

## 🤝 6. Contribution & License
This project is intended for personal portfolio and research purposes.

External contributions via Issues and Pull Requests are welcome and will be reviewed case-by-case.

All rights reserved by @Rorshi.
Unauthorized use, modification, or redistribution is strictly prohibited.

> ✉️ For inquiries or collaboration requests: [email protected]

<br>

[Back to top](#한국어-설명서)