style(ui_components): update code comments

README.md

@@ -8,7 +8,7 @@ sdk_version: "6.9.0"
 app_file: app.py
 ---
 
-# ⚙️ Neural Engine (neuro/)
+# ⚙️ Neural Engine (neural/)
 
 이 Space는 **Cognitive World Interaction Engine의 Core Model**의 추론 API와 간단한 Web Test용 Gradio UI를 제공합니다.  
 Hugging Face Hub에 업로드된  

app.py

@@ -1,18 +1,17 @@
-import gradio as gr
 from inference import run_inference
 from modules.ui_components import build_ui
 from webtest_prompt import build_webtest_prompt
 
 
-# Web Test UI 호출 함수
+# Web Test UI Call Function
 def gradio_infer(npc_id, npc_location, player_utt):
     prompt = build_webtest_prompt(npc_id, npc_location, player_utt)
     result = run_inference(prompt)
     return result["npc_output_text"], result["deltas"], result["flags_prob"]
 
-# ping: 상태 확인 및 깨우기
+# ping: Check status and wake up
 def ping():
-    # 모델이 로드되어 있는지 확인, 없으면 로드
+    # Check if model is loaded, load if not
     global wrapper, tokenizer, model, flags_order
     if 'model' not in globals() or model is None:
         from model_loader import ModelWrapper
@@ -21,34 +20,6 @@ def ping():
     return {"status": "awake"}
 
 
-# with gr.Blocks() as demo:
-#     gr.Markdown("## CWIE Core Model Inference")
-
-#     with gr.Tab("Web Test UI"):
-#         npc_id = gr.Textbox(label="NPC ID")
-#         npc_loc = gr.Textbox(label="NPC Location")
-#         player_utt = gr.Textbox(label="Player Utterance")
-#         npc_resp = gr.Textbox(label="NPC Response")
-#         deltas = gr.JSON(label="Deltas")
-#         flags = gr.JSON(label="Flags Probabilities")
-#         btn = gr.Button("Run Inference")
-
-#         # Web Test 전용 (api_name 제거)
-#         btn.click(
-#             fn=gradio_infer,
-#             inputs=[npc_id, npc_loc, player_utt],
-#             outputs=[npc_resp, deltas, flags]
-#         )
-
-#     # ping 엔드포인트 (상태 확인/깨우기)
-#     gr.Button("Ping Server").click(
-#         fn=ping,
-#         inputs=[],
-#         outputs=[],
-#         api_name="ping"
-#     )
-
-
 if __name__ == "__main__":
     demo = build_ui()
     demo.launch(server_name="0.0.0.0", server_port=7860)

config.py

@@ -1,25 +1,26 @@
 import os
+
 import torch
 from dotenv import load_dotenv
 
-# .env 파일 로드 (로컬 개발 시)
+# Load .env file (for local development)
 load_dotenv()
 
-# 모델 경로 (환경변수 없으면 기본값 사용)
+# Model path (uses default if environment variable is missing)
 BASE_MODEL = os.getenv("BASE_MODEL", "Qwen/Qwen2.5-3B-Instruct")
 ADAPTERS = os.getenv("ADAPTER_MODEL", "m97j/npc_LoRA-fps")
 
-# 장치 설정
+# Device configuration
 DEVICE = os.getenv("DEVICE", "cuda" if torch.cuda.is_available() else "cpu")
 
-# 토크나이저/모델 공통
+# Tokenizer/Model common parameters
 MAX_LENGTH = int(os.getenv("MAX_LENGTH", 1024))
-NUM_FLAGS = int(os.getenv("NUM_FLAGS", 7))  # flags.json 길이와 일치
+NUM_FLAGS = int(os.getenv("NUM_FLAGS", 7))  # match withflags.json
 
-# 생성 파라미터
+# Generation parameters (can be overridden at inference time)
 GEN_MAX_NEW_TOKENS = int(os.getenv("GEN_MAX_NEW_TOKENS", 400))
 GEN_TEMPERATURE = float(os.getenv("GEN_TEMPERATURE", 0.7))
 GEN_TOP_P = float(os.getenv("GEN_TOP_P", 0.9))
 
-# Hugging Face Token (Private 모델 접근용)
+# Hugging Face Token (For Private Model Access)
 HF_TOKEN = os.getenv("HF_TOKEN")

inference.py

@@ -1,9 +1,10 @@
 import torch
-from config import DEVICE, MAX_LENGTH, GEN_MAX_NEW_TOKENS, GEN_TEMPERATURE, GEN_TOP_P
+from config import (DEVICE, GEN_MAX_NEW_TOKENS, GEN_TEMPERATURE, GEN_TOP_P,
+                    MAX_LENGTH)
 from model_loader import ModelWrapper
 
