Add/update README (model card)

README.md

@@ -3,207 +3,198 @@ base_model: Qwen/Qwen3-1.7B
 library_name: peft
 pipeline_tag: text-generation
 tags:
-- base_model:adapter:Qwen/Qwen3-1.7B
 - lora
 - sft
 - transformers
 - trl
+- pokemon
+- pokemon-showdown
+- gen9ou
+- action-selection
 ---
 
-# Model Card for Model ID
-
-<!-- Provide a quick summary of what the model is/does. -->
+# Qwen3-1.7B PokéLLM LoRA (Gen9 OU / JSON Action Selector)
 
+**Summary:**  
+Qwen/Qwen3-1.7B を LoRA で事後学習し、ポケモン Showdown の Gen9 OU 対戦における **単手意思決定**（行動選択）を行う軽量アダプタです。  
+本モデルは、与えられた候補集合に対して **厳密 JSON** で `{"action":"index::<k>"}` を返すことを目的に最適化されています。  
+（`index::<k>` は、あなたのエージェントが提示する候補リストの 0-based インデックス）
 
+---
 
 ## Model Details
 
-### Model Description
-
-<!-- Provide a longer summary of what this model is. -->
-
+- **Base model:** `Qwen/Qwen3-1.7B`
+- **Adapter type:** LoRA (PEFT)
+- **Task:** Pokémon Showdown Gen9 OU の 1 手意思決定（行動選択）
+- **I/O 仕様:**  
+  入力: 観測（軽量テキスト or 構造化を文字列化）＋候補 `CANDIDATES`（内部で index にマッピング）  
+  出力: 厳密 JSON 一個 `{ "action": "index::<k>" }`
+- **Intended framework:** 🤗 Transformers + PEFT（PyTorch）
+- **License:** Base モデルに準拠（Qwen/Qwen3-1.7B のライセンスをご確認ください）
+- **Author :** _波浪 創(hellohazime)_
 
+### What this model is / isn’t
+- ✅ **すること**: 候補（技 / 交代など）から **1 つ**を選ぶ。  
+- ⚠️ **しないこと**: 一般的な雑談・長文生成・マルチターン方策学習・ダメージ計算の厳密再現。
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
-
-### Model Sources [optional]
-
-<!-- Provide the basic links for the model. -->
-
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+---
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
+- 対戦中の観測テキストと、候補キー（内部で `index` に変換したもの）を提示し、**1 手**を選択させる。
+- 出力は **必ず 1 行 1 JSON**。解析側は `action` を読み取り、あなたの `index_map[k]` に解決して実行してください。
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
-
-[More Information Needed]
-
-### Downstream Use [optional]
-
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
-
-[More Information Needed]
-
-### Out-of-Scope Use
-
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+### Downstream Use
+- poke-env / Pokémon Showdown クライアントと組み合わせれば、**ローカル対戦エージェント**として利用できます。
+- 学習済みプロンプト・スキーマに依存します。異なるスキーマで使う場合は再学習を推奨。
 
-[More Information Needed]
+### Out-of-Scope
+- 一般領域の対話、長文化・推論タスク、Gen9 OU 以外のフォーマットへの強い汎化は想定していません。
 
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
+---
 
-Use the code below to get started with the model.
+## How to Get Started
+
+### Load with PEFT (Transformers)
+
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+from peft import PeftModel
+
+BASE = "Qwen/Qwen3-1.7B"
+ADAPTER = "YOUR_USERNAME/qwen3-1p7b-pokellm-lora"  # ← あなたのリポ名に置換
+
+tok = AutoTokenizer.from_pretrained(BASE, trust_remote_code=True)
+if tok.pad_token_id is None and tok.eos_token_id is not None:
+    tok.pad_token = tok.eos_token
+
+base = AutoModelForCausalLM.from_pretrained(BASE, trust_remote_code=True, device_map="auto")
+model = PeftModel.from_pretrained(base, ADAPTER)
+
+# --- 推論の例（厳密JSONを狙うプロンプト） ---
+obs = "turn | 3\nyour_active | Gholdengo\nopp_active | Great Tusk\nmoves | Make It Rain, Shadow Ball, Trick, Focus Blast"
+# 例: allowed は内部で index に並べ替えた候補（move群→switch群）に対応
+allowed = ["index::0","index::1","index::2","index::3"]  # 例
+prompt = (
+    "You are a Gen9 OU single-battle agent.\n"
+    "Return exactly one JSON object on a single line.\n"
+    'Schema: {"action": "index::<k>"} No markdown, no extra text.\n'
+    f"ALLOWED: {' | '.join(allowed)}\n\n"
+    f"{obs}\n\n"
+    "Action:"
+)
+
+inputs = tok(prompt, return_tensors="pt").to(model.device)
+out_ids = model.generate(
+    **inputs,
+    max_new_tokens=48,
+    do_sample=False,  # 温度0相当
+    eos_token_id=tok.eos_token_id,
+    pad_token_id=tok.eos_token_id
+)
+print(tok.decode(out_ids[0], skip_special_tokens=True))
+````
+
+> **Note:** MLX ランタイムで LoRA を直接ロードするには別途変換が必要です（標準の PEFT/Torch では上記のように動作します）。
 
-[More Information Needed]
+---
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
+* 出典: `jakegrigsby/metamon-parsed-replays`（Showdown リプレイの構造化アーカイブ）
+* フィルタ: **Gen9 OU / Elo ≥ 1500** を中心に抽出・整形
+* 生成された SFT データは以下の**index スキーマ**（簡略）:
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+  * `system`: 「厳密 JSON で 1 手のみ返す」等の指示
+  * `user`: `{ "state": {...}, "CANDIDATES": ["index::0", ...] }`
+  * `assistant`: `{ "action": "index::<k>" }`
 
-#### Preprocessing [optional]
+### Preprocessing
 
-[More Information Needed]
+* 候補（move / switch）を **アルファベット順**に整列し、`index::<k>` に対応付け。
+* 観測は軽量テキスト（ターン/自他アクティブ/使用可能技の見出し名 etc.）に要約。
+* 長さ上限（cutoff）: 1024 tokens 目安。
 
+### Training Procedure (LoRA / SFT)
 
-#### Training Hyperparameters
+* **PEFT LoRA:** `r=8, alpha=16, dropout=0.05, bias="none"`
+  **target\_modules:** `q_proj, k_proj, v_proj, o_proj, gate_proj, up_proj, down_proj`
+* **Optimizer:** AdamW（`transformers.TrainingArguments(optim="adamw_torch")`）
+* **LR:** 2e-4 近辺（スモーク→本学習でスケール）
+* **Batch size:** 端末依存（例: `per_device_train_batch_size=8`, `gradient_accumulation_steps=1`）
+* **Max steps:** データサイズに応じて設定（例: 10–25k）
+* **Evaluation:** `eval_ratio ≈ 5%`, `eval_steps=500` 前後
+  `EarlyStoppingCallback(patience=3, metric=eval_loss)`
+* **Precision:** fp32（Mac/MPS で安定運用）
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+> 実行スクリプトは TRL `SFTTrainer` を用いた標準的な SFT（packing 無効、`formatting_func` で chat template を適用）構成です。
 
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+---
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
+### Protocol
 
-### Testing Data, Factors & Metrics
+* **環境:** ローカル Pokémon Showdown (:8080), `poke-env` 経由
+* **形式:** `gen9ou`（同一チーム同士で LLM vs Random の簡易ベースライン）
+* **強制スキーマ:** 厳密 JSON 一個（`{"action": "index::<k>"}`）
 
-#### Testing Data
+### Result (example)
 
-<!-- This should link to a Dataset Card if possible. -->
+```
+| Model                                   | Backend | Format | Schema | Win% | Fallback% | Avg Lat(ms) | p95(ms) | Decis. | Battles |
+|-----------------------------------------|---------|--------|--------|-----:|----------:|------------:|--------:|-------:|--------:|
+| Qwen/Qwen3-1.7B + <this adapter>        | hf      | gen9ou | index  | 80.0 |      0.0  |      1645.4 |  1728.6 |    346 |     10 |
+```
 
-[More Information Needed]
+* **補足:** 対戦相手は poke-env の `RandomPlayer`。本 LoRA の “index スキーマ厳守” と最小限観測だけで、安定した JSON 出力を確認。
+* さらなる妥当性評価（他フォーマット、強い相手、別チーム、長期戦）や人手検証は今後の課題です。
 
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
+---
 
-#### Software
+## Bias, Risks, and Limitations
 
-[More Information Needed]
+* 単手方策であり、**長期的なプランニングやリソース管理**は学習していません。
+* **index スキーマ依存**のため、プロンプト逸脱や候補整列順の不一致で性能が大きく劣化します。
+* データは公開リプレイ由来で、**プレイヤースキルやメタ**に偏りがあり得ます。
+* ダメージ計算・乱数・特性相互作用は**簡略観測**のみで与えており、**完全再現ではありません**。
 
-## Citation [optional]
+### Recommendations
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+* 生成の健全性チェック（JSON 解析、候補外出力のフォールバック）を必ず実装してください。
+* 実運用では **評価対戦の拡充**（様々な構築・相手・ルール）を推奨します。
 
-**BibTeX:**
+---
 
-[More Information Needed]
+## Technical Specifications
 
-**APA:**
+### Architecture
 
-[More Information Needed]
+* Qwen3-1.7B（Causal LM）+ LoRA（PEFT）
 
-## Glossary [optional]
+### Software
 
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
+* Transformers / TRL / PEFT / PyTorch（MPS）
+* Tokenizer は base に付属の chat template を使用（無い場合は簡易フォールバック）
 
-[More Information Needed]
+---
 
-## More Information [optional]
+## How to Cite / Credit
 
-[More Information Needed]
+* Base: **Qwen/Qwen3-1.7B**
+* Data inspiration: **metamon-parsed-replays**（Showdown 由来の公開リプレイ構造化）
 
-## Model Card Authors [optional]
+---
 
-[More Information Needed]
+## Model Card Authors 
 
-## Model Card Contact
+* 波浪 創(hellohazime) *
 
-[More Information Needed]
 ### Framework versions
 
-- PEFT 0.17.1
+* PEFT 0.17.1（動作確認）
+* Transformers / TRL は 2025 時点の安定版で確認（詳細は `training_args.bin` を参照）