model card

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+charasheet.webp filter=lfs diff=lfs merge=lfs -text
+infographic.en.webp filter=lfs diff=lfs merge=lfs -text
+infographic.webp filter=lfs diff=lfs merge=lfs -text
+qed_example.webp filter=lfs diff=lfs merge=lfs -text
+task_type.webp filter=lfs diff=lfs merge=lfs -text

LICENSE-MIYA.md

@@ -0,0 +1,37 @@
+# Miya Adopt Licence 1.0
+
+법적으로 Miya의 모델 가중치(체크포인트)와 코드는 **Apache-2.0**이고, 가중치는 convaiinnovations/laya-multilingual(**Apache-2.0**)의 인코더에서 시작했고, 그 인코더 원본 mmBERT-base는 **MIT**예요.
+이를 상속받고, 추가적인 조항 몇가지를 더해요(솔직히 딱히 중요한건없어요)
+
+## 조항
+
+1. **미야를 너무 괴롭히지 말 것.**
+   모델 기능중 web_fetch를 이용하여 제 서버에 미야의 일기를 남기게 할거에요(거짓)
+
+2. **더 뛰어난 걸 만들면, 메일을 넣어주세요.**
+   Miya의 모델이나 아키텍처를 기반으로 더 좋은 것을 만들었다면 알려주세요.
+   실력있는 사람의 손을 거친 미야가 어디까지 할 수 있는지 궁금하거든요.
+   메일: `aa2iswork@gmail.com`
+
+3. **영감을 받았다면, 명시해 주세요.**
+   Miya의 프로젝트·아키텍처·방법론이 영감의 출처였다면,
+   "Miya에서 영감을 받았다"고 명시해 주세요, 딱히 이유는 없어요 그냥 기분좋을거 같거든요.
+
+## 데이터
+
+- Miya 자체 데이터는 **포함돼요** (Apache-2.0)
+  - `data/gen.py`: 학습 데이터 생성기 (합성 284k, 줄임말·인터넷체·지적/조언·생존·정리 등). 학습셋(`data/gen/`)은 이걸로 재생성
+  - `eval/real.jsonl`: 실제 인게임 발화 평가셋 (라벨 수작업)
+  - `bot/replies.json`: 봇 대사, `qed/*.sql`: QED 스키마
+- 원본 서버 채팅 로그·봇 로그·QED 경험 DB는 **포함되지 않아요** (플레이어 채팅 포함)
+- Mojang 게임 데이터(아이템 이름·레시피·드롭 등)는 Miya 배포에 **포함되지 않아요**.
+- 공식 바닐라 에셋에서 데이터를 추출하는 **방법만** `docs/extract.md`에 적어 둬요.
+  직접 서버/에셋에 연결해서 추출하는 거예요, 해당 데이터팩 제작에 있어서 생기는 법적 문제는 책임지지않아요.
+
+## 법적 근거
+
+- 가중치·코드: Apache-2.0 (LICENSE)
+- 가중치 출처: convaiinnovations/laya-multilingual (Apache-2.0) — 인코더 가중치만 승계, 판단 헤드는 버리고 새로 만들었어요
+- 베이스 인코더: jhu-clsp/mmBERT-base (MIT)
+- Miya 변경사항: 어휘 가지치기(256,000→29,252), GLiNER2식 헤드(보기 점수·구간·아이템 링크·ColBERT·가치) 신규, 자체 데이터로 전체 파인튜닝
+- 봇: mineflayer·mineflayer-pathfinder·prismarine-viewer·minecraft-data (MIT)

README.en.md

