Merge pull request #84 from lfnovo/fix/tts-factory-config-support

fix: align create_text_to_speech signature with other factory methods

Author: lfnovo

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.19.2] - 2026-02-14
+
+### Fixed
+
+- **TTS Factory Config Support** - Aligned `create_text_to_speech()` signature with other factory methods by adding `config` dict parameter. Previously, `config={"api_key": "..."}` was silently ignored, causing authentication failures for callers using the standard config pattern.
+
+### Deprecated
+
+- Direct `api_key` and `base_url` parameters on `create_text_to_speech()` — use `config={"api_key": "...", "base_url": "..."}` instead.
+- Removed `api_key` parameter from `create_tts()` deprecated alias.
+
 ## [2.19.1] - 2026-02-12
 
 ### Fixed

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "esperanto"
-version = "2.19.1"
+version = "2.19.2"
 description = "A light-weight, production-ready, unified interface for various AI model providers"
 authors = [
     { name = "LUIS NOVO", email = "lfnovo@gmail.com" }

src/esperanto/factory.py

@@ -300,6 +300,7 @@ def create_text_to_speech(
         cls,
         provider: str,
         model_name: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
         **kwargs,
@@ -309,8 +310,9 @@ def create_text_to_speech(
         Args:
             provider: Provider name (openai, elevenlabs, google)
             model_name: Name of the model to use
-            api_key: API key for the provider
-            base_url: Optional base URL for the API
+            config: Optional configuration dict for the model
+            api_key: Deprecated. Use config={"api_key": "..."} instead.
+            base_url: Deprecated. Use config={"base_url": "..."} instead.
             **kwargs: Additional provider-specific configuration
 
         Returns:
@@ -320,9 +322,28 @@ def create_text_to_speech(
             ValueError: If provider is not supported
             ImportError: If provider module is not installed
         """
-        provider_class = cls._import_provider_class("text_to_speech", provider)
-        return provider_class(
-            model_name=model_name, api_key=api_key, base_url=base_url, **kwargs
+        config = config or {}
+
+        if api_key is not None:
+            warnings.warn(
+                "Passing api_key directly to create_text_to_speech() is deprecated. "
+                'Use config={"api_key": "..."} instead.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            config["api_key"] = api_key
+
+        if base_url is not None:
+            warnings.warn(
+                "Passing base_url directly to create_text_to_speech() is deprecated. "
+                'Use config={"base_url": "..."} instead.',
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            config["base_url"] = base_url
+
+        return cls._create_instance(
+            "text_to_speech", provider, model_name=model_name, **config, **kwargs
         )
 
     @classmethod
@@ -356,15 +377,13 @@ def create_tts(
         provider: str,
         model_name: Optional[str] = None,
         config: Optional[Dict[str, Any]] = None,
-        api_key: Optional[str] = None,
     ) -> TextToSpeechModel:
         """Create a text-to-speech model instance (alias for create_text_to_speech).
 
         Args:
             provider: Provider name
             model_name: Optional name of the model to use
             config: Optional configuration for the model
-            api_key: Optional API key for authentication
 
         Returns:
             Text-to-speech model instance
@@ -376,7 +395,7 @@ def create_tts(
             stacklevel=2,
         )
         return cls.create_text_to_speech(
-            provider, model_name=model_name, config=config, api_key=api_key
+            provider, model_name=model_name, config=config
         )
 
     @classmethod

tests/test_factory.py

@@ -1,10 +1,133 @@
 """Tests for the AIFactory class."""
 
+import warnings
+
 import pytest
 from unittest.mock import patch, MagicMock
 
 from esperanto.factory import AIFactory
 
 
 # Note: Caching functionality has been removed from AIFactory.
-# Tests now verify that factory creates new instances each time.
+# Tests now verify that factory creates new instances each time.
+
+
+class TestCreateTextToSpeech:
+    """Tests for create_text_to_speech config dict support."""
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_config_dict_passes_api_key_and_base_url(self, mock_import):
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        AIFactory.create_text_to_speech(
+            "openai",
+            model_name="tts-1",
+            config={"api_key": "sk-test", "base_url": "https://custom.api"},
+        )
+
+        mock_cls.assert_called_once_with(
+            model_name="tts-1",
+            api_key="sk-test",
+            base_url="https://custom.api",
+        )
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_direct_api_key_emits_deprecation_warning(self, mock_import):
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            AIFactory.create_text_to_speech(
+                "openai", model_name="tts-1", api_key="sk-test"
+            )
+
+        deprecation_warnings = [x for x in w if issubclass(x.category, DeprecationWarning)]
+        assert len(deprecation_warnings) == 1
+        assert "api_key" in str(deprecation_warnings[0].message)
+
+        mock_cls.assert_called_once_with(
+            model_name="tts-1",
+            api_key="sk-test",
+        )
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_direct_base_url_emits_deprecation_warning(self, mock_import):
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            AIFactory.create_text_to_speech(
+                "openai", model_name="tts-1", base_url="https://custom.api"
+            )
+
+        deprecation_warnings = [x for x in w if issubclass(x.category, DeprecationWarning)]
+        assert len(deprecation_warnings) == 1
+        assert "base_url" in str(deprecation_warnings[0].message)
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_direct_params_override_config(self, mock_import):
+        """Direct api_key/base_url take precedence when config also has them."""
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        with warnings.catch_warnings(record=True):
+            warnings.simplefilter("always")
+            AIFactory.create_text_to_speech(
+                "openai",
+                model_name="tts-1",
+                config={"api_key": "config-key", "base_url": "https://config.api"},
+                api_key="direct-key",
+                base_url="https://direct.api",
+            )
+
+        mock_cls.assert_called_once_with(
+            model_name="tts-1",
+            api_key="direct-key",
+            base_url="https://direct.api",
+        )
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_config_without_api_key(self, mock_import):
+        """Config dict works even without api_key/base_url."""
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        AIFactory.create_text_to_speech(
+            "openai",
+            model_name="tts-1",
+            config={"voice": "alloy"},
+        )
+
+        mock_cls.assert_called_once_with(
+            model_name="tts-1",
+            voice="alloy",
+        )
+
+    @patch.object(AIFactory, "_import_provider_class")
+    def test_create_tts_alias_forwards_config(self, mock_import):
+        """The deprecated create_tts alias correctly forwards config."""
+        mock_cls = MagicMock()
+        mock_import.return_value = mock_cls
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            AIFactory.create_tts(
+                "openai",
+                model_name="tts-1",
+                config={"api_key": "sk-test"},
+            )
+
+        # Should have the create_tts deprecation warning
+        tts_warnings = [
+            x for x in w
+            if issubclass(x.category, DeprecationWarning) and "create_tts" in str(x.message)
+        ]
+        assert len(tts_warnings) == 1
+
+        mock_cls.assert_called_once_with(
+            model_name="tts-1",
+            api_key="sk-test",
+        )