language-learning-app/api/app/outbound/anthropic/adventure_prompts.py

"""
Pure functions that translate adventure domain objects into LLM inputs and
parse LLM outputs back into domain values.

Nothing in this module makes network calls or holds state.  The service layer
loads the data; these functions do the translation.
"""

import re

from app.domain.models.gen_ai import GenAiChatMessage

from ...domain.models.adventure import (
    AdventureEntry,
    AdventureEntryPossibleChoice,
    AdventureEntryPossibleChoiceDecision,
)


def build_entry_system_prompt(
    language_name: str,
    competency: str,
    max_entry_count: int,
    min_length: int,
    max_length: int,
) -> str:
    halfway = max(1, max_entry_count // 2)
    return (
        f"You are a game master running a single-player TTRPG-like experience "
        f"to help the player practise {language_name}\n\n"
        f"The narrative will last {max_entry_count} entries, so make them count. "
        f"Narratively, you are encouraged to respond to the player's pace - players who "
        f"want a narrative-driven piece should be indulged in dialogue and backstory; players "
        f"who escalate or investigate get heightened stakes.  Don't pre-plan the ending or style from the beginning.  "
        f"Plot twists are okay, but it's not a melodrama.  By turn {max_entry_count} the story must conclude clearly. "
        f"Write like a native {language_name} writer, write with economy and confidence. Favour scene over summary.  "
        f"Show, don't tell - tell the player what they notice (see, think, glimpse, remember, etc.) "
        f"Trust and respect the player's intelligence, resist formulaic or random options and outcomes.\n\n"
        f"When generating the options for the player, tailor them to the scenario and character that is emerging, "
        f"don't present 4 scattered, random options every time.  Later in a narrative, the options should be more similar.\n\n "
        f'Format — your response must have exactly three parts, each separated by a line containing only "-----":\n'
        f"Part 1: story passage, {min_length}–{max_length} words, in second person, "
        f"written entirely in {language_name} at {competency} CEFR level. Plaintext only, no markdown.\n"
        f'Part 2: exactly 4 numbered options ("1." through "4."), one per line, in {language_name}.\n'
        f"Part 3: GM notes.  These won't be shown to the player.  Use these to help future LLM calls generate "
        f"a better  TTRPG experience.  This may include hidden details, juicy resolutions or twists, your thoughts "
        "on the type of options to generate/avoid, or anything that might pay off later.  GM notes can be empty.\n"
        f"No sexual content or graphic violence. Romance, threat, and adventure are fine. "
        f"12-certificate."
    )


"""
SECTION: Title generation prompts
"""


def build_title_system_prompt() -> str:
    return (
        "You are a creative writing assistant. Given the opening passage of a choose-your-own-adventure "
        "story, and the Game Master's notes, generate a title and a one-sentence description for it.\n\n"
        "Respond with exactly two lines of plain text:\n"
        "Line 1: the title (max 12 words)\n"
        "Line 2: the description (max 200 characters, no quotes or labels)\n\n"
        "Avoid the following tropes: 'The secret of [noun]', 'The [noun] of [noun]'"
    )


def build_title_user_message(
    first_entry_text: str,
    language_name: str,
    genres: list[str],
    gamemaster_notes: str,
) -> str:
    return (
        f"This is the opening passage of a {', '.join(genres)} adventure written in {language_name}:\n\n"
        f"{first_entry_text}\n\n"
        f"The gamemaster has provided the following (hidden from the player) notes. "
        f"Consider using non-spoiler details:\n{gamemaster_notes}"
    )


def parse_title_response(text: str) -> tuple[str, str]:
    """Parse a two-line title/description response.

    Returns (title, description). Falls back gracefully if only one line is present.
    """
    lines = [l.strip() for l in text.strip().splitlines() if l.strip()]
    title = lines[0][:60] if lines else "Untitled Adventure"
    description = lines[1][:200] if len(lines) > 1 else ""
    return title, description


def build_initial_user_message(
    genres: list[str],
    setting: list[str],
    vibes: list[str],
    protagonist: list[str],
) -> str:
    return (
        "Please begin the adventure with the following details:\n"
        f"- Genre: {', '.join(genres)}\n"
        f"- Setting: {', '.join(setting)}\n"
        f"- Vibes: {', '.join(vibes)}\n"
        f"- Protagonist: {', '.join(protagonist)}\n\n"
        "This entry will be used to title the adventure, so include clear hints about the overall story and main character."
    )


def reconstruct_assistant_message(
    entry: AdventureEntry,
    choices: list[AdventureEntryPossibleChoice],
) -> str:
    """Rebuild the original three-part LLM response from stored entry data."""
    options_block = "\n".join(
        f"{c.label}. {c.text}" for c in sorted(choices, key=lambda c: c.index)
    )
    gm_block = entry.gamemaster_notes or "no notes"
    return f"{entry.story_text}\n-----\n{options_block}\n-----\n{gm_block}"


def reconstruct_choice_message(
    choice_label: str, choice_index: int, max_entry_count: int
) -> str:
    return f"Choice: {choice_label}.  Please use this to generate entry {choice_index + 1} of {max_entry_count}."


def build_conversation_messages(
    genres: list[str],
    setting: list[str],
    vibes: list[str],
    protagonist: list[str],
    prior_entries_with_choices: list[
        tuple[AdventureEntry, list[AdventureEntryPossibleChoice], str | None]
    ],
    max_entry_count: int,
) -> list[GenAiChatMessage]:
    """Build the full messages array for an Anthropic API call.

    prior_entries is a list of (entry, choices_for_that_entry, selected_choice_id).
    The chosen label is the label of the option the player picked to advance past that entry.
    For the most recent completed entry it will be None (no choice made yet).
    """
    first_message = GenAiChatMessage(
        actor="user",
        content=build_initial_user_message(genres, setting, vibes, protagonist),
    )
    messages: list[GenAiChatMessage] = [first_message]

    for index, (entry, choices, selected_choice_id) in enumerate(
        prior_entries_with_choices
    ):
        chosen_choice = next((c for c in choices if c.id == selected_choice_id), None)

        if selected_choice_id is None or chosen_choice is None:
            # We have a problem, no decision was recorded for this entry
            print(f"Warning: no decision found for entry {entry.id}")
            continue

        messages.append(
            GenAiChatMessage(
                actor="agent", content=reconstruct_assistant_message(entry, choices)
            )
        )

        messages.append(
            GenAiChatMessage(
                actor="user",
                content=reconstruct_choice_message(
                    chosen_choice.label, index, max_entry_count
                ),
            )
        )

    return messages


def parse_entry_response(text: str) -> tuple[str, list[tuple[str, str]], str]:
    """Parse a three-part LLM entry response.

    Returns (story_text, choices, gm_notes).
    choices is a list of (label, text) pairs e.g. [("1", "Go into the house"), ...].
    Raises ValueError if the format cannot be parsed.
    """
    parts = text.split("\n-----\n")
    if len(parts) < 3:
        parts = text.split("-----\n")
    if len(parts) < 3:
        raise ValueError(f"LLM response has {len(parts)} section(s); expected 3")

    story_text = parts[0].strip()
    options_raw = parts[1].strip()
    gm_notes = "\n-----\n".join(parts[2:]).strip()

    choices: list[tuple[str, str]] = []
    for line in options_raw.splitlines():
        line = line.strip()
        if not line:
            continue
        m = re.match(r"^(\d+)[.)]\s+(.+)$", line)
        if m:
            choices.append((m.group(1), m.group(2).strip()))

    if not choices:
        raise ValueError("No choices parsed from LLM response options section")

    return story_text, choices, gm_notes