feat: Introduce UnconfiguredProvider class to handle unconfigured integrations (#443)

Author: vamaq

src/galileo/__future__/integration.py

@@ -18,7 +18,14 @@
 from galileo.utils.exceptions import APIException
 
 if TYPE_CHECKING:
-    from galileo.__future__.provider import AnthropicProvider, AzureProvider, BedrockProvider, OpenAIProvider, Provider
+    from galileo.__future__.provider import (
+        AnthropicProvider,
+        AzureProvider,
+        BedrockProvider,
+        OpenAIProvider,
+        Provider,
+        UnconfiguredProvider,
+    )
 
 logger = logging.getLogger(__name__)
 
@@ -355,7 +362,7 @@ def _to_provider(cls, integration_db: IntegrationDB) -> Provider:
     # Convenience properties for accessing configured integrations by type
 
     @classmethod
-    def _get_integration_by_name(cls, integration_name: str) -> Provider | None:
+    def _get_integration_by_name(cls, integration_name: str) -> Provider | UnconfiguredProvider:
         """
         Get a configured integration by name.
 
@@ -364,26 +371,24 @@ def _get_integration_by_name(cls, integration_name: str) -> Provider | None:
 
         Returns
         -------
-            Provider | None: The provider if found, None otherwise.
+            Provider | UnconfiguredProvider: The provider if found, or an UnconfiguredProvider
+                            that raises helpful errors when accessed.
                             If multiple integrations of the same type exist,
                             returns the selected one, or the first one if none selected.
         """
         try:
             providers_list = cls.list()
             # Type narrowing: list() without all=True returns list[Provider]
             if providers_list and isinstance(providers_list[0], str):
-                return None
+                return UnconfiguredProvider(integration_name)
 
             # Cast is safe because we checked for strings above
             providers = cast(list[Provider], providers_list)
             matching = [p for p in providers if p.name == integration_name]
 
             if not matching:
-                logger.warning(
-                    f"Integration.{integration_name}: No '{integration_name}' integration configured. "
-                    f"Create one using Integration.create_{integration_name.replace('aws_', '')}()"
-                )
-                return None
+                logger.debug(f"Integration.{integration_name}: No '{integration_name}' integration configured.")
+                return UnconfiguredProvider(integration_name)
 
             # If multiple matches, prefer the selected one
             selected = [p for p in matching if p.is_selected]
@@ -394,16 +399,17 @@ def _get_integration_by_name(cls, integration_name: str) -> Provider | None:
             return matching[0]
         except Exception as e:
             logger.error(f"Integration._get_integration_by_name: failed to get {integration_name}: {e}")
-            return None
+            return UnconfiguredProvider(integration_name)
 
     @classproperty
-    def openai(cls) -> Provider | None:
+    def openai(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured OpenAI integration.
 
         Returns
         -------
-            OpenAIProvider | None: The OpenAI provider if configured, None otherwise.
+            OpenAIProvider | UnconfiguredProvider: The OpenAI provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -414,13 +420,14 @@ def openai(cls) -> Provider | None:
         return cls._get_integration_by_name("openai")
 
     @classproperty
-    def azure(cls) -> Provider | None:
+    def azure(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured Azure OpenAI integration.
 
         Returns
         -------
-            AzureProvider | None: The Azure provider if configured, None otherwise.
+            AzureProvider | UnconfiguredProvider: The Azure provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -431,13 +438,14 @@ def azure(cls) -> Provider | None:
         return cls._get_integration_by_name("azure")
 
     @classproperty
-    def bedrock(cls) -> Provider | None:
+    def bedrock(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured AWS Bedrock integration.
 
         Returns
         -------
-            BedrockProvider | None: The Bedrock provider if configured, None otherwise.
+            BedrockProvider | UnconfiguredProvider: The Bedrock provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -448,13 +456,14 @@ def bedrock(cls) -> Provider | None:
         return cls._get_integration_by_name("aws_bedrock")
 
     @classproperty
-    def anthropic(cls) -> Provider | None:
+    def anthropic(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured Anthropic (Claude) integration.
 
         Returns
         -------
-            AnthropicProvider | None: The Anthropic provider if configured, None otherwise.
+            AnthropicProvider | UnconfiguredProvider: The Anthropic provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -465,13 +474,14 @@ def anthropic(cls) -> Provider | None:
         return cls._get_integration_by_name("anthropic")
 
     @classproperty
-    def vertex_ai(cls) -> Provider | None:
+    def vertex_ai(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured Google Vertex AI integration.
 
         Returns
         -------
-            Provider | None: The Vertex AI provider if configured, None otherwise.
+            Provider | UnconfiguredProvider: The Vertex AI provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -482,13 +492,14 @@ def vertex_ai(cls) -> Provider | None:
         return cls._get_integration_by_name("vertex_ai")
 
     @classproperty
-    def mistral(cls) -> Provider | None:
+    def mistral(cls) -> Provider | UnconfiguredProvider:
         """
         Get the configured Mistral AI integration.
 
         Returns
         -------
-            Provider | None: The Mistral provider if configured, None otherwise.
+            Provider | UnconfiguredProvider: The Mistral provider if configured,
+                or UnconfiguredProvider that raises helpful errors when accessed.
 
         Examples
         --------
@@ -633,4 +644,5 @@ def create_anthropic(cls, *, token: str) -> AnthropicProvider:
     GenericProvider,
     OpenAIProvider,
     Provider,
+    UnconfiguredProvider,
 )

src/galileo/__future__/provider.py

@@ -6,7 +6,7 @@
 from typing import Any
 
 from galileo.__future__.shared.base import StateManagementMixin, SyncState
-from galileo.__future__.shared.exceptions import APIError, ValidationError
+from galileo.__future__.shared.exceptions import APIError, IntegrationNotConfiguredError, ValidationError
 from galileo.config import GalileoPythonConfig
 from galileo.resources.api.integrations import (
     create_or_update_integration_integrations_anthropic_put,
@@ -837,5 +837,54 @@ def _get_integration_name(self) -> IntegrationName:
         return self._integration_name
 
 
+class UnconfiguredProvider:
+    """
+    Placeholder for integrations that are not configured.
+
+    This class implements the Null Object Pattern to provide helpful error messages
+    when users attempt to access an integration that doesn't exist. Instead of
+    returning None (which leads to cryptic AttributeError messages), this class
+    raises IntegrationNotConfiguredError with guidance on how to fix the issue.
+
+    Examples
+    --------
+        # When Azure is not configured:
+        >>> Integration.azure.models
+        IntegrationNotConfiguredError: No 'azure' integration configured.
+        Create one using Integration.create_azure() or configure it in the Galileo console.
+
+        # Truthiness check still works:
+        >>> if Integration.azure:
+        ...     print("configured")
+        ... else:
+        ...     print("not configured")
+        not configured
+    """
+
+    _integration_name: str
+
+    def __init__(self, integration_name: str) -> None:
+        # Use object.__setattr__ to bypass our custom __setattr__
+        object.__setattr__(self, "_integration_name", integration_name)
+
+    def __bool__(self) -> bool:
+        """Allow truthiness checks: 'if Integration.azure:' returns False."""
+        return False
+
+    def __getattr__(self, name: str) -> None:
+        """Raise helpful error when any attribute is accessed."""
+        raise IntegrationNotConfiguredError(self._integration_name)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        """Raise helpful error when any attribute is set."""
+        raise IntegrationNotConfiguredError(self._integration_name)
+
+    def __repr__(self) -> str:
+        return f"UnconfiguredProvider('{self._integration_name}')"
+
+    def __str__(self) -> str:
+        return f"UnconfiguredProvider('{self._integration_name}')"
+
+
 # Import Model here to avoid circular imports
 from galileo.__future__.model import Model  # noqa: E402

src/galileo/__future__/shared/exceptions.py

@@ -1,4 +1,4 @@
-from typing import Optional
+from typing import ClassVar, Optional
 
 
 class GalileoFutureError(Exception):
@@ -68,3 +68,31 @@ def __init__(self, message: str, sync_state: Optional[str] = None, original_erro
         super().__init__(message)
         self.sync_state = sync_state
         self.original_error = original_error
+
+
+class IntegrationNotConfiguredError(GalileoFutureError):
+    """
+    Raised when attempting to use an integration that is not configured.
+
+    This error provides guidance on how to create or configure the integration.
+    """
+
+    # Integrations that have SDK create methods
+    _SUPPORTED_CREATE_METHODS: ClassVar[dict[str, str]] = {
+        "openai": "Integration.create_openai()",
+        "azure": "Integration.create_azure()",
+        "aws_bedrock": "Integration.create_bedrock()",
+        "anthropic": "Integration.create_anthropic()",
+    }
+
+    def __init__(self, integration_name: str):
+        create_method = self._SUPPORTED_CREATE_METHODS.get(integration_name)
+        if create_method:
+            message = (
+                f"No '{integration_name}' integration configured.\n"
+                f"Create one using {create_method} or configure it in the Galileo console."
+            )
+        else:
+            message = f"No '{integration_name}' integration configured.\nConfigure it in the Galileo console."
+        super().__init__(message)
+        self.integration_name = integration_name