shiftgate 0.1.1__tar.gz → 0.1.2__tar.gz

{shiftgate-0.1.1 → shiftgate-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shiftgate
-Version: 0.1.1
+Version: 0.1.2
 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
@@ -41,15 +41,13 @@ Your inference backend (Ollama, vLLM) is responsible for loading the weights; sh
 
 Instead of hardcoding which adapter to use, shiftgate embeds your query and matches it against a catalog of task clusters using cosine similarity — then routes inference to the best-fit LoRA adapter on your running Ollama or vLLM instance.
 
-Inspired by the [LORAUTER paper](https://arxiv.org/abs/2406.08213) (EPFL, 2026).
-
 ---
 
 ## Quickstart
 
 ```bash
 # 1. Install (requires Python 3.10+, uv recommended)
-uv add shiftgate
+uv tool install shiftgate (or pip install shiftgate)
 
 # 2. Initialise: sets up ~/.shiftgate/ and computes task embeddings
 shiftgate init
@@ -126,24 +124,26 @@ User query
 
 ## Commands
 
-| Command | Description |
-|---|---|
-| `shiftgate init` | First-time setup: initialise `~/.shiftgate/`, compute task embeddings |
-| `shiftgate route "<query>"` | Route a query and show the decision — no inference |
-| `shiftgate route "<query>" --explain` | Full decision tree: task scores, candidates, selection reason |
-| `shiftgate run "<query>"` | Route + run via Ollama or vLLM |
-| `shiftgate adapter add <hf_repo> [--tags …] [--base …]` | Register adapter from HuggingFace (metadata only) |
-| `shiftgate adapter add <id> --local <path> [--tags …]` | Register a local adapter path |
-| `shiftgate adapter add <id> --runtime <name> [--tags …]` | Register a backend-loaded adapter by its runtime name |
-| `shiftgate adapter list` | Table of all registered adapters |
-| `shiftgate adapter remove <id>` | Remove an adapter |
-| `shiftgate task list` | Table of all task clusters |
-| `shiftgate task add` | Interactively add a new task cluster |
-| `shiftgate feedback accept` | Mark last routing as good |
-| `shiftgate feedback reject` | Mark last routing as bad |
-| `shiftgate feedback stats` | Adapter acceptance rate table |
-| `shiftgate status` | Backend connectivity + registry summary |
-| `shiftgate demo` | Animated demo with fake routing traces |
+
+| Command                                                  | Description                                                           |
+| -------------------------------------------------------- | --------------------------------------------------------------------- |
+| `shiftgate init`                                         | First-time setup: initialise `~/.shiftgate/`, compute task embeddings |
+| `shiftgate route "<query>"`                              | Route a query and show the decision — no inference                    |
+| `shiftgate route "<query>" --explain`                    | Full decision tree: task scores, candidates, selection reason         |
+| `shiftgate run "<query>"`                                | Route + run via Ollama or vLLM                                        |
+| `shiftgate adapter add <hf_repo> [--tags …] [--base …]`  | Register adapter from HuggingFace (metadata only)                     |
+| `shiftgate adapter add <id> --local <path> [--tags …]`   | Register a local adapter path                                         |
+| `shiftgate adapter add <id> --runtime <name> [--tags …]` | Register a backend-loaded adapter by its runtime name                 |
+| `shiftgate adapter list`                                 | Table of all registered adapters                                      |
+| `shiftgate adapter remove <id>`                          | Remove an adapter                                                     |
+| `shiftgate task list`                                    | Table of all task clusters                                            |
+| `shiftgate task add`                                     | Interactively add a new task cluster                                  |
+| `shiftgate feedback accept`                              | Mark last routing as good                                             |
+| `shiftgate feedback reject`                              | Mark last routing as bad                                              |
+| `shiftgate feedback stats`                               | Adapter acceptance rate table                                         |
+| `shiftgate status`                                       | Backend connectivity + registry summary                               |
+| `shiftgate demo`                                         | Animated demo with fake routing traces                                |
+
 
 ---
 
@@ -231,12 +231,14 @@ To add a task cluster that better matches your domain, edit `data/default_tasks.
 
 ## Roadmap
 
-| Version | Focus |
-|---|---|
-| **v0.1** | Single base model, multi-adapter routing ← _current_ |
-| v0.2 | Feedback loop + adapter scoring (auto-demote bad adapters) |
-| v0.3 | Multi-model routing (route to different base models per task) |
-| v1.0 | Community registry + web UI |
+
+| Version  | Focus                                                         |
+| -------- | ------------------------------------------------------------- |
+| **v0.1** | Single base model, multi-adapter routing ← *current*          |
+| v0.2     | Feedback loop + adapter scoring (auto-demote bad adapters)    |
+| v0.3     | Multi-model routing (route to different base models per task) |
+| v1.0     | Community registry + web UI                                   |
+
 
 ---
 
@@ -270,8 +272,8 @@ The recommended flow:
 1. Bump the version in `pyproject.toml` (`version = "x.y.z"`).
 2. Open a PR, get it reviewed and merged.
 3. Tag the commit: `git tag vx.y.z && git push origin vx.y.z`.
-4. The CI workflow builds the wheel with `uv build` and publishes to PyPI  
-   using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)  
+4. The CI workflow builds the wheel with `uv build` and publishes to PyPI
+  using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)  
    — no stored API token needed.
 
 For a one-off manual publish (maintainers only):
@@ -306,4 +308,4 @@ shiftgate/
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

{shiftgate-0.1.1 → shiftgate-0.1.2}/README.md

@@ -8,15 +8,13 @@ Your inference backend (Ollama, vLLM) is responsible for loading the weights; sh
 
 Instead of hardcoding which adapter to use, shiftgate embeds your query and matches it against a catalog of task clusters using cosine similarity — then routes inference to the best-fit LoRA adapter on your running Ollama or vLLM instance.
 
-Inspired by the [LORAUTER paper](https://arxiv.org/abs/2406.08213) (EPFL, 2026).
-
 ---
 
 ## Quickstart
 
 ```bash
 # 1. Install (requires Python 3.10+, uv recommended)
-uv add shiftgate
+uv tool install shiftgate (or pip install shiftgate)
 
 # 2. Initialise: sets up ~/.shiftgate/ and computes task embeddings
 shiftgate init
@@ -93,24 +91,26 @@ User query
 
 ## Commands
 
-| Command | Description |
-|---|---|
-| `shiftgate init` | First-time setup: initialise `~/.shiftgate/`, compute task embeddings |
-| `shiftgate route "<query>"` | Route a query and show the decision — no inference |
-| `shiftgate route "<query>" --explain` | Full decision tree: task scores, candidates, selection reason |
-| `shiftgate run "<query>"` | Route + run via Ollama or vLLM |
-| `shiftgate adapter add <hf_repo> [--tags …] [--base …]` | Register adapter from HuggingFace (metadata only) |
-| `shiftgate adapter add <id> --local <path> [--tags …]` | Register a local adapter path |
-| `shiftgate adapter add <id> --runtime <name> [--tags …]` | Register a backend-loaded adapter by its runtime name |
-| `shiftgate adapter list` | Table of all registered adapters |
-| `shiftgate adapter remove <id>` | Remove an adapter |
-| `shiftgate task list` | Table of all task clusters |
-| `shiftgate task add` | Interactively add a new task cluster |
-| `shiftgate feedback accept` | Mark last routing as good |
-| `shiftgate feedback reject` | Mark last routing as bad |
-| `shiftgate feedback stats` | Adapter acceptance rate table |
-| `shiftgate status` | Backend connectivity + registry summary |
-| `shiftgate demo` | Animated demo with fake routing traces |
+
+| Command                                                  | Description                                                           |
+| -------------------------------------------------------- | --------------------------------------------------------------------- |
+| `shiftgate init`                                         | First-time setup: initialise `~/.shiftgate/`, compute task embeddings |
+| `shiftgate route "<query>"`                              | Route a query and show the decision — no inference                    |
+| `shiftgate route "<query>" --explain`                    | Full decision tree: task scores, candidates, selection reason         |
+| `shiftgate run "<query>"`                                | Route + run via Ollama or vLLM                                        |
+| `shiftgate adapter add <hf_repo> [--tags …] [--base …]`  | Register adapter from HuggingFace (metadata only)                     |
+| `shiftgate adapter add <id> --local <path> [--tags …]`   | Register a local adapter path                                         |
+| `shiftgate adapter add <id> --runtime <name> [--tags …]` | Register a backend-loaded adapter by its runtime name                 |
+| `shiftgate adapter list`                                 | Table of all registered adapters                                      |
+| `shiftgate adapter remove <id>`                          | Remove an adapter                                                     |
+| `shiftgate task list`                                    | Table of all task clusters                                            |
+| `shiftgate task add`                                     | Interactively add a new task cluster                                  |
+| `shiftgate feedback accept`                              | Mark last routing as good                                             |
+| `shiftgate feedback reject`                              | Mark last routing as bad                                              |
+| `shiftgate feedback stats`                               | Adapter acceptance rate table                                         |
+| `shiftgate status`                                       | Backend connectivity + registry summary                               |
+| `shiftgate demo`                                         | Animated demo with fake routing traces                                |
+
 
 ---
 
@@ -198,12 +198,14 @@ To add a task cluster that better matches your domain, edit `data/default_tasks.
 
 ## Roadmap
 
-| Version | Focus |
-|---|---|
-| **v0.1** | Single base model, multi-adapter routing ← _current_ |
-| v0.2 | Feedback loop + adapter scoring (auto-demote bad adapters) |
-| v0.3 | Multi-model routing (route to different base models per task) |
-| v1.0 | Community registry + web UI |
+
+| Version  | Focus                                                         |
+| -------- | ------------------------------------------------------------- |
+| **v0.1** | Single base model, multi-adapter routing ← *current*          |
+| v0.2     | Feedback loop + adapter scoring (auto-demote bad adapters)    |
+| v0.3     | Multi-model routing (route to different base models per task) |
+| v1.0     | Community registry + web UI                                   |
+
 
 ---
 
@@ -237,8 +239,8 @@ The recommended flow:
 1. Bump the version in `pyproject.toml` (`version = "x.y.z"`).
 2. Open a PR, get it reviewed and merged.
 3. Tag the commit: `git tag vx.y.z && git push origin vx.y.z`.
-4. The CI workflow builds the wheel with `uv build` and publishes to PyPI  
-   using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)  
+4. The CI workflow builds the wheel with `uv build` and publishes to PyPI
+  using [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)  
    — no stored API token needed.
 
 For a one-off manual publish (maintainers only):
@@ -273,4 +275,4 @@ shiftgate/
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT. See [LICENSE](LICENSE).

{shiftgate-0.1.1 → shiftgate-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shiftgate"
-version = "0.1.1"
+version = "0.1.2"
 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.1 → shiftgate-0.1.2}/shiftgate/cli.py

@@ -104,11 +104,15 @@ def _finish_adapter_add(adapter: AdapterEntry, task_reg, adapter_reg) -> None:
 
     linked = _auto_link_adapter(adapter, task_reg)
     if linked:
+        # Successfully wired into at least one task cluster → mark routable.
+        adapter.status = "linked"
+        adapter_reg.save()
         task_reg.save()
-        console.print(f"   [dim]Linked to task cluster(s): {', '.join(linked)}[/dim]")
+        console.print(f"   [green]Status:     linked[/green] → {', '.join(linked)}")
     else:
         console.print(
-            "   [dim]No task clusters auto-linked (no tag overlap). "
+            "   [yellow]Status:     unassigned[/yellow] — no task clusters matched these tags.\n"
+            "   [dim]This adapter will NOT be selected by the router until it is linked. "
             "Use `shiftgate task list` to see clusters.[/dim]"
         )
 
@@ -479,7 +483,15 @@ def run(
     )
 
     if adapter is None:
-        console.print(f"[red]Adapter '{trace.selected_adapter_id}' not found in registry.[/red]")
+        # Either the matched task has no linked adapter, or the linked ID is
+        # missing from the registry. In both cases: never guess, never run.
+        console.print(
+            "[red]No adapter available for this query — not running inference.[/red]\n"
+            f"  Matched task: [bold]{trace.matched_task_id}[/bold]\n"
+            "  Add one with: "
+            f"[cyan]shiftgate adapter add <hf_repo> --tags {trace.matched_task_id}[/cyan]"
+        )
+        feedback_loop.record_trace(trace)
         raise typer.Exit(1)
 
     if backend_name is None:

{shiftgate-0.1.1 → shiftgate-0.1.2}/shiftgate/registry/schemas.py

@@ -15,6 +15,8 @@ weights available to the backend (Ollama, vLLM, etc.) before running inference.
 
 from __future__ import annotations
 
+from typing import Literal
+
 from pydantic import BaseModel, Field, model_validator
 
 
@@ -81,6 +83,16 @@ class AdapterEntry(BaseModel):
         description="Optional benchmark score (0–1) reported by the adapter author.",
     )
 
+    # --- routing wiring status ---
+    status: Literal["linked", "unassigned"] = Field(
+        default="unassigned",
+        description=(
+            "Whether this adapter is wired into at least one task cluster's "
+            "preferred_adapters list. 'linked' = reachable by the router; "
+            "'unassigned' = registered but not yet routable to any task."
+        ),
+    )
+
     @model_validator(mode="after")
     def _at_least_one_source(self) -> "AdapterEntry":
         """Warn (not error) when no source field is set.
@@ -155,7 +167,13 @@ class RoutingTrace(BaseModel):
     similarity_score: float = Field(
         description="Cosine similarity between the query embedding and the winning centroid (0–1)."
     )
-    selected_adapter_id: str = Field(description="ID of the adapter that was selected for inference.")
+    selected_adapter_id: str | None = Field(
+        default=None,
+        description=(
+            "ID of the adapter selected for inference, or None when the matched "
+            "task has no linked adapter in the registry."
+        ),
+    )
     accepted: bool | None = Field(
         default=None,
         description="User feedback: True = good routing, False = bad routing, None = not yet rated.",

{shiftgate-0.1.1 → shiftgate-0.1.2}/shiftgate/router/matcher.py

@@ -43,16 +43,25 @@ class MatchResult:
 
     Returned by ``select_adapter`` so that both the router and the
     ``--explain`` display have access to the complete decision tree.
+
+    ``selected_adapter`` is ``None`` when the matched task has no adapter
+    linked in the registry.  In that case ``selection_method`` is
+    ``"no_adapter_for_task"`` and the router must NOT run inference.
     """
 
-    selected_adapter: AdapterEntry
+    selected_adapter: AdapterEntry | None
     matched_task: TaskCluster
     similarity_score: float
     # All top-K task matches including their candidate adapter lists
     all_task_matches: list[TaskMatch] = field(default_factory=list)
-    # How the adapter was ultimately found: "preferred", "fallback", or "tag_overlap"
+    # How the adapter was found: "preferred", "fallback", or "no_adapter_for_task"
     selection_method: str = "preferred"
 
+    @property
+    def has_adapter(self) -> bool:
+        """True when an adapter was successfully selected."""
+        return self.selected_adapter is not None
+
 
 # ---------------------------------------------------------------------------
 # Core functions
@@ -109,40 +118,38 @@ def select_adapter(
     top_tasks: list[TaskMatch],
     adapter_registry,  # AdapterRegistry — avoid circular import with string hint
 ) -> MatchResult:
-    """Select the best adapter given the ranked task list.
+    """Select the adapter linked to the best-matching task.
 
     Strategy
     --------
-    Pass 1 — explicit preferred/fallback lists
-        For each top task (highest score first), walk ``preferred_adapters``
-        then ``fallback_adapters``.  Return the first adapter found in the
-        registry.  Also populates ``TaskMatch.candidate_adapters`` for every
-        task so the ``--explain`` view can show all candidates.
-
-    Pass 2 — tag-overlap fallback
-        If no task had a registered preferred/fallback adapter (e.g. the user
-        just added an adapter without re-linking), score every registered
-        adapter by how many of its ``task_tags`` appear as tokens in the top
-        task's ID (e.g. tag ``"sql"`` overlaps ``"code_sql"``).  Return the
-        highest-scoring adapter.  This means ``adapter add`` works immediately
-        without a separate linking step.
-
-    Pass 3 — empty registry
-        Raise ``NoAdapterError`` only when there are literally no adapters.
+    For each top task (highest score first), walk ``preferred_adapters`` then
+    ``fallback_adapters`` and collect the adapters that exist in the registry
+    (populating ``TaskMatch.candidate_adapters`` for the ``--explain`` view).
+    The first such adapter found, on the highest-scoring task, is selected.
+
+    No silent fallback
+    ------------------
+    If the matched (top) task has **no** linked adapter in the registry, the
+    router must NOT substitute an arbitrary adapter — doing so silently routes,
+    e.g., a music query to a SQL adapter and destroys trust.  Instead this
+    returns a ``MatchResult`` with ``selected_adapter=None`` and
+    ``selection_method="no_adapter_for_task"``.
 
     Parameters
     ----------
     top_tasks:
-        Output of ``top_k_tasks``.
+        Output of ``top_k_tasks`` (sorted by score descending).
     adapter_registry:
         ``AdapterRegistry`` instance to look up adapter IDs.
 
     Returns
     -------
-    ``MatchResult`` containing the selected adapter, winning task, score, and
-    the full ranked task list annotated with their candidate adapters.
+    ``MatchResult``.  ``selected_adapter`` is ``None`` when no adapter is
+    linked to any of the ranked tasks.  The ``matched_task`` is always the
+    top-scoring task so callers can still report what was matched.
     """
-    # Pass 1: populate candidate lists and find the first explicit match.
+    # Populate candidate lists for every task (for the --explain view) and
+    # find the first explicit match in score order.
     explicit_result: MatchResult | None = None
 
     for tm in top_tasks:
@@ -178,40 +185,25 @@ def select_adapter(
         )
         return explicit_result
 
-    # Pass 2: tag-overlap fallback.
-    all_adapters = adapter_registry.list_adapters()
-    if not all_adapters:
-        raise NoAdapterError(
-            "No adapters registered. Add one with `shiftgate adapter add`."
-        )
-
+    # No adapter linked to any ranked task — do NOT guess. Report the matched
+    # task with no adapter so the caller can prompt the user to add one.
     top_task = top_tasks[0]
-    task_vocab: set[str] = set()
-    for tm in top_tasks:
-        task_vocab.update(tm.task.id.lower().split("_"))
-
-    best_adapter = max(
-        all_adapters,
-        key=lambda a: len({t.lower() for t in a.task_tags} & task_vocab),
-    )
-
-    # Add the fallback adapter as a candidate on the top task for the explain view.
-    if best_adapter not in top_task.candidate_adapters:
-        top_task.candidate_adapters.append(best_adapter)
-
-    logger.debug(
-        "Tag-overlap fallback selected adapter '%s' for task '%s'",
-        best_adapter.id,
+    logger.info(
+        "No linked adapter for matched task '%s' — refusing to guess.",
         top_task.task.id,
     )
     return MatchResult(
-        selected_adapter=best_adapter,
+        selected_adapter=None,
         matched_task=top_task.task,
         similarity_score=top_task.score,
         all_task_matches=top_tasks,
-        selection_method="tag_overlap",
+        selection_method="no_adapter_for_task",
     )
 
 
 class NoAdapterError(RuntimeError):
-    """Raised when the matcher cannot find any registered adapter for a query."""
+    """Raised when the matcher cannot find any registered adapter for a query.
+
+    Retained for backward compatibility; ``select_adapter`` no longer raises it
+    (it returns a ``MatchResult`` with ``selected_adapter=None`` instead).
+    """

{shiftgate-0.1.1 → shiftgate-0.1.2}/shiftgate/router/router.py

@@ -15,7 +15,7 @@ from shiftgate.registry.adapter_registry import AdapterRegistry
 from shiftgate.registry.schemas import RoutingTrace
 from shiftgate.registry.task_registry import TaskRegistry
 from shiftgate.router.embedder import Embedder
-from shiftgate.router.matcher import MatchResult, NoAdapterError, select_adapter, top_k_tasks
+from shiftgate.router.matcher import MatchResult, select_adapter, top_k_tasks
 
 logger = logging.getLogger(__name__)
 
@@ -54,10 +54,14 @@ def route(
     ``(RoutingTrace, MatchResult)`` — the trace for persistence/feedback and
     the full match result for detailed display (e.g. ``--explain``).
 
+    Note
+    ----
+    When the matched task has no linked adapter, ``MatchResult.selected_adapter``
+    is ``None`` and the trace's ``selected_adapter_id`` is ``None``.  The router
+    never substitutes an arbitrary adapter.
+
     Raises
     ------
-    NoAdapterError
-        If no registered adapter matches any of the top-K tasks.
     ValueError
         If embeddings have not been computed (missing centroids).
     """
@@ -71,12 +75,14 @@ def route(
     ranked = top_k_tasks(query_embedding, all_tasks, k=top_k)
     result = select_adapter(ranked, adapter_registry)
 
+    selected_id = result.selected_adapter.id if result.selected_adapter else None
+
     trace = RoutingTrace(
         id=uuid.uuid4().hex,
         query=query,
         matched_task_id=result.matched_task.id,
         similarity_score=result.similarity_score,
-        selected_adapter_id=result.selected_adapter.id,
+        selected_adapter_id=selected_id,
         timestamp=datetime.now(timezone.utc).isoformat(),
     )
 
@@ -85,7 +91,7 @@ def route(
         query[:60],
         result.matched_task.id,
         result.similarity_score * 100,
-        result.selected_adapter.id,
+        selected_id or "<none>",
         result.selection_method,
     )
     return trace, result

{shiftgate-0.1.1 → shiftgate-0.1.2}/shiftgate/utils/display.py

@@ -83,7 +83,10 @@ def show_routing_decision(
     backend_name:
         Active backend name ('ollama', 'vllm', or None).
     """
-    colour = _similarity_colour(trace.similarity_score)
+    # When no adapter was selected the decision is unactionable — render red
+    # regardless of how confident the task match was.
+    no_adapter = adapter is None and trace.selected_adapter_id is None
+    colour = "red" if no_adapter else _similarity_colour(trace.similarity_score)
 
     grid = Table.grid(padding=(0, 2))
     grid.add_column(style="dim", min_width=16)
@@ -98,7 +101,18 @@ def show_routing_decision(
     task_text.append_text(_similarity_bar(trace.similarity_score))
     grid.add_row("Matched Task", task_text)
 
-    if adapter:
+    if no_adapter:
+        # Never silently substitute an adapter. Tell the user how to fix it.
+        adapter_text = Text("No adapter available", style="bold red")
+        grid.add_row("Adapter", adapter_text)
+        suggestion = Text()
+        suggestion.append("Add one with: ", style="dim")
+        suggestion.append(
+            f"shiftgate adapter add <hf_repo> --tags {trace.matched_task_id}",
+            style="cyan",
+        )
+        grid.add_row("Suggestion", suggestion)
+    elif adapter:
         adapter_text = Text()
         adapter_text.append(adapter.name, style="bold magenta")
         adapter_text.append(f"  [{adapter.base_model}]", style="dim")
@@ -107,7 +121,7 @@ def show_routing_decision(
             adapter_text.append(f"\n  {source}", style="dim blue")
         grid.add_row("Adapter", adapter_text)
     else:
-        grid.add_row("Adapter", Text(trace.selected_adapter_id, style="bold magenta"))
+        grid.add_row("Adapter", Text(str(trace.selected_adapter_id), style="bold magenta"))
 
     backend_text = Text(backend_name or "—", style="green" if backend_name else "dim")
     grid.add_row("Backend", backend_text)
@@ -115,12 +129,12 @@ def show_routing_decision(
     if trace.latency_ms is not None:
         grid.add_row("Latency", Text(f"{trace.latency_ms:.0f} ms", style="dim"))
 
-    panel = Panel(
-        grid,
-        title=f"[bold {colour}] shiftgate routing decision [/bold {colour}]",
-        border_style=colour,
-        expand=False,
+    title = (
+        "[bold red] no adapter available [/bold red]"
+        if no_adapter
+        else f"[bold {colour}] shiftgate routing decision [/bold {colour}]"
     )
+    panel = Panel(grid, title=title, border_style=colour, expand=False)
     console.print()
     console.print(panel)
     console.print()
@@ -192,15 +206,23 @@ def show_explain_decision(
     method_labels = {
         "preferred": "[green]preferred_adapters list[/green]",
         "fallback": "[yellow]fallback_adapters list[/yellow]",
-        "tag_overlap": "[yellow]tag-overlap fallback[/yellow] (adapter not in any task list yet — run `shiftgate adapter add` with matching tags)",
+        "no_adapter_for_task": "[red]no adapter linked to the matched task[/red]",
     }
     method_display = method_labels.get(match_result.selection_method, match_result.selection_method)
 
     selected = match_result.selected_adapter
-    console.print(f"  [bold]Selected adapter:[/bold]  [bold magenta]{selected.id}[/bold magenta]")
-    console.print(f"  [bold]Base model:[/bold]        {selected.base_model}")
-    console.print(f"  [bold]Source:[/bold]            {_adapter_source_label(selected)}")
-    console.print(f"  [bold]Selection method:[/bold]  {method_display}")
+    if selected is None:
+        console.print("  [bold]Selected adapter:[/bold]  [bold red]No adapter available[/bold red]")
+        console.print(f"  [bold]Selection method:[/bold]  {method_display}")
+        console.print(
+            "  [dim]Add one with:[/dim]  "
+            f"[cyan]shiftgate adapter add <hf_repo> --tags {match_result.matched_task.id}[/cyan]"
+        )
+    else:
+        console.print(f"  [bold]Selected adapter:[/bold]  [bold magenta]{selected.id}[/bold magenta]")
+        console.print(f"  [bold]Base model:[/bold]        {selected.base_model}")
+        console.print(f"  [bold]Source:[/bold]            {_adapter_source_label(selected)}")
+        console.print(f"  [bold]Selection method:[/bold]  {method_display}")
     console.print()
     console.rule()
     console.print()
@@ -233,13 +255,18 @@ def show_adapter_table(adapters: list[AdapterEntry]) -> None:
     table.add_column("Base Model", style="dim")
     table.add_column("Tags", style="green")
     table.add_column("Source", style="blue")
+    table.add_column("Status", justify="center")
     table.add_column("Score", justify="right")
 
     for a in adapters:
         source = _adapter_source_label(a)
         score = f"{a.benchmark_score:.2f}" if a.benchmark_score is not None else "—"
         tags = ", ".join(a.task_tags) if a.task_tags else "—"
-        table.add_row(a.id, a.name, a.base_model, tags, source, score)
+        if a.status == "linked":
+            status = "[green]linked[/green]"
+        else:
+            status = "[yellow]unassigned[/yellow]"
+        table.add_row(a.id, a.name, a.base_model, tags, source, status, score)
 
     console.print(table)
 

{shiftgate-0.1.1 → shiftgate-0.1.2}/tests/test_registry.py

@@ -381,3 +381,68 @@ class TestAutoLinkAdapter:
 
         linked = _auto_link_adapter(adapter, task_reg)
         assert linked == []
+
+
+# ---------------------------------------------------------------------------
+# Adapter status field
+# ---------------------------------------------------------------------------
+
+class TestAdapterStatus:
+    def test_default_status_is_unassigned(self):
+        adapter = AdapterEntry(id="x", name="X", base_model="b")
+        assert adapter.status == "unassigned"
+
+    def test_status_persists_round_trip(self, tmp_shiftgate, monkeypatch):
+        import shiftgate.registry.adapter_registry as ar_mod
+
+        save_path = tmp_shiftgate / "adapters.json"
+        monkeypatch.setattr(ar_mod, "_USER_ADAPTERS_PATH", save_path)
+
+        adapter = AdapterEntry(
+            id="sql-lora", name="SQL", base_model="llama3",
+            task_tags=["sql"], hf_repo="org/sql-lora", status="linked",
+        )
+        AdapterRegistry(adapters=[adapter], source_path=save_path).save()
+
+        reloaded = AdapterRegistry.load().get_adapter("sql-lora")
+        assert reloaded.status == "linked"
+
+    def test_finish_adapter_add_marks_linked(self, tmp_shiftgate, monkeypatch):
+        """_finish_adapter_add should set status='linked' when a task is linked."""
+        import shiftgate.cli as cli_mod
+
+        # Quiet console output during the test.
+        monkeypatch.setattr(cli_mod.console, "print", lambda *a, **k: None)
+
+        task = TaskCluster(
+            id="code_sql", name="SQL", description="",
+            validation_examples=["x"], preferred_adapters=[],
+        )
+        task_reg = TaskRegistry(tasks=[task], source_path=tmp_shiftgate / "tasks.json")
+        adapter = AdapterEntry(
+            id="sql-lora", name="SQL", base_model="llama3",
+            task_tags=["sql"], hf_repo="org/sql-lora",
+        )
+        adapter_reg = AdapterRegistry(adapters=[adapter], source_path=tmp_shiftgate / "adapters.json")
+
+        cli_mod._finish_adapter_add(adapter, task_reg, adapter_reg)
+        assert adapter.status == "linked"
+
+    def test_finish_adapter_add_stays_unassigned_without_match(self, tmp_shiftgate, monkeypatch):
+        import shiftgate.cli as cli_mod
+
+        monkeypatch.setattr(cli_mod.console, "print", lambda *a, **k: None)
+
+        task = TaskCluster(
+            id="code_sql", name="SQL", description="",
+            validation_examples=["x"], preferred_adapters=[],
+        )
+        task_reg = TaskRegistry(tasks=[task], source_path=tmp_shiftgate / "tasks.json")
+        adapter = AdapterEntry(
+            id="music-lora", name="Music", base_model="llama3",
+            task_tags=["music"], hf_repo="org/music-lora",
+        )
+        adapter_reg = AdapterRegistry(adapters=[adapter], source_path=tmp_shiftgate / "adapters.json")
+
+        cli_mod._finish_adapter_add(adapter, task_reg, adapter_reg)
+        assert adapter.status == "unassigned"

{shiftgate-0.1.1 → shiftgate-0.1.2}/tests/test_router.py

@@ -172,17 +172,26 @@ class TestSelectAdapter:
         result = select_adapter(ranked, adapter_reg_partial)
         assert result.selected_adapter.id in {"adapter-y", "adapter-z"}
 
-    def test_raises_no_adapter_error_when_registry_empty(self, synthetic_tasks, tmp_path):
+    def test_no_adapter_when_registry_empty(self, synthetic_tasks, tmp_path):
+        """An empty registry yields a None adapter, never an exception or a guess."""
         empty_reg = AdapterRegistry(adapters=[], source_path=tmp_path / "adapters.json")
         query_emb = np.array([1.0, 0.0, 0.0], dtype=np.float32)
         ranked = top_k_tasks(query_emb, synthetic_tasks, k=3)
-        with pytest.raises(NoAdapterError):
-            select_adapter(ranked, empty_reg)
+        result = select_adapter(ranked, empty_reg)
+        assert result.selected_adapter is None
+        assert result.has_adapter is False
+        assert result.selection_method == "no_adapter_for_task"
+        # The matched task is still reported so the caller can prompt the user.
+        assert result.matched_task.id == "task_x"
+
+    def test_no_silent_fallback_when_task_has_no_linked_adapter(self, tmp_path):
+        """The bug fix: an unrelated adapter must NOT be picked for the matched task.
 
-    def test_tag_overlap_fallback_when_preferred_lists_empty(self, tmp_path):
-        """If preferred_adapters is empty for all tasks, adapter tags are used as fallback."""
-        task_sql = _make_task("code_sql", [0, 1, 0], adapter_ids=[])
-        task_py  = _make_task("code_python", [1, 0, 0], adapter_ids=[])
+        A music-style query matches a task that has no linked adapter; even
+        though a sql-lora exists in the registry, it must not be selected.
+        """
+        task_music = _make_task("audio_music", [0, 1, 0], adapter_ids=[])
+        task_py    = _make_task("code_python", [1, 0, 0], adapter_ids=[])
 
         sql_adapter = AdapterEntry(
             id="sql-lora",
@@ -192,25 +201,13 @@ class TestSelectAdapter:
         )
         reg = AdapterRegistry(adapters=[sql_adapter], source_path=tmp_path / "adapters.json")
 
-        query_emb = np.array([0.0, 1.0, 0.0], dtype=np.float32)
-        ranked = top_k_tasks(query_emb, [task_sql, task_py], k=2)
-        result = select_adapter(ranked, reg)
-
-        assert result.selected_adapter.id == "sql-lora"
-        assert result.selection_method == "tag_overlap"
-
-    def test_tag_overlap_selects_best_matching_adapter(self, tmp_path):
-        task_sql = _make_task("code_sql", [0, 1, 0], adapter_ids=[])
-
-        sql_adapter = AdapterEntry(id="sql-lora", name="SQL", base_model="x", task_tags=["sql", "code"])
-        py_adapter  = AdapterEntry(id="py-lora",  name="Py",  base_model="x", task_tags=["python"])
-
-        reg = AdapterRegistry(adapters=[sql_adapter, py_adapter], source_path=tmp_path / "adapters.json")
-        query_emb = np.array([0.0, 1.0, 0.0], dtype=np.float32)
-        ranked = top_k_tasks(query_emb, [task_sql], k=1)
+        query_emb = np.array([0.0, 1.0, 0.0], dtype=np.float32)  # matches audio_music
+        ranked = top_k_tasks(query_emb, [task_music, task_py], k=2)
         result = select_adapter(ranked, reg)
 
-        assert result.selected_adapter.id == "sql-lora"
+        assert result.selected_adapter is None
+        assert result.selection_method == "no_adapter_for_task"
+        assert result.matched_task.id == "audio_music"
 
     def test_fallback_adapters_are_tried(self, tmp_path):
         task_with_fallback = TaskCluster(