Downloads · 30 days
14
4% of all-time downloads
omaraboelmaaty/pastport-npc-llama3-gguf
pastport-npc-llama3-gguf is a text generation model from omaraboelmaaty. Use it when you need the model to write or continue text. The card lists the license as llama3.
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).
Downloads · 30 days
14
4% of all-time downloads
All-time downloads
377
Public
Repo size
4.9 GB
Likes
0
Public
Click a slice to open those files.
.gguf4.9 GB · 100%
From the Hugging Face model README
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.
npc_model_q4.gguf, 4.58 GB)llama.cpp / llama-cpp-python, CPU or GPU (n_gpu_layers configurable)detect_lang() finds a mismatch
between the response language and the user's spoken language)This model is designed to run inside the PastPort NPC Engine, which wraps it with:
world_context (civilization, location, role/name, resolved historical year)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.
This mirrors the actual loading/inference parameters used in PastPort's own NPC Engine server:
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'screate_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.
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:
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.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.
The model is trained to always respond with JSON containing two keys, not plain text:
{
"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.
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.
Developed by Omar Abo Elmaaty as part of PastPort, a Computer Science graduation project combining generative AI and VR for interactive history education.