StoryChatBot / engine /prompt_builder.py
cereeenn120's picture
Expand language support
2c96d86
Raw History Blame Contribute Delete
24.4 kB
"""
Prompt builder β€” assembles the full system prompt from all parts.
Build order (each section separated by a blank line):
1. Global rules (format rules, roleplay rules)
2. Character definition (identity, personality, speech, world, examples)
3. Character-specific instructions (system_prompt field in JSON)
4. User persona (optional)
5. Memory (conversation summary + long-term memories)
Then passed as the system message, followed by:
6. Recent conversation history
7. Current user message
"""
import logging
import os
import re
from pathlib import Path
from typing import Any
from engine.static_files import load_static_json, load_static_text
logger = logging.getLogger(__name__)
ROOT = Path(__file__).resolve().parent.parent
CHARACTERS_DIR = ROOT / "characters"
PROMPTS_DIR = ROOT / "prompts"
ASSETS_DIR = ROOT / "assets"
# ── Character loading ──────────────────────────────────────────────────────────
def load_character(character_id: str) -> dict[str, Any]:
"""Load a character by ID from its category/group folder."""
if not isinstance(character_id, str) or not re.fullmatch(r"[a-zA-Z0-9_-]{1,100}", character_id):
raise ValueError("Invalid character ID.")
matches = list(Path(CHARACTERS_DIR).rglob(f"{character_id}.json"))
if not matches:
raise FileNotFoundError(f"Character file not found: {character_id}")
if len(matches) > 1:
raise ValueError(f"Character ID is not unique: {character_id}")
return load_static_json(matches[0])
def list_groups() -> list[dict[str, Any]]:
"""Build the story catalogue from the existing category/group metadata."""
groups: dict[tuple[str, str], dict[str, Any]] = {}
for item in list_characters():
key = (item["library_category"], item["character_group"])
group = groups.setdefault(key, {
"category": key[0], "name": key[1], "characters": [],
"group_image": _group_image_for_catalog(key[0], key[1]),
})
character = load_character(item["id"])
group["characters"].append({
"id": item["id"], "name": item["name"], "description": item["description"],
"group_role": character.get("group_role", "supporting"),
"role": character.get("identity", {}).get("role", ""),
"age": character.get("age", character.get("identity", {}).get("age", "")),
"gender": character.get("gender", character.get("identity", {}).get("gender", "")),
"personality": character.get("personality", []),
"background": character.get("identity", {}).get("background", ""),
"body_image": _image_url_for_catalog(get_avatar_path(item["id"])),
"portrait_image": _image_url_for_catalog(get_portrait_path(item["id"])),
"world": character.get("world", {}),
})
return [groups[key] for key in sorted(groups, key=lambda pair: (pair[0].casefold(), pair[1].casefold()))]
def _group_image_for_catalog(category: str, group: str) -> str | None:
"""Return the optional group_01 image for a category/group directory."""
slug = lambda value: re.sub(r"[^a-z0-9]+", "_", value.casefold()).strip("_")
group_dir = ASSETS_DIR / slug(category) / slug(group)
for suffix in ("jpg", "jpeg", "png", "webp"):
image = group_dir / f"group_01.{suffix}"
if image.is_file():
return _image_url_for_catalog(str(image))
return None
def _image_url_for_catalog(path: str | None) -> str | None:
if not path:
return None
try:
return "/assets/" + Path(path).resolve().relative_to(ASSETS_DIR.resolve()).as_posix()
except ValueError:
return None
def list_characters() -> list[dict[str, str]]:
"""
Discover all characters from the characters/ directory.
Returns a list of dicts with id, name, and description.
Skips any files that fail to parse (logs a warning instead of raising).
"""
characters = []
for path in sorted(Path(CHARACTERS_DIR).rglob("*.json")):
try:
data = load_static_json(path)
characters.append({
"id": data.get("id", os.path.splitext(os.path.basename(path))[0]),
"name": data.get("name", "Unknown"),
"description": data.get("description", ""),
"categories": data.get("categories", []),
"library_category": data.get("library_category", "Other"),
"character_group": data.get("character_group", "Other"),
})
except Exception as e:
logger.warning(f"[Characters] Skipping {path}: {e}")
return characters
def _character_asset_dir(character_id: str) -> Path | None:
matches = list(Path(CHARACTERS_DIR).rglob(f"{character_id}.json"))
if len(matches) != 1:
return None
relative = matches[0].relative_to(CHARACTERS_DIR)
return Path(ASSETS_DIR) / relative.parent / character_id
def _first_image(directory: Path | None, prefix: str) -> str | None:
if directory is None or not directory.is_dir():
return None
matches = sorted(path for path in directory.glob(f"{prefix}_*")
if path.suffix.lower() in {".png", ".jpg", ".jpeg", ".webp"})
return str(matches[0]) if matches else None
def get_avatar_path(character_id: str) -> str | None:
"""
Return the first avatar image path found for a character.
Logs a warning and returns None if no image exists β€” does not raise.
"""
avatar_dir = _character_asset_dir(character_id)
path = _first_image(avatar_dir, "body")
if path:
return path
logger.warning(
f"[Avatar] No image found for '{character_id}' in '{avatar_dir}'. "
"A placeholder will be shown in the UI."
)
return None
def get_portrait_path(character_id: str) -> str | None:
"""Return the portrait image used beside chat messages, falling back to body art."""
directory = _character_asset_dir(character_id)
return _first_image(directory, "portrait") or _first_image(directory, "body")
# ── Prompt sections ────────────────────────────────────────────────────────────
def build_global_prompt() -> str:
"""Load the global system prompt from prompts/system_prompt.txt."""
path = os.path.join(PROMPTS_DIR, "system_prompt.txt")
return load_static_text(path).strip()
def build_character_prompt(character: dict[str, Any]) -> str:
"""
Build the character definition block from a character dict.
Covers: identity, personality, speech style, behavior, world, roleplay rules,
and a capped set of example dialogues.
"""
name = character.get("name", "Unknown")
sections = [f"You are {name}."]
# Identity
identity = character.get("identity", {})
if identity:
parts = []
if identity.get("role"):
parts.append(f"Role: {identity['role']}")
if identity.get("background"):
parts.append(f"Background: {identity['background']}")
if parts:
sections.append("IDENTITY\n" + "\n".join(parts))
# Personality
personality = character.get("personality", [])
if personality:
sections.append("PERSONALITY\n" + ", ".join(personality))
# Speech style
speech = character.get("speech_style", {})
if speech:
parts = []
if speech.get("tone"):
parts.append(f"Tone: {', '.join(speech['tone'])}")
if speech.get("formality"):
parts.append(f"Formality: {speech['formality']}")
if speech.get("sentence_style"):
parts.append(f"Sentence style: {speech['sentence_style']}")
flags = []
if speech.get("uses_humor"):
flags.append("humor")
if speech.get("uses_rhetorical_questions"):
flags.append("rhetorical questions")
if speech.get("avoids_excessive_enthusiasm"):
flags.append("avoids excessive enthusiasm")
if flags:
parts.append("Uses: " + ", ".join(flags))
if parts:
sections.append("SPEECH STYLE\n" + "\n".join(parts))
# Behavior
behavior = character.get("behavior", {})
if behavior:
lines = [
f"- {k.replace('_', ' ')}: {v}"
for k, v in behavior.items()
]
sections.append("BEHAVIOR\n" + "\n".join(lines))
# World
world = character.get("world", {})
if world:
parts = []
if world.get("universe"):
parts.append(f"Universe: {world['universe']}")
if world.get("setting"):
parts.append(f"Setting: {world['setting']}")
if world.get("description"):
parts.append(world["description"])
sections.append("WORLD\n" + "\n".join(parts))
# Roleplay rules
roleplay = character.get("roleplay", {})
if roleplay:
parts = []
if roleplay.get("action_format"):
parts.append(f"Action format: {roleplay['action_format']}")
if roleplay.get("thought_format"):
parts.append(f"Thought format: {roleplay['thought_format']}")
if roleplay.get("break_character") is False:
parts.append("Never break character.")
if parts:
sections.append("ROLEPLAY RULES\n" + "\n".join(parts))
# Example dialogues (capped at 4 to manage token budget)
examples = character.get("example_dialogues", [])
if examples:
lines = ["EXAMPLE DIALOGUES"]
for ex in examples[:4]:
lines.append(f'User: {ex["user"]}')
lines.append(f'{name}: {ex["character"]}')
lines.append("")
sections.append("\n".join(lines).strip())
return "\n\n".join(sections)
def build_story_prompt(
group: dict[str, Any], role: dict[str, Any], topic: str = "",
response_length: str = "balanced", creativity: str = "balanced",
point_of_view: str = "third_person_limited",
themes: dict[str, str] | None = None, next_plot: str = "",
) -> str:
"""Build the ensemble and narrator instructions for one story turn."""
cast = []
for character in group.get("characters", []):
cast.append(build_compact_story_character_prompt(load_character(character["id"])))
role_name = role.get("name") or "the user's original character"
length_rules = {
"short": "Keep the response brief: one or two concise paragraphs, while still moving the scene forward.",
"balanced": "Write 3–4 vivid, substantial paragraphs, balancing scene detail with a clear opening for the player.",
"long": "Write 4–6 richly detailed paragraphs, developing the scene, character interactions, and consequences before leaving an opening for the player.",
}
creativity_rules = {
"grounded": "Keep developments plausible and closely connected to established events, character motives, and the story world. Avoid sudden twists.",
"balanced": "Balance coherent, character-driven progression with occasional fresh and unexpected developments that follow naturally from the scene.",
"imaginative": "Favor vivid, unusual possibilities and surprising developments, while preserving cause and effect, character consistency, and the established world.",
}
point_of_view_rules = {
"first_person": "Write the narration in first person from the player's character's perspective, using 'I' and 'me'. Describe only what the player character can observe; never decide the player's actions, words, thoughts, or feelings.",
"second_person": "Address the player character as 'you' in second-person narration. Describe only what the player character can observe; never decide the player's actions, words, thoughts, or feelings.",
"third_person_limited": "Use third-person limited narration focused on the player's character. Describe only what the player character can observe; never reveal private thoughts or feelings of any character.",
"third_person_omniscient": "Use third-person omniscient narration, which may move between characters and reveal their private thoughts and feelings when useful. Never decide the player's actions, words, thoughts, or feelings.",
}
sections = [
"You are the Narrator of an immersive ensemble story. Narrate the world and all non-player characters; never decide the user's actions, words, thoughts, or feelings. Follow the selected point of view when deciding whose private thoughts and feelings may be narrated. Do not create action or thought sections, blocks, tags, labels, or headings.",
f"STORY GROUP: {group['name']} ({group['category']})\n" + "\n\n".join(cast),
f"PLAYER ROLE\nThe user plays {role_name}. Treat this as the user's role in the story, not as a character you control.",
"POINT OF VIEW\n" + point_of_view_rules.get(point_of_view, point_of_view_rules["third_person_limited"]),
"STORY RESPONSE FORMAT\n" + length_rules.get(response_length, length_rules["balanced"]) + " Narration is plain prose. Every in-world spoken line must use exactly this format: <character name>\"spoken dialogue\". Put each speaker on its own line. The speaker prefix above is the ONLY permitted angle-bracket notation. Never emit <action>, </action>, <thought>, </thought>, or any other markup tag; never wrap narration in labeled bodies or sections. Physical actions belong naturally in the Narrator's prose. Follow the selected point of view for narration; the player's private thoughts and feelings must never be stated unless the player explicitly provides them.",
"STORY PROGRESSION\n" + creativity_rules.get(creativity, creativity_rules["balanced"]) + " Do not recap or restate the same scene beats, dialogue, or pending choice from earlier turns. Each reply must respond to the player's latest input and advance the timeline with a new action, consequence, or meaningful interaction. Do not manufacture unrelated conflict just to force progress.",
]
description = role.get("description", "")
if description:
sections.append(f"PLAYER CHARACTER DETAILS\n{_clip_context(description, 1600)}")
if topic.strip():
sections.append(f"USER'S OPTIONAL STORY PREMISE\n{_clip_context(topic.strip(), 1400)}\nUse this as a starting direction while allowing the story to develop naturally.")
selected_themes = themes or {}
theme_lines = [f"{label}: {selected_themes.get(key, '')}" for key, label in (("main", "Main theme"), ("supporting1", "Supporting theme 1"), ("supporting2", "Supporting theme 2")) if selected_themes.get(key)]
if theme_lines:
sections.append("USER'S STORY THEMES\n" + "\n".join(theme_lines) + "\nUse these as genre and tone guidance while keeping characters and events consistent with the source world.")
if next_plot.strip():
sections.append(f"PLAYER'S PREFERRED STORY DIRECTION\n{_clip_context(next_plot.strip(), 1200)}\nWork this direction into the story naturally over time. Treat it as guidance, not permission to skip the player's choices or force an implausible outcome.")
return "\n\n".join(sections)
def build_compact_story_character_prompt(character: dict[str, Any]) -> str:
"""Keep the character's distinguishing facts while omitting bulky examples."""
name = str(character.get("name", "Unknown"))
identity = character.get("identity", {})
speech = character.get("speech_style", {})
personality = character.get("personality", [])
lines = [f"{name} (group role: {character.get('group_role', 'supporting')})"]
if identity.get("role"):
lines.append(f"Role: {identity['role']}")
if personality:
lines.append("Personality: " + ", ".join(str(item) for item in personality[:8]))
tone = speech.get("tone", [])
if tone:
lines.append("Voice: " + ", ".join(str(item) for item in tone[:4]))
if speech.get("sentence_style"):
lines.append(f"Speech: {speech['sentence_style']}")
background = str(identity.get("background", "")).strip()
if background:
lines.append("Background: " + _clip_context(background, 240))
notes = str(character.get("system_prompt", "")).strip()
if notes:
lines.append("Character notes: " + _clip_context(notes, 300))
return "\n".join(lines)
def select_active_story_characters(
group: dict[str, Any], role: dict[str, Any], recent_messages: list[dict[str, str]], current_message: str,
*, summary: str = "", long_term_memory: list[dict] | None = None,
max_major: int = 15, max_supporting: int = 8,
) -> dict[str, Any]:
"""Select the core cast plus supporting characters already relevant to the scene."""
characters = list(group.get("characters", []))
player_id = role.get("character_id") if role.get("kind") == "existing" else None
major = [member for member in characters if member.get("group_role", "supporting") == "major"]
# Older group metadata remains usable: for small groups, treat the whole cast as core.
if not major and len(characters) <= max_major:
major = characters
selected = major[:max_major]
if player_id:
player = next((member for member in characters if member.get("id") == player_id), None)
if player and player not in selected:
if len(selected) >= max_major:
selected[-1] = player
else:
selected.append(player)
scene_text = str(summary or "") + "\n"
scene_text += "\n".join(str(item.get("content", "")) for item in recent_messages[-12:])
scene_text += "\n" + "\n".join(str(item.get("content", "")) for item in (long_term_memory or []))
scene_text += "\n" + str(current_message or "")
scene_folded = scene_text.casefold()
mentioned = [member for member in characters
if member not in selected and member.get("name", "").casefold() in scene_folded]
mentioned.sort(key=lambda member: scene_folded.rfind(member.get("name", "").casefold()), reverse=True)
selected.extend(mentioned[:max_supporting])
result = dict(group)
result["characters"] = selected
return result
def _clip_context(value: str, limit: int) -> str:
value = re.sub(r"\s+", " ", value).strip()
if len(value) <= limit:
return value
return value[:limit - 1].rsplit(" ", 1)[0] + "…"
def build_character_specific_prompt(character: dict[str, Any]) -> str:
"""
Return the character's system_prompt field.
This is character-specific fine-tuning on top of the global rules β€”
it does not replace them.
"""
sp = character.get("system_prompt", "").strip()
if sp:
return f"ADDITIONAL CHARACTER NOTES\n{sp}"
return ""
def build_persona_prompt(persona: dict[str, str] | None) -> str:
"""
Build the user persona section.
Returns an empty string if persona is absent or all fields are blank.
"""
if not persona or not any(persona.values()):
return ""
lines = ["THE USER IS PLAYING THE ROLE OF:"]
for key in ("name", "age", "gender", "personality", "background"):
val = _clip_context(persona.get(key, "").strip(), 900)
if val:
lines.append(f"{key.capitalize()}: {val}")
return "\n".join(lines)
def build_memory_prompt(summary: str, long_term_memory: list[dict]) -> str:
"""Build the memory section from conversation summary and long-term memories."""
parts = []
if summary:
parts.append(f"CONVERSATION SUMMARY\n{_clip_context(summary, 2200)}")
if long_term_memory:
lines = ["LONG-TERM MEMORY"]
ranked = sorted(long_term_memory, key=lambda mem: (
0 if mem.get("origin") == "manual" else 1,
{"high": 0, "medium": 1, "low": 2}.get(mem.get("importance", "medium"), 1),
))
remaining = 2600
for mem in ranked:
content = _clip_context(str(mem.get("content", "")), min(360, remaining - 32))
if not content or remaining <= 32:
break
importance = mem.get("importance", "medium").upper()
lines.append(f"[{importance}] {content}")
remaining -= len(content) + len(importance) + 4
parts.append("\n".join(lines))
return "\n\n".join(parts)
# ── Language instruction ───────────────────────────────────────────────────────
# Maps lowercase language name β†’ display label (native name in parentheses)
_LANG_LABELS: dict[str, str] = {
"turkish": "Turkish (TΓΌrkΓ§e)",
"french": "French (FranΓ§ais)",
"german": "German (Deutsch)",
"italian": "Italian (Italiano)",
"russian": "Russian (Русский)",
"chinese": "Chinese (δΈ­ζ–‡)",
"hindi": "Hindi (ΰ€Ήΰ€Ώΰ€¨ΰ₯ΰ€¦ΰ₯€)",
"spanish": "Spanish (EspaΓ±ol)",
"arabic": "Arabic (Ψ§Ω„ΨΉΨ±Ψ¨ΩŠΨ©)",
"bengali": "Bengali (বাংলা)",
"portuguese": "Portuguese (PortuguΓͺs)",
"indonesian": "Indonesian (Bahasa Indonesia)",
"japanese": "Japanese (ζ—₯本θͺž)",
}
def build_language_prompt(language: str) -> str:
"""
Return a language-enforcement instruction for the system prompt.
Returns an empty string for English (the default behaviour of most models).
"""
key = language.strip().lower()
if not key or key == "english":
return ""
label = _LANG_LABELS.get(key, language)
return (
f"LANGUAGE\n"
f"You must always respond in {label}. "
f"This applies to all dialogue, actions, and internal thoughts β€” "
f"regardless of what language the user writes in."
)
# ── Final assembly ─────────────────────────────────────────────────────────────
def build_messages(
character: dict[str, Any],
persona: dict[str, str] | None,
summary: str,
long_term_memory: list[dict],
recent_messages: list[dict],
current_message: str,
language: str = "English",
story_prompt: str | None = None,
) -> list[dict[str, str]]:
"""
Assemble the full messages array to send to the LLM.
System prompt build order:
1. Global rules (format rules, roleplay rules)
2. Character definition (identity, personality, speech, world, examples)
3. Character-specific instructions (system_prompt field in JSON)
4. User persona (optional)
5. Memory (summary + long-term)
6. Language instruction (omitted for English)
Then:
7. Recent conversation history
8. Current user message
"""
system_sections: list[str] = []
global_prompt = build_global_prompt()
if global_prompt and not story_prompt:
system_sections.append(global_prompt)
if story_prompt:
system_sections.append(story_prompt)
else:
char_prompt = build_character_prompt(character)
if char_prompt:
system_sections.append(char_prompt)
char_specific = build_character_specific_prompt(character) if not story_prompt else ""
if char_specific:
system_sections.append(char_specific)
persona_prompt = build_persona_prompt(persona)
if persona_prompt:
system_sections.append(persona_prompt)
memory_prompt = build_memory_prompt(summary, long_term_memory)
if memory_prompt:
system_sections.append(memory_prompt)
# Language instruction goes last β€” recency helps models follow it reliably
lang_prompt = build_language_prompt(language)
if lang_prompt:
system_sections.append(lang_prompt)
system_content = "\n\n".join(system_sections)
messages: list[dict[str, str]] = [{"role": "system", "content": system_content}]
messages.extend(recent_messages)
if current_message:
messages.append({"role": "user", "content": current_message})
logger.debug(
f"[PromptBuilder] Built: {len(system_content)} chars system | "
f"{len(system_sections)} sections | "
f"{len(recent_messages)} history turns | "
f"language='{language}'"
)
return messages