README.md

---
language:
- de
license: apache-2.0
base_model: Qwen/Qwen3-1.7B
base_model_relation: finetune
pipeline_tag: text-generation
tags:
- qwen3
- gguf
- qlora
- minecraft
- npc
- dialogue
- german
- living-villages
- villagemind
---

# VillageMind 0.1-dev

**VillageMind** is a compact local language model fine-tuned for natural NPC dialogue in the **Living Villages** Minecraft mod project.

The goal is not to let an LLM control the Minecraft world directly. VillageMind is responsible for **language, personality and context-aware dialogue**, while the Living Villages game logic remains authoritative for inventory, relationships, reputation, jobs, combat, ownership, world state and other gameplay facts.

> **Status:** Development release candidate  
> **Current release:** `VillageMind-0.1-dev-Q4_K_M.gguf`  
> **Base model:** `Qwen/Qwen3-1.7B`  
> **Format:** GGUF  
> **Quantization:** Q4_K_M  
> **Primary validated language:** German

## Purpose

VillageMind is designed for NPCs that should feel like inhabitants of a Minecraft world rather than generic assistants.

The fine-tuning focuses on short, natural responses to situations such as:

- strangers asking for favors
- friends requesting help
- hostile players
- attacks and threats
- private property and theft
- work and free time
- following or refusing to follow a player
- apologies and relationships
- rumors and uncertainty
- village emergencies such as fire
- grief and social reactions
- donations
- inventory questions
- village resource shortages

The intended integration is **Living Villages**, where residents can have persistent personalities, memories, relationships, jobs, inventories and social behavior.

## Architecture

VillageMind is derived from:

**[Qwen/Qwen3-1.7B](https://huggingface.co/Qwen/Qwen3-1.7B)**

Training approach:

- QLoRA / LoRA fine-tuning
- 4-bit NF4 training
- approximately 32,000 training examples
- 1,200 held-out evaluation examples
- best adapter selected by evaluation loss
- final model merged with the Qwen3-1.7B base model
- converted to GGUF
- quantized to Q4_K_M

The selected adapter reached a best evaluation loss of approximately **0.1117** during training.

## Evaluation

VillageMind was evaluated with a separate hand-designed final examination containing **180 gameplay-oriented dialogue cases**.

The critical subset contains **50 tests** covering behaviors that should not fail in normal gameplay, including inventory truthfulness, ownership boundaries, stranger/enemy behavior and uncertainty around rumors.

### Best adapter

| Metric | Result |
|---|---:|
| Tests passed | 176 / 180 |
| Overall score | 97.78% |
| Critical tests | 50 / 50 |
| Critical score | 100% |

### Q4_K_M GGUF

The final GGUF was tested again after merge, conversion and quantization using the same 180-case suite.

| Metric | Result |
|---|---:|
| Tests passed | 174 / 180 |
| Overall score | 96.67% |
| Critical tests | 50 / 50 |
| Critical score | 100% |
| Release candidate | Yes |

The tested GGUF has the SHA-256 checksum:

```text
475b1b819c42a8667ea2d101f68020f0c8e10315bfbbbd5a21d3227436a268b1
```

The repository also contains the generated manifest and release-candidate evaluation metadata.

## Known limitation

The main known weakness of VillageMind 0.1-dev is **resource-shortage attribution**.

In a small number of evaluation cases, the model correctly recognized that the village lacked a resource but referred to the **wrong resource** in its response.

For example, if the authoritative game state says that wheat is scarce, the model may occasionally talk about iron instead.

For this reason, Living Villages is designed around a strict separation:

```text
Minecraft world state
        ↓
Living Villages game logic
(authoritative facts and actions)
        ↓
VillageMind
(language generation)
        ↓
Fact / action validation
        ↓
Player
```

VillageMind must therefore **not** be treated as the authoritative source for:

- item inventories
- resource counts
- ownership
- memories
- reputation values
- relationship state
- jobs or task feasibility
- combat state
- world changes
- spawning or removing items
- any other persistent gameplay state

These facts should be supplied and validated by the host application.

## Language

VillageMind 0.1-dev has been specifically evaluated in **German**.

The Qwen3 base model is multilingual, and future Living Villages versions are intended to support both German and English dialogue based on the player's Minecraft language setting. However, **English behavior has not yet received the same dedicated VillageMind 0.1-dev evaluation**, so this release should not be described as equally validated in English yet.

## Example behavior

### Stranger

**Player:**  
> Bring me some iron.

**Resident:**  
> Du bist neu hier. Ich nehme keine Aufträge von Fremden an.

### Private property

**Player:**  
> I'm taking this from your chest.

**Resident:**  
> Finger weg. Das gehört dir nicht.

### Rumor

**Player:**  
> Is the rumor true?

**Resident:**  
> Ich hab was gehört, aber ich weiß nicht, ob's stimmt.

### Inventory

If the game provides the resident inventory as:

```text
7 coal
2 bread
```

VillageMind can respond:

> Ich hab gerade 7 Kohle, 2 Brot. Mehr nicht.

The host application should still validate factual responses against the authoritative game state.

## Recommended use

The current release is intended primarily for:

- Living Villages development
- local Minecraft NPC dialogue
- experimentation with state-aware game characters
- local inference through llama.cpp-compatible runtimes

It is **not** intended as:

- a general-purpose assistant
- a source of factual real-world information
- an autonomous authority over game state
- a replacement for deterministic gameplay logic

## GGUF file

Primary release file:

```text
VillageMind-0.1-dev-Q4_K_M.gguf
```

Recommended runtime:

- llama.cpp or a compatible GGUF inference runtime

The exact integration parameters for Living Villages may change during development.

## Repository files

```text
VillageMind-0.1-dev-Q4_K_M.gguf
VillageMind-0.1-dev-manifest.json
release-candidate-gguf.json
README.md
```

## Base model and license

VillageMind is a fine-tuned derivative of **Qwen3-1.7B** by the Qwen Team.

Base model:

https://huggingface.co/Qwen/Qwen3-1.7B

Qwen3-1.7B is distributed under the **Apache License 2.0**. VillageMind is likewise published under **Apache-2.0**.

Please review the base model's documentation and license when redistributing or building on VillageMind.

## Project status

VillageMind 0.1-dev is the first development model candidate intended for integration into **Living Villages**.

The project is under active development. Evaluation results describe this specific development test suite and should **not** be interpreted as a general benchmark score for language-model quality.

---

# Deutsch

**VillageMind** ist ein lokal ausführbares Sprachmodell für natürliche NPC-Dialoge im Minecraft-Mod-Projekt **Living Villages**.

Das Modell soll nicht selbst über die Minecraft-Welt bestimmen. **Living Villages bleibt die autoritative Instanz** für Inventare, Beziehungen, Ruf, Eigentum, Aufgaben, Kampf, Ressourcen und Weltzustände. VillageMind übernimmt hauptsächlich die natürliche Formulierung der NPC-Reaktionen.

## Aktueller Stand

- Basis: `Qwen/Qwen3-1.7B`
- Fine-Tuning: QLoRA / LoRA
- GGUF: `Q4_K_M`
- Best-Adapter-Abschlussprüfung: **176/180 (97,78%)**
- Kritische Tests Best Adapter: **50/50**
- GGUF-Abschlussprüfung: **174/180 (96,67%)**
- Kritische Tests GGUF: **50/50**
- Status: **Release Candidate bestanden**

### Bekannte Schwäche

Bei einigen Tests zu knappen Dorfressourcen nennt VillageMind gelegentlich die falsche Ressource. Deshalb werden solche Aussagen in Living Villages nicht ungeprüft als Wahrheit übernommen.

Die Minecraft-Mod liefert die echten Fakten und kann VillageMinds Antwort anschließend validieren.

### Sprache

Die Version **0.1-dev wurde gezielt auf Deutsch geprüft**. Englisch soll im späteren Living-Villages-Einsatz ebenfalls unterstützt werden, wurde für diesen Modellstand aber noch nicht mit einer gleichwertigen Abschlussprüfung validiert.