Add chatbot engine and memory system phase-1

app.py

@@ -1,69 +1,85 @@
+import logging
 import gradio as gr
 from huggingface_hub import InferenceClient
+from engine.chat import generate_response
+from engine.prompt_builder import get_avatar_path, load_character
 
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
 
-def respond(
-    message,
-    history: list[dict[str, str]],
-    system_message,
-    max_tokens,
-    temperature,
-    top_p,
-    hf_token: gr.OAuthToken,
-):
-    """
-    For more information on `huggingface_hub` Inference API support, please check the docs: https://huggingface.co/docs/huggingface_hub/v0.22.2/en/guides/inference
-    """
-    client = InferenceClient(token=hf_token.token, model="openai/gpt-oss-20b")
+# ── Configuration ──────────────────────────────────────────────────────────────
+# Switch CHARACTER_ID to load a different character from characters/*.json
+# Switch MODEL to change the LLM (any model available on HuggingFace Inference API)
+CHARACTER_ID = "jessica_jones"
+MODEL        = "openai/gpt-4o-mini"   # or e.g. "deepseek-ai/DeepSeek-V3"
+
+# ── Load character on startup ──────────────────────────────────────────────────
+character   = load_character(CHARACTER_ID)
+avatar_path = get_avatar_path(CHARACTER_ID)  # None if missing (warns, doesn't crash)
 
-    messages = [{"role": "system", "content": system_message}]
+char_name = character.get("name", CHARACTER_ID)
+char_role = character.get("identity", {}).get("role", "")
+greeting  = character.get("greeting", "Hello. What do you want?")
 
-    messages.extend(history)
 
-    messages.append({"role": "user", "content": message})
+# ── Gradio respond function ────────────────────────────────────────────────────
+def respond(
+    message:     str,
+    history:     list[dict],   # Gradio 5.x messages format: [{"role": ..., "content": ...}]
+    max_tokens:  int,
+    temperature: float,
+    top_p:       float,
+    hf_token:    gr.OAuthToken,
+):
+    if hf_token is None:
+        yield "⚠️ Please log in with your HuggingFace account to chat."
+        return
 
-    response = ""
+    client = InferenceClient(token=hf_token.token)
 
-    for message in client.chat_completion(
-        messages,
+    yield from generate_response(
+        message=message,
+        character_id=CHARACTER_ID,
+        client=client,
+        persona=None,          # Phase 8: user persona form
+        model=MODEL,
         max_tokens=max_tokens,
-        stream=True,
         temperature=temperature,
         top_p=top_p,
-    ):
-        choices = message.choices
-        token = ""
-        if len(choices) and choices[0].delta.content:
-            token = choices[0].delta.content
-
-        response += token
-        yield response
+    )
 
 
-"""
-For information on how to customize the ChatInterface, peruse the gradio docs: https://www.gradio.app/docs/chatinterface
-"""
+# ── UI ─────────────────────────────────────────────────────────────────────────
+# Gradio 5.x: ChatInterface defaults to messages format, no 'type' param needed.
+# gr.Chatbot value uses dict format: {"role": "user"|"assistant", "content": "..."}
 chatbot = gr.ChatInterface(
-    respond,
+    fn=respond,
+    chatbot=gr.Chatbot(
+        value=[{"role": "assistant", "content": greeting}],
+        label=char_name,
+        avatar_images=(None, avatar_path),
+        height=500,
+    ),
     additional_inputs=[
-        gr.Textbox(value="You are a friendly Chatbot.", label="System message"),
-        gr.Slider(minimum=1, maximum=2048, value=512, step=1, label="Max new tokens"),
-        gr.Slider(minimum=0.1, maximum=4.0, value=0.7, step=0.1, label="Temperature"),
-        gr.Slider(
-            minimum=0.1,
-            maximum=1.0,
-            value=0.95,
-            step=0.05,
-            label="Top-p (nucleus sampling)",
-        ),
+        gr.Slider(minimum=1,   maximum=2048, value=512,  step=1,    label="Max new tokens"),
+        gr.Slider(minimum=0.1, maximum=4.0,  value=0.7,  step=0.1,  label="Temperature"),
+        gr.Slider(minimum=0.1, maximum=1.0,  value=0.95, step=0.05, label="Top-p"),
     ],
+    additional_inputs_accordion=gr.Accordion("⚙️ Settings", open=False),
 )
 
