fix(rag): don't let a broken native dep crash every agent import

A broken native dependency under the optional RAG stack — most commonly
torchcodec/FFmpeg pulled in transitively by sentence-transformers, but
also an arch-mismatched faiss build — raises RuntimeError/OSError at
import, not ImportError. The guard in rag/sdk.py only caught ImportError,
so the exception escaped and killed the entire import chain: importing
gaia.agents.chat (or any agent that transitively imports RAG) died at
module load even when RAG was never used, taking `gaia chat` and friends
down with it.

Broaden the sentence-transformers and faiss guards to treat any import
failure as "not installed", and capture the failure reason so the loud,
deferred error in RAGSDK._check_dependencies() distinguishes "not
installed" (reinstall) from "installed but broken" (fix the underlying
native dep, e.g. FFmpeg) instead of misdirecting the user.

Author: Ovtcharov

src/gaia/rag/sdk.py

@@ -30,15 +30,26 @@
     except ImportError:
         PdfReader = None
 
+# Not just ImportError: a broken native dependency (e.g. torchcodec/FFmpeg
+# pulled in by sentence-transformers, or an arch-mismatched faiss build) raises
+# RuntimeError/OSError at import. Treat that the same as "not installed" so a
+# bad install can't crash every module that transitively imports RAG; the loud,
+# actionable error is deferred to RAGSDK._check_dependencies() at point of use.
+# Capture the reason so that error can tell "not installed" from "installed but
+# broken" instead of misdirecting the user to reinstall a package they have.
+_SENTENCE_TRANSFORMERS_IMPORT_ERROR = None
 try:
     from sentence_transformers import SentenceTransformer
-except ImportError:
+except Exception as _e:  # pylint: disable=broad-except
     SentenceTransformer = None
+    _SENTENCE_TRANSFORMERS_IMPORT_ERROR = _e
 
+_FAISS_IMPORT_ERROR = None
 try:
     import faiss
-except ImportError:
+except Exception as _e:  # pylint: disable=broad-except
     faiss = None
+    _FAISS_IMPORT_ERROR = _e
 
 from gaia.chat.sdk import AgentConfig, AgentSDK
 from gaia.logger import get_logger
@@ -225,6 +236,23 @@ def _check_dependencies(self):
                 f"Or install packages directly:\n"
                 f"  uv pip install {' '.join(missing)}\n"
             )
+            # A package that is installed but failed to import (broken native
+            # deps) needs a different fix than a missing one — name the cause.
+            broken = []
+            if SentenceTransformer is None and _SENTENCE_TRANSFORMERS_IMPORT_ERROR:
+                broken.append(
+                    f"  sentence-transformers: {_SENTENCE_TRANSFORMERS_IMPORT_ERROR}"
+                )
+            if faiss is None and _FAISS_IMPORT_ERROR:
+                broken.append(f"  faiss: {_FAISS_IMPORT_ERROR}")
+            if broken:
+                error_msg += (
+                    "\nThe package(s) below are installed but failed to load — "
+                    "reinstalling won't help until the underlying error is fixed "
+                    "(e.g. a missing FFmpeg for torchcodec):\n"
+                    + "\n".join(broken)
+                    + "\n"
+                )
             raise ImportError(error_msg)
 
     def _safe_open(self, file_path: str, mode="rb"):

tests/unit/rag/test_dependency_guard.py

@@ -0,0 +1,59 @@
+# Copyright(C) 2024-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Unit tests for RAG dependency-import guards.
+
+A broken native dependency (e.g. torchcodec/FFmpeg under sentence-transformers,
+or an arch-mismatched faiss build) raises ``RuntimeError``/``OSError`` at import
+rather than ``ImportError``. The guard in ``gaia.rag.sdk`` must treat that the
+same as "not installed" so it cannot crash every module that transitively
+imports RAG, while still surfacing a loud, actionable error at point of use.
+"""
+
+import importlib
+from unittest.mock import patch
+
+import pytest
+
+# Importing the module must NOT raise even when an optional native dep is broken
+# in the environment — that is the regression this guard protects against.
+sdk = importlib.import_module("gaia.rag.sdk")
+
+
+def _bare_sdk():
+    """An RAGSDK instance without running __init__ (it only needs the method)."""
+    return sdk.RAGSDK.__new__(sdk.RAGSDK)
+
+
+def test_module_imports_without_optional_deps():
+    """The module is importable regardless of optional-dependency health."""
+    assert hasattr(sdk, "RAGSDK")
+    assert hasattr(sdk, "_SENTENCE_TRANSFORMERS_IMPORT_ERROR")
+    assert hasattr(sdk, "_FAISS_IMPORT_ERROR")
+
+
+def test_broken_install_reports_actionable_cause():
+    """An installed-but-broken dep surfaces the captured cause, not just 'install it'."""
+    cause = RuntimeError("Could not load libtorchcodec (FFmpeg not found)")
+    with (
+        patch.object(sdk, "SentenceTransformer", None),
+        patch.object(sdk, "_SENTENCE_TRANSFORMERS_IMPORT_ERROR", cause),
+    ):
+        with pytest.raises(ImportError) as excinfo:
+            _bare_sdk()._check_dependencies()
+    msg = str(excinfo.value)
+    assert "installed but failed to load" in msg
+    assert "libtorchcodec" in msg  # the captured cause is named
+
+
+def test_genuinely_missing_dep_omits_broken_section():
+    """A simply-missing dep gets install instructions, not the broken-load hint."""
+    with (
+        patch.object(sdk, "SentenceTransformer", None),
+        patch.object(sdk, "_SENTENCE_TRANSFORMERS_IMPORT_ERROR", None),
+    ):
+        with pytest.raises(ImportError) as excinfo:
+            _bare_sdk()._check_dependencies()
+    msg = str(excinfo.value)
+    assert "sentence-transformers" in msg
+    assert "installed but failed to load" not in msg