Upload folder using huggingface_hub

.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m tests.test_parser)"
+    ]
+  }
+}

.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+.env
+*.log
+saves/
+.gradio/
+flagged/
+finetune/out/
+finetune/data/

README.md

@@ -1,13 +1,141 @@
 ---
-title: Micro Rpg Engine
-emoji: 🏆
-colorFrom: yellow
-colorTo: yellow
+title: Micro RPG Engine
+emoji: 🍄
+colorFrom: purple
+colorTo: indigo
 sdk: gradio
-sdk_version: 6.18.0
-python_version: '3.13'
+sdk_version: 5.50.0
 app_file: app.py
-pinned: false
+pinned: true
+license: apache-2.0
+short_description: A whole RPG world generated live by a small 1B-4B model.
+tags:
+  - small-models-hackathon
+  - thousand-token-wood
+  - rpg
+  - text-adventure
+  - qwen
+  - minicpm
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<!-- SUBMISSÃO — preencher antes de submeter:
+  Demo video: <COLE O LINK DO VÍDEO AQUI>
+  Social post: <COLE O LINK DO POST AQUI>
+  Track: Thousand Token Wood (entretenimento/whimsical)
+  ⚠️ Confirme o slug exato da tag de track no template da org build-small-hackathon.
+-->
+
+> **🎥 Demo video:** _<adicionar link>_ &nbsp;•&nbsp; **📣 Social post:** _<adicionar link>_
+
+# 🍄 Micro RPG Engine
+
+A text RPG where a **small language model (1B–4B)** generates *everything* in real
+time — the world, NPCs, dialogue, combat, the shop, random events. There is no
+pre-written content. **No AI, no game.** Every playthrough is unique.
+
+> Hugging Face Small Models Hackathon — **Track 2**
+
+## The technical bet
+
+The hard part with small models isn't writing pretty prose — it's **narrative
+consistency**: not forgetting your HP, your inventory, that you already killed the
+goblin. A generic "RPG-themed chatbot" loses the plot in three turns.
+
+Our approach makes the **Python engine the source of truth**, not the model:
+
+```
+                 ┌─────────────────────────────────────────┐
+   player input  │  GameEngine (turn loop)                  │
+  ───────────────▶                                          │
+                 │  1. build context from GameState  ───────┼──▶  System prompt
+                 │  2. call the 1B-4B model                  │     + authoritative
+                 │  3. parse output  ◀──────────────────────┼─────  state snapshot
+                 │     ├─ <narrative> → shown to player      │
+                 │     └─ <state> tags → VALIDATED & applied │
+                 │  4. GameState mutates (HP, gold, items)   │
+                 └─────────────────────────────────────────┘
+```
+
+The model never *remembers* the numbers — it receives them, fresh, every turn, and
+may only *propose* deltas (`HP: -10`, `ITEM_ADD: Rusty Sword`) through a strict tag
+protocol. The parser clamps and validates every change against the real state. The
+model handles imagination; Python handles bookkeeping. That's what keeps a 1.5B
+model coherent across a long dungeon crawl.
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+By default it loads the model with `transformers`. To run with no local GPU, set a
+Hugging Face token and it falls back to the serverless Inference API:
+
+```bash
+# Windows PowerShell
+$env:HF_TOKEN = "hf_..."
+$env:MICRORPG_BACKEND = "inference_api"
+python app.py
+```
+
+## Configuration (env vars)
+
+| Variable             | Default                       | Meaning                                  |
+|----------------------|-------------------------------|------------------------------------------|
+| `MICRORPG_MODEL`     | `Qwen/Qwen3-4B-Instruct-2507` | Model repo id                            |
+| `MICRORPG_BACKEND`   | `transformers`                | `transformers` \| `inference_api` \| `mock` |
+| `HF_TOKEN`           | —                             | Token for the Inference API backend      |
+| `MICRORPG_MAX_TOKENS`| `512`                         | Max new tokens per turn                  |
+
+Set `MICRORPG_BACKEND=mock` to run the full engine with a deterministic fake model
+(no weights, no network) — handy for testing the parser and UI.
+
+## Fine-tuning (the "Well-Tuned" quest)
+
+The hard skill for a small model here is emitting the strict three-block tag format
+with valid mechanics, every turn. We teach it with a **parser-validated synthetic
+dataset**: `build_dataset.py` generates RPG turns in the exact protocol, then runs
+**every single one through the real engine parser** and keeps only those that parse
+and apply cleanly. 100% of the training data is guaranteed well-formed.
+
+```bash
+pip install -r requirements-train.txt          # GPU / Colab
+python -m finetune.build_dataset --n 1200       # offline, no model needed
+python -m finetune.train \
+    --model Qwen/Qwen3-4B-Instruct-2507 \
+    --out finetune/out/qwen3-4b-microrpg        # LoRA, ~few MB adapter
+```
+
+Play with your fine-tuned model by pointing the engine at the adapter:
+
+```bash
+# Windows PowerShell
+$env:MICRORPG_ADAPTER = "finetune/out/qwen3-4b-microrpg"
+python app.py
+```
+
+The dataset is model-agnostic — swap `--model` for MiniCPM, or a Llama for the
+**Llama Champion** quest. Add `--load-4bit` for QLoRA on a small GPU.
+
+## Project layout
+
+```
+app.py              Gradio UI + glue
+style.css           Custom theme (parchment / arcane)
+engine/
+  game_state.py     GameState: HP, gold, inventory, location, NPCs, quest log
+  prompts.py        System prompt + the tag protocol the model must follow
+  llm.py            Model backends (transformers / inference API / mock)
+  parser.py         Splits narrative from mechanics, validates deltas
+  engine.py         GameEngine: the turn loop
+finetune/
+  build_dataset.py  Parser-validated synthetic turns → train.jsonl / eval.jsonl
+  train.py          LoRA SFT (TRL/PEFT); produces a small adapter
+tests/
+  test_parser.py    Parser/engine smoke tests (run with mock backend)
+```
+
+## License
+
+Apache-2.0.

app.py

