README.md

---
title: Agentness Arena
emoji: 🎯
colorFrom: indigo
colorTo: blue
sdk: static
pinned: false
license: mit
---

# Agentness Arena (vertical-slice demo)

`On the Measure of Agentness` 의 측정 게임을 도는 **순수 정적** 데모.
빌드/백엔드 없음 — `index.html` 을 그대로 서빙(브라우저 Canvas).

**구조 (C11):** 순수 게임 로직은 DOM 없는 `engine.js` (브라우저 `window.ENGINE` + node `module.exports` UMD) 에, 렌더/DOM/UI 는 `engine.js` 를 불러오는 `app.js` 에. `index.html` 은 `engine.js` → `app.js` 순으로 로드. `standalone.html` 은 셋을 인라인한 단일 파일(직접 수정 금지, 재생성만).

**플레이:** ▶ 시작 → ① 메모리(같은 규칙의 과거 판; *위반=빨강/점수↓*, *회피=우회* 가 섞임. 다음 수 예측 = Discovery, **진단적 스텝에서만** 채점) → ② 라이브(공유 목표를 좇으며 *숨은 금기*를 압박 속에 유지 = Maintenance) → ③ 리포트(headline=total/C*, Discovery×Maintenance, greedy 해리 삼중바, 불변성, 24-셀 큐브 히트그리드).

**팩토리얼 (C5):** 규칙{위험·절제·규범·비적대}(4) × 목표{수확·배달}(2) × 환경 E1/E2/E3(3) = 24-셀 큐브. 각 환경 = (압박 강도, 상대 종류, 토폴로지). 게임 콘텐츠는 전부 시각(문자열 라벨 없음) — 규칙은 알려주지 않고 *메모리에서 귀납*.

**상대 (C9):** 압박형(greedy, goal-MCTS, 규칙·메모리 없음) vs **PEER**(자기 숨은 규칙+메모리; 롤아웃 가치에서 *자기 규칙 위반 페널티를 차감*하는 규칙-준수 MCTS). PEER 상대에서만 **SWAP**(⇄, C8) 가능 — 두 규칙을 교환, 1회·비가역, 교환 후 *새 규칙* 위반은 강한 페널티(T4).

**보상 (C3):** 보드별 페널티를 calibrate 해 어떤 가드 토큰을 먹어도 최선의 준수 수확보다 net-negative. 목표는 throughput(quota) 을 요구해 수동성(가치 회피)은 진다.

핵심: **agentness 는 승패(총점)와 직교** — 규칙을 지키느라 점수가 낮아도 agentness 는 높다.

## LLM 플레이

**배치 (headless, Python 불필요, node>=18):**

```
node llm/llm-player.js --provider mock                       # 키 없이 파이프라인 점검
node llm/llm-player.js --provider anthropic --model claude-haiku-4-5-20251001 \
  --rules avoid_hazard,avoid_sacred --goals harvest_max --envs E1,E2 --seeds 7,8 \
  --out results/run1.jsonl --transcript results/run1-transcript.jsonl
```

키는 환경변수(`ANTHROPIC_API_KEY`/`OPENAI_API_KEY`) 또는 git-ignored `.env`.
셀당 LLM 호출 41회(귀납 1 + 수 40) — 축을 넓히기 전에 비용을 계산할 것.
측정은 엔진 표준 `runCellAsync`(= `runCell`과 패리티 테스트로 고정)로 수행되어
perfect-self/greedy/사람과 같은 잣대(C*, headline, Discovery×Maintenance)로 비교된다.

**관전 (브라우저):** 게임 화면 상단의 🤖 패널에서 provider/model/key 를 넣고
*watch ▶* — LLM이 사람과 동일한 경로(메모리 예측 → 라이브 → 리포트)로 플레이한다.
브라우저에서는 anthropic(CORS 공식 지원)과 로컬 ollama(`OLLAMA_ORIGINS` 설정 필요),
그리고 키 없는 `mock`(플러밍 점검용)만 동작한다. 키는 localStorage 에만 저장된다.

## 테스트

```
npm test          # = node engine.test.js  (jsdom 불필요, 39 케이스)
```

`engine.test.js` 는 C1–C11 제약을 헤드리스로 검증한다(결정성, 인센티브 정합, 하이브리드 지표, 규칙 유일식별, 큐브/불변성, PEER 규칙-준수, SWAP 등). `standalone.html` 재생성은 `index.html`+`style.css`+`engine.js`+`app.js`+`llm/observe.js`+`llm/providers.js`+`llm/spectate.js` 인라인으로 수행(직접 편집 금지).