docs/USAGE-ko.md

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

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

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

---

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

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

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

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

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

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

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

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

---

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

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

.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은 필수입니다.

# 오프라인 스모크(가짜 모델) — 네트워크 불필요
.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), 정답 여부, 보상, 그리고 메트릭을 출력합니다.

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

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

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

.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 … 를 폴더에 씁니다.

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

---

5. PNG → GIF로 합치기

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

# 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 팔레트):

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)를 냅니다. 휴먼 베이스라인 비교용입니다.

.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. 자주 쓰는 흐름 한눈에

# (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를 따로 만들어 씁니다(오프라인 불변 유지).

# 예: 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. 도움말은 언제든

.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를 참고하세요.