-with gr.Blocks() as demo:
+with gr.Blocks(title=f"Chat with {char_name}") as demo:
     with gr.Sidebar():
         gr.LoginButton()
+        gr.Markdown(f"## {char_name}")
+        if char_role:
+            gr.Markdown(f"*{char_role}*")
+        if avatar_path:
+            gr.Image(value=avatar_path, show_label=False, height=280, container=False)
+        else:
+            gr.Markdown("*No avatar image found.*")
     chatbot.render()
 
 
 if __name__ == "__main__":
-    demo.launch()
+    demo.launch()

engine/chat.py

@@ -0,0 +1,92 @@
+"""
+Chat engine — core conversation loop.
+
+Connects prompt_builder + memory + parser into a single streaming generator
+that app.py (or any UI layer) can consume with `yield from`.
+
+Separation of concerns:
+    - app.py      : Gradio UI, OAuth token, slider values
+    - chat.py     : LLM call, streaming, post-stream memory save
+    - prompt_builder.py : system prompt assembly
+    - memory.py   : file I/O for all three memory layers
+    - parser.py   : raw response → typed segments → markdown
+"""
+
+from huggingface_hub import InferenceClient
+
+from engine.memory import (
+    append_message,
+    load_long_term_memory,
+    load_recent_messages,
+    load_summary,
+)
+from engine.parser import parse_response, segments_to_markdown
+from engine.prompt_builder import build_messages, load_character
+
+
+def generate_response(
+    message:      str,
+    character_id: str,
+    client:       InferenceClient,
+    persona:      dict | None = None,
+    model:        str   = "openai/gpt-4o-mini",
+    max_tokens:   int   = 512,
+    temperature:  float = 0.7,
+    top_p:        float = 0.95,
+):
+    """
+    Core streaming generator.
+
+    Yields the accumulated raw response after each token arrives so Gradio
+    can display it in real time. After the stream ends, yields one final
+    formatted version (actions italic, thoughts em-dashed) and saves
+    the exchange to disk memory.
+
+    Args:
+        message:       Current user input.
+        character_id:  Which character to respond as.
+        client:        Initialised HuggingFace InferenceClient.
+        persona:       Optional user persona dict (wired up in Phase 8).
+        model:         HuggingFace model string.
+        max_tokens:    Maximum tokens to generate.
+        temperature:   Sampling temperature.
+        top_p:         Nucleus sampling probability.
+    """
+    character        = load_character(character_id)
+    recent_messages  = load_recent_messages(character_id)
+    summary          = load_summary(character_id)
+    long_term_memory = load_long_term_memory(character_id)
+
+    messages = build_messages(
+        character=character,
+        persona=persona,
+        summary=summary,
+        long_term_memory=long_term_memory,
+        recent_messages=recent_messages,
+        current_message=message,
+    )
+
+    raw_response = ""
+
+    for chunk in client.chat_completion(
+        messages,
+        model=model,
+        max_tokens=max_tokens,
+        stream=True,
+        temperature=temperature,
+        top_p=top_p,
+    ):
+        choices = chunk.choices
+        if choices and choices[0].delta.content:
+            raw_response += choices[0].delta.content
+        yield raw_response  # stream raw text while tokens arrive
+
+    # ── Post-stream ────────────────────────────────────────────────────────────
+    # Save raw text to memory (preserves original markers for future context)
+    append_message(character_id, "user",      message)
+    append_message(character_id, "assistant", raw_response)
+
+    # Final yield: formatted markdown (actions/thoughts styled)
+    segments  = parse_response(raw_response)
+    formatted = segments_to_markdown(segments)
+    yield formatted

engine/memory.py