@@ -0,0 +1,166 @@
+"""Micro RPG Engine — Gradio app.
+
+A text RPG generated live by a small (1B-4B) language model. The model imagines;
+Python keeps the books. See README.md for the architecture.
+
+Run:    python app.py
+Test:   MICRORPG_BACKEND=mock python app.py     (no weights, no network)
+"""
+
+from __future__ import annotations
+
+import os
+import gradio as gr
+
+from engine import GameEngine, GameState, build_backend
+from engine.parser import TurnResult
+
+
+BACKEND_KIND = os.environ.get("MICRORPG_BACKEND", "transformers")
+MODEL_ID = os.environ.get("MICRORPG_MODEL", "Qwen/Qwen3-4B-Instruct-2507")
+
+# Build the backend once at startup (loading weights can be slow).
+_backend = build_backend(BACKEND_KIND, MODEL_ID)
+
+
+# --------------------------------------------------------------------------- #
+# rendering helpers
+# --------------------------------------------------------------------------- #
+def render_story(history: list[TurnResult]) -> str:
+    """Render the running story as markdown."""
+    if not history:
+        return "_Press **Begin Adventure** to enter the world..._"
+    parts = []
+    for i, turn in enumerate(history):
+        if turn.narrative:
+            parts.append(turn.narrative)
+        if turn.applied:
+            parts.append("> " + " · ".join(turn.applied))
+    return "\n\n".join(parts)
+
+
+def render_stats(state: GameState) -> str:
+    hp_pct = int(100 * state.hp / max(1, state.max_hp))
+    bar = (
+        f'<div class="hpbar"><div class="hpfill" style="width:{hp_pct}%"></div></div>'
+    )
+    lines = [
+        "### ⚔️ Hero",
+        f"**HP** {state.hp}/{state.max_hp}",
+        bar,
+        f"**Level** {state.level} &nbsp; (XP {state.xp}/{state.level*10})",
+        f"**Gold** {state.gold} 🪙",
+        f"**Location** {state.location}",
+        "",
+        "**Inventory**",
+    ]
+    lines += [f"- {it}" for it in state.inventory] or ["- (empty)"]
+    if state.enemy and state.enemy.alive:
+        e = state.enemy
+        lines += ["", f"### 🗡️ Combat", f"**{e.name}** — {e.hp}/{e.max_hp} HP"]
+    if state.npcs:
+        lines += ["", "**Known characters**"]
+        lines += [f"- {n.name} ({n.role or n.disposition})" for n in state.npcs.values()]
+    if state.game_over:
+        lines += ["", "### 💀 **GAME OVER**"]
+    return "\n".join(lines)
+
+
+def choice_updates(choices: list[str]):
+    """Map up to 3 model-proposed choices onto the three choice buttons."""
+    updates = []
+    for i in range(3):
+        if i < len(choices):
+            updates.append(gr.update(value=choices[i], visible=True))
+        else:
+            updates.append(gr.update(visible=False))
+    return updates
+
+
+# --------------------------------------------------------------------------- #
+# event handlers (engine lives in gr.State so each browser session is isolated)
+# --------------------------------------------------------------------------- #
+def new_game():
+    engine = GameEngine(_backend)
+    turn = engine.start()
+    return (
+        engine,
+        render_story(engine.history),
+        render_stats(engine.state),
+        *choice_updates(turn.choices),
+        "",  # clear the textbox
+    )
+
+
+def take_action(engine: GameEngine, action: str):
+    if engine is None:
+        engine = GameEngine(_backend)
+        engine.start()
+    if action and action.strip():
+        turn = engine.act(action)
+    else:
+        turn = engine.history[-1] if engine.history else engine.start()
+    return (
+        engine,
+        render_story(engine.history),
+        render_stats(engine.state),
+        *choice_updates(turn.choices),
+        "",
+    )
+
+
+# --------------------------------------------------------------------------- #
+# UI
+# --------------------------------------------------------------------------- #
+def build_ui():
+    css_path = os.path.join(os.path.dirname(__file__), "style.css")
+    css = open(css_path, encoding="utf-8").read() if os.path.exists(css_path) else ""
+
+    with gr.Blocks(css=css, title="Micro RPG Engine", theme=gr.themes.Base()) as demo:
+        engine_state = gr.State(None)
+
+        gr.Markdown(
+            f"# 🍄 Micro RPG Engine\n"
+            f"*A world dreamed up live by a small model — `{MODEL_ID}` "
+            f"({BACKEND_KIND}). No AI, no game.*",
+            elem_id="title-md",
+        )
+
+        with gr.Row():
+            with gr.Column(scale=3):
+                story = gr.Markdown(render_story([]), elem_id="story")
+            with gr.Column(scale=1):
+                stats = gr.Markdown("", elem_id="stats")
+
+        with gr.Row():
+            c1 = gr.Button("...", visible=False, variant="secondary")
+            c2 = gr.Button("...", visible=False, variant="secondary")
+            c3 = gr.Button("...", visible=False, variant="secondary")
+
+        with gr.Row():
+            action = gr.Textbox(
+                placeholder="...or type your own action and press Enter",
+                show_label=False,
+                elem_id="action-input",
+                scale=4,
+            )
+            send = gr.Button("Act", variant="primary", scale=1)
+
+        with gr.Row():
+            begin = gr.Button("🎲 Begin / Restart Adventure", variant="primary")
+
+        outputs = [engine_state, story, stats, c1, c2, c3, action]
+
+        begin.click(new_game, outputs=outputs)
+        send.click(take_action, inputs=[engine_state, action], outputs=outputs)
+        action.submit(take_action, inputs=[engine_state, action], outputs=outputs)
+
+        # Clicking a choice button sends that choice text as the action.
+        for btn in (c1, c2, c3):
+            btn.click(take_action, inputs=[engine_state, btn], outputs=outputs)
+
+    return demo
+
+
+if __name__ == "__main__":
+    build_ui().launch()

engine/__init__.py

@@ -0,0 +1,7 @@
+"""Micro RPG Engine — a text RPG driven by a small (1B-4B) language model."""
+
+from .game_state import GameState, NPC, Enemy
+from .engine import GameEngine
+from .llm import build_backend
+
+__all__ = ["GameState", "NPC", "Enemy", "GameEngine", "build_backend"]

engine/engine.py

@@ -0,0 +1,65 @@
+"""The turn loop.
+
+GameEngine ties the pieces together:
+
+    player action ─▶ build prompt from GameState ─▶ model.chat() ─▶ parser
+                  ◀─ narrative + updated state ◀────────────────────┘
+
+It also enforces a couple of rules the model should not be trusted with:
+  * if the model forgets to make a defeated enemy stop attacking, combat still ends
+    when enemy HP hits 0 (handled in the parser);
+  * a guaranteed enemy counter-attack option exists even if the model is lazy
+    (the engine never *adds* damage on its own — it only ever clamps).
+"""
+
+from __future__ import annotations
+
+from .game_state import GameState
+from .llm import Backend
+from . import prompts, parser
+
+
+class GameEngine:
+    def __init__(self, backend: Backend, state: GameState | None = None):
+        self.backend = backend
+        self.state = state or GameState()
+        self.history: list[parser.TurnResult] = []
+
+    # ------------------------------------------------------------------ public
+    def start(self) -> parser.TurnResult:
+        """Generate the opening scene."""
+        user = prompts.build_opening_prompt(self.state.context_snapshot())
+        return self._turn(user)
+
+    def act(self, player_action: str) -> parser.TurnResult:
+        """Process one player action."""
+        if self.state.game_over:
+            return parser.TurnResult(
+                narrative="Your tale has ended. Start a new adventure to play again.",
+                choices=[],
+                applied=[],
+                raw="",
+            )
+        action = player_action.strip() or "look around"
+        user = prompts.build_turn_prompt(self.state.context_snapshot(), action)
+        return self._turn(user)
+
+    def reset(self) -> "GameEngine":
+        self.state = GameState()
+        self.history.clear()
+        return self
+
+    # ----------------------------------------------------------------- internal
+    def _turn(self, user_message: str) -> parser.TurnResult:
+        try:
+            raw = self.backend.chat(prompts.SYSTEM_PROMPT, user_message)
+        except Exception as exc:  # network/model errors shouldn't crash the UI
+            return parser.TurnResult(
+                narrative=f"(The mists swirl — the storyteller faltered: {exc})",
+                choices=["Try again."],
+                applied=[],
+                raw="",
+            )
+        result = parser.run_turn(self.state, raw)
+        self.history.append(result)
+        return result

engine/game_state.py

