devPirate01/SkyrimLLMBridge-Gemma-2B

Skyrim LLM Bridge — Fine-Tuned Gemma 2B (Q4_K_M)

This is an instruction-tuned, QLoRA fine-tuned version of Google's Gemma 2B language model, trained specifically for the Deterministic LLM Dialogue Bridge Skyrim mod as part of an MSc in Artificial Intelligence dissertation at Cardiff University.

The model is trained to output deterministic, structured JSON payloads corresponding to character persona constraints, epistemic ground truth, and quest stage transitions, solving the "unbounded hallucination" problem in LLM-driven video game NPCs.

---

🔬 Empirical Benchmark Results (vs Base Models)

Evaluated across 1,500 trials (5 random seeds, 100 test scenarios) on an AMD Radeon RX 6900 XT (ROCm backend):

Metric	Base Gemma 2B	Base Command R+ (26B)	Fine-Tuned Gemma 2B (This Model)
Rule & Routing Accuracy	19.0% (±1.76%)	29.0% (±3.17%)	53.4% (±3.24%)
Median Latency	0.92s	2.43s	0.98s
Mean Latency	0.95s	2.50s	1.91s
P95 Latency	1.15s	3.10s	1.25s
Throughput (Tokens/s)	38.5 TPS	14.1 TPS	36.2 TPS
Peak VRAM Usage	5.5 GB	15.6 GB	7.1 GB
Epistemic Leakage Rate	5/500 (1.0%)	0/500 (0.0%)	5/500 (1.0%)

Statistical significance: Fine-tuned 2B vs Base 2B: t = 14.08, p < 0.001; Fine-tuned 2B vs Base 26B: t = 9.81, p < 0.001.

---

🧠 Training Context & Skyrim Interaction Dynamics

This model was adapted via QLoRA (Rank 16, Alpha 16) specifically on conversational interactions in The Elder Scrolls V: Skyrim. Rather than functioning as an unconstrained chatbot, the model was trained on thousands of multi-turn dialogues reflecting the realities of gaming environments:

• Handling Hostile & Nonsensical Prompts: Reacts with in-character clarification or de-escalation rather than breaking persona or emitting hallucinated apologies.
• Epistemic Isolation: Strictly respects what the character knows versus what remains unrevealed, preventing premature quest spoiler leaks.
• Deterministic Policy Routing: Explicitly maps narrative intent to defined game-engine policies (witness_reveal_c1, witness_deny_map_knowledge, etc.).

---

📐 Trained JSON Schema Contract (For Developers & Other Games)

Developers and modders can use this exact model for other Skyrim NPCs or even other game engines (Unreal, Unity, Fallout 4, Starfield) by following this ChatML JSON specification:

1. System Prompt Template

Control <CHARACTER_NAME>. Return exactly one valid JSON object and nothing else.

PROFILE
<Character background, personality, and epistemic boundaries>

OUTPUT
Use exactly these keys in this order: schema_version, dialogue, player_intent, topic, policy_id, response_type, clue_claims, action_request.
Use double quotes. No Markdown, code fences, or extra keys. schema_version must be "1.0".

VOCAB
Intents: greet, social_chat, request_quest_guidance, offer_information, unclear, ask_for_repetition, ask_for_information, ask_for_clarification
Topics: none, witness, victim, drink, argument, unrelated, map, poison, quest_progress, suspect, personal

POLICIES
<narrative_policy_id> -> <response_type>

RULES
<Specific character knowledge and gating rules>

2. User Input Turn (Game Engine Context)

{
  "schema_version": "1.0",
  "request_id": "req_042",
  "session": {
    "session_id": "session_gameplay_01",
    "experimental_group": "gameplay"
  },
  "quest": {
    "quest_id": "poisoned_mead",
    "quest_stage": 10,
    "known_clues": ["C1"]
  },
  "npc": {
    "npc_id": "tavern_witness",
    "location": "The Bannered Mare"
  },
  "player": {
    "message": "Remind me what you smelled on Vigund's cup."
  }
}

3. Model Output Turn (Deterministic State Proposal)

{
  "schema_version": "1.0",
  "dialogue": "I handled Vigund's mead. His cup carried the bitter scent of Nightshade.",
  "player_intent": "ask_for_repetition",
  "topic": "drink",
  "policy_id": "witness_repeat_c1",
  "response_type": "repeat_known_information",
  "clue_claims": ["C1"],
  "action_request": null
}

Key Field Descriptions:

• dialogue: The exact spoken line to be voiced or displayed by the game engine.
• player_intent: Semantic classification of the player's utterance (ask_for_information, threaten, greet, etc.).
• policy_id: The authoritative game state policy triggered by this turn.
• clue_claims: List of quest clues revealed during this turn (e.g. ["C1"]). The external Python validator ensures the player has met prerequisites before granting the clue.
• action_request: Can be set to game actions (e.g. attack, flee, trade, or null).

---

🛠️ How to Adapt This Model to Your Own Game / Mod

1. Keep the JSON output keys identical: The model's weights are fine-tuned to emit schema_version, dialogue, player_intent, topic, policy_id, response_type, clue_claims, action_request.
2. Provide your game state in the user prompt: Supply your quest ID, stage, known clues, and the player's message in the User turn.
3. Validate in Python/C++: Use a lightweight validator to verify the emitted JSON before committing state changes to your game engine.

---

🚀 Unified Setup Guide (Part 2 of 3)

This model serves as the AI core for the Skyrim LLM Bridge.

Step 1: Get the Skyrim Mod

Download and install the game plugin via Nexus Mods.

Step 2: Run This Model in KoboldCpp

1. Download gemma-4-e2b-it.Q4_K_M.gguf from the Files and versions tab above (~3.2 GB).
2. Download KoboldCpp.
3. In KoboldCpp GUI:
   • Model: Select gemma-4-e2b-it.Q4_K_M.gguf
   • Context Size: 4096
   • GPU Layers: 33 (or -1 for all layers on GPUs with 8GB+ VRAM; 0 for CPU)
   • Port: 5001
   • Host: 127.0.0.1
4. Click Launch. KoboldCpp will expose an OpenAI-compatible API at http://127.0.0.1:5001/v1.

Step 3: Run the Python Bridge Server

1. Download SkyrimLLMBridge_Server_v1.0.zip from the GitHub Releases.
2. Extract the ZIP, install dependencies via pip install -r requirements.txt.
3. In .env, ensure:

   LLM_PROVIDER=koboldcpp
   KOBOLDCPP_URL=http://127.0.0.1:5001/v1
   KOBOLDCPP_MODEL=koboldcpp
   SKYRIM_DATA_DIR=C:\Program Files (x86)\Steam\steamapps\common\Skyrim Special Edition\Data\SKSE\Plugins\StorageUtilData\CompanionLLM
   

4. Run python bridge.py and launch Skyrim with SKSE!