refactor(factory): Implement Provider Registry Pattern (Priority 6) (#128)

Priority 6: Provider Registry Pattern

- Implemented Strategy Pattern in src/clients/registry.py
- Decoupled client creation from factory
- Added HuggingFaceProvider and OpenAIProvider

✅ All checks passed

src/clients/factory.py

@@ -4,13 +4,19 @@ from typing import Any
 
 import structlog
 from agent_framework import BaseChatClient
-from agent_framework.openai import OpenAIChatClient
 
-from src.clients.huggingface import HuggingFaceChatClient
+from src.clients.providers import HuggingFaceProvider, OpenAIProvider
+from src.clients.registry import ProviderRegistry
 from src.utils.config import settings
 
 logger = structlog.get_logger()
 
+# Register strategies in order of priority
+# 1. OpenAI (Specific key or Env)
+ProviderRegistry.register(OpenAIProvider())
+# 2. HuggingFace (Free Fallback)
+ProviderRegistry.register(HuggingFaceProvider())
+
 
 def get_chat_client(
     provider: str | None = None,
@@ -21,56 +27,30 @@ def get_chat_client(
     """
     Factory for creating chat clients.
 
-    Auto-detection priority:
+    Delegates to ProviderRegistry for strategy selection.
+
+    Auto-detection priority (via Registry):
     1. Explicit provider parameter
-    2. API key prefix detection (sk- → OpenAI, sk-ant- → Anthropic)
-    3. OpenAI key from env (Best Function Calling)
-    4. Gemini key from env (Best Context/Cost)
-    5. HuggingFace (Free Fallback)
+    2. API key prefix detection (sk- → OpenAI)
+    3. OpenAI key from env
+    4. HuggingFace (Free Fallback)
 
     Args:
-        provider: Force specific provider ("openai", "gemini", "huggingface")
-        api_key: Override API key for the provider (auto-detects provider from prefix)
+        provider: Force specific provider ("openai", "huggingface")
+        api_key: Override API key
         model_id: Override default model ID
         **kwargs: Additional arguments for the client
 
     Returns:
-        Configured BaseChatClient instance (Namespace Neutral)
+        Configured BaseChatClient instance
 
     Raises:
-        ValueError: If an unsupported provider is explicitly requested
-        NotImplementedError: If Gemini or Anthropic is requested (not yet implemented)
+        ValueError: If an unsupported provider is requested
     """
-    # Normalize provider to lowercase for case-insensitive matching
-    normalized = provider.lower() if provider is not None else None
-
-    # FIX: Auto-detect provider from API key prefix when not explicitly set
-    # This enables BYOK (Bring Your Own Key) from Gradio without explicit provider
-    # Order matters: "sk-ant-" must be checked before "sk-" (both start with "sk-")
-    if normalized is None and api_key:
-        if api_key.startswith("sk-"):
-            normalized = "openai"
-        # HF tokens start with "hf_" - no auto-detection needed (falls through to default)
-
-    # Validate explicit provider requests early
-    valid_providers = (None, "openai", "huggingface")
-    if normalized not in valid_providers:
-        raise ValueError(f"Unsupported provider: {provider!r}")
-
-    # 1. OpenAI (Standard / Paid Tier)
-    if normalized == "openai" or (normalized is None and settings.has_openai_key):
-        logger.info("Using OpenAI Chat Client")
-        return OpenAIChatClient(
-            model_id=model_id or settings.openai_model,
-            api_key=api_key or settings.openai_api_key,
-            **kwargs,
-        )
-
-    # 4. HuggingFace (Free Fallback)
-    # This is the default if no other keys are present
-    logger.info("Using HuggingFace Chat Client (Free Tier)")
-    return HuggingFaceChatClient(
-        model_id=model_id or settings.huggingface_model,
-        api_key=api_key or settings.hf_token,
+    return ProviderRegistry.get_client(
+        settings=settings,
+        provider=provider,
+        api_key=api_key,
+        model_id=model_id,
         **kwargs,
     )

src/clients/providers.py

@@ -0,0 +1,84 @@
+"""
+LLM Client Provider Strategies.
+"""
+
+from typing import Any
+
+from agent_framework import BaseChatClient
+from agent_framework.openai import OpenAIChatClient
+
+from src.clients.huggingface import HuggingFaceChatClient
+from src.clients.registry import ClientProvider
+from src.utils.config import Settings
+
+
+class OpenAIProvider(ClientProvider):
+    """Strategy for OpenAI client creation."""
+
+    @property
+    def name(self) -> str:
+        return "OpenAI"
+
+    def can_handle(
+        self, provider_name: str | None, api_key: str | None, settings: Settings
+    ) -> bool:
+        # 1. Explicit request
+        if provider_name == "openai":
+            return True
+
+        # 2. BYOK Detection (sk-...)
+        if provider_name is None and api_key and api_key.startswith("sk-"):
+            return True
+
+        # 3. Env Fallback (if no explicit provider)
+        if provider_name is None and settings.has_openai_key:
+            return True
+
+        return False
+
+    def create(
+        self,
+        settings: Settings,
+        api_key: str | None = None,
+        model_id: str | None = None,
+        **kwargs: Any,
+    ) -> BaseChatClient:
+        return OpenAIChatClient(
+            model_id=model_id or settings.openai_model,
+            api_key=api_key or settings.openai_api_key,
+            **kwargs,
+        )
+
+
+class HuggingFaceProvider(ClientProvider):
+    """Strategy for HuggingFace client creation (Free Tier Fallback)."""
+
+    @property
+    def name(self) -> str:
+        return "HuggingFace"
+
+    def can_handle(
+        self, provider_name: str | None, api_key: str | None, settings: Settings
+    ) -> bool:
+        # 1. Explicit request
+        if provider_name == "huggingface":
+            return True
+
+        # 2. Fallback (Default) - only if NO specific provider requested
+        if provider_name is None:
+            return True
+
+        return False
+
+    def create(
+        self,
+        settings: Settings,
+        api_key: str | None = None,
+        model_id: str | None = None,
+        **kwargs: Any,
+    ) -> BaseChatClient:
+        return HuggingFaceChatClient(
+            model_id=model_id or settings.huggingface_model,
+            api_key=api_key or settings.hf_token,
+            **kwargs,
+        )

src/clients/registry.py

@@ -0,0 +1,90 @@
+"""
+Client Provider Registry for unified provider selection.
+
+Implements the Strategy Pattern to decouple client creation from the factory.
+"""
+
+from typing import Any, ClassVar, Protocol
+
+import structlog
+from agent_framework import BaseChatClient
+
+from src.utils.config import Settings
+
+logger = structlog.get_logger()
+
+
+class ClientProvider(Protocol):
+    """Protocol for LLM client providers."""
+
+    @property
+    def name(self) -> str:
+        """Provider name (e.g., 'openai', 'huggingface')."""
+        ...
+
+    def can_handle(
+        self, provider_name: str | None, api_key: str | None, settings: Settings
+    ) -> bool:
+        """Determine if this provider should handle the request."""
+        ...
+
+    def create(
+        self,
+        settings: Settings,
+        api_key: str | None = None,
+        model_id: str | None = None,
+        **kwargs: Any,
+    ) -> BaseChatClient:
+        """Create the client instance."""
+        ...
+
+
+class ProviderRegistry:
+    """Registry for managing available LLM providers."""
+
+    _providers: ClassVar[list[ClientProvider]] = []
+
+    @classmethod
+    def register(cls, provider: ClientProvider) -> None:
+        """Register a new provider strategy."""
+        cls._providers.append(provider)
+
+    @classmethod
+    def clear(cls) -> None:
+        """Clear all registered providers (useful for testing)."""
+        cls._providers.clear()
+
+    @classmethod
+    def get_client(
+        cls,
+        settings: Settings,
+        provider: str | None = None,
+        api_key: str | None = None,
+        model_id: str | None = None,
+        **kwargs: Any,
+    ) -> BaseChatClient:
+        """
+        Find and execute the appropriate provider strategy.
+
+        Args:
+            settings: Application settings
+            provider: Explicit provider name
+            api_key: Optional API key
+            model_id: Optional model ID
+            **kwargs: Additional arguments for the client
+
+        Returns:
+            Configured BaseChatClient
+
+        Raises:
+            ValueError: If no provider can handle the request
+        """
+        # Normalize provider name
+        normalized_provider = provider.lower() if provider else None
+
+        for p in cls._providers:
+            if p.can_handle(normalized_provider, api_key, settings):
+                logger.info(f"Using {p.name} Chat Client")
+                return p.create(settings, api_key, model_id, **kwargs)
+
+        raise ValueError(f"No suitable provider found for provider={provider}")

tests/unit/clients/test_chat_client_factory.py

@@ -79,7 +79,7 @@ class TestChatClientFactory:
 
             from src.clients.factory import get_chat_client
 
-            with pytest.raises(ValueError, match="Unsupported provider"):
+            with pytest.raises(ValueError, match="No suitable provider found"):
                 get_chat_client(provider="invalid_provider")
 
     def test_byok_auto_detects_openai_from_key_prefix(self) -> None: