refactor(llm): framework-owned provider registry (#1773)

Add register_provider/get_provider_names to LLMFramework protocol.

our public API delegates to the active framework instead of importing from LangChain internals directly. LangChainFramework implements the new methods, routing to its internal chat/llm provider registries. Backward compat aliases register_chat_provider/register_llm_provider still work.

Author: Pouyanpi

nemoguardrails/cli/providers.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 
 import logging
+import warnings
 from typing import List, Literal, Optional, Tuple, cast
 
 import typer
@@ -31,9 +32,14 @@
 
 def _list_providers() -> None:
     """List all available providers."""
-    console.print("\n[bold]Text Completion Providers:[/]")
-    for provider in sorted(get_llm_provider_names()):
-        console.print(f"  • {provider}")
+    # Suppress deprecation warning: get_llm_provider_names is deprecated for
+    # external callers but the CLI intentionally shows both categories until
+    # text completion providers are removed in 0.23.0.
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", DeprecationWarning)
+        console.print("\n[bold]Text Completion Providers:[/]")
+        for provider in sorted(get_llm_provider_names()):
+            console.print(f"  • {provider}")
 
     console.print("\n[bold]Chat Completion Providers:[/]")
     for provider in sorted(get_chat_provider_names()):
@@ -45,7 +51,10 @@ def _get_provider_completions(
 ) -> List[str]:
     """Get list of providers based on type."""
     if provider_type == "text completion":
-        return sorted(get_llm_provider_names())
+        # See comment in _list_providers for why we suppress this warning.
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            return sorted(get_llm_provider_names())
     elif provider_type == "chat completion":
         return sorted(get_chat_provider_names())
     return []

nemoguardrails/integrations/langchain/llm_adapter.py

@@ -210,6 +210,37 @@ async def stream_async(
 
 
 class LangChainFramework:
+    def register_provider(self, name: str, provider_cls: Any) -> None:
+        from nemoguardrails.integrations.langchain.providers.providers import (
+            register_chat_provider as _register_chat,
+        )
+
+        _register_chat(name, provider_cls)
+
+    def register_llm_provider(self, name: str, provider_cls: Any) -> None:
+        from nemoguardrails.integrations.langchain.providers.providers import (
+            register_llm_provider as _register_llm,
+        )
+
+        _register_llm(name, provider_cls)
+
+    def get_provider_names(self) -> List[str]:
+        return sorted(set(self.get_chat_provider_names() + self.get_llm_provider_names()))
+
+    def get_chat_provider_names(self) -> List[str]:
+        from nemoguardrails.integrations.langchain.providers.providers import (
+            get_chat_provider_names as _get_chat,
+        )
+
+        return _get_chat()
+
+    def get_llm_provider_names(self) -> List[str]:
+        from nemoguardrails.integrations.langchain.providers.providers import (
+            get_llm_provider_names as _get_llm,
+        )
+
+        return _get_llm()
+
     def create_model(
         self,
         model_name: str,

nemoguardrails/llm/providers/__init__.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2023-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,20 +13,68 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Re-export from new location for backwards compatibility.
-# Implementation moved to nemoguardrails/integrations/langchain/providers/.
-from nemoguardrails.integrations.langchain.providers import (
-    get_chat_provider_names,
-    get_community_chat_provider_names,
-    get_llm_provider_names,
-    register_chat_provider,
-    register_llm_provider,
-)
+import warnings
+from typing import Any, List
+
+from nemoguardrails.llm.frameworks import get_default_framework, get_framework
+
+
+def _active_framework():
+    return get_framework(get_default_framework())
+
+
+def register_provider(name: str, provider_cls: Any) -> None:
+    _active_framework().register_provider(name, provider_cls)
+
+
+def get_provider_names() -> List[str]:
+    return _active_framework().get_provider_names()
+
+
+def register_chat_provider(name: str, provider_cls: Any) -> None:
+    register_provider(name, provider_cls)
+
+
+def register_llm_provider(name: str, provider_cls: Any) -> None:
+    warnings.warn(
+        "register_llm_provider is deprecated and will be removed in 0.23.0. "
+        "Text completion providers are being removed. Use register_chat_provider "
+        "or register_provider instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    fw = _active_framework()
+    if hasattr(fw, "register_llm_provider"):
+        fw.register_llm_provider(name, provider_cls)  # type: ignore[attr-defined]
+    else:
+        fw.register_provider(name, provider_cls)
+
+
+def get_chat_provider_names() -> List[str]:
+    fw = _active_framework()
+    if hasattr(fw, "get_chat_provider_names"):
+        return fw.get_chat_provider_names()  # type: ignore[attr-defined]
+    return fw.get_provider_names()
+
+
+def get_llm_provider_names() -> List[str]:
+    warnings.warn(
+        "get_llm_provider_names is deprecated and will be removed in 0.23.0. "
+        "Text completion providers are being removed. Use get_provider_names instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    fw = _active_framework()
+    if hasattr(fw, "get_llm_provider_names"):
+        return fw.get_llm_provider_names()  # type: ignore[attr-defined]
+    return fw.get_provider_names()
+
 
 __all__ = [
-    "get_chat_provider_names",
-    "get_community_chat_provider_names",
-    "get_llm_provider_names",
+    "register_provider",
+    "get_provider_names",
     "register_chat_provider",
     "register_llm_provider",
+    "get_chat_provider_names",
+    "get_llm_provider_names",
 ]

nemoguardrails/types.py

@@ -261,7 +261,8 @@ class LLMFramework(Protocol):
     """Protocol for pluggable LLM framework backends.
 
     Each framework (LangChain, LiteLLM, etc.) implements this protocol to
-    provide a factory for creating ``LLMModel`` instances.
+    provide a factory for creating ``LLMModel`` instances and managing
+    its own set of providers.
 
     ``model_kwargs`` carries all provider-specific configuration. Framework
     implementations extract what they need (e.g. LangChain pops ``mode``
@@ -274,3 +275,7 @@ def create_model(
         provider_name: str,
         model_kwargs: Optional[Dict[str, Any]] = None,
     ) -> LLMModel: ...
+
+    def register_provider(self, name: str, provider_cls: Any) -> None: ...
+
+    def get_provider_names(self) -> List[str]: ...

tests/llm/test_frameworks.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import warnings
 from unittest.mock import MagicMock
 
 import pytest
@@ -24,6 +25,14 @@
     register_framework,
     set_default_framework,
 )
+from nemoguardrails.llm.providers import (
+    get_chat_provider_names,
+    get_llm_provider_names,
+    get_provider_names,
+    register_chat_provider,
+    register_llm_provider,
+    register_provider,
+)
 from nemoguardrails.types import LLMModel
 
 
@@ -82,3 +91,78 @@ def test_reset_clears_registry(self):
         _reset_frameworks()
         with pytest.raises(KeyError):
             get_framework("temp")
+
+
+class FakeChatProvider:
+    pass
+
+
+class FakeLLMProvider:
+    async def _acall(self, prompt, stop=None, **kwargs):
+        return "fake"
+
+
+@pytest.fixture(autouse=False)
+def clean_providers():
+    from nemoguardrails.integrations.langchain.providers import providers as _p
+
+    chat_backup = dict(_p._chat_providers)
+    llm_backup = dict(_p._llm_providers)
+    yield
+    _p._chat_providers.clear()
+    _p._chat_providers.update(chat_backup)
+    _p._llm_providers.clear()
+    _p._llm_providers.update(llm_backup)
+
+
+@pytest.mark.usefixtures("clean_providers")
+class TestProviderRegistration:
+    def test_register_provider_appears_in_get_provider_names(self):
+        register_provider("test_provider", FakeChatProvider)
+        assert "test_provider" in get_provider_names()
+
+    def test_register_chat_provider_appears_in_chat_names(self):
+        register_chat_provider("test_chat", FakeChatProvider)
+        assert "test_chat" in get_chat_provider_names()
+
+    def test_register_llm_provider_appears_in_llm_names(self):
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            register_llm_provider("test_llm", FakeLLMProvider)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            assert "test_llm" in get_llm_provider_names()
+
+    def test_chat_and_llm_provider_names_are_different_subsets(self):
+        register_chat_provider("only_chat_test", FakeChatProvider)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            register_llm_provider("only_llm_test", FakeLLMProvider)
+
+        chat_names = get_chat_provider_names()
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            llm_names = get_llm_provider_names()
+
+        assert "only_chat_test" in chat_names
+        assert "only_chat_test" not in llm_names
+        assert "only_llm_test" in llm_names
+        assert "only_llm_test" not in chat_names
+
+    def test_get_provider_names_returns_both(self):
+        register_chat_provider("both_chat", FakeChatProvider)
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", DeprecationWarning)
+            register_llm_provider("both_llm", FakeLLMProvider)
+
+        all_names = get_provider_names()
+        assert "both_chat" in all_names
+        assert "both_llm" in all_names
+
+    def test_register_llm_provider_emits_deprecation(self):
+        with pytest.warns(DeprecationWarning, match="removed in 0.23.0"):
+            register_llm_provider("dep_test", FakeLLMProvider)
+
+    def test_get_llm_provider_names_emits_deprecation(self):
+        with pytest.warns(DeprecationWarning, match="removed in 0.23.0"):
+            get_llm_provider_names()

tests/test_types.py

@@ -473,6 +473,12 @@ class MockFramework:
             def create_model(self, model_name, provider_name, model_kwargs=None):
                 return None
 
+            def register_provider(self, name, provider_cls):
+                pass
+
+            def get_provider_names(self):
+                return []
+
         assert isinstance(MockFramework(), LLMFramework)
 
     def test_incomplete_class_fails_protocol(self):