naderu-loom-7b/README.md

---
license: apache-2.0
base_model: mistralai/Mistral-7B-Instruct-v0.3
library_name: transformers
pipeline_tag: text-generation
language:
  - en
tags:
  - interactive-fiction
  - game-master
  - json
  - structured-output
  - lora
  - qlora
  - mistral
  - naderu
---

# naderu-loom-7b

**An offline interactive-fiction narrator by [Naderu](https://naderu.com) — a BytesBrains Pte. Ltd. venture.**

`naderu-loom` is a compact, specialised **game-master** model. Given a game **state** and the
player's **action**, it narrates the next scene and returns a single **JSON turn** an app can
render and apply — built to run **offline on-device**. It is an honest portfolio/demonstration
piece: a small creative model with a **quantitative evaluation gate**, not a reasoning engine.

## Provenance

- **Fine-tuned from:** [`mistralai/Mistral-7B-Instruct-v0.3`](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.3) (Apache-2.0).
- **Method:** LoRA (r=16, α=32) trained as **QLoRA on the 4-bit MLX quant** of the base
  ([`mlx-community/Mistral-7B-Instruct-v0.3-4bit`](https://huggingface.co/mlx-community/Mistral-7B-Instruct-v0.3-4bit)),
  LoRA on 16 layers, lr 3e-5, 1000 iters, assistant-tokens-only (`--mask-prompt`), seq 1024.
  Trained with **MLX** on an Apple M4 Mac Mini (24 GB, no GPU); ~6.5 GB peak, final val loss 0.23.
  These weights are the adapter **fused and de-quantized to bf16** for portability.
- **Training data:** ~320 Naderu-authored `(state, action) → JSON turn` examples across five
  genres (fantasy, mystery, sci-fi, horror, fairytale). License-clean and reproducible.
- **License:** Apache-2.0 (inherits the base model's terms).

## The turn contract

**Mistral-7B-v0.3 has no `system` role**, so the contract is folded into the user message. Each
turn the model receives `STATE` (genre, tone, hp, inventory, flags) + an `ACTION`, and replies
with exactly one JSON object:

```json
{
  "scene": "2–4 sentences of narration.",
  "choices": ["2 to 4 short action strings"],
  "state_delta": {"inventory_add": ["rusty key"], "inventory_remove": [], "flags_set": {"door_unlocked": true}, "hp": 0}
}
```

Rules: JSON only; 2–4 choices; never remove/use an item the player does not hold; flags stay
consistent with the story; honor genre and tone. The app applies `state_delta` and renders
`choices` as buttons.

## How to use

```python
import json
from transformers import AutoModelForCausalLM, AutoTokenizer

SYSTEM = (
    "You are naderu-loom, an offline interactive-fiction narrator (a game master) by "
    "Naderu (naderu.com). Each turn you receive the game STATE and the player's ACTION, "
    "and you reply with exactly one JSON object and nothing else, matching this schema: "
    '{"scene": <2-4 sentence narration>, "choices": [<2 to 4 short action strings>], '
    '"state_delta": {"inventory_add": [..], "inventory_remove": [..], '
    '"flags_set": {..}, "hp": <integer change, 0 if none>}}. '
    "Rules: reply with JSON only; never remove or use an item the player does not have; "
    "keep flags consistent with the story so far; honor the genre and tone; keep choices "
    "between 2 and 4."
)

mid = "bytesbrains/naderu-loom-7b"
tok = AutoTokenizer.from_pretrained(mid)
model = AutoModelForCausalLM.from_pretrained(mid)

state = {"genre": "fantasy", "tone": "grim", "hp": 10, "inventory": [], "flags": {}}
user = f"{SYSTEM}\n\nSTATE: {json.dumps(state)}\nACTION: __start__"   # no system role — fold it in
enc = tok.apply_chat_template([{"role": "user", "content": user}],
                              add_generation_prompt=True, return_tensors="pt")
out = model.generate(enc, max_new_tokens=256, do_sample=False)
print(tok.decode(out[0, enc.shape[1]:], skip_special_tokens=True))
```

Tip: clamp the returned `choices` list to ≤ 4 as a thin output-validation layer (see the eval note).

## Evaluation

**Suite:** `eval/suites/naderu-loom/run_eval.py` (v1, greedy) · **Run:** 2026-07-15
(34 turns / 9 scripted playthroughs, 5 genres) · **Result: PASS**

| Metric | Gate | Result |
|--------|------|--------|
| valid_json_rate | ≥ 0.98 | **1.000** ✅ |
| schema_rate | ≥ 0.95 | **0.971** ✅ (33/34) |
| state_violations | 0 | **0** ✅ |
| constraint_rate | ≥ 0.98 | **1.000** ✅ |

Honest note: **1 of 34 turns emitted 5 choices** (over the 2–4 bound), reflected in
`schema_rate` (0.971), which still clears its 0.95 bar. Clamp choices to ≤ 4 in the app.
World-state tracking holds — the model correctly refuses to use an item it doesn't hold
(0 state violations). Narrative quality is coherent and on-tone across genres but is
**reported, not gated** (subjective).

## Limitations & risks

- 7B → limited long-horizon reasoning; **the app is the source of truth for state** (the model
  proposes `state_delta`, the app applies and validates it).
- Fiction may be clichéd, repetitive, or tonally off; English-first.
- Trained via 4-bit QLoRA, so it carries the base's 4-bit quantization characteristics.
- Model-generated fiction — add content controls for a general audience.

## About Naderu

[**Naderu**](https://naderu.com) is an AI-models company (a BytesBrains Pte. Ltd. venture). We
**train** foundation models into specialised ones, **release** them with model cards, provenance,
and clear licensing, and **serve** the engineering around them. Every capability claim is backed
by a real evaluation — never vibes. Recipe, dataset, and eval gate are open in the Naderu repo.

- 🌐 [naderu.com](https://naderu.com) · 🧱 Base [`Mistral-7B-Instruct-v0.3`](https://huggingface.co/mistralai/Mistral-7B-Instruct-v0.3) (Apache-2.0) · 🏷️ v0.1.0 (2026-07-15)