feat: Remove initialize() Method from LlamaStackAsLibrary

Signed-off-by: Mustafa Elbehery <[email protected]>

Author: Elbehery

docs/source/distributions/importing_as_library.md

@@ -17,7 +17,6 @@ client = LlamaStackAsLibraryClient(
     # provider_data is optional, but if you need to pass in any provider specific data, you can do so here.
     provider_data={"tavily_search_api_key": os.environ["TAVILY_SEARCH_API_KEY"]},
 )
-client.initialize()
 ```
 
 This will parse your config and set up any inline implementations and remote clients needed for your implementation.
@@ -32,5 +31,4 @@ If you've created a [custom distribution](https://llama-stack.readthedocs.io/en/
 
 ```python
 client = LlamaStackAsLibraryClient(config_path)
-client.initialize()
 ```

llama_stack/core/library_client.py

@@ -153,7 +153,11 @@ def __init__(
 
         self.loop = asyncio.new_event_loop()
 
-    def initialize(self):
+        # Automatically initialize the client
+        self._auto_initialize()
+
+    def _auto_initialize(self):
+        """Internal method to handle automatic initialization during construction."""
         if in_notebook():
             import nest_asyncio
 
@@ -169,6 +173,18 @@ def initialize(self):
         finally:
             asyncio.set_event_loop(None)
 
+    def initialize(self):
+        """
+        Deprecated method for backward compatibility.
+
+        Initialization now happens automatically in __init__.
+        This method is kept for backward compatibility and does nothing.
+
+        Returns:
+            None: Returns None to match historical behavior
+        """
+        return None
+
     def _remove_root_logger_handlers(self):
         """
         Remove all handlers from the root logger. Needed to avoid polluting the console with logs.
@@ -237,8 +253,18 @@ def __init__(
         self.custom_provider_registry = custom_provider_registry
         self.provider_data = provider_data
         self.route_impls: RouteImpls | None = None  # Initialize to None to prevent AttributeError
+        self._is_initialized: bool = False  # Track initialization state
 
     async def initialize(self) -> bool:
+        """
+        Initialize the async client. Can be called multiple times safely.
+
+        Returns:
+            bool: True if initialization was successful
+        """
+        if self._is_initialized:
+            return True
+
         try:
             self.route_impls = None
             self.impls = await construct_stack(self.config, self.custom_provider_registry)
@@ -288,6 +314,7 @@ async def initialize(self) -> bool:
             console.print(yaml.dump(safe_config, indent=2))
 
         self.route_impls = initialize_route_impls(self.impls)
+        self._is_initialized = True
         return True
 
     async def request(
@@ -298,9 +325,6 @@ async def request(
         stream=False,
         stream_cls=None,
     ):
-        if self.route_impls is None:
-            raise ValueError("Client not initialized. Please call initialize() first.")
-
         # Create headers with provider data if available
         headers = options.headers or {}
         if self.provider_data:

tests/integration/fixtures/common.py

@@ -246,9 +246,7 @@ def llama_stack_client(request, provider_data):
         provider_data=provider_data,
         skip_logger_removal=True,
     )
-    if not client.initialize():
-        raise RuntimeError("Initialization failed")
-
+    # Client is automatically initialized during construction
     return client
 
 

tests/unit/distribution/test_library_client_initialization.py

@@ -5,86 +5,70 @@
 # the root directory of this source tree.
 
 """
-Unit tests for LlamaStackAsLibraryClient initialization error handling.
+Unit tests for LlamaStackAsLibraryClient automatic initialization.
 
-These tests ensure that users get proper error messages when they forget to call
-initialize() on the library client, preventing AttributeError regressions.
+These tests ensure that the library client is automatically initialized
+and ready to use immediately after construction.
 """
 
-import pytest
-
 from llama_stack.core.library_client import (
     AsyncLlamaStackAsLibraryClient,
     LlamaStackAsLibraryClient,
 )
 
 
-class TestLlamaStackAsLibraryClientInitialization:
-    """Test proper error handling for uninitialized library clients."""
-
-    @pytest.mark.parametrize(
-        "api_call",
-        [
-            lambda client: client.models.list(),
-            lambda client: client.chat.completions.create(model="test", messages=[{"role": "user", "content": "test"}]),
-            lambda client: next(
-                client.chat.completions.create(
-                    model="test", messages=[{"role": "user", "content": "test"}], stream=True
-                )
-            ),
-        ],
-        ids=["models.list", "chat.completions.create", "chat.completions.create_stream"],
-    )
-    def test_sync_client_proper_error_without_initialization(self, api_call):
-        """Test that sync client raises ValueError with helpful message when not initialized."""
+class TestLlamaStackAsLibraryClientAutoInitialization:
+    """Test automatic initialization of library clients."""
+
+    def test_sync_client_auto_initialization(self):
+        """Test that sync client is automatically initialized after construction."""
         client = LlamaStackAsLibraryClient("nvidia")
 
-        with pytest.raises(ValueError) as exc_info:
-            api_call(client)
-
-        error_msg = str(exc_info.value)
-        assert "Client not initialized" in error_msg
-        assert "Please call initialize() first" in error_msg
-
-    @pytest.mark.parametrize(
-        "api_call",
-        [
-            lambda client: client.models.list(),
-            lambda client: client.chat.completions.create(model="test", messages=[{"role": "user", "content": "test"}]),
-        ],
-        ids=["models.list", "chat.completions.create"],
-    )
-    async def test_async_client_proper_error_without_initialization(self, api_call):
-        """Test that async client raises ValueError with helpful message when not initialized."""
+        # Client should be automatically initialized
+        assert client.async_client._is_initialized is True
+        assert client.async_client.route_impls is not None
+
+    async def test_async_client_auto_initialization(self):
+        """Test that async client can be initialized and works properly."""
         client = AsyncLlamaStackAsLibraryClient("nvidia")
 
-        with pytest.raises(ValueError) as exc_info:
-            await api_call(client)
+        # Initialize the client
+        result = await client.initialize()
+        assert result is True
+        assert client._is_initialized is True
+        assert client.route_impls is not None
+
+    def test_initialize_method_backward_compatibility(self):
+        """Test that initialize() method still works for backward compatibility."""
+        client = LlamaStackAsLibraryClient("nvidia")
+
+        # initialize() should return None (historical behavior) and not cause errors
+        result = client.initialize()
+        assert result is None
 
-        error_msg = str(exc_info.value)
-        assert "Client not initialized" in error_msg
-        assert "Please call initialize() first" in error_msg
+        # Multiple calls should be safe
+        result2 = client.initialize()
+        assert result2 is None
 
-    async def test_async_client_streaming_error_without_initialization(self):
-        """Test that async client streaming raises ValueError with helpful message when not initialized."""
+    async def test_async_initialize_method_idempotent(self):
+        """Test that async initialize() method can be called multiple times safely."""
         client = AsyncLlamaStackAsLibraryClient("nvidia")
 
-        with pytest.raises(ValueError) as exc_info:
-            stream = await client.chat.completions.create(
-                model="test", messages=[{"role": "user", "content": "test"}], stream=True
-            )
-            await anext(stream)
+        # First initialization
+        result1 = await client.initialize()
+        assert result1 is True
+        assert client._is_initialized is True
 
-        error_msg = str(exc_info.value)
-        assert "Client not initialized" in error_msg
-        assert "Please call initialize() first" in error_msg
+        # Second initialization should be safe and return True
+        result2 = await client.initialize()
+        assert result2 is True
+        assert client._is_initialized is True
 
-    def test_route_impls_initialized_to_none(self):
-        """Test that route_impls is initialized to None to prevent AttributeError."""
-        # Test sync client
+    def test_route_impls_automatically_set(self):
+        """Test that route_impls is automatically set during construction."""
+        # Test sync client - should be auto-initialized
         sync_client = LlamaStackAsLibraryClient("nvidia")
-        assert sync_client.async_client.route_impls is None
+        assert sync_client.async_client.route_impls is not None
 
-        # Test async client directly
-        async_client = AsyncLlamaStackAsLibraryClient("nvidia")
-        assert async_client.route_impls is None
+        # Test that the async client is marked as initialized
+        assert sync_client.async_client._is_initialized is True

tests/verifications/openai_api/fixtures/fixtures.py

@@ -137,8 +137,7 @@ def openai_client(base_url, api_key, provider):
             raise ValueError(f"Invalid config for Llama Stack: {provider}, it must be of the form 'stack:<config>'")
         config = parts[1]
         client = LlamaStackAsLibraryClient(config, skip_logger_removal=True)
-        if not client.initialize():
-            raise RuntimeError("Initialization failed")
+        # Client is automatically initialized during construction
         return client
 
     return OpenAI(