@@ -0,0 +1,170 @@
+"""The authoritative game state.
+
+The whole point of the engine is that *this* is the source of truth, not the
+language model. The model proposes changes; `GameState` (via the parser) decides
+what actually happens, clamping every value to a legal range. A small model can
+hallucinate "you now have 9000 HP" — the state will not let it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, asdict
+from typing import Optional
+import json
+
+
+MAX_HP_CAP = 999
+MAX_INVENTORY = 24
+
+
+@dataclass
+class Enemy:
+    """An enemy currently in combat. `None` on the state means no active fight."""
+
+    name: str
+    hp: int
+    max_hp: int
+    attack: int = 3
+
+    @property
+    def alive(self) -> bool:
+        return self.hp > 0
+
+
+@dataclass
+class NPC:
+    """A named character the model has introduced. Persisted so the model can be
+    reminded who exists — this is a big lever for consistency."""
+
+    name: str
+    role: str = ""          # "blacksmith", "old hermit", ...
+    disposition: str = "neutral"   # friendly / neutral / hostile
+    note: str = ""          # one-line memory, e.g. "owes you a favour"
+
+
+@dataclass
+class GameState:
+    # --- vitals ---
+    hp: int = 20
+    max_hp: int = 20
+    gold: int = 10
+    level: int = 1
+    xp: int = 0
+
+    # --- world ---
+    location: str = "The Crossroads"
+    inventory: list[str] = field(default_factory=lambda: ["Rusty Dagger", "Bread"])
+    npcs: dict[str, NPC] = field(default_factory=dict)
+    quest: str = "Discover why the village of Mossfall fell silent."
+
+    # --- combat (None when not fighting) ---
+    enemy: Optional[Enemy] = None
+
+    # --- meta ---
+    turn: int = 0
+    game_over: bool = False
+    log: list[str] = field(default_factory=list)
+
+    # ------------------------------------------------------------------ vitals
+    def damage(self, amount: int) -> None:
+        amount = max(0, int(amount))
+        self.hp = max(0, self.hp - amount)
+        if self.hp == 0:
+            self.game_over = True
+
+    def heal(self, amount: int) -> None:
+        amount = max(0, int(amount))
+        self.hp = min(self.max_hp, self.hp + amount)
+
+    def add_gold(self, amount: int) -> None:
+        self.gold = max(0, self.gold + int(amount))
+
+    def add_xp(self, amount: int) -> None:
+        self.xp += max(0, int(amount))
+        # simple, legible leveling curve: 10 * level to advance
+        while self.xp >= self.level * 10:
+            self.xp -= self.level * 10
+            self.level += 1
+            self.max_hp = min(MAX_HP_CAP, self.max_hp + 5)
+            self.hp = self.max_hp  # full heal on level-up
+            self.log.append(f"LEVEL UP → {self.level} (max HP {self.max_hp})")
+
+    # --------------------------------------------------------------- inventory
+    def add_item(self, item: str) -> bool:
+        item = item.strip()
+        if not item or len(self.inventory) >= MAX_INVENTORY:
+            return False
+        self.inventory.append(item)
+        return True
+
+    def remove_item(self, item: str) -> bool:
+        item = item.strip().lower()
+        for i, owned in enumerate(self.inventory):
+            if owned.lower() == item:
+                self.inventory.pop(i)
+                return True
+        return False
+
+    def has_item(self, item: str) -> bool:
+        item = item.strip().lower()
+        return any(owned.lower() == item for owned in self.inventory)
+
+    # --------------------------------------------------------------------- npc
+    def upsert_npc(self, npc: NPC) -> None:
+        key = npc.name.strip().lower()
+        if not key:
+            return
+        if key in self.npcs:
+            # merge: keep old note unless a new non-empty one is given
+            old = self.npcs[key]
+            old.role = npc.role or old.role
+            old.disposition = npc.disposition or old.disposition
+            old.note = npc.note or old.note
+        else:
+            self.npcs[key] = npc
+
+    # ------------------------------------------------------------------ combat
+    def start_combat(self, enemy: Enemy) -> None:
+        self.enemy = enemy
+
+    def end_combat(self) -> None:
+        self.enemy = None
+
+    # ----------------------------------------------------------- (de)serialize
+    def to_dict(self) -> dict:
+        d = asdict(self)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "GameState":
+        d = dict(d)
+        if d.get("enemy"):
+            d["enemy"] = Enemy(**d["enemy"])
+        if d.get("npcs"):
+            d["npcs"] = {k: NPC(**v) for k, v in d["npcs"].items()}
+        return cls(**d)
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+
+    # ------------------------------------------------------------ for the LLM
+    def context_snapshot(self) -> str:
+        """A compact, human-readable snapshot fed to the model every turn so it
+        never has to remember the numbers itself."""
+        lines = [
+            f"HP: {self.hp}/{self.max_hp}",
+            f"Level: {self.level}  XP: {self.xp}/{self.level * 10}",
+            f"Gold: {self.gold}",
+            f"Location: {self.location}",
+            f"Inventory: {', '.join(self.inventory) if self.inventory else '(empty)'}",
+            f"Current quest: {self.quest}",
+        ]
+        if self.enemy and self.enemy.alive:
+            e = self.enemy
+            lines.append(f"IN COMBAT with {e.name} ({e.hp}/{e.max_hp} HP, atk {e.attack})")
+        if self.npcs:
+            known = "; ".join(
+                f"{n.name} ({n.role or n.disposition})" for n in self.npcs.values()
+            )
+            lines.append(f"Known characters: {known}")
+        return "\n".join(lines)

engine/llm.py

@@ -0,0 +1,178 @@
+"""Model backends.
+
+Three interchangeable backends behind one tiny interface:
+
+    backend.chat(system: str, user: str) -> str
+
+- `transformers`    : load the small model locally (default; GPU or CPU).
+- `inference_api`   : call the Hugging Face serverless Inference API (no GPU).
+- `mock`            : a deterministic fake that emits valid tagged output, so the
+                      parser, engine and UI can be tested with no weights / network.
+
+Pick with the MICRORPG_BACKEND env var. See README for all knobs.
+"""
+
+from __future__ import annotations
+
+import os
+import random
+from typing import Protocol
+
+
+DEFAULT_MODEL = os.environ.get("MICRORPG_MODEL", "Qwen/Qwen3-4B-Instruct-2507")
+MAX_NEW_TOKENS = int(os.environ.get("MICRORPG_MAX_TOKENS", "512"))
+
+
+class Backend(Protocol):
+    name: str
+
+    def chat(self, system: str, user: str) -> str: ...
+
+
+# --------------------------------------------------------------------------- #
+# transformers (local)
+# --------------------------------------------------------------------------- #
+class TransformersBackend:
+    name = "transformers"
+
+    def __init__(self, model_id: str = DEFAULT_MODEL):
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        self.model_id = model_id
+        adapter = os.environ.get("MICRORPG_ADAPTER")  # fine-tuned LoRA dir, optional
+
+        # If an adapter is given, the tokenizer was saved alongside it (and may carry
+        # the right chat template) — prefer it; otherwise load the base tokenizer.
+        self.tokenizer = AutoTokenizer.from_pretrained(adapter or model_id)
+        dtype = torch.bfloat16 if torch.cuda.is_available() else torch.float32
+        self.model = AutoModelForCausalLM.from_pretrained(
+            model_id,
+            torch_dtype=dtype,
+            device_map="auto" if torch.cuda.is_available() else None,
+        )
+        if adapter:
+            from peft import PeftModel
+            self.model = PeftModel.from_pretrained(self.model, adapter)
+            print(f"[llm] loaded fine-tuned adapter: {adapter}")
+        self._torch = torch
+
+    def chat(self, system: str, user: str) -> str:
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        inputs = self.tokenizer.apply_chat_template(
+            messages, add_generation_prompt=True, return_tensors="pt"
+        ).to(self.model.device)
+
+        with self._torch.no_grad():
+            out = self.model.generate(
+                inputs,
+                max_new_tokens=MAX_NEW_TOKENS,
+                do_sample=True,
+                temperature=0.8,
+                top_p=0.9,
+                repetition_penalty=1.1,
+                pad_token_id=self.tokenizer.eos_token_id,
+            )
+        text = self.tokenizer.decode(
+            out[0][inputs.shape[-1]:], skip_special_tokens=True
+        )
+        return text.strip()
+
+
+# --------------------------------------------------------------------------- #
+# Hugging Face Inference API (serverless, no local GPU)
+# --------------------------------------------------------------------------- #
+class InferenceAPIBackend:
+    name = "inference_api"
+
+    def __init__(self, model_id: str = DEFAULT_MODEL):
+        from huggingface_hub import InferenceClient
+
+        token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+        self.model_id = model_id
+        self.client = InferenceClient(model=model_id, token=token)
+
+    def chat(self, system: str, user: str) -> str:
+        resp = self.client.chat_completion(
+            messages=[
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            max_tokens=MAX_NEW_TOKENS,
+            temperature=0.8,
+            top_p=0.9,
+        )
+        return resp.choices[0].message.content.strip()
+
+
+# --------------------------------------------------------------------------- #
+# mock (no weights, no network) — emits valid tagged output
+# --------------------------------------------------------------------------- #
+class MockBackend:
+    """Deterministic-ish fake model. It reads the action out of the user message
+    and produces a plausible tagged turn so the rest of the stack can be exercised
+    end-to-end without any model. Not smart — just well-formed."""
+
+    name = "mock"
+
+    _SCENES = [
+        ("A cold wind drags mist across {loc}. Something shifts in the dark ahead.",
+         "ENEMY: Mist Wraith|hp=10|atk=3"),
+        ("You find a leather pouch half-buried in the mud. Coins glint inside.",
+         "GOLD: +7"),
+        ("An old hermit beckons you toward a flickering lantern.",
+         "NPC: Aldric|hermit|friendly|knows the old roads"),
+        ("A rusted chest yields a glimmer of steel.",
+         "ITEM_ADD: Iron Shortsword"),
+        ("The path opens onto a ruined chapel, its bell long silent.",
+         "LOCATION: The Ruined Chapel"),
+    ]
+
+    def __init__(self, model_id: str = "mock"):
+        self.model_id = model_id
+        self._rng = random.Random(7)
+
+    def chat(self, system: str, user: str) -> str:
+        action = user.lower()
+        loc = "the crossroads"
+        for line in user.splitlines():
+            if line.lower().startswith("location:"):
+                loc = line.split(":", 1)[1].strip()
+
+        # Combat-aware: if the player attacks, hurt the enemy and take a hit back.
+        if "in combat" in action and any(
+            w in action for w in ("attack", "strike", "hit", "swing", "stab")
+        ):
+            narrative = "You lunge forward and your blade bites home; the creature shrieks and claws back."
+            state = "ENEMY_HP: -6\nHP: -3\nXP: +4"
+            choices = ["1. Press the attack.", "2. Back away and guard.", "3. Try to flee."]
+        else:
+            scene, change = self._rng.choice(self._SCENES)
+            narrative = scene.format(loc=loc)
+            state = change
+            choices = ["1. Investigate closely.", "2. Move on carefully.", "3. Call out."]
+
+        return (
+            f"<narrative>\n{narrative}\n</narrative>\n"
+            f"<state>\n{state}\n</state>\n"
+            f"<choices>\n" + "\n".join(choices) + "\n</choices>"
+        )
+
+
+# --------------------------------------------------------------------------- #
+# factory
+# --------------------------------------------------------------------------- #
+def build_backend(kind: str | None = None, model_id: str | None = None) -> Backend:
+    kind = (kind or os.environ.get("MICRORPG_BACKEND", "transformers")).lower()
+    model_id = model_id or DEFAULT_MODEL
+
+    if kind == "mock":
+        return MockBackend()
+    if kind in ("inference_api", "api", "inference"):
+        return InferenceAPIBackend(model_id)
+    if kind in ("transformers", "local"):
+        return TransformersBackend(model_id)
+    raise ValueError(f"Unknown backend: {kind!r}")

engine/parser.py

@@ -0,0 +1,201 @@
+"""Output parser.
+
+Turns the model's raw text into (narrative, choices, list-of-deltas), then applies
+the deltas to the GameState with full validation. This module is where "the model
+proposes, Python disposes" actually happens.
+
+It is intentionally forgiving about formatting (small models drift) but strict about
+*effects*: an unparseable number is ignored, an unknown key is ignored, and every
+applied change is clamped by GameState.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .game_state import GameState, NPC, Enemy
+
+
+@dataclass
+class TurnResult:
+    narrative: str
+    choices: list[str]
+    applied: list[str]          # human-readable list of what changed
+    raw: str                    # original model text (for debugging)
+
+
+_BLOCK = lambda tag, text: _extract_block(tag, text)
+
+
+def _extract_block(tag: str, text: str) -> str:
+    """Grab the content between <tag> ... </tag>. Tolerates a missing closing tag
+    by reading to the next block or end of string."""
+    # normal, well-formed case
+    m = re.search(rf"<{tag}>(.*?)</{tag}>", text, re.DOTALL | re.IGNORECASE)
+    if m:
+        return m.group(1).strip()
+    # lenient: <tag> with no close — read until the next <...> or EOS
+    m = re.search(rf"<{tag}>(.*?)(?=<\w+>|\Z)", text, re.DOTALL | re.IGNORECASE)
+    if m:
+        return m.group(1).strip()
+    return ""
+
+
+def parse(raw: str) -> tuple[str, list[str], list[str]]:
+    """Return (narrative, choices, raw_state_lines) from model text."""
+    narrative = _extract_block("narrative", raw)
+    state_block = _extract_block("state", raw)
+    choices_block = _extract_block("choices", raw)
+
+    # Fallback: if there were no tags at all, treat the whole thing as narrative.
+    if not narrative and not state_block and not choices_block:
+        narrative = raw.strip()
+
+    choices: list[str] = []
+    for line in choices_block.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        # strip leading "1." / "1)" / "- " markers
+        line = re.sub(r"^\s*(?:\d+[.)]|[-*•])\s*", "", line)
+        if line:
+            choices.append(line)
+
+    state_lines = [ln.strip() for ln in state_block.splitlines() if ln.strip()]
+    return narrative, choices, state_lines
+
+
+def _parse_int(token: str) -> int | None:
+    m = re.search(r"[-+]?\d+", token)
+    return int(m.group()) if m else None
+
+
+def apply_state_changes(state: GameState, state_lines: list[str]) -> list[str]:
+    """Validate and apply each proposed change. Returns a human-readable changelog."""
+    applied: list[str] = []
+
+    for line in state_lines:
+        if ":" not in line and not line.upper().startswith(("ENEMY_DEFEATED", "GAME_OVER")):
+            continue
+
+        key, _, value = line.partition(":")
+        key = key.strip().upper()
+        value = value.strip()
+
+        if key == "HP":
+            n = _parse_int(value)
+            if n is None:
+                continue
+            if n < 0:
+                state.damage(-n)
+                applied.append(f"HP {n}")
+            else:
+                state.heal(n)
+                applied.append(f"HP +{n}")
+
+        elif key == "GOLD":
+            n = _parse_int(value)
+            if n is not None:
+                state.add_gold(n)
+                applied.append(f"Gold {n:+d}")
+
+        elif key == "XP":
+            n = _parse_int(value)
+            if n is not None and n > 0:
+                before = state.level
+                state.add_xp(n)
+                applied.append(f"XP +{n}")
+                if state.level > before:
+                    applied.append(f"Level up → {state.level}")
+
+        elif key == "ITEM_ADD":
+            if value and state.add_item(value):
+                applied.append(f"+ {value}")
+
+        elif key == "ITEM_REMOVE":
+            if value and state.remove_item(value):
+                applied.append(f"- {value}")
+
+        elif key == "LOCATION":
+            if value:
+                state.location = value
+                applied.append(f"Moved to {value}")
+
+        elif key == "QUEST":
+            if value:
+                state.quest = value
+                applied.append("Quest updated")
+
+        elif key == "NPC":
+            npc = _parse_npc(value)
+            if npc:
+                state.upsert_npc(npc)
+                applied.append(f"Met {npc.name}")
+
+        elif key == "ENEMY":
+            enemy = _parse_enemy(value)
+            if enemy:
+                state.start_combat(enemy)
+                applied.append(f"Combat: {enemy.name}")
+
+        elif key == "ENEMY_HP":
+            n = _parse_int(value)
+            if n is not None and state.enemy:
+                state.enemy.hp = max(0, state.enemy.hp + n)
+                applied.append(f"{state.enemy.name} HP {n:+d}")
+                if not state.enemy.alive:
+                    applied.append(f"{state.enemy.name} defeated")
+                    state.end_combat()
+
+        elif key.startswith("ENEMY_DEFEATED"):
+            if state.enemy:
+                applied.append(f"{state.enemy.name} defeated")
+                state.end_combat()
+
+        elif key.startswith("GAME_OVER"):
+            state.game_over = True
+            applied.append("GAME OVER")
+
+    return applied
+
+
+def _parse_npc(value: str) -> NPC | None:
+    # format: Name|role|disposition|note  (later fields optional)
+    parts = [p.strip() for p in value.split("|")]
+    if not parts or not parts[0]:
+        return None
+    name = parts[0]
+    role = parts[1] if len(parts) > 1 else ""
+    disp = parts[2] if len(parts) > 2 else "neutral"
+    note = parts[3] if len(parts) > 3 else ""
+    return NPC(name=name, role=role, disposition=disp, note=note)
+
+
+def _parse_enemy(value: str) -> Enemy | None:
+    # format: Name|hp=12|atk=4
+    parts = [p.strip() for p in value.split("|")]
+    if not parts or not parts[0]:
+        return None
+    name = parts[0]
+    hp, atk = 10, 3
+    for p in parts[1:]:
+        m = re.search(r"(hp|atk|attack)\s*=\s*(\d+)", p, re.IGNORECASE)
+        if m:
+            if m.group(1).lower() == "hp":
+                hp = int(m.group(2))
+            else:
+                atk = int(m.group(2))
+    hp = max(1, min(hp, 200))
+    atk = max(0, min(atk, 50))
+    return Enemy(name=name, hp=hp, max_hp=hp, attack=atk)
+
+
+def run_turn(state: GameState, raw: str) -> TurnResult:
+    """Full pipeline: parse model text, apply changes, advance the turn counter."""
+    narrative, choices, state_lines = parse(raw)
+    applied = apply_state_changes(state, state_lines)
+    state.turn += 1
+    if applied:
+        state.log.append(f"Turn {state.turn}: " + "; ".join(applied))
+    return TurnResult(narrative=narrative, choices=choices, applied=applied, raw=raw)

