chore(reformat): reformat existing code with ruff.

app.py

@@ -15,6 +15,19 @@ Run modes
 
 from __future__ import annotations
 
+# ── Compatibility shim: must run BEFORE gradio is imported ──────────────────
+# Gradio 6.15.2 calls spaces.gradio_auto_wrap() in block_function.py, but the
+# spaces==0.50.4 package injected by HF's ZeroGPU infrastructure does not have
+# that attribute yet. A no-op is safe: every GPU endpoint already has @spaces.GPU
+# applied manually below, so ZeroGPU allocation is still correct.
+try:
+    import spaces as _spaces
+
+    if not hasattr(_spaces, "gradio_auto_wrap"):
+        _spaces.gradio_auto_wrap = lambda fn: fn
+except ImportError:
+    pass
+
 # ── Mode selection: must run BEFORE any visualnovel import ──────────────────
 # config.py reads os.getenv() at import time via load_dotenv(), so we must
 # set the env vars first.

modal_app.py

@@ -41,12 +41,12 @@ painter_image = (
         "diffusers==0.35.1",
         "transformers==4.47.1",
         "accelerate==1.8.1",
-        "peft",        # required by diffusers load_lora_weights / fuse_lora
+        "peft",  # required by diffusers load_lora_weights / fuse_lora
         "safetensors",
         "Pillow",
         "huggingface_hub",
-        "rembg",       # background removal for sprites
-        "onnxruntime", # rembg runtime dep
+        "rembg",  # background removal for sprites
+        "onnxruntime",  # rembg runtime dep
     )
 )
 
@@ -69,7 +69,7 @@ app = modal.App("vn-app")
 GGUF_REPO = "Qwen/Qwen3-14B-GGUF"
 GGUF_FILE = "Qwen3-14B-Q8_0.gguf"
 # Painter: SDXL-base-1.0 + ByteDance Lightning LoRA (matches local SdxlLightningPainter)
-SDXL_BASE_REPO  = "stabilityai/stable-diffusion-xl-base-1.0"
+SDXL_BASE_REPO = "stabilityai/stable-diffusion-xl-base-1.0"
 SDXL_BASE_LOCAL = "sdxl-base"
 LIGHTNING_LORA_REPO = "ByteDance/SDXL-Lightning"
 LIGHTNING_LORA_FILE = "sdxl_lightning_4step_lora.safetensors"
@@ -243,6 +243,7 @@ class ModalPainterBackend:
 
         if remove_bg:
             from rembg import remove  # noqa: PLC0415
+
             img = remove(img)  # returns RGBA PIL image
 
         buf = io.BytesIO()

visualnovel/config.py

@@ -75,7 +75,7 @@ LLM_GGUF_FILE = os.getenv("VN_LLM_GGUF_FILE", "Qwen3-14B-Q4_K_M.gguf")
 
 # Defaults are backend-aware so the app works without an explicit .env override.
 _lightning_model = "stabilityai/stable-diffusion-xl-base-1.0"
-_lightning_lora  = "ByteDance/SDXL-Lightning::sdxl_lightning_4step_lora.safetensors"
+_lightning_lora = "ByteDance/SDXL-Lightning::sdxl_lightning_4step_lora.safetensors"
 IMAGE_MODEL = os.getenv(
     "VN_IMAGE_MODEL",
     _lightning_model if IMAGE_BACKEND == "lightning" else "stabilityai/sdxl-turbo",
@@ -98,7 +98,7 @@ TTS_BACKEND = os.getenv("VN_TTS_BACKEND", "mock")  # mock | kokoro
 CONTEXT_TOKEN_BUDGET = int(os.getenv("VN_CTX_BUDGET", "3500"))  # the "Thousand Token Wood"
 RECENT_TURNS_K = int(os.getenv("VN_RECENT_K", "6"))
 COMPACT_EVERY = int(os.getenv("VN_COMPACT_EVERY", "8"))  # also compacts when over budget
-IMAGE_SIZE  = int(os.getenv("VN_IMAGE_SIZE",  "768"))
+IMAGE_SIZE = int(os.getenv("VN_IMAGE_SIZE", "768"))
 _default_steps = "4" if IMAGE_BACKEND == "lightning" else "2"
 IMAGE_STEPS = int(os.getenv("VN_IMAGE_STEPS", _default_steps))
 # Backdrops use a non-zero guidance so the negative prompt (no people) is actually applied.

visualnovel/llm.py

@@ -23,7 +23,12 @@ from typing import Any, Protocol
 
 def _safe_print(msg: str) -> None:
     """Print to stdout, replacing unencodable chars (cp1252 on Windows terminals)."""
-    print(msg.encode(sys.stdout.encoding or "utf-8", errors="replace").decode(sys.stdout.encoding or "utf-8", errors="replace"))
+    print(
+        msg.encode(sys.stdout.encoding or "utf-8", errors="replace").decode(
+            sys.stdout.encoding or "utf-8", errors="replace"
+        )
+    )
+
 
 from . import config
 

visualnovel/memory.py

@@ -32,35 +32,37 @@ def assemble_context(state: GameState, player_input: str) -> str:
         if cid not in state.scene.present
     ]
     if off_stage:
-        parts.append("KNOWN BUT OFF STAGE (can return — use their existing id):\n" + "\n".join(off_stage))
+        parts.append(
+            "KNOWN BUT OFF STAGE (can return — use their existing id):\n" + "\n".join(off_stage)
+        )
 
     # ── Ending milestone hints — injected when a character hits ±100 ──────────
     for ch in state.characters.values():
         if ch.relationship >= 100 and ch.id in state.scene.present:
             parts.append(
                 f"*** ROMANCE PEAK: {ch.name}'s affection is at MAX (100/100). ***\n"
-                f"This turn MUST be their heartfelt confession. Emit ending(kind=\"warm\") "
-                f"with a poetic 2-4 sentence epilogue. Also emit set_music=\"romantic\"."
+                f'This turn MUST be their heartfelt confession. Emit ending(kind="warm") '
+                f'with a poetic 2-4 sentence epilogue. Also emit set_music="romantic".'
             )
         elif ch.relationship <= -100 and ch.id in state.scene.present:
             parts.append(
                 f"*** RELATIONSHIP BROKEN: {ch.name} is at MIN (-100/100). ***\n"
-                f"They storm off with a final cutting line. MUST emit exit_character=\"{ch.id}\". "
-                f"If the stage becomes empty after this, also emit ending(kind=\"defeat\") "
-                f"with a dark 2-4 sentence epilogue. Emit set_music=\"sad\"."
+                f'They storm off with a final cutting line. MUST emit exit_character="{ch.id}". '
+                f'If the stage becomes empty after this, also emit ending(kind="defeat") '
+                f'with a dark 2-4 sentence epilogue. Emit set_music="sad".'
             )
     # If scene already empty and not yet ended — nudge for defeat
     if not state.scene.present and state.beat != "ended" and state.characters:
         parts.append(
             "*** THE STAGE IS EMPTY — the wanderer is completely alone. ***\n"
-            "Emit ending(kind=\"defeat\") with a melancholic epilogue. Emit set_music=\"sad\"."
+            'Emit ending(kind="defeat") with a melancholic epilogue. Emit set_music="sad".'
         )
 
     # Surface the current music track prominently so the LLM doesn't switch it needlessly.
     current_music = state.flags.get("current_music")
     if current_music:
         parts.append(
-            f"CURRENT BGM: \"{current_music}\" — leave set_music null unless a MAJOR tonal "
+            f'CURRENT BGM: "{current_music}" — leave set_music null unless a MAJOR tonal '
             f"shift justifies a change (max once every 6-8 turns)."
         )
 

visualnovel/orchestrator.py

@@ -106,8 +106,11 @@ def init_world(llm: LLMBackend, setup: SetupForm) -> tuple[GameState, DirectorOu
 #  direct_turn
 # --------------------------------------------------------------------------- #
 def direct_turn(
-    llm: LLMBackend, state: GameState, player_input: str,
-    action: str = "talk", target: str = "",
+    llm: LLMBackend,
+    state: GameState,
+    player_input: str,
+    action: str = "talk",
+    target: str = "",
 ) -> DirectorOutput:
     if config.USE_MOCK:
         return _mock_turn(state, player_input)

visualnovel/painter.py

@@ -61,9 +61,9 @@ class Painter(Protocol):
 # fixed prefix + suffix stay within budget.  Rough budgets per prompt:
 #   backdrop : 15 (prefix) + 18 (desc) + 5 (mood) + 12 (style) + 2 (suffix) ≈ 52
 #   sprite   : 12 (prefix) + 10 (style) + 20 (appearance) + 5 (mood+suffix)  ≈ 47
-_DESC_WORDS  = 18   # scene description budget
-_STYLE_WORDS = 12   # style_guide budget in prompts
-_APP_WORDS   = 20   # character appearance budget
+_DESC_WORDS = 18  # scene description budget
+_STYLE_WORDS = 12  # style_guide budget in prompts
+_APP_WORDS = 20  # character appearance budget
 
 
 def _w(text: str, n: int) -> str:
@@ -81,7 +81,7 @@ def _backdrop_style(style_guide: str) -> str:
 
 def backdrop_prompt(state: GameState) -> str:
     style = _backdrop_style(state.style_guide)
-    desc  = _w(state.scene.description, _DESC_WORDS)
+    desc = _w(state.scene.description, _DESC_WORDS)
     return (
         f"background art, empty scenic environment, wide establishing shot, no humans, "
         f"uninhabited location, {desc}, {state.scene.mood} atmosphere, "
@@ -91,7 +91,7 @@ def backdrop_prompt(state: GameState) -> str:
 
 def sprite_prompt(state: GameState, ch: Character) -> str:
     style = _w(state.style_guide, _STYLE_WORDS)
-    app   = _w(ch.appearance, _APP_WORDS)
+    app = _w(ch.appearance, _APP_WORDS)
     return (
         f"vtuber character design, solo, single character, full-body, centered, "
         f"{style}, {app}, {ch.mood} expression, "
@@ -122,7 +122,10 @@ class PainterBase:
     def backdrop(self, state: GameState) -> Path:
         prompt = backdrop_prompt(state)
         return self._cached(
-            kind="bg", key=state.scene.id, prompt=prompt, seed=state.scene.backdrop_seed,
+            kind="bg",
+            key=state.scene.id,
+            prompt=prompt,
+            seed=state.scene.backdrop_seed,
             negative_prompt=_BACKDROP_NEGATIVE,
             guidance_scale=config.BACKDROP_GUIDANCE,
         )
@@ -130,7 +133,10 @@ class PainterBase:
     def sprite(self, state: GameState, ch: Character) -> Path:
         prompt = sprite_prompt(state, ch)
         return self._cached(
-            kind="sprite", key=f"{ch.id}.{ch.mood}", prompt=prompt, seed=ch.sprite_seed,
+            kind="sprite",
+            key=f"{ch.id}.{ch.mood}",
+            prompt=prompt,
+            seed=ch.sprite_seed,
             negative_prompt=_SPRITE_NEGATIVE,
         )
 
@@ -138,35 +144,54 @@ class PainterBase:
         """Generate (and cache) a special ending illustration based on the ending kind."""
         style = _backdrop_style(state.style_guide)
         _ENDING_DESCS: dict[str, tuple[str, str]] = {
-            "warm":        ("cherry blossom park at golden sunset, petals falling softly, "
-                            "empty bench under blooming trees, warm amber light filtering through branches",
-                            "romantic warm"),
-            "bittersweet": ("misty autumn street at twilight, fallen leaves on cobblestones, "
-                            "distant lamplight, empty path fading into soft fog",
-                            "melancholic gentle"),
-            "strange":     ("surreal moonlit garden, glowing silver motes drifting upward, "
-                            "impossible geometry, dreamlike luminous plants",
-                            "mysterious ethereal"),
-            "defeat":      ("rain-soaked empty park bench at night, fallen leaves in puddles, "
-                            "single dim lamppost, deserted street receding into darkness",
-                            "desolate cold"),
+            "warm": (
+                "cherry blossom park at golden sunset, petals falling softly, "
+                "empty bench under blooming trees, warm amber light filtering through branches",
+                "romantic warm",
+            ),
+            "bittersweet": (
+                "misty autumn street at twilight, fallen leaves on cobblestones, "
+                "distant lamplight, empty path fading into soft fog",
+                "melancholic gentle",
+            ),
+            "strange": (
+                "surreal moonlit garden, glowing silver motes drifting upward, "
+                "impossible geometry, dreamlike luminous plants",
+                "mysterious ethereal",
+            ),
+            "defeat": (
+                "rain-soaked empty park bench at night, fallen leaves in puddles, "
+                "single dim lamppost, deserted street receding into darkness",
+                "desolate cold",
+            ),
         }
         desc, mood = _ENDING_DESCS.get(kind, _ENDING_DESCS["warm"])
         prompt = (
             f"background art, empty scenic environment, wide establishing shot, no humans, "
             f"uninhabited location, {desc}, {mood} atmosphere, {style}, no text"
         )
-        seed = (state.seed * 1234567 + sum(ord(c) for c in kind)) % (2 ** 31)
+        seed = (state.seed * 1234567 + sum(ord(c) for c in kind)) % (2**31)
         return self._cached(
-            kind="ending", key=kind, prompt=prompt, seed=seed,
+            kind="ending",
+            key=kind,
+            prompt=prompt,
+            seed=seed,
             negative_prompt=_BACKDROP_NEGATIVE,
             guidance_scale=config.BACKDROP_GUIDANCE,
         )
 
     # -- internals --
-    def _cached(self, *, kind: str, key: str, prompt: str, seed: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0,
-                transform=None) -> Path:
+    def _cached(
+        self,
+        *,
+        kind: str,
+        key: str,
+        prompt: str,
+        seed: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+        transform=None,
+    ) -> Path:
         h = hashlib.sha1(
             f"{kind}|{prompt}|{negative_prompt}|{seed}|{guidance_scale}".encode()
         ).hexdigest()[:12]
@@ -175,15 +200,26 @@ class PainterBase:
             collector.record_cache(hit=True)
             return path
         collector.record_cache(hit=False)
-        img = self._render(prompt, seed, config.IMAGE_SIZE,
-                           negative_prompt=negative_prompt, guidance_scale=guidance_scale)
+        img = self._render(
+            prompt,
+            seed,
+            config.IMAGE_SIZE,
+            negative_prompt=negative_prompt,
+            guidance_scale=guidance_scale,
+        )
         if transform is not None:
             img = transform(img)
         img.save(path)
         return path
 
-    def _render(self, prompt: str, seed: int, size: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0):
+    def _render(
+        self,
+        prompt: str,
+        seed: int,
+        size: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+    ):
         raise NotImplementedError
 
 
@@ -191,8 +227,14 @@ class PainterBase:
 #  Mock — labelled placeholder, no models
 # --------------------------------------------------------------------------- #
 class MockPainter(PainterBase):
-    def _render(self, prompt: str, seed: int, size: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0):
+    def _render(
+        self,
+        prompt: str,
+        seed: int,
+        size: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+    ):
         from PIL import Image, ImageDraw  # noqa: PLC0415
 
         # deterministic colour from the seed so the same entity keeps the same placeholder
@@ -265,8 +307,14 @@ class SdxlTurboPainter(PainterBase):
             transform=remove,  # removes background → transparent PNG
         )
 
-    def _render(self, prompt: str, seed: int, size: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0):
+    def _render(
+        self,
+        prompt: str,
+        seed: int,
+        size: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+    ):
         gen = self.torch.Generator(device=self.device).manual_seed(seed)
         result = self.pipe(
             prompt=prompt,
@@ -321,8 +369,14 @@ class SdxlLightningPainter(PainterBase):
             transform=remove,  # removes background → transparent PNG
         )
 
-    def _render(self, prompt: str, seed: int, size: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0):
+    def _render(
+        self,
+        prompt: str,
+        seed: int,
+        size: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+    ):
         gen = self.torch.Generator(device=self.device).manual_seed(seed)
         result = self.pipe(
             prompt=prompt,
@@ -379,8 +433,14 @@ class ModalPainter(PainterBase):
         img.save(path)
         return path
 
-    def _render(self, prompt: str, seed: int, size: int,
-                negative_prompt: str = "", guidance_scale: float = 0.0):
+    def _render(
+        self,
+        prompt: str,
+        seed: int,
+        size: int,
+        negative_prompt: str = "",
+        guidance_scale: float = 0.0,
+    ):
         import io  # noqa: PLC0415
 
         from PIL import Image  # noqa: PLC0415

visualnovel/prompts.py

@@ -175,7 +175,11 @@ def format_player_turn(player_input: str, action: str = "talk", target: str = ""
     """Combine target + action hint + player text into a single context line."""
     hint = _ACTION_HINTS.get(action, "")
     text = player_input.strip()
-    target_hint = f"*The wanderer addresses {target} specifically — only {target} should reply.*\n" if target else ""
+    target_hint = (
+        f"*The wanderer addresses {target} specifically — only {target} should reply.*\n"
+        if target
+        else ""
+    )
     parts = [p for p in [target_hint, hint, text] if p]
     return "\n".join(parts) or "…"
 

visualnovel/schemas.py

@@ -88,19 +88,21 @@ class Ending(BaseModel):
 
 class NPCRelDelta(BaseModel):
     """One directed bond update between two NPCs."""
-    source: str   # character id who holds the feeling
-    target: str   # character id the feeling is directed at
-    delta: int    # change to apply (-100..100)
+
+    source: str  # character id who holds the feeling
+    target: str  # character id the feeling is directed at
+    delta: int  # change to apply (-100..100)
     note: str = ""  # human label: "jealousy", "camaraderie", "rivalry", "fondness", "protects", …
 
 
 class NPCBond(BaseModel):
     """A directed NPC↔NPC bond for the frontend graph."""
+
     source_id: str
     source_name: str
     target_id: str
     target_name: str
-    value: int    # current -100..100
+    value: int  # current -100..100
     note: str = ""
 
 
@@ -183,7 +185,9 @@ class ViewState(BaseModel):
     place: str = ""
     backdrop_url: str | None = None
     present: list[SpritePresence] = Field(default_factory=list)
-    known_characters: list[SpritePresence] = Field(default_factory=list)  # all met chars incl. off-stage
+    known_characters: list[SpritePresence] = Field(
+        default_factory=list
+    )  # all met chars incl. off-stage
     beat: Beat = "opening"
     ended: bool = False
     ending_text: str | None = None
@@ -192,5 +196,7 @@ class ViewState(BaseModel):
     notifications: list[str] = Field(default_factory=list)  # popup messages this turn
     intro_text: str = ""  # shown once in the book overlay at game start; empty on subsequent turns
     audio_b64: str | None = None  # data:audio/wav;base64,... — absent when TTS is mocked
-    current_music: str | None = None  # active BGM track name (calm|romantic|dramatic|mystery|sad|joyful)
+    current_music: str | None = (
+        None  # active BGM track name (calm|romantic|dramatic|mystery|sad|joyful)
+    )
     npc_bonds: list[NPCBond] = Field(default_factory=list)  # all directed NPC↔NPC bonds

visualnovel/state.py

@@ -14,7 +14,7 @@ import re
 from pathlib import Path
 
 from . import config
-from .schemas import Character, DirectorOutput, GameState, NPCRelDelta, Scene
+from .schemas import Character, DirectorOutput, GameState, Scene
 
 _CLAMP = (-100, 100)
 

visualnovel/tts.py

@@ -32,46 +32,68 @@ from . import config
 # ---------------------------------------------------------------------------
 _VOICE_PROFILES: list[tuple[str, str, frozenset[str]]] = [
     # ── American Female ────────────────────────────────────────────────────
-    ("af_heart",   "f", frozenset({"warm", "bright", "breathless", "tender", "sweet", "laughs", "light"})),
-    ("af_bella",   "f", frozenset({"soft", "gentle", "quiet", "shy", "delicate", "whisper", "whispered"})),
-    ("af_sarah",   "f", frozenset({"clear", "professional", "calm", "steady", "cool", "composed"})),
-    ("af_sky",     "f", frozenset({"airy", "bubbly", "cheerful", "energetic", "lively", "peppy"})),
-    ("af_jessica", "f", frozenset({"bold", "confident", "sharp", "spirited", "assertive", "direct"})),
-    ("af_nicole",  "f", frozenset({"rich", "smooth", "soothing", "mature", "warm", "velvet"})),
-    ("af_nova",    "f", frozenset({"crisp", "precise", "intelligent", "focused", "analytical"})),
-    ("af_river",   "f", frozenset({"flowing", "peaceful", "serene", "dreamy", "drifts", "trails"})),
-    ("af_kore",    "f", frozenset({"strong", "powerful", "serious", "stern", "commanding"})),
-    ("af_aoede",   "f", frozenset({"melodic", "musical", "lyrical", "poetic", "ethereal", "sings"})),
-    ("af_alloy",   "f", frozenset({"neutral", "balanced", "modern", "even"})),
+    (
+        "af_heart",
+        "f",
+        frozenset({"warm", "bright", "breathless", "tender", "sweet", "laughs", "light"}),
+    ),
+    (
+        "af_bella",
+        "f",
+        frozenset({"soft", "gentle", "quiet", "shy", "delicate", "whisper", "whispered"}),
+    ),
+    ("af_sarah", "f", frozenset({"clear", "professional", "calm", "steady", "cool", "composed"})),
+    ("af_sky", "f", frozenset({"airy", "bubbly", "cheerful", "energetic", "lively", "peppy"})),
+    (
+        "af_jessica",
+        "f",
+        frozenset({"bold", "confident", "sharp", "spirited", "assertive", "direct"}),
+    ),
+    ("af_nicole", "f", frozenset({"rich", "smooth", "soothing", "mature", "warm", "velvet"})),
+    ("af_nova", "f", frozenset({"crisp", "precise", "intelligent", "focused", "analytical"})),
+    ("af_river", "f", frozenset({"flowing", "peaceful", "serene", "dreamy", "drifts", "trails"})),
+    ("af_kore", "f", frozenset({"strong", "powerful", "serious", "stern", "commanding"})),
+    ("af_aoede", "f", frozenset({"melodic", "musical", "lyrical", "poetic", "ethereal", "sings"})),
+    ("af_alloy", "f", frozenset({"neutral", "balanced", "modern", "even"})),
     # ── British Female ─────────────────────────────────────────────────────
-    ("bf_alice",    "f", frozenset({"british", "english", "uk", "posh", "accent", "clipped"})),
-    ("bf_emma",     "f", frozenset({"british", "english", "uk", "homely", "friendly", "warm"})),
-    ("bf_isabella", "f", frozenset({"british", "english", "uk", "refined", "elegant", "sophisticated"})),
-    ("bf_lily",     "f", frozenset({"british", "english", "uk", "gentle", "soft", "sweet"})),
+    ("bf_alice", "f", frozenset({"british", "english", "uk", "posh", "accent", "clipped"})),
+    ("bf_emma", "f", frozenset({"british", "english", "uk", "homely", "friendly", "warm"})),
+    (
+        "bf_isabella",
+        "f",
+        frozenset({"british", "english", "uk", "refined", "elegant", "sophisticated"}),
+    ),
+    ("bf_lily", "f", frozenset({"british", "english", "uk", "gentle", "soft", "sweet"})),
     # ── American Male ─────────────────────────────────────────────────────
-    ("am_adam",    "m", frozenset({"confident", "deep", "steady", "bass", "strong", "rich"})),
-    ("am_echo",    "m", frozenset({"resonant", "full", "commanding", "measured"})),
-    ("am_eric",    "m", frozenset({"friendly", "casual", "warm", "approachable", "cheerful"})),
-    ("am_fenrir",  "m", frozenset({"gruff", "rough", "intense", "dark", "rugged", "growl", "harsh"})),
-    ("am_liam",    "m", frozenset({"young", "energetic", "bright", "enthusiastic", "lively"})),
+    ("am_adam", "m", frozenset({"confident", "deep", "steady", "bass", "strong", "rich"})),
+    ("am_echo", "m", frozenset({"resonant", "full", "commanding", "measured"})),
+    ("am_eric", "m", frozenset({"friendly", "casual", "warm", "approachable", "cheerful"})),
+    (
+        "am_fenrir",
+        "m",
+        frozenset({"gruff", "rough", "intense", "dark", "rugged", "growl", "harsh"}),
+    ),
+    ("am_liam", "m", frozenset({"young", "energetic", "bright", "enthusiastic", "lively"})),
     ("am_michael", "m", frozenset({"mature", "calm", "authoritative", "professorial", "quiet"})),
-    ("am_onyx",    "m", frozenset({"smooth", "velvet", "baritone", "low", "silky", "suave"})),
-    ("am_puck",    "m", frozenset({"playful", "mischievous", "quick", "witty", "impish", "teasing"})),
+    ("am_onyx", "m", frozenset({"smooth", "velvet", "baritone", "low", "silky", "suave"})),
+    ("am_puck", "m", frozenset({"playful", "mischievous", "quick", "witty", "impish", "teasing"})),
     # ── British Male ──────────────────────────────────────────────────────
-    ("bm_daniel",  "m", frozenset({"british", "english", "uk", "smooth", "refined", "crisp"})),
-    ("bm_fable",   "m", frozenset({"british", "english", "uk", "storyteller", "dramatic", "expressive"})),
-    ("bm_george",  "m", frozenset({"british", "english", "uk", "distinguished", "formal", "noble"})),
-    ("bm_lewis",   "m", frozenset({"british", "english", "uk", "young", "casual", "easy"})),
+    ("bm_daniel", "m", frozenset({"british", "english", "uk", "smooth", "refined", "crisp"})),
+    (
+        "bm_fable",
+        "m",
+        frozenset({"british", "english", "uk", "storyteller", "dramatic", "expressive"}),
+    ),
+    ("bm_george", "m", frozenset({"british", "english", "uk", "distinguished", "formal", "noble"})),
+    ("bm_lewis", "m", frozenset({"british", "english", "uk", "young", "casual", "easy"})),
 ]
 
-_MALE_GENDER_HINTS   = {"man", "male", "his", "him", "he", "boy", "lad", "gentleman"}
+_MALE_GENDER_HINTS = {"man", "male", "his", "him", "he", "boy", "lad", "gentleman"}
 _FEMALE_GENDER_HINTS = {"woman", "female", "her", "she", "girl", "lady"}
 
-_MODEL_PATH  = config.MODELS_DIR / "kokoro" / "kokoro-v1.0.onnx"
+_MODEL_PATH = config.MODELS_DIR / "kokoro" / "kokoro-v1.0.onnx"
 _VOICES_PATH = config.MODELS_DIR / "kokoro" / "voices-v1.0.bin"
-_KOKORO_BASE_URL = (
-    "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
-)
+_KOKORO_BASE_URL = "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files-v1.0"
 
 
 def _ensure_kokoro_models() -> None:
@@ -97,7 +119,7 @@ def _pick_voice(voice_description: str, sprite_seed: int) -> str:
     words = set(voice_description.lower().split())
 
     # Detect gender from description
-    is_male   = bool(words & _MALE_GENDER_HINTS)
+    is_male = bool(words & _MALE_GENDER_HINTS)
     is_female = bool(words & _FEMALE_GENDER_HINTS)
     # If ambiguous, default to female (most anime VN characters)
     target_gender = "m" if is_male and not is_female else "f"
@@ -140,8 +162,12 @@ class KokoroTTS:
         voice_id = _pick_voice(voice_description, seed)
         # Fallback if the chosen voice isn't in this model build
         if voice_id not in self._available_voices:
-            fallback = [vid for vid, g, _ in _VOICE_PROFILES if g == "f" and vid in self._available_voices]
-            voice_id = fallback[seed % len(fallback)] if fallback else next(iter(self._available_voices))
+            fallback = [
+                vid for vid, g, _ in _VOICE_PROFILES if g == "f" and vid in self._available_voices
+            ]
+            voice_id = (
+                fallback[seed % len(fallback)] if fallback else next(iter(self._available_voices))
+            )
 
         cache_key = hashlib.sha256(f"{text}\x00{voice_id}\x00{seed}".encode()).hexdigest()
         if cache_key in self._cache: