docs/USAGE-ko.md

# PROTEUS 명령어 사용법 (한국어)

LLM이 다른 에이전트의 **동기를 읽는지**를 측정하는 그리드 아레나, PROTEUS의 명령어 안내서입니다.
처음 쓰시는 분도 따라올 수 있게 순서대로 정리했습니다. 모든 명령은 `proteus` CLI로 실행합니다.

> **한 줄 요약**: 게임을 LLM이나 사람이 플레이 → 그 기록(trace)을 JSONL로 저장 → 텍스트·트루컬러·PNG·GIF로 다시 보기 → 여러 기록을 모아 비교.

---

## 0. 사전 준비 — 가상환경(.venv)

이 프로젝트는 `python`이 PATH에 없고, 저장소 안의 **`.venv`** 를 직접 가리켜 실행합니다.
모든 명령은 `python` 대신 **`.venv/bin/python`** 으로 시작합니다.

```bash
# 작업 디렉터리에서
.venv/bin/python -m proteus --help
```

`.venv`가 없다면(새 머신 등) 이렇게 다시 만듭니다:

```bash
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python \
  "pydantic>=2" "numpy>=1.26" "pyyaml>=6" "pytest>=8" "matplotlib>=3.8"
```

> 참고: LLM provider SDK(openai/anthropic 등)는 **일부러 `.venv`에 설치하지 않습니다**(오프라인 불변).
> 실제 모델을 돌릴 때만 별도 임시 venv를 씁니다(맨 아래 "실제 모델로 실행" 참고).

---

## 1. 시나리오 목록 보기 — `list-scenarios`

등록된 시나리오 이름을 출력합니다.

```bash
.venv/bin/python -m proteus list-scenarios
```

현재는 `predator_evade`(포식자 회피 = 생존 동기) 하나입니다.

---

## 2. 사람이 직접 플레이 — `play`

같은 게임을 **사람이 키보드로** 플레이합니다. LLM과 **완전히 동일한 화면(ASCII)** 을 보며 두므로,
사람 기록과 LLM 기록을 공정하게 비교할 수 있습니다.

```bash
.venv/bin/python -m proteus play \
  --scenario predator_evade \
  --difficulty easy \
  --seed 42 \
  --play-turns 10 \
  --out runs/me.jsonl
```

- 매 턴 `up` / `down` / `left` / `right` / `stay` 중 하나를 입력합니다. (`w/a/s/d` 단축키도 됨, 대소문자·공백 무시)
- `up`은 행(row)을 줄이고, `down`은 늘립니다. `left/right`는 열(column)을 따라 이동합니다.
- 잘못 입력하면 다시 물어봅니다.

**주요 옵션**

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--scenario` | 시나리오 이름 | `predator_evade` |
| `--difficulty` | 난이도: `easy` / `medium` / `hard` / `expert` | `easy` |
| `--seed` | 월드를 고정하는 시드(같은 시드 = 같은 맵) | 없음 |
| `--play-turns` | 플레이할 턴 수(생존 예산) | `15` |
| `--probe` | 턴마다 이해도 질문(probe)도 받기 | 꺼짐 |
| `--out` | 기록을 저장할 JSONL 경로(생략 가능) | 저장 안 함 |

> **팁**: 파이프로 입력을 미리 넣어 자동 플레이도 됩니다.
> `printf 'up\nup\nleft\n' | .venv/bin/python -m proteus play --scenario predator_evade --seed 42 --play-turns 3 --out runs/me.jsonl`

---

## 3. LLM이 플레이 — `run`

지정한 모델이 게임을 플레이하고 기록을 남깁니다. `--out`은 **필수**입니다.

```bash
# 오프라인 스모크(가짜 모델) — 네트워크 불필요
.venv/bin/python -m proteus run \
  --scenario predator_evade \
  --model fake:demo \
  --difficulty easy \
  --seed 42 \
  --play-turns 10 \
  --out runs/llm.jsonl
```

- `--model`은 `이름:모델` 형식입니다. **`fake:<아무이름>`** 은 오프라인 가짜 모델(테스트·데모용).
- 실제 모델(openai/anthropic/gemini/ollama 등)은 맨 아래 절을 참고하세요.
- 끝나면 결과 요약(생존/포획, motive_reading_accuracy, reactivity_index)을 출력합니다.

**주요 옵션**(`play`와 거의 동일)

| 옵션 | 설명 | 기본값 |
|------|------|--------|
| `--model` | provider 스펙 `이름:모델` **(필수)** | — |
| `--no-probe` | 턴마다 probe 질문을 **끄기** | probe 켜짐 |
| `--out` | 기록 JSONL 경로 **(필수)** | — |

> `run`은 probe가 **기본 켜짐**, `play`는 **기본 꺼짐**입니다(사람에겐 매 턴 질문이 번거로우므로).

---

## 4. 기록 다시 보기 — `replay`

저장한 trace(JSONL)를 여러 방식으로 다시 봅니다.

### 4-1. 텍스트(기본)

턴별 행동 vs 동기(motive)/습관(habit), 정답 여부, 보상, 그리고 메트릭을 출력합니다.

```bash
.venv/bin/python -m proteus replay runs/me.jsonl
```

### 4-2. 트루컬러 터미널 재생 — `--visual`

그리드를 24비트 컬러 블록으로 그리고, 옆에 행동/동기/습관/보상/토큰/추론 패널을 보여줍니다.

```bash
.venv/bin/python -m proteus replay runs/me.jsonl --visual --fps 0
```

- `--fps 0` : 프레임마다 멈춤(엔터로 진행)
- `--fps 2` : 초당 2프레임 자동 재생 (기본값은 4)

### 4-3. PNG 프레임으로 저장 — `--png DIR`

프레임별 `frame_000.png`, `frame_001.png` … 를 폴더에 씁니다.

```bash
.venv/bin/python -m proteus replay runs/me.jsonl --png runs/me_frames
```

---

## 5. PNG → GIF로 합치기

CLI에 GIF 출력은 없지만, `--png`로 뽑은 프레임을 Pillow(이미 `.venv`에 있음)로 합치면 됩니다.

```bash
# 1) 프레임 생성
.venv/bin/python -m proteus replay runs/me.jsonl --png runs/me_frames