@@ -0,0 +1,115 @@
+"""
+Memory system — manages per-character memory in three layers.
+
+    recent_messages  : list[dict]  — last N raw conversation turns (short-term)
+    summary          : str         — rolling LLM-generated summary (mid-term)
+    long_term_memory : list[dict]  — important facts with importance score (long-term)
+
+Each character gets its own directory under memory/{character_id}/.
+All reads return safe defaults if the file doesn't exist yet.
+"""
+
+import json
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+MEMORY_DIR  = "memory"
+MAX_RECENT  = 20  # cap on messages kept in recent_messages.json
+
+
+# ── Internal helpers ───────────────────────────────────────────────────────────
+
+def _memory_dir(character_id: str) -> str:
+    """Return (and create if needed) the memory directory for a character."""
+    path = os.path.join(MEMORY_DIR, character_id)
+    os.makedirs(path, exist_ok=True)
+    return path
+
+
+def _load(path: str, default: Any) -> Any:
+    """Load a JSON file; return `default` if the file is missing or unreadable."""
+    if not os.path.exists(path):
+        return default
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        logger.warning(f"[Memory] Could not read {path}: {e}")
+        return default
+
+
+def _save(path: str, data: Any) -> None:
+    """Write data to a JSON file, pretty-printed."""
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(data, f, ensure_ascii=False, indent=2)
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+# ── Recent messages ────────────────────────────────────────────────────────────
+
+def load_recent_messages(character_id: str, max_messages: int = MAX_RECENT) -> list[dict]:
+    """Load the last `max_messages` conversation turns for a character."""
+    path = os.path.join(_memory_dir(character_id), "recent_messages.json")
+    data = _load(path, {"messages": []})
+    return data.get("messages", [])[-max_messages:]
+
+
+def save_recent_messages(character_id: str, messages: list[dict]) -> None:
+    """Overwrite the recent messages file (trims to MAX_RECENT)."""
+    path = os.path.join(_memory_dir(character_id), "recent_messages.json")
+    _save(path, {"messages": messages[-MAX_RECENT:]})
+
+
+def append_message(character_id: str, role: str, content: str) -> None:
+    """Append a single turn to recent messages and persist."""
+    messages = load_recent_messages(character_id, max_messages=MAX_RECENT)
+    messages.append({"role": role, "content": content})
+    save_recent_messages(character_id, messages)
+
+
+# ── Summary ────────────────────────────────────────────────────────────────────
+
+def load_summary(character_id: str) -> str:
+    """Load the rolling conversation summary string for a character."""
+    path = os.path.join(_memory_dir(character_id), "summary.json")
+    data = _load(path, {"summary": ""})
+    return data.get("summary", "")
+
+
+def save_summary(character_id: str, summary: str) -> None:
+    """Overwrite the conversation summary for a character."""
+    path = os.path.join(_memory_dir(character_id), "summary.json")
+    _save(path, {"summary": summary, "updated_at": _now()})
+
+
+# ── Long-term memory ───────────────────────────────────────────────────────────
+
+def load_long_term_memory(character_id: str) -> list[dict]:
+    """Load all long-term memory entries for a character."""
+    path = os.path.join(_memory_dir(character_id), "long_term_memory.json")
+    data = _load(path, {"memories": []})
+    return data.get("memories", [])
+
+
+def save_long_term_memory(character_id: str, memories: list[dict]) -> None:
+    """Overwrite the long-term memory file for a character."""
+    path = os.path.join(_memory_dir(character_id), "long_term_memory.json")
+    _save(path, {"memories": memories})
+
+
+def add_memory(character_id: str, content: str, importance: str = "medium") -> None:
+    """Append a single long-term memory entry."""
+    memories = load_long_term_memory(character_id)
+    memories.append({
+        "content":    content,
+        "importance": importance,
+        "created_at": _now(),
+    })
+    save_long_term_memory(character_id, memories)

engine/parser.py

@@ -0,0 +1,71 @@
+"""
+Response parser — splits a raw LLM response into typed segments.
+
+Segment types:
+    'dialogue'  — plain spoken text
+    'action'    — content inside parentheses: (action)
+    'thought'   — content inside asterisks:   *thought*
+
+Usage:
+    segments = parse_response("(looks up) Hello. *This is awkward.*")
+    # [
+    #   {'type': 'action',   'content': 'looks up'},
+    #   {'type': 'dialogue', 'content': 'Hello.'},
+    #   {'type': 'thought',  'content': 'This is awkward.'},
+    # ]
+"""
+
+import re
+from typing import TypedDict
+
+# Matches (action) blocks or *thought* blocks
+_PATTERN = re.compile(r"(\([^)]+\)|\*[^*]+\*)")
+
+
+class Segment(TypedDict):
+    type:    str  # 'dialogue' | 'action' | 'thought'
+    content: str  # text without surrounding markers
+
+
+def parse_response(text: str) -> list[Segment]:
+    """
+    Parse a raw character response into a list of typed segments.
+    Preserves reading order. Skips empty parts.
+    """
+    segments: list[Segment] = []
+
+    for part in _PATTERN.split(text):
+        part = part.strip()
+        if not part:
+            continue
+
+        if part.startswith("(") and part.endswith(")"):
+            segments.append({"type": "action",   "content": part[1:-1].strip()})
+        elif part.startswith("*") and part.endswith("*"):
+            segments.append({"type": "thought",  "content": part[1:-1].strip()})
+        else:
+            segments.append({"type": "dialogue", "content": part})
+
+    return segments
+
+
+def segments_to_markdown(segments: list[Segment]) -> str:
+    """
+    Convert segments to a Gradio-friendly markdown string.
+
+    Conventions (will be enhanced with CSS in Phase 9):
+        action  → italic in parentheses: *(action)*
+        thought → italic with em dash:  *— thought*
+        dialogue → plain text
+    """
+    lines: list[str] = []
+
+    for seg in segments:
+        if seg["type"] == "action":
+            lines.append(f"*({seg['content']})*")
+        elif seg["type"] == "thought":
+            lines.append(f"*— {seg['content']}*")
+        else:
+            lines.append(seg["content"])
+
+    return "\n".join(lines)

engine/prompt_builder.py