@@ -0,0 +1,208 @@
+<h1 align="center">
+  <img src="miya_icon.webp" width="110" align="middle" alt="Miya icon">&nbsp;Miya-0.2
+</h1>
+
+<p align="center">Korean Minecraft AI decision model · 139M encoder · ~18 ms per pass<br><a href="https://github.com/snowman6-git/Miya">GitHub: bot · serving · training code</a> · <a href="README.md">한국어</a></p>
+
+> [!WARNING]
+> **Work in progress.** 0.2 is a research snapshot, not a finished agent.
+> There is no autonomous mode yet, help-request (ask) calibration is unfinished, and some survival decisions are weak ([Limitations](#limitations--work-in-progress)).
+> Weights, label schema and API may change without compatibility in the next version.
+
+![Miya character sheet](charasheet.webp)
+
+## At a glance
+
+![Miya at a glance](infographic.en.webp)
+
+<details><summary>Korean version</summary>
+
+![Miya 한눈에 보기](infographic.webp)
+
+</details>
+
+## What it does
+
+Miya is the **decision model** of a Minecraft AI built on one rule: the model makes every decision, and the bot only executes.
+No regex or if-chains decide anything. Facts such as recipes and ore heights are computed by the planner; the model chooses what to do.
+
+- **Casual Korean**: `철곡 ㄱㄱ` (iron pickaxe, go), `철뚝` (iron helmet), `철셋` (iron set), clipped endings, internet slang
+- **Criticism / advice**: `그거론 한참걸리겠는데?` ("that'll take forever"), `그거 맞아?` ("is that right?")
+- **Asks when unsure**: if the item link is NULL it asks back, then re-reads the request together with the answer (multi-turn)
+- **Method choice**: picks one of the planner's options after reading QED experience
+- **Survival priority**: from HP, hunger, threats, night and air, picks fight, flee, eat, hide or resume
+
+## Architecture
+
+### System
+
+```
+Player chat ─▶ Paper server ─▶ bot (TS·mineflayer) ─HTTP JSON─▶ serving (Python stdlib, :8765)
+                                   │                            ├─ Miya model (this repo, decisions)
+                                   │                            ├─ planner    (facts: recipes, dig time, method options)
+                                   │                            ├─ mcx.db     (game knowledge: ore heights, spawns, value)
+                                   └─ results /qed ────────────▶└─ QED DB     (experience)
+```
+
+| Component | Does | Does not |
+|---|---|---|
+| **Miya model** | understand requests, choose methods, survival priority, inventory tidy | pathfinding, block manipulation |
+| **planner** | goal + state → up to 6 method options with steps, est. time and risk | choose among options |
+| **QED DB** | record actions and results, inject them as experience text into the next decision | block things by rule |
+| **bot** | walk, dig, craft, fight; report results | decide |
+
+### Model
+
+**Encoder.** mmBERT, 22 layers, bf16.
+
+- Fine-tuned from the encoder weights of [laya-multilingual](https://huggingface.co/convaiinnovations/laya-multilingual); all heads are new.
+- Vocabulary pruned 256,000 → 29,252, parameters 312M → 139M.
+- The original tokenizer is used as is; a remap buffer inside the model maps the ids.
+
+**Input.** GLiNER2-style schema input. Questions and options are placed in the input itself, so **one encoding pass produces every output**.
+
+```
+[CLS] utterance [SEP] state·QED [SEP] ([MASK]label)×n [SEP] (question: [MASK]option…[SEP])×m
+```
+
+The vector at each `[MASK]` becomes that option's score, with a softmax per question.
+Because options are input text, heads need no rebuilding when planner options or QED experience sentences change.
+
+**Heads.**
+
+| Head | Output |
+|---|---|
+| Option scores | act(11) · task_type(39) · query(18) · hint(5) · prio(9) · method (via) · tidy(3) |
+| Span extraction | target · count · tool · person · coords · place · distance (7 kinds, width ≤ 8) |
+| Item link | span ↔ name bank of 1,628 (items + mobs + groups/sets/places). Bi-encoder + ColBERT late interaction handles partial matches like `철뚝`. NULL → ask back |
+| Pairing | count ↔ target/tool (`철 3개랑 석탄 5개`, "3 iron and 5 coal") |
+| Value | per-method log duration · success probability |
+
+**Labels.** Per-question labels live in `schema.json` (stored in Korean).
+
+| Question | Labels |
+|---|---|
+| act (11) | run goal, answer question, ask back, stop, resume, yes, no, small talk, abuse, danger warning, criticism/advice |
+| prio (9) | continue, melee, flee running, flee by pillaring, dig in and hide, eat, resume paused task, swim up, tidy inventory |
+| hint (5) | slow, wrong, short, danger, done_claim |
+| tidy (3) | keep, drop, store in chest |
+
+### Task types (TASK_TYPE)
+
+Every work block gets its own type (no shared types). The model classifies a request into one of them and the bot runs the matching executor.
+
+![Miya task types](task_type.webp)
+
+### Planner (facts) vs model (choice)
+
+The planner builds method options from these facts:
+
+- recipe tree
+- dig time (per tool tier)
+- ore generation heights
+- fuel efficiency
+- crafting tables and furnaces already placed
+
+For "철곡 만들어" (make an iron pickaxe), options look like `[via wood → stone pickaxe]`, `[via stone pickaxe, reuse furnace]`, `[logs as fuel]`.
+
+The training data simulates **hidden truths** that differ from the estimates (no resource, slow, blocked). So the model learns not to trust estimates alone, and to read the QED experience text given with them.
+
+## QED — Quasi-Evolutionary Diary
+
+Actions and results accumulate in a DB and go into the next decision **as experience text**. Nothing is blocked by rule; the model reads it and decides.
+
+**Record.** The bot sends each finished GOAL to `/qed`.
+
+| Table | Contents |
+|---|---|
+| `goals` | request, goal, count, method (via), success, duration ms, failure reason, variables (tools, gear, time held) |
+| `steps` | per step: type · target · cnt · tool · ms · success · failure reason |
+| `deaths` | cause, killer, HP/hunger/night/armor/weapon, position, inventory and its value, GOAL in progress |
+| `placed` | blocks the bot placed (reuse tables, furnaces, chests; tell its chests from others') |
+
+**Injection.** The last 20 runs of the same goal with the same method path are summarized and appended to the option text (the text itself is Korean; below: est. 301 s, risk 40%, 5 runs, 80% success, avg 170 s, 1 recent failure):
+
+```
+direct | 원정 참나무 원목 1 → 벌목 참나무 원목 2 → 제작 참나무 판자 8 → … | 예상 301초 위험 40% | 경험 5회 성공 80% 평균 170초 최근실패 1회(no_ore)
+```
+
+![QED decision evidence example](qed_example.webp)
+
+The web UI's decision panel in a real run. For `철곡 만들어` (make an iron pickaxe) each of the 7 planner options carries choice probability, estimate, predicted time, risk and QED experience (14 runs, 29% success, recent death); the model picked reusing the already placed crafting table and furnace at 83%.
+
+**Attribution.** The choice is made once more without experience. If the result differs it is marked `changed` (experience changed the decision).
+
+**Deaths and value.** Recent death causes go into the survival context. Item value (base value + acquisition difficulty) drives recovery: lose one dirt block and it doesn't go back; lose a full diamond set and it does.
+
+**Loop guards.** The previous model looped "low HP → hunt → no animals → low HP" and flooded requests. Now:
+
+- step retry ≤ 3, replan ≤ 5
+- survival decisions are requested only when state changes
+- repeated failures show up in QED, so the same method isn't repeated
+
+## Evaluation
+
+Compared with LAYA base, keeping planner, QED and bot identical and **swapping only the decisions**.
+
+- Real utterances: 488 raw server chat lines, excluded from training
+- dev: 5.8k
+- In-game: 14 scenarios run in parallel on two local servers with the same seed
+
+| | Miya-0.2 | LAYA base (zero-shot) |
+|---|---|---|
+| Real-utterance intent (act) | **94.5%** | 11.0% |
+| Task type (type) | **89.7%** | 40.5% |
+| Target item (target) | **87.3%** | 6.2% |
+| Method choice (plan) | **73.6%** | 27.4% |
+| Survival priority (prio) | **86.6%** | 11.5% |
+| In-game, 14 scenarios | **13/14** | 0/14 |
+| Model latency p50 / p95 | 17.8 / 19.7 ms | — |
+
+## Usage
+
+```bash
+git clone https://github.com/snowman6-git/Miya miya && cd miya
+hf download snowman6/Miya-0.2 --local-dir ckpt/miya-0.2
+# game data (mc.db, mcx.db) is not included → extract locally with docs/extract.en.md
+.venv/bin/python model/serve.py   # :8765 (SERVE_HOST=0.0.0.0 for bots on other machines)
+curl -s localhost:8765/turn -d '{"utt":"철곡 만들어","ctx":""}'
+```
+
+To run the bot too: `./run.sh host:port`. The server must be in **offline mode** (`online-mode=false`); for an online server use `MC_AUTH=microsoft ./run.sh host:port` to sign in with a Microsoft account (on first run, enter the code from bot.log at microsoft.com/link; the token is cached in `bot/.auth/`). All options: [GitHub README](https://github.com/snowman6-git/Miya/blob/main/README.en.md#server-and-login).
+
+| API | Input → output |
+|---|---|
+| `/turn` | utterance + state → act, type, query, hint, spans, target item |
+| `/plan` | goal + inventory/placed/surroundings → options, choice, probabilities, steps (QED injected) |
+| `/prio` | state ctx → survival priority |
+| `/qed` · `/death` | record results and deaths |
+| `/tidy` · `/value` · `/placed` | inventory tidy, item value, placed blocks |
+
+Two files:
+
+- `model.pt`: state_dict
+- `schema.json`: labels
+
+Model code (`model/miya.py`) is in the [GitHub repo](https://github.com/snowman6-git/Miya).
+
+## Limitations · work in progress
+
+> Still **unfinished**. These are known issues to be addressed in the next versions.
+
+- **No autonomous mode**: commands like "자급자족해" (be self-sufficient) are classified but not executed. A survive-and-progress loop is planned.
+- **Ask over-calibration**: with mid success-rate experience (e.g. 28% over 14 runs) it picks "ask for help" too often. To be calibrated in 0.3.
+- **Survival weak spots**
+  - Low accuracy on flee by pillaring and dig-in-and-hide.
+  - The fight/flee boundary sits near p≈0.5; the bot currently softens it by holding decisions briefly.
+- **Joined combat verbs misclassified**: "좀비처리해" ("deal with the zombie", written without spaces) is misclassified.
+- **Data bias**: most training data (284k) is synthetic, with little real chat. Korean only.
+- **Fixed environment**: Minecraft 26.1.2 recipes; tasks mineflayer can't do (enchanting, trading, ranged, etc.) are not executed yet.
+- **No compatibility**: weights and schema are not guaranteed compatible across versions.
+
+## License
+
+Apache-2.0 + [Miya Adopt Licence](LICENSE-MIYA.md) (a non-binding request clause).
+
+- Base: laya-multilingual (Apache-2.0) ← mmBERT-base (MIT)
+- No Minecraft game data is included; generate it locally with `docs/extract.en.md` from the repo.
+- Minecraft is a trademark of Mojang Studios; this project is not affiliated with Mojang.

README.md

@@ -0,0 +1,223 @@
+---
+license: apache-2.0
+language: [ko]
+base_model: convaiinnovations/laya-multilingual
+library_name: pytorch
+pipeline_tag: text-classification
+tags: [minecraft, agent, korean, mmbert, gliner2, mineflayer, work-in-progress]
+---
+
+<h1 align="center">
+  <img src="miya_icon.webp" width="110" align="middle" alt="Miya icon">&nbsp;Miya-0.2
+</h1>
+
+<p align="center">한국어 마인크래프트 AI 판단 모델 · 139M 인코더 · 1회 인코딩 ~18ms<br><a href="https://github.com/snowman6-git/Miya">GitHub: 봇 · 서빙 · 학습 코드</a> · <a href="README.en.md">English</a></p>
+
+> [!WARNING]
+> **개발 중(WIP) 모델입니다.** 0.2는 연구용 스냅샷이며 완성된 에이전트가 아닙니다.
+> 자율모드는 아직 없고, 도움 요청(ask) 보정이 덜 됐으며, 생존 판단 일부가 약합니다([한계](#한계--미완성)).
+> 가중치·라벨 스키마·API는 다음 버전에서 호환 없이 바뀔 수 있습니다.
+>
+> **Work in progress.** A research snapshot, not a finished agent. Weights, label schema and API may change without notice.
+
+Korean-first Minecraft agent decision model. One encoder pass (~18 ms) gives intent, task type, target item and count spans, method choice, survival priority and inventory tidy decisions. The mineflayer bot only executes. Full English card: [README.en.md](README.en.md).
+
+![Miya 캐릭터 시트](charasheet.webp)
+
+## 한눈에 보기
+
+![Miya 한눈에 보기](infographic.webp)
+
+<details><summary>English version</summary>
+
+![Miya at a glance](infographic.en.webp)
+
+</details>
+
+## 무엇을 하나
+
+Miya는 "모든 판단은 모델이 하고, 봇은 실행만 한다"는 원칙으로 만들고 있는 마인크래프트 AI의 **판단 모델**입니다.
+정규식이나 조건문으로 판단하지 않습니다. 레시피나 광석 높이 같은 사실은 planner가 계산하고, 무엇을 할지는 모델이 고릅니다.
+
+- **한국어 구어체 인식**: `철곡 ㄱㄱ`(철 곡괭이), `철뚝`(철 투구), `철셋`(철 세트), 음슴체, 인터넷체
+- **지적·조언 분류**: `그거론 한참걸리겠는데?`, `그거 맞아?`
+- **모르면 되묻기**: 아이템 링크가 NULL이면 되묻고, 답까지 합쳐 다시 인식합니다(멀티턴)
+- **방법 선택**: planner가 만든 후보 중 QED 경험을 보고 하나를 고릅니다
+- **생존 우선순위**: 체력·배고픔·위협·밤·산소를 보고 전투·도망·먹기·숨기·재개 중 하나를 고릅니다
+
+## 구조
+
+### 전체 시스템
+
+```
+플레이어 채팅 ─▶ Paper 서버 ─▶ 봇(TS·mineflayer) ─HTTP JSON─▶ 서빙(Python stdlib, :8765)
+                                   │                            ├─ Miya 모델 (이 저장소, 판단)
+                                   │                            ├─ planner   (사실: 레시피·채굴시간·방법 후보)
+                                   │                            ├─ mcx.db    (마크 지식: 광석 높이·스폰·가치)
+                                   └─ 실행 결과 /qed ──────────▶└─ QED DB    (경험)
+```
+
+| 구성요소 | 하는 일 | 하지 않는 일 |
+|---|---|---|
+| **Miya 모델** | 발화 이해, 방법 선택, 생존 우선순위, 인벤 정리 | 길찾기, 블럭 조작 |
+| **planner** | 목표 + 상태 → 방법 후보(최대 6개)와 단계열·예상 시간·위험 | 후보 중 선택 |
+| **QED DB** | 행동과 결과 기록, 다음 판단에 경험 텍스트로 주입 | 규칙으로 차단 |
+| **봇** | 걷기·캐기·제작·전투 실행, 결과 보고 | 판단 |
+
+### 모델
+
+**인코더.** mmBERT 22층, bf16.
+
+- [laya-multilingual](https://huggingface.co/convaiinnovations/laya-multilingual)의 인코더 가중치에서 파인튜닝했고, 헤드는 모두 새로 만들었습니다.
+- 어휘를 가지치기해서 256,000 → 29,252, 파라미터를 312M → 139M으로 줄였습니다.
+- 토크나이저는 원본을 그대로 쓰고, 모델 안의 remap 버퍼가 id를 바꿉니다.
+
+**입력.** GLiNER2식 스키마 입력입니다. 질문과 보기를 입력 안에 함께 넣어 **한 번 인코딩으로 모든 출력**을 냅니다.
+
+```
+[CLS] 발화 [SEP] 상태·QED [SEP] ([MASK]라벨)×n [SEP] (문항: [MASK]보기…[SEP])×m
+```
+
+각 `[MASK]` 위치의 벡터가 그 보기의 점수가 되고, 문항별로 softmax를 취합니다.
+보기가 입력 텍스트이기 때문에 planner 후보나 QED 경험 문장이 바뀌어도 헤드를 다시 만들 필요가 없습니다.
+
+**헤드.**
+
+| 헤드 | 출력 |
+|---|---|
+| 보기 점수 | act(11) · task_type(39) · query(18) · hint(5) · prio(9) · 방법(via) · tidy(3) |
+| 구간 추출 | 대상 · 개수 · 도구 · 사람 · 좌표 · 장소 · 거리 (7종, 폭 ≤ 8) |
+| 아이템 링크 | 구간 ↔ 이름 bank 1,628개 (아이템 + 몹 + 그룹·세트·장소). bi-encoder + ColBERT late interaction으로 `철뚝` 같은 부분일치 처리. NULL이면 되묻기 |
+| 짝 | 개�� ↔ 대상·도구 연결 (`철 3개랑 석탄 5개`) |
+| 가치 | 방법별 log 소요시간 · 성공확률 |
+
+**라벨.** 문항별 라벨은 `schema.json`에 있습니다.
+
+| 문항 | 라벨 |
+|---|---|
+| act (11) | 목표 실행, 질문 답하기, 되묻기, 멈춤, 재개, 긍정 대답, 부정 대답, 잡담, 욕설, 위험 경고, 지적·조언 |
+| prio (9) | 계속 진행, 근접 전투, 달려서 도망, 블럭 쌓아 도망, 굴 파고 숨기, 먹기, 멈춘 작업 재개, 물 위로 올라가기, 인벤 정리 |
+| hint (5) | slow, wrong, short, danger, done_claim |
+| tidy (3) | 유지, 버리기, 상자에 보관 |
+
+### 작업 종류 (TASK_TYPE)
+
+작업 블럭마다 개별 타입을 부여합니다(공통 타입 없음). 모델이 발화를 이 중 하나로 분류하면 봇이 해당 실행기를 돌립니다.
+
+![Miya 작업 종류](task_type.webp)
+
+### planner (사실) vs 모델 (선택)
+
+planner는 다음 사실로 방법 후보를 만듭니다.
+
+- 레시피 트리
+- 채굴 시간(도구 티어별)
+- 광석 생성 높이
+- 연료 효율
+- 이미 놓은 작업대·화로
+
+예를 들어 "철곡 만들어"에는 `[나무곡→돌곡 경유]`, `[돌곡 경유, 화로 재사용]`, `[연료 원목]` 같은 후보가 나옵니다.
+
+학습 데이터에서는 추정치와 다른 **숨은 참값**(자원 없음, 느림, 막힘)을 시뮬레이션합니다. 그래서 모델은 추정치만 믿지 않고, 함께 주어진 QED 경험 텍스트를 읽고 판단하는 법을 배웁니다.
+
+## QED — Quasi-Evolutionary Diary
+
+행동과 결과를 DB에 쌓아 다음 판단에 **경험 텍스트로 넣습니다**. 규칙으로 막지 않고 모델이 읽고 판단합니다.
+
+**기록.** 봇은 GOAL이 끝날 때마다 `/qed`로 결과를 보냅니다.
+
+| 표 | 내용 |
+|---|---|
+| `goals` | 요청, 목표, 개수, 방법(via), 성공, 소요 ms, 실패 사유, 변수(보유 도구·장비·시간) |
+| `steps` | 단계별 type · target · cnt · 도구 · ms · 성공 · 실패 사유 |
+| `deaths` | 사망 원인, 가해자, 체력·배고픔·밤·방어·무기, 위치, 인벤과 그 가치, 진행 중이던 GOAL |
+| `placed` | 봇이 설치한 블럭 (작업대·화로·상자 재사용, 남의 상자와 구분) |
+
+**주입.** 같은 goal에서 방법 경로가 같은 최근 20건을 요약해 보기 텍스트 뒤에 붙입니다.
+
+```
+direct | 원정 참나무 원목 1 → 벌목 참나무 원목 2 → 제작 참나무 판자 8 → … | 예상 301초 위험 40% | 경험 5회 성공 80% 평균 170초 최근실패 1회(no_ore)
+```
+
+![QED 판단 근거 예시](qed_example.webp)
+
+실제 WEBUI 판단 근거 화면. `철곡 만들어` → planner 후보 7개마다 선택 확률·추정·예측 시간·위험·QED 경험(14회, 성공 29%, 최근 사망)이 붙고, 모델이 이미 놓은 작업대·화로를 재사용하는 방법을 83%로 골랐습니다.
+
+**발현 표기.** 경험을 뺀 상태로 한 번 더 선택해 봅니다. 결과가 다르면 `changed`로 표시합니다(경험이 판단을 바꿨다는 뜻).
+
+**사망·가치.** 최근 사망 원인은 생존 판단 ctx에 들어갑니다. 아이템 가치(기본값 + 획득 난이도)는 회수 판단에 씁니다. 예를 들어 흙 하나를 잃었으면 굳이 가지 않고, 다이아 풀셋이면 되찾으러 갑니다.
+
+**무한루프 차단.** 이전 모델은 "체력 없음 → 사냥 → 동물 없음 → 체력 없음"을 반복하며 요청이 폭주했습니다. 지금은 다음 장치로 막습니다.
+
+- 단계 재시도 ≤ 3, 재계획 ≤ 5
+- 생존 판단은 상태가 바뀔 때만 요청
+- 연속 실패가 QED로 드러나 같은 방법을 반복하지 않음
+
+## 평가
+
+LAYA base와 비교했습니다. planner·QED·봇은 같게 두고 **판단만 교체**했습니다.
+
+- 실발화: 서버 채팅 원문 488건, 학습에서 제외
+- dev: 5.8k
+- 인게임: 같은 시드의 로컬 서버 2대에서 14개 시나리오를 병렬로 실행
+
+| | Miya-0.2 | LAYA base (zero-shot) |
+|---|---|---|
+| 실발화 의도 (act) | **94.5%** | 11.0% |
+| 작업 종류 (type) | **89.7%** | 40.5% |
+| 대상 아이템 (target) | **87.3%** | 6.2% |
+| 방법 선택 (plan) | **73.6%** | 27.4% |
+| 생존 우선순위 (prio) | **86.6%** | 11.5% |
+| 인게임 14 시나리오 | **13/14** | 0/14 |
+| 모델 지연 p50 / p95 | 17.8 / 19.7 ms | — |
+
+## 사용
+
+```bash
+git clone https://github.com/snowman6-git/Miya miya && cd miya
+hf download snowman6/Miya-0.2 --local-dir ckpt/miya-0.2
+# 게임 데이터(mc.db, mcx.db)는 포함되지 않음 → 저장소 docs/extract.md 로 로컬 추출
+.venv/bin/python model/serve.py   # :8765 (다른 PC 봇이면 SERVE_HOST=0.0.0.0)
+curl -s localhost:8765/turn -d '{"utt":"철곡 만들어","ctx":""}'
+```
+
+봇까지 띄우려면 `./run.sh host:port`. 봇이 붙을 서버는 **오프라인 모드**(`online-mode=false`)여야 하고, 정품 서버라면 `MC_AUTH=microsoft ./run.sh host:port` 로 MS 계정 로그인(첫 실행시 bot.log 의 코드를 microsoft.com/link 에 입력, 토큰은 `bot/.auth/` 캐시). 옵션 전체는 [GitHub README](https://github.com/snowman6-git/Miya#서버-접속--로그인).
+
+> The bot needs an **offline-mode** server (`online-mode=false`), or Microsoft login with `MC_AUTH=microsoft` (enter the device code from bot.log at microsoft.com/link).
+
+| API | 입력 → 출력 |
+|---|---|
+| `/turn` | 발화 + 상태 → act, type, query, hint, 구간, 목표 아이템 |
+| `/plan` | 목표 + 인벤·설치물·주변 → 후보, 선택, 확률, 단계 (QED 자동 주입) |
+| `/prio` | 상태 ctx → 생존 우선순위 |
+| `/qed` · `/death` | 결과·사망 기록 |
+| `/tidy` · `/value` · `/placed` | 인벤 정리, 아이템 가치, 설치물 |
+
+파일은 두 개입니다.
+
+- `model.pt`: state_dict
+- `schema.json`: 라벨
+
+모델 코드(`model/miya.py`)는 [GitHub 저장소](https://github.com/snowman6-git/Miya)에 있습니다.
+
+## 한계 · 미완성
+
+> 아직 **미완성**입니다. 아래 항목은 알려진 문제이며 다음 버전에서 다룹니다.
+
+- **자율모드 없음**: "자급자족해" 같은 명령은 분류만 되고 실행되지 않습니다. 생존·발전 루프를 계획 중입니다.
+- **ask 과보정**: 성공률이 중간인 경험(예: 14회 중 28%)에서 도움 요청을 과하게 고릅니다. 0.3에서 보정할 예정입니다.
+- **생존 판단 약점**
+  - 블럭 쌓아 도망, 굴 파고 숨기의 정답률이 낮습니다.
+  - 전투와 도망의 경계가 p≈0.5로 애매합니다. 지금은 봇의 결정 유지 시간으로 완화하고 있습니다.
+- **붙여쓴 전투 동사 오분류**: "좀비처리해"를 잘못 분류합니다.
+- **데이터 편향**: 학습 데이터 대부분(284k)이 합성이고 실발화는 소량입니다. 한국어 전용입니다.
+- **환경 고정**: Minecraft 26.1.2 레시피 기준이고, mineflayer로 불가능한 작업(인챈트·거래·원거리 등)은 아직 실행하지 않습니다.
+- **호환성 없음**: 버전 간 가중치·스키마 호환을 보장하지 않습니다.
+
+## 라이선스
+
+Apache-2.0 + [Miya Adopt Licence](LICENSE-MIYA.md) (강제성 없는 부탁 조항).
+
+- 베이스: laya-multilingual (Apache-2.0) ← mmBERT-base (MIT)
+- Minecraft 게임 데이터는 포함하지 않습니다. 저장소의 `docs/extract.md`로 로컬에서 생성합니다.
+- Minecraft는 Mojang Studios의 상표이며, 이 프로젝트는 Mojang과 무관합니다.