Document pruned public archive

README.md

@@ -10,38 +10,51 @@ tags:
 - repe
 - npc
 - game-ai
+- preliminary
 ---
 
-# Huangquan Wuchang RepE NPC Prototype
+# Huangquan Wuchang RepE / QLoRA NPC Prototype
 
-This repository contains preliminary R&D artifacts for the *Huangquan Road* / *Mingjie Kuangye* project.
+This repository preserves the necessary working traces and model artifacts for a preliminary Wuchang NPC experiment from the Huangquan Road project. It is not the current main game runtime.
 
-It is not part of the current main game runtime. It documents an earlier local NPC-model experiment for the character Wuchang.
+## Purpose
 
-## Contents
+The experiment explored how to make a local Qwen-based NPC speak in a more archaic, concise, and less modern style. It combines:
 
-- `merged_model/`: first merged local model after the taciturn/ruthless LoRA stage.
-- `merged_model_v2/`: final merged local Wuchang model after the bilingual archaic-style LoRA stage.
-- `finetune/`: QLoRA checkpoints and adapter files.
-- `data/pairs/`: Gemini 3 Pro generated contrast-pair training data.
-- `vectors/`: RepE steering vectors for taciturn and ruthless traits.
-- `outputs/`: layer sweep results.
-- `test_logs/`: automated dialogue and plot-routing test logs.
-- `src/`, `wuchang_chat*.py`, `test_wuchang*.py`: extraction, steering, routing, chat, and evaluation scripts.
-- `TECH_DOC.md`: detailed technical notes.
+- Representation Engineering (RepE) steering vectors for taciturn / ruthless traits.
+- QLoRA adapters for style and behavior consolidation.
+- A rule / classifier based plot router for Wuchang-specific narrative triggers.
+- Iterative test logs for prompt variants, routing behavior, language style, and injection resistance.
 
-## Summary
+## Retained Contents
 
-The prototype combines representation engineering and LoRA fine-tuning:
+The public archive keeps the materials needed to explain and inspect the work:
 
-- Base model: `Qwen/Qwen3.5-9B`
-- Traits: taciturn and ruthless steering vectors
-- Style target: concise archaic Chinese and archaic English
-- Training data: 350 bilingual Wuchang style contrast pairs, plus taciturn/ruthless contrast data
-- Final model artifact: `merged_model_v2`
+- `TECH_DOC.md`, `config.yaml`, `requirements.txt`: technical notes and experiment configuration.
+- `data/pairs/*.jsonl`: synthetic contrast data generated with Gemini 3 Pro.
+- `data/generate_*.py`: scripts used to generate the contrast pairs.
+- `src/*.py`: RepE vector extraction, steering application, evaluation, and model utilities.
+- `finetune/train_lora.py`, `finetune/merge_lora.py`: QLoRA training and merge scripts.
+- `finetune/checkpoints/*`: final first-pass LoRA adapter and tokenizer/config files.
+- `finetune/style_checkpoint/*`: final bilingual archaic-style LoRA adapter and tokenizer/config files.
+- `vectors/*.pt`: layer-wise RepE steering vectors.
+- `outputs/*.jsonl`, `outputs/*best_layer.txt`: layer sweep records.
+- `test_logs/*.txt`, `test_wuchang*.py`, `wuchang_chat*.py`: iterative NPC behavior tests and chat prototypes.
 
-The training data was generated with Gemini 3 Pro and then used as project-specific experimental data for the Wuchang NPC prototype.
+## Pruned From the Public Archive
+
+The following local files were intentionally removed from the current public revision:
+
+- `merged_model/` and `merged_model_v2/` full merged model weights.
+- Intermediate checkpoint folders such as `checkpoint-96`, `checkpoint-192`, `checkpoint-288`, `checkpoint-44`, `checkpoint-88`, and `checkpoint-132`.
+- Optimizer, scheduler, RNG, Python cache, and local tool-configuration files.
+
+These files are redundant for assessment evidence because the public archive keeps the final adapters, data, configuration, training scripts, RepE vectors, and test records. Full merged weights can be regenerated from the documented base model and retained adapters if needed.
+
+## Data Provenance
+
+The style-control pairs are synthetic contrast data generated with Gemini 3 Pro. They should be described as generated experiment data, not player data or real conversations.
 
 ## Boundary
 
-This was an early experiment and is not integrated into the current released game flow. It should be cited as preliminary model-training work rather than as a current gameplay feature.
+This is preliminary work. The current Huangquan game uses persona runtime prompts, provider clients, output guards, and optional narrative enhancements as its main NPC dialogue path.