Merge branch 'main' into make-openaimix-pydantic

.github/workflows/providers-build.yml

@@ -112,7 +112,7 @@ jobs:
           fi
           entrypoint=$(docker inspect --format '{{ .Config.Entrypoint }}' $IMAGE_ID)
           echo "Entrypoint: $entrypoint"
-          if [ "$entrypoint" != "[python -m llama_stack.core.server.server /app/run.yaml]" ]; then
+          if [ "$entrypoint" != "[llama stack run /app/run.yaml]" ]; then
             echo "Entrypoint is not correct"
             exit 1
           fi
@@ -150,7 +150,7 @@ jobs:
           fi
           entrypoint=$(docker inspect --format '{{ .Config.Entrypoint }}' $IMAGE_ID)
           echo "Entrypoint: $entrypoint"
-          if [ "$entrypoint" != "[python -m llama_stack.core.server.server /app/run.yaml]" ]; then
+          if [ "$entrypoint" != "[llama stack run /app/run.yaml]" ]; then
             echo "Entrypoint is not correct"
             exit 1
           fi

docs/docs/concepts/apis/external.mdx

@@ -357,7 +357,7 @@ server:
 8. Run the server:
 
 ```bash
-python -m llama_stack.core.server.server --yaml-config ~/.llama/run-byoa.yaml
+llama stack run ~/.llama/run-byoa.yaml
 ```
 
 9. Test the API:

docs/docs/deploying/kubernetes_deployment.mdx

@@ -170,7 +170,7 @@ spec:
       - name: llama-stack
         image: localhost/llama-stack-run-k8s:latest
         imagePullPolicy: IfNotPresent
-        command: ["python", "-m", "llama_stack.core.server.server", "--config", "/app/config.yaml"]
+        command: ["llama", "stack", "run", "/app/config.yaml"]
         ports:
           - containerPort: 5000
         volumeMounts:

docs/docs/distributions/k8s/stack-k8s.yaml.template

@@ -52,7 +52,7 @@ spec:
           value: "${SAFETY_MODEL}"
         - name: TAVILY_SEARCH_API_KEY
           value: "${TAVILY_SEARCH_API_KEY}"
-        command: ["python", "-m", "llama_stack.core.server.server", "/etc/config/stack_run_config.yaml", "--port", "8321"]
+        command: ["llama", "stack", "run", "/etc/config/stack_run_config.yaml", "--port", "8321"]
         ports:
           - containerPort: 8321
         volumeMounts:

llama_stack/cli/stack/run.py

@@ -6,11 +6,18 @@
 
 import argparse
 import os
+import ssl
 import subprocess
 from pathlib import Path
 
+import uvicorn
+import yaml
+
 from llama_stack.cli.stack.utils import ImageType
 from llama_stack.cli.subcommand import Subcommand
+from llama_stack.core.datatypes import LoggingConfig, StackRunConfig
+from llama_stack.core.stack import cast_image_name_to_string, replace_env_vars, validate_env_pair
+from llama_stack.core.utils.config_resolution import Mode, resolve_config_or_distro
 from llama_stack.log import get_logger
 
 REPO_ROOT = Path(__file__).parent.parent.parent.parent
@@ -146,23 +153,7 @@ class StackRun(Subcommand):
         # using the current environment packages.
         if not image_type and not image_name:
             logger.info("No image type or image name provided. Assuming environment packages.")
-            from llama_stack.core.server.server import main as server_main
-
-            # Build the server args from the current args passed to the CLI
-            server_args = argparse.Namespace()
-            for arg in vars(args):
-                # If this is a function, avoid passing it
-                # "args" contains:
-                # func=<bound method StackRun._run_stack_run_cmd of <llama_stack.cli.stack.run.StackRun object at 0x10484b010>>
-                if callable(getattr(args, arg)):
-                    continue
-                if arg == "config":
-                    server_args.config = str(config_file)
-                else:
-                    setattr(server_args, arg, getattr(args, arg))
-
-            # Run the server
-            server_main(server_args)
+            self._uvicorn_run(config_file, args)
         else:
             run_args = formulate_run_args(image_type, image_name)
 
@@ -184,6 +175,76 @@ class StackRun(Subcommand):
 
             run_command(run_args)
 
+    def _uvicorn_run(self, config_file: Path | None, args: argparse.Namespace) -> None:
+        if not config_file:
+            self.parser.error("Config file is required")
+
+        # Set environment variables if provided
+        if args.env:
+            for env_pair in args.env:
+                try:
+                    key, value = validate_env_pair(env_pair)
+                    logger.info(f"Setting environment variable {key} => {value}")
+                    os.environ[key] = value
+                except ValueError as e:
+                    logger.error(f"Error: {str(e)}")
+                    self.parser.error(f"Invalid environment variable format: {env_pair}")
+
+        config_file = resolve_config_or_distro(str(config_file), Mode.RUN)
+        with open(config_file) as fp:
+            config_contents = yaml.safe_load(fp)
+            if isinstance(config_contents, dict) and (cfg := config_contents.get("logging_config")):
+                logger_config = LoggingConfig(**cfg)
+            else:
+                logger_config = None
+            config = StackRunConfig(**cast_image_name_to_string(replace_env_vars(config_contents)))
+
+        port = args.port or config.server.port
+        host = config.server.host or ["::", "0.0.0.0"]
+
+        # Set the config file in environment so create_app can find it
+        os.environ["LLAMA_STACK_CONFIG"] = str(config_file)
+
+        uvicorn_config = {
+            "factory": True,
+            "host": host,
+            "port": port,
+            "lifespan": "on",
+            "log_level": logger.getEffectiveLevel(),
+            "log_config": logger_config,
+        }
+
+        keyfile = config.server.tls_keyfile
+        certfile = config.server.tls_certfile
+        if keyfile and certfile:
+            uvicorn_config["ssl_keyfile"] = config.server.tls_keyfile
+            uvicorn_config["ssl_certfile"] = config.server.tls_certfile
+            if config.server.tls_cafile:
+                uvicorn_config["ssl_ca_certs"] = config.server.tls_cafile
+                uvicorn_config["ssl_cert_reqs"] = ssl.CERT_REQUIRED
+
+            logger.info(
+                f"HTTPS enabled with certificates:\n  Key: {keyfile}\n  Cert: {certfile}\n  CA: {config.server.tls_cafile}"
+            )
+        else:
+            logger.info(f"HTTPS enabled with certificates:\n  Key: {keyfile}\n  Cert: {certfile}")
+
+        logger.info(f"Listening on {host}:{port}")
+
+        # We need to catch KeyboardInterrupt because uvicorn's signal handling
+        # re-raises SIGINT signals using signal.raise_signal(), which Python
+        # converts to KeyboardInterrupt. Without this catch, we'd get a confusing
+        # stack trace when using Ctrl+C or kill -2 (SIGINT).
+        # SIGTERM (kill -15) works fine without this because Python doesn't
+        # have a default handler for it.
+        #
+        # Another approach would be to ignore SIGINT entirely - let uvicorn handle it through its own
+        # signal handling but this is quite intrusive and not worth the effort.
+        try:
+            uvicorn.run("llama_stack.core.server.server:create_app", **uvicorn_config)
+        except (KeyboardInterrupt, SystemExit):
+            logger.info("Received interrupt signal, shutting down gracefully...")
+
     def _start_ui_development_server(self, stack_server_port: int):
         logger.info("Attempting to start UI development server...")
         # Check if npm is available

llama_stack/core/build_container.sh

@@ -324,14 +324,14 @@ fi
 RUN pip uninstall -y uv
 EOF
 
-# If a run config is provided, we use the --config flag
+# If a run config is provided, we use the llama stack CLI
 if [[ -n "$run_config" ]]; then
   add_to_container << EOF
-ENTRYPOINT ["python", "-m", "llama_stack.core.server.server", "$RUN_CONFIG_PATH"]
+ENTRYPOINT ["llama", "stack", "run", "$RUN_CONFIG_PATH"]
 EOF
 elif [[ "$distro_or_config" != *.yaml ]]; then
   add_to_container << EOF
-ENTRYPOINT ["python", "-m", "llama_stack.core.server.server", "$distro_or_config"]
+ENTRYPOINT ["llama", "stack", "run", "$distro_or_config"]
 EOF
 fi
 

llama_stack/core/distribution.py

@@ -243,6 +243,7 @@ def get_external_providers_from_module(
                     spec = module.get_provider_spec()
                 else:
                     # pass in a partially filled out provider spec to satisfy the registry -- knowing we will be overwriting it later upon build and run
+                    # in the case we are building we CANNOT import this module of course because it has not been installed.
                     spec = ProviderSpec(
                         api=Api(provider_api),
                         provider_type=provider.provider_type,
@@ -251,9 +252,20 @@ def get_external_providers_from_module(
                         config_class="",
                     )
                 provider_type = provider.provider_type
-                # in the case we are building we CANNOT import this module of course because it has not been installed.
-                # return a partially filled out spec that the build script will populate.
-                registry[Api(provider_api)][provider_type] = spec
+                if isinstance(spec, list):
+                    # optionally allow people to pass inline and remote provider specs as a returned list.
+                    # with the old method, users could pass in directories of specs using overlapping code
+                    # we want to ensure we preserve that flexibility in this method.
+                    logger.info(
+                        f"Detected a list of external provider specs from {provider.module} adding all to the registry"
+                    )
+                    for provider_spec in spec:
+                        if provider_spec.provider_type != provider.provider_type:
+                            continue
+                        logger.info(f"Adding {provider.provider_type} to registry")
+                        registry[Api(provider_api)][provider.provider_type] = provider_spec
+                else:
+                    registry[Api(provider_api)][provider_type] = spec
             except ModuleNotFoundError as exc:
                 raise ValueError(
                     "get_provider_spec not found. If specifying an external provider via `module` in the Provider spec, the Provider must have the `provider.get_provider_spec` module available"

llama_stack/core/server/server.py

@@ -4,7 +4,6 @@
 # This source code is licensed under the terms described in the LICENSE file in
 # the root directory of this source tree.
 
-import argparse
 import asyncio
 import concurrent.futures
 import functools
@@ -12,7 +11,6 @@ import inspect
 import json
 import logging  # allow-direct-logging
 import os
-import ssl
 import sys
 import traceback
 import warnings
@@ -35,7 +33,6 @@ from pydantic import BaseModel, ValidationError
 
 from llama_stack.apis.common.errors import ConflictError, ResourceNotFoundError
 from llama_stack.apis.common.responses import PaginatedResponse
-from llama_stack.cli.utils import add_config_distro_args, get_config_from_args
 from llama_stack.core.access_control.access_control import AccessDeniedError
 from llama_stack.core.datatypes import (
     AuthenticationRequiredError,
@@ -55,7 +52,6 @@ from llama_stack.core.stack import (
     Stack,
     cast_image_name_to_string,
     replace_env_vars,
-    validate_env_pair,
 )
 from llama_stack.core.utils.config import redact_sensitive_fields
 from llama_stack.core.utils.config_resolution import Mode, resolve_config_or_distro
@@ -333,23 +329,18 @@ class ClientVersionMiddleware:
         return await self.app(scope, receive, send)
 
 
-def create_app(
-    config_file: str | None = None,
-    env_vars: list[str] | None = None,
-) -> StackApp:
+def create_app() -> StackApp:
     """Create and configure the FastAPI application.
 
-    Args:
-        config_file: Path to config file. If None, uses LLAMA_STACK_CONFIG env var or default resolution.
-        env_vars: List of environment variables in KEY=value format.
-        disable_version_check: Whether to disable version checking. If None, uses LLAMA_STACK_DISABLE_VERSION_CHECK env var.
+    This factory function reads configuration from environment variables:
+    - LLAMA_STACK_CONFIG: Path to config file (required)
 
     Returns:
         Configured StackApp instance.
     """
-    config_file = config_file or os.getenv("LLAMA_STACK_CONFIG")
+    config_file = os.getenv("LLAMA_STACK_CONFIG")
     if config_file is None:
-        raise ValueError("No config file provided and LLAMA_STACK_CONFIG env var is not set")
+        raise ValueError("LLAMA_STACK_CONFIG environment variable is required")
 
     config_file = resolve_config_or_distro(config_file, Mode.RUN)
 
@@ -361,16 +352,6 @@ def create_app(
             logger_config = LoggingConfig(**cfg)
         logger = get_logger(name=__name__, category="core::server", config=logger_config)
 
-        if env_vars:
-            for env_pair in env_vars:
-                try:
-                    key, value = validate_env_pair(env_pair)
-                    logger.info(f"Setting environment variable {key} => {value}")
-                    os.environ[key] = value
-                except ValueError as e:
-                    logger.error(f"Error: {str(e)}")
-                    raise ValueError(f"Invalid environment variable format: {env_pair}") from e
-
         config = replace_env_vars(config_contents)
         config = StackRunConfig(**cast_image_name_to_string(config))
 
@@ -494,101 +475,6 @@ def create_app(
     return app
 
 
-def main(args: argparse.Namespace | None = None):
-    """Start the LlamaStack server."""
-    parser = argparse.ArgumentParser(description="Start the LlamaStack server.")
-
-    add_config_distro_args(parser)
-    parser.add_argument(
-        "--port",
-        type=int,
-        default=int(os.getenv("LLAMA_STACK_PORT", 8321)),
-        help="Port to listen on",
-    )
-    parser.add_argument(
-        "--env",
-        action="append",
-        help="Environment variables in KEY=value format. Can be specified multiple times.",
-    )
-
-    # Determine whether the server args are being passed by the "run" command, if this is the case
-    # the args will be passed as a Namespace object to the main function, otherwise they will be
-    # parsed from the command line
-    if args is None:
-        args = parser.parse_args()
-
-    config_or_distro = get_config_from_args(args)
-
-    try:
-        app = create_app(
-            config_file=config_or_distro,
-            env_vars=args.env,
-        )
-    except Exception as e:
-        logger.error(f"Error creating app: {str(e)}")
-        sys.exit(1)
-
-    config_file = resolve_config_or_distro(config_or_distro, Mode.RUN)
-    with open(config_file) as fp:
-        config_contents = yaml.safe_load(fp)
-        if isinstance(config_contents, dict) and (cfg := config_contents.get("logging_config")):
-            logger_config = LoggingConfig(**cfg)
-        else:
-            logger_config = None
-        config = StackRunConfig(**cast_image_name_to_string(replace_env_vars(config_contents)))
-
-    import uvicorn
-
-    # Configure SSL if certificates are provided
-    port = args.port or config.server.port
-
-    ssl_config = None
-    keyfile = config.server.tls_keyfile
-    certfile = config.server.tls_certfile
-
-    if keyfile and certfile:
-        ssl_config = {
-            "ssl_keyfile": keyfile,
-            "ssl_certfile": certfile,
-        }
-        if config.server.tls_cafile:
-            ssl_config["ssl_ca_certs"] = config.server.tls_cafile
-            ssl_config["ssl_cert_reqs"] = ssl.CERT_REQUIRED
-            logger.info(
-                f"HTTPS enabled with certificates:\n  Key: {keyfile}\n  Cert: {certfile}\n  CA: {config.server.tls_cafile}"
-            )
-        else:
-            logger.info(f"HTTPS enabled with certificates:\n  Key: {keyfile}\n  Cert: {certfile}")
-
-    listen_host = config.server.host or ["::", "0.0.0.0"]
-    logger.info(f"Listening on {listen_host}:{port}")
-
-    uvicorn_config = {
-        "app": app,
-        "host": listen_host,
-        "port": port,
-        "lifespan": "on",
-        "log_level": logger.getEffectiveLevel(),
-        "log_config": logger_config,
-    }
-    if ssl_config:
-        uvicorn_config.update(ssl_config)
-
-    # We need to catch KeyboardInterrupt because uvicorn's signal handling
-    # re-raises SIGINT signals using signal.raise_signal(), which Python
-    # converts to KeyboardInterrupt. Without this catch, we'd get a confusing
-    # stack trace when using Ctrl+C or kill -2 (SIGINT).
-    # SIGTERM (kill -15) works fine without this because Python doesn't
-    # have a default handler for it.
-    #
-    # Another approach would be to ignore SIGINT entirely - let uvicorn handle it through its own
-    # signal handling but this is quite intrusive and not worth the effort.
-    try:
-        asyncio.run(uvicorn.Server(uvicorn.Config(**uvicorn_config)).serve())
-    except (KeyboardInterrupt, SystemExit):
-        logger.info("Received interrupt signal, shutting down gracefully...")
-
-
 def _log_run_config(run_config: StackRunConfig):
     """Logs the run config with redacted fields and disabled providers removed."""
     logger.info("Run configuration:")
@@ -615,7 +501,3 @@ def remove_disabled_providers(obj):
         return [item for item in (remove_disabled_providers(i) for i in obj) if item is not None]
     else:
         return obj
-
-
-if __name__ == "__main__":
-    main()

llama_stack/core/start_stack.sh

@@ -116,7 +116,7 @@ if [[ "$env_type" == "venv" ]]; then
         yaml_config_arg=""
     fi
 
-    $PYTHON_BINARY -m llama_stack.core.server.server \
+    llama stack run \
     $yaml_config_arg \
     --port "$port" \
     $env_vars \

tests/unit/distribution/test_distribution.py

@@ -390,3 +390,467 @@ pip_packages:
         assert provider.is_external is True
         # config_class is empty string in partial spec
         assert provider.config_class == ""
+
+
+class TestGetExternalProvidersFromModule:
+    """Test suite for installing external providers from module."""
+
+    def test_stackrunconfig_provider_without_module(self, mock_providers):
+        """Test that providers without module attribute are skipped."""
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        import_module_side_effect = make_import_module_side_effect()
+
+        with patch("importlib.import_module", side_effect=import_module_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="no_module",
+                            provider_type="no_module",
+                            config={},
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+            # Should not add anything to registry
+            assert len(result[Api.inference]) == 0
+
+    def test_stackrunconfig_with_version_spec(self, mock_providers):
+        """Test provider with module containing version spec (e.g., package==1.0.0)."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+        from llama_stack.providers.datatypes import ProviderSpec
+
+        fake_spec = ProviderSpec(
+            api=Api.inference,
+            provider_type="versioned_test",
+            config_class="versioned_test.config.VersionedTestConfig",
+            module="versioned_test==1.0.0",
+        )
+        fake_module = SimpleNamespace(get_provider_spec=lambda: fake_spec)
+
+        def import_side_effect(name):
+            if name == "versioned_test.provider":
+                return fake_module
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="versioned",
+                            provider_type="versioned_test",
+                            config={},
+                            module="versioned_test==1.0.0",
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+            assert "versioned_test" in result[Api.inference]
+            assert result[Api.inference]["versioned_test"].module == "versioned_test==1.0.0"
+
+    def test_buildconfig_does_not_import_module(self, mock_providers):
+        """Test that BuildConfig does not import the module (building=True)."""
+        from llama_stack.core.datatypes import BuildConfig, BuildProvider, DistributionSpec
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        build_config = BuildConfig(
+            version=2,
+            image_type="container",
+            image_name="test_image",
+            distribution_spec=DistributionSpec(
+                description="test",
+                providers={
+                    "inference": [
+                        BuildProvider(
+                            provider_type="build_test",
+                            module="build_test==1.0.0",
+                        )
+                    ]
+                },
+            ),
+        )
+
+        # Should not call import_module at all when building
+        with patch("importlib.import_module") as mock_import:
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, build_config, building=True)
+
+            # Verify module was NOT imported
+            mock_import.assert_not_called()
+
+            # Verify partial spec was created
+            assert "build_test" in result[Api.inference]
+            provider = result[Api.inference]["build_test"]
+            assert provider.module == "build_test==1.0.0"
+            assert provider.is_external is True
+            assert provider.config_class == ""
+            assert provider.api == Api.inference
+
+    def test_buildconfig_multiple_providers(self, mock_providers):
+        """Test BuildConfig with multiple providers for the same API."""
+        from llama_stack.core.datatypes import BuildConfig, BuildProvider, DistributionSpec
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        build_config = BuildConfig(
+            version=2,
+            image_type="container",
+            image_name="test_image",
+            distribution_spec=DistributionSpec(
+                description="test",
+                providers={
+                    "inference": [
+                        BuildProvider(provider_type="provider1", module="provider1"),
+                        BuildProvider(provider_type="provider2", module="provider2"),
+                    ]
+                },
+            ),
+        )
+
+        with patch("importlib.import_module") as mock_import:
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, build_config, building=True)
+
+            mock_import.assert_not_called()
+            assert "provider1" in result[Api.inference]
+            assert "provider2" in result[Api.inference]
+
+    def test_distributionspec_does_not_import_module(self, mock_providers):
+        """Test that DistributionSpec does not import the module (building=True)."""
+        from llama_stack.core.datatypes import BuildProvider, DistributionSpec
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        dist_spec = DistributionSpec(
+            description="test distribution",
+            providers={
+                "inference": [
+                    BuildProvider(
+                        provider_type="dist_test",
+                        module="dist_test==2.0.0",
+                    )
+                ]
+            },
+        )
+
+        # Should not call import_module at all when building
+        with patch("importlib.import_module") as mock_import:
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, dist_spec, building=True)
+
+            # Verify module was NOT imported
+            mock_import.assert_not_called()
+
+            # Verify partial spec was created
+            assert "dist_test" in result[Api.inference]
+            provider = result[Api.inference]["dist_test"]
+            assert provider.module == "dist_test==2.0.0"
+            assert provider.is_external is True
+            assert provider.config_class == ""
+
+    def test_list_return_from_get_provider_spec(self, mock_providers):
+        """Test when get_provider_spec returns a list of specs."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+        from llama_stack.providers.datatypes import ProviderSpec
+
+        spec1 = ProviderSpec(
+            api=Api.inference,
+            provider_type="list_test",
+            config_class="list_test.config.Config1",
+            module="list_test",
+        )
+        spec2 = ProviderSpec(
+            api=Api.inference,
+            provider_type="list_test_remote",
+            config_class="list_test.config.Config2",
+            module="list_test",
+        )
+
+        fake_module = SimpleNamespace(get_provider_spec=lambda: [spec1, spec2])
+
+        def import_side_effect(name):
+            if name == "list_test.provider":
+                return fake_module
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="list_test",
+                            provider_type="list_test",
+                            config={},
+                            module="list_test",
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+
+            # Only the matching provider_type should be added
+            assert "list_test" in result[Api.inference]
+            assert result[Api.inference]["list_test"].config_class == "list_test.config.Config1"
+
+    def test_list_return_filters_by_provider_type(self, mock_providers):
+        """Test that list return filters specs by provider_type."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+        from llama_stack.providers.datatypes import ProviderSpec
+
+        spec1 = ProviderSpec(
+            api=Api.inference,
+            provider_type="wanted",
+            config_class="test.Config1",
+            module="test",
+        )
+        spec2 = ProviderSpec(
+            api=Api.inference,
+            provider_type="unwanted",
+            config_class="test.Config2",
+            module="test",
+        )
+
+        fake_module = SimpleNamespace(get_provider_spec=lambda: [spec1, spec2])
+
+        def import_side_effect(name):
+            if name == "test.provider":
+                return fake_module
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="wanted",
+                            provider_type="wanted",
+                            config={},
+                            module="test",
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+
+            # Only the matching provider_type should be added
+            assert "wanted" in result[Api.inference]
+            assert "unwanted" not in result[Api.inference]
+
+    def test_list_return_adds_multiple_provider_types(self, mock_providers):
+        """Test that list return adds multiple different provider_types when config requests them."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+        from llama_stack.providers.datatypes import ProviderSpec
+
+        # Module returns both inline and remote variants
+        spec1 = ProviderSpec(
+            api=Api.inference,
+            provider_type="remote::ollama",
+            config_class="test.RemoteConfig",
+            module="test",
+        )
+        spec2 = ProviderSpec(
+            api=Api.inference,
+            provider_type="inline::ollama",
+            config_class="test.InlineConfig",
+            module="test",
+        )
+
+        fake_module = SimpleNamespace(get_provider_spec=lambda: [spec1, spec2])
+
+        def import_side_effect(name):
+            if name == "test.provider":
+                return fake_module
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="remote_ollama",
+                            provider_type="remote::ollama",
+                            config={},
+                            module="test",
+                        ),
+                        Provider(
+                            provider_id="inline_ollama",
+                            provider_type="inline::ollama",
+                            config={},
+                            module="test",
+                        ),
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+
+            # Both provider types should be added to registry
+            assert "remote::ollama" in result[Api.inference]
+            assert "inline::ollama" in result[Api.inference]
+            assert result[Api.inference]["remote::ollama"].config_class == "test.RemoteConfig"
+            assert result[Api.inference]["inline::ollama"].config_class == "test.InlineConfig"
+
+    def test_module_not_found_raises_value_error(self, mock_providers):
+        """Test that ModuleNotFoundError raises ValueError with helpful message."""
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        def import_side_effect(name):
+            if name == "missing_module.provider":
+                raise ModuleNotFoundError(name)
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="missing",
+                            provider_type="missing",
+                            config={},
+                            module="missing_module",
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+
+            with pytest.raises(ValueError) as exc_info:
+                get_external_providers_from_module(registry, config, building=False)
+
+            assert "get_provider_spec not found" in str(exc_info.value)
+
+    def test_generic_exception_is_raised(self, mock_providers):
+        """Test that generic exceptions are properly raised."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        def bad_spec():
+            raise RuntimeError("Something went wrong")
+
+        fake_module = SimpleNamespace(get_provider_spec=bad_spec)
+
+        def import_side_effect(name):
+            if name == "error_module.provider":
+                return fake_module
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="error",
+                            provider_type="error",
+                            config={},
+                            module="error_module",
+                        )
+                    ]
+                },
+            )
+            registry = {Api.inference: {}}
+
+            with pytest.raises(RuntimeError) as exc_info:
+                get_external_providers_from_module(registry, config, building=False)
+
+            assert "Something went wrong" in str(exc_info.value)
+
+    def test_empty_provider_list(self, mock_providers):
+        """Test with empty provider list."""
+        from llama_stack.core.datatypes import StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+
+        config = StackRunConfig(
+            image_name="test_image",
+            providers={},
+        )
+        registry = {Api.inference: {}}
+        result = get_external_providers_from_module(registry, config, building=False)
+
+        # Should return registry unchanged
+        assert result == registry
+        assert len(result[Api.inference]) == 0
+
+    def test_multiple_apis_with_providers(self, mock_providers):
+        """Test multiple APIs with providers."""
+        from types import SimpleNamespace
+
+        from llama_stack.core.datatypes import Provider, StackRunConfig
+        from llama_stack.core.distribution import get_external_providers_from_module
+        from llama_stack.providers.datatypes import ProviderSpec
+
+        inference_spec = ProviderSpec(
+            api=Api.inference,
+            provider_type="inf_test",
+            config_class="inf.Config",
+            module="inf_test",
+        )
+        safety_spec = ProviderSpec(
+            api=Api.safety,
+            provider_type="safe_test",
+            config_class="safe.Config",
+            module="safe_test",
+        )
+
+        def import_side_effect(name):
+            if name == "inf_test.provider":
+                return SimpleNamespace(get_provider_spec=lambda: inference_spec)
+            elif name == "safe_test.provider":
+                return SimpleNamespace(get_provider_spec=lambda: safety_spec)
+            raise ModuleNotFoundError(name)
+
+        with patch("importlib.import_module", side_effect=import_side_effect):
+            config = StackRunConfig(
+                image_name="test_image",
+                providers={
+                    "inference": [
+                        Provider(
+                            provider_id="inf",
+                            provider_type="inf_test",
+                            config={},
+                            module="inf_test",
+                        )
+                    ],
+                    "safety": [
+                        Provider(
+                            provider_id="safe",
+                            provider_type="safe_test",
+                            config={},
+                            module="safe_test",
+                        )
+                    ],
+                },
+            )
+            registry = {Api.inference: {}, Api.safety: {}}
+            result = get_external_providers_from_module(registry, config, building=False)
+
+            assert "inf_test" in result[Api.inference]
+            assert "safe_test" in result[Api.safety]