LLM-Tank: Gemma-3 270M robot-JSON weights + model card + demo

.gitattributes

@@ -33,3 +33,6 @@ 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
+demo.gif filter=lfs diff=lfs merge=lfs -text
+demo.mp4 filter=lfs diff=lfs merge=lfs -text
+tokenizer.json filter=lfs diff=lfs merge=lfs -text

README.md

@@ -1,3 +1,126 @@
 ---
-license: apache-2.0
+license: gemma
+base_model: unsloth/gemma-3-270m-it
+language:
+- en
+pipeline_tag: text-generation
+tags:
+- robotics
+- text-to-json
+- instruction-following
+- mujoco
+- gemma3
+library_name: transformers
 ---
+
+# LLM-Tank — Gemma-3 270M → robot JSON
+
+Fine-tuned **Gemma-3 270M** that translates **one free-form English
+instruction** for a tracked robot with a gripper arm into a strict JSON
+command list, executed in a **MuJoCo** simulation.
+
+Full pipeline: `text → this model → valid JSON → controller → robot
+drives / grasps`. Code & sim: see the source repository.
+
+![LLM-Tank demo](demo.gif)
+
+## What it outputs
+
+A single JSON object `{"commands": [ ... ]}`. Actions:
+
+- `move` — `direction` (forward|backward), `distance_m`, `speed?`
+- `turn` — `direction` (left|right), `angle_deg`, `speed?`
+- `stop`, `wait` — `duration_s`
+- `grasp` / `release` — optional `cell` ∈
+  `front|front_left|front_right|left|right` (discrete, relative to the
+  robot; IK is solved by the controller, **not** the model)
+- out-of-scope / nonsense → `{"commands": []}`
+
+The model emits **no coordinates** — only discrete actions/enums (this
+keeps generation reliable and schema-checkable).
+
+## Required input format (IMPORTANT)
+
+The model was trained `train == infer` with a **fixed short system
+prompt** folded with the instruction into ONE user turn. You must use
+exactly this:
+
+```python
+import json
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+SYSTEM = ("You translate ONE English instruction for a tracked robot "
+          "with a gripper arm into a single JSON object "
+          '{"commands":[...]} using actions: move, turn, stop, wait, '
+          "grasp, release. Output ONLY the JSON object, no prose, no "
+          'markdown. If the instruction is out of scope or nonsense, '
+          'output {"commands": []}.')
+
+tok = AutoTokenizer.from_pretrained("PATH_OR_REPO")
+model = AutoModelForCausalLM.from_pretrained("PATH_OR_REPO",
+                                             torch_dtype="auto",
+                                             device_map="auto")
+
+def translate(instruction: str) -> dict:
+    user = SYSTEM + "\n\n---\nINSTRUCTION: " + instruction.strip()
+    enc = tok.apply_chat_template(
+        [{"role": "user", "content": user}],
+        tokenize=True, add_generation_prompt=True,
+        return_dict=True, return_tensors="pt").to(model.device)
+    out = model.generate(**enc, max_new_tokens=160, do_sample=False)
+    txt = tok.decode(out[0][enc["input_ids"].shape[1]:],
+                     skip_special_tokens=True)
+    i, j = txt.find("{"), txt.rfind("}")
+    try:
+        return json.loads(txt[i:j + 1])
+    except Exception:
+        return {"commands": []}  # safe fallback
+
+print(translate("go forward 2 meters then turn left"))
+# {"commands": [{"action": "move", "direction": "forward",
+#   "distance_m": 2.0}, {"action": "turn", "direction": "left",
+#   "angle_deg": 90}]}
+print(translate("pick it up"))      # {"commands": [{"action": "grasp"}]}
+print(translate("make me a coffee"))# {"commands": []}
+```
+
+Greedy decoding (`do_sample=False`). The model is ~99% schema-valid
+without constrained decoding; always keep the safe fallback.
+
+## Metrics (held-out val, 352 examples: locomotion + manipulation + OOD)
+
+| metric | value |
+| --- | --- |
+| schema_valid_rate | 0.991 |
+| exact_match_rate | 0.943 |
+| action_seq_accuracy | 0.980 |
+| ood_f1 | 0.857 |
+| task_success (MuJoCo, 40) | 0.975 |
+
+## Training
+
+Full fine-tuning (not LoRA) of `unsloth/gemma-3-270m-it` on ~3.5k
+synthetic instruction→JSON pairs (generated with 120B models, validated
+against a JSON Schema). fp32, Kaggle T4. Two phases: locomotion, then
++ arm (grasp/release). Details in the source repo (`docs/`).
+
+## Demo
+
+`demo.mp4` (in this repo) — ~1 min, two panes: left = command + model
+JSON output, right = the robot acting in MuJoCo (real model + real
+physics, not staged).
+
+## Limitations
+
+- No perception: the model can't target objects by name/color, only by
+  discrete relative `cell`. Object resolution is spatial (controller
+  grabs the nearest graspable body in the chosen cell).
+- English only. Single fixed gripper, minimal custom arm.
+- Designed for the accompanying controller/sim; raw JSON is meaningless
+  without it.
+
+## License
+
+Weights are a derivative of Google **Gemma-3** — use is governed by the
+[Gemma Terms of Use](https://ai.google.dev/gemma/terms). Accompanying
+code is under its own license (see the source repository).

chat_template.jinja

@@ -0,0 +1,50 @@
+{# Unsloth Chat template fixes #}
+{{ bos_token }}
+{%- if messages[0]['role'] == 'system' -%}
+    {%- if messages[0]['content'] is string -%}
+        {%- set first_user_prefix = messages[0]['content'] + '
+
+' -%}
+    {%- else -%}
+        {%- set first_user_prefix = messages[0]['content'][0]['text'] + '
+
+' -%}
+    {%- endif -%}
+    {%- set loop_messages = messages[1:] -%}
+{%- else -%}
+    {%- set first_user_prefix = "" -%}
+    {%- set loop_messages = messages -%}
+{%- endif -%}
+{%- for message in loop_messages -%}
+    {%- if (message['role'] == 'user') != (loop.index0 % 2 == 0) -%}
+        {{ raise_exception("Conversation roles must alternate user/assistant/user/assistant/...") }}
+    {%- endif -%}
+    {%- if (message['role'] == 'assistant') -%}
+        {%- set role = "model" -%}
+    {%- else -%}
+        {%- set role = message['role'] -%}
+    {%- endif -%}
+    {{ '<start_of_turn>' + role + '
+' + (first_user_prefix if loop.first else "") }}
+    {%- if message['content'] is string -%}
+        {{ message['content'] | trim }}
+    {%- elif message['content'] is iterable -%}
+        {%- for item in message['content'] -%}
+            {%- if item['type'] == 'image' -%}
+                {{ '<start_of_image>' }}
+            {%- elif item['type'] == 'text' -%}
+                {{ item['text'] | trim }}
+            {%- endif -%}
+        {%- endfor -%}
+    {%- elif message['content'] is defined -%}
+        {{ raise_exception("Invalid content type") }}
+    {%- endif -%}
+    {{ '<end_of_turn>
+' }}
+{%- endfor -%}
+{%- if add_generation_prompt -%}
+    {{'<start_of_turn>model
+'}}
+{%- endif -%}
+
+{# Copyright 2025-present Unsloth. Apache 2.0 License. #}

config.json

@@ -0,0 +1,63 @@
+{
+  "_sliding_window_pattern": 6,
+  "architectures": [
+    "Gemma3ForCausalLM"
+  ],
+  "attention_bias": false,
+  "attention_dropout": 0.0,
+  "attn_logit_softcapping": null,
+  "bos_token_id": 2,
+  "dtype": "bfloat16",
+  "eos_token_id": 106,
+  "final_logit_softcapping": null,
+  "head_dim": 256,
+  "hidden_activation": "gelu_pytorch_tanh",
+  "hidden_size": 640,
+  "initializer_range": 0.02,
+  "intermediate_size": 2048,
+  "layer_types": [
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "sliding_attention",
+    "full_attention"
+  ],
+  "max_position_embeddings": 32768,
+  "model_type": "gemma3_text",
+  "num_attention_heads": 4,
+  "num_hidden_layers": 18,
+  "num_key_value_heads": 1,
+  "pad_token_id": 0,
+  "query_pre_attn_scalar": 256,
+  "rms_norm_eps": 1e-06,
+  "rope_parameters": {
+    "full_attention": {
+      "rope_theta": 1000000.0,
+      "rope_type": "default"
+    },
+    "sliding_attention": {
+      "rope_theta": 10000.0,
+      "rope_type": "default"
+    }
+  },
+  "sliding_window": 512,
+  "tie_word_embeddings": true,
+  "transformers_version": "5.0.0",
+  "unsloth_fixed": true,
+  "use_bidirectional_attention": false,
+  "use_cache": false,
+  "vocab_size": 262144
+}

demo.mp4

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

generation_config.json

@@ -0,0 +1,14 @@
+{
+  "bos_token_id": 2,
+  "cache_implementation": "hybrid",
+  "do_sample": true,
+  "eos_token_id": [
+    1,
+    106
+  ],
+  "max_length": 32768,
+  "pad_token_id": 0,
+  "top_k": 64,
+  "top_p": 0.95,
+  "transformers_version": "5.0.0"
+}

model.safetensors

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

tokenizer.json

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

tokenizer_config.json

@@ -0,0 +1,24 @@
+{
+  "backend": "tokenizers",
+  "boi_token": "<start_of_image>",
+  "bos_token": "<bos>",
+  "clean_up_tokenization_spaces": false,
+  "eoi_token": "<end_of_image>",
+  "eos_token": "<end_of_turn>",
+  "image_token": "<image_soft_token>",
+  "is_local": false,
+  "mask_token": "<mask>",
+  "model_max_length": 32768,
+  "model_specific_special_tokens": {
+    "boi_token": "<start_of_image>",
+    "eoi_token": "<end_of_image>",
+    "image_token": "<image_soft_token>"
+  },
+  "pad_token": "<pad>",
+  "padding_side": "left",
+  "sp_model_kwargs": null,
+  "spaces_between_special_tokens": false,
+  "tokenizer_class": "GemmaTokenizer",
+  "unk_token": "<unk>",
+  "use_default_system_prompt": false
+}