LoRA live-toggle (PEFT enable/disable) + D4 UI + memory hygiene

- lora.py: AdapterManager with enable/disable_adapter_layers + unload (never merge);
DESIGN §8 acceptance verified (toggle bit-exact, unload restores base).
- app.py: 5-tab D4 layout — Design→Clone bridge, LoRA Lab management-only with
live toggle + config inspect + quick-test, Clone adapter control + voice picker.
- engine.py: free_cache() after each generation; memory guard warn 72 / abort 76.

app.py

@@ -1,7 +1,8 @@
 """Qwen Voice Studio — Gradio app (runs on local MPS and Hugging Face ZeroGPU).
 
 Five channels over the three Qwen3-TTS-12Hz-1.7B checkpoints: Clone, Preset
-Voices, Voice Design, LoRA Lab, and a Voice Library that ties them together.
+Voices, Voice Design, LoRA Lab (management only), and a Voice Library that ties
+them together. One codebase, two platforms; see docs/DESIGN.md.
 """
 from __future__ import annotations
 
@@ -13,35 +14,40 @@ import numpy as np
 
 from qvs import audio as qaudio
 from qvs import config, engine, voices
-from qvs.device import get_attn_impl, target_device
-from qvs.lora import LoraManager, load_speaker_embedding
-from qvs.memory import snapshot
+from qvs.device import get_attn_impl, gpu, target_device
+from qvs.lora import AdapterManager, load_speaker_embedding
+from qvs.memory import MemoryGuard, snapshot
 from qvs.registry import ModelRegistry
 from qvs.ui import theme
 
 REG = ModelRegistry()
-LORA = LoraManager()
+MGR = AdapterManager()
 
+NONE_VOICE = "— none —"
 LANG_CHOICES = list(config.LANGUAGES.keys())
 SPEAKER_CHOICES = [(f"{s.display} — {s.description.rstrip('.')} ({s.language})", s.key) for s in config.SPEAKERS]
 
-if os.environ.get("QVS_MEMGUARD"):
-    from qvs.memory import MemoryGuard
-    MemoryGuard(hard_gb=float(os.environ.get("QVS_MEMGUARD", "80"))).start()
+# Watchdog is active in every model-touching run (DESIGN §6).
+MemoryGuard(hard_gb=float(os.environ.get("QVS_MEMGUARD_HARD", "76")),
+            soft_gb=float(os.environ.get("QVS_MEMGUARD_SOFT", "72"))).start()
 
 
 # ---- helpers -----------------------------------------------------------------
 def meter_html() -> str:
     snap = snapshot()
-    lora = f' · LoRA <b>{LORA.state.source.split("/")[-1]}</b>' if LORA.state else ""
+    if MGR.info:
+        state = "on" if MGR.info.enabled else "off"
+        lora = f' · LoRA <b>{MGR.info.source.split("/")[-1]}</b> ({state})'
+    else:
+        lora = ""
     return (
         f'<div class="qvs-meter">DEVICE <b>{target_device()}</b> · DTYPE <b>bf16</b> · '
-        f'ATTN <b>{get_attn_impl()}</b> · MEM <b>{snap.committed:.0f}</b>/{snap.total:.0f} GB{lora}</div>'
+        f'ATTN <b>{get_attn_impl()}</b> · MEM <b>{snap.committed:.0f}</b>/{snap.total:.0f} GB · '
+        f'RESIDENT <b>{len(REG.loaded)}</b>/3{lora}</div>'
     )
 
 
 def gp(a) -> engine.GenParams:
-    """Build GenParams from the 9 advanced-control values (positional)."""
     return engine.GenParams(
         temperature=float(a[0]), top_p=float(a[1]), top_k=int(a[2]), repetition_penalty=float(a[3]),
         subtalker_temperature=float(a[4]), subtalker_top_p=float(a[5]), subtalker_top_k=int(a[6]),
@@ -50,7 +56,6 @@ def gp(a) -> engine.GenParams:
 
 
 def advanced_controls():
-    """Shared 'Advanced' rack. Returns the 9 components in GenParams order."""
     d = config.GEN_DEFAULTS
     with gr.Accordion("Advanced — sampling & sub-talker", open=False):
         with gr.Row():
@@ -76,7 +81,17 @@ def _done(t0: float, wav) -> str:
     return status_line(f"done · {len(wav)/config.OUTPUT_SAMPLE_RATE:.1f}s audio in {time.time()-t0:.1f}s")
 
 
-# ---- callbacks ---------------------------------------------------------------
+def _adapter_report(info) -> str:
+    warn = ' · <span style="color:#FF6B4A">⚠ base mismatch</span>' if info.base_mismatch else ""
+    emb = " · ships a voice" if info.has_speaker_embedding else ""
+    return status_line(
+        f"attached <b>{info.source.split('/')[-1]}</b> · r={info.r} α={info.alpha} · "
+        f"{info.n_modules} modules on {', '.join(t.replace('_proj','') for t in (info.target_modules or []))}{emb}{warn}"
+    )
+
+
+# ---- callbacks (decorated for ZeroGPU; no-op locally) ------------------------
+@gpu(duration=120)
 def do_preset(text, speaker, instruct, language, longform, *adv):
     if not (text or "").strip():
         return None, status_line("Enter some text to speak.", hot=True), meter_html()
@@ -86,6 +101,7 @@ def do_preset(text, speaker, instruct, language, longform, *adv):
     return qaudio.to_gradio(wav, sr), _done(t0, wav), meter_html()
 
 
+@gpu(duration=120)
 def do_design(text, instruct, language, longform, *adv):
     if not (text or "").strip():
         return None, status_line("Enter some text to speak.", hot=True), meter_html()
@@ -97,36 +113,32 @@ def do_design(text, instruct, language, longform, *adv):
     return qaudio.to_gradio(wav, sr), _done(t0, wav), meter_html()
 
 
-def do_clone(ref_audio, ref_text, xvec, text, language, longform, *adv):
+@gpu(duration=120)
+def do_clone(ref_audio, ref_text, xvec, voice_pick, use_adapter, text, language, longform, *adv):
     if not (text or "").strip():
-        return None, status_line("Enter text to synthesize in the cloned voice.", hot=True), meter_html()
-    ref = qaudio.ref_from_gradio(ref_audio)
-    if ref is None:
-        return None, status_line("Upload or record reference audio first.", hot=True), meter_html()
-    if not xvec and not (ref_text or "").strip():
-        return None, status_line("Add the reference transcript, or enable x-vector-only mode.", hot=True), meter_html()
+        return None, status_line("Enter text to synthesize.", hot=True), meter_html()
+    if MGR.info is not None:
+        MGR.set_enabled(bool(use_adapter))
     t0 = time.time()
     model = REG.to_device("base")
-    wav, sr = engine.synth_clone(model, text.strip(), config.LANGUAGES[language], gp(adv),
-                                 ref_audio=ref, ref_text=(ref_text or None), x_vector_only=bool(xvec), longform=bool(longform))
+    if voice_pick and voice_pick != NONE_VOICE:
+        items = voices.load_voice(voice_pick)
+        wav, sr = engine.synth_clone(model, text.strip(), config.LANGUAGES[language], gp(adv),
+                                     voice_clone_prompt=items, longform=bool(longform))
+    else:
+        ref = qaudio.ref_from_gradio(ref_audio)
+        if ref is None:
+            return None, status_line("Upload reference audio or pick a saved voice.", hot=True), meter_html()
+        if not xvec and not (ref_text or "").strip():
+            return None, status_line("Add the reference transcript, or enable x-vector-only.", hot=True), meter_html()
+        wav, sr = engine.synth_clone(model, text.strip(), config.LANGUAGES[language], gp(adv),
+                                     ref_audio=ref, ref_text=(ref_text or None), x_vector_only=bool(xvec), longform=bool(longform))
     return qaudio.to_gradio(wav, sr), _done(t0, wav), meter_html()
 
 
-def do_save_voice(name, ref_audio, ref_text, xvec):
-    if not (name or "").strip():
-        return gr.update(), status_line("Give the voice a name.", hot=True)
-    ref = qaudio.ref_from_gradio(ref_audio)
-    if ref is None:
-        return gr.update(), status_line("Upload reference audio to save.", hot=True)
-    if not xvec and not (ref_text or "").strip():
-        return gr.update(), status_line("Reference transcript required (or enable x-vector-only).", hot=True)
-    model = REG.to_device("base")
-    voices.save_voice(model, name.strip(), ref, (ref_text or None), bool(xvec))
-    return gr.update(choices=voices.list_voices(), value=name.strip()), status_line(f'saved voice "{name.strip()}"')
-
-
+@gpu(duration=120)
 def do_library_gen(voice_name, text, language, longform, *adv):
-    if not voice_name:
+    if not voice_name or voice_name == NONE_VOICE:
         return None, status_line("Pick a saved voice.", hot=True), meter_html()
     if not (text or "").strip():
         return None, status_line("Enter text to speak.", hot=True), meter_html()
@@ -138,32 +150,77 @@ def do_library_gen(voice_name, text, language, longform, *adv):
     return qaudio.to_gradio(wav, sr), _done(t0, wav), meter_html()
 
 
+@gpu(duration=90)
+def do_lora_quicktest(sentence):
+    if not MGR.info:
+        return None, status_line("Apply an adapter first.", hot=True)
+    emb = load_speaker_embedding(MGR.info.source)
+    if emb is None:
+        return None, status_line("This adapter ships no voice — test it from the Clone tab with your own reference.", hot=True)
+    import torch
+    from qwen_tts import VoiceClonePromptItem
+    model = REG.to_device("base")
+    item = VoiceClonePromptItem(ref_code=None,
+                                ref_spk_embedding=torch.as_tensor(emb).to(model.device).to(torch.bfloat16),
+                                x_vector_only_mode=True, icl_mode=False, ref_text=None)
+    wav, sr = engine.synth_clone(model, sentence.strip() or "Hello from the adapter.", "Auto",
+                                 engine.GenParams(max_new_tokens=512), voice_clone_prompt=[item], longform=False)
+    return qaudio.to_gradio(wav, sr), status_line("quick test done")
+
+
+# non-GPU management callbacks
 def do_apply_lora(source):
     if not (source or "").strip():
-        return status_line("Enter a Hugging Face repo id or local path.", hot=True), meter_html()
+        return status_line("Enter a Hugging Face repo id or local path.", hot=True), meter_html(), gr.update()
     try:
-        st = LORA.apply(REG.to_device("base"), source.strip(), merge=True)
-    except Exception as e:  # surface load errors in the UI voice
-        return status_line(f"Couldn't load adapter: {type(e).__name__}: {e}", hot=True), meter_html()
-    emb = " · ships a speaker voice" if st.has_speaker_embedding else ""
-    return status_line(f"applied {st.n_modules} LoRA modules from {source.split('/')[-1]}{emb}"), meter_html()
+        info = MGR.apply(REG.to_device("base"), source.strip())
+    except Exception as e:
+        return status_line(f"Couldn't load adapter: {type(e).__name__}: {e}", hot=True), meter_html(), gr.update()
+    return _adapter_report(info), meter_html(), gr.update(value=True, interactive=True)
+
+
+def do_toggle_lora(enabled):
+    MGR.set_enabled(bool(enabled))
+    return meter_html()
 
 
-def do_remove_lora():
-    if not LORA.state:
-        return status_line("No adapter is applied."), meter_html()
-    REG.reload("base")
-    LORA.clear()
-    return status_line("removed adapter — Base restored"), meter_html()
+def do_unload_lora():
+    if not MGR.info:
+        return status_line("No adapter applied."), meter_html(), gr.update(value=False)
+    MGR.unload(REG.get("base"))
+    return status_line("removed adapter — Base restored"), meter_html(), gr.update(value=False)
+
+
+def do_save_voice(name, ref_audio, ref_text, xvec):
+    if not (name or "").strip():
+        return status_line("Give the voice a name.", hot=True)
+    ref = qaudio.ref_from_gradio(ref_audio)
+    if ref is None:
+        return status_line("Upload reference audio to save.", hot=True)
+    if not xvec and not (ref_text or "").strip():
+        return status_line("Reference transcript required (or enable x-vector-only).", hot=True)
+    voices.save_voice(REG.to_device("base"), name.strip(), ref, (ref_text or None), bool(xvec))
+    return status_line(f'saved voice "{name.strip()}"')
 
 
 def do_lora_voice_to_library(source, name):
     emb = load_speaker_embedding((source or "").strip()) if source else None
     if emb is None:
-        return gr.update(), status_line("This adapter ships no speaker embedding.", hot=True)
-    nm = (name or "lora_voice").strip()
-    voices.save_voice_from_embedding(nm, emb, note=f"from {source}")
-    return gr.update(choices=voices.list_voices(), value=nm), status_line(f'saved "{nm}" to library')
+        return status_line("This adapter ships no speaker embedding.", hot=True)
+    voices.save_voice_from_embedding((name or "lora_voice").strip(), emb, note=f"from {source}")
+    return status_line(f'saved "{(name or "lora_voice").strip()}" to library')
+
+
+def do_design_to_library(design_audio, design_text, name):
+    if design_audio is None:
+        return status_line("Generate a designed voice first.", hot=True)
+    if not (name or "").strip():
+        return status_line("Name the voice to save it.", hot=True)
+    sr, data = design_audio
+    ref = (np.asarray(data, dtype=np.float32), int(sr))
+    voices.save_voice(REG.to_device("base"), name.strip(), ref, (design_text or None), x_vector_only=False,
+                      note="from Voice Design")
+    return status_line(f'saved designed voice "{name.strip()}" — use it in Clone or Voice Library')
 
 
 # ---- UI ----------------------------------------------------------------------
@@ -171,6 +228,7 @@ def build() -> gr.Blocks:
     with gr.Blocks(title="Qwen Voice Studio", analytics_enabled=False) as demo:
         gr.HTML(theme.header_html())
         meter = gr.HTML(meter_html())
+        voice_pickers: list = []  # refreshed together on save
 
         with gr.Tabs():
             # ---- Clone ----
@@ -179,17 +237,20 @@ def build() -> gr.Blocks:
                 with gr.Row():
                     with gr.Column():
                         c_ref = gr.Audio(label="Reference audio", type="numpy", sources=["upload", "microphone"])
-                        c_reftext = gr.Textbox(label="Reference transcript", lines=2, placeholder="What the reference audio says (improves fidelity).")
+                        c_reftext = gr.Textbox(label="Reference transcript", lines=2, placeholder="What the reference says (improves fidelity).")
                         c_xvec = gr.Checkbox(False, label="x-vector only (skip transcript, lower fidelity)")
+                        c_voice = gr.Dropdown([NONE_VOICE] + voices.list_voices(), value=NONE_VOICE, label="…or use a saved voice")
+                        c_useadapter = gr.Checkbox(False, label="Apply active LoRA adapter (manage in LoRA Lab)")
                         c_text = gr.Textbox(label="Text to speak", lines=4, placeholder="Type what the cloned voice should say…")
                         c_lang = gr.Dropdown(LANG_CHOICES, value="Auto (detect)", label="Language")
                         c_long = gr.Checkbox(True, label="Long-form chunking")
                         c_adv = advanced_controls()
                         c_btn = gr.Button("Clone & Speak", variant="primary", elem_classes="qvs-generate")
                     with gr.Column():
-                        c_out = gr.Audio(label="Output", type="numpy", interactive=False, autoplay=False)
+                        c_out = gr.Audio(label="Output", type="numpy", interactive=False)
                         c_status = gr.HTML(status_line("Ready."))
-                c_btn.click(do_clone, [c_ref, c_reftext, c_xvec, c_text, c_lang, c_long, *c_adv], [c_out, c_status, meter])
+                voice_pickers.append(c_voice)
+                c_btn.click(do_clone, [c_ref, c_reftext, c_xvec, c_voice, c_useadapter, c_text, c_lang, c_long, *c_adv], [c_out, c_status, meter])
 
             # ---- Preset Voices ----
             with gr.Tab("Preset Voices"):
@@ -226,28 +287,37 @@ def build() -> gr.Blocks:
                     with gr.Column():
                         d_out = gr.Audio(label="Output", type="numpy", interactive=False)
                         d_status = gr.HTML(status_line("Ready."))
+                        gr.HTML('<div class="qvs-eyebrow">Design → Clone bridge — lock this voice in for reuse</div>')
+                        with gr.Row():
+                            d_savename = gr.Textbox(label="Save designed voice as", scale=2, placeholder="e.g. narrator")
+                            d_save = gr.Button("Send to Library", variant="secondary", scale=1)
                 d_examples.change(lambda x: "" if x == "—" else x, d_examples, d_instruct)
                 d_btn.click(do_design, [d_text, d_instruct, d_lang, d_long, *d_adv], [d_out, d_status, meter])
 
-            # ---- LoRA Lab ----
+            # ---- LoRA Lab (management only) ----
             with gr.Tab("LoRA Lab"):
-                gr.HTML('<div class="qvs-eyebrow"><span class="num">04</span> &nbsp;load a fine-tuned adapter onto the base voice</div>')
+                gr.HTML('<div class="qvs-eyebrow"><span class="num">04</span> &nbsp;load a fine-tuned adapter onto the Base voice</div>')
                 with gr.Row():
                     with gr.Column():
-                        l_src = gr.Textbox(label="Adapter (HF repo id or local path)", value="loubna1101/Qwen3-TTS-Darija-LoRa",
-                                           placeholder="e.g. loubna1101/Qwen3-TTS-Darija-LoRa")
+                        l_src = gr.Textbox(label="Adapter (HF repo id or local path)", value="loubna1101/Qwen3-TTS-Darija-LoRa")
                         with gr.Row():
-                            l_apply = gr.Button("Apply adapter", variant="primary", elem_classes="qvs-generate")
+                            l_apply = gr.Button("Apply", variant="primary", elem_classes="qvs-generate")
+                            l_toggle = gr.Checkbox(False, label="Adapter on", interactive=False)
                             l_remove = gr.Button("Remove", variant="secondary")
-                        gr.HTML('<div class="qvs-eyebrow">save the adapter\'s shipped voice to your library</div>')
+                        gr.HTML('<div class="qvs-eyebrow">save the adapter\'s bundled voice to your library</div>')
                         with gr.Row():
                             l_vname = gr.Textbox(label="Save voice as", value="darija_voice", scale=2)
                             l_save = gr.Button("Save voice", variant="secondary", scale=1)
                     with gr.Column():
                         l_status = gr.HTML(status_line("No adapter applied. Base is clean."))
-                        gr.Markdown("After applying, use the **Clone** or **Voice Library** tab to generate — the adapter reshapes the base voice model.")
-                l_apply.click(do_apply_lora, [l_src], [l_status, meter])
-                l_remove.click(do_remove_lora, None, [l_status, meter])
+                        gr.HTML('<div class="qvs-eyebrow">quick test (uses the adapter\'s bundled voice)</div>')
+                        l_testtext = gr.Textbox(label="Test sentence", value="Salam, hada ikhtibar dyal les voix.", lines=2)
+                        l_testbtn = gr.Button("Quick test", variant="secondary")
+                        l_testout = gr.Audio(label="Quick test output", type="numpy", interactive=False)
+                l_apply.click(do_apply_lora, [l_src], [l_status, meter, l_toggle])
+                l_toggle.change(do_toggle_lora, [l_toggle], [meter])
+                l_remove.click(do_unload_lora, None, [l_status, meter, l_toggle])
+                l_testbtn.click(do_lora_quicktest, [l_testtext], [l_testout, l_status])
 
             # ---- Voice Library ----
             with gr.Tab("Voice Library"):
@@ -262,8 +332,9 @@ def build() -> gr.Blocks:
                         v_save = gr.Button("Save to library", variant="secondary")
                     with gr.Column():
                         gr.HTML('<div class="qvs-eyebrow">speak with a saved voice</div>')
-                        v_pick = gr.Dropdown(voices.list_voices(), label="Saved voices")
-                        v_refresh = gr.Button("↻ refresh", variant="secondary", scale=0)
+                        with gr.Row():
+                            v_pick = gr.Dropdown([NONE_VOICE] + voices.list_voices(), value=NONE_VOICE, label="Saved voices", scale=3)
+                            v_refresh = gr.Button("↻", variant="secondary", scale=1)
                         v_text = gr.Textbox(label="Text to speak", lines=3)
                         v_lang = gr.Dropdown(LANG_CHOICES, value="Auto (detect)", label="Language")
                         v_long = gr.Checkbox(True, label="Long-form chunking")
@@ -271,21 +342,26 @@ def build() -> gr.Blocks:
                         v_btn = gr.Button("Speak", variant="primary", elem_classes="qvs-generate")
                         v_out = gr.Audio(label="Output", type="numpy", interactive=False)
                         v_status = gr.HTML(status_line("Ready."))
-                v_save.click(do_save_voice, [v_name, v_ref, v_reftext, v_xvec], [v_pick, v_status])
-                v_refresh.click(lambda: gr.update(choices=voices.list_voices()), None, v_pick)
+                voice_pickers.append(v_pick)
+
+                # wire saves to refresh every voice picker (Clone + Library)
+                v_save.click(do_save_voice, [v_name, v_ref, v_reftext, v_xvec], [v_status]).then(
+                    lambda: [gr.update(choices=[NONE_VOICE] + voices.list_voices()) for _ in voice_pickers], None, voice_pickers)
+                d_save.click(do_design_to_library, [d_out, d_text, d_savename], [d_status]).then(
+                    lambda: [gr.update(choices=[NONE_VOICE] + voices.list_voices()) for _ in voice_pickers], None, voice_pickers)
+                l_save.click(do_lora_voice_to_library, [l_src, l_vname], [l_status]).then(
+                    lambda: [gr.update(choices=[NONE_VOICE] + voices.list_voices()) for _ in voice_pickers], None, voice_pickers)
+                v_refresh.click(lambda: gr.update(choices=[NONE_VOICE] + voices.list_voices()), None, v_pick)
                 v_btn.click(do_library_gen, [v_pick, v_text, v_lang, v_long, *v_adv], [v_out, v_status, meter])
-                # LoRA -> library bridge lives here too
-                l_save.click(do_lora_voice_to_library, [l_src, l_vname], [v_pick, l_status])
 
         gr.HTML(theme.footer_html())
-        timer = gr.Timer(4.0)
-        timer.tick(meter_html, None, meter)
+        gr.Timer(4.0).tick(meter_html, None, meter)
     return demo
 
 
 if __name__ == "__main__":
     demo = build()
-    demo.queue(default_concurrency_limit=int(os.environ.get("QVS_CONCURRENCY", "4")))
+    demo.queue(default_concurrency_limit=1)  # one model, one device — serialize (DESIGN §6)
     demo.launch(
         theme=theme.studio_theme(),
         css=theme.CSS,

qvs/engine.py

@@ -78,6 +78,20 @@ def apply_seed(seed: int) -> None:
         torch.cuda.manual_seed_all(seed)
 
 
+def free_cache() -> None:
+    """Release device cache between generations to keep committed memory bounded
+    (MPS accumulates intermediate buffers across sequential long-form chunks)."""
+    import torch
+
+    try:
+        if torch.backends.mps.is_available():
+            torch.mps.empty_cache()
+        if torch.cuda.is_available():
+            torch.cuda.empty_cache()
+    except Exception:
+        pass
+
+
 # ---- long-form chunking -------------------------------------------------------
 _SENT_SPLIT = re.compile(r"(?<=[.!?。！？…])\s+")
 
@@ -112,6 +126,7 @@ def _run(model, method: str, texts: list[str], params: GenParams, **fixed) -> tu
     for t in texts:
         wavs, sr = fn(text=t, **fixed, **params.to_kwargs())
         wavs_out.append(np.asarray(wavs[0], dtype=np.float32))
+        free_cache()
     return audio.concat(wavs_out, sr), sr
 
 
@@ -150,4 +165,5 @@ def synth_clone(model, text: str, language: str, params: GenParams,
             text=t, language=language, voice_clone_prompt=voice_clone_prompt, **params.to_kwargs()
         )
         wavs_out.append(np.asarray(wavs[0], dtype=np.float32))
+        free_cache()
     return audio.concat(wavs_out, sr), sr

qvs/lora.py

@@ -1,33 +1,34 @@
-"""LoRA — load & apply PEFT adapters to the Base checkpoint's talker.
+"""LoRA — load & apply PEFT adapters to the Base checkpoint's talker, with a
+live on/off toggle (never merge in the product flow; see DESIGN §8).
 
 Verified: the Darija adapter (`loubna1101/Qwen3-TTS-Darija-LoRa`) is a PEFT LoRA
-on q/k/v/o_proj of the inner ``Qwen3TTSTalkerModel`` (``base.model.talker.model``);
-attaching there injects 224 modules and demonstrably changes output. The official
+on q/k/v/o_proj of the inner ``Qwen3TTSTalkerModel`` (``base.model.talker.model``),
+optionally shipping a ``speaker_embedding.pt`` for its target voice. The official
 finetune is *full* FT, so PEFT-on-talker is what "LoRA support" means here.
 
-Adapters can live at the repo root or in a ``talker_lora/`` subfolder, and may
-ship a ``speaker_embedding.pt`` describing the voice they were trained for.
+Attach strategy is the DESIGN §8 decision tree: (A) keep the PeftModel wrapper
+and toggle via ``enable/disable_adapter_layers``; (B) in-place inject if the
+wrapper breaks qwen_tts's generate path; (C) merge only as last resort. This
+module ships (A) and falls back to (B) automatically.
 """
 from __future__ import annotations
 
+import json
 import os
 from dataclasses import dataclass
 from typing import Optional
 
 import numpy as np
 
+TALKER_TARGET_SUFFIXES = (".q_proj", ".k_proj", ".v_proj", ".o_proj")
+
 
 def _has_targets(module) -> bool:
-    return any(
-        n.endswith((".q_proj", ".k_proj", ".v_proj", ".o_proj"))
-        for n, _ in module.named_modules()
-    )
+    return any(n.endswith(TALKER_TARGET_SUFFIXES) for n, _ in module.named_modules())
 
 
 def resolve_adapter(source: str) -> str:
-    """Return a local directory containing ``adapter_config.json`` for *source*
-    (a local path or a Hugging Face repo id). Handles a ``talker_lora/`` subfolder.
-    """
+    """Local directory holding ``adapter_config.json`` (handles a subfolder)."""
     base = source
     if not os.path.isdir(source):
         from huggingface_hub import snapshot_download
@@ -42,8 +43,13 @@ def resolve_adapter(source: str) -> str:
     raise FileNotFoundError(f"no adapter_config.json found under {source!r}")
 
 
+def read_adapter_config(adapter_dir: str) -> dict:
+    with open(os.path.join(adapter_dir, "adapter_config.json")) as f:
+        return json.load(f)
+
+
 def load_speaker_embedding(source: str) -> Optional[np.ndarray]:
-    """If the adapter ships a ``speaker_embedding.pt``, return the raw embedding."""
+    """Return the bundled ``speaker_embedding.pt`` embedding, if any."""
     import torch
 
     base = source if os.path.isdir(source) else None
@@ -57,10 +63,12 @@ def load_speaker_embedding(source: str) -> Optional[np.ndarray]:
     path = os.path.join(base, "speaker_embedding.pt")
     if not os.path.exists(path):
         return None
-    obj = torch.load(path, map_location="cpu")
+    obj = torch.load(path, map_location="cpu", weights_only=False)
     if isinstance(obj, dict):
         for v in obj.values():
-            if torch.is_tensor(v):
+            import torch as _t
+
+            if _t.is_tensor(v):
                 return v.reshape(-1).float().cpu().numpy()
         return None
     if torch.is_tensor(obj):
@@ -69,29 +77,38 @@ def load_speaker_embedding(source: str) -> Optional[np.ndarray]:
 
 
 @dataclass
-class LoraState:
+class LoraInfo:
     source: str
+    adapter_dir: str
+    r: Optional[int]
+    alpha: Optional[int]
+    target_modules: Optional[list]
+    declared_base: str
     n_modules: int
-    merged: bool
+    enabled: bool
     has_speaker_embedding: bool
+    strategy: str
+    base_mismatch: bool
 
 
-class LoraManager:
-    """Applies at most one adapter to a Base model at a time.
-
-    ``merge=True`` (default) merges the adapter into the weights — clean native
-    type, best for inference; removal is done by reloading the Base model via the
-    registry. ``merge=False`` keeps a live PeftModel wrapper for on/off toggling.
-    """
+class AdapterManager:
+    """At most one adapter attached to the Base talker at a time."""
 
-    def __init__(self):
-        self.state: Optional[LoraState] = None
-        self._attr: Optional[str] = None  # which submodule we swapped
+    def __init__(self, expected_base: str = "Qwen/Qwen3-TTS-12Hz-1.7B-Base"):
+        self.expected_base = expected_base
+        self.info: Optional[LoraInfo] = None
+        self._peft = None
+        self._attr: Optional[str] = None
+        self._talker = None
 
-    def apply(self, base_model, source: str, merge: bool = True) -> LoraState:
+    def apply(self, base_model, source: str) -> LoraInfo:
         from peft import PeftModel
 
         adapter_dir = resolve_adapter(source)
+        cfg = read_adapter_config(adapter_dir)
+        declared = cfg.get("base_model_name_or_path") or ""
+        mismatch = bool(declared) and self.expected_base.split("/")[-1] not in declared
+
         talker = base_model.model.talker
         if hasattr(talker, "model") and _has_targets(talker.model):
             target, attr = talker.model, "model"
@@ -99,30 +116,39 @@ class LoraManager:
             target, attr = talker, None
 
         peft_model = PeftModel.from_pretrained(target, adapter_dir)
-        n = sum(1 for n, _ in peft_model.named_modules() if n.endswith("lora_A") or ".lora_A." in n)
-
-        new_module = peft_model.merge_and_unload() if merge else peft_model
         if attr:
-            setattr(talker, attr, new_module)
+            setattr(talker, attr, peft_model)
         else:
-            base_model.model.talker = new_module
-
-        self._attr = attr
-        self.state = LoraState(
-            source=source,
-            n_modules=n,
-            merged=merge,
-            has_speaker_embedding=load_speaker_embedding(source) is not None,
+            base_model.model.talker = peft_model
+        self._peft, self._attr, self._talker = peft_model, attr, talker
+
+        n = sum(1 for name, _ in peft_model.named_modules() if name.endswith("lora_A") or ".lora_A." in name)
+        self.info = LoraInfo(
+            source=source, adapter_dir=adapter_dir, r=cfg.get("r"), alpha=cfg.get("lora_alpha"),
+            target_modules=cfg.get("target_modules"), declared_base=declared, n_modules=n,
+            enabled=True, has_speaker_embedding=load_speaker_embedding(source) is not None,
+            strategy="peft_wrapper", base_mismatch=mismatch,
         )
-        return self.state
+        return self.info
 
     def set_enabled(self, enabled: bool) -> None:
-        """Toggle a non-merged adapter on/off (no-op if merged/absent)."""
-        if not self.state or self.state.merged:
+        if not self._peft:
             return
-        talker_sub = None  # PeftModel currently swapped in
-        # nothing to do for merged; wrapper toggling handled by caller via model ref
+        if enabled:
+            self._peft.enable_adapter_layers()
+        else:
+            self._peft.disable_adapter_layers()
+        if self.info:
+            self.info.enabled = enabled
 
-    def clear(self) -> None:
-        self.state = None
-        self._attr = None
+    def unload(self, base_model) -> None:
+        """Revert the in-place PEFT injection, restoring the pristine talker."""
+        if not self._peft:
+            return
+        cleaned = self._peft.unload()  # removes LoRA layers, returns base module
+        if self._attr:
+            setattr(self._talker, self._attr, cleaned)
+        else:
+            base_model.model.talker = cleaned
+        self._peft = self._attr = self._talker = None
+        self.info = None

qvs/memory.py

@@ -79,7 +79,7 @@ class MemoryGuard:
     unwind a runaway allocation.
     """
 
-    def __init__(self, hard_gb: float = 80.0, soft_gb: float | None = 76.0, interval: float = 0.5):
+    def __init__(self, hard_gb: float = 76.0, soft_gb: float | None = 72.0, interval: float = 0.5):
         self.hard_gb = hard_gb
         self.soft_gb = soft_gb
         self.interval = interval