LoRA adapter, model card and training history

README.md

@@ -0,0 +1,110 @@
+---
+license: gemma
+base_model: google/gemma-4-E2B-it
+library_name: peft
+tags:
+  - lora
+  - peft
+  - doom
+  - vizdoom
+  - freedoom
+  - decision-model
+  - system-one
+  - laya
+  - gemma
+language:
+  - en
+---
+
+# doomGemma — Gemma 4 E2B LoRA for doomLaya decisions
+
+A LoRA adapter that turns **Gemma 4 E2B** into a typed decision model for the
+[doomLaya](https://github.com/azalio/doomLaya) FreeDoom agent. It was trained on
+**exactly the same 979 labelled questions** that were used to train
+[Laya v3](https://huggingface.co/azalio/laya-doom-v3) (a 421M "System One" encoder),
+so the two can be compared on equal data.
+
+The model does not play by itself. The doomLaya agent turns the game state into text
+(health, weapons, visible enemies with ids and distances, items, doors) and asks two
+multiple-choice questions, `command` and `weapon`; an executor aims, plans paths and
+presses buttons. **All choices belong to the model.**
+
+## Results (RTX 4070, 25 Sep 2026)
+
+130 held-out validation questions of doomLaya v3:
+
+| model | command | weapon | ECE (raw) |
+|---|---|---|---|
+| Gemma 4 E2B, zero-shot | 0.51 | 0.78 | 0.38 |
+| Laya v3 (azalio/laya-doom-v3) | 0.725 | 0.98 | 0.06 |
+| **this adapter (Q8_0 GGUF, via llama.cpp)** | **0.96** | **1.00** | **0.04** |
+
+FreeDoom **MAP01**, skill 3, 180 s limit, seeds 48–53 (none used for training or validation):
+
+| player | exits | mean time | range | deaths |
+|---|---|---|---|---|
+| Laya v3 | 6/6 | 59.5 s | 42.9–71.0 s | 0 |
+| **this adapter** | 6/6 | 60.0 s | 56.6–64.2 s | 0 |
+| rule-based teacher that produced the labels | 6/6 | 81.6 s | 64.5–124.9 s | 1 |
+
+The models exit faster than the rule-based teacher because they imitate it imperfectly
+and pick up fewer items; the teacher does not optimise time-to-exit.
+
+Latency on the same RTX 4070, same 1,416 recorded game packets:
+
+| setup | p50 | p99 |
+|---|---|---|
+| Laya v3, its own server | 23 ms | 25 ms |
+| this adapter, llama.cpp Q8_0 + grammar | 59 ms | 118 ms |
+| this adapter, direct PyTorch bf16 | 84 ms | 100 ms |
+
+## Limitations
+
+- Trained and validated **only on MAP01**. On **MAP02** nobody exits (0/3), **including
+  the rule-based teacher**: the chain stops at a **yellow-key door** (sector 37, linedef
+  special 27), which doomLaya offers as an openable door while the key is far away and
+  out of sight. Generalisation to new maps **cannot be measured** on this bench.
+- The labels come from a **rule-based teacher**, not from human play: the adapter learns
+  to imitate those rules.
+- The validation set is small (130 questions); calibration numbers carry noticeable noise.
+
+## How it is used
+
+Each option becomes a letter. A grammar allows a single token among the valid letters,
+and the option probabilities are read from the logprobs of that token
+(one prefill + one token, no free-form generation). The exact prompt:
+
+```python
+LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
+SYSTEM = ("You control a DOOM player in real time. "
+          "Pick the best option for each question. Reply only with the letters.")
+
+def build(state, name, question):            # one question per request
+    keys = list(question["criteria"])
+    lines = [f"{LETTERS[i]}) {question['criteria'][k]}" for i, k in enumerate(keys)]
+    user = (state + "\n\n" + f"{name.upper()} — {question.get('instructions', '')}\n"
+            + "\n".join(lines) + f"\n\nAnswer with 1 letter, in this order: {name.upper()}.")
+    return [{"role": "system", "content": SYSTEM}, {"role": "user", "content": user}], keys
+```
+
+The chat template is applied with `add_generation_prompt=True, enable_thinking=False`;
+the answer is the next token.
+
+## Training
+
+- Data: `training/v3/train.json` (979) and `validation.json` (130) from azalio/doomLaya
+  at commit `b25edd3` (Apache-2.0). Game seeds 42/43 for training, 44 for validation, MAP01 only.
+- LoRA rank 16, alpha 32, dropout 0.05 on `q,k,v,o,gate,up,down` of the language model;
+  AdamW, lr 1e-4, weight decay 0.01, gradient accumulation 8, clip 1.0, seed 771.
+  **Loss only on the answer letter.** Best epoch by validation accuracy (command + weapon):
+  **epoch 2 of 3**, 550 s per epoch on one RTX 4070 (history in `training_history.json`).
+- Base weights: `google/gemma-4-E2B-it` (`model.safetensors` sha256 `2db5482b…`).
+
+## Credits and licences
+
+- Base model: Google **Gemma 4 E2B**. This adapter is a Gemma derivative and is
+  distributed under the [Gemma Terms of Use](https://ai.google.dev/gemma/terms).
+- Training data and game harness: [azalio/doomLaya](https://github.com/azalio/doomLaya),
+  Apache-2.0 (see their NOTICE).
+- Laya: [Convai Innovations](https://huggingface.co/convaiinnovations/laya), Apache-2.0.
+- FreeDoom and ViZDoom under their respective licences.

adapter_config.json

@@ -0,0 +1,46 @@
+{
+  "alora_invocation_tokens": null,
+  "alpha_pattern": {},
+  "arrow_config": null,
+  "auto_mapping": {
+    "base_model_class": "Gemma4ForConditionalGeneration",
+    "parent_library": "transformers.models.gemma4.modeling_gemma4"
+  },
+  "base_model_name_or_path": "google/gemma-4-E2B-it",
+  "bias": "none",
+  "corda_config": null,
+  "ensure_weight_tying": false,
+  "eva_config": null,
+  "exclude_modules": null,
+  "fan_in_fan_out": false,
+  "inference_mode": true,
+  "init_lora_weights": true,
+  "kasa_config": null,
+  "layer_replication": null,
+  "layers_pattern": null,
+  "layers_to_transform": null,
+  "loftq_config": {},
+  "lora_alpha": 32,
+  "lora_bias": false,
+  "lora_dropout": 0.05,
+  "lora_ga_config": null,
+  "megatron_config": null,
+  "megatron_core": "megatron.core",
+  "modules_to_save": null,
+  "monteclora_config": null,
+  "peft_type": "LORA",
+  "peft_version": "0.21.0",
+  "qalora_group_size": 16,
+  "r": 16,
+  "rank_pattern": {},
+  "revision": null,
+  "target_modules": ".*language_model.*\\.(q_proj|k_proj|v_proj|o_proj|gate_proj|up_proj|down_proj)",
+  "target_parameters": null,
+  "task_type": null,
+  "trainable_token_indices": null,
+  "use_bdlora": null,
+  "use_dora": false,
+  "use_qalora": false,
+  "use_rslora": false,
+  "velora_config": null
+}

adapter_model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e1ac4eb4853311b509d87b5cf33be663e81e8220f223858ff02489253e289a83
+size 96693360

best_epoch.json

@@ -0,0 +1,7 @@
+{
+ "best_epoch": 2,
+ "validation_accuracy": {
+  "command": 0.95,
+  "weapon": 1.0
+ }
+}

training_history.json

@@ -0,0 +1,33 @@
+[
+ {
+  "epoch": 0,
+  "validation_accuracy": {
+   "command": 0.5125,
+   "weapon": 0.76
+  }
+ },
+ {
+  "epoch": 1,
+  "validation_accuracy": {
+   "command": 0.7875,
+   "weapon": 1.0
+  },
+  "seconds": 550.1
+ },
+ {
+  "epoch": 2,
+  "validation_accuracy": {
+   "command": 0.95,
+   "weapon": 1.0
+  },
+  "seconds": 549.8
+ },
+ {
+  "epoch": 3,
+  "validation_accuracy": {
+   "command": 0.9375,
+   "weapon": 1.0
+  },
+  "seconds": 550.1
+ }
+]