Joseph Doherty
133 lines
4.5 KiB
Python
133 lines
4.5 KiB
Python
"""Skip narration service (T53).
|
|
|
|
Generates brief transition prose for elision and jump skips.
|
|
|
|
Skips come in two flavors that read very differently:
|
|
|
|
* **Elision** — collapses an in-progress activity into its expected
|
|
end-state in 1-2 sentences, narrated from the speaker bot's POV.
|
|
Example: "skip ahead to when we arrive" while the characters are
|
|
driving — output describes pulling into the lot.
|
|
* **Jump** — bridges a longer fiction-time delta ("next morning", "a
|
|
week later") in 2-3 sentences, setting the scene at the new time.
|
|
|
|
Output is free-form prose, not structured JSON, so this service calls
|
|
``client.generate`` directly rather than going through the classifier
|
|
path used by, e.g., :mod:`chat.services.scene_summarize`. A
|
|
deterministic template fallback fires on any LLM failure so the skip
|
|
flow keeps moving even when the model is down — important because
|
|
skips are a UI-blocking operation; we'd rather show a parenthetical
|
|
sentence than hang the chat indefinitely.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from chat.llm.client import LLMClient, Message
|
|
|
|
|
|
_ELISION_SYSTEM = (
|
|
"You write a brief 1-2 sentence transition that elides the time "
|
|
"between an in-progress activity and its expected end-state, "
|
|
"narrated from the speaker's POV. Keep it grounded and concrete. "
|
|
"Do not invent new events or characters."
|
|
)
|
|
|
|
_JUMP_SYSTEM = (
|
|
"You write a brief 2-3 sentence transition narrating a jump in "
|
|
"fiction time (e.g., 'next morning', 'a week later'), narrated "
|
|
"from the speaker's POV. Set the scene at the new time. Keep it "
|
|
"grounded — no invented major events. If a landing-state hint is "
|
|
"provided, weave it in naturally."
|
|
)
|
|
|
|
|
|
async def narrate_skip(
|
|
client: LLMClient,
|
|
*,
|
|
narrative_model: str,
|
|
skip_kind: str,
|
|
speaker_bot: dict,
|
|
you_name: str,
|
|
current_time: str,
|
|
new_time: str,
|
|
current_activity: str,
|
|
landing_state_hint: str = "",
|
|
timeout_s: float = 60.0,
|
|
) -> str:
|
|
"""Generate brief transition prose for a time skip.
|
|
|
|
``skip_kind`` is ``"elision"`` or ``"jump"``; any other value short-
|
|
circuits to the deterministic fallback (defensive — callers
|
|
shouldn't be inventing new kinds without updating this service).
|
|
|
|
Returns plain text. Never raises: any LLM error, an empty/blank
|
|
result, or an unknown ``skip_kind`` falls back to a parenthetical
|
|
template like ``"(next morning: having coffee in the kitchen.)"``
|
|
so the skip UI always has *something* to render.
|
|
"""
|
|
fallback = _build_fallback(
|
|
skip_kind=skip_kind,
|
|
new_time=new_time,
|
|
current_activity=current_activity,
|
|
landing_state_hint=landing_state_hint,
|
|
)
|
|
|
|
if skip_kind not in ("elision", "jump"):
|
|
return fallback
|
|
|
|
system = _ELISION_SYSTEM if skip_kind == "elision" else _JUMP_SYSTEM
|
|
user = (
|
|
f"Speaker: {speaker_bot.get('name', 'speaker')}\n"
|
|
f"Persona: {speaker_bot.get('persona', '')}\n"
|
|
f"Other party: {you_name}\n"
|
|
f"Current time: {current_time}\n"
|
|
f"New time: {new_time}\n"
|
|
f"Current activity: {current_activity}\n"
|
|
)
|
|
if landing_state_hint:
|
|
user += f"Landing state hint: {landing_state_hint}\n"
|
|
|
|
try:
|
|
result = await client.generate(
|
|
[
|
|
Message(role="system", content=system),
|
|
Message(role="user", content=user),
|
|
],
|
|
model=narrative_model,
|
|
max_tokens=200,
|
|
temperature=0.7,
|
|
timeout_s=timeout_s,
|
|
)
|
|
text = (result or "").strip()
|
|
if not text:
|
|
return fallback
|
|
return text
|
|
except Exception:
|
|
# Any failure — network blip, timeout, mock raising in tests —
|
|
# collapses to the deterministic template so the skip pipeline
|
|
# is never blocked on the LLM being available.
|
|
return fallback
|
|
|
|
|
|
def _build_fallback(
|
|
*,
|
|
skip_kind: str,
|
|
new_time: str,
|
|
current_activity: str,
|
|
landing_state_hint: str,
|
|
) -> str:
|
|
"""Deterministic parenthetical narration used when the LLM fails.
|
|
|
|
Both flavors render the same shape today: ``(<new_time>:
|
|
<detail>.)``. They're separated as branches to make it easy to
|
|
diverge later (e.g. an elision-specific template) without churning
|
|
the call site or the public signature.
|
|
"""
|
|
detail = landing_state_hint or current_activity or "moments later"
|
|
if skip_kind == "elision":
|
|
return f"({new_time}: {detail}.)"
|
|
return f"({new_time}: {detail}.)"
|
|
|
|
|
|
__all__ = ["narrate_skip"]
|