ifmanzhang/huangquan-wuchang-repe-npc

Huangquan Wuchang RepE / QLoRA NPC Prototype

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.

Purpose

The experiment explored how to make a local Qwen-based NPC speak in a more archaic, concise, and less modern style. It combines:

• 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.

Retained Contents

The public archive keeps the materials needed to explain and inspect the work:

• 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.

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 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.