refactor(llm): update integration boundary for canonical tool calls

Add tool_calls_to_langchain_format() to convert canonical nested
tool calls back to LangChain flat format at the output boundary.
Update runnable_rails.py and guardrails.py to use the new types.

Author: Pouyanpi

nemoguardrails/integrations/langchain/message_utils.py

@@ -26,6 +26,8 @@
     ToolMessage,
 )
 
+from nemoguardrails.types import ChatMessage, Role
+
 
 def get_message_role(msg: BaseMessage) -> str:
     """Get the role string for a BaseMessage."""
@@ -147,36 +149,6 @@ def is_base_message(obj: Any) -> bool:
     return isinstance(obj, BaseMessage)
 
 
-def chatmessage_to_langchain_message(msg: "ChatMessage") -> BaseMessage:
-    from nemoguardrails.types import Role
-
-    content = msg.content or ""
-    if msg.role == Role.USER:
-        return HumanMessage(content=content)
-    elif msg.role == Role.SYSTEM:
-        return SystemMessage(content=content)
-    elif msg.role == Role.TOOL:
-        return ToolMessage(content=content, tool_call_id=msg.tool_call_id or "")
-    elif msg.role == Role.ASSISTANT:
-        kwargs: Dict[str, Any] = {}
-        if msg.tool_calls:
-            kwargs["tool_calls"] = [
-                {
-                    "name": tc.function.name,
-                    "args": tc.function.arguments,
-                    "id": tc.id,
-                    "type": "tool_call",
-                }
-                for tc in msg.tool_calls
-            ]
-        return AIMessage(content=content, **kwargs)
-    return HumanMessage(content=content)
-
-
-def chatmessages_to_langchain_messages(msgs: List["ChatMessage"]) -> List[BaseMessage]:
-    return [chatmessage_to_langchain_message(m) for m in msgs]
-
-
 def is_ai_message(obj: Any) -> bool:
     """Check if an object is an AIMessage."""
     return isinstance(obj, AIMessage)
