shiftgate 0.1.4__tar.gz → 0.1.6__tar.gz

{shiftgate-0.1.4 → shiftgate-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shiftgate
-Version: 0.1.4
+Version: 0.1.6
 Summary: Intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop.
 Project-URL: Homepage, https://github.com/shiftgate-ai/shiftgate
 Project-URL: Repository, https://github.com/shiftgate-ai/shiftgate
@@ -35,6 +35,8 @@ Description-Content-Type: text/markdown
 
 > **shiftgate is an intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop.**
 
+*Inspired by [LORAUTER](https://arxiv.org/abs/2601.21795) — Effective LoRA Adapter Routing using Task Representations (EPFL, 2026).*
+
 **Shiftgate is a routing layer. Users manage models and LoRA weights themselves.**  
 shiftgate stores only adapter *metadata* — it never downloads, caches, or manages weights.
 Your inference backend (Ollama, vLLM) is responsible for loading the weights; shiftgate just tells it *which* adapter to use for each query.
@@ -306,6 +308,12 @@ shiftgate/
 
 ---
 
+## References
+
+- [LORAUTER](https://arxiv.org/abs/2601.21795) — *Effective LoRA Adapter Routing using Task Representations* (Dhasade et al., EPFL, 2026). shiftgate's task-level semantic routing is inspired by this work; it is not a reimplementation of the paper's full algorithm.
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{shiftgate-0.1.4 → shiftgate-0.1.6}/README.md

@@ -2,6 +2,8 @@
 
 > **shiftgate is an intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop.**
 
+*Inspired by [LORAUTER](https://arxiv.org/abs/2601.21795) — Effective LoRA Adapter Routing using Task Representations (EPFL, 2026).*
+
 **Shiftgate is a routing layer. Users manage models and LoRA weights themselves.**  
 shiftgate stores only adapter *metadata* — it never downloads, caches, or manages weights.
 Your inference backend (Ollama, vLLM) is responsible for loading the weights; shiftgate just tells it *which* adapter to use for each query.
@@ -273,6 +275,12 @@ shiftgate/
 
 ---
 
+## References
+
+- [LORAUTER](https://arxiv.org/abs/2601.21795) — *Effective LoRA Adapter Routing using Task Representations* (Dhasade et al., EPFL, 2026). shiftgate's task-level semantic routing is inspired by this work; it is not a reimplementation of the paper's full algorithm.
+
+---
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

{shiftgate-0.1.4 → shiftgate-0.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shiftgate"
-version = "0.1.4"
+version = "0.1.6"
 description = "Intelligent routing layer that automatically selects the right LoRA adapter for each task in your local agent loop."
 readme = "README.md"
 requires-python = ">=3.10"

{shiftgate-0.1.4 → shiftgate-0.1.6}/shiftgate/__init__.py

@@ -1,8 +1,7 @@
 """
 shiftgate — Intelligent LoRA adapter routing for local LLM inference.
 
-Automatically selects the right adapter for each task using semantic
-similarity, inspired by the LORAUTER paper (EPFL, 2026).
+Automatically selects the right adapter for each task using semantic similarity.
 """
 
 __version__ = "0.1.0"

{shiftgate-0.1.4 → shiftgate-0.1.6}/shiftgate/cli.py

@@ -117,18 +117,52 @@ def _finish_adapter_add(adapter: AdapterEntry, task_reg, adapter_reg) -> None:
         )
 
 
+def _verify_runtime_adapter(adapter: AdapterEntry, adapter_reg) -> None:
+    """Best-effort check that a runtime adapter is loaded in a live backend.
+
+    Updates ``adapter.verified`` (True / False / None) and re-saves the
+    registry.  Never raises — verification is purely informational and must
+    not fail the ``adapter add`` command.
+    """
+    from shiftgate.runtime.backend import BackendRouter
+
+    try:
+        with console.status("[cyan]Verifying adapter against running backend…[/cyan]"):
+            router = BackendRouter()
+            is_loaded, backend_name = router.verify_adapter(adapter)
+    except Exception as exc:  # pragma: no cover - defensive, should not happen
+        logger_msg = f"verification error: {exc}"
+        console.print(f"   [dim]Backend: verification skipped ({logger_msg})[/dim]")
+        return
+
+    runtime = adapter.runtime_name or adapter.id
+
+    if backend_name is None:
+        adapter.verified = None
+        console.print("   [dim]Backend: not running (verification skipped)[/dim]")
+    elif is_loaded:
+        adapter.verified = True
+        console.print(f"   [green]Backend: {backend_name} ✓ verified[/green]")
+    else:
+        adapter.verified = False
+        console.print(
+            f"   [yellow]Backend: {backend_name} ⚠ runtime '{runtime}' not loaded "
+            "— did you pass --lora-modules?[/yellow]"
+        )
+
+    adapter_reg.save()
+
+
 # ---------------------------------------------------------------------------
 # shiftgate init
 # ---------------------------------------------------------------------------
 
 @app.command()
 def init() -> None:
-    """Set up ~/.shiftgate/, compute task embeddings, and show a welcome message."""
+    """Set up ~/.shiftgate/ and compute task embeddings."""
     from shiftgate.registry.adapter_registry import AdapterRegistry
     from shiftgate.registry.task_registry import TaskRegistry
-    from shiftgate.utils.display import show_task_table, show_welcome_banner
-
-    show_welcome_banner()
+    from shiftgate.utils.display import show_task_table
 
     shiftgate_dir = Path.home() / ".shiftgate"
     shiftgate_dir.mkdir(parents=True, exist_ok=True)
@@ -291,6 +325,11 @@ def adapter_add(
     adapter_reg.add_adapter(adapter)
     _finish_adapter_add(adapter, task_reg, adapter_reg)
 
+    # For runtime-registered adapters, try to confirm the backend actually
+    # has it loaded. Purely informational — never fails the add command.
+    if adapter.runtime_name:
+        _verify_runtime_adapter(adapter, adapter_reg)
+
 
 @adapter_app.command("list")
 def adapter_list() -> None:
@@ -593,6 +632,79 @@ def status() -> None:
     )
 
 
+# ---------------------------------------------------------------------------
+# shiftgate doctor
+# ---------------------------------------------------------------------------
+
+@app.command()
+def doctor() -> None:
+    """Run a full health check and print a diagnostic report.
+
+    Checks the embedder, the inference backend, every registered adapter's
+    runtime availability, task-embedding readiness, and flags any task
+    clusters that have no linked adapter.  Run this whenever something feels off.
+    """
+    from shiftgate.runtime.backend import BackendRouter, effective_backend_name
+    from shiftgate.utils.display import show_doctor_report
+
+    task_reg, adapter_reg = _load_registries()
+
+    # --- 1. Embedder ---
+    embedder_ok = False
+    embedder_detail = ""
+    with console.status("[cyan]Checking embedder…[/cyan]"):
+        try:
+            vec = _get_embedder().embed("test")
+            embedder_ok = vec is not None and len(vec) > 0
+            embedder_detail = f"dim={len(vec)}" if embedder_ok else "empty embedding"
+        except Exception as exc:
+            embedder_detail = str(exc)
+
+    # --- 2. Backend ---
+    with console.status("[cyan]Probing backends…[/cyan]"):
+        router = BackendRouter()
+        backend_name = router.detect()
+        backend_url = router.active_backend_url
+        loaded_adapters: list[str] = []
+        if backend_name is not None and router._active is not None:
+            loaded_adapters = router._active.list_loaded_adapters()
+
+    # --- 3. Per-adapter runtime availability ---
+    adapter_rows = []
+    for a in adapter_reg.list_adapters():
+        effective = effective_backend_name(a)
+        if backend_name is None:
+            state = "unknown"  # no backend to check against
+        elif effective in loaded_adapters:
+            state = "loaded"
+        else:
+            state = "missing"
+        adapter_rows.append(
+            {"id": a.id, "runtime": effective, "status": a.status, "state": state}
+        )
+
+    # --- 4 & 5. Task embedding readiness + unlinked clusters ---
+    all_tasks = task_reg.get_all_tasks()
+    n_with_embeddings = sum(1 for t in all_tasks if t.embedding_centroid is not None)
+    registered_ids = {a.id for a in adapter_reg.list_adapters()}
+    unlinked_tasks = [
+        t.id
+        for t in all_tasks
+        if not (set(t.preferred_adapters) | set(t.fallback_adapters)) & registered_ids
+    ]
+
+    show_doctor_report(
+        embedder_ok=embedder_ok,
+        embedder_detail=embedder_detail,
+        backend_name=backend_name,
+        backend_url=backend_url,
+        adapter_rows=adapter_rows,
+        n_tasks=len(all_tasks),
+        n_with_embeddings=n_with_embeddings,
+        unlinked_tasks=unlinked_tasks,
+    )
+
+
 # ---------------------------------------------------------------------------
 # shiftgate demo
 # ---------------------------------------------------------------------------

{shiftgate-0.1.4 → shiftgate-0.1.6}/shiftgate/registry/schemas.py

@@ -93,6 +93,16 @@ class AdapterEntry(BaseModel):
         ),
     )
 
+    # --- backend verification result ---
+    verified: bool | None = Field(
+        default=None,
+        description=(
+            "Result of the last backend verification: True = the adapter's "
+            "runtime name was found loaded in a running backend, False = it was "
+            "not found, None = no backend was reachable when last checked."
+        ),
+    )
+
     @model_validator(mode="after")
     def _at_least_one_source(self) -> "AdapterEntry":
         """Warn (not error) when no source field is set.

{shiftgate-0.1.4 → shiftgate-0.1.6}/shiftgate/runtime/backend.py

@@ -38,6 +38,21 @@ _CONNECT_TIMEOUT = 3.0
 _READ_TIMEOUT = 120.0
 
 
+def effective_backend_name(adapter: AdapterEntry) -> str:
+    """Return the name the inference backend knows this adapter by.
+
+    When the adapter was registered with ``--runtime <name>`` the user has
+    explicitly told us the backend loaded it under that name (e.g. a vLLM
+    ``--lora-modules`` key or an Ollama Modelfile model name).  In that case we
+    must send ``runtime_name`` — sending ``adapter.id`` would address a model
+    the backend has never heard of.
+
+    Priority: ``runtime_name`` (if set and non-empty) > ``id``.
+    """
+    runtime = (adapter.runtime_name or "").strip()
+    return runtime if runtime else adapter.id
+
+
 class BaseBackend(ABC):
     """Abstract base for inference backends."""
 
@@ -49,6 +64,14 @@ class BaseBackend(ABC):
     def generate(self, prompt: str, adapter: AdapterEntry) -> str:
         """Send ``prompt`` to the backend and return the generated text."""
 
+    @abstractmethod
+    def list_loaded_adapters(self) -> list[str]:
+        """Return the model/adapter names currently loaded in the backend.
+
+        Must use a short timeout and silently return ``[]`` if the backend is
+        unreachable — this method is only used for informational verification.
+        """
+
 
 # ---------------------------------------------------------------------------
 # Ollama
@@ -109,7 +132,9 @@ class OllamaBackend(BaseBackend):
             If True, Ollama streams response tokens.  This client reads the
             full stream and returns the concatenated text.
         """
-        model = model_name or adapter.id
+        # Explicit override wins; otherwise use the backend-effective name
+        # (runtime_name when set, else adapter.id).
+        model = model_name or effective_backend_name(adapter)
         payload = {"model": model, "prompt": prompt, "stream": stream}
 
         logger.debug("Ollama generate: model=%s", model)
@@ -126,6 +151,20 @@ class OllamaBackend(BaseBackend):
         data = r.json()
         return data.get("response", "")
 
+    def list_loaded_adapters(self) -> list[str]:
+        """Return the names of all models loaded in Ollama (``GET /api/tags``).
+
+        Silently returns ``[]`` if Ollama is unreachable.
+        """
+        try:
+            r = httpx.get(f"{self.base_url}/api/tags", timeout=_CONNECT_TIMEOUT)
+            r.raise_for_status()
+            models = r.json().get("models", [])
+            return [m["name"] for m in models if "name" in m]
+        except Exception as exc:
+            logger.debug("Ollama list_loaded_adapters failed: %s", exc)
+            return []
+
 
 # ---------------------------------------------------------------------------
 # vLLM
@@ -183,7 +222,9 @@ class VLLMBackend(BaseBackend):
         system_prompt:
             System message prepended before the user message.
         """
-        model = lora_name or adapter.id
+        # Explicit override wins; otherwise use the backend-effective name
+        # (runtime_name when set, else adapter.id).
+        model = lora_name or effective_backend_name(adapter)
         payload = {
             "model": model,
             "messages": [
@@ -209,6 +250,21 @@ class VLLMBackend(BaseBackend):
         except (KeyError, IndexError) as exc:
             raise BackendError(f"Unexpected vLLM response format: {data}") from exc
 
+    def list_loaded_adapters(self) -> list[str]:
+        """Return all model/LoRA ids served by vLLM (``GET /v1/models``).
+
+        The ``data`` array lists the base model plus every ``--lora-modules``
+        key.  Silently returns ``[]`` if vLLM is unreachable.
+        """
+        try:
+            r = httpx.get(f"{self.base_url}/v1/models", timeout=_CONNECT_TIMEOUT)
+            r.raise_for_status()
+            data = r.json().get("data", [])
+            return [m["id"] for m in data if "id" in m]
+        except Exception as exc:
+            logger.debug("vLLM list_loaded_adapters failed: %s", exc)
+            return []
+
 
 # ---------------------------------------------------------------------------
 # BackendRouter — auto-detects which backend is live
@@ -276,6 +332,37 @@ class BackendRouter:
             return "vllm"
         return None
 
+    @property
+    def active_backend_url(self) -> str | None:
+        """Return the base URL of the active backend, or None."""
+        if self._active is not None:
+            return self._active.base_url
+        return None
+
+    def verify_adapter(self, adapter: AdapterEntry) -> tuple[bool, str | None]:
+        """Check whether an adapter is actually loaded in the active backend.
+
+        Auto-detects a backend if one hasn't been probed yet.
+
+        Returns
+        -------
+        ``(is_loaded, backend_name)``
+            - ``(True, "<name>")``  — backend running and the adapter's
+              effective name is present in its loaded model list.
+            - ``(False, "<name>")`` — backend running but the name is absent.
+            - ``(False, None)``     — no backend reachable (verification skipped).
+
+        Never raises: HTTP failures degrade to ``(False, None)``.
+        """
+        if self._active is None:
+            self.detect()
+        if self._active is None:
+            return (False, None)
+
+        target = effective_backend_name(adapter)
+        loaded = self._active.list_loaded_adapters()
+        return (target in loaded, self.active_backend_name)
+
 
 # ---------------------------------------------------------------------------
 # Exceptions

{shiftgate-0.1.4 → shiftgate-0.1.6}/shiftgate/utils/display.py

@@ -333,19 +333,8 @@ def animate_swap(from_adapter: str, to_adapter: str, duration: float = 1.5) -> N
 # ---------------------------------------------------------------------------
 
 def show_welcome_banner() -> None:
-    """Print the shiftgate welcome banner shown during `shiftgate init`."""
-    banner = Text(justify="center")
-    banner.append("\n  ⚡ shiftgate  ", style="bold cyan")
-    banner.append("v0.1\n", style="dim")
-    banner.append("  Intelligent LoRA routing for local LLM inference\n", style="italic white")
-    banner.append("  Inspired by LORAUTER · EPFL 2026\n\n", style="dim")
-
-    panel = Panel(
-        Align.center(banner),
-        border_style="cyan",
-        expand=False,
-    )
-    console.print(Align.center(panel))
+    """Print a one-line banner (``shiftgate demo`` only)."""
+    console.print("\n[bold cyan]⚡ shiftgate[/bold cyan]\n")
 
 
 # ---------------------------------------------------------------------------
@@ -411,3 +400,148 @@ def show_status(
     grid.add_row("Embeddings", Text(emb_label, style=emb_style))
 
     console.print(Panel(grid, title="shiftgate status", border_style="cyan", expand=False))
+
+
+# ---------------------------------------------------------------------------
+# Doctor report
+# ---------------------------------------------------------------------------
+
+def show_doctor_report(
+    *,
+    embedder_ok: bool,
+    embedder_detail: str,
+    backend_name: str | None,
+    backend_url: str | None,
+    adapter_rows: list[dict],
+    n_tasks: int,
+    n_with_embeddings: int,
+    unlinked_tasks: list[str],
+) -> None:
+    """Render the full ``shiftgate doctor`` health report.
+
+    Parameters mirror the checks performed in ``cli.doctor``.  Each section is
+    a Rich panel/table; a final summary line tallies pass / warn / fail.
+    """
+    ok_mark = "[green]✓[/green]"
+    warn_mark = "[yellow]⚠[/yellow]"
+    fail_mark = "[red]✗[/red]"
+
+    warnings = 0
+    failures = 0
+
+    console.print()
+    console.rule("[bold cyan]shiftgate doctor[/bold cyan]")
+    console.print()
+
+    # --- Core checks grid ---
+    core = Table.grid(padding=(0, 2))
+    core.add_column(width=3)
+    core.add_column(style="bold", min_width=18)
+    core.add_column()
+
+    # Embedder
+    if embedder_ok:
+        core.add_row(ok_mark, "Embedder", Text(f"loaded ({embedder_detail})", style="green"))
+    else:
+        failures += 1
+        core.add_row(fail_mark, "Embedder", Text(f"failed: {embedder_detail}", style="red"))
+
+    # Backend
+    if backend_name:
+        core.add_row(
+            ok_mark,
+            "Backend",
+            Text(f"{backend_name}  ({backend_url})", style="green"),
+        )
+    else:
+        warnings += 1
+        core.add_row(
+            warn_mark,
+            "Backend",
+            Text("none detected — start ollama serve or vLLM", style="yellow"),
+        )
+
+    # Task embeddings
+    if n_tasks > 0 and n_with_embeddings == n_tasks:
+        core.add_row(
+            ok_mark,
+            "Task embeddings",
+            Text(f"{n_with_embeddings}/{n_tasks} clusters ready", style="green"),
+        )
+    else:
+        warnings += 1
+        core.add_row(
+            warn_mark,
+            "Task embeddings",
+            Text(
+                f"{n_with_embeddings}/{n_tasks} computed — run `shiftgate init`",
+                style="yellow",
+            ),
+        )
+
+    console.print(Panel(core, title="Core", border_style="cyan", expand=False))
+    console.print()
+
+    # --- Adapter availability table ---
+    if adapter_rows:
+        table = Table(
+            title="Adapter runtime availability",
+            box=box.ROUNDED,
+            header_style="bold cyan",
+            border_style="cyan",
+        )
+        table.add_column("Adapter ID", style="bold magenta")
+        table.add_column("Backend name")
+        table.add_column("Linked", justify="center")
+        table.add_column("Loaded", justify="center")
+
+        for row in adapter_rows:
+            linked = (
+                "[green]linked[/green]" if row["status"] == "linked"
+                else "[yellow]unassigned[/yellow]"
+            )
+            state = row["state"]
+            if state == "loaded":
+                loaded = f"{ok_mark} loaded"
+            elif state == "missing":
+                warnings += 1
+                loaded = f"{warn_mark} not loaded"
+            else:  # unknown — no backend
+                loaded = "[dim]— (no backend)[/dim]"
+            table.add_row(row["id"], row["runtime"], linked, loaded)
+
+        console.print(table)
+    else:
+        console.print("[dim]No adapters registered. Add one with `shiftgate adapter add`.[/dim]")
+    console.print()
+
+    # --- Unlinked task clusters warning ---
+    if unlinked_tasks:
+        warnings += 1
+        console.print(
+            Panel(
+                Text(
+                    "These task clusters have no linked adapter and will return "
+                    "'No adapter available' if matched:\n  "
+                    + ", ".join(unlinked_tasks),
+                    style="yellow",
+                ),
+                title=f"{warn_mark} Unlinked task clusters ({len(unlinked_tasks)})",
+                border_style="yellow",
+                expand=False,
+            )
+        )
+        console.print()
+
+    # --- Summary line ---
+    if failures:
+        summary = f"[bold red]{failures} failed[/bold red]"
+        if warnings:
+            summary += f", [yellow]{warnings} warning(s)[/yellow]"
+    elif warnings:
+        summary = f"[bold yellow]{warnings} warning(s)[/bold yellow] — shiftgate is usable but check above"
+    else:
+        summary = "[bold green]All checks passed — shiftgate is healthy.[/bold green]"
+
+    console.print(f"  {summary}")
+    console.print()

shiftgate-0.1.6/tests/test_backend.py

@@ -0,0 +1,137 @@
+"""
+Tests for the inference backend layer.
+
+Focus areas:
+  - effective_backend_name() name resolution (runtime_name vs id)
+  - BackendRouter.verify_adapter() against a stubbed loaded-adapter list
+No real HTTP calls are made.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from shiftgate.registry.schemas import AdapterEntry
+from shiftgate.runtime.backend import (
+    BackendRouter,
+    VLLMBackend,
+    effective_backend_name,
+)
+
+
+def _adapter(**kwargs) -> AdapterEntry:
+    base = dict(id="sql-lora", name="SQL", base_model="llama3")
+    base.update(kwargs)
+    return AdapterEntry(**base)
+
+
+# ---------------------------------------------------------------------------
+# effective_backend_name()
+# ---------------------------------------------------------------------------
+
+class TestEffectiveBackendName:
+    def test_uses_runtime_name_when_set(self):
+        adapter = _adapter(runtime_name="sql-lora-vllm")
+        assert effective_backend_name(adapter) == "sql-lora-vllm"
+
+    def test_falls_back_to_id_when_runtime_name_none(self):
+        adapter = _adapter(runtime_name=None, hf_repo="org/sql-lora")
+        assert effective_backend_name(adapter) == "sql-lora"
+
+    def test_falls_back_to_id_when_runtime_name_blank(self):
+        # An empty / whitespace runtime_name must not be used.
+        adapter = _adapter(runtime_name="   ", hf_repo="org/sql-lora")
+        assert effective_backend_name(adapter) == "sql-lora"
+
+
+# ---------------------------------------------------------------------------
+# generate() uses the effective name
+# ---------------------------------------------------------------------------
+
+class TestGenerateUsesEffectiveName:
+    def test_vllm_generate_sends_runtime_name(self, monkeypatch):
+        captured = {}
+
+        class _Resp:
+            def raise_for_status(self):
+                pass
+
+            def json(self):
+                return {"choices": [{"message": {"content": "ok"}}]}
+
+        def fake_post(url, json, timeout):
+            captured["model"] = json["model"]
+            return _Resp()
+
+        monkeypatch.setattr("shiftgate.runtime.backend.httpx.post", fake_post)
+
+        backend = VLLMBackend()
+        adapter = _adapter(runtime_name="sql-lora-vllm")
+        backend.generate("hello", adapter)
+        assert captured["model"] == "sql-lora-vllm"
+
+    def test_vllm_generate_explicit_override_wins(self, monkeypatch):
+        captured = {}
+
+        class _Resp:
+            def raise_for_status(self):
+                pass
+
+            def json(self):
+                return {"choices": [{"message": {"content": "ok"}}]}
+
+        def fake_post(url, json, timeout):
+            captured["model"] = json["model"]
+            return _Resp()
+
+        monkeypatch.setattr("shiftgate.runtime.backend.httpx.post", fake_post)
+
+        backend = VLLMBackend()
+        adapter = _adapter(runtime_name="sql-lora-vllm")
+        # Explicit lora_name must win over runtime_name.
+        backend.generate("hello", adapter, lora_name="override-name")
+        assert captured["model"] == "override-name"
+
+
+# ---------------------------------------------------------------------------
+# BackendRouter.verify_adapter()
+# ---------------------------------------------------------------------------
+
+class TestVerifyAdapter:
+    def test_no_backend_returns_false_none(self, monkeypatch):
+        router = BackendRouter()
+        monkeypatch.setattr(router, "detect", lambda: None)
+        # Active stays None → verification skipped.
+        is_loaded, backend_name = router.verify_adapter(_adapter(runtime_name="x"))
+        assert is_loaded is False
+        assert backend_name is None
+
+    def test_loaded_returns_true(self, monkeypatch):
+        router = BackendRouter()
+        # Force vLLM active and stub its loaded list.
+        router._active = router._vllm
+        monkeypatch.setattr(router._vllm, "list_loaded_adapters", lambda: ["base", "sql-lora-vllm"])
+        is_loaded, backend_name = router.verify_adapter(_adapter(runtime_name="sql-lora-vllm"))
+        assert is_loaded is True
+        assert backend_name == "vllm"
+
+    def test_not_loaded_returns_false_with_backend(self, monkeypatch):
+        router = BackendRouter()
+        router._active = router._vllm
+        monkeypatch.setattr(router._vllm, "list_loaded_adapters", lambda: ["base"])
+        is_loaded, backend_name = router.verify_adapter(_adapter(runtime_name="sql-lora-vllm"))
+        assert is_loaded is False
+        assert backend_name == "vllm"
+
+
+# ---------------------------------------------------------------------------
+# list_loaded_adapters() degrades gracefully when offline
+# ---------------------------------------------------------------------------
+
+class TestListLoadedAdaptersOffline:
+    def test_vllm_returns_empty_on_connection_error(self, monkeypatch):
+        def boom(*a, **k):
+            raise OSError("connection refused")
+
+        monkeypatch.setattr("shiftgate.runtime.backend.httpx.get", boom)
+        assert VLLMBackend().list_loaded_adapters() == []