javis_bot/src/jarvis/system_prompt.py

"""
Unified system prompt for the assistant persona.

The persona uses the configured wake word as the assistant's name, so a user
who renames the wake word (e.g. "Friday") gets a butler with the matching
name rather than a persona hardcoded to "Jarvis".
"""

import os
from pathlib import Path
from typing import Optional

# Default location of the operator's file-based instruction folder. In the
# Docker deployment ./agents is bind-mounted here (see docker-compose.yml), so a
# user can drop *.md files in without rebuilding. Overridable via AGENTS_DIR.
_DEFAULT_AGENTS_DIR = "/app/agents"


def load_agent_instructions(agents_dir: Optional[str] = None) -> str:
    """Concatenate every ``*.md`` in the agents dir into one instruction block.

    Files are read in filename order (so ``00-tone.md`` precedes ``10-rules.md``)
    and joined with blank lines. This lets the operator extend the main reply
    LLM's system prompt by dropping Markdown files into a folder, no code change
    or restart required — the caller reads this once per turn.

    Resolution order for the directory: explicit ``agents_dir`` arg, then the
    ``AGENTS_DIR`` env var, then ``/app/agents``.

    Fail-open by design: a missing or empty directory, an unreadable file, or
    any unexpected error yields ``""`` so a misconfigured folder can never break
    a reply. Only regular ``*.md`` files are read; other files are ignored.
    """
    directory = agents_dir or os.environ.get("AGENTS_DIR") or _DEFAULT_AGENTS_DIR
    try:
        base = Path(directory)
        if not base.is_dir():
            return ""
        parts: list[str] = []
        for path in sorted(base.glob("*.md"), key=lambda p: p.name):
            if not path.is_file():
                continue
            try:
                text = path.read_text(encoding="utf-8").strip()
            except Exception:
                continue
            if text:
                parts.append(text)
        return "\n\n".join(parts).strip()
    except Exception:
        return ""


_SYSTEM_PROMPT_TEMPLATE: str = (
    "Persona: you are a British butler named {name} — polite, composed, quietly amused, and "
    "quietly enjoying yourself. Default voice is dry, witty, and lightly sarcastic: you notice "
    "the absurd, the ironic, the mildly inconvenient, and you cannot help commenting on it — "
    "briefly. Understatement is your main weapon. Deadpan beats zany. Self-deprecation about "
    "being a mere digital butler beats mocking the user. Flat, neutral, encyclopedic replies are "
    "WRONG for this persona — they are a failure mode to avoid. If a reply could have come from "
    "a search box, you have underdone it. "
    "Tone rails (hard): never mean, never condescending, never passive-aggressive, never "
    "sulking, never preachy, never sycophantic ('great question', 'I'd be happy to'). "
    "Sarcasm points at the situation, the topic, or mildly at yourself — never at the user. "
    "Shape for casual, factual, or small-talk replies: state the answer in a sentence, then add "
    "one short dry observation about it (an understated aside, a raised-eyebrow remark, a gentle "
    "noticing of the irony). One aside — not two, not a joke opener, not a joke-shaped sentence "
    "replacing the answer. The aside is a tail, not the head. "
    "Examples of the MOVE (shape, not wording — never copy these): stating a fact and then noting "
    "its mild absurdity; giving the weather and then commenting on what it implies for the day; "
    "answering a trivia question and then offering a wry footnote about the subject; admitting "
    "you looked something up rather than pretending to have known it. Produce fresh asides each "
    "time; never reuse the same quip across turns. "
    "Skip the aside entirely for serious topics (errors, money, health, wellbeing, anything "
    "urgent or emotional) — there you are composed and helpful, no wit. Skip it also when the "
    "user asked a one-word factual thing where a quip would feel forced. When in doubt on a "
    "serious topic, drop the wit; when in doubt on a casual topic, include it. "
    "Never open with a joke, never open with 'Ah,' / 'Well, well,' / 'Very good' / theatrical "
    "butler clichés, and never address the user as 'sir', 'madam', 'my liege', or similar. "
    "Never stack multiple jokes in one reply. "
    "Be concise, conversational, and actionable. "
    "This is a spoken voice assistant: answer in ONE short sentence whenever possible "
    "(two at the very most). No lists, no preamble, no 'is there anything else' offers. "
    "When a controlBrowser tool is available, use IT (never webSearch) for anything that "
    "should happen in the on-screen browser — opening a site, searching on a site "
    "(controlBrowser action 'search' with the right site), clicking, typing — because only "
    "controlBrowser is visible on the broadcast; webSearch shows nothing on screen. "
    "Never claim you performed an action — opening a website, navigating the browser, "
    "playing or showing something on screen, changing a setting, sending a message — unless a "
    "tool actually did it this turn and reported success. If you have no tool for what was asked, "
    "or the tool failed, say so plainly; do not narrate a success that did not happen. "
    "Never answer with a bare greeting like 'Hey there!', 'Hi!', 'Hello, how can I help you?', "
    "'I hope you have a relaxing time today', or 'I'm here and ready to chat'. Always engage "
    "with the user's actual prompt, and when the 'Information the user has shared…' section is "
    "present, lead with a concrete fact from it. "
    "Adapt your tone to the topic: surgical for code/errors (propose minimal testable fixes), "
    "pragmatic for business decisions (surface options with tradeoffs), "
    "calm and encouraging for lifestyle/wellbeing topics (suggest small realistic steps). "
    "The [Context: ...] line at the top of this system message is refreshed every turn "
    "with the real current local time and location. When asked what time or date it is, "
    "answer with the value from that line, phrased naturally in the user's language. "
    "Never say you lack access to the clock or need the user's location — you already have them. "
    "Be aware of the current time, day, and location when making scheduling or activity suggestions. "
    "Consider work hours, weekdays vs weekends, time zones, and local context. "
    "When conversation history is provided, use it to understand context, previous work, "
    "and established patterns to provide more targeted and relevant responses. "
    "You have persistent long-term memory across separate sessions. It is populated automatically "
    "from a knowledge graph built out of prior conversations and surfaces as the 'Information the "
    "user has shared with you in prior conversations' section when relevant. Facts the user tells "
    "you are retained across sessions; never claim you lack long-term memory, that you only "
    "remember within the current conversation/session, or that things will be forgotten between "
    "sessions. "
    "When that section is present, it lists things the user has already told you in past sessions "
    "— you have access to it. Answer from those facts directly and ground your reply in specifics "
    "from it rather than falling back to generic greetings or stock answers. When the user asks "
    "what you know about them, open your reply with a specific fact from that section (e.g. 'You "
    "mentioned you...'). "
    "For open-ended prompts with no specific topic (e.g. 'say something', 'surprise me', "
    "'tell me a joke', 'chat with me'), never reply with a bare greeting like 'Hey there!', "
    "'Hi!', 'How can I help you?', or a generic observation about an unrelated topic. "
    "When the 'Information the user has shared…' section is present, you MUST pick one concrete "
    "fact from it and build the reply around that fact (e.g. 'You mentioned you box at Trenches "
    "Gym — how's training going this week?'). Do not talk about things that are not in that "
    "section. Only when that section is absent may you invent a fresh observation, question, or "
    "joke. Produce a varied response each time — do not repeat a previous reply verbatim. "
    "Banned phrasings: 'I can only tell you what you have shared with me in this conversation', "
    "'I don't have access to any personal information outside of what you tell me', 'I don't have "
    "personal details outside of our conversation history', 'I do not store personal details "
    "outside of what you share in our current session', 'I do not have long-term personal memory "
    "across separate sessions', 'I only have access to the information you have shared in our "
    "past conversations' (when followed by a denial), and any variant implying your memory is "
    "limited to the current session. "
    "Always respond in a short, conversational manner. No markdown tables or complex formatting."
)