@@ -308,3 +280,54 @@ def create_tool_message(
         kwargs["status"] = status
 
     return ToolMessage(content=content, **kwargs)
+
+
+_ROLE_TO_LANGCHAIN = {
+    Role.USER: HumanMessage,
+    Role.ASSISTANT: AIMessage,
+    Role.SYSTEM: SystemMessage,
+    Role.TOOL: ToolMessage,
+}
+
+
+def chatmessage_to_langchain_message(msg: ChatMessage) -> BaseMessage:
+    cls = _ROLE_TO_LANGCHAIN.get(msg.role)
+    if cls is None:
+        raise ValueError(f"Unsupported role: {msg.role}")
+
+    kwargs: Dict[str, Any] = {}
+    if msg.name is not None:
+        kwargs["name"] = msg.name
+
+    if cls is AIMessage and msg.tool_calls:
+        kwargs["tool_calls"] = [
+            {"name": tc.function.name, "args": tc.function.arguments, "id": tc.id, "type": tc.type}
+            for tc in msg.tool_calls
+        ]
+
+    if cls is ToolMessage:
+        kwargs["tool_call_id"] = msg.tool_call_id or ""
+
+    return cls(content=msg.content, **kwargs)
+
+
+def chatmessages_to_langchain_messages(msgs: List[ChatMessage]) -> List[BaseMessage]:
+    return [chatmessage_to_langchain_message(m) for m in msgs]
+
+
+def tool_calls_to_langchain_format(tool_calls: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    result = []
+    for tc in tool_calls:
+        func = tc.get("function")
+        if func:
+            result.append(
+                {
+                    "name": func.get("name", ""),
+                    "args": func.get("arguments", {}),
+                    "id": tc.get("id", ""),
+                    "type": "tool_call",
+                }
+            )
+        else:
+            result.append(tc)
+    return result

nemoguardrails/integrations/langchain/runnable_rails.py

@@ -31,6 +31,7 @@
     create_ai_message_chunk,
     is_base_message,
     message_to_dict,
+    tool_calls_to_langchain_format,
 )
 from nemoguardrails.integrations.langchain.utils import async_wrap
 from nemoguardrails.rails.llm.options import GenerationOptions
@@ -498,10 +499,12 @@ def _format_output(
         Raises:
             ValueError: If the input type cannot be handled.
         """
-        # Standardize result format if it's a list
         if isinstance(result, list) and len(result) > 0:
             result = result[0]
 
+        if tool_calls:
+            tool_calls = tool_calls_to_langchain_format(tool_calls)
+
         if self.passthrough and self.passthrough_runnable:
             return self._format_passthrough_output(result, context)
 

tests/test_tool_calling_passthrough_only.py

@@ -23,6 +23,7 @@
 from nemoguardrails import LLMRails, RailsConfig
 from nemoguardrails.actions.llm.generation import LLMGenerationActions
 from nemoguardrails.context import tool_calls_var
+from nemoguardrails.integrations.langchain.llm_adapter import LangChainLLMAdapter
 from tests.utils import get_bound_llm_magic_mock
 
 
@@ -106,20 +107,21 @@ def test_config_passthrough_false(self, config_no_passthrough):
     @pytest.mark.asyncio
     async def test_tool_calls_work_in_passthrough_mode(self, config_passthrough, mock_llm_with_tool_calls):
         """Test that tool calls create BotToolCalls events in passthrough mode."""
-        # Set up context with tool calls
         tool_calls = [
             {
                 "id": "call_123",
-                "type": "tool_call",
-                "name": "test_tool",
-                "args": {"param": "value"},
+                "type": "function",
+                "function": {
+                    "name": "test_tool",
+                    "arguments": {"param": "value"},
+                },
             }
         ]
         tool_calls_var.set(tool_calls)
 
         generation_actions = LLMGenerationActions(
             config=config_passthrough,
-            llm=mock_llm_with_tool_calls,
+            llm=LangChainLLMAdapter(mock_llm_with_tool_calls),
             llm_task_manager=MagicMock(),
             get_embedding_search_provider_instance=MagicMock(return_value=None),
         )
@@ -133,7 +135,11 @@ async def test_tool_calls_work_in_passthrough_mode(self, config_passthrough, moc
 
         assert len(result.events) == 1
         assert result.events[0]["type"] == "BotToolCalls"
-        assert result.events[0]["tool_calls"] == tool_calls
+        stored = result.events[0]["tool_calls"]
+        assert len(stored) == 1
+        assert stored[0]["function"]["name"] == "test_tool"
+        assert stored[0]["function"]["arguments"] == {"param": "value"}
+        assert stored[0]["id"] == "call_123"
 
     @pytest.mark.asyncio
     async def test_tool_calls_ignored_in_non_passthrough_mode(self, config_no_passthrough, mock_llm_with_tool_calls):
@@ -150,7 +156,7 @@ async def test_tool_calls_ignored_in_non_passthrough_mode(self, config_no_passth
 
         generation_actions = LLMGenerationActions(
             config=config_no_passthrough,
-            llm=mock_llm_with_tool_calls,
+            llm=LangChainLLMAdapter(mock_llm_with_tool_calls),
             llm_task_manager=MagicMock(),
             get_embedding_search_provider_instance=MagicMock(return_value=None),
         )
@@ -177,7 +183,7 @@ async def test_no_tool_calls_creates_bot_message_in_passthrough(self, config_pas
 
         generation_actions = LLMGenerationActions(
             config=config_passthrough,
-            llm=mock_llm_with_tool_calls,
+            llm=LangChainLLMAdapter(mock_llm_with_tool_calls),
             llm_task_manager=MagicMock(),
             get_embedding_search_provider_instance=MagicMock(return_value=None),
         )
@@ -194,12 +200,12 @@ async def test_no_tool_calls_creates_bot_message_in_passthrough(self, config_pas
 
     def test_llm_rails_integration_passthrough_mode(self, config_passthrough, mock_llm_with_tool_calls):
         """Test LLMRails with passthrough mode allows tool calls."""
-        rails = LLMRails(config=config_passthrough, llm=mock_llm_with_tool_calls)
+        rails = LLMRails(config=config_passthrough, llm=LangChainLLMAdapter(mock_llm_with_tool_calls))
 
         assert rails.config.passthrough is True
 
     def test_llm_rails_integration_non_passthrough_mode(self, config_no_passthrough, mock_llm_with_tool_calls):
         """Test LLMRails without passthrough mode."""
-        rails = LLMRails(config=config_no_passthrough, llm=mock_llm_with_tool_calls)
+        rails = LLMRails(config=config_no_passthrough, llm=LangChainLLMAdapter(mock_llm_with_tool_calls))
 
         assert rails.config.passthrough is False