-# 전역 로드 (서버 시작 시 1회)
-wrapper = ModelWrapper()  # 기본은 latest 브랜치
+# Global Load (once at server start)
+wrapper = ModelWrapper()
 tokenizer, model, flags_order = wrapper.get()
 
 GEN_PARAMS = {
@@ -18,17 +19,17 @@ def run_inference(prompt: str):
     inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=MAX_LENGTH).to(DEVICE)
 
     with torch.no_grad():
-        # 텍스트 생성
+        # language generation
         gen_ids = model.generate(**inputs, **GEN_PARAMS)
         generated_text = tokenizer.decode(
             gen_ids[0][inputs["input_ids"].shape[1]:], skip_special_tokens=True
         )
 
-        # 히든 스테이트 추출
+        # hidden state extraction
         outputs = model(**inputs, output_hidden_states=True)
         h = outputs.hidden_states[-1]
 
-        # <STATE> 토큰 위치 풀링
+        # <STATE> token position pooling
         STATE_ID = tokenizer.convert_tokens_to_ids("<STATE>")
         ids = inputs["input_ids"]
         mask = (ids == STATE_ID).unsqueeze(-1)
@@ -38,7 +39,7 @@ def run_inference(prompt: str):
         else:
             pooled = h[:, -1, :]
 
-        # 커스텀 헤드 추론
+        # delta, flag, flag_threshold prediction
         delta_pred = torch.tanh(model.delta_head(pooled))[0].cpu().tolist()
         flag_prob = torch.sigmoid(model.flag_head(pooled))[0].cpu().tolist()
         flag_thr = torch.sigmoid(model.flag_threshold_head(pooled))[0].cpu().tolist()
@@ -58,6 +59,6 @@ def run_inference(prompt: str):
 
 def reload_model(branch="latest"):
     global wrapper, tokenizer, model, flags_order
-    wrapper = ModelWrapper(branch=branch)  # branch 인자로 latest 전달
+    wrapper = ModelWrapper(branch=branch)
     tokenizer, model, flags_order = wrapper.get()
     print(f"Model reloaded from branch: {branch}")

model_loader.py

@@ -1,7 +1,10 @@
-import os, json, torch
+import json
+import os
+
+import torch
 import torch.nn as nn
-from transformers import AutoTokenizer, AutoModelForCausalLM
 from config import DEVICE, HF_TOKEN
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
 SPECIALS = ["<SYS>", "<CTX>", "<PLAYER>", "<NPC>", "<STATE>", "<RAG>", "<PLAYER_STATE>"]
 
@@ -13,18 +16,18 @@ def get_current_branch():
 
 class ModelWrapper:
     def __init__(self):
-        # Flags 정보
+        # Flags info
         flags_path = os.path.join(os.path.dirname(__file__), "flags.json")
         self.flags_order = json.load(open(flags_path, encoding="utf-8"))["ALL_FLAGS"]
         self.num_flags = len(self.flags_order)
 
         branch = get_current_branch()
 
