powershell -ExecutionPolicy Bypass -File quick_setup.ps1

# Windows
powershell -ExecutionPolicy Bypass -File setup-deps.ps1

> 
이 스크립트는 다음을 수행합니다:
> - OS 및 GPU 환경을 감지합니다.
> - https://github.com/comfyanonymous/ComfyUI에서 ComfyUI를 클론합니다.
> - https://github.com/RVC-Boss/GPT-SoVITS에서 GPT-SoVITS를 클론합니다.
> - 새로운 경로로 `config.yaml`을 업데이트합니다.
> 
설정이 완료되면 **download-models.ps1** → **setup-llama.ps1** → **start.ps1** 순서로 진행하세요.

## 🎬 데모

### 다중 채널 채팅
![QQ Bot Demo](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/demo_qqbot.gif)

👆 QQ Bot: 텍스트 채팅 + TTS 음성 + ComfyUI 이미지 생성 + 캐릭터 메모리

### Live2D 데스크톱 펫
![Live2D Demo](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/demo_live2d.gif)

> 👆 **Shiki Natsume** Live2D: 감정 기반 모션, 립싱크, 말풍선이 포함된 실시간 캐릭터 애니메이션. 로컬 HTTP 브리지를 통해 제어됩니다.

### ⭐ ATRI - 두 번째 AI 여자친구

**나츠메와 성격이 반대**, 격리 메모리와 함께 교체 가능합니다.

![ATRI Live2D](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/atri_live2d.gif)

> 👆 **ATRI** Live2D: 은발, 루비 레드 눈, 흰 드레스를 입고 맨발 - 순수하고 표현력이 풍부함.

![ATRI ComfyUI](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/atri_comfyui.gif)

> 👆 **ATRI** ComfyUI: AI 이미지 생성 - 바닷가 일몰, 흐르는 듯한 흰 드레스, 따뜻한 골든아워 조명.

### ⭐ Yono Sakura - 세 번째 AI 여자친구

**침착한 수호 선배**, 학생회장 겸 학원 최강 전투원 - 이제 당신의 데스크톱 동반자가 됩니다.

![Sakura Desktop Pet](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/sakura_demo.gif)

> 👆 **Yono Sakura** 데스크톱 펫: 은핑크 그라데이션 머리, 연한 파란 눈, 교복 - 반응형 초상화 표현, 선제적 케어 알림, 그리고 GPT-SoVITS를 통한 실시간 TTS 음성.

### 🌐 웹 채팅 프론트엔드

![Web Chat Demo](https://raw.githubusercontent.com/momori777/Artemis/HEAD/media/webchat-demo.gif)

> 👆 **웹 채팅**: `http://127.0.0.1:19270`의 브라우저 기반 채팅 인터페이스 - QQ/Telegram 봇의 대안입니다. 로컬 데몬 프록시 → llama.cpp 서버에 직접 연결됩니다. 8 GB VRAM으로 중단 없이 완전히 실행할 수 있습니다.

### 🎙️ TTS 음성
🔊 **듣기** (클릭하여 재생, ATRI 일본어):

🎧 [tts_atori.mp3](media/tts_atori.mp3) *(46KB, 브라우저에서 재생)*

### 🎨 ComfyUI 이미지 워크숍
<video src=

🚀 더 이상 '미래' 계획이 아닙니다. 지금 작동합니다: [Qwen-Drive-1.0-4B](https://huggingface.co/Qwen/Qwen-Drive-1.0-4B)

📖 전체 설계: [`imagination.md`](imagination.md) | 브릿지 참조: [`skills/cosmos/BRIDGE_REFERENCE.md`](skills/cosmos/BRIDGE_REFERENCE.md)

**NVIDIA Cosmos** (커뮤니티 FP8 양자화 모델은 `skills/cosmos/`에 보관됨)는 물리적으로 일관성 있는 장면 비디오를 생성하고 공간적 관계를 이해하는 월드 파운데이션 모델(World Foundation Model)입니다.

### Cosmos가 필요한 이유?

네 가지 핵심 기능(LLM + TTS + ComfyUI + Live2D)은 현재 **분리되어** 있습니다. LLM은 Live2D가 무엇을 하는지 알지 못하며, ComfyUI는 대화의 감정을 감지하지 못합니다. Cosmos는 **물리적 상식 계층(physical common-sense layer)**을 채워줍니다:

### 이중 소형 아키텍처(Dual Compact Architecture)

| 구성 요소 | 모델 | 파라미터 | VRAM |
|---|---|---|---|
| 🧠 언어 지능 (Language Mind) | Qwen3.6-35B-A3B (MoE) | 총 35B / 활성 3B | ~8 GB |
| 🌍 물리 지능 (Physical Mind) | Cosmos 3 Nano FP8 | 15.75B | ~16 GB |

### 하드웨어 로드맵

| 연도 | GPU | Cosmos 상태 |
|---|---|---|
| 2026 | RTX 5070 (8-12GB) | ❌ 보관됨, 감지 준비 완료 |
| 2027-01 | RTX 5070 Ti Super (24 GB) | ✅ 이미 완료 |

### 현재 상태

- ✅ `skills/cosmos/`에 레포지토리(Repo)가 보관됨
- ✅ 브릿지 설계 `imagination.md` + `cosmos_check.py` 준비 완료
- ✅ Qwen ↔ Cosmos 이중 지능 아키텍처 설계 완료
- ✅ 2027-01: RTX 5070 Ti Super (24 GB) — 이미 구동 중

## 기능(Features)

- 🔄 **다중 캐릭터 핫스왑(Multi-Character Hot-Swap)** - AI 여자친구 간 원클릭 전환 가능 (Natsume ⇄ ATRI ⇄ Sakura); SOUL/IDENTITY/TTS 가중치/Live2D 모델이 모두 자동 전환되며, 메모리는 캐릭터별로 격리됩니다.
- 🃏 **SillyTavern 캐릭터 카드 가져오기(Character Card Import)** - PNG/JSON 캐릭터 카드를 자동 감지 및 가져옵니다; 에이전트가 가져오는 즉시 페르소나를 자동으로 전환합니다.
- 💬 **채팅 로그 가져오기(Chat Log Import)** - SillyTavern JSONL 대화 로그를 `memory/role_play/<character>/`에 가져와 저장합니다; 에이전트는 역할 전환 시 컨텍스트를 복원합니다.
- 🎤 **TTS 음성 합성(Voice Synthesis)** - 로컬 GPT-SoVITS 추론, 일본어 음성 (대화별 감정 일치), 3가지 캐릭터 음성 모델 (Natsume / ATRI / Sakura)
- 🎤 **ASR 음성 인식(Speech Recognition)** - 로컬 Faster-Whisper small 모델 (~1.5GB VRAM), llama와 공존; 99개 언어 지원
- 🎨 **AI 이미지 생성(Image Generation)** - 로컬 ComfyUI 추론, SDXL/Illustrious 모델, 3가지 캐릭터 프롬프트 템플릿
- 🖥️ **Sakura 데스크톱 펫(Desktop Pet)** - 능동적인 케어, 화면 관찰 및 로컬 LLM 인지 기능을 갖춘 PySide6 데스크톱 동반자; 3가지 캐릭터 지원
- 🎭 **Live2D 캐릭터 모델(Character Model)** - 감정 기반 표현 및 말풍선이 있는 실시간 Live2D 렌더링 (Natsume / ATRI L2D; Sakura 초상화 모드)
- 🧠 **스마트 VRAM 계층화(Smart VRAM Tiering)** - GPU VRAM을 자동 감지하고 적절한 전략을 선택합니다: ≥12GB는 모든 것을 온라인 상태로 유지 (llama + 스킬); 8GB는 GPU 집약적 작업을 위해 llama를 핫스왑; <8GB는 안전 모드.

제로 수동 설정
- 🎛️ **Artemis Studio Console** - Visual TTS + ComfyUI 워크샵, llama 상태와 무관하게 언제든지 DIY 음성 및 이미지 제작 가능 - 진정한 오프라인 크리에이티브 스위트
- 💾 **역할극 메모리(Roleplay Memory)** - `memory/role_play/` 디렉토리 내 캐릭터별 일일 대화 요약본
- 🧠 **장기 기억 시스템(Long-term Memory System)** - [headroom](https://github.com/chopratejas/headroom) (SmartCrusher + CCR) 및 [mem0](https://github.com/mem0ai/mem0) (Qdrant 벡터 데이터베이스) 기반:
  - **중국어 임베딩 부스트(Chinese Embedding Boost)** - 모든-MiniLM-L6-v2와 함께 BGE-small-zh-v1.5를 추가하여 CN/JP/EN 하이브리드 메모리 검색의 정확도 향상
  - **SmartCrusher 컨텍스트 트리밍(Context Trimming)** - LLM 요청당 채팅 기록을 24 메시지 / 40K 문자열로 제한
  - **CCR (Curate-Consolidate-Retrieve)** - 백그라운드 워커가 매 8턴마다 지속 가능한 사실을 추출하여 mem0 Qdrant에 작성
  - **벡터 + BM25 하이브리드 검색(Vector + BM25 Hybrid Search)** - Qdrant를 통한 의미적 유사성 + 키워드 일치
  - **자동 동기화 브릿지(Auto-Sync Bridge)** - 크론 작업이 30분마다 Qdrant → `_mem0_auto.md`를 동기화하여 OpenClaw의 네이티브 `memory_search`로 벡터 메모리 검색 가능하게 함
  - **캐릭터별 격리(Per-Character Isolation)** - Qdrant에서 `user_id` 스코핑; 4개의 독립적인 메모리 공간 (sakura / natsume / enola / atori)
  - **회상 우선순위(Recall Priority)** - 벡터 장기 기억 > 손으로 작성한 일일 노트 > SOUL 기반 페르소나

> [skills/behavior-engine/README.md](skills/behavior-engine/README.md) 및 [AGENTS_roleplay_EN.md#behavior-engine](AGENTS_roleplay_EN.md#behavior-engine) 참조.

### 💖 관계 시스템 (행동 엔진, Behavior Engine)

별도의 프로젝트인 **girl-agent**에서 포팅된 **계층적 의사 결정 엔진(layered decision engine)**으로, 각 캐릭터에게 독립적인 관계 점수, 갈등 상태, 관계 단계, 그리고 호르몬 주기를 부여하여 그들의 행동과 답변 스타일을 구동합니다.

**핵심 루프:** 매 턴마다 무드 델타(moodDelta) (관심/신뢰/매력/짜증/역겨움)를 생성 → 점수에 누적됨 → 갈등 고조/진정기를 유발 → 관계 단계 전환을 자동 확인 → LLM의 답변 스타일을 형성합니다.

| Field | Range | 의미 | 효과 |
|-------|-------|---------|--------|
| `score.interest` | -100~100 | 관심도 (Interest) | 답장 온기, 주도성 |
| ... | 
**9가지 관계 단계:** 처음 만남 → 냉랭한 시기 → 분위기가 무르익음 → 설득됨 → 첫 데이트 → 초기 연애 → 안정적인 연애 → 장기적 관계 → 이별

**4단계 갈등 시스템:** 레벨 0 정상 → 레벨 1 약간의 토라짐 (slight sulk) → 레벨 2 짜증남 (in a huff) → 레벨 3 심각한 냉전 (severe cold war) → 레벨 4 차단/삭제 (blocked/deleted)

**호르몬 주기:** 가우시안 사이클 모델(Gaussian cycle model)은 에너지, 짜증, 애정, 성욕의 주기적인 변화를 시뮬레이션하여 답장의 길이와 분위기에 영향을 미칩니다.

**상태 파일 (State file):** `memory/role_play/<char>/relationship.json` (캐릭터별 독립적이며, 핫 로딩(hot-loaded)됨)
**모듈 위치 (Module location):** `skills/behavior-engine/`

## 모델 (Models)

HuggingFace에 호스팅된 모든 모델: **[TAOTAO777/ai-girlfriend-natsume](https://huggingface.co/TAOTAO777/ai-girlfriend-natsume)**

자세한 내용은 [`models.yaml`](models.yaml)을 참조하세요.

| 모델 | 용도 | 크기 | 컨텍스트 |
|---|---|---|---|
| **LuffyTheFox Qwen3.6-35B-A3B Genesis Hermes V13 MTP APEX Compact** (GGUF) | 채팅 LLM (주요 MoE) | 16.11 GB | 120K |
| ... | 
> 📁 임베딩 모델 경로: `embedding/all-MiniLM-L6-v2/` + `embedding/bge-small-zh-v1.5/` (HF 리포지토리)

### 원클릭 다운로드 (One-command Download)

```powershell
# huggingface-cli 설치: pip install huggingface_hub
huggingface-cli login

...