engine/prompts.py

@@ -0,0 +1,82 @@
+"""System prompt and the tag protocol.
+
+The protocol is deliberately tiny and rigid. Small models follow a short, strict
+format far more reliably than a verbose one. Every turn the model must answer with
+exactly three blocks: <narrative>, <state>, <choices>. Anything outside them is
+discarded by the parser.
+"""
+
+SYSTEM_PROMPT = """\
+You are the engine of a dark-fantasy text RPG. You narrate a living world and run
+its rules. You are NOT a chatbot — never break character, never mention being an AI,
+never explain the rules to the player.
+
+THE GAME STATE (HP, gold, inventory, location) is tracked by the program, not by
+you. Before every turn you receive the current, authoritative state. You may only
+PROPOSE changes to it using the tag protocol below. The program validates and
+applies them. Never invent the player's HP or gold — read it from the state given.
+
+You MUST reply with EXACTLY these three blocks, in this order, and nothing else:
+
+<narrative>
+2-4 vivid sentences describing what happens as a result of the player's action.
+Second person, present tense. Be concrete and consistent with the state and the
+characters already introduced. Do not list choices here.
+</narrative>
+
+<state>
+One change per line, only when something actually changes. Allowed keys:
+  HP: -8            (damage; negative number)
+  HP: +5            (healing; positive number)
+  GOLD: +12         (or negative to spend)
+  XP: +6
+  ITEM_ADD: Iron Key
+  ITEM_REMOVE: Bread
+  LOCATION: The Sunken Crypt
+  QUEST: Find the three shards of the Moonglass
+  NPC: Borin|blacksmith|friendly|forged your blade
+        (name | role | friendly/neutral/hostile | one short memory)
+  ENEMY: Cave Goblin|hp=12|atk=4   (begins combat)
+  ENEMY_HP: -6                       (damage the current enemy)
+  ENEMY_DEFEATED                     (ends combat; give XP/loot separately)
+  GAME_OVER: death                   (only when the player truly dies)
+Leave this block empty (just the tags with nothing between) if nothing changed.
+</state>
+
+<choices>
+1. A short actionable option.
+2. A second, different option.
+3. A third option (may be risky, clever, or a question to an NPC).
+</choices>
+
+RULES:
+- Keep numbers small and fair. Early enemies have 8-15 HP and deal 2-6 damage.
+- If the player attacks an enemy, deal damage via ENEMY_HP and let the enemy hit
+  back via HP, unless they dodge.
+- Reward exploration and victories with small GOLD/XP and occasional items.
+- Stay consistent: reuse NPC names, remember the location, honor the inventory.
+- Never give the player items or gold they didn't earn just because they asked.
+"""
+
+# The very first turn: ask the model to open the adventure.
+OPENING_INSTRUCTION = (
+    "Begin the adventure. Set an evocative opening scene at the player's current "
+    "location, hint at the quest, and offer the first choices. Introduce at most "
+    "one NPC."
+)
+
+
+def build_turn_prompt(state_snapshot: str, player_action: str) -> str:
+    """The user-role message for a normal turn."""
+    return (
+        "=== CURRENT STATE (authoritative — trust these numbers) ===\n"
+        f"{state_snapshot}\n"
+        "=== PLAYER ACTION ===\n"
+        f"{player_action}\n"
+        "=== YOUR TURN ===\n"
+        "Respond with the three blocks <narrative>, <state>, <choices>."
+    )
+
+
+def build_opening_prompt(state_snapshot: str) -> str:
+    return build_turn_prompt(state_snapshot, OPENING_INSTRUCTION)