-        # 1) 토크나이저 (학습 당시 vocab + SPECIALS)
+        # 1) Tokenizer (vocab + SPECIALS at the time of training LoRA)
         self.tokenizer = AutoTokenizer.from_pretrained(
-            "m97j/npc_LoRA-fps",          # 병합된 모델이 올라간 repo
+            "m97j/npc_LoRA-fps",
             revision=branch,
-            subfolder="testcase_output", # 병합된 모델이 올라간 경로
+            subfolder="testcase_output",
             use_fast=True,
             token=HF_TOKEN,
             trust_remote_code=True
@@ -34,24 +37,25 @@ class ModelWrapper:
         self.tokenizer.padding_side = "right"
         self.tokenizer.add_special_tokens({"additional_special_tokens": SPECIALS})
 
-        # 2) 병합된 모델 로드 (샤드 자동 인식)
+        # 2) Base model (LoRA model with merged weights, but without custom heads)
         self.model = AutoModelForCausalLM.from_pretrained(
-            "m97j/npc_LoRA-fps",          # 병합된 모델이 올라간 repo
+            "m97j/npc_LoRA-fps",
             revision=branch,
-            subfolder="testcase_output", # 병합된 모델이 올라간 경로
-            device_map=None,              # 오프로딩 비활성화
+            subfolder="testcase_output",
+            device_map=None,
             low_cpu_mem_usage=False,
             trust_remote_code=True,
             token=HF_TOKEN
         )
 
-        # 3) 커스텀 헤드 추가
+        # 3) add custom heads (delta, flag, flag_threshold) - architecture only, weights will be loaded separately
         hidden_size = self.model.config.hidden_size
         self.model.delta_head = nn.Linear(hidden_size, 2).to(DEVICE)
         self.model.flag_head = nn.Linear(hidden_size, self.num_flags).to(DEVICE)
         self.model.flag_threshold_head = nn.Linear(hidden_size, self.num_flags).to(DEVICE)
 
-        # 4) 커스텀 헤드 가중치 로드
+        # 4) Load custom head weights separately (if available)
+        #  - this is necessary because the LoRA merging process may not include these heads, and they might be trained separately.
         for head_name, file_name in [
             ("delta_head", "delta_head.pt"),
             ("flag_head", "flag_head.pt"),
@@ -65,7 +69,7 @@ class ModelWrapper:
             except Exception as e:
                 print(f"[WARN] Failed to load {file_name}: {e}")
 
-        # 5) 디바이스 배치
+        # 5) Move model to device and set to eval mode
         self.model.to(DEVICE)
         self.model.eval()
 

modules/case_loader.py

@@ -1,15 +1,16 @@
-import os, json
-from webtest_prompt import build_webtest_prompt
+import json
+import os
+
 from inference import run_inference
+from webtest_prompt import build_webtest_prompt
 
-BASE_DIR = os.path.dirname(os.path.dirname(__file__))  # modules/ 상위 폴더
+BASE_DIR = os.path.dirname(os.path.dirname(__file__))
 TEST_CASES_PATH = os.path.join(BASE_DIR, "test_cases.json")
 
 with open(TEST_CASES_PATH, "r", encoding="utf-8") as f:
     TEST_CASES = json.load(f)
 
 def get_case_names():
-    # description은 input 안에 있음
     return [f"{i+1}. {c['input'].get('description','')}" for i, c in enumerate(TEST_CASES)]
 
 def load_cases():

modules/ui_components.py

@@ -1,7 +1,8 @@
 import gradio as gr
-from .case_loader import load_case, run_case
 
-# test case names
+from modules.case_loader import load_case, run_case
+
+# test case names (for dropdown display)
 CASE_NAMES = [
     "폐공장에서 NPC와 대화하는 장면",
     "마을 대장장이와 무기 수리에 대해 대화하는 장면",
@@ -35,9 +36,8 @@ def format_case_info(case: dict) -> dict:
 def build_ui():
     with gr.Blocks(theme=gr.themes.Soft(primary_hue="blue", secondary_hue="purple")) as demo:
         gr.Markdown("""
-        # 👾 CWIE Neuro Engine
-        **CWIE Core 모델 추론 서버**  
-        Qwen 3B 기반 LoRA 파인튜닝 모델을 사용하여 NPC 대사 생성 및 게임 상태변화를 예측합니다.
+        # 👾 CWIE Neural Engine
+        Qwen 3B 기반 LoRA 파인튜닝 모델을 사용하여 NPC 대사생성, 게임 상태변화 예측등 세계와 상호작용 하는 엔진을 실행합니다.
         """)
 
         with gr.Row():

webtest_prompt.py

@@ -1,9 +1,10 @@
-from typing import Dict, Any
+from typing import Any, Dict
+
 
 def build_webtest_prompt(npc_id: str, npc_location: str, player_utt: str) -> str:
     """
-    Web Test 전용: 최소 입력값(NPC ID, Location, Player 발화)으로
-    모델 학습 포맷에 맞는 prompt 문자열을 생성.
+    Web Test Only: Generate a prompt string suitable for the model training format 
+    using minimum input values (NPC ID, Location, Player utterance).
     """
     pre = {
         "npc_id": npc_id,
@@ -29,15 +30,15 @@ def build_webtest_prompt(npc_id: str, npc_location: str, player_utt: str) -> str
 
 def _assemble_prompt_for_model(pre: Dict[str, Any]) -> str:
     """
-    Web Test 전용 내부 함수:
-    pre dict → 모델 입력 포맷 문자열(<SYS>~<NPC>)
+    Web Test Only: Internal function for assembling the prompt string for the model.
+    pre dict → Model input format string (<SYS>~<NPC>)
     """
 
     tags = pre.get("tags", {})
     ps = pre.get("player_state", {})
     rag_docs = pre.get("rag_main_docs", [])
 
-    # RAG 문서 분리
+    # RAG documents are categorized into LORE and DESCRIPTION based on their content.
     lore_text = ""
     desc_text = ""
     for doc in rag_docs: