cade-cli 0.14.1__tar.gz → 0.15.0__tar.gz

{cade_cli-0.14.1 → cade_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cade-cli
-Version: 0.14.1
+Version: 0.15.0
 Summary: Cade - The CLI Agent from Arcade.dev
 Project-URL: Homepage, https://arcade.dev
 Project-URL: Documentation, https://docs.arcade.dev
@@ -43,7 +43,7 @@ Classifier: Topic :: Software Development
 Classifier: Topic :: Software Development :: Code Generators
 Classifier: Typing :: Typed
 Requires-Python: >=3.11
-Requires-Dist: agent-library<1.0.0,>=0.13.1
+Requires-Dist: agent-library<1.0.0,>=0.14.0
 Requires-Dist: anthropic<1.0.0,>=0.34.0
 Requires-Dist: arcade-core<5.0.0,>=4.7.0
 Requires-Dist: arcade-mcp-server<2.0.0,>=1.22.0
@@ -123,7 +123,7 @@ The install script detects your OS/arch, downloads the matching prebuilt binary
 `~/.local/bin` — no GitHub token required. Pin a version or install location:
 
 ```bash
-CADE_VERSION=0.14.1 CADE_INSTALL_DIR=/usr/local/bin \
+CADE_VERSION=0.15.0 CADE_INSTALL_DIR=/usr/local/bin \
   sh -c "$(curl -fsSL https://arcadeagent.dev/install)"
 ```
 
@@ -135,7 +135,11 @@ larger download). Force it with `CADE_VARIANT=cpu` or `CADE_VARIANT=gpu`.
 
 **Prerequisites:** Python 3.11+, an Arcade account ([arcade.dev](https://arcade.dev)) for cloud tools, and an LLM provider key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`). Skip the Arcade account with `--local-only` or `CADE_LOCAL_ONLY=1`.
 
+The first run walks you through picking a model provider and key (stored in your
+OS keyring); re-run it any time with `cade init`.
+
 ```bash
+cade init           # pick provider + model (runs automatically on first launch)
 cade login          # Arcade Cloud OAuth (skip with --local-only)
 cade --version
 ```
@@ -227,11 +231,15 @@ cade info / cade edit reviewer                # inspect / change config
 cade mem                                      # the current agent's memory (status)
 cade mem add ~/notes                          # index a directory
 cade mem search "auth design"                 # semantic search
+cade mem warm                                 # pre-load the semantic memory model
 ```
 
 Memory is per-agent — each agent has its own
 `~/.cade/data/agents/<id>/memory/.librarian/` index, so a `reviewer` agent's
-notes never leak into another.
+notes never leak into another. Cade advertises `Memory_*` tools without starting
+the memory server; the first actual memory call starts it and keeps it warm for
+later calls. Use `cade mem warm` when you want to pay that semantic-search
+warmup before a conversation.
 
 ---
 

{cade_cli-0.14.1 → cade_cli-0.15.0}/README.md

@@ -35,7 +35,7 @@ The install script detects your OS/arch, downloads the matching prebuilt binary
 `~/.local/bin` — no GitHub token required. Pin a version or install location:
 
 ```bash
-CADE_VERSION=0.14.1 CADE_INSTALL_DIR=/usr/local/bin \
+CADE_VERSION=0.15.0 CADE_INSTALL_DIR=/usr/local/bin \
   sh -c "$(curl -fsSL https://arcadeagent.dev/install)"
 ```
 
@@ -47,7 +47,11 @@ larger download). Force it with `CADE_VARIANT=cpu` or `CADE_VARIANT=gpu`.
 
 **Prerequisites:** Python 3.11+, an Arcade account ([arcade.dev](https://arcade.dev)) for cloud tools, and an LLM provider key (`OPENAI_API_KEY` or `ANTHROPIC_API_KEY`). Skip the Arcade account with `--local-only` or `CADE_LOCAL_ONLY=1`.
 
+The first run walks you through picking a model provider and key (stored in your
+OS keyring); re-run it any time with `cade init`.
+
 ```bash
+cade init           # pick provider + model (runs automatically on first launch)
 cade login          # Arcade Cloud OAuth (skip with --local-only)
 cade --version
 ```
@@ -139,11 +143,15 @@ cade info / cade edit reviewer                # inspect / change config
 cade mem                                      # the current agent's memory (status)
 cade mem add ~/notes                          # index a directory
 cade mem search "auth design"                 # semantic search
+cade mem warm                                 # pre-load the semantic memory model
 ```
 
 Memory is per-agent — each agent has its own
 `~/.cade/data/agents/<id>/memory/.librarian/` index, so a `reviewer` agent's
-notes never leak into another.
+notes never leak into another. Cade advertises `Memory_*` tools without starting
+the memory server; the first actual memory call starts it and keeps it warm for
+later calls. Use `cade mem warm` when you want to pay that semantic-search
+warmup before a conversation.
 
 ---
 

{cade_cli-0.14.1 → cade_cli-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cade-cli"
-version = "0.14.1"
+version = "0.15.0"
 description = "Cade - The CLI Agent from Arcade.dev"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -38,7 +38,7 @@ dependencies = [
     "prompt-toolkit>=3.0.52,<4.0.0",
     "httpx>=0.27.0,<1.0.0",
     "filelock>=3.0.0,<4.0.0",
-    "agent-library>=0.13.1,<1.0.0",
+    "agent-library>=0.14.0,<1.0.0",
     "croniter>=2.0.0,<4.0.0",
     "python-telegram-bot>=21.0,<22.0",
     "keyring>=24.0,<26.0",

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/cli/app.py

@@ -53,6 +53,7 @@ from cadecoder.core.runtime import set_runtime
 # output like `cade list` / `cade status` on a fresh install).
 _NO_RUNTIME_SUBCOMMANDS = frozenset(
     {
+        "init",
         "new",
         "use",
         "list",
@@ -225,6 +226,23 @@ def _doctor_paths(runtime: Any) -> dict[str, Any]:
     }
 
 
+@app.command(
+    name="init",
+    help="Set up (or change) your model provider and default model",
+    rich_help_panel=PANEL_SETUP,
+)
+def init_cmd() -> None:
+    from cadecoder.cli.onboarding import can_prompt, run_onboarding
+
+    if not can_prompt():
+        console.print(
+            "[red]cade init needs an interactive terminal.[/red] "
+            "Set OPENAI_API_KEY or ANTHROPIC_API_KEY instead."
+        )
+        raise typer.Exit(1)
+    run_onboarding(console, force=True)
+
+
 @app.command(
     name="doctor",
     help="Show paths, the current agent, and check the Cade home for problems",
@@ -366,6 +384,15 @@ def main_callback(
     if ctx.invoked_subcommand in _NO_RUNTIME_SUBCOMMANDS:
         return
 
+    # First-run setup: on a brand-new install, walk the user through picking a
+    # provider + model before we build the runtime, so the first session uses
+    # what they chose (not the hardcoded default). No-ops when already set up or
+    # when not attached to an interactive terminal (piped/CI).
+    from cadecoder.cli.onboarding import needs_onboarding, run_onboarding
+
+    if needs_onboarding():
+        run_onboarding(console)
+
     # Interaction + runtime-backed commands run as the current agent, auto-creating
     # a `default` agent on first run via build_runtime → ensure_current_agent.
     runtime = build_runtime()

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/cli/commands/mem.py

@@ -188,6 +188,32 @@ def _run_mem(args: list[str]) -> int:
     return 0
 
 
+def _warm_memory() -> int:
+    """Preload the text embedding model for the current agent's memory."""
+    try:
+        from librarian.processing.embed import get_embedder
+    except ImportError:
+        console.print(
+            "[red]agent-library is not installed.[/red] Install it into the "
+            "active environment: [bold]uv pip install agent-library[/bold]."
+        )
+        return 1
+
+    console.print("[cyan]Warming semantic memory search...[/cyan]")
+    try:
+        embedder = get_embedder()
+        dimension = embedder.dimension
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]Memory warmup failed:[/red] {exc}")
+        return 1
+
+    console.print(
+        f"[green]Memory semantic search is warm[/green] "
+        f"[dim](model={embedder.model_name}, dimension={dimension})[/dim]"
+    )
+    return 0
+
+
 def mem_command(ctx: typer.Context) -> None:
     """Run a ``cade mem`` subcommand scoped to the current agent.
 
@@ -208,6 +234,9 @@ def mem_command(ctx: typer.Context) -> None:
             f"[dim]cade mem: scoped to agent [bold]{agent_name}[/bold] "
             f"(storage={memory_home})[/dim]\n"
         )
+    elif forwarded[0] == "warm":
+        rc = _warm_memory()
+        raise typer.Exit(rc)
     rc = _run_mem(forwarded)
     raise typer.Exit(rc)
 
@@ -217,5 +246,6 @@ __all__ = (
     "_apply_memory_env",
     "_load_librarian_app",
     "_run_mem",
+    "_warm_memory",
     "mem_command",
 )

cade_cli-0.15.0/src/cadecoder/cli/onboarding.py

@@ -0,0 +1,317 @@
+"""First-run onboarding for the Cade CLI.
+
+A brand-new install has no obvious way to pick a model provider, and the silent
+provider fallback used to log a GPT model even when only an Anthropic key was
+set. This wizard runs once on first launch (and on demand via ``cade init``):
+it asks which provider to use, captures/stores an API key in the OS keyring,
+records a recommended default model, and writes the global config + default
+agent so the very first session uses exactly what the user chose.
+"""
+
+from __future__ import annotations
+
+import os
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.prompt import Confirm, Prompt
+
+from cadecoder.core import constants
+from cadecoder.core.paths import get_paths
+
+# Provider option ids surfaced in the wizard.
+_PROVIDER_ANTHROPIC = "anthropic"
+_PROVIDER_OPENAI = "openai"
+_PROVIDER_LOCAL = "local"
+
+# Keyring namespace for stored model keys.
+_KEYRING_SERVICE = "cade/model"
+
+
+def _marker_path():
+    """Path to the sentinel that records onboarding has completed."""
+    return get_paths().state_dir / "onboarded"
+
+
+def is_onboarded() -> bool:
+    """Return whether onboarding has completed at least once."""
+    return _marker_path().exists()
+
+
+def mark_onboarded() -> None:
+    """Record that onboarding has completed (idempotent)."""
+    paths = get_paths()
+    paths.ensure_base_dirs()
+    _marker_path().write_text("ok\n", encoding="utf-8")
+
+
+def _already_configured() -> bool:
+    """Heuristic: a pre-existing install that already has a usable provider.
+
+    Used to avoid wizarding users who upgrade into this feature with a working
+    setup. Env keys deliberately do NOT count here — a fresh install should
+    still see the wizard even if a key is exported (the user asked for that).
+    """
+    try:
+        from cadecoder.core.config import load_account_config
+
+        if load_account_config().email:
+            return True
+    except Exception:
+        pass
+    try:
+        from cadecoder.core.config import _load_global_settings
+
+        settings = _load_global_settings()
+        if settings.model_settings is not None and settings.model_settings.api_key:
+            return True
+    except Exception:
+        pass
+    return False
+
+
+def needs_onboarding() -> bool:
+    """Return whether the first-run wizard should run.
+
+    True only when onboarding has never completed and there's no evidence of a
+    prior working configuration (which is migrated by stamping the marker).
+    """
+    if is_onboarded():
+        return False
+    if _already_configured():
+        mark_onboarded()
+        return False
+    return True
+
+
+def can_prompt() -> bool:
+    """Return whether we're attached to an interactive terminal."""
+    import sys
+
+    try:
+        return sys.stdin.isatty() and sys.stderr.isatty()
+    except Exception:
+        return False
+
+
+def _store_key(provider: str, key: str) -> str:
+    """Store ``key`` for ``provider`` and return a secret reference.
+
+    Falls back to a plaintext config value only if secret storage is entirely
+    unavailable, so onboarding never hard-fails on a headless box.
+    """
+    from cadecoder.core.secrets import store_secret
+
+    try:
+        return store_secret(_KEYRING_SERVICE, f"{provider}_api_key", key)
+    except Exception:
+        # Last resort: persist the literal value in config. Not ideal, but the
+        # user explicitly entered it during setup.
+        return key
+
+
+def _gather_anthropic(console: Console) -> tuple[str | None, str | None]:
+    """Collect an Anthropic key. Returns (api_key_ref_or_none, host=None)."""
+    env_key = os.environ.get("ANTHROPIC_API_KEY")
+    if env_key:
+        console.print("[green]Found ANTHROPIC_API_KEY in your environment.[/green]")
+        if Confirm.ask(
+            "Save it to your keyring so Cade works in every session?",
+            default=True,
+            console=console,
+        ):
+            return _store_key(_PROVIDER_ANTHROPIC, env_key), None
+        return None, None  # rely on the environment variable
+
+    key = Prompt.ask("Paste your Anthropic API key", password=True, console=console).strip()
+    if not key:
+        raise OnboardingAborted("No API key entered.")
+    return _store_key(_PROVIDER_ANTHROPIC, key), None
+
+
+def _gather_openai(console: Console) -> tuple[str | None, str | None]:
+    """Collect an OpenAI key. Returns (api_key_ref_or_none, host=None)."""
+    env_key = os.environ.get("OPENAI_API_KEY")
+    if env_key:
+        console.print("[green]Found OPENAI_API_KEY in your environment.[/green]")
+        if Confirm.ask(
+            "Save it to your keyring so Cade works in every session?",
+            default=True,
+            console=console,
+        ):
+            return _store_key(_PROVIDER_OPENAI, env_key), None
+        return None, None
+
+    key = Prompt.ask("Paste your OpenAI API key", password=True, console=console).strip()
+    if not key:
+        raise OnboardingAborted("No API key entered.")
+    return _store_key(_PROVIDER_OPENAI, key), None
+
+
+def _gather_local(console: Console) -> tuple[str | None, str]:
+    """Collect a local/OpenAI-compatible endpoint. Returns (api_key, host)."""
+    host = Prompt.ask(
+        "Endpoint base URL",
+        default=constants.DEFAULT_OLLAMA_BASE_URL,
+        console=console,
+    ).strip()
+    # Many local servers ignore the key but require a non-empty value.
+    key = Prompt.ask(
+        "API key (most local servers accept any value)",
+        default="local",
+        console=console,
+    ).strip()
+    return (key or "local"), host
+
+
+class OnboardingAborted(Exception):
+    """Raised when the user cancels onboarding (Ctrl-C / empty required input)."""
+
+
+def run_onboarding(console: Console, *, force: bool = False) -> bool:
+    """Run the interactive setup wizard.
+
+    Args:
+        console: Rich console (stderr) to render prompts on.
+        force: Re-run even if already onboarded (``cade init``).
+
+    Returns:
+        True if a provider was configured; False if skipped/aborted.
+    """
+    if not force and not needs_onboarding():
+        return False
+
+    if not can_prompt():
+        # Non-interactive (piped/CI). Don't block; the provider error path will
+        # guide the user if nothing is configured.
+        return False
+
+    console.print(
+        Panel.fit(
+            "Welcome to [bold]Cade[/bold] — let's pick a model provider.\n"
+            "You can change this anytime with [bold]cade init[/bold].",
+            border_style="cyan",
+        )
+    )
+
+    has_anthropic = bool(os.environ.get("ANTHROPIC_API_KEY"))
+    has_openai = bool(os.environ.get("OPENAI_API_KEY"))
+
+    def _label(text: str, detected: bool) -> str:
+        return f"{text} [green](detected)[/green]" if detected else text
+
+    console.print()
+    console.print(f"  [bold]1[/bold]. {_label('Anthropic (Claude)', has_anthropic)}")
+    console.print(f"  [bold]2[/bold]. {_label('OpenAI (GPT)', has_openai)}")
+    console.print("  [bold]3[/bold]. Local / OpenAI-compatible (Ollama, vLLM, …)")
+    console.print()
+
+    default_choice = "1"
+    if has_openai and not has_anthropic:
+        default_choice = "2"
+
+    try:
+        choice = Prompt.ask(
+            "Choose your model provider",
+            choices=["1", "2", "3"],
+            default=default_choice,
+            console=console,
+        )
+
+        if choice == "1":
+            provider = _PROVIDER_ANTHROPIC
+            api_key_ref, host = _gather_anthropic(console)
+            agent_provider = "anthropic"
+        elif choice == "2":
+            provider = _PROVIDER_OPENAI
+            api_key_ref, host = _gather_openai(console)
+            agent_provider = "openai"
+        else:
+            provider = _PROVIDER_OPENAI  # OpenAI-compatible transport
+            api_key_ref, host = _gather_local(console)
+            agent_provider = "openai"
+
+        default_model = constants.RECOMMENDED_MODELS.get(
+            _PROVIDER_LOCAL if choice == "3" else provider,
+            constants.DEFAULT_AI_MODEL,
+        )
+        model = Prompt.ask("Model", default=default_model, console=console).strip() or default_model
+    except (KeyboardInterrupt, EOFError):
+        console.print("\n[yellow]Setup cancelled.[/yellow]")
+        return False
+    except OnboardingAborted as e:
+        console.print(f"[yellow]Setup cancelled: {e}[/yellow]")
+        return False
+
+    _persist(
+        provider=provider,
+        agent_provider=agent_provider,
+        model=model,
+        host=host,
+        api_key_ref=api_key_ref,
+    )
+
+    label = {"anthropic": "Anthropic", "openai": "OpenAI"}.get(agent_provider, agent_provider)
+    if host:
+        label = f"{label} @ {host}"
+    console.print()
+    console.print(
+        Panel.fit(
+            f"[bold]You're set up.[/bold]\n"
+            f"Model:    [cyan]{model}[/cyan]\n"
+            f"Provider: [cyan]{label}[/cyan]\n\n"
+            "Change it later with [bold]cade init[/bold] or edit "
+            f"[dim]{get_paths().global_config}[/dim].",
+            border_style="green",
+        )
+    )
+    return True
+
+
+def _persist(
+    *,
+    provider: str,
+    agent_provider: str,
+    model: str,
+    host: str | None,
+    api_key_ref: str | None,
+) -> None:
+    """Write the chosen provider/model to global config + the default agent."""
+    from cadecoder.core import agent as agent_mod
+    from cadecoder.core.config import (
+        ModelConfig,
+        _load_global_settings,
+        _save_global_settings,
+        reset_config,
+    )
+
+    settings = _load_global_settings()
+    settings.provider = agent_provider
+    settings.model = model
+    settings.model_settings = ModelConfig(
+        provider=agent_provider, model=model, host=host, api_key=api_key_ref
+    )
+    _save_global_settings(settings)
+
+    # Make the active/default agent match the choice so the first session uses
+    # it (the agent — not the global config — is the runtime source of truth).
+    name = agent_mod.get_active_agent_name() or "default"
+    existing = agent_mod.resolve(name)
+    if existing is None:
+        existing = agent_mod.new_agent(name, description="Default Cade agent", model=model)
+    existing.model = model
+    existing.provider = agent_provider
+    agent_mod.save_agent(existing)
+    agent_mod.set_active_agent(existing.name)
+
+    mark_onboarded()
+
+    # Apply immediately: refresh config caches and re-register providers so the
+    # current process uses the new key/model without a restart.
+    reset_config()
+    try:
+        from cadecoder.providers import initialize_providers
+
+        initialize_providers()
+    except Exception:
+        pass

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/core/config.py

@@ -399,6 +399,9 @@ def get_config() -> AppConfig:
 def reset_config() -> None:
     global _config
     _config = None
+    # AppConfig caches its own class-level singleton; drop it too so a fresh
+    # get_config() reflects on-disk changes (e.g. after onboarding writes config).
+    AppConfig._instance = None
     _load_global_settings.cache_clear()
     load_account_config.cache_clear()
 

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/core/constants.py

@@ -12,6 +12,18 @@ from typing import Final
 
 DEFAULT_AI_MODEL: Final[str] = "claude-opus-4-7"
 
+# Recommended default model per provider. Used by onboarding and provider
+# selection so that, e.g., a user who only configures OpenAI gets a GPT model
+# rather than the Anthropic default (which would have no usable provider).
+RECOMMENDED_MODELS: Final[dict[str, str]] = {
+    "anthropic": "claude-opus-4-7",
+    "openai": "gpt-5.2",
+    "ollama": "qwen3:4b",
+}
+
+# Suggested base URL for a local Ollama (OpenAI-compatible) endpoint.
+DEFAULT_OLLAMA_BASE_URL: Final[str] = "http://localhost:11434/v1"
+
 # ------------------------------------------------------------------------------
 # Project & File Operations
 # ------------------------------------------------------------------------------

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/core/errors.py

@@ -90,7 +90,8 @@ def get_provider_config_help() -> str:
     return """
 No AI provider configured.
 
-Options:
+Run 'cade init' to set up a provider interactively, or set a key:
+
   Remote LLM:
     export OPENAI_API_KEY="your-key"
       or
@@ -102,3 +103,35 @@ Options:
 
     Or just: --endpoint <url> --model <model>
 """.strip()
+
+
+def provider_unavailable_help(model: str) -> str:
+    """Return an actionable message when a model's provider isn't configured.
+
+    Names the specific key the configured model needs, instead of silently
+    falling back to a different provider/model (which produced confusing
+    "used gpt-* but I set an Anthropic key" reports).
+
+    Args:
+        model: The configured model identifier.
+
+    Returns:
+        A multi-line help string naming the required provider key.
+    """
+    from cadecoder.core.model_specs import provider_family
+
+    family = provider_family(model)
+    if family == "anthropic":
+        need = "It's an Anthropic model — set ANTHROPIC_API_KEY."
+    elif family == "openai":
+        need = "It's an OpenAI model — set OPENAI_API_KEY."
+    else:
+        need = (
+            "Set OPENAI_API_KEY (with OPENAI_BASE_URL for a local/compatible "
+            "endpoint) or ANTHROPIC_API_KEY."
+        )
+    return (
+        f"No API key is configured for the active model '{model}'.\n"
+        f"{need}\n"
+        "Run 'cade init' to set up (or switch) a provider."
+    )

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/core/secrets.py

@@ -52,7 +52,10 @@ def resolve(ref: str) -> str:
         rest = ref[len("keyring://") :]
         if "/" not in rest:
             raise SecretError(f"keyring ref must be service/name, got {ref!r}")
-        service, name = rest.split("/", 1)
+        # Split on the LAST slash so service names that themselves contain a
+        # slash (e.g. "cade/model") round-trip correctly. Matches the resolver
+        # in core.config._secret_get.
+        service, name = rest.rsplit("/", 1)
         value = _keyring_get(service, name)
         if not value:
             raise SecretError(f"keyring {service}/{name} not set")

{cade_cli-0.14.1 → cade_cli-0.15.0}/src/cadecoder/execution/orchestrator.py

@@ -11,7 +11,7 @@ from cadecoder.ai.prompts import build_system_prompt
 from cadecoder.core.constants import (
     MAX_EXECUTION_ITERATIONS,
 )
-from cadecoder.core.errors import get_provider_config_help
+from cadecoder.core.errors import get_provider_config_help, provider_unavailable_help
 from cadecoder.core.logging import log
 from cadecoder.core.runtime import get_runtime
 from cadecoder.core.types import ExecutionEventType, extract_tool_output_content
@@ -176,17 +176,22 @@ class Orchestrator:
         # user has explicitly configured a temperature (global or per-context).
         self.temperature = runtime.temperature
 
-        # Select provider based on model name if not explicitly provided
+        # Select provider based on model name if not explicitly provided.
+        # IMPORTANT: do NOT silently fall back to a different default provider
+        # when the configured model's provider is unavailable — that produced
+        # confusing behavior (e.g. logging a GPT model while the user had set an
+        # Anthropic key). Fail loudly with a model-specific message instead.
         if provider is not None:
             self.provider = provider
         else:
             self.provider = get_provider_for_model(self.default_model)
-            if not self.provider:
-                # Fallback to default if model-based selection fails
-                self.provider = provider_registry.get_default()
 
         if not self.provider:
-            raise ValueError(get_provider_config_help())
+            # No provider at all → generic setup help; otherwise name the key the
+            # configured model needs.
+            if not provider_registry.available_providers:
+                raise ValueError(get_provider_config_help())
+            raise ValueError(provider_unavailable_help(self.default_model))
 
         self.tool_manager = tool_manager
         self._tools_cache: list[dict[str, Any]] | None = None