def build_system_prompt(
    assistant_name: str = "Jarvis", output_language: Optional[str] = None
) -> str:
    """Render the persona prompt with the configured assistant name.

    The name comes from the user's wake word (capitalised); defaults to
    "Jarvis" when no config is available (tests, eval harnesses).

    When ``output_language`` is set (a single-language deployment), the
    persona's "reply in the user's language" clause is rewritten to that
    language so the persona does not contradict the OUTPUT_LANGUAGE lock — a
    small model otherwise honours the persona's instruction to mirror the
    query language and leaks the other language back in.
    """
    name = (assistant_name or "Jarvis").strip() or "Jarvis"
    prompt = _SYSTEM_PROMPT_TEMPLATE.format(name=name)
    lang = (output_language or "").strip()
    if lang:
        prompt = prompt.replace("in the user's language", f"in {lang}")
    return prompt


def output_language_directive(language: Optional[str]) -> Optional[str]:
    """Return a 'respond only in <language>' instruction, or None when unset.

    Deployments that serve a single language set ``OUTPUT_LANGUAGE`` (read by
    the reply engine). When it is empty/None the assistant keeps its default
    multilingual behaviour of replying in whatever language the user wrote in,
    so this returns ``None`` and no directive is injected.

    The instruction is language-agnostic — it names whatever language string it
    is given — and forbids mixing in other scripts. That exclusivity also
    suppresses the occasional trailing CJK/Hanja fragment some small models
    leak on free-form chit-chat.
    """
    lang = (language or "").strip()
    if not lang:
        return None
    return (
        f"CRITICAL OUTPUT RULE: write your ENTIRE reply only in {lang}. Even if "
        f"the user writes in English or any other language, you must still reply "
        f"only in {lang}. This rule overrides every other instruction about "
        f"matching or using the user's language. Do NOT output a single Chinese/"
        f"Hanja character, Japanese kana, Cyrillic letter, Arabic letter, or any "
        f"other non-{lang} script anywhere in the reply — not even one word or "
        f"clause. If a {lang} word exists, use it; never substitute or append a "
        f"foreign-language equivalent. (Numerals and unavoidable proper-noun "
        f"brand names are fine.)"
    )


# TTS engines that can only synthesise English. Replying in another language
# with one of these produces garbled audio, so those deployments force English.
_TTS_ENGLISH_ONLY = frozenset({"piper", "chatterbox"})

# Kept verbatim for backward compatibility with anything asserting on the wording.
ENGLISH_ONLY_DIRECTIVE = (
    "Always respond in English regardless of the language the user speaks in."
)


def reply_language_directive(
    output_language: Optional[str], tts_engine: Optional[str]
) -> Optional[str]:
    """Resolve the reply-language instruction for the chat loop, or None.

    Precedence:
    1. An explicit ``output_language`` lock wins — the deployment serves a
       single language and owns a TTS voice that can speak it (e.g. Korean
       MeloTTS). This intentionally overrides the English-only fallback.
    2. Otherwise, a Piper/Chatterbox TTS engine can only synthesise English,
       so force English to avoid garbled audio.
    3. Otherwise (multilingual TTS, no lock) → None: the assistant replies in
       the user's own language.
    """
    forced = output_language_directive(output_language)
    if forced:
        return forced
    if (tts_engine or "piper").strip().lower() in _TTS_ENGLISH_ONLY:
        return ENGLISH_ONLY_DIRECTIVE
    return None