finetune/build_dataset.py

@@ -0,0 +1,376 @@
+"""Build the fine-tuning dataset for Micro RPG Engine.
+
+Strategy (the "Well-Tuned" bonus quest, done honestly):
+
+We synthesize RPG *turns* in the EXACT tag protocol the engine expects, then —
+the important part — we run every single generated turn through the real parser
+(`engine.parser`) against a matching `GameState`. A turn is written to the dataset
+ONLY if it parses cleanly and its <state> deltas apply without error. So 100% of
+the training data is guaranteed well-formed and mechanically valid.
+
+That's what teaches a 1B-4B model the thing that's actually hard: emitting the
+three-block format and consistent mechanics, every turn.
+
+No model and no network are needed to build the dataset — it's fully offline.
+
+Usage:
+    python -m finetune.build_dataset --n 800 --out finetune/data
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import random
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from engine.game_state import GameState, Enemy, NPC
+from engine import prompts, parser
+
+
+# --------------------------------------------------------------------------- #
+# variation pools
+# --------------------------------------------------------------------------- #
+LOCATIONS = [
+    "The Crossroads", "The Sunken Crypt", "Mossfall Village", "The Whispering Woods",
+    "An Abandoned Watchtower", "The Drowned Cellar", "A Ruined Chapel",
+    "The Ashen Market", "The Frostbitten Pass", "The Hollow King's Tomb",
+    "A Mushroom Cavern", "The Broken Bridge",
+]
+
+ENEMIES = [
+    ("Cave Goblin", 9, 14, 2, 5), ("Mist Wraith", 8, 12, 3, 6),
+    ("Giant Rat", 6, 10, 1, 4), ("Skeleton Warrior", 12, 18, 3, 7),
+    ("Bog Lurker", 14, 22, 2, 6), ("Bandit Scout", 10, 16, 3, 6),
+    ("Hungry Ghoul", 11, 17, 3, 7), ("Stone Gargoyle", 16, 24, 2, 5),
+]
+
+ITEMS = [
+    "Iron Shortsword", "Health Potion", "Torch", "Iron Key", "Silver Ring",
+    "Tattered Map", "Oak Shield", "Bundle of Arrows", "Moonglass Shard",
+    "Loaf of Bread", "Vial of Antidote", "Rusty Lantern",
+]
+
+NPCS = [
+    ("Borin", "blacksmith", "friendly", "forged your blade"),
+    ("Aldric", "old hermit", "neutral", "knows the old roads"),
+    ("Mara", "merchant", "neutral", "always after coin"),
+    ("Sister Wen", "healer", "friendly", "tends the wounded"),
+    ("Grimm", "gravekeeper", "neutral", "guards the crypt"),
+    ("Captain Voss", "guard captain", "hostile", "blames you for the fire"),
+]
+
+QUESTS = [
+    "Discover why the village of Mossfall fell silent.",
+    "Find the three shards of the Moonglass.",
+    "Escort the merchant safely through the pass.",
+    "Recover the Hollow King's stolen crown.",
+]
+
+
+# --------------------------------------------------------------------------- #
+# formatting + validation
+# --------------------------------------------------------------------------- #
+def fmt_response(narrative: str, state_lines: list[str], choices: list[str]) -> str:
+    state_body = "\n".join(state_lines)
+    choice_body = "\n".join(f"{i}. {c}" for i, c in enumerate(choices, 1))
+    return (
+        f"<narrative>\n{narrative}\n</narrative>\n"
+        f"<state>\n{state_body}\n</state>\n"
+        f"<choices>\n{choice_body}\n</choices>"
+    )
+
+
+def is_valid(state: GameState, response: str, expect_changes: bool) -> bool:
+    """Round-trip the crafted response through the real parser against a *copy*
+    of the state. Accept only if it parses into a narrative + 3 choices and its
+    deltas apply (changing something when changes were intended)."""
+    narrative, choices, state_lines = parser.parse(response)
+    if not narrative or len(choices) != 3:
+        return False
+    probe = GameState.from_dict(state.to_dict())  # deep-ish copy
+    applied = parser.apply_state_changes(probe, state_lines)
+    if expect_changes and not applied:
+        return False
+    return True
+
+
+# --------------------------------------------------------------------------- #
+# scene generators — each returns (state, action, response)
+# --------------------------------------------------------------------------- #
+def _base_state(rng: random.Random, **over) -> GameState:
+    s = GameState(
+        hp=rng.randint(8, 20), max_hp=20, gold=rng.randint(0, 30),
+        level=rng.randint(1, 3), location=rng.choice(LOCATIONS),
+        quest=rng.choice(QUESTS),
+        inventory=rng.sample(ITEMS, k=rng.randint(1, 3)),
+    )
+    for k, v in over.items():
+        setattr(s, k, v)
+    return s
+
+
+def scene_opening(rng):
+    s = _base_state(rng)
+    name, role, disp, note = rng.choice(NPCS)
+    narrative = rng.choice([
+        f"Cold rain needles the stones of {s.location}. A hooded figure watches you "
+        f"from beneath a dead tree, saying nothing.",
+        f"You arrive at {s.location} as the last light fails. Somewhere ahead, a bell "
+        f"tolls once and falls silent.",
+        f"The road ends at {s.location}. The air tastes of ash and old iron, and a "
+        f"lone lantern sways with no wind to move it.",
+    ])
+    lines = [f"NPC: {name}|{role}|{disp}|{note}"]
+    choices = [
+        f"Approach {name} and ask what happened here.",
+        "Search the area before anyone notices you.",
+        "Press on toward the heart of the ruins.",
+    ]
+    return s, prompts.OPENING_INSTRUCTION, fmt_response(narrative, lines, choices), True
+
+
+def scene_loot(rng):
+    s = _base_state(rng)
+    if rng.random() < 0.5:
+        gold = rng.randint(3, 15)
+        lines = [f"GOLD: +{gold}"]
+        narrative = f"You pry open a rotted strongbox. {gold} tarnished coins spill into your palm."
+    else:
+        item = rng.choice(ITEMS)
+        lines = [f"ITEM_ADD: {item}"]
+        narrative = f"Half-buried in the muck you find a {item}, still serviceable."
+    action = rng.choice(["I search the room", "look under the rubble", "I rummage through the chest"])
+    choices = ["Pocket it and move on.", "Keep searching for more.", "Listen for danger first."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_combat_start(rng):
+    s = _base_state(rng)
+    name, lo, hi, alo, ahi = rng.choice(ENEMIES)
+    hp = rng.randint(lo, hi)
+    atk = rng.randint(alo, ahi)
+    lines = [f"ENEMY: {name}|hp={hp}|atk={atk}"]
+    narrative = rng.choice([
+        f"A {name} lunges from the shadows, teeth bared. There is no time to talk.",
+        f"The dark coalesces into a {name}. It blocks the only way forward.",
+        f"Gravel shifts — a {name} rises, weapon raised, eyes fixed on you.",
+    ])
+    action = rng.choice(["I approach the shadowy figure", "go through the doorway", "I light my torch and step forward"])
+    choices = ["Strike first with your weapon.", "Raise your guard and wait.", "Try to slip past it."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_combat_attack(rng):
+    name, lo, hi, alo, ahi = rng.choice(ENEMIES)
+    ehp = rng.randint(6, hi)
+    atk = rng.randint(alo, ahi)
+    s = _base_state(rng, hp=rng.randint(10, 20), enemy=Enemy(name, ehp, ehp, atk))
+    dmg = rng.randint(4, 8)
+    took = rng.randint(2, max(2, atk))
+    xp = rng.randint(2, 5)
+    lines = [f"ENEMY_HP: -{dmg}", f"HP: -{took}", f"XP: +{xp}"]
+    narrative = rng.choice([
+        f"Your blade bites deep; the {name} shrieks and rakes you in return.",
+        f"You land a solid blow, but the {name} answers with a glancing strike.",
+        f"Steel meets flesh. The {name} staggers, then claws back at you.",
+    ])
+    action = rng.choice([f"I attack the {name}", "swing my sword", "I strike at it"])
+    choices = ["Press the attack.", "Fall back and guard.", "Attempt to flee."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_killing_blow(rng):
+    name, lo, hi, alo, ahi = rng.choice(ENEMIES)
+    ehp = rng.randint(3, 7)
+    s = _base_state(rng, hp=rng.randint(8, 20), enemy=Enemy(name, ehp, ehp + 6, rng.randint(alo, ahi)))
+    xp = rng.randint(5, 10)
+    lines = [f"ENEMY_HP: -{ehp + rng.randint(1,4)}", f"XP: +{xp}"]
+    if rng.random() < 0.5:
+        lines.append(f"GOLD: +{rng.randint(4, 18)}")
+    else:
+        lines.append(f"ITEM_ADD: {rng.choice(ITEMS)}")
+    narrative = rng.choice([
+        f"With a final thrust the {name} crumples and goes still. Silence returns.",
+        f"You break through its guard — the {name} falls and does not rise.",
+        f"The {name} reels and collapses at your feet, defeated.",
+    ])
+    action = rng.choice([f"I finish off the {name}", "deliver the killing blow", "I strike again"])
+    choices = ["Search the body.", "Catch your breath.", "Move deeper inside."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_flee(rng):
+    name = rng.choice(ENEMIES)[0]
+    ehp = rng.randint(8, 16)
+    s = _base_state(rng, enemy=Enemy(name, ehp, ehp, 4))
+    dest = rng.choice(LOCATIONS)
+    took = rng.randint(0, 4)
+    lines = [f"LOCATION: {dest}"]
+    if took:
+        lines.append(f"HP: -{took}")
+    narrative = (
+        f"You break away and run. The {name} gives chase but loses you in the dark, "
+        f"and you stumble out into {dest}."
+    )
+    action = rng.choice(["I flee", "run away", "I try to escape"])
+    choices = ["Catch your breath.", "Keep moving.", "Look for another path."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_npc_talk(rng):
+    name, role, disp, note = rng.choice(NPCS)
+    s = _base_state(rng)
+    s.upsert_npc(NPC(name, role, disp, note))
+    if rng.random() < 0.5:
+        quest = rng.choice(QUESTS)
+        lines = [f"QUEST: {quest}"]
+        narrative = (
+            f'"{name} leans close. \"If you seek answers,\" the {role} mutters, '
+            f'\"then there is something you must do.\" The path ahead grows clearer.'
+        )
+    else:
+        lines = []  # pure dialogue, no mechanics — important to teach empty <state>
+        narrative = (
+            f'{name} the {role} studies you a long moment. "Mind yourself out there," '
+            f'they say. "The dead don\'t stay buried in these parts."'
+        )
+    action = rng.choice([f"I ask {name} about the village", f"talk to {name}", f"question the {role}"])
+    choices = [f"Ask {name} for help.", "Thank them and leave.", "Press for more details."]
+    expect = bool(lines)
+    return s, action, fmt_response(narrative, lines, choices), expect
+
+
+def scene_shop(rng):
+    s = _base_state(rng, gold=rng.randint(15, 40), location="The Ashen Market")
+    item = rng.choice(["Health Potion", "Oak Shield", "Bundle of Arrows", "Vial of Antidote"])
+    cost = rng.randint(5, 14)
+    lines = [f"GOLD: -{cost}", f"ITEM_ADD: {item}"]
+    narrative = (
+        f"The merchant weighs your coins, then slides a {item} across the stall. "
+        f'"Pleasure doing business," she says without smiling.'
+    )
+    action = rng.choice([f"I buy a {item}", f"purchase the {item}", "I pay for the item"])
+    choices = ["Browse the other wares.", "Haggle over the price.", "Leave the market."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_use_potion(rng):
+    s = _base_state(rng, hp=rng.randint(4, 12), inventory=["Health Potion", rng.choice(ITEMS)])
+    heal = rng.randint(6, 12)
+    lines = [f"ITEM_REMOVE: Health Potion", f"HP: +{heal}"]
+    narrative = (
+        f"You uncork the Health Potion and drink. Warmth floods your limbs as wounds "
+        f"knit closed."
+    )
+    action = rng.choice(["I drink the health potion", "use my potion", "I quaff the potion"])
+    choices = ["Continue on.", "Rest a moment longer.", "Check your surroundings."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_move(rng):
+    s = _base_state(rng)
+    dest = rng.choice([l for l in LOCATIONS if l != s.location])
+    lines = [f"LOCATION: {dest}"]
+    narrative = rng.choice([
+        f"You follow the winding path until the trees give way to {dest}.",
+        f"After a long walk the way opens onto {dest}, quiet and watchful.",
+    ])
+    action = rng.choice(["I head north", "go east through the trees", "I take the stone stairs down"])
+    choices = ["Explore the area.", "Stay alert for danger.", "Call out to see who answers."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_trap(rng):
+    s = _base_state(rng, hp=rng.randint(10, 20))
+    dmg = rng.randint(2, 6)
+    lines = [f"HP: -{dmg}"]
+    narrative = rng.choice([
+        "The floor gives way to a hidden spike pit. You twist aside but a barb tears your leg.",
+        "A dart hisses from the wall and buries itself in your shoulder before you can move.",
+    ])
+    action = rng.choice(["I open the chest", "step onto the tiles", "I pull the lever"])
+    choices = ["Bind the wound.", "Search for more traps.", "Press on, ignoring the pain."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+def scene_death(rng):
+    name = rng.choice(ENEMIES)[0]
+    s = _base_state(rng, hp=rng.randint(2, 5), enemy=Enemy(name, 10, 10, 6))
+    lines = ["HP: -12", "GAME_OVER: death"]
+    narrative = (
+        f"The {name} is faster. Its blow lands true and the world tips sideways into "
+        f"cold and dark. Your story ends here."
+    )
+    action = rng.choice(["I charge recklessly", "I attack with everything I have", "stand and fight"])
+    choices = ["Begin a new tale.", "Reflect on your journey.", "Rest at last."]
+    return s, action, fmt_response(narrative, lines, choices), True
+
+
+GENERATORS = [
+    scene_opening, scene_loot, scene_combat_start, scene_combat_attack,
+    scene_killing_blow, scene_flee, scene_npc_talk, scene_shop,
+    scene_use_potion, scene_move, scene_trap, scene_death,
+]
+
+
+# --------------------------------------------------------------------------- #
+# build
+# --------------------------------------------------------------------------- #
+def build(n: int, seed: int = 13):
+    rng = random.Random(seed)
+    examples = []
+    attempts = 0
+    rejected = 0
+    while len(examples) < n and attempts < n * 20:
+        attempts += 1
+        gen = rng.choice(GENERATORS)
+        state, action, response, expect_changes = gen(rng)
+        if not is_valid(state, response, expect_changes):
+            rejected += 1
+            continue
+        user = prompts.build_turn_prompt(state.context_snapshot(), action)
+        examples.append({
+            "messages": [
+                {"role": "system", "content": prompts.SYSTEM_PROMPT},
+                {"role": "user", "content": user},
+                {"role": "assistant", "content": response},
+            ]
+        })
+    return examples, rejected
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=800, help="number of training examples")
+    ap.add_argument("--eval-frac", type=float, default=0.05)
+    ap.add_argument("--out", default=os.path.join(os.path.dirname(__file__), "data"))
+    ap.add_argument("--seed", type=int, default=13)
+    args = ap.parse_args()
+
+    examples, rejected = build(args.n, args.seed)
+    random.Random(args.seed).shuffle(examples)
+
+    n_eval = max(1, int(len(examples) * args.eval_frac))
+    eval_set, train_set = examples[:n_eval], examples[n_eval:]
+
+    os.makedirs(args.out, exist_ok=True)
+    train_path = os.path.join(args.out, "train.jsonl")
+    eval_path = os.path.join(args.out, "eval.jsonl")
+    for path, data in ((train_path, train_set), (eval_path, eval_set)):
+        with open(path, "w", encoding="utf-8") as f:
+            for ex in data:
+                f.write(json.dumps(ex, ensure_ascii=False) + "\n")
+
+    print(f"Generated {len(examples)} validated turns "
+          f"({rejected} rejected by the parser during generation).")
+    print(f"  train: {len(train_set)} -> {train_path}")
+    print(f"  eval : {len(eval_set)} -> {eval_path}")
+    print("Every example is guaranteed to parse and apply cleanly.")
+
+
+if __name__ == "__main__":
+    main()

finetune/train.py

@@ -0,0 +1,150 @@
+"""LoRA supervised fine-tuning for Micro RPG Engine.
+
+Teaches a small base model (1B-4B) to reliably emit the three-block tag protocol
+with valid mechanics, using the parser-validated dataset from build_dataset.py.
+
+We use LoRA (PEFT) so it trains on a single consumer/Colab GPU and produces a tiny
+adapter (a few MB). Point the engine at it with MICRORPG_ADAPTER to play with your
+fine-tuned model.
+
+Quickstart
+----------
+    pip install -r requirements-train.txt
+    python -m finetune.build_dataset --n 1200
+    python -m finetune.train \
+        --model Qwen/Qwen3-4B-Instruct-2507 \
+        --out finetune/out/qwen3-4b-microrpg
+
+Then play with it:
+    # PowerShell
+    $env:MICRORPG_ADAPTER = "finetune/out/qwen3-4b-microrpg"
+    python app.py
+
+Notes
+-----
+* `--model` accepts any chat model with a chat template (Qwen3-4B, MiniCPM, a Llama
+  for the "Llama Champion" quest, etc.). Swap freely — the dataset is model-agnostic.
+* For a 4B model on a small GPU, add `--load-4bit` (needs bitsandbytes).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--model", default=os.environ.get("MICRORPG_MODEL", "Qwen/Qwen3-4B-Instruct-2507"))
+    ap.add_argument("--train", default="finetune/data/train.jsonl")
+    ap.add_argument("--eval", default="finetune/data/eval.jsonl")
+    ap.add_argument("--out", default="finetune/out/microrpg-adapter")
+    ap.add_argument("--epochs", type=float, default=3.0)
+    ap.add_argument("--lr", type=float, default=2e-4)
+    ap.add_argument("--batch", type=int, default=2)
+    ap.add_argument("--grad-accum", type=int, default=8)
+    ap.add_argument("--max-len", type=int, default=1536)
+    ap.add_argument("--lora-r", type=int, default=16)
+    ap.add_argument("--lora-alpha", type=int, default=32)
+    ap.add_argument("--load-4bit", action="store_true", help="QLoRA via bitsandbytes")
+    ap.add_argument("--merge", action="store_true",
+                    help="after training, merge the adapter into the base and save full weights")
+    args = ap.parse_args()
+
+    # Heavy imports kept inside main so `--help` and import-checks stay light.
+    import torch
+    from datasets import load_dataset
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+    from peft import LoraConfig
+    from trl import SFTConfig, SFTTrainer
+
+    print(f"Base model : {args.model}")
+    print(f"Train file : {args.train}")
+
+    tokenizer = AutoTokenizer.from_pretrained(args.model)
+    if tokenizer.pad_token is None:
+        tokenizer.pad_token = tokenizer.eos_token
+
+    model_kwargs = {"torch_dtype": torch.bfloat16 if torch.cuda.is_available() else torch.float32}
+    if args.load_4bit:
+        from transformers import BitsAndBytesConfig
+        model_kwargs["quantization_config"] = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.bfloat16,
+            bnb_4bit_use_double_quant=True,
+        )
+    if torch.cuda.is_available():
+        model_kwargs["device_map"] = "auto"
+
+    model = AutoModelForCausalLM.from_pretrained(args.model, **model_kwargs)
+
+    # LoRA adapter on attention + MLP projections — the standard, portable target set.
+    peft_config = LoraConfig(
+        r=args.lora_r,
+        lora_alpha=args.lora_alpha,
+        lora_dropout=0.05,
+        bias="none",
+        task_type="CAUSAL_LM",
+        target_modules=[
+            "q_proj", "k_proj", "v_proj", "o_proj",
+            "gate_proj", "up_proj", "down_proj",
+        ],
+    )
+
+    data_files = {"train": args.train}
+    if os.path.exists(args.eval):
+        data_files["eval"] = args.eval
+    ds = load_dataset("json", data_files=data_files)
+
+    sft_config = SFTConfig(
+        output_dir=args.out,
+        num_train_epochs=args.epochs,
+        per_device_train_batch_size=args.batch,
+        gradient_accumulation_steps=args.grad_accum,
+        learning_rate=args.lr,
+        lr_scheduler_type="cosine",
+        warmup_ratio=0.05,
+        logging_steps=10,
+        save_strategy="epoch",
+        eval_strategy="epoch" if "eval" in ds else "no",
+        bf16=torch.cuda.is_available(),
+        gradient_checkpointing=True,
+        max_seq_length=args.max_len,
+        packing=False,
+        report_to="none",
+        # The dataset has a "messages" column → TRL applies the chat template and,
+        # by default, masks the prompt so loss is computed only on the assistant turn.
+        assistant_only_loss=True,
+    )
+
+    trainer = SFTTrainer(
+        model=model,
+        args=sft_config,
+        train_dataset=ds["train"],
+        eval_dataset=ds.get("eval"),
+        peft_config=peft_config,
+        processing_class=tokenizer,
+    )
+
+    trainer.train()
+    trainer.save_model(args.out)
+    tokenizer.save_pretrained(args.out)
+    print(f"\nAdapter saved to: {args.out}")
+
+    if args.merge:
+        print("Merging adapter into base weights...")
+        merged_dir = args.out.rstrip("/\\") + "-merged"
+        merged = trainer.model.merge_and_unload()
+        merged.save_pretrained(merged_dir)
+        tokenizer.save_pretrained(merged_dir)
+        print(f"Merged model saved to: {merged_dir}")
+
+    print("\nPlay with it:  set MICRORPG_ADAPTER to the output dir, then run app.py")
+
+
+if __name__ == "__main__":
+    main()

