feat!: Restructure provider factory and support additional create methods (#102)

feat!: Rename OpenAIProvider → OpenAIRunnerFactory; rename
openai_provider.py → openai_runner_factory.py
feat!: Rename LangChainProvider → LangChainRunnerFactory; rename
langchain_provider.py → langchain_runner_factory.py
feat!: Remove abstract static create(ai_config) from AIProvider ABC; see
new create_[model|agent|agent_graph]
feat: Add create_model(), create_agent(), create_agent_graph() instance
methods to AIProvider ABC (non-abstract, default warns)
feat!: Rename AIProviderFactory with RunnerFactory; delete
ai_provider_factory.py
feat: RunnerFactory.create_model/agent/agent_graph() replace async
AIProviderFactory.create()
fix: LDClient now calls RunnerFactory.create_model() synchronously
instead of awaiting AIProviderFactory.create()

Author: jsonbailey

packages/ai-providers/server-ai-langchain/src/ldai_langchain/__init__.py

@@ -1,13 +1,8 @@
-"""LaunchDarkly AI SDK - LangChain Provider.
-
-This package provides LangChain integration for the LaunchDarkly Server-Side AI SDK,
-"""
-
-from ldai_langchain.langchain_provider import LangChainProvider
+from ldai_langchain.langchain_runner_factory import LangChainRunnerFactory
 
 __version__ = "0.1.0"
 
 __all__ = [
     '__version__',
-    'LangChainProvider',
+    'LangChainRunnerFactory',
 ]

…src/ldai_langchain/langchain_provider.py …ai_langchain/langchain_runner_factory.pypackages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_provider.py renamed to packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_runner_factory.py packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_provider.py renamed to packages/ai-providers/server-ai-langchain/src/ldai_langchain/langchain_runner_factory.py

@@ -1,5 +1,3 @@
-"""LangChain implementation of AIProvider for LaunchDarkly AI SDK."""
-
 from typing import Any, Dict, List, Optional, Union
 
 from langchain_core.language_models.chat_models import BaseChatModel
@@ -11,31 +9,24 @@
 from ldai.tracker import TokenUsage
 
 
-class LangChainProvider(AIProvider):
-    """
-    LangChain implementation of AIProvider.
-
-    This provider integrates LangChain models with LaunchDarkly's tracking capabilities.
-    """
+class LangChainRunnerFactory(AIProvider):
+    """LangChain provider for the LaunchDarkly AI SDK."""
 
-    def __init__(self, llm: BaseChatModel):
+    def __init__(self, llm: Optional[BaseChatModel] = None):
         """
-        Initialize the LangChain provider.
-
-        :param llm: A LangChain BaseChatModel instance
+        :param llm: A LangChain BaseChatModel instance (optional)
         """
         self._llm = llm
 
-    @staticmethod
-    async def create(ai_config: AIConfigKind) -> 'LangChainProvider':
+    def create_model(self, config: AIConfigKind) -> 'LangChainRunnerFactory':
         """
-        Static factory method to create a LangChain AIProvider from an AI configuration.
+        Create a configured LangChain model provider for the given AI config.
 
-        :param ai_config: The LaunchDarkly AI configuration
-        :return: Configured LangChainProvider instance
+        :param config: The LaunchDarkly AI configuration
+        :return: Configured LangChainRunnerFactory ready to invoke the model
         """
-        llm = LangChainProvider.create_langchain_model(ai_config)
-        return LangChainProvider(llm)
+        llm = LangChainRunnerFactory.create_langchain_model(config)
+        return LangChainRunnerFactory(llm)
 
     async def invoke_model(self, messages: List[LDMessage]) -> ChatResponse:
         """
@@ -45,9 +36,10 @@ async def invoke_model(self, messages: List[LDMessage]) -> ChatResponse:
         :return: ChatResponse containing the model's response and metrics
         """
         try:
-            langchain_messages = LangChainProvider.convert_messages_to_langchain(messages)
+            assert self._llm is not None
+            langchain_messages = LangChainRunnerFactory.convert_messages_to_langchain(messages)
             response: BaseMessage = await self._llm.ainvoke(langchain_messages)
-            metrics = LangChainProvider.get_ai_metrics_from_response(response)
+            metrics = LangChainRunnerFactory.get_ai_metrics_from_response(response)
 
             content: str = ''
             if isinstance(response.content, str):
@@ -89,7 +81,8 @@ async def invoke_structured_model(
             metrics=LDAIMetrics(success=False, usage=None),
         )
         try:
-            langchain_messages = LangChainProvider.convert_messages_to_langchain(messages)
+            assert self._llm is not None
+            langchain_messages = LangChainRunnerFactory.convert_messages_to_langchain(messages)
             structured_llm = self._llm.with_structured_output(response_structure, include_raw=True)
             response = await structured_llm.ainvoke(langchain_messages)
 
@@ -104,7 +97,7 @@ async def invoke_structured_model(
             if raw_response is not None:
                 if hasattr(raw_response, 'content'):
                     structured_response.raw_response = raw_response.content
-                structured_response.metrics.usage = LangChainProvider.get_ai_usage_from_response(raw_response)
+                structured_response.metrics.usage = LangChainRunnerFactory.get_ai_usage_from_response(raw_response)
 
             if response.get('parsing_error'):
                 log.warning(f'LangChain structured model invocation had a parsing error')
@@ -117,11 +110,11 @@ async def invoke_structured_model(
             log.warning(f'LangChain structured model invocation failed: {error}')
             return structured_response
 
-    def get_chat_model(self) -> BaseChatModel:
+    def get_chat_model(self) -> Optional[BaseChatModel]:
         """
         Get the underlying LangChain model instance.
 
-        :return: The underlying BaseChatModel
+        :return: The underlying BaseChatModel, or None if not yet configured
         """
         return self._llm
 
@@ -174,23 +167,19 @@ def get_ai_usage_from_response(response: BaseMessage) -> TokenUsage:
     @staticmethod
     def get_ai_metrics_from_response(response: BaseMessage) -> LDAIMetrics:
         """
-        Get AI metrics from a LangChain provider response.
-
-        This method extracts token usage information and success status from LangChain responses
-        and returns a LaunchDarkly AIMetrics object.
+        Extract LaunchDarkly AI metrics from a LangChain response.
 
         :param response: The response from the LangChain model
         :return: LDAIMetrics with success status and token usage
 
-        Example:
-            # Use with tracker.track_metrics_of for automatic tracking
+        Example::
+
             response = await tracker.track_metrics_of(
                 lambda: llm.ainvoke(messages),
-                LangChainProvider.get_ai_metrics_from_response
+                LangChainRunnerFactory.get_ai_metrics_from_response
             )
         """
-        # Extract token usage if available
-        usage = LangChainProvider.get_ai_usage_from_response(response)
+        usage = LangChainRunnerFactory.get_ai_usage_from_response(response)
 
         return LDAIMetrics(success=True, usage=usage)
 
@@ -201,9 +190,6 @@ def convert_messages_to_langchain(
         """
         Convert LaunchDarkly messages to LangChain messages.
 
-        This helper method enables developers to work directly with LangChain message types
-        while maintaining compatibility with LaunchDarkly's standardized message format.
-
         :param messages: List of LDMessage objects
         :return: List of LangChain message objects
         :raises ValueError: If an unsupported message role is encountered
@@ -225,10 +211,7 @@ def convert_messages_to_langchain(
     @staticmethod
     def create_langchain_model(ai_config: AIConfigKind) -> BaseChatModel:
         """
-        Create a LangChain model from an AI configuration.
-
-        This public helper method enables developers to initialize their own LangChain models
-        using LaunchDarkly AI configurations.
+        Create a LangChain model from a LaunchDarkly AI configuration.
 
         :param ai_config: The LaunchDarkly AI configuration
         :return: A configured LangChain BaseChatModel
@@ -242,7 +225,7 @@ def create_langchain_model(ai_config: AIConfigKind) -> BaseChatModel:
         model_name = model_dict.get('name', '')
         provider = provider_dict.get('name', '')
         parameters = dict(model_dict.get('parameters') or {})
-        mapped_provider = LangChainProvider.map_provider(provider)
+        mapped_provider = LangChainRunnerFactory.map_provider(provider)
 
         # Bedrock requires the foundation provider (e.g. Bedrock:Anthropic) passed in
         # parameters separately from model_provider, which is used for LangChain routing.

packages/ai-providers/server-ai-langchain/tests/test_langchain_provider.py

@@ -7,7 +7,7 @@
 
 from ldai import LDMessage
 
-from ldai_langchain import LangChainProvider
+from ldai_langchain import LangChainRunnerFactory
 
 
 class TestConvertMessagesToLangchain:
@@ -16,7 +16,7 @@ class TestConvertMessagesToLangchain:
     def test_converts_system_messages_to_system_message(self):
         """Should convert system messages to SystemMessage."""
         messages = [LDMessage(role='system', content='You are a helpful assistant.')]
-        result = LangChainProvider.convert_messages_to_langchain(messages)
+        result = LangChainRunnerFactory.convert_messages_to_langchain(messages)
 
         assert len(result) == 1
         assert isinstance(result[0], SystemMessage)
@@ -25,7 +25,7 @@ def test_converts_system_messages_to_system_message(self):
     def test_converts_user_messages_to_human_message(self):
         """Should convert user messages to HumanMessage."""
         messages = [LDMessage(role='user', content='Hello, how are you?')]
-        result = LangChainProvider.convert_messages_to_langchain(messages)
+        result = LangChainRunnerFactory.convert_messages_to_langchain(messages)
 
         assert len(result) == 1
         assert isinstance(result[0], HumanMessage)
@@ -34,7 +34,7 @@ def test_converts_user_messages_to_human_message(self):
     def test_converts_assistant_messages_to_ai_message(self):
         """Should convert assistant messages to AIMessage."""
         messages = [LDMessage(role='assistant', content='I am doing well, thank you!')]
-        result = LangChainProvider.convert_messages_to_langchain(messages)
+        result = LangChainRunnerFactory.convert_messages_to_langchain(messages)
 
         assert len(result) == 1
         assert isinstance(result[0], AIMessage)
@@ -47,7 +47,7 @@ def test_converts_multiple_messages_in_order(self):
             LDMessage(role='user', content='What is the weather like?'),
             LDMessage(role='assistant', content='I cannot check the weather.'),
         ]
-        result = LangChainProvider.convert_messages_to_langchain(messages)
+        result = LangChainRunnerFactory.convert_messages_to_langchain(messages)
 
         assert len(result) == 3
         assert isinstance(result[0], SystemMessage)
@@ -62,11 +62,11 @@ class MockMessage:
             content = 'Test message'
 
         with pytest.raises(ValueError, match='Unsupported message role: unknown'):
-            LangChainProvider.convert_messages_to_langchain([MockMessage()])  # type: ignore
+            LangChainRunnerFactory.convert_messages_to_langchain([MockMessage()])  # type: ignore
 
     def test_handles_empty_message_array(self):
         """Should handle empty message array."""
-        result = LangChainProvider.convert_messages_to_langchain([])
+        result = LangChainRunnerFactory.convert_messages_to_langchain([])
         assert len(result) == 0
 
 
@@ -84,7 +84,7 @@ def test_creates_metrics_with_success_true_and_token_usage(self):
             },
         }
 
-        result = LangChainProvider.get_ai_metrics_from_response(mock_response)
+        result = LangChainRunnerFactory.get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
         assert result.usage is not None
@@ -103,7 +103,7 @@ def test_creates_metrics_with_snake_case_token_usage(self):
             },
         }
 
