Update model card with pending TB2-lite evaluation status

README.md

@@ -1,88 +1,167 @@
 ---
-license: other
 language:
-- ko
 - en
+- ko
+library_name: transformers
+pipeline_tag: text-generation
 tags:
-- hrm-text
-- korean
 - terminal
-- tool-use
-- code
-- pretraining
-pipeline_tag: text-generation
+- sft
+- vllm
+- tb2-lite
+- evaluation-pending
+base_model: unknown
 ---
 
-# KoHRM-Text-1.4B
-
-`KoHRM-Text-1.4B`는 `sapientinc/HRM-Text`의 PrefixLM 학습 구조를 기반으로, 한국어/영어/코딩/터미널/툴콜 사용성을 목표로 scratch pretraining하는 모델입니다.
-
-이 카드는 2026-05-23 기준 작업 중인 모델 카드 초안입니다. 현재 업로드되는 epoch artifact는 raw HRM-Text FSDP2 checkpoint이며, 바로 Transformers에서 로드하는 최종 배포 형식이 아닙니다.
-
-## 모델 정보
-
-| 항목 | 값 |
-|---|---|
-| model id | `LLM-OS-Models/KoHRM-Text-1.4B` |
-| base code | `sapientinc/HRM-Text` |
-| training from | scratch |
-| architecture | HRM-Text `XL` |
-| params | 1,384,120,320 |
-| context | 4096 tokens |
-| dtype | bfloat16 |
-| tokenizer | byte-level BPE, NFC normalization |
-| vocab | 131,072 |
-
-## 토크나이저
-
-새 tokenizer는 한국어, 영어, 코드, shell, terminal instruction, JSON tool-call을 함께 고려해 학습했습니다.
-
-| 샘플 | chars/token |
-|---|---:|
-| 한국어 일반 | 2.60 |
-| 한국어 법률 | 2.36 |
-| 한국어 터미널 지시 | 2.18 |
-| shell command | 2.68 |
-| tool JSON | 3.32 |
-| Python code | 3.37 |
-| 영어 | 4.40 |
-
-Tokenizer repo: `LLM-OS-Models/HRM-Text-Ko-Terminal-Tokenizer-131K`
-
-## 학습 데이터
-
-stage-0 입력은 전처리 완료된 711.3M token mix입니다.
-
-| 데이터 | token |
-|---|---:|
-| HRM cleaned base sample | 250.0M |
-| SWE-ZERO + GLM reasoning mix | 251.2M |
-| 한국어 법률/조례/행정규칙/판례 task | 83.1M |
-| ToolBench train tool-call task | 127.0M |
-| 합계 | 711.3M |
-
-이후 stage는 HRM cleaned 원본 retokenized dataset, local terminal dataset, 추가 한국어/코딩/툴콜 데이터를 순차적으로 포함합니다. 평가 데이터 성격의 `tb2_lite`, Terminal Bench 2, ToolBench eval, chi-bench는 train에서 제외합니다.
-
-## 학습 방식
-
-- Objective: PrefixLM style response-only loss
-- Optimizer: HRM-Text upstream Adam-atan2
-- Context: 4096 tokens
-- Hardware: 8 x NVIDIA H200
-- Current stable global batch: 172,032 tokens
-- Checkpoint policy: epoch-level raw FSDP2 checkpoint upload
-
-논문 기본 global batch는 196,608 tokens였지만, 이 모델은 vocab이 131,072로 커서 final logits memory가 더 큽니다. 장기 run에서는 OOM 여유를 위해 172,032 tokens를 기본값으로 사용합니다.
-
-Staged pretraining에서는 checkpoint의 model/optimizer/EMA/carry를 이어받고, `resume_step_offset`과 `total_steps_override`로 LR schedule을 전체 pretraining 기준에 맞춥니다. 즉, 새 데이터가 준비될 때마다 학습을 재시작하되 optimizer와 schedule을 끊지 않는 방향으로 운용합니다.
-
-## 현재 상태
-
-- stage-0 training: in progress
-- HF upload: epoch checkpoint watcher active
-- final Transformers conversion: not yet produced
-- public benchmark score: not yet evaluated for this model
-
-## 제한사항
-
-현재 checkpoint artifact는 중간 학습 산출물입니다. 안전성 정렬, 최종 instruction tuning, 최종 benchmark, 배포용 변환이 끝난 모델이 아닙니다. 한국어 터미널/툴콜 능력은 목표 영역이지만, stage-0만으로는 완성된 성능을 보장하지 않습니다.
+# LLM-OS-Models/KoHRM-Text-1.4B
+
+터미널 작업 자동화를 위한 Terminal SFT 모델입니다. 입력된 작업/이전 터미널 상태를 보고 다음에 실행할 명령을 JSON 형태로 생성하는 용도로 학습했습니다.
+
+## 모델 요약
+
+- Base model: `unknown`
+- Training setup: `Terminal SFT`
+- Model card snapshot: `2026-05-23 09:04:40 UTC`
+- Corrected TB2-lite evaluated results currently indexed: `56`
+- Corrected TB2-lite score: `pending / not matched in current result directory`
+
+## Quickstart
+
+설치와 로그인:
+
+```bash
+pip install -U vllm transformers huggingface_hub
+huggingface-cli login
+```
+
+관련 코드:
+
+- GitHub: https://github.com/LLM-OS-Models/Terminal
+- vLLM 평가 실행: `tb2_lite/scripts/replay_eval.py`
+- chat template/fallback 생성: `tb2_lite/scripts/prompt_builder.py`
+- JSON/command 채점: `tb2_lite/scripts/replay_metrics.py`
+
+vLLM 직접 실행 예시. 평가 코드와 동일하게 chat template을 우선 사용하고, template이 없으면 ChatML/Gemma fallback을 사용합니다.
+
+```python
+from transformers import AutoTokenizer
+from vllm import LLM, SamplingParams
+
+model_id = "LLM-OS-Models/KoHRM-Text-1.4B"
+tp = 1
+
+tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+llm = LLM(
+    model=model_id,
+    tokenizer=model_id,
+    trust_remote_code=True,
+    dtype="bfloat16",
+    tensor_parallel_size=tp,
+    max_model_len=49152,
+    gpu_memory_utilization=0.92,
+)
+
+messages = [
+    {"role": "system", "content": "You are a terminal automation assistant. Return JSON only."},
+    {"role": "user", "content": "Inspect the current directory and list Python files."},
+]
+
+def render_chatml(messages):
+    parts = []
+    for message in messages:
+        role = "assistant" if message["role"] == "assistant" else message["role"]
+        if role == "tool":
+            role = "user"
+        parts.append(f"<|im_start|>{role}\n{message['content']}<|im_end|>\n")
+    parts.append("<|im_start|>assistant\n")
+    return "".join(parts)
+
+def render_gemma4_turn(messages, empty_thought_channel=False):
+    parts = ["<bos>"]
+    for message in messages:
+        role = "model" if message["role"] == "assistant" else message["role"]
+        if role == "tool":
+            role = "user"
+        parts.append(f"<|turn>{role}\n{message['content'].strip()}<turn|>\n")
+    parts.append("<|turn>model\n")
+    if empty_thought_channel:
+        parts.append("<|channel>thought\n<channel|>")
+    return "".join(parts)
+
+def render_prompt(model_id, tokenizer, messages):
+    model_key = model_id.lower()
+    if "gemma-4" in model_key:
+        try:
+            return tokenizer.apply_chat_template(
+                messages,
+                tokenize=False,
+                add_generation_prompt=True,
+                enable_thinking=False,
+            )
+        except Exception:
+            return render_gemma4_turn(
+                messages,
+                empty_thought_channel=("26b" in model_key or "31b" in model_key),
+            )
+    try:
+        return tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+    except Exception:
+        return render_chatml(messages)
+
+prompt = render_prompt(model_id, tokenizer, messages)
+sampling = SamplingParams(
+    temperature=0.0,
+    top_p=1.0,
+    max_tokens=1024,
+    repetition_penalty=1.0,
+)
+outputs = llm.generate([prompt], sampling_params=sampling)
+print(outputs[0].outputs[0].text)
+```
+
+권장 출력 형식:
+
+```json
+{
+  "analysis": "brief reasoning about the next terminal action",
+  "plan": "short execution plan",
+  "commands": [
+    {"keystrokes": "ls -la\n", "duration": 0.1}
+  ],
+  "task_complete": false
+}
+```
+
+평가와 동일한 replay 명령:
+
+```bash
+python tb2_lite/scripts/replay_eval.py \
+  --model LLM-OS-Models/KoHRM-Text-1.4B \
+  --model-short LLM-OS-Models__KoHRM-Text-1.4B \
+  --eval-path tb2_lite/data/replay_full.jsonl \
+  --output-dir /home/work/.data/tb2_lite_eval/corrected_readme_models_vllm \
+  --dtype bfloat16 \
+  --tp 1 \
+  --max-model-len 49152 \
+  --max-tokens 1024 \
+  --temperature 0.0 \
+  --top-p 1.0 \
+  --gpu-memory-utilization 0.92 \
+  --language-model-only
+```
+
+- 기본 권장 tensor parallel: `1`. OOM이면 `--tp`와 `tensor_parallel_size`를 2/4/8로 올리세요.
+- corrected TB2-lite 평가는 `temperature=0.0`, `top_p=1.0`, `max_tokens=1024`로 고정했습니다.
+- Gemma 4는 JSON 출력을 위해 `enable_thinking=False`를 사용하고, 26B/31B 계열은 평가 코드에서 empty thought channel 처리를 자동 적용합니다.
+
+## 평가 상태
+
+- Current corrected TB2-lite score: `pending`
+- Reason: 현재 `/home/work/.data/tb2_lite_eval/corrected_readme_models_vllm` 집계 결과와 이 HF repo명이 직접 매칭되지 않았습니다.
+- Next step: 동일한 `tb2_lite/scripts/replay_eval.py` 경로로 평가를 돌린 뒤 점수 카드로 자동 교체합니다.
+
+## 모델군 해석
+
+- 이 repo는 아직 현재 corrected TB2-lite 집계 JSON과 직접 매칭되는 점수가 없습니다.
+- TB2-lite 점수는 일반 지능 벤치마크가 아니라 터미널 next-action JSON 재현 능력을 측정합니다.
+- 생성 명령은 실제 실행 전에 sandbox, allowlist, human review 같은 안전장치를 거쳐야 합니다.