fix(connectors): actionable error when keyring missing on base install (#1622)

A bare `pip install amd-gaia` (no extras) ships `gaia connectors` as a
base command, but `keyring` lives only in the `[ui]`/`[api]`/`[dev]`
extras — so `gaia connectors list`/`status` and the provider-credential
paths crashed with a raw `ModuleNotFoundError: No module named
'keyring'` that named neither the cause nor the fix. Now those
subcommands fail loudly with an actionable `ConnectorsError` — `gaia
connectors needs the 'keyring' package … pip install keyring (or pip
install "amd-gaia[ui]")` — which the CLI prints to stderr instead of a
traceback.

This is the base-CLI half of the gap #1617/#1620 fixed for the `[api]`
partner recipe. It implements the issue's Option 3 (guarded import) —
the part the issue itself calls "worth doing regardless." The larger
base-dep-vs-`[connectors]`-extra packaging decision (Options 1/2) is
**left to a maintainer** (flagged for @kovtcharov-amd in the issue);
this guard holds regardless of where `keyring` ultimately lands, and on
its own satisfies the issue's acceptance branch "*fails with an
actionable error naming the exact install command.*"

Refs #1621

## Test plan

- [ ] `python -m pytest tests/unit/connectors/test_keyring_guard.py -x`
passes (new regression guard: import without `keyring` →
`ConnectorsError` naming `pip install`; with `keyring` → real module
re-exported)
- [ ] `python -m pytest tests/unit/connectors/ -x` passes (no regression
in store/mcp_server keyring usage)
- [ ] `python util/lint.py --all` passes
- [ ] Manual: in a venv with **no** `keyring` installed, `gaia
connectors list` prints `Connectors error: gaia connectors needs the
'keyring' package … pip install keyring …` and exits non-zero (instead
of a `ModuleNotFoundError` traceback)

Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Tomasz Iniewicz <itomek@users.noreply.github.com>

Author: github-actions[bot]

src/gaia/connectors/_keyring.py

@@ -0,0 +1,33 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""
+Guarded import of the optional ``keyring`` dependency (#1621).
+
+``gaia connectors`` is a *base* CLI command, but ``keyring`` ships only in the
+``[ui]``/``[api]``/``[dev]`` extras — never in base ``install_requires``. A bare
+``pip install amd-gaia`` therefore reaches ``import keyring`` deep in the store
+on the list/status/credential subcommands and dies with a raw
+``ModuleNotFoundError`` that names neither the cause nor the fix.
+
+Importing ``keyring`` through this module turns that into the actionable error
+CLAUDE.md's "fail loudly" rule requires: it names what failed, what to install,
+and where to read more. The re-exported name is the real ``keyring`` module
+(with ``keyring.errors`` pre-imported), so callers use it exactly as before.
+"""
+
+from __future__ import annotations
+
+from gaia.connectors.errors import ConnectorsError
+
+try:
+    import keyring
+    import keyring.errors  # noqa: F401  # re-exported as ``keyring.errors``
+except ImportError as e:  # pragma: no cover - exercised via reload in tests
+    raise ConnectorsError(
+        "gaia connectors needs the 'keyring' package, which is not installed. "
+        'Install it with `pip install keyring` (or `pip install "amd-gaia[ui]"` '
+        "for the full Agent UI install). "
+        "See docs/sdk/infrastructure/connections.mdx."
+    ) from e
+
+__all__ = ["keyring"]

src/gaia/connectors/mcp_server.py

@@ -27,8 +27,7 @@
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional
 
-import keyring
-
+from gaia.connectors._keyring import keyring  # actionable error if missing (#1621)
 from gaia.connectors.errors import ConnectorsError
 from gaia.connectors.handler import register_handler
 from gaia.connectors.spec import ConnectorSpec

src/gaia/connectors/store.py

@@ -35,9 +35,7 @@
 import time
 from typing import List, Optional
 
-import keyring
-import keyring.errors
-
+from gaia.connectors._keyring import keyring  # actionable error if missing (#1621)
 from gaia.connectors.errors import (
     AuthRequiredError,
     ConnectorsError,

tests/unit/connectors/test_keyring_guard.py

@@ -0,0 +1,71 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""Regression test for issue #1621.
+
+``gaia connectors`` is a *base* CLI command, but ``keyring`` ships only in the
+``[ui]``/``[api]``/``[dev]`` extras. A bare ``pip install amd-gaia`` reaches
+``import keyring`` deep in ``gaia.connectors.store`` on the list/status/credential
+subcommands and used to die with a raw ``ModuleNotFoundError`` that named neither
+the cause nor the fix.
+
+``gaia.connectors._keyring`` guards that import and re-raises a ``ConnectorsError``
+naming the exact install command — CLAUDE.md's "fail loudly / actionable errors"
+rule. The CLI handler (``gaia.connectors.cli.handle``) catches ``ConnectorsError``
+and prints it to stderr, so the user sees the install hint instead of a traceback.
+
+The promotion of ``keyring`` to a base dep vs. a dedicated extra is a separate
+maintainer packaging decision; this guard is the defense-in-depth half that holds
+regardless of where the dependency ultimately lives.
+"""
+
+from __future__ import annotations
+
+import builtins
+import importlib
+import sys
+
+import pytest
+
+from gaia.connectors.errors import ConnectorsError
+
+
+def test_keyring_guard_raises_actionable_error(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Importing the keyring shim without ``keyring`` installed must raise an
+    actionable ``ConnectorsError`` (not a bare ``ModuleNotFoundError``)."""
+    real_import = builtins.__import__
+
+    def _blocked_import(name, *args, **kwargs):
+        if name == "keyring" or name.startswith("keyring."):
+            raise ModuleNotFoundError("No module named 'keyring'")
+        return real_import(name, *args, **kwargs)
+
+    # Drop any cached keyring + shim modules so the guarded import re-runs.
+    for mod in list(sys.modules):
+        if (
+            mod == "keyring"
+            or mod.startswith("keyring.")
+            or mod == "gaia.connectors._keyring"
+        ):
+            monkeypatch.delitem(sys.modules, mod, raising=False)
+
+    monkeypatch.setattr(builtins, "__import__", _blocked_import)
+
+    with pytest.raises(ConnectorsError) as excinfo:
+        importlib.import_module("gaia.connectors._keyring")
+
+    msg = str(excinfo.value)
+    assert "keyring" in msg
+    assert "pip install" in msg
+
+    # Restore a clean shim for the rest of the suite (keyring is available again
+    # now that the monkeypatch is being torn down at function exit).
+    sys.modules.pop("gaia.connectors._keyring", None)
+
+
+def test_keyring_shim_reexports_real_module() -> None:
+    """When ``keyring`` IS installed the shim re-exports the real module,
+    so ``store``/``mcp_server`` keep using ``keyring`` / ``keyring.errors``."""
+    shim = importlib.import_module("gaia.connectors._keyring")
+    real = importlib.import_module("keyring")
+    assert shim.keyring is real
+    assert hasattr(shim.keyring, "errors")