-        result = LangChainProvider.get_ai_metrics_from_response(mock_response)
+        result = LangChainRunnerFactory.get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
         assert result.usage is not None
@@ -115,7 +115,7 @@ def test_creates_metrics_with_success_true_and_no_usage_when_metadata_missing(se
         """Should create metrics with success=True and no usage when metadata is missing."""
         mock_response = AIMessage(content='Test response')
 
-        result = LangChainProvider.get_ai_metrics_from_response(mock_response)
+        result = LangChainRunnerFactory.get_ai_metrics_from_response(mock_response)
 
         assert result.success is True
         assert result.usage is None
@@ -126,23 +126,23 @@ class TestMapProvider:
 
     def test_maps_gemini_to_google_genai(self):
         """Should map gemini to google-genai."""
-        assert LangChainProvider.map_provider('gemini') == 'google-genai'
-        assert LangChainProvider.map_provider('Gemini') == 'google-genai'
-        assert LangChainProvider.map_provider('GEMINI') == 'google-genai'
+        assert LangChainRunnerFactory.map_provider('gemini') == 'google-genai'
+        assert LangChainRunnerFactory.map_provider('Gemini') == 'google-genai'
+        assert LangChainRunnerFactory.map_provider('GEMINI') == 'google-genai'
 
     def test_maps_bedrock_and_model_families_to_bedrock_converse(self):
         """Should map bedrock and bedrock:model_family to bedrock_converse."""
-        assert LangChainProvider.map_provider('bedrock') == 'bedrock_converse'
-        assert LangChainProvider.map_provider('Bedrock:Anthropic') == 'bedrock_converse'
-        assert LangChainProvider.map_provider('bedrock:anthropic') == 'bedrock_converse'
-        assert LangChainProvider.map_provider('bedrock:amazon') == 'bedrock_converse'
-        assert LangChainProvider.map_provider('bedrock:cohere') == 'bedrock_converse'
+        assert LangChainRunnerFactory.map_provider('bedrock') == 'bedrock_converse'
+        assert LangChainRunnerFactory.map_provider('Bedrock:Anthropic') == 'bedrock_converse'
+        assert LangChainRunnerFactory.map_provider('bedrock:anthropic') == 'bedrock_converse'
+        assert LangChainRunnerFactory.map_provider('bedrock:amazon') == 'bedrock_converse'
+        assert LangChainRunnerFactory.map_provider('bedrock:cohere') == 'bedrock_converse'
 
     def test_returns_provider_name_unchanged_for_unmapped_providers(self):
         """Should return provider name unchanged for unmapped providers."""
-        assert LangChainProvider.map_provider('openai') == 'openai'
-        assert LangChainProvider.map_provider('anthropic') == 'anthropic'
-        assert LangChainProvider.map_provider('unknown') == 'unknown'
+        assert LangChainRunnerFactory.map_provider('openai') == 'openai'
+        assert LangChainRunnerFactory.map_provider('anthropic') == 'anthropic'
+        assert LangChainRunnerFactory.map_provider('unknown') == 'unknown'
 
 
 class TestInvokeModel:
@@ -158,7 +158,7 @@ async def test_returns_success_true_for_string_content(self, mock_llm):
         """Should return success=True for string content."""
         mock_response = AIMessage(content='Test response')
         mock_llm.ainvoke = AsyncMock(return_value=mock_response)
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         messages = [LDMessage(role='user', content='Hello')]
         result = await provider.invoke_model(messages)
@@ -171,7 +171,7 @@ async def test_returns_success_false_for_non_string_content_and_logs_warning(sel
         """Should return success=False for non-string content and log warning."""
         mock_response = AIMessage(content=[{'type': 'image', 'data': 'base64data'}])
         mock_llm.ainvoke = AsyncMock(return_value=mock_response)
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         messages = [LDMessage(role='user', content='Hello')]
         result = await provider.invoke_model(messages)
@@ -184,7 +184,7 @@ async def test_returns_success_false_when_model_invocation_throws_error(self, mo
         """Should return success=False when model invocation throws an error."""
         error = Exception('Model invocation failed')
         mock_llm.ainvoke = AsyncMock(side_effect=error)
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         messages = [LDMessage(role='user', content='Hello')]
         result = await provider.invoke_model(messages)
@@ -210,7 +210,7 @@ async def test_returns_success_true_for_successful_invocation(self, mock_llm):
         mock_structured_llm = MagicMock()
         mock_structured_llm.ainvoke = AsyncMock(return_value=mock_response)
         mock_llm.with_structured_output = MagicMock(return_value=mock_structured_llm)
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         messages = [LDMessage(role='user', content='Hello')]
         response_structure = {'type': 'object', 'properties': {}}
@@ -226,7 +226,7 @@ async def test_returns_success_false_when_structured_model_invocation_throws_err
         mock_structured_llm = MagicMock()
         mock_structured_llm.ainvoke = AsyncMock(side_effect=error)
         mock_llm.with_structured_output = MagicMock(return_value=mock_structured_llm)
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         messages = [LDMessage(role='user', content='Hello')]
         response_structure = {'type': 'object', 'properties': {}}
@@ -244,7 +244,7 @@ class TestGetChatModel:
     def test_returns_underlying_llm(self):
         """Should return the underlying LLM."""
         mock_llm = MagicMock()
-        provider = LangChainProvider(mock_llm)
+        provider = LangChainRunnerFactory(mock_llm)
 
         assert provider.get_chat_model() is mock_llm
 

packages/ai-providers/server-ai-openai/src/ldai_openai/__init__.py

@@ -1,5 +1,5 @@
-"""LaunchDarkly AI SDK OpenAI Provider."""
+from ldai_openai.openai_runner_factory import OpenAIRunnerFactory
 
-from ldai_openai.openai_provider import OpenAIProvider
-
-__all__ = ['OpenAIProvider']
+__all__ = [
+    'OpenAIRunnerFactory',
+]