Upload README.md

README.md

@@ -0,0 +1,281 @@
+---
+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.