This is a fine-tuned, GGUF-quantized version of Llama 3 8B, trained to role-play as historical figures for PastPort, an AI-powered VR history-education platform (graduation project).

The model powers the NPC dialogue subsystem: given a historical persona, an era, and a location, it responds in character — in Arabic or English, matching the language the user speaks — while staying within the knowledge boundaries of its assigned historical period.

Model Details

Base model: Llama 3 8B
Fine-tuning method: LoRA, merged into the base weights before quantization
Quantization: GGUF, Q4 (npc_model_q4.gguf, 4.58 GB)
Training data: English-only historical-persona dialogue dataset (Arabic output relies on the base model's multilingual generalization, not on Arabic training data)
Intended runtime: llama.cpp / llama-cpp-python, CPU or GPU (n_gpu_layers configurable)
Languages: English, Arabic (bilingual auto-detection with a language-correction fallback pass in the serving code: a second lightweight LLM call fires whenever detect_lang() finds a mismatch between the response language and the user's spoken language)

Intended Use

This model is designed to run inside the PastPort NPC Engine, which wraps it with:

A world_context (civilization, location, role/name, resolved historical year)
Whisper (speech-to-text) and XTTS v2 (text-to-speech) for voice conversation
A language-mismatch fallback that re-generates the response in the correct language if needed

Used standalone (raw text completion, no wrapper), it will still generally attempt in-character historical dialogue, but without era/year grounding or the language fallback, so responses may occasionally break character, hallucinate anachronistic knowledge, or answer in the wrong language.

Out-of-Scope Use

Not intended as a general-purpose assistant or factual-accuracy source for real historical research — it is optimized for engaging, in-character educational dialogue, not citation-grade historical accuracy.
Not intended for unmoderated public deployment without the language-correction and prompt-context wrapper it was designed to run behind.

How to Use (llama.cpp / llama-cpp-python)

This mirrors the actual loading/inference parameters used in PastPort's own NPC Engine server:

python

from llama_cpp import Llama
from huggingface_hub import hf_hub_download

model_path = hf_hub_download(
    repo_id="omaraboelmaaty/pastport-npc-llama3-gguf",
    filename="npc_model_q4.gguf",
)

llm = Llama(
    model_path=model_path,
    n_ctx=2048,
    n_threads=8,
    n_gpu_layers=35,  # set to 0 for CPU-only inference
    verbose=False,
)

system_prompt = """You are a historical NPC.

Year: -41
Location: Alexandria
Civilization: Ptolemaic Egypt
Identity: Cleopatra VII

Return ONLY JSON:

{
  "response": "...",
  "anim_cues": {
    "emotion": ["neutral"],
    "facial_expression": ["neutral"],
    "gesture": ["idle"],
    "head_movement": ["still"],
    "tts_style": ["calm"]
  }
}

Rules:
- Stay in character
- No modern knowledge
- Short replies

You MUST respond in English only.
"""

output = llm.create_chat_completion(
    messages=[
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": "What do you think of Rome?"},
    ],
    temperature=0.25,
    max_tokens=400,
    repeat_penalty=1.3,
    response_format={"type": "json_object"},  # llama.cpp JSON-mode, enforces valid JSON output
)
print(output["choices"][0]["message"]["content"])
# -> {"response": "...", "anim_cues": {"emotion": ["wary"], ...}}

Note: the served system prompt is plain text passed through llama-cpp-python's create_chat_completion (which applies whatever chat template is embedded in the GGUF's metadata), not the raw <|system|>/<|user|>/<|assistant|> string format used during Stage 2 fine-tuning. If you notice degraded instruction-following or JSON adherence compared to the training-time examples, this template mismatch is the most likely first place to look.

Limitations

~2 tokens/second on modest consumer hardware (e.g. RTX 3070 Laptop GPU, 8 GB VRAM) — expect slow, non-instant generation.
Roman/Latin-heavy personas show more language-slippage (unwanted English creeping into Arabic responses) than Egyptian personas, since fine-tuning data is English-only.
Not evaluated for safety-critical or unsupervised production use — built and tested as a graduation project component.

Training & Fine-Tuning

Fine-tuned from meta-llama/Meta-Llama-3-8B-Instruct using QLoRA (4-bit NF4 double-quantized base + LoRA adapters, via HuggingFace transformers + peft + bitsandbytes), in two stages:

Stage 1 — general historical-persona dialogue (stage1_train.jsonl / stage1_val.jsonl). LoRA rank 8, alpha 16, target modules q_proj/v_proj, dropout 0.05. 2 epochs, learning rate 2e-4, batch size 1 with gradient accumulation 8, fp16.
Stage 2 — continues training from the Stage 1 adapter on a structured-output dataset (QA_with_anim_cues_v2.jsonl) that adds a JSON anim_cues field alongside the text response. 2 epochs, learning rate 1e-4, same batch/accumulation settings. Uses a custom <|system|>/<|user|>/<|assistant|> prompt template with the loss masked to only the assistant turn.

The two LoRA adapters were merged into the base weights (merge_lora_to_base.py, CPU merge, saved as safetensors), then converted to GGUF and quantized to Q4 (npc_model_q4.gguf, 4.58 GB) via llama.cpp for local CPU/GPU inference.

Arabic responses are not the result of Arabic training data — the dataset is English-only, and Arabic output relies entirely on the base model's own multilingual generalization, which is why Roman/Latin-heavy personas show more language-slippage into English than Egyptian personas.

Structured output format

The model is trained to always respond with JSON containing two keys, not plain text:

json

{
  "response": "Wars that devastated Europe. Millions died, empires fell.",
  "anim_cues": {
    "emotion": ["somber"],
    "facial_expression": ["serious"],
    "gesture": ["hand_on_chest"],
    "head_movement": ["shake_head"],
    "tts_style": ["reflective"]
  }
}

anim_cues drives the Unity-side NPC animation and TTS-style selection alongside the spoken response text — this model was trained to be a full expressive-dialogue controller, not just a text generator.

License

Distributed under the Meta Llama 3 Community License, inherited from the base model. You must comply with Meta's Llama 3 license terms for any use of this model or derivatives.

Citation / Attribution

Developed by Omar Abo Elmaaty as part of PastPort, a Computer Science graduation project combining generative AI and VR for interactive history education.