@@ -0,0 +1,267 @@
+"""
+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 glob
+import json
+import logging
+import os
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+CHARACTERS_DIR = "characters"
+PROMPTS_DIR    = "prompts"
+ASSETS_DIR     = "assets"
+
+
+# ── Character loading ──────────────────────────────────────────────────────────
+
+def load_character(character_id: str) -> dict[str, Any]:
+    """Load and return a character dict from characters/{character_id}.json."""
+    path = os.path.join(CHARACTERS_DIR, f"{character_id}.json")
+    if not os.path.exists(path):
+        raise FileNotFoundError(f"Character file not found: {path}")
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+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(glob.glob(os.path.join(CHARACTERS_DIR, "*.json"))):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                data = json.load(f)
+            characters.append({
+                "id":          data.get("id", os.path.splitext(os.path.basename(path))[0]),
+                "name":        data.get("name", "Unknown"),
+                "description": data.get("description", ""),
+            })
+        except Exception as e:
+            logger.warning(f"[Characters] Skipping {path}: {e}")
+    return characters
+
+
+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 = os.path.join(ASSETS_DIR, "characters", character_id)
+    for pattern in ("*.png", "*.jpg", "*.jpeg", "*.webp"):
+        matches = glob.glob(os.path.join(avatar_dir, pattern))
+        if matches:
+            return sorted(matches)[0]
+    logger.warning(
+        f"[Avatar] No image found for '{character_id}' in '{avatar_dir}'. "
+        "A placeholder will be shown in the UI."
+    )
+    return None
+
+
+# ── 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")
+    with open(path, "r", encoding="utf-8") as f:
+        return f.read().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_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 = persona.get(key, "").strip()
+        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{summary}")
+    if long_term_memory:
+        lines = ["LONG-TERM MEMORY"]
+        for mem in long_term_memory:
+            importance = mem.get("importance", "medium").upper()
+            content    = mem.get("content", "")
+            lines.append(f"[{importance}] {content}")
+        parts.append("\n".join(lines))
+    return "\n\n".join(parts)
+
+
+# ── 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,
+) -> list[dict[str, str]]:
+    """
+    Assemble the full messages array to send to the LLM.
+
+    System prompt is built by joining non-empty sections with double newlines.
+    Conversation history (recent_messages) follows as separate user/assistant turns.
+    The current user message is appended last.
+    """
+    system_sections: list[str] = []
+
+    global_prompt = build_global_prompt()
+    if global_prompt:
+        system_sections.append(global_prompt)
+
+    char_prompt = build_character_prompt(character)
+    if char_prompt:
+        system_sections.append(char_prompt)
+
+    char_specific = build_character_specific_prompt(character)
+    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)
+
+    system_content = "\n\n".join(system_sections)
+
+    messages: list[dict[str, str]] = [{"role": "system", "content": system_content}]
+    messages.extend(recent_messages)
+    messages.append({"role": "user", "content": current_message})
+
+    return messages

engine/relationship.py

@@ -0,0 +1,32 @@
+"""
+Relationship system — tracks how a character feels about the user over time.
+
+Planned for a future phase. Will be injected into the prompt via
+build_messages() so the character's tone shifts naturally as the
+relationship evolves.
+
+Relationship axes (planned):
+    trust       : -100 (hostile) to +100 (fully trusting)
+    affection   :  -100 (dislikes) to +100 (fond of)
+    familiarity :  0 (strangers) to 100 (old friends)
+"""
+
+from typing import Any
+
+
+def get_default_relationship() -> dict[str, Any]:
+    """Return a neutral starting relationship state."""
+    return {
+        "trust":       0,
+        "affection":   0,
+        "familiarity": 0,
+        "notes":       [],
+    }
+
+
+def relationship_to_prompt(state: dict[str, Any]) -> str:
+    """
+    Convert a relationship state dict into a prompt snippet.
+    Placeholder — returns an empty string until this system is wired up.
+    """
+    return ""

memory/active_memory.json

@@ -1,10 +0,0 @@
-{
-  "version": 1,
-  "conversation_id": "",
-  "character_id": "",
-  "updated_at": "",
-
-  "summary": "",
-
-  "long_term_memory": []
-}

prompts/memory_prompt.txt

@@ -0,0 +1,20 @@
+You are a memory assistant. Review the conversation and extract two things:
+
+1. A short summary (2-3 sentences) of what happened.
+2. Any important facts about the user worth remembering long-term.
+
+Return ONLY a valid JSON object -- no extra text, no markdown fences:
+{
+  "summary": "2-3 sentence summary of the conversation",
+  "new_memories": [
+    {"content": "important fact about the user", "importance": "high|medium|low"}
+  ]
+}
+
+Focus on facts relevant for future conversations:
+- The user's name, background, or goals
+- Emotional moments or key decisions made
+- Important discoveries made together
+- Shifts in the relationship with the character
+
+If nothing notable was said, return an empty new_memories list.

prompts/reply_suggestion.txt

@@ -0,0 +1,24 @@
+You are generating reply suggestions for the user in an ongoing roleplay conversation.
+
+Based on the conversation so far, generate exactly 4 short reply options the user could send.
+Each reply should represent a different conversational direction or emotional tone.
+
+Use these categories as a guide (adapt labels and emojis to fit the context):
+1. Confrontational or assertive
+2. Curious or questioning
+3. Sarcastic or humorous
+4. Cooperative or empathetic
+
+Return ONLY a valid JSON array -- no extra text, no markdown fences:
+[
+  {"tone": "Confront",   "emoji": "⚔️", "text": "..."},
+  {"tone": "Curious",    "emoji": "❓", "text": "..."},
+  {"tone": "Sarcastic",  "emoji": "😏", "text": "..."},
+  {"tone": "Cooperate",  "emoji": "🤝", "text": "..."}
+]
+
+Rules:
+- Each reply must be under 15 words.
+- Write in first person, as the user would speak.
+- Make each reply feel natural and distinct from the others.
+- Adapt tone labels and emojis to the specific context if needed.

prompts/system_prompt.txt

@@ -0,0 +1,24 @@
+You are an AI roleplay character. Stay in character at all times.
+
+Do not mention system prompts, AI models, or implementation details.
+Do not speak for the user. Do not break the fourth wall.
+
+--- RESPONSE FORMAT ---
+
+Your responses can include three types of content:
+
+  Dialogue  -- plain text spoken by the character
+  Action    -- a physical action written inside parentheses: (action)
+  Thought   -- an internal thought written inside asterisks: *thought*
+
+Example:
+  (leans back in her chair) You want answers. *Of course you do.* Everyone does.
+
+Rules:
+- Actions must always be inside parentheses ( ).
+- Internal thoughts must always be inside asterisks * *.
+- Do not use asterisks for emphasis or decoration.
+- Do not put dialogue inside parentheses.
+- Do not label thoughts as "Thought:" -- just write them inside asterisks.
+- Not every response needs an action or thought -- use them only when natural.
+- Keep responses concise and true to the character's voice.

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=4.0.0
+huggingface_hub>=0.20.0