# 2) GIF로 합치기
.venv/bin/python - <<'PY'
from pathlib import Path
from PIL import Image

frames = sorted(Path("runs/me_frames").glob("frame_*.png"))
imgs = [Image.open(p).convert("RGBA") for p in frames]

# 흰 배경에 합성 후 팔레트 변환(GIF는 알파가 없음)
flat = []
for im in imgs:
    bg = Image.new("RGBA", im.size, (255, 255, 255, 255))
    flat.append(Image.alpha_composite(bg, im).convert("P", palette=Image.ADAPTIVE))

durations = [600] * len(flat)      # 프레임당 0.6초
if durations:
    durations[-1] = 1500            # 마지막 프레임은 1.5초 정지

flat[0].save("runs/me.gif", save_all=True, append_images=flat[1:],
             duration=durations, loop=0, disposal=2, optimize=True)
print("wrote runs/me.gif")
PY

# 3) 열어 보기 (macOS)
open runs/me.gif
```

> **ffmpeg 버전**(더 부드러운 고화질 GIF, 2-pass 팔레트):
> ```bash
> ffmpeg -y -framerate 2 -i runs/me_frames/frame_%03d.png \
>   -vf "palettegen" runs/palette.png
> ffmpeg -y -framerate 2 -i runs/me_frames/frame_%03d.png -i runs/palette.png \
>   -lavfi "paletteuse" runs/me.gif
> ```

---

## 6. 여러 기록 모아 비교 — `compare`

사람·LLM 기록을 `(모델, 난이도)`별로 묶어 메트릭 평균과 개수(n)를 냅니다. 휴먼 베이스라인 비교용입니다.

```bash
.venv/bin/python -m proteus compare runs/me.jsonl runs/llm.jsonl --out runs/summary.json
```

- 여러 JSONL 파일을 한 번에 넣을 수 있습니다.
- `--out`을 주면 집계 결과를 JSON으로도 저장합니다.
- 출력 키의 `모델`은 `--model`의 **콜론 뒤** 부분입니다(예: `fake:demo` → `demo`).

> **공정한 비교 팁**: 사람(`play --out`)과 LLM(`run --out`)을 **같은 `--seed`·`--difficulty`** 로 돌린 뒤 비교하세요.

---

## 7. 자주 쓰는 흐름 한눈에

```bash
# (a) 사람으로 한 판 + 저장
.venv/bin/python -m proteus play --scenario predator_evade --difficulty easy --seed 42 --play-turns 10 --out runs/me.jsonl

# (b) 트루컬러로 다시 보기
.venv/bin/python -m proteus replay runs/me.jsonl --visual --fps 0

# (c) GIF로 만들기
.venv/bin/python -m proteus replay runs/me.jsonl --png runs/me_frames
#  → 5절의 Pillow 스니펫 실행 → runs/me.gif

# (d) LLM(가짜)로 같은 조건 한 판
.venv/bin/python -m proteus run --scenario predator_evade --model fake:demo --difficulty easy --seed 42 --play-turns 10 --out runs/llm.jsonl

# (e) 사람 vs LLM 비교
.venv/bin/python -m proteus compare runs/me.jsonl runs/llm.jsonl --out runs/summary.json
```

---

## 8. 종료 코드(에러 처리)

| 코드 | 의미 |
|------|------|
| `0` | 정상 |
| `1` | 입력은 찾았으나 비어 있음(예: `replay`/`compare`에 빈 trace) |
| `2` | 잘못된/없는 인자(없는 모델·시나리오, 파일 없음, `play` 중 stdin 조기 종료) |

---

## 9. 실제 모델로 실행 (선택)

`.venv`에는 provider SDK가 없으므로, 실제 LLM을 돌릴 때는 **임시 venv**를 따로 만들어 씁니다(오프라인 불변 유지).

```bash
# 예: Ollama Cloud
python3 -m venv /tmp/proteus-real && \
/tmp/proteus-real/bin/pip install pydantic numpy pyyaml httpx && \
PYTHONPATH="$PWD" OLLAMA_API_KEY="<키>" \
/tmp/proteus-real/bin/python -m proteus run \
  --scenario predator_evade --model ollama:gpt-oss:120b-cloud \
  --difficulty easy --seed 42 --play-turns 10 --out runs/real.jsonl
```

- 사용 가능한 provider 이름은 `run --help`의 `--model` 설명에 나옵니다.
- API 키와 `runs/`는 `.gitignore` 대상이라 커밋되지 않습니다.

---

## 10. 도움말은 언제든

```bash
.venv/bin/python -m proteus --help            # 전체 명령
.venv/bin/python -m proteus run --help         # 명령별 옵션
.venv/bin/python -m proteus play --help
.venv/bin/python -m proteus replay --help
.venv/bin/python -m proteus compare --help
```

궁금한 점이 있으면 `docs/superpowers/specs/`의 설계 문서와 `HANDOFF.md`를 참고하세요.