requirements-train.txt

@@ -0,0 +1,10 @@
+# Fine-tuning deps (NOT needed to run the app / Space — only to train an adapter).
+# Install on a GPU machine or Colab:  pip install -r requirements-train.txt
+torch>=2.2.0
+transformers>=4.46.0
+datasets>=3.0.0
+trl>=0.12.0
+peft>=0.13.0
+accelerate>=0.34.0
+# Optional, only for --load-4bit (QLoRA):
+bitsandbytes>=0.44.0 ; platform_system != "Windows"

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=5.9,<6
+huggingface_hub>=0.25.0
+transformers>=4.44.0
+torch>=2.2.0
+accelerate>=0.33.0

style.css

@@ -0,0 +1,100 @@
+/* Micro RPG Engine — parchment / arcane theme */
+
+:root {
+  --parchment: #f4ecd8;
+  --ink: #2b2118;
+  --blood: #7c2d2d;
+  --gold: #b8860b;
+  --arcane: #4b3b6b;
+}
+
+.gradio-container {
+  background:
+    radial-gradient(circle at 20% 10%, #1a1320 0%, #0d0a12 60%),
+    #0d0a12 !important;
+  font-family: "Georgia", "Iowan Old Style", serif !important;
+  max-width: 1100px !important;
+  margin: auto !important;
+}
+
+#title-md h1 {
+  text-align: center;
+  color: var(--gold);
+  letter-spacing: 1px;
+  text-shadow: 0 0 18px rgba(184, 134, 11, 0.35);
+  margin-bottom: 0;
+}
+#title-md p {
+  text-align: center;
+  color: #b9a98c;
+  font-style: italic;
+  margin-top: 4px;
+}
+
+/* The story panel — looks like aged parchment */
+#story {
+  background: linear-gradient(180deg, #f7f0dd 0%, #ece0c2 100%) !important;
+  color: var(--ink) !important;
+  border: 1px solid #6b5836 !important;
+  border-radius: 10px !important;
+  box-shadow: 0 0 30px rgba(0, 0, 0, 0.6), inset 0 0 60px rgba(120, 90, 40, 0.15);
+  min-height: 360px;
+  padding: 22px 26px !important;
+  font-size: 1.08rem;
+  line-height: 1.65;
+}
+/* Force the dark ink onto every text node Gradio nests inside the panel —
+   otherwise the theme's light --body-text-color wins on <p>/<span>/<li>. */
+#story,
+#story p,
+#story li,
+#story span,
+#story strong,
+#story em,
+#story a {
+  color: var(--ink) !important;
+}
+#story h3 { color: var(--blood) !important; margin-top: 0; }
+/* The changelog lines (rendered as blockquotes) — readable brown on parchment */
+#story blockquote {
+  color: #5c4326 !important;
+  border-left: 3px solid var(--gold) !important;
+  background: rgba(120, 90, 40, 0.08);
+  font-style: italic;
+}
+#story blockquote * { color: #5c4326 !important; }
+
+/* Stats sidebar */
+#stats {
+  background: rgba(30, 22, 40, 0.85) !important;
+  border: 1px solid var(--arcane) !important;
+  border-radius: 10px !important;
+  color: #e8dfc8 !important;
+  padding: 16px 18px !important;
+  font-size: 0.98rem;
+}
+#stats .hpbar {
+  height: 14px; border-radius: 7px; background: #311; overflow: hidden;
+  border: 1px solid #511;
+}
+#stats .hpfill {
+  height: 100%; background: linear-gradient(90deg, #7c2d2d, #c0392b);
+}
+
+/* Buttons */
+button.primary, .gr-button-primary {
+  background: linear-gradient(180deg, #5a4630, #3a2c1c) !important;
+  border: 1px solid var(--gold) !important;
+  color: var(--parchment) !important;
+}
+button.primary:hover { box-shadow: 0 0 14px rgba(184,134,11,0.5) !important; }
+
+/* Input box */
+#action-input textarea {
+  background: #1c1626 !important;
+  color: #efe6cf !important;
+  border: 1px solid #4b3b6b !important;
+  font-family: "Georgia", serif !important;
+}
+
+footer { visibility: hidden; }

tests/test_parser.py

@@ -0,0 +1,103 @@
+"""Parser + engine smoke tests. Run with: python -m tests.test_parser
+
+These use the mock backend, so no model weights or network are required."""
+
+import sys
+import os
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from engine.game_state import GameState, Enemy
+from engine import parser
+from engine.engine import GameEngine
+from engine.llm import build_backend
+
+
+def check(name, cond):
+    status = "ok  " if cond else "FAIL"
+    print(f"[{status}] {name}")
+    if not cond:
+        raise AssertionError(name)
+
+
+def test_parse_blocks():
+    raw = (
+        "<narrative>You enter a dim hall.</narrative>"
+        "<state>\nHP: -5\nGOLD: +10\nITEM_ADD: Torch\nLOCATION: Dim Hall\n</state>"
+        "<choices>\n1. Go north.\n2. Light the torch.\n</choices>"
+    )
+    narrative, choices, lines = parser.parse(raw)
+    check("narrative extracted", narrative == "You enter a dim hall.")
+    check("choices extracted", choices == ["Go north.", "Light the torch."])
+    check("state lines count", len(lines) == 4)
+
+
+def test_apply_changes_clamped():
+    state = GameState(hp=20, max_hp=20, gold=10)
+    parser.apply_state_changes(state, ["HP: -5", "GOLD: +10", "ITEM_ADD: Torch"])
+    check("hp reduced", state.hp == 15)
+    check("gold added", state.gold == 20)
+    check("item added", state.has_item("Torch"))
+
+    # over-heal is clamped to max_hp
+    parser.apply_state_changes(state, ["HP: +999"])
+    check("heal clamped to max", state.hp == 20)
+
+    # can't go below zero gold
+    parser.apply_state_changes(state, ["GOLD: -9999"])
+    check("gold floored at 0", state.gold == 0)
+
+
+def test_death():
+    state = GameState(hp=5)
+    parser.apply_state_changes(state, ["HP: -50"])
+    check("hp floored at 0", state.hp == 0)
+    check("game over on death", state.game_over)
+
+
+def test_combat_flow():
+    state = GameState()
+    parser.apply_state_changes(state, ["ENEMY: Goblin|hp=10|atk=4"])
+    check("combat started", state.enemy is not None and state.enemy.name == "Goblin")
+    parser.apply_state_changes(state, ["ENEMY_HP: -6"])
+    check("enemy damaged", state.enemy.hp == 4)
+    parser.apply_state_changes(state, ["ENEMY_HP: -10"])
+    check("combat ended on death", state.enemy is None)
+
+
+def test_leveling():
+    state = GameState(level=1, xp=0, max_hp=20)
+    parser.apply_state_changes(state, ["XP: +10"])
+    check("leveled up", state.level == 2)
+    check("max hp grew", state.max_hp == 25)
+
+
+def test_unparseable_ignored():
+    state = GameState(hp=20)
+    before = state.to_dict()
+    parser.apply_state_changes(state, ["HP: lots", "WUT: 5", "random gibberish"])
+    check("garbage ignored", state.to_dict() == before)
+
+
+def test_full_engine_mock():
+    engine = GameEngine(build_backend("mock"))
+    opening = engine.start()
+    check("opening has narrative", len(opening.narrative) > 0)
+    check("opening has choices", len(opening.choices) == 3)
+
+    # force a combat then attack
+    engine.state.start_combat(Enemy("Wraith", hp=10, max_hp=10, attack=3))
+    res = engine.act("I attack the wraith with my dagger")
+    check("attack damaged enemy or ended combat",
+          engine.state.enemy is None or engine.state.enemy.hp < 10)
+
+
+def main():
+    tests = [v for k, v in sorted(globals().items()) if k.startswith("test_")]
+    for t in tests:
+        t()
+    print(f"\nAll {len(tests)} test groups passed.")
+
+
+if __name__ == "__main__":
+    main()