omaraboelmaaty/pastport-llm-model

🧠 PastPort LLM Model

PastPort LLM is a quantized GGUF model built on LLaMA 3 Instruct and adapted for real-time historical NPC simulation.

It powers the PastPort system --- a time-locked AI character engine designed for immersive historical interaction.

---

🏗 Base Model

• Architecture: LLaMA 3 Instruct\
• Format: GGUF\
• Quantization: Q4\
• Inference Backend: llama-cpp-python\
• Context Length: 2048 tokens\
• Optimized for CUDA GPU inference

This model is derived from LLaMA 3 Instruct and further adapted for structured, character-constrained historical simulation.

---

🎯 Fine-Tuning & Adaptation

The model has been instruction-adapted and behavior-aligned for:

1️⃣ Historical Role Simulation

• Fixed identity (Pharaoh, Emperor, Scholar, etc.)
• Civilization-locked worldview
• Period-consistent vocabulary

2️⃣ Time-Locked Knowledge

• Dynamic internal year selection
• No knowledge beyond assigned historical year
• Refusal behavior for future-related questions

3️⃣ Structured JSON Output

The model always returns:

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

This enables: - Emotion-aware TTS\

• Animation synchronization\
• Real-time streaming playback

---

📚 Training & Data Adaptation

Adaptation included:

• Instruction-following dialogue datasets\
• Synthetic historical Q&A generation\
• Role-conditioned prompts\
• Civilization-specific context templates\
• JSON-structured output enforcement

The model is optimized to:

• Stay strictly in character\
• Avoid modern references\
• Avoid post-period knowledge\
• Maintain linguistic consistency\
• Respond in Arabic or English only

No proprietary datasets were used.

---

🌍 Intended Use

Designed for:

• Real-time historical NPC engines\
• Museum installations\
• VR / AR historical environments\
• Educational simulations\
• AI character storytelling

---

🚫 Out-of-Scope Use

Not intended for:

• General assistant usage\
• Modern factual QA\
• Legal or medical advice\
• Open-domain unrestricted chat

---

⚙ Recommended Hardware

Minimum: - NVIDIA T4 GPU

Recommended: - NVIDIA A10G or higher

Optimized for GPU inference using llama-cpp-python.

---

🚀 Example Usage

from huggingface_hub import hf_hub_download
from llama_cpp import Llama

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

llm = Llama(
    model_path=model_path,
    n_ctx=2048,
    n_gpu_layers=35
)

---

👤 Author

Omar Abo Elmaaty
AI Developer -- Real